Skip to content

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

jkomyno7811edc848d8
diff --git a/ts/packages/core/src/types/webhookEvents.types.ts b/ts/packages/core/src/types/webhookEvents.types.ts
index e22f1a551..24132886e 100644
--- a/ts/packages/core/src/types/webhookEvents.types.ts
+++ b/ts/packages/core/src/types/webhookEvents.types.ts
@@ -8,6 +8,7 @@ import { ConnectionStatuses } from './connectedAccountAuthStates.types';
export const WebhookEventTypes = {
CONNECTION_EXPIRED: 'composio.connected_account.expired',
+ TRIGGER_MESSAGE: 'composio.trigger.message',
} as const;
export type WebhookEventType = (typeof WebhookEventTypes)[keyof typeof WebhookEventTypes];
@@ -26,24 +27,28 @@ export type WebhookEventType = (typeof WebhookEventTypes)[keyof typeof WebhookEv
* - Webhook payloads include additional fields (auth_scheme, deprecated)
* not present in the SDK schema
*
- * @see connectedAccounts.types.ts for the camelCase SDK version
+ * Uses .passthrough() to accept unknown fields the API may add in the future.
+ *
+ * @see ConnectedAccountAuthConfigSchema in connectedAccounts.types.ts for the camelCase SDK version
*/
-export const WebhookConnectedAccountAuthConfigSchema = z.object({
- /** The nano ID of the auth config */
- id: z.string(),
- /** @deprecated - use state.authScheme instead */
- auth_scheme: z.nativeEnum(AuthSchemeTypes),
- /** Whether this auth config is managed by Composio */
- is_composio_managed: z.boolean(),
- /** Whether the auth config is disabled */
- is_disabled: z.boolean(),
- /** @deprecated */
- deprecated: z
- .object({
- uuid: z.string(),
- })
- .optional(),
-});
+export const WebhookConnectedAccountAuthConfigSchema = z
+ .object({
+ /** The nano ID of the auth config */
+ id: z.string(),
+ /** @deprecated - use state.authScheme instead */
+ auth_scheme: z.nativeEnum(AuthSchemeTypes),
+ /** Whether this auth config is managed by Composio */
+ is_composio_managed: z.boolean(),
+ /** Whether the auth config is disabled */
+ is_disabled: z.boolean(),
+ /** @deprecated */
+ deprecated: z
+ .object({
+ uuid: z.string(),
+ })
+ .optional(),
+ })
+ .passthrough();
export type WebhookConnectedAccountAuthConfig = z.infer<
typeof WebhookConnectedAccountAuthConfigSchema
@@ -59,68 +64,78 @@ export type WebhookConnectedAccountAuthConfig = z.infer<
* - Webhook payloads need loose validation (z.record(z.unknown()))
* since the connection state varies and isn't the focus of event handling
*
- * @see connectedAccountAuthStates.types.ts for the full typed version
+ * Uses .passthrough() to accept unknown fields the API may add in the future.
+ *
+ * @see ConnectionDataSchema in connectedAccountAuthStates.types.ts for the full typed version
*/
-export const WebhookConnectionStateSchema = z.object({
- /** The auth scheme type (e.g., 'OAUTH2', 'API_KEY') */
- authScheme: z.nativeEnum(AuthSchemeTypes),
- /** Connection state values - varies by auth scheme */
- val: z.record(z.unknown()),
-});
+export const WebhookConnectionStateSchema = z
+ .object({
+ /** The auth scheme type (e.g., 'OAUTH2', 'API_KEY') */
+ authScheme: z.nativeEnum(AuthSchemeTypes),
+ /** Connection state values - varies by auth scheme */
+ val: z.record(z.unknown()),
+ })
+ .passthrough();
export type WebhookConnectionState = z.infer<typeof WebhookConnectionStateSchema>;
/**
* Connected account data schema for webhook payloads (raw API format, snake_case).
*
- * This intentionally does NOT reuse ConnectedAccountRetrieveResponseSchema from
- * connectedAccounts.types.ts because:
+ * This is the snake_case equivalent of ConnectedAccountRetrieveResponseSchema
+ * from connectedAccounts.types.ts. It intentionally does NOT reuse that schema because:
* - Webhook payloads arrive in raw snake_case (auth_config, user_id, created_at, etc.)
* while the SDK schema uses camelCase (authConfig, createdAt, etc.)
* - The SDK applies a transformation layer (utils/transformers/connectedAccounts.ts)
* before validation; webhooks are validated directly by the user
* - Webhook payloads include user_id, which the SDK schema omits
*
- * @see connectedAccounts.types.ts for the camelCase SDK version
+ * Uses .passthrough() to accept unknown fields the API may add in the future.
+ *
+ * @see ConnectedAccountRetrieveResponseSchema in connectedAccounts.types.ts for the camelCase SDK version
* @see utils/transformers/connectedAccounts.ts for the snake-to-camel transformation
*/
-export const SingleConnectedAccountDetailedResponseSchema = z.object({
- /** Toolkit information */
- toolkit: z.object({
- slug: z.string().describe('The slug of the toolkit'),
- }),
- /** Auth config details */
- auth_config: WebhookConnectedAccountAuthConfigSchema,
- /** The nano ID of the connected account */
- id: z.string(),
- /** @deprecated - user ID of the connection owner */
- user_id: z.string(),
- /** Connection status */
- status: z.nativeEnum(ConnectionStatuses),
- /** ISO-8601 timestamp of creation */
- created_at: z.string(),
- /** ISO-8601 timestamp of last update */
- updated_at: z.string(),
- /** Connection state data (auth scheme + state values) */
- state: WebhookConnectionStateSchema,
- /** @deprecated - use state instead */
- data: z.record(z.unknown()),
- /** @deprecated - use state instead */
- params: z.record(z.unknown()),
- /** Reason for the current status (e.g., expiration reason) */
- status_reason: z.string().nullable(),
- /** Whether the connection is disabled */
- is_disabled: z.boolean(),
- /** Endpoint for making test requests */
- test_request_endpoint: z.string().optional(),
- /** @deprecated */
- deprecated: z
- .object({
- labels: z.array(z.string()),
- uuid: z.string(),
- })
- .optional(),
-});
+export const SingleConnectedAccountDetailedResponseSchema = z
+ .object({
+ /** Toolkit information */
+ toolkit: z
+ .object({
+ slug: z.string().describe('The slug of the toolkit'),
+ })
+ .passthrough(),
+ /** Auth config details */
+ auth_config: WebhookConnectedAccountAuthConfigSchema,
+ /** The nano ID of the connected account */
+ id: z.string(),
+ /** @deprecated - user ID of the connection owner */
+ user_id: z.string(),
+ /** Connection status */
+ status: z.nativeEnum(ConnectionStatuses),
+ /** ISO-8601 timestamp of creation */
+ created_at: z.string(),
+ /** ISO-8601 timestamp of last update */
+ updated_at: z.string(),
+ /** Connection state data (auth scheme + state values) */
+ state: WebhookConnectionStateSchema,
+ /** @deprecated - use state instead */
+ data: z.record(z.unknown()),
+ /** @deprecated - use state instead */
+ params: z.record(z.unknown()),
+ /** Reason for the current status (e.g., expiration reason) */
+ status_reason: z.string().nullable(),
+ /** Whether the connection is disabled */
+ is_disabled: z.boolean(),
+ /** Endpoint for making test requests */
+ test_request_endpoint: z.string().optional(),
+ /** @deprecated */
+ deprecated: z
+ .object({
+ labels: z.array(z.string()),
+ uuid: z.string(),
+ })
+ .optional(),
+ })
+ .passthrough();
export type SingleConnectedAccountDetailedResponse = z.infer<
typeof SingleConnectedAccountDetailedResponseSchema
@@ -132,14 +147,18 @@ export type SingleConnectedAccountDetailedResponse = z.infer<
/**
* Webhook metadata for connection events.
- * Note: This differs from the trigger webhook metadata in WebhookPayloadV3Schema.
+ * Note: This differs from the trigger webhook metadata in WebhookTriggerPayloadV3Schema.
+ *
+ * Uses .passthrough() to accept unknown fields the API may add in the future.
*/
-export const WebhookConnectionMetadataSchema = z.object({
- /** Project nano ID */
- project_id: z.string(),
- /** Organization UUID */
- org_id: z.string(),
-});
+export const WebhookConnectionMetadataSchema = z
+ .object({
+ /** Project nano ID */
+ project_id: z.string(),
+ /** Organization UUID */
+ org_id: z.string(),
+ })
+ .passthrough();
export type WebhookConnectionMetadata = z.infer<typeof WebhookConnectionMetadataSchema>;
@@ -147,6 +166,8 @@ export type WebhookConnectionMetadata = z.infer<typeof WebhookConnectionMetadata
* Connection expired webhook event payload.
* Emitted when a connected account expires due to authentication refresh failure.
*
+ * Uses .passthrough() to accept unknown fields the API may add in the future.
+ *
* @example
* ```typescript
* import { ConnectionExpiredEventSchema } from '@composio/core';
@@ -161,18 +182,20 @@ export type WebhookConnectionMetadata = z.infer<typeof WebhookConnectionMetadata
* }
* ```
*/
-export const ConnectionExpiredEventSchema = z.object({
- /** Unique message ID (e.g., "msg_847cdfcd-d219-4f18-a6dd-91acd42ca94a") */
- id: z.string(),
- /** ISO-8601 timestamp of when the event was emitted */
- timestamp: z.string(),
- /** Event type identifier */
- type: z.literal(WebhookEventTypes.CONNECTION_EXPIRED),
- /** Connected account data (same as GET /api/v3/connected_accounts/{id}) */
- data: SingleConnectedAccountDetailedResponseSchema,
- /** Event metadata */
- metadata: WebhookConnectionMetadataSchema,
-});
+export const ConnectionExpiredEventSchema = z
+ .object({
+ /** Unique message ID (e.g., "msg_847cdfcd-d219-4f18-a6dd-91acd42ca94a") */
+ id: z.string(),
+ /** ISO-8601 timestamp of when the event was emitted */
+ timestamp: z.string(),
+ /** Event type identifier */
+ type: z.literal(WebhookEventTypes.CONNECTION_EXPIRED),
+ /** Connected account data (same as GET /api/v3/connected_accounts/{id}) */
+ data: SingleConnectedAccountDetailedResponseSchema,
+ /** Event metadata */
+ metadata: WebhookConnectionMetadataSchema,
+ })
+ .passthrough();
export type ConnectionExpiredEvent = z.infer<typeof ConnectionExpiredEventSchema>;
@@ -184,8 +207,12 @@ export type ConnectionExpiredEvent = z.infer<typeof ConnectionExpiredEventSchema
* Union of all typed webhook event schemas.
* Extend this as new event types are added.
*
- * Note: This is separate from WebhookPayloadV3Schema which is a generic schema
- * for ANY V3 webhook. This union provides specific types for known events.
+ * Note: This covers specific known event types with strict validation.
+ * For unknown or new event types, use WebhookPayloadV3Schema from
+ * triggers.types.ts which accepts any composio.* event with loose validation.
+ *
+ * Trigger events (composio.trigger.message) are handled through the
+ * WebhookTriggerPayloadV3Schema in triggers.types.ts and the TriggerEvent type.
*/
export const WebhookEventSchema = z.discriminatedUnion('type', [ConnectionExpiredEventSchema]);
diff --git a/ts/packages/core/test/types/webhookEvents.test.ts b/ts/packages/core/test/types/webhookEvents.test.ts
index b276980a9..41904120c 100644
--- a/ts/packages/core/test/types/webhookEvents.test.ts
+++ b/ts/packages/core/test/types/webhookEvents.test.ts
@@ -10,6 +10,7 @@ import {
describe('WebhookEventTypes', () => {
it('should have correct event type constants', () => {
expect(WebhookEventTypes.CONNECTION_EXPIRED).toBe('composio.connected_account.expired');
+ expect(WebhookEventTypes.TRIGGER_MESSAGE).toBe('composio.trigger.message');
});
});
@@ -41,6 +42,20 @@ describe('WebhookConnectionMetadataSchema', () => {
const result = WebhookConnectionMetadataSchema.safeParse(invalidMetadata);
expect(result.success).toBe(false);
});
+
+ it('should accept metadata with extra unknown fields (passthrough)', () => {
+ const metadata = {
+ project_id: 'pr_koucdrMIwRsf',
+ org_id: '4a4ded8f-d3ae-4dea-a229-c30234298b05',
+ some_future_field: 'new_value',
+ };
+
+ const result = WebhookConnectionMetadataSchema.safeParse(metadata);
+ expect(result.success).toBe(true);
+ if (result.success) {
+ expect(result.data.some_future_field).toBe('new_value');
+ }
+ });
});
describe('SingleConnectedAccountDetailedResponseSchema', () => {
@@ -118,6 +133,21 @@ describe('SingleConnectedAccountDetailedResponseSchema', () => {
const result = SingleConnectedAccountDetailedResponseSchema.safeParse(data);
expect(result.success).toBe(false);
});
+
+ it('should accept payloads with extra unknown fields (passthrough)', () => {
+ const data = {
+ ...validConnectedAccountData,
+ some_future_field: 'future_value',
+ another_new_field: 42,
+ };
+
+ const result = SingleConnectedAccountDetailedResponseSchema.safeParse(data);
+ expect(result.success).toBe(true);
+ if (result.success) {
+ expect(result.data.some_future_field).toBe('future_value');
+ expect(result.data.another_new_field).toBe(42);
+ }
+ });
});
describe('ConnectionExpiredEventSchema', () => {
@@ -211,6 +241,20 @@ describe('ConnectionExpiredEventSchema', () => {
expect(result.data.data.status_reason).toBe('Token refresh failed due to revoked access');
}
});
+
+ it('accepts event payload with extra unknown fields (passthrough)', () => {
+ const payload = {
+ ...validPayload,
+ version: '3.1',
+ source: 'composio-webhook-system',
+ };
+ const result = ConnectionExpiredEventSchema.safeParse(payload);
+ expect(result.success).toBe(true);
+ if (result.success) {
+ expect(result.data.version).toBe('3.1');
+ expect(result.data.source).toBe('composio-webhook-system');
+ }
+ });
});
describe('WebhookEventSchema', () => {