Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 10:45 UTC
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', () => {