@devries-cameron20 / composio-1 / commits / e9fcbe3d8
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(core): stop dropping auth field metadata from toolkit auth details

`transformToolkitRetrieveResponse` handed the two auth field groups straight through from the raw client response. Every other key on those fields already happens to be camelCase on the wire, but `is_secret` and `legacy_template_name` do not, so they never matched `ToolkitAuthFieldSchema` and zod dropped them while validating the transformed object. `auth_hint_url` was never mapped at all. `is_secret` is the one signal a client has for deciding whether to mask an input when it renders its own credential form, which is what `toolkits.getConnectedAccountInitiationFields()` exists to drive. Losing it means the caller cannot tell an API key apart from a shop subdomain. The Python helpers return the generated client models untouched, so they never lost these keys. Map the auth fields explicitly instead of passing them through, and add `isSecret`, `legacyTemplateName` and `authHintUrl` to the schemas. Optional keys are spread conditionally so that an absent key stays absent: assigning it unconditionally would create an own property holding `undefined` and silently beat a caller's fallback in `{ default: 'fallback', ...field }`. A type-level test fails the build when the generated client grows a key in any of the four field groups that the mapping does not list. The client declares each group as its own interface, so both the raw field type and the test distribute over all four; deriving from one interface alone would miss a key added to any of the other three. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Moritz Diesing committed Sep 9, 2026 at 21:16 UTC e9fcbe3d898118c385bd2d8c3986e436dd1d861d
5 files changed +362 -2
.changeset/toolkit-auth-field-is-secret.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/core': patch
3 +---
4 +
5 +Stop dropping `is_secret`, `legacy_template_name` and `auth_hint_url` from toolkit auth config details. `transformToolkitRetrieveResponse` passed the auth field groups through unchanged, so the snake_case keys never matched `ToolkitAuthFieldSchema` and zod stripped them during validation; `auth_hint_url` was never mapped at all. Fields returned by `toolkits.getConnectedAccountInitiationFields()` and `toolkits.getAuthConfigCreationFields()` now carry `isSecret`, which the API documents as the signal for whether a client should mask the input, plus `legacyTemplateName`; auth config details returned by `toolkits.get()` now carry `authHintUrl`. Each of these keys is present only when the API sends it, so spreading a field no longer overwrites a caller's own fallback with `undefined`.
ts/packages/core/src/types/toolkit.types.ts
+17
@@ -66,10 +66,27 @@ export const ToolkitAuthFieldSchema = z.object({
66 name: z.string(),
67 type: z.string(),
68 default: z.string().nullable().optional(),
69 + /**
70 + * Whether this field holds a secret/credential value. Clients use it to
71 + * decide whether to mask the input when collecting the value in their own
72 + * UI. The property is absent when the API omits the flag for the field.
73 + */
74 + isSecret: z.boolean().optional(),
75 + /**
76 + * The legacy template name the API reports for this field, mapped from
77 + * `legacy_template_name`. The API declares it as an optional string without
78 + * further documenting its semantics.
79 + */
80 + legacyTemplateName: z.string().optional(),
81 });
82 export const ToolkitAuthConfigDetailsSchema = z.object({
83 name: z.string(),
84 mode: z.string(),
85 + /**
86 + * URL to a page where users can obtain or configure credentials for this
87 + * authentication method, e.g. `https://github.com/settings/tokens`.
88 + */
89 + authHintUrl: z.string().nullable().optional(),
90 fields: z.object({
91 authConfigCreation: z.object({
92 optional: z.array(ToolkitAuthFieldSchema),
ts/packages/core/src/utils/transformers/toolkits.ts
+62 -2
@@ -6,6 +6,7 @@ import {
6 import {
7 ToolKitListResponse,
8 ToolKitListResponseSchema,
9 + ToolkitAuthField,
10 ToolkitRetrieveResponse,
11 ToolkitRetrieveResponseSchema,
12 ToolkitRetrieveCategoriesResponse,
@@ -13,6 +14,58 @@ import {
14 } from '../../types/toolkit.types';
15 import { transform } from '../transform';
16
17 +type RawToolkitAuthConfigDetailFields = NonNullable<
18 + RawToolkitRetrieveResponse['auth_config_details']
19 +>[number]['fields'];
20 +
21 +/**
22 + * A single auth form field as the API ships it, across all four groups. The
23 + * generated client declares each group as its own interface; they are identical
24 + * today, so the union costs nothing and keeps the mapping honest if they ever
25 + * drift apart.
26 + *
27 + * Most keys are already camelCase on the wire (`displayName`), but `is_secret`
28 + * and `legacy_template_name` are not, so the field needs an explicit mapping
29 + * instead of a pass-through: a pass-through leaves them under keys the schema
30 + * does not know and zod strips them while validating.
31 + *
32 + * `type-tests/toolkit-auth-field-mapping.test-d.ts` fails the build when the
33 + * generated client grows a key in any of the four groups that is not listed
34 + * there.
35 + */
36 +type RawToolkitAuthField =
37 + | RawToolkitAuthConfigDetailFields['auth_config_creation']['required'][number]
38 + | RawToolkitAuthConfigDetailFields['auth_config_creation']['optional'][number]
39 + | RawToolkitAuthConfigDetailFields['connected_account_initiation']['required'][number]
40 + | RawToolkitAuthConfigDetailFields['connected_account_initiation']['optional'][number];
41 +
42 +const transformToolkitAuthField = (field: RawToolkitAuthField): ToolkitAuthField => ({
43 + name: field.name,
44 + displayName: field.displayName,
45 + description: field.description,
46 + type: field.type,
47 + required: field.required,
48 + // Optional keys are spread conditionally rather than assigned. Assigning an
49 + // absent wire key creates an own property holding `undefined`, which silently
50 + // beats a caller's fallback in `{ default: 'fallback', ...field }`. JSON never
51 + // carries an explicit `undefined`, so checking for it is the same test as
52 + // asking whether the server sent the key at all — and `null` and `false`
53 + // survive.
54 + ...(field.default !== undefined && { default: field.default }),
55 + ...(field.is_secret !== undefined && { isSecret: field.is_secret }),
56 + ...(field.legacy_template_name !== undefined && {
57 + legacyTemplateName: field.legacy_template_name,
58 + }),
59 +});
60 +
61 +const transformToolkitAuthFieldGroup = (group: {
62 + required: Array<RawToolkitAuthField>;
63 + optional: Array<RawToolkitAuthField>;
64 +}) => ({
65 + required: group.required.map(transformToolkitAuthField),
66 + optional: group.optional.map(transformToolkitAuthField),
67 +});
68 +
69 export const transformToolkitListResponse = (
70 response: RawToolkitListResponse
71 ): ToolKitListResponse => {
@@ -70,9 +123,16 @@ export const transformToolkitRetrieveResponse = (
123 authConfigDetails: response.auth_config_details?.map(authConfig => ({
124 name: authConfig.name,
125 mode: authConfig.mode,
126 + ...(authConfig.auth_hint_url !== undefined && {
127 + authHintUrl: authConfig.auth_hint_url,
128 + }),
129 fields: {
74 - authConfigCreation: authConfig.fields.auth_config_creation,
75 - connectedAccountInitiation: authConfig.fields.connected_account_initiation,
130 + authConfigCreation: transformToolkitAuthFieldGroup(
131 + authConfig.fields.auth_config_creation
132 + ),
133 + connectedAccountInitiation: transformToolkitAuthFieldGroup(
134 + authConfig.fields.connected_account_initiation
135 + ),
136 },
137 proxy: {
138 baseUrl: authConfig.proxy?.base_url,
ts/packages/core/test/utils/transformers/toolkits.test.ts new
+183
@@ -0,0 +1,183 @@
1 +import { describe, it, expect } from 'vitest';
2 +import { transformToolkitRetrieveResponse } from '../../../src/utils/transformers/toolkits';
3 +
4 +type RawRetrieveResponse = Parameters<typeof transformToolkitRetrieveResponse>[0];
5 +
6 +/**
7 + * The API describes every auth form field with an `is_secret` flag ("Clients use
8 + * it to decide whether to mask the input"), a `legacy_template_name`, and every
9 + * auth method with an `auth_hint_url`. All three are snake_case on the wire, so a
10 + * pass-through leaves them under keys the zod schema does not know and validation
11 + * strips them.
12 + *
13 + * Every one of the four field groups is populated here, because the transformer
14 + * maps each of them separately.
15 + */
16 +const rawToolkit = {
17 + name: 'Shopify',
18 + slug: 'shopify',
19 + meta: {
20 + created_at: '2024-01-01T00:00:00Z',
21 + updated_at: '2024-01-02T00:00:00Z',
22 + tools_count: 12,
23 + triggers_count: 3,
24 + },
25 + is_local_toolkit: false,
26 + composio_managed_auth_schemes: ['OAUTH2'],
27 + auth_config_details: [
28 + {
29 + name: 'API Key',
30 + mode: 'API_KEY',
31 + auth_hint_url: 'https://shopify.dev/api-keys',
32 + fields: {
33 + auth_config_creation: {
34 + required: [
35 + {
36 + name: 'client_secret',
37 + displayName: 'Client Secret',
38 + description: 'The app client secret',
39 + type: 'string',
40 + required: true,
41 + is_secret: true,
42 + legacy_template_name: 'clientSecret',
43 + },
44 + ],
45 + optional: [
46 + {
47 + name: 'scopes',
48 + displayName: 'Scopes',
49 + description: 'Comma separated scopes',
50 + type: 'string',
51 + required: false,
52 + is_secret: false,
53 + default: null,
54 + legacy_template_name: 'oauthScopes',
55 + },
56 + ],
57 + },
58 + connected_account_initiation: {
59 + required: [
60 + {
61 + name: 'api_key',
62 + displayName: 'API Key',
63 + description: 'Your Shopify API key',
64 + type: 'string',
65 + required: true,
66 + is_secret: true,
67 + legacy_template_name: 'apiKey',
68 + },
69 + ],
70 + optional: [
71 + {
72 + name: 'shop_domain',
73 + displayName: 'Shop Domain',
74 + description: 'your-store.myshopify.com',
75 + type: 'string',
76 + required: false,
77 + is_secret: false,
78 + default: 'example.myshopify.com',
79 + },
80 + ],
81 + },
82 + },
83 + },
84 + ],
85 +} as unknown as RawRetrieveResponse;
86 +
87 +/** Same shape, but the API omits every optional key. */
88 +const rawToolkitWithoutOptionalKeys = {
89 + ...rawToolkit,
90 + auth_config_details: [
91 + {
92 + name: 'Bearer',
93 + mode: 'BEARER_TOKEN',
94 + fields: {
95 + auth_config_creation: { required: [], optional: [] },
96 + connected_account_initiation: {
97 + required: [
98 + {
99 + name: 'token',
100 + displayName: 'Token',
101 + description: 'A bearer token',
102 + type: 'string',
103 + required: true,
104 + },
105 + ],
106 + optional: [],
107 + },
108 + },
109 + },
110 + ],
111 +} as unknown as RawRetrieveResponse;
112 +
113 +const initiationRequired = (raw: RawRetrieveResponse) =>
114 + transformToolkitRetrieveResponse(raw).authConfigDetails?.[0].fields.connectedAccountInitiation
115 + .required[0];
116 +
117 +describe('transformToolkitRetrieveResponse', () => {
118 + it('preserves is_secret as isSecret in all four auth field groups', () => {
119 + const fields = transformToolkitRetrieveResponse(rawToolkit).authConfigDetails?.[0].fields;
120 +
121 + expect(fields?.authConfigCreation.required[0].isSecret).toBe(true);
122 + expect(fields?.authConfigCreation.optional[0].isSecret).toBe(false);
123 + expect(fields?.connectedAccountInitiation.required[0].isSecret).toBe(true);
124 + expect(fields?.connectedAccountInitiation.optional[0].isSecret).toBe(false);
125 + });
126 +
127 + it('preserves legacy_template_name as legacyTemplateName', () => {
128 + const fields = transformToolkitRetrieveResponse(rawToolkit).authConfigDetails?.[0].fields;
129 +
130 + expect(fields?.authConfigCreation.required[0].legacyTemplateName).toBe('clientSecret');
131 + expect(fields?.authConfigCreation.optional[0].legacyTemplateName).toBe('oauthScopes');
132 + expect(fields?.connectedAccountInitiation.required[0].legacyTemplateName).toBe('apiKey');
133 + });
134 +
135 + it('maps a whole field without losing or inventing keys', () => {
136 + expect(initiationRequired(rawToolkit)).toEqual({
137 + name: 'api_key',
138 + displayName: 'API Key',
139 + description: 'Your Shopify API key',
140 + type: 'string',
141 + required: true,
142 + isSecret: true,
143 + legacyTemplateName: 'apiKey',
144 + });
145 + });
146 +
147 + it('keeps a null default and a false flag rather than dropping them', () => {
148 + const field =
149 + transformToolkitRetrieveResponse(rawToolkit).authConfigDetails?.[0].fields.authConfigCreation
150 + .optional[0];
151 +
152 + expect(field?.default).toBeNull();
153 + expect(field?.isSecret).toBe(false);
154 + });
155 +
156 + it('maps auth_hint_url to authHintUrl', () => {
157 + const details = transformToolkitRetrieveResponse(rawToolkit).authConfigDetails?.[0];
158 +
159 + expect(details?.authHintUrl).toBe('https://shopify.dev/api-keys');
160 + });
161 +
162 + /**
163 + * `toEqual` treats a missing property and one holding `undefined` as equal, so
164 + * these assertions use `toHaveProperty`. Creating the key unconditionally would
165 + * override a caller's fallback in `{ default: 'fallback', ...field }`.
166 + */
167 + it('omits optional keys entirely when the API does not send them', () => {
168 + const field = initiationRequired(rawToolkitWithoutOptionalKeys);
169 +
170 + expect(field).not.toHaveProperty('default');
171 + expect(field).not.toHaveProperty('isSecret');
172 + expect(field).not.toHaveProperty('legacyTemplateName');
173 + expect(
174 + transformToolkitRetrieveResponse(rawToolkitWithoutOptionalKeys).authConfigDetails?.[0]
175 + ).not.toHaveProperty('authHintUrl');
176 + });
177 +
178 + it('lets a caller fallback survive spreading a field with no default', () => {
179 + const field = initiationRequired(rawToolkitWithoutOptionalKeys);
180 +
181 + expect({ default: 'caller fallback', ...field }.default).toBe('caller fallback');
182 + });
183 +});
ts/packages/core/type-tests/toolkit-auth-field-mapping.test-d.ts new
+95
@@ -0,0 +1,95 @@
1 +/**
2 + * Type-level guard for the toolkit auth field mapping.
3 + *
4 + * `transformToolkitRetrieveResponse` projects each auth form field key by key.
5 + * A key the generated client declares but the projection forgets is dropped
6 + * silently: zod removes it while validating, and no runtime test notices unless
7 + * someone thought to assert that exact key. That is how `is_secret`,
8 + * `legacy_template_name` and `auth_hint_url` were lost.
9 + *
10 + * What this file does: it fails the build (tsconfig.type-tests.json) when
11 + * `@composio/client` declares a key in any of the four field groups, or on the
12 + * auth config detail, that is not listed below.
13 + *
14 + * What it does NOT do: it does not verify that the transformer still assigns
15 + * those keys. The lists here are hand-written, so removing an assignment from
16 + * the mapper while leaving its key listed stays green at compile time. The
17 + * runtime test pins the projection for the keys known today
18 + * (`test/utils/transformers/toolkits.test.ts`, "maps a whole field without
19 + * losing or inventing keys"); this file covers the keys nobody has seen yet.
20 + */
21 +import type { ToolkitRetrieveResponse as RawToolkitRetrieveResponse } from '@composio/client/resources/toolkits';
22 +import type { ToolkitAuthField, ToolkitAuthConfigDetails } from '../src';
23 +
24 +type RawAuthConfigDetail = NonNullable<RawToolkitRetrieveResponse['auth_config_details']>[number];
25 +type RawFields = RawAuthConfigDetail['fields'];
26 +
27 +/**
28 + * The generated client declares each of the four field groups as its own
29 + * interface. They are identical today, but a plain `keyof` over their union
30 + * would yield only the keys they share, so a key added to one group alone would
31 + * slip through. Distributing `keyof` over the union keeps every group covered.
32 + */
33 +type RawAuthField =
34 + | RawFields['auth_config_creation']['required'][number]
35 + | RawFields['auth_config_creation']['optional'][number]
36 + | RawFields['connected_account_initiation']['required'][number]
37 + | RawFields['connected_account_initiation']['optional'][number];
38 +
39 +type KeysOfUnion<T> = T extends unknown ? keyof T : never;
40 +
41 +/** Compile error carrying the offending keys when `Actual` is not empty. */
42 +type NoneLeftOver<Actual extends PropertyKey> = [Actual] extends [never] ? true : Actual;
43 +
44 +/**
45 + * Wire keys the transformer deliberately maps onto `ToolkitAuthField`.
46 + * Add a key here only together with the mapping and the schema field.
47 + */
48 +type MappedFieldKeys =
49 + | 'name'
50 + | 'displayName'
51 + | 'description'
52 + | 'type'
53 + | 'required'
54 + | 'default'
55 + | 'is_secret'
56 + | 'legacy_template_name';
57 +
58 +const everyFieldKeyIsMapped: NoneLeftOver<Exclude<KeysOfUnion<RawAuthField>, MappedFieldKeys>> =
59 + true;
60 +void everyFieldKeyIsMapped;
61 +
62 +/**
63 + * Wire keys on the auth config detail. `deprecated_auth_provider_details` is
64 + * listed as knowingly skipped: the client marks it `@deprecated` and warns
65 + * against further use, so it is excluded on purpose rather than by oversight.
66 + */
67 +type MappedDetailKeys =
68 + 'name' | 'mode' | 'fields' | 'proxy' | 'auth_hint_url' | 'deprecated_auth_provider_details';
69 +
70 +const everyDetailKeyIsMapped: NoneLeftOver<
71 + Exclude<KeysOfUnion<RawAuthConfigDetail>, MappedDetailKeys>
72 +> = true;
73 +void everyDetailKeyIsMapped;
74 +
75 +/** The camelCase counterparts must exist on the public types. */
76 +type MissingOnField = Exclude<
77 + | 'name'
78 + | 'displayName'
79 + | 'description'
80 + | 'type'
81 + | 'required'
82 + | 'default'
83 + | 'isSecret'
84 + | 'legacyTemplateName',
85 + keyof ToolkitAuthField
86 +>;
87 +const fieldTargetsExist: NoneLeftOver<MissingOnField> = true;
88 +void fieldTargetsExist;
89 +
90 +type MissingOnDetail = Exclude<
91 + 'name' | 'mode' | 'fields' | 'proxy' | 'authHintUrl',
92 + keyof ToolkitAuthConfigDetails
93 +>;
94 +const detailTargetsExist: NoneLeftOver<MissingOnDetail> = true;
95 +void detailTargetsExist;