1
-import { describe, it, expect, afterEach, vi } from 'vitest';
1
+import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
2
+import { ComposioError as ClientComposioError } from '@composio/client';
3
import { Composio } from '../../src/composio';
4
import { MockProvider } from '../utils/mocks/provider.mock';
4
-import { ComposioNoAPIKeyError } from '../../src/errors/SDKErrors';
5
+import { ComposioError } from '../../src/errors/ComposioError';
6
+import { ComposioNoAPIKeyError, ComposioScopeConfigError } from '../../src/errors/SDKErrors';
7
8
/**
7
- * `userApiKey` / `orgApiKey` are forwarded to the API client, which selects the
8
- * credential per operation and resolves the env fallbacks itself.
9
+ * The SDK resolves its credentials (options, environment fallbacks, and a
10
+ * credential default header) and hands the API client a single `auth`, plus
11
+ * the resolved org/project scope as `scope`. Neither travels through the
12
+ * client's `defaultHeaders`, which refuses those names.
13
*/
10
-describe('Composio user and organization API keys', () => {
14
+describe('Composio credentials and scope', () => {
15
const baseConfig = {
16
apiKey: 'ak_test',
17
baseURL: 'https://api.test.com',
20
disableVersionCheck: true,
21
};
22
23
+ const captureFetch = () => {
24
+ const fetchMock = vi.fn(async () => Response.json({}));
25
+ vi.stubGlobal('fetch', fetchMock);
26
+ return fetchMock;
27
+ };
28
+
29
+ const sentHeaders = (fetchMock: ReturnType<typeof captureFetch>, callIndex = 0) => {
30
+ const call = fetchMock.mock.calls[callIndex] as unknown as [string, { headers: HeadersInit }];
31
+ return new Headers(call[1].headers);
32
+ };
33
+
34
+ const credentialHeaders = (headers: Headers) => ({
35
+ 'x-api-key': headers.get('x-api-key'),
36
+ 'x-user-api-key': headers.get('x-user-api-key'),
37
+ 'x-org-api-key': headers.get('x-org-api-key'),
38
+ });
39
+
40
+ beforeEach(() => {
41
+ vi.stubEnv('COMPOSIO_API_KEY', undefined);
42
+ vi.stubEnv('COMPOSIO_USER_API_KEY', undefined);
43
+ vi.stubEnv('COMPOSIO_ORG_API_KEY', undefined);
44
+ });
45
+
46
afterEach(() => {
47
vi.unstubAllEnvs();
48
+ vi.unstubAllGlobals();
49
});
50
23
- it('forwards both keys to the API client', () => {
24
- const composio = new Composio({
25
- ...baseConfig,
26
- userApiKey: 'uak_test',
27
- orgApiKey: 'oak_test',
51
+ describe('auth mapping', () => {
52
+ it('authenticates every request with the project key when it is the only key', async () => {
53
+ const fetchMock = captureFetch();
54
+ const composio = new Composio(baseConfig);
55
+
56
+ expect(composio.getClient().authMode).toBe('project');
57
+ await composio.getClient().toolRouter.session.retrieve('trs_1');
58
+ await composio.getClient().org.list();
59
+
60
+ expect(credentialHeaders(sentHeaders(fetchMock, 0))).toEqual({
61
+ 'x-api-key': 'ak_test',
62
+ 'x-user-api-key': null,
63
+ 'x-org-api-key': null,
64
+ });
65
+ expect(credentialHeaders(sentHeaders(fetchMock, 1))).toEqual({
66
+ 'x-api-key': 'ak_test',
67
+ 'x-user-api-key': null,
68
+ 'x-org-api-key': null,
69
+ });
70
});
29
- const client = composio.getClient();
30
- expect(client.apiKey).toBe('ak_test');
31
- expect(client.userApiKey).toBe('uak_test');
32
- expect(client.orgApiKey).toBe('oak_test');
33
- });
71
35
- it('leaves both keys unset on the client when not configured', () => {
36
- vi.stubEnv('COMPOSIO_USER_API_KEY', '');
37
- vi.stubEnv('COMPOSIO_ORG_API_KEY', '');
38
- const client = new Composio(baseConfig).getClient();
39
- expect(client.userApiKey).toBeNull();
40
- expect(client.orgApiKey).toBeNull();
41
- });
72
+ it('selects per operation when the project key comes with a user key', async () => {
73
+ const fetchMock = captureFetch();
74
+ const composio = new Composio({ ...baseConfig, userApiKey: 'uak_test' });
75
43
- it('lets the client resolve the env fallbacks', () => {
44
- vi.stubEnv('COMPOSIO_USER_API_KEY', 'uak_env');
45
- vi.stubEnv('COMPOSIO_ORG_API_KEY', 'oak_env');
46
- const client = new Composio(baseConfig).getClient();
47
- expect(client.userApiKey).toBe('uak_env');
48
- expect(client.orgApiKey).toBe('oak_env');
49
- });
76
+ expect(composio.getClient().authMode).toBe('auto');
77
+ await composio.getClient().toolRouter.session.retrieve('trs_1');
78
+ await composio.getClient().org.list();
79
51
- it('exposes both keys on getConfig() and carries them into createSession()', () => {
52
- const composio = new Composio({
53
- ...baseConfig,
54
- userApiKey: 'uak_test',
55
- orgApiKey: 'oak_test',
56
- });
57
- expect(composio.getConfig()).toMatchObject({ userApiKey: 'uak_test', orgApiKey: 'oak_test' });
58
- const session = composio.createSession({ headers: { 'x-request-id': '1' } });
59
- expect(session.getConfig()).toMatchObject({ userApiKey: 'uak_test', orgApiKey: 'oak_test' });
60
- expect(session.getClient().userApiKey).toBe('uak_test');
61
- expect(session.getClient().orgApiKey).toBe('oak_test');
62
- });
80
+ expect(credentialHeaders(sentHeaders(fetchMock, 0))).toEqual({
81
+ 'x-api-key': 'ak_test',
82
+ 'x-user-api-key': null,
83
+ 'x-org-api-key': null,
84
+ });
85
+ expect(credentialHeaders(sentHeaders(fetchMock, 1))).toEqual({
86
+ 'x-api-key': null,
87
+ 'x-user-api-key': 'uak_test',
88
+ 'x-org-api-key': null,
89
+ });
90
+ });
91
64
- it('stores env-resolved keys on the config so createSession() keeps them after env changes', () => {
65
- vi.stubEnv('COMPOSIO_USER_API_KEY', 'uak_env');
66
- vi.stubEnv('COMPOSIO_ORG_API_KEY', 'oak_env');
67
- const composio = new Composio(baseConfig);
68
- expect(composio.getConfig()).toMatchObject({ userApiKey: 'uak_env', orgApiKey: 'oak_env' });
69
-
70
- vi.stubEnv('COMPOSIO_USER_API_KEY', '');
71
- vi.stubEnv('COMPOSIO_ORG_API_KEY', 'oak_other');
72
- const session = composio.createSession({ headers: { 'x-request-id': '1' } });
73
- expect(session.getClient().userApiKey).toBe('uak_env');
74
- expect(session.getClient().orgApiKey).toBe('oak_env');
75
- });
92
+ it('selects per operation when the project key comes with an organization key', async () => {
93
+ const fetchMock = captureFetch();
94
+ const composio = new Composio({ ...baseConfig, orgApiKey: 'oak_test' });
95
+
96
+ expect(composio.getClient().authMode).toBe('auto');
97
+ await composio.getClient().toolkits.retrieve('github');
98
+ await composio.getClient().org.owner.project.list();
99
77
- it('accepts a disabled project key when a user API key is configured', () => {
78
- vi.stubEnv('COMPOSIO_API_KEY', 'ak_env');
79
- const composio = new Composio({ ...baseConfig, apiKey: null, userApiKey: 'uak_test' });
80
- const client = composio.getClient();
81
- expect(client.apiKey).toBeNull();
82
- expect(client.userApiKey).toBe('uak_test');
83
- expect(composio.getConfig().apiKey).toBeNull();
100
+ expect(sentHeaders(fetchMock, 0).get('x-api-key')).toBe('ak_test');
101
+ expect(credentialHeaders(sentHeaders(fetchMock, 1))).toEqual({
102
+ 'x-api-key': null,
103
+ 'x-user-api-key': null,
104
+ 'x-org-api-key': 'oak_test',
105
+ });
106
+ });
107
+
108
+ it('selects per operation with all three keys, resolving the alternates from the environment', async () => {
109
+ vi.stubEnv('COMPOSIO_USER_API_KEY', 'uak_env');
110
+ vi.stubEnv('COMPOSIO_ORG_API_KEY', 'oak_env');
111
+ const fetchMock = captureFetch();
112
+ const composio = new Composio(baseConfig);
113
+
114
+ expect(composio.getClient().authMode).toBe('auto');
115
+ await composio.getClient().org.list();
116
+ await composio.getClient().org.owner.project.list();
117
+
118
+ expect(sentHeaders(fetchMock, 0).get('x-user-api-key')).toBe('uak_env');
119
+ expect(sentHeaders(fetchMock, 1).get('x-org-api-key')).toBe('oak_env');
120
+ });
121
+
122
+ it('authenticates every request, sessions included, with the user key when the project key is disabled', async () => {
123
+ const fetchMock = captureFetch();
124
+ const composio = new Composio({ ...baseConfig, apiKey: null, userApiKey: 'uak_test' });
125
+
126
+ expect(composio.getClient().authMode).toBe('user');
127
+ await composio.getClient().toolRouter.session.retrieve('trs_1');
128
+
129
+ expect(credentialHeaders(sentHeaders(fetchMock))).toEqual({
130
+ 'x-api-key': null,
131
+ 'x-user-api-key': 'uak_test',
132
+ 'x-org-api-key': null,
133
+ });
134
+ });
135
+
136
+ it('reads COMPOSIO_USER_API_KEY when the project key is disabled and the option is omitted', () => {
137
+ vi.stubEnv('COMPOSIO_USER_API_KEY', 'uak_env');
138
+
139
+ const composio = new Composio({ ...baseConfig, apiKey: null });
140
+
141
+ expect(composio.getClient().authMode).toBe('user');
142
+ expect(composio.getConfig()).toMatchObject({ apiKey: null, userApiKey: 'uak_env' });
143
+ });
144
+
145
+ it('keeps the user key on every request when an organization key is also configured', async () => {
146
+ const fetchMock = captureFetch();
147
+ const composio = new Composio({
148
+ ...baseConfig,
149
+ apiKey: null,
150
+ userApiKey: 'uak_test',
151
+ orgApiKey: 'oak_test',
152
+ });
153
+
154
+ expect(composio.getClient().authMode).toBe('user');
155
+ await composio.getClient().toolRouter.session.retrieve('trs_1');
156
+ await composio.getClient().org.owner.project.list();
157
+
158
+ expect(credentialHeaders(sentHeaders(fetchMock, 0))).toEqual({
159
+ 'x-api-key': null,
160
+ 'x-user-api-key': 'uak_test',
161
+ 'x-org-api-key': null,
162
+ });
163
+ expect(credentialHeaders(sentHeaders(fetchMock, 1))).toEqual({
164
+ 'x-api-key': null,
165
+ 'x-user-api-key': 'uak_test',
166
+ 'x-org-api-key': null,
167
+ });
168
+ });
169
+
170
+ it('authenticates every request with the organization key when it is the only key', async () => {
171
+ const fetchMock = captureFetch();
172
+ const composio = new Composio({ ...baseConfig, apiKey: null, orgApiKey: 'oak_test' });
173
+
174
+ expect(composio.getClient().authMode).toBe('organization');
175
+ await composio.getClient().org.owner.project.list();
176
+
177
+ expect(credentialHeaders(sentHeaders(fetchMock))).toEqual({
178
+ 'x-api-key': null,
179
+ 'x-user-api-key': null,
180
+ 'x-org-api-key': 'oak_test',
181
+ });
182
+ });
183
+
184
+ it('rejects a disabled project key when neither alternate key is configured', () => {
185
+ vi.stubEnv('COMPOSIO_API_KEY', 'ak_env');
186
+ expect(() => new Composio({ ...baseConfig, apiKey: null })).toThrow(ComposioNoAPIKeyError);
187
+ });
188
});
189
86
- it('accepts a disabled project key when an organization API key is configured', () => {
87
- const client = new Composio({ ...baseConfig, apiKey: null, orgApiKey: 'oak_test' }).getClient();
88
- expect(client.apiKey).toBeNull();
89
- expect(client.orgApiKey).toBe('oak_test');
190
+ describe('credential default headers', () => {
191
+ it('authenticates with an x-user-api-key header alone and does not forward it as a header', async () => {
192
+ const fetchMock = captureFetch();
193
+ const composio = new Composio({
194
+ ...baseConfig,
195
+ apiKey: null,
196
+ defaultHeaders: { 'X-User-Api-Key': 'uak_header', 'x-request-id': 'req-1' },
197
+ });
198
+
199
+ expect(composio.getClient().authMode).toBe('user');
200
+ expect(composio.getConfig()).toMatchObject({
201
+ apiKey: null,
202
+ userApiKey: 'uak_header',
203
+ defaultHeaders: { 'x-request-id': 'req-1' },
204
+ });
205
+ await composio.getClient().toolRouter.session.retrieve('trs_1');
206
+
207
+ const headers = sentHeaders(fetchMock);
208
+ expect(credentialHeaders(headers)).toEqual({
209
+ 'x-api-key': null,
210
+ 'x-user-api-key': 'uak_header',
211
+ 'x-org-api-key': null,
212
+ });
213
+ expect(headers.get('x-request-id')).toBe('req-1');
214
+ });
215
+
216
+ it('lets an x-user-api-key header replace a configured project key', async () => {
217
+ const fetchMock = captureFetch();
218
+ const composio = new Composio({
219
+ ...baseConfig,
220
+ defaultHeaders: { 'x-user-api-key': 'uak_header' },
221
+ });
222
+
223
+ expect(composio.getClient().authMode).toBe('user');
224
+ await composio.getClient().toolkits.retrieve('github');
225
+
226
+ expect(credentialHeaders(sentHeaders(fetchMock))).toEqual({
227
+ 'x-api-key': null,
228
+ 'x-user-api-key': 'uak_header',
229
+ 'x-org-api-key': null,
230
+ });
231
+ });
232
+
233
+ it('lets an x-org-api-key header replace the configured keys', () => {
234
+ const composio = new Composio({
235
+ ...baseConfig,
236
+ userApiKey: 'uak_test',
237
+ defaultHeaders: { 'x-org-api-key': 'oak_header' },
238
+ });
239
+
240
+ expect(composio.getClient().authMode).toBe('organization');
241
+ expect(composio.getConfig()).toMatchObject({
242
+ apiKey: null,
243
+ userApiKey: null,
244
+ orgApiKey: 'oak_header',
245
+ });
246
+ });
247
+
248
+ it('takes the project key from an x-api-key header', async () => {
249
+ const fetchMock = captureFetch();
250
+ const composio = new Composio({
251
+ ...baseConfig,
252
+ defaultHeaders: { 'x-api-key': 'ak_header' },
253
+ });
254
+
255
+ expect(composio.getClient().authMode).toBe('project');
256
+ await composio.getClient().toolkits.retrieve('github');
257
+
258
+ expect(sentHeaders(fetchMock).get('x-api-key')).toBe('ak_header');
259
+ });
260
+
261
+ it('rejects more than one credential header', () => {
262
+ expect(
263
+ () =>
264
+ new Composio({
265
+ ...baseConfig,
266
+ defaultHeaders: { 'x-api-key': 'ak_header', 'x-user-api-key': 'uak_header' },
267
+ })
268
+ ).toThrow(ComposioError);
269
+ });
270
+
271
+ it('rejects a raw x-api-key default header when the project key is disabled', () => {
272
+ expect(
273
+ () =>
274
+ new Composio({
275
+ ...baseConfig,
276
+ apiKey: null,
277
+ userApiKey: 'uak_test',
278
+ defaultHeaders: { 'x-api-key': 'ak_raw' },
279
+ })
280
+ ).toThrow(ComposioNoAPIKeyError);
281
+ });
282
+
283
+ it('still lets the API client reject identity headers', () => {
284
+ expect(
285
+ () => new Composio({ ...baseConfig, defaultHeaders: { 'x-source': 'custom' } })
286
+ ).toThrow(ClientComposioError);
287
+ });
288
});
289
92
- it('rejects a raw x-api-key default header when the project key is disabled', () => {
93
- expect(
94
- () =>
95
- new Composio({
96
- ...baseConfig,
97
- apiKey: null,
98
- userApiKey: 'uak_test',
99
- defaultHeaders: { 'x-api-key': 'ak_raw' },
100
- })
101
- ).toThrow(ComposioNoAPIKeyError);
290
+ describe('createSession()', () => {
291
+ it('carries the resolved keys on the config, not the API client, into clones', () => {
292
+ vi.stubEnv('COMPOSIO_USER_API_KEY', 'uak_env');
293
+ vi.stubEnv('COMPOSIO_ORG_API_KEY', 'oak_env');
294
+ const composio = new Composio(baseConfig);
295
+ expect(composio.getConfig()).toMatchObject({ userApiKey: 'uak_env', orgApiKey: 'oak_env' });
296
+
297
+ vi.stubEnv('COMPOSIO_USER_API_KEY', '');
298
+ vi.stubEnv('COMPOSIO_ORG_API_KEY', 'oak_other');
299
+ const session = composio.createSession({ headers: { 'x-request-id': '1' } });
300
+
301
+ expect(session.getConfig()).toMatchObject({
302
+ apiKey: 'ak_test',
303
+ userApiKey: 'uak_env',
304
+ orgApiKey: 'oak_env',
305
+ });
306
+ expect(session.getClient().authMode).toBe('auto');
307
+ });
308
+
309
+ it('routes a user key from the parent default headers through auth', async () => {
310
+ const fetchMock = captureFetch();
311
+ const composio = new Composio({
312
+ ...baseConfig,
313
+ defaultHeaders: { 'x-user-api-key': 'uak_header' },
314
+ });
315
+
316
+ const session = composio.createSession({ headers: { 'x-request-id': 'req-2' } });
317
+ await session.getClient().toolRouter.session.retrieve('trs_1');
318
+
319
+ expect(session.getConfig().defaultHeaders).toEqual({ 'x-request-id': 'req-2' });
320
+ expect(session.getClient().authMode).toBe('user');
321
+ expect(credentialHeaders(sentHeaders(fetchMock))).toEqual({
322
+ 'x-api-key': null,
323
+ 'x-user-api-key': 'uak_header',
324
+ 'x-org-api-key': null,
325
+ });
326
+ });
327
+
328
+ it('lets a clone header replace the parent user key', () => {
329
+ const composio = new Composio({ ...baseConfig, apiKey: null, userApiKey: 'uak_parent' });
330
+
331
+ const session = composio.createSession({ headers: { 'x-user-api-key': 'uak_clone' } });
332
+
333
+ expect(session.getConfig()).toMatchObject({ apiKey: null, userApiKey: 'uak_clone' });
334
+ expect(session.getClient().authMode).toBe('user');
335
+ });
336
});
337
104
- it('rejects a disabled project key when neither alternate key is configured', () => {
105
- vi.stubEnv('COMPOSIO_API_KEY', 'ak_env');
106
- vi.stubEnv('COMPOSIO_USER_API_KEY', '');
107
- vi.stubEnv('COMPOSIO_ORG_API_KEY', '');
108
- expect(() => new Composio({ ...baseConfig, apiKey: null })).toThrow(ComposioNoAPIKeyError);
338
+ describe('scope', () => {
339
+ const orgId = 'org_nano_abc';
340
+ const projectId = 'proj_nano_xyz';
341
+
342
+ it('passes orgId and projectId to the API client as its scope', async () => {
343
+ const fetchMock = captureFetch();
344
+ const composio = new Composio({ ...baseConfig, orgId, projectId });
345
+
346
+ expect(composio.getClient().scope).toEqual({ organizationId: orgId, projectId });
347
+ await composio.getClient().toolkits.retrieve('github');
348
+
349
+ const headers = sentHeaders(fetchMock);
350
+ expect(headers.get('x-org-id')).toBe(orgId);
351
+ expect(headers.get('x-project-id')).toBe(projectId);
352
+ });
353
+
354
+ it('moves a scope supplied through default headers into the client scope', () => {
355
+ const composio = new Composio({
356
+ ...baseConfig,
357
+ defaultHeaders: { 'X-Org-Id': orgId, 'x-project-id': projectId, 'x-request-id': 'r' },
358
+ });
359
+
360
+ expect(composio.getClient().scope).toEqual({ organizationId: orgId, projectId });
361
+ expect(composio.getConfig()).toMatchObject({
362
+ orgId,
363
+ projectId,
364
+ defaultHeaders: { 'x-request-id': 'r' },
365
+ });
366
+ });
367
+
368
+ it('leaves the client unscoped without a scope', () => {
369
+ expect(new Composio(baseConfig).getClient().scope).toBeUndefined();
370
+ });
371
+
372
+ it('keeps the scope on clones', () => {
373
+ const session = new Composio({ ...baseConfig, orgId, projectId }).createSession();
374
+
375
+ expect(session.getClient().scope).toEqual({ organizationId: orgId, projectId });
376
+ });
377
+
378
+ it('rejects a scope option that disagrees with its default header', () => {
379
+ expect(
380
+ () =>
381
+ new Composio({
382
+ ...baseConfig,
383
+ orgId,
384
+ projectId,
385
+ defaultHeaders: { 'x-org-id': 'org_other' },
386
+ })
387
+ ).toThrow(ComposioScopeConfigError);
388
+ });
389
});
390
});