1
+/**
2
+ * @fileoverview The `composio.experimental` namespace. Houses experimental
3
+ * SDK methods whose shape may change in future releases.
4
+ *
5
+ * For experimental stateless factories (e.g. `experimental_createTool`),
6
+ * see the top-level `experimental_*` exports from `@composio/core`.
7
+ * Anything that takes a Composio client and performs I/O belongs here.
8
+ */
9
+import ComposioClient, { BadRequestError } from '@composio/client';
10
+import {
11
+ ConnectedAccountPatchParams,
12
+ ConnectedAccountPatchResponse,
13
+ ConnectedAccountListParams as ConnectedAccountListParamsRaw,
14
+} from '@composio/client/resources/connected-accounts';
15
+import { LinkCreateParams } from '@composio/client/resources/link';
16
+import { SessionLinkParams } from '@composio/client/resources/tool-router/session/session';
17
+import {
18
+ ConnectedAccountExperimental,
19
+ UpdateConnectedAccountAclParams,
20
+ UpdateConnectedAccountAclParamsSchema,
21
+} from '../types/connectedAccounts.types';
22
+import { ValidationError } from '../errors/ValidationErrors';
23
+import { ComposioAclOnlyForSharedError } from '../errors';
24
+import { telemetry } from '../telemetry/Telemetry';
25
+
26
+/**
27
+ * Server-side 400 message the API uses to reject ACL writes against a
28
+ * PRIVATE connection. Substring-matched in `updateAcl` here, and in the
29
+ * sibling `connectedAccounts.link()` / `session.authorize()` call sites
30
+ * — kept as a single constant so a server-side message tweak only
31
+ * requires one edit.
32
+ */
33
+export const ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT = 'acl_config_for_shared is only valid on SHARED';
34
+
35
+/**
36
+ * Structural shape of the wire's experimental block on requests. Both
37
+ * `LinkCreateParams.Experimental` and `SessionLinkParams.Experimental`
38
+ * (Stainless-generated, nominally distinct) accept this shape.
39
+ */
40
+type ExperimentalWire = {
41
+ account_type?: 'PRIVATE' | 'SHARED';
42
+ acl_config_for_shared?: {
43
+ allow_all_users?: boolean;
44
+ allowed_user_ids?: string[];
45
+ not_allowed_user_ids?: string[];
46
+ };
47
+};
48
+
49
+/**
50
+ * Serialise the SDK's `aclConfigForShared` (camelCase) to the wire's
51
+ * `acl_config_for_shared` block. Returns `undefined` when the caller
52
+ * didn't pass anything (PATCH-style "don't touch ACL"); returns `{}`
53
+ * when the caller passed an explicit empty object.
54
+ */
55
+export function serializeAclConfigForWire(
56
+ acl:
57
+ | {
58
+ allowAllUsers?: boolean;
59
+ allowedUserIds?: string[];
60
+ notAllowedUserIds?: string[];
61
+ }
62
+ | undefined
63
+): NonNullable<ExperimentalWire['acl_config_for_shared']> | undefined {
64
+ if (acl === undefined) return undefined;
65
+ return {
66
+ ...(acl.allowAllUsers !== undefined && { allow_all_users: acl.allowAllUsers }),
67
+ ...(acl.allowedUserIds !== undefined && { allowed_user_ids: acl.allowedUserIds }),
68
+ ...(acl.notAllowedUserIds !== undefined && { not_allowed_user_ids: acl.notAllowedUserIds }),
69
+ };
70
+}
71
+
72
+/**
73
+ * Serialise the SDK's `experimental` options block (camelCase) to the
74
+ * wire's `experimental` block (snake_case). Used by both
75
+ * `connectedAccounts.link()` and `session.authorize()`. Returns
76
+ * `undefined` when the caller didn't pass the block at all.
77
+ */
78
+export function serializeExperimentalForWire(
79
+ experimental: ConnectedAccountExperimental | undefined
80
+): ExperimentalWire | undefined {
81
+ if (experimental === undefined) return undefined;
82
+ const aclWire = serializeAclConfigForWire(experimental.aclConfigForShared);
83
+ const wire: ExperimentalWire = {};
84
+ if (experimental.accountType !== undefined) {
85
+ wire.account_type = experimental.accountType;
86
+ }
87
+ if (aclWire !== undefined) {
88
+ wire.acl_config_for_shared = aclWire;
89
+ }
90
+ return wire;
91
+}
92
+
93
+/**
94
+ * `composio.experimental` namespace. Mirrors the Python SDK's
95
+ * `composio.experimental` mount, with one method per experimental
96
+ * surface. **Shape may change in future releases.**
97
+ */
98
+export class Experimental {
99
+ private client: ComposioClient;
100
+
101
+ constructor(client: ComposioClient) {
102
+ this.client = client;
103
+ telemetry.instrument(this, 'Experimental');
104
+ }
105
+
106
+ /**
107
+ * Update the per-user ACL on a SHARED connected account.
108
+ * **Experimental — shape may change in future releases.**
109
+ *
110
+ * Only meaningful for SHARED connections — calling this on a PRIVATE
111
+ * connection raises `ComposioAclOnlyForSharedError` (400). ACL writes
112
+ * require the connection's creator or an API key.
113
+ *
114
+ * PATCH semantics: omit a field to leave it unchanged; pass an empty
115
+ * array to clear an allow/deny list. At least one field must be
116
+ * provided.
117
+ *
118
+ * Resolution rule (deny wins):
119
+ * 1. requesting `userId` in `notAllowedUserIds` → DENY
120
+ * 2. `allowAllUsers === true` → ALLOW
121
+ * 3. requesting `userId` in `allowedUserIds` → ALLOW
122
+ * 4. otherwise → DENY
123
+ *
124
+ * @example
125
+ * ```typescript
126
+ * import { Composio } from '@composio/core';
127
+ *
128
+ * const composio = new Composio({ apiKey: '...' });
129
+ *
130
+ * // Allow every userId to use this connection
131
+ * await composio.experimental.updateAcl('ca_abc', { allowAllUsers: true });
132
+ *
133
+ * // Everyone except a specific user
134
+ * await composio.experimental.updateAcl('ca_abc', {
135
+ * allowAllUsers: true,
136
+ * notAllowedUserIds: ['user_bob'],
137
+ * });
138
+ *
139
+ * // Targeted allow
140
+ * await composio.experimental.updateAcl('ca_abc', {
141
+ * allowedUserIds: ['user_alice', 'user_bob'],
142
+ * });
143
+ *
144
+ * // Revoke a previously-granted allow list (back to deny-by-default)
145
+ * await composio.experimental.updateAcl('ca_abc', { allowedUserIds: [] });
146
+ * ```
147
+ *
148
+ * **Empty-array semantics — read carefully.** Passing `[]` for either
149
+ * list **replaces** the list, it does not extend it:
150
+ *
151
+ * - `allowedUserIds: []` → revoke all previously-granted user IDs (state
152
+ * reverts to deny-by-default unless `allowAllUsers` is true).
153
+ * - `notAllowedUserIds: []` → **clears the deny list**, which silently
154
+ * re-grants access to users you previously blocked. Always pair an
155
+ * empty deny list with a deliberate audit of the allow side.
156
+ *
157
+ * @returns The PATCH response (`{ id, status, success }`). To read
158
+ * the updated ACL block, call
159
+ * `composio.connectedAccounts.get(nanoid)` after the promise
160
+ * resolves and inspect `account.experimental?.aclConfigForShared`.
161
+ */
162
+ async updateAcl(
163
+ nanoid: string,
164
+ params: UpdateConnectedAccountAclParams
165
+ ): Promise<ConnectedAccountPatchResponse> {
166
+ const parsedParams = UpdateConnectedAccountAclParamsSchema.safeParse(params);
167
+ if (!parsedParams.success) {
168
+ throw new ValidationError('Failed to parse connected account ACL update params', {
169
+ cause: parsedParams.error,
170
+ });
171
+ }
172
+
173
+ const body: ConnectedAccountPatchParams = {
174
+ experimental: {
175
+ acl_config_for_shared: serializeAclConfigForWire(parsedParams.data),
176
+ },
177
+ };
178
+
179
+ try {
180
+ return await this.client.connectedAccounts.patch(nanoid, body);
181
+ } catch (error) {
182
+ if (
183
+ error instanceof BadRequestError &&
184
+ typeof error.message === 'string' &&
185
+ error.message.includes(ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT)
186
+ ) {
187
+ throw new ComposioAclOnlyForSharedError(error.message, { cause: error });
188
+ }
189
+ throw error;
190
+ }
191
+ }
192
+}
193
+
194
+// Re-exports so the wire-shape helpers stay reachable from the existing
195
+// callsites in `models/` without bouncing through `experimental.ts` —
196
+// the canonical home is here, but the imports look unchanged at the
197
+// caller.
198
+export type { LinkCreateParams, SessionLinkParams, ConnectedAccountListParamsRaw };