@devries-cameron20 / composio-1 / commits / 7811edc84
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.

feat(ts): address ts comments, add .passthrough() to zod for future-proofness

jkomyno committed Feb 6, 2026 at 20:32 UTC 7811edc848d8df8f562ac44c9a2a36aa934fc388
2 files changed +156 -85
ts/packages/core/src/types/webhookEvents.types.ts
+112 -85
@@ -8,6 +8,7 @@ import { ConnectionStatuses } from './connectedAccountAuthStates.types';
8
9 export const WebhookEventTypes = {
10 CONNECTION_EXPIRED: 'composio.connected_account.expired',
11 + TRIGGER_MESSAGE: 'composio.trigger.message',
12 } as const;
13
14 export type WebhookEventType = (typeof WebhookEventTypes)[keyof typeof WebhookEventTypes];
@@ -26,24 +27,28 @@ export type WebhookEventType = (typeof WebhookEventTypes)[keyof typeof WebhookEv
27 * - Webhook payloads include additional fields (auth_scheme, deprecated)
28 * not present in the SDK schema
29 *
29 - * @see connectedAccounts.types.ts for the camelCase SDK version
30 + * Uses .passthrough() to accept unknown fields the API may add in the future.
31 + *
32 + * @see ConnectedAccountAuthConfigSchema in connectedAccounts.types.ts for the camelCase SDK version
33 */
31 -export const WebhookConnectedAccountAuthConfigSchema = z.object({
32 - /** The nano ID of the auth config */
33 - id: z.string(),
34 - /** @deprecated - use state.authScheme instead */
35 - auth_scheme: z.nativeEnum(AuthSchemeTypes),
36 - /** Whether this auth config is managed by Composio */
37 - is_composio_managed: z.boolean(),
38 - /** Whether the auth config is disabled */
39 - is_disabled: z.boolean(),
40 - /** @deprecated */
41 - deprecated: z
42 - .object({
43 - uuid: z.string(),
44 - })
45 - .optional(),
46 -});
34 +export const WebhookConnectedAccountAuthConfigSchema = z
35 + .object({
36 + /** The nano ID of the auth config */
37 + id: z.string(),
38 + /** @deprecated - use state.authScheme instead */
39 + auth_scheme: z.nativeEnum(AuthSchemeTypes),
40 + /** Whether this auth config is managed by Composio */
41 + is_composio_managed: z.boolean(),
42 + /** Whether the auth config is disabled */
43 + is_disabled: z.boolean(),
44 + /** @deprecated */
45 + deprecated: z
46 + .object({
47 + uuid: z.string(),
48 + })
49 + .optional(),
50 + })
51 + .passthrough();
52
53 export type WebhookConnectedAccountAuthConfig = z.infer<
54 typeof WebhookConnectedAccountAuthConfigSchema
@@ -59,68 +64,78 @@ export type WebhookConnectedAccountAuthConfig = z.infer<
64 * - Webhook payloads need loose validation (z.record(z.unknown()))
65 * since the connection state varies and isn't the focus of event handling
66 *
62 - * @see connectedAccountAuthStates.types.ts for the full typed version
67 + * Uses .passthrough() to accept unknown fields the API may add in the future.
68 + *
69 + * @see ConnectionDataSchema in connectedAccountAuthStates.types.ts for the full typed version
70 */
64 -export const WebhookConnectionStateSchema = z.object({
65 - /** The auth scheme type (e.g., 'OAUTH2', 'API_KEY') */
66 - authScheme: z.nativeEnum(AuthSchemeTypes),
67 - /** Connection state values - varies by auth scheme */
68 - val: z.record(z.unknown()),
69 -});
71 +export const WebhookConnectionStateSchema = z
72 + .object({
73 + /** The auth scheme type (e.g., 'OAUTH2', 'API_KEY') */
74 + authScheme: z.nativeEnum(AuthSchemeTypes),
75 + /** Connection state values - varies by auth scheme */
76 + val: z.record(z.unknown()),
77 + })
78 + .passthrough();
79
80 export type WebhookConnectionState = z.infer<typeof WebhookConnectionStateSchema>;
81
82 /**
83 * Connected account data schema for webhook payloads (raw API format, snake_case).
84 *
76 - * This intentionally does NOT reuse ConnectedAccountRetrieveResponseSchema from
77 - * connectedAccounts.types.ts because:
85 + * This is the snake_case equivalent of ConnectedAccountRetrieveResponseSchema
86 + * from connectedAccounts.types.ts. It intentionally does NOT reuse that schema because:
87 * - Webhook payloads arrive in raw snake_case (auth_config, user_id, created_at, etc.)
88 * while the SDK schema uses camelCase (authConfig, createdAt, etc.)
89 * - The SDK applies a transformation layer (utils/transformers/connectedAccounts.ts)
90 * before validation; webhooks are validated directly by the user
91 * - Webhook payloads include user_id, which the SDK schema omits
92 *
84 - * @see connectedAccounts.types.ts for the camelCase SDK version
93 + * Uses .passthrough() to accept unknown fields the API may add in the future.
94 + *
95 + * @see ConnectedAccountRetrieveResponseSchema in connectedAccounts.types.ts for the camelCase SDK version
96 * @see utils/transformers/connectedAccounts.ts for the snake-to-camel transformation
97 */
87 -export const SingleConnectedAccountDetailedResponseSchema = z.object({
88 - /** Toolkit information */
89 - toolkit: z.object({
90 - slug: z.string().describe('The slug of the toolkit'),
91 - }),
92 - /** Auth config details */
93 - auth_config: WebhookConnectedAccountAuthConfigSchema,
94 - /** The nano ID of the connected account */
95 - id: z.string(),
96 - /** @deprecated - user ID of the connection owner */
97 - user_id: z.string(),
98 - /** Connection status */
99 - status: z.nativeEnum(ConnectionStatuses),
100 - /** ISO-8601 timestamp of creation */
101 - created_at: z.string(),
102 - /** ISO-8601 timestamp of last update */
103 - updated_at: z.string(),
104 - /** Connection state data (auth scheme + state values) */
105 - state: WebhookConnectionStateSchema,
106 - /** @deprecated - use state instead */
107 - data: z.record(z.unknown()),
108 - /** @deprecated - use state instead */
109 - params: z.record(z.unknown()),
110 - /** Reason for the current status (e.g., expiration reason) */
111 - status_reason: z.string().nullable(),
112 - /** Whether the connection is disabled */
113 - is_disabled: z.boolean(),
114 - /** Endpoint for making test requests */
115 - test_request_endpoint: z.string().optional(),
116 - /** @deprecated */
117 - deprecated: z
118 - .object({
119 - labels: z.array(z.string()),
120 - uuid: z.string(),
121 - })
122 - .optional(),
123 -});
98 +export const SingleConnectedAccountDetailedResponseSchema = z
99 + .object({
100 + /** Toolkit information */
101 + toolkit: z
102 + .object({
103 + slug: z.string().describe('The slug of the toolkit'),
104 + })
105 + .passthrough(),
106 + /** Auth config details */
107 + auth_config: WebhookConnectedAccountAuthConfigSchema,
108 + /** The nano ID of the connected account */
109 + id: z.string(),
110 + /** @deprecated - user ID of the connection owner */
111 + user_id: z.string(),
112 + /** Connection status */
113 + status: z.nativeEnum(ConnectionStatuses),
114 + /** ISO-8601 timestamp of creation */
115 + created_at: z.string(),
116 + /** ISO-8601 timestamp of last update */
117 + updated_at: z.string(),
118 + /** Connection state data (auth scheme + state values) */
119 + state: WebhookConnectionStateSchema,
120 + /** @deprecated - use state instead */
121 + data: z.record(z.unknown()),
122 + /** @deprecated - use state instead */
123 + params: z.record(z.unknown()),
124 + /** Reason for the current status (e.g., expiration reason) */
125 + status_reason: z.string().nullable(),
126 + /** Whether the connection is disabled */
127 + is_disabled: z.boolean(),
128 + /** Endpoint for making test requests */
129 + test_request_endpoint: z.string().optional(),
130 + /** @deprecated */
131 + deprecated: z
132 + .object({
133 + labels: z.array(z.string()),
134 + uuid: z.string(),
135 + })
136 + .optional(),
137 + })
138 + .passthrough();
139
140 export type SingleConnectedAccountDetailedResponse = z.infer<
141 typeof SingleConnectedAccountDetailedResponseSchema
@@ -132,14 +147,18 @@ export type SingleConnectedAccountDetailedResponse = z.infer<
147
148 /**
149 * Webhook metadata for connection events.
135 - * Note: This differs from the trigger webhook metadata in WebhookPayloadV3Schema.
150 + * Note: This differs from the trigger webhook metadata in WebhookTriggerPayloadV3Schema.
151 + *
152 + * Uses .passthrough() to accept unknown fields the API may add in the future.
153 */
137 -export const WebhookConnectionMetadataSchema = z.object({
138 - /** Project nano ID */
139 - project_id: z.string(),
140 - /** Organization UUID */
141 - org_id: z.string(),
142 -});
154 +export const WebhookConnectionMetadataSchema = z
155 + .object({
156 + /** Project nano ID */
157 + project_id: z.string(),
158 + /** Organization UUID */
159 + org_id: z.string(),
160 + })
161 + .passthrough();
162
163 export type WebhookConnectionMetadata = z.infer<typeof WebhookConnectionMetadataSchema>;
164
@@ -147,6 +166,8 @@ export type WebhookConnectionMetadata = z.infer<typeof WebhookConnectionMetadata
166 * Connection expired webhook event payload.
167 * Emitted when a connected account expires due to authentication refresh failure.
168 *
169 + * Uses .passthrough() to accept unknown fields the API may add in the future.
170 + *
171 * @example
172 * ```typescript
173 * import { ConnectionExpiredEventSchema } from '@composio/core';
@@ -161,18 +182,20 @@ export type WebhookConnectionMetadata = z.infer<typeof WebhookConnectionMetadata
182 * }
183 * ```
184 */
164 -export const ConnectionExpiredEventSchema = z.object({
165 - /** Unique message ID (e.g., "msg_847cdfcd-d219-4f18-a6dd-91acd42ca94a") */
166 - id: z.string(),
167 - /** ISO-8601 timestamp of when the event was emitted */
168 - timestamp: z.string(),
169 - /** Event type identifier */
170 - type: z.literal(WebhookEventTypes.CONNECTION_EXPIRED),
171 - /** Connected account data (same as GET /api/v3/connected_accounts/{id}) */
172 - data: SingleConnectedAccountDetailedResponseSchema,
173 - /** Event metadata */
174 - metadata: WebhookConnectionMetadataSchema,
175 -});
185 +export const ConnectionExpiredEventSchema = z
186 + .object({
187 + /** Unique message ID (e.g., "msg_847cdfcd-d219-4f18-a6dd-91acd42ca94a") */
188 + id: z.string(),
189 + /** ISO-8601 timestamp of when the event was emitted */
190 + timestamp: z.string(),
191 + /** Event type identifier */
192 + type: z.literal(WebhookEventTypes.CONNECTION_EXPIRED),
193 + /** Connected account data (same as GET /api/v3/connected_accounts/{id}) */
194 + data: SingleConnectedAccountDetailedResponseSchema,
195 + /** Event metadata */
196 + metadata: WebhookConnectionMetadataSchema,
197 + })
198 + .passthrough();
199
200 export type ConnectionExpiredEvent = z.infer<typeof ConnectionExpiredEventSchema>;
201
@@ -184,8 +207,12 @@ export type ConnectionExpiredEvent = z.infer<typeof ConnectionExpiredEventSchema
207 * Union of all typed webhook event schemas.
208 * Extend this as new event types are added.
209 *
187 - * Note: This is separate from WebhookPayloadV3Schema which is a generic schema
188 - * for ANY V3 webhook. This union provides specific types for known events.
210 + * Note: This covers specific known event types with strict validation.
211 + * For unknown or new event types, use WebhookPayloadV3Schema from
212 + * triggers.types.ts which accepts any composio.* event with loose validation.
213 + *
214 + * Trigger events (composio.trigger.message) are handled through the
215 + * WebhookTriggerPayloadV3Schema in triggers.types.ts and the TriggerEvent type.
216 */
217 export const WebhookEventSchema = z.discriminatedUnion('type', [ConnectionExpiredEventSchema]);
218
ts/packages/core/test/types/webhookEvents.test.ts
+44
@@ -10,6 +10,7 @@ import {
10 describe('WebhookEventTypes', () => {
11 it('should have correct event type constants', () => {
12 expect(WebhookEventTypes.CONNECTION_EXPIRED).toBe('composio.connected_account.expired');
13 + expect(WebhookEventTypes.TRIGGER_MESSAGE).toBe('composio.trigger.message');
14 });
15 });
16
@@ -41,6 +42,20 @@ describe('WebhookConnectionMetadataSchema', () => {
42 const result = WebhookConnectionMetadataSchema.safeParse(invalidMetadata);
43 expect(result.success).toBe(false);
44 });
45 +
46 + it('should accept metadata with extra unknown fields (passthrough)', () => {
47 + const metadata = {
48 + project_id: 'pr_koucdrMIwRsf',
49 + org_id: '4a4ded8f-d3ae-4dea-a229-c30234298b05',
50 + some_future_field: 'new_value',
51 + };
52 +
53 + const result = WebhookConnectionMetadataSchema.safeParse(metadata);
54 + expect(result.success).toBe(true);
55 + if (result.success) {
56 + expect(result.data.some_future_field).toBe('new_value');
57 + }
58 + });
59 });
60
61 describe('SingleConnectedAccountDetailedResponseSchema', () => {
@@ -118,6 +133,21 @@ describe('SingleConnectedAccountDetailedResponseSchema', () => {
133 const result = SingleConnectedAccountDetailedResponseSchema.safeParse(data);
134 expect(result.success).toBe(false);
135 });
136 +
137 + it('should accept payloads with extra unknown fields (passthrough)', () => {
138 + const data = {
139 + ...validConnectedAccountData,
140 + some_future_field: 'future_value',
141 + another_new_field: 42,
142 + };
143 +
144 + const result = SingleConnectedAccountDetailedResponseSchema.safeParse(data);
145 + expect(result.success).toBe(true);
146 + if (result.success) {
147 + expect(result.data.some_future_field).toBe('future_value');
148 + expect(result.data.another_new_field).toBe(42);
149 + }
150 + });
151 });
152
153 describe('ConnectionExpiredEventSchema', () => {
@@ -211,6 +241,20 @@ describe('ConnectionExpiredEventSchema', () => {
241 expect(result.data.data.status_reason).toBe('Token refresh failed due to revoked access');
242 }
243 });
244 +
245 + it('accepts event payload with extra unknown fields (passthrough)', () => {
246 + const payload = {
247 + ...validPayload,
248 + version: '3.1',
249 + source: 'composio-webhook-system',
250 + };
251 + const result = ConnectionExpiredEventSchema.safeParse(payload);
252 + expect(result.success).toBe(true);
253 + if (result.success) {
254 + expect(result.data.version).toBe('3.1');
255 + expect(result.data.source).toBe('composio-webhook-system');
256 + }
257 + });
258 });
259
260 describe('WebhookEventSchema', () => {