Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(connected-accounts): sanitize public docstrings — remove internal references
venkat82eba561f771bd
diff --git a/.changeset/connected-accounts-acl.md b/.changeset/connected-accounts-acl.mdindex d580488b7..b963e8818 100644--- a/.changeset/connected-accounts-acl.md+++ b/.changeset/connected-accounts-acl.md@@ -2,14 +2,12 @@'@composio/core': minor----Add `accountType` and per-user ACL support for SHARED connected accounts (Hermes #9860, #9882, #9902).+Add `accountType` and per-user ACL support for SHARED connected accounts.-Surfaces three Apollo-side features that previously had no SDK wrappers:--- **`accountType` on create**: `composio.connectedAccounts.link(userId, authConfigId, { accountType: 'SHARED' })` creates a SHARED connection. Default remains `PRIVATE`. SHARED is reachable from a tool-router session by other users in the project, but only when explicitly pinned and only when the requesting `userId` passes the connection's ACL.+- **`accountType` on create**: `composio.connectedAccounts.link(userId, authConfigId, { accountType: 'SHARED' })` creates a SHARED connection. Default remains `PRIVATE`. A SHARED connection can be used by other `userId`s, but only when the connection is explicitly pinned in a tool-router session's config and only when the requesting `userId` passes the connection's ACL.- **`accountType` on retrieve**: `get()` and `list()` responses now include `accountType` (`'PRIVATE' | 'SHARED'`).-- **`aclConfigForShared` on create + retrieve**: per-user ACL block — `{ allowAllUsers, allowedUserIds, notAllowedUserIds }`. On responses the whole block is `undefined` for non-creator/non-API-key callers (the backend strips it), so callers can distinguish *"I can't see the ACL"* from *"ACL is the default deny-by-default state"*.-- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the ACL via `PATCH /connected_accounts/{id}` (the SDK serialises to the wire's `acl_config_for_shared` block). Backend rejects ACL writes on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field required.+- **`aclConfigForShared` on create + retrieve**: per-user ACL block — `{ allowAllUsers, allowedUserIds, notAllowedUserIds }`. On responses the field is `undefined` when the caller isn't authorised to see the ACL, so callers can distinguish *"I can't see the ACL"* from *"ACL is the default deny-by-default state"*.+- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the ACL via `PATCH`. PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field required. Calling on a PRIVATE connection raises `ComposioAclOnlyForSharedError` (400).- **`ToolRouterSession.authorize()` options gain `accountType` + `aclConfigForShared`**, so a SHARED connection with an ACL can be created in one call from inside a tool-router session.ACL resolution rule (deny wins):@@ -19,14 +17,14 @@ ACL resolution rule (deny wins):3. requesting `userId` ∈ `allowedUserIds` → ALLOW4. otherwise → DENY (deny-by-default)-Backend caps: each ACL list ≤1000 entries; each `userId` 1..256 chars. The SDK enforces these caps via Zod at the input boundary.+Limits: each ACL list accepts up to 1000 entries; each `userId` is 1..256 characters. The SDK enforces these caps at the input boundary.New error classes:- `ComposioSharedAccessDeniedError` (403) — surfaces from direct `connectedAccountId` execution paths when the requesting user fails the ACL.-- `ComposioAclOnlyForSharedError` (400) — sent ACL fields on a PRIVATE row.+- `ComposioAclOnlyForSharedError` (400) — ACL fields sent on a PRIVATE connection.- `ComposioSharedConnectionNotAccessibleError` (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.No breaking changes. Existing `link()` callers without the new options get a `PRIVATE` connection exactly as today; existing `get()` / `list()` callers see new optional fields.-The Python SDK mirror ships in a separate PR — same wire contract, same release train.+The Python SDK mirror ships in a separate PR.diff --git a/ts/packages/core/src/errors/ConnectedAccountsErrors.ts b/ts/packages/core/src/errors/ConnectedAccountsErrors.tsindex 48cd19d78..3d5e92d3a 100644--- a/ts/packages/core/src/errors/ConnectedAccountsErrors.ts+++ b/ts/packages/core/src/errors/ConnectedAccountsErrors.ts@@ -60,12 +60,9 @@ export class ComposioFailedToCreateConnectedAccountLink extends ComposioError {* Thrown when a tool execution attempts to use a SHARED connected account* but the requesting `userId` is not allowed by the connection's ACL.*- * Surfaces from the matching layer when a SHARED connection is reached- * directly (e.g. via `composio.tools.execute(slug, { connectedAccountId })`)- * without going through a tool-router session that already pre-flighted the- * ACL at session-create time.- *- * Backend response: 403 with code `ConnectedAccount_SharedAccessDenied`.+ * Surfaces when a SHARED connection is reached directly (e.g. via+ * `composio.tools.execute(slug, { connectedAccountId })`) without going+ * through a tool-router session.*/export class ComposioSharedAccessDeniedError extends ComposioError {constructor(@@ -86,11 +83,8 @@ export class ComposioSharedAccessDeniedError extends ComposioError {/*** Thrown when ACL fields (`allowAllUsers`, `allowedUserIds`,- * `notAllowedUserIds`) are sent on a `PRIVATE` connection — at create time- * or via PATCH. ACL is only meaningful for `SHARED` connections; the- * matching layer never reads it for PRIVATE.- *- * Backend response: 400 with code `ConnectedAccount_AclOnlyForShared`.+ * `notAllowedUserIds`) are sent on a `PRIVATE` connection — at create+ * time or via PATCH. ACL is only meaningful for `SHARED` connections.*/export class ComposioAclOnlyForSharedError extends ComposioError {constructor(@@ -111,10 +105,8 @@ export class ComposioAclOnlyForSharedError extends ComposioError {/*** Thrown by tool-router session create / PATCH when the session's `userId`- * cannot use a pinned SHARED connection — caught at session-create time so- * the session never enters a state that 4xxs mid-execution.- *- * Backend response: 400 with code `ToolRouterV2_SharedConnectionNotAccessible`.+ * cannot use a pinned SHARED connection — caught at session-create time+ * so the session never enters a state that fails mid-execution.*/export class ComposioSharedConnectionNotAccessibleError extends ComposioError {constructor(diff --git a/ts/packages/core/src/models/ConnectedAccounts.ts b/ts/packages/core/src/models/ConnectedAccounts.tsindex 3c34fe703..c3e932f89 100644--- a/ts/packages/core/src/models/ConnectedAccounts.ts+++ b/ts/packages/core/src/models/ConnectedAccounts.ts@@ -57,12 +57,12 @@ import { ConnectionData } from '../types/connectedAccountAuthStates.types';let _legacyInitiateWarningEmitted = false;/**- * Serialise the SDK's `aclConfigForShared` (camelCase, top-level optional)- * to the wire's `acl_config_for_shared` block. Returns `undefined` when the- * caller didn't pass anything (PATCH-style "don't touch ACL"); returns- * `{}` when the caller passed an explicit empty object (the backend treats- * both the same way today — deny-by-default — but the explicit form is- * preserved so the intent is visible in network traces).+ * Serialise the SDK's `aclConfigForShared` (camelCase) to the wire's+ * `acl_config_for_shared` block. Returns `undefined` when the caller+ * didn't pass anything (PATCH-style "don't touch ACL"); returns `{}`+ * when the caller passed an explicit empty object — both mean+ * deny-by-default, but the explicit form preserves the caller's intent+ * in network traces.*/function serializeAclConfigForWire(acl:@@ -419,9 +419,8 @@ export class ConnectedAccounts {);return connectionRequest;} catch (error) {- // Backend rejects ACL fields on PRIVATE connections with a 400 +- // `ConnectedAccount_AclOnlyForShared`. Surface it as a typed error so- // callers can `instanceof` instead of grepping messages.+ // The server rejects ACL on PRIVATE connections — surface that as a+ // typed error so callers can `instanceof` instead of grepping messages.if (error instanceof BadRequestError &&typeof error.message === 'string' &&@@ -616,11 +615,9 @@ export class ConnectedAccounts {}/**- * Enable or disable a connected account (wraps the `/status` endpoint- * — accepts only `{ enabled: boolean }` despite the historical JSDoc- * mentioning "alias and/or credentials"). For ACL writes on SHARED- * connections, see {@link updateAcl}. Alias / credential PATCH isn't- * surfaced on the SDK yet.+ * Enable or disable a connected account. Accepts `{ enabled: boolean }`.+ *+ * For ACL writes on SHARED connections, see {@link updateAcl}.** @param {string} nanoid - The unique identifier of the connected account* @param {UpdateConnectedAccountParams} params - The update parameters@@ -649,23 +646,23 @@ export class ConnectedAccounts {/*** Update the per-user ACL on a SHARED connected account.*- * Only meaningful for SHARED connections — the backend rejects ACL writes- * on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). Auth gate is- * creator-or-API-key (a non-creator project member updating an alias on a- * SHARED row still works via {@link update}, but ACL writes do not).+ * Only meaningful for SHARED connections — calling this on a PRIVATE+ * connection raises `ComposioAclOnlyForSharedError` (400). ACL writes+ * require the connection's creator or an API key; alias edits via+ * {@link update} are governed separately.** PATCH semantics: omit a field to leave it unchanged; pass an empty array* to clear an allow/deny list. At least one field must be provided.** Resolution rule (deny wins):- * 1. requesting userId in `notAllowedUserIds` → DENY- * 2. `allowAllUsers === true` → ALLOW- * 3. requesting userId in `allowedUserIds` → ALLOW- * 4. otherwise → DENY+ * 1. requesting `userId` in `notAllowedUserIds` → DENY+ * 2. `allowAllUsers === true` → ALLOW+ * 3. requesting `userId` in `allowedUserIds` → ALLOW+ * 4. otherwise → DENY** @example* ```typescript- * // Open access to everyone in the project+ * // Allow every userId to use this connection* await composio.connectedAccounts.updateAcl('ca_abc', { allowAllUsers: true });** // Everyone except a specific user@@ -714,8 +711,8 @@ export class ConnectedAccounts {try {return await this.client.connectedAccounts.patch(nanoid, body);} catch (error) {- // Same `AclOnlyForShared` 400 the create path can hit — backend- // rejects ACL writes on a PRIVATE row at PATCH-time too.+ // Same ACL-on-PRIVATE rejection the create path can hit — surface+ // it as a typed error.if (error instanceof BadRequestError &&typeof error.message === 'string' &&diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex c50982977..e3dd6343b 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -76,9 +76,9 @@ export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =* Options accepted by {@link ToolRouterSession.authorize}.** Validated at the SDK boundary so callers get clear `ValidationError`s for- * oversized ACL lists or invalid user IDs — same Zod caps as the equivalent+ * oversized ACL lists or invalid `userId`s — same caps as the equivalent* `composio.connectedAccounts.link()` path (≤1000 entries per list, each- * user_id 1..256 chars). Caught Bugbot review.+ * `userId` 1..256 characters).*/const AuthorizeOptionsSchema = z.object({callbackUrl: z.string().optional(),@@ -327,15 +327,14 @@ export class ToolRouterSession<* Initiate an authorization flow for a toolkit.* Returns a ConnectionRequest with a redirect URL for the user.*- * `accountType` and `aclConfigForShared` (Hermes #9860, #9902) let the- * caller create a SHARED connection with a per-user ACL in one flow.- * Default behaviour (omit both) creates a PRIVATE connection.+ * Use `accountType` and `aclConfigForShared` to create a SHARED connection+ * with a per-user ACL in one flow. Default behaviour (omit both) creates+ * a PRIVATE connection.*- * `aclConfigForShared` is validated through `ConnectedAccountAclConfigSchema`- * — same Zod caps as `composio.connectedAccounts.link()` (≤1000 entries- * per list, each user_id 1..256 chars). Invalid input throws- * `ValidationError` at the SDK boundary instead of hitting an opaque- * backend 400.+ * `aclConfigForShared` is validated against the same caps as+ * `composio.connectedAccounts.link()` (≤1000 entries per list, each+ * `userId` 1..256 characters). Invalid input throws `ValidationError`+ * at the SDK boundary.*/async authorize(toolkit: string,@@ -379,9 +378,8 @@ export class ToolRouterSession<try {response = await this.client.toolRouter.session.link(this.sessionId, body);} catch (error) {- // Backend rejects ACL fields on PRIVATE connections with a 400 +- // `ConnectedAccount_AclOnlyForShared`. Surface it as a typed error- // mirroring `composio.connectedAccounts.link()`.+ // The server rejects ACL on PRIVATE connections — surface that as a+ // typed error mirroring `composio.connectedAccounts.link()`.if (error instanceof BadRequestError &&typeof error.message === 'string' &&diff --git a/ts/packages/core/src/types/connectedAccounts.types.ts b/ts/packages/core/src/types/connectedAccounts.types.tsindex bad43af21..745214568 100644--- a/ts/packages/core/src/types/connectedAccounts.types.ts+++ b/ts/packages/core/src/types/connectedAccounts.types.ts@@ -31,11 +31,11 @@ export type ConnectedAccountStatusEnum = z.infer<typeof ConnectedAccountStatusSc* Sharing model for a connected account.** - `PRIVATE` (default): only the owning `userId` can use the connection.- * - `SHARED`: reachable from a tool-router session by other users in the- * project, but only when explicitly pinned in the session config and only- * when the requesting `userId` passes the connection's ACL (see- * `allowAllUsers` / `allowedUserIds` / `notAllowedUserIds`). Set at create- * time only — cannot be changed later.+ * - `SHARED`: can be used by other `userId`s, but only when the connection+ * is explicitly pinned in a tool-router session's config and only when+ * the requesting `userId` passes the connection's ACL (see+ * `allowAllUsers` / `allowedUserIds` / `notAllowedUserIds`). Set at+ * creation time only — cannot be changed later.*/export const ConnectedAccountTypes = {PRIVATE: 'PRIVATE',@@ -49,24 +49,26 @@ export type ConnectedAccountType =(typeof ConnectedAccountTypes)[keyof typeof ConnectedAccountTypes];/**- * Per-user access control for a SHARED connected account. Inert for PRIVATE.+ * Per-user access control for a SHARED connected account. Ignored for+ * PRIVATE.*- * On the wire this lives under `acl_config_for_shared` — a single JSONB- * column on `connected_accounts`. The SDK exposes the inner shape as- * `aclConfigForShared` on inputs and responses (omit the block to mean- * "don't touch ACL" on create / PATCH; absence on a response means the- * caller isn't allowed to see the ACL).+ * Pass `aclConfigForShared` on create / PATCH to grant access; omit it+ * to leave the ACL unchanged (on PATCH) or to keep the default+ * deny-by-default state (on create). On responses, the field is+ * `undefined` when the caller isn't authorised to see the ACL —+ * distinguish that from an empty/default state explicitly.** Resolution rule (deny wins):- * 1. requesting userId in `notAllowedUserIds` → DENY- * 2. `allowAllUsers === true` → ALLOW- * 3. requesting userId in `allowedUserIds` → ALLOW- * 4. otherwise → DENY (deny-by-default)+ * 1. requesting `userId` in `notAllowedUserIds` → DENY+ * 2. `allowAllUsers === true` → ALLOW+ * 3. requesting `userId` in `allowedUserIds` → ALLOW+ * 4. otherwise → DENY (deny-by-default)*- * Default state (block omitted or `{}`) means only the connection's creator- * can use it. The creator must grant access explicitly.+ * Default state (block omitted or `{}`) means only the connection's+ * creator can use it. The creator must grant access explicitly.*- * Backend caps: each list ≤1000 entries; each user_id 1..256 chars.+ * Limits: each list accepts up to 1000 entries; each `userId` is+ * 1..256 characters.*/const ACL_LIST_MAX_LENGTH = 1000;const ACL_USER_ID_MAX_LENGTH = 256;@@ -76,24 +78,24 @@ export const ConnectedAccountAclConfigSchema = z.object({allowAllUsers: z.boolean().optional()- .describe('Wildcard "any user_id in the project" allow toggle. Default false.'),+ .describe('When true, any `userId` may use this SHARED connection (subject to the deny list). Default false.'),allowedUserIds: z.array(aclUserIdString).max(ACL_LIST_MAX_LENGTH).optional()- .describe('Explicit allow list (developer-assigned user_id strings). Default [].'),+ .describe('Explicit list of `userId` strings allowed to use this SHARED connection. Default [].'),notAllowedUserIds: z.array(aclUserIdString).max(ACL_LIST_MAX_LENGTH).optional()- .describe('Explicit deny list. Wins over allow on conflict. Default [].'),+ .describe('Explicit list of `userId` strings denied access. Wins over allow on conflict. Default [].'),});export type ConnectedAccountAclConfig = z.infer<typeof ConnectedAccountAclConfigSchema>;/**- * Resolved ACL as it appears on responses (creator / API-key callers).- * All three fields are populated when the block is visible; the block- * itself is absent for non-creator cookie callers.+ * Resolved ACL as it appears on responses. All three fields are populated+ * when the field is visible; the field itself is `undefined` for callers+ * not authorised to see it.*/export const ConnectedAccountAclConfigResponseSchema = z.object({allowAllUsers: z.boolean(),@@ -211,11 +213,11 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{createdAt: z.string(),updatedAt: z.string(),accountType: ConnectedAccountTypeSchema.optional(),- // `acl_config_for_shared` is only present on responses when the caller is- // the connection's creator or is using a project/org API key. Non-creator- // cookie callers see the row without this block — left as `undefined`- // here so callers can distinguish "I can't see the ACL" from "ACL is the- // default deny-by-default state".+ // `aclConfigForShared` is only present on the response when the caller+ // is authorised to see the ACL — otherwise the block is absent and the+ // field is `undefined`. Callers can distinguish "I can't see the ACL"+ // from "ACL is the default deny-by-default state" by checking for the+ // presence of the field.aclConfigForShared: ConnectedAccountAclConfigResponseSchema.optional(),});@@ -292,11 +294,11 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({*/allowMultiple: z.boolean().optional(),/**- * Sharing model for the new connection. `PRIVATE` (default) is usable only by- * the owning `userId`. `SHARED` is reachable from a tool-router session by- * other users in the project — but only when explicitly pinned and only when- * the requesting `userId` passes the connection's ACL. Set at create time- * only.+ * Sharing model for the new connection. `PRIVATE` (default) is usable only+ * by the owning `userId`. `SHARED` can be used by other `userId`s — but+ * only when the connection is explicitly pinned in a tool-router session's+ * config and only when the requesting `userId` passes the connection's+ * ACL. Set at creation time only.*/accountType: ConnectedAccountTypeSchema.optional(),/**diff --git a/ts/packages/core/src/utils/transformers/connectedAccounts.ts b/ts/packages/core/src/utils/transformers/connectedAccounts.tsindex c831535ca..c4afbd897 100644--- a/ts/packages/core/src/utils/transformers/connectedAccounts.ts+++ b/ts/packages/core/src/utils/transformers/connectedAccounts.ts@@ -18,15 +18,6 @@ type RawConnectedAccountResponseWithLabels = () & {word_id?: string | null;alias?: string | null;- // account_type / acl_config_for_shared are added by Hermes #9860, #9882,- // and the merged #9902. Cast lives here until @composio/client regenerates- // against a backend spec that contains them.- account_type?: 'PRIVATE' | 'SHARED';- acl_config_for_shared?: {- allow_all_users: boolean;- allowed_user_ids: string[];- not_allowed_user_ids: string[];- };};/**@@ -80,11 +71,11 @@ export function transformConnectedAccountResponse(updatedAt: response.updated_at,testRequestEndpoint: response.test_request_endpoint,accountType: responseWithLabels.account_type,- // `acl_config_for_shared` is conditionally visible — backend strips- // the whole block for non-creator/non-API-key callers. Forward- // `undefined` when absent rather than synthesising defaults, so- // callers can distinguish "I can't see the ACL" from "ACL is the- // default deny-by-default state".+ // `acl_config_for_shared` is conditionally visible — the field is+ // absent when the caller isn't authorised to see it. Forward+ // `undefined` rather than synthesising defaults so callers can+ // distinguish "I can't see the ACL" from "ACL is the default+ // deny-by-default state".aclConfigForShared: responseWithLabels.acl_config_for_shared? {allowAllUsers: responseWithLabels.acl_config_for_shared.allow_all_users,diff --git a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.tsindex 45ab3c57f..98c22838e 100644--- a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts+++ b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts@@ -1521,7 +1521,7 @@ describe('ConnectedAccounts', () => {});});- describe('link with accountType + ACL (Hermes #9860, #9902)', () => {+ describe('link with accountType + ACL', () => {beforeEach(() => {extendedMockClient.connectedAccounts.list.mockResolvedValue({items: [],