@devries-cameron20 / composio Mirror · read-only / commits / 2e1c25eb7
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 22:15 UTC

feat(sdk,docs): SEC-339 link-auth migration support across SDK + docs (#3289)

## Summary End-to-end work to help SDK and direct API users move off the legacy `POST /api/v3/connected_accounts` path for **Composio-managed OAuth** ahead of the [2026-04-24 changelog announcement](/docs/changelog/2026/04/24) — cutover dates **2026-05-08** (new orgs) and **2026-07-03** (all orgs). Pairs with the backend deprecation signals in [ComposioHQ/hermes#9622](https://github.com/ComposioHQ/hermes/pull/9622). Custom auth configs (your own OAuth app) and non-OAuth schemes (API key, bearer, basic) are unaffected throughout. ## SDK changes ### TypeScript (`@composio/core`) - **New error class** `ComposioLegacyConnectedAccountsEndpointRetiredError` in `errors/ConnectedAccountsErrors.ts` — extends `ComposioError`, status 400, with `possibleFixes` pre-populated to point at `link()` and the migration guide. - **`initiate()` wraps the create call** in try/catch and re-throws the new typed error when the response message indicates the retiring path. The match is conservative — substring on stable backend message text, with everything else flowing through unchanged. - **One-time-per-process deprecation warning** via `logger.warn` when the response indicates `OAUTH1` / `OAUTH2` / `DCR_OAUTH`. Wording is conditional ("If this auth config is Composio-managed...") so custom-OAuth users can ignore it without ambiguity. - **JSDoc** on `initiate()` flags the deprecation explicitly with both cutover dates and a link to the migration guide. ### Python (`composio` core) - Mirror exception class `ComposioLegacyConnectedAccountsEndpointRetiredError` in `composio/exceptions.py`. - `initiate()` catches `BadRequestError` from `composio_client`, inspects the message text, and re-raises as the typed exception (preserves `__cause__`). - One-time-per-process `warnings.warn(..., DeprecationWarning, stacklevel=2)` on the redirectable-OAuth response path. - Docstring carries a `.. deprecated::` block with the dates. ## Doc changes | File | Change | |---|---| | `docs/content/docs/tools-direct/authenticating-tools.mdx` | Add a `<Callout type="warn">` to the `OAuth Connections` subsection of `Direct SDK Setup`. The Hosted Authentication section already shows `link()` first; this surfaces the retirement on the `initiate()` subsection where readers most need it. | | `docs/content/docs/auth-configuration/connected-accounts.mdx` | Promote the `Multiple accounts` callout from `info` to `warn`, pin the cutover dates, and route readers to the migration guide. | | `docs/content/docs/auth-configuration/custom-auth-configs.mdx` | Add an `info` callout clarifying that the `initiate()` example shown is *intentionally* fine here (custom auth configs are exempt). Avoids copy-paste confusion. | | `docs/content/reference/errors.mdx` | New section `## Specific error codes` → `### Error 600` with anchor `#error-600`. The `suggested_fix` URL emitted by the backend in the 400 response (`/reference/errors#error-600`) now resolves to real content instead of 404'ing. | | `docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx` | **New page.** Dedicated migration guide. Side-by-side before/after for both languages, the `allow_multiple` replacement pattern, an `is_composio_managed` routing recipe for mixed integrations, notes on detecting the deprecation via SDK warning vs RFC 8594 response headers, and a transition-friendly try/except example. | | `docs/content/docs/auth-configuration/meta.json` | Wire the new migration guide into the Authentication sidebar. | ## Why this scope In the audit before this PR the SDK was the biggest gap — `composio.connectedAccounts.initiate()` (TS) and `composio.connected_accounts.initiate()` (Python) both call the legacy endpoint, so every doc that teaches `initiate()` for OAuth was teaching a path that breaks at cutover. The SDK changes give existing users a typed deprecation path (warning before cutover, typed error after) without forcing a behavior change on the custom-auth-config and non-OAuth users who are unaffected. The doc changes target the two highest-traffic teaching pages for OAuth flows, plug the broken `error-600` URL the backend already references, and add a focused migration guide that consolidates everything callers need. ## How did I test this PR - **TS**: `pnpm tsc --noEmit` in `ts/packages/core` — error count unchanged vs `next` (baseline 53 → 53; all pre-existing, none touch the modified files). The new error class follows the existing `ComposioFailedToCreateConnectedAccountLink` template; the typed-error wrap reuses the `BadRequestError` import and pattern from `errors/ComposioError.ts:13`. - **Python**: confirmed `BadRequestError` is exported from `composio_client` and `connection_data.auth_scheme` is a valid attribute on the response model (`composio_client.types.connected_account_create_response.ConnectionDataUnionMember0` declares `auth_scheme: Literal["OAUTH1"] = FieldInfo(alias="authScheme")` — same shape across all union members). - **Docs**: all internal links use the relative-path convention (`/docs/...`, `/reference/...`) and follow the format used by existing changelog cross-links (e.g., `/docs/changelog/2026/04/24`). The new `#error-600` anchor matches the URL the backend's `suggested_fix` already emits. - **Manual trace**: walked the four decision branches against the modified `initiate()` code paths in both languages — custom auth configs and non-OAuth schemes never trigger either the warning or the typed-error path; managed OAuth triggers the warning on success and the typed error on the eventual 400. Pre-cutover the SDK warning is the loudest signal; post-cutover the typed error is the cleanest catch point. Both are scoped strictly to the affected combination.

lingalarahul7 committed May 5, 2026 at 16:15 UTC 2e1c25eb7fce053e70f7d2a76d432f6ae723cb62

No changes.