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(sdk-ts): SEC-339 deprecation warning + typed-error wrap in initiate()
Wrap connectedAccounts.create() to surface 400 BadRequest from the retiring path as ComposioLegacyConnectedAccountsEndpointRetiredError, emit a one-time deprecation warning when the response indicates a redirectable OAuth scheme, and update the JSDoc to flag the cutover. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Composio committed
Apr 25, 2026 at 18:12 UTC
da71fa3313250042fe9fd8385779814b301d654d
1 file changed
+71
-2
ts/packages/core/src/models/ConnectedAccounts.ts
+71
-2
@@ -5,7 +5,7 @@
5
* @date 2025-05-05
6
* @module ConnectedAccounts
7
*/
8
-import ComposioClient from '@composio/client';
8
+import ComposioClient, { BadRequestError } from '@composio/client';
9
import {
10
ConnectedAccountDeleteResponse,
11
ConnectedAccountRefreshParams,
@@ -39,10 +39,21 @@ import {
39
} from '../utils/transformers/connectedAccounts';
40
import {
41
ComposioFailedToCreateConnectedAccountLink,
42
+ ComposioLegacyConnectedAccountsEndpointRetiredError,
43
ComposioMultipleConnectedAccountsError,
44
} from '../errors';
45
import logger from '../utils/logger';
46
import { ConnectionData } from '../types/connectedAccountAuthStates.types';
47
+
48
+// SEC-339: schemes that take the redirectable OAuth path on the legacy
49
+// `POST /api/v3/connected_accounts` endpoint, and so are subject to the
50
+// 2026-05-08 / 2026-07-03 retirement when the auth config is Composio-managed.
51
+const LEGACY_RETIRING_OAUTH_SCHEMES = new Set(['OAUTH1', 'OAUTH2', 'DCR_OAUTH']);
52
+
53
+// One-time-per-process guard so long-running services don't spam the deprecation
54
+// warning on every initiate() call.
55
+let _legacyInitiateWarningEmitted = false;
56
+
57
/**
58
* ConnectedAccounts class
59
*
@@ -111,6 +122,22 @@ export class ConnectedAccounts {
122
* This function creates a new connected account and returns a connection request.
123
* Users can then wait for the connection to be established using the `waitForConnection` method.
124
*
125
+ * **Deprecated for Composio-managed OAuth (OAuth1, OAuth2, DCR_OAUTH).**
126
+ * The legacy `POST /api/v3/connected_accounts` endpoint that this method
127
+ * wraps is being retired for Composio-managed auth configs on redirectable
128
+ * schemes. The cutover is **2026-05-08** for new organizations and
129
+ * **2026-07-03** for all remaining organizations. After your org's cutover,
130
+ * this method will throw {@link ComposioLegacyConnectedAccountsEndpointRetiredError}
131
+ * for that specific combination.
132
+ *
133
+ * Use {@link ConnectedAccounts.link} for Composio-managed OAuth — it works for
134
+ * every redirectable scheme regardless of whether the auth config is
135
+ * Composio-managed or custom, and the return shape is the same.
136
+ *
137
+ * Custom auth configs (your own OAuth app) and non-OAuth schemes (API key,
138
+ * bearer token, basic auth) are unaffected and continue to work on
139
+ * `initiate()`. See https://docs.composio.dev/docs/changelog/2026/04/24
140
+ *
141
* @param {string} userId - User ID of the connected account
142
* @param {string} authConfigId - Auth config ID of the connected account
143
* @param {CreateConnectedAccountOptions} options - Options for creating a new connected account
@@ -201,7 +228,49 @@ export class ConnectedAccounts {
228
},
229
};
230
204
- const response = await this.client.connectedAccounts.create(createParams);
231
+ let response;
232
+ try {
233
+ response = await this.client.connectedAccounts.create(createParams);
234
+ } catch (error) {
235
+ // SEC-339: When the server has flipped this org to the retired path,
236
+ // the legacy endpoint returns 400 with a stable migration message.
237
+ // Surface it as a typed error so callers get an actionable hint instead
238
+ // of a generic BadRequestError.
239
+ if (
240
+ error instanceof BadRequestError &&
241
+ typeof error.message === 'string' &&
242
+ error.message.includes('no longer supported') &&
243
+ error.message.includes('/api/v3/connected_accounts/link')
244
+ ) {
245
+ throw new ComposioLegacyConnectedAccountsEndpointRetiredError(error.message, {
246
+ cause: error,
247
+ });
248
+ }
249
+ throw error;
250
+ }
251
+
252
+ // SEC-339: Warn once per process when a successful initiate() lands on
253
+ // the redirectable-OAuth path. We can't tell from the response alone
254
+ // whether the auth config is Composio-managed (the field that determines
255
+ // whether the cutover applies), so the warning text is conditional in
256
+ // wording — custom-OAuth users can ignore it, Composio-managed-OAuth
257
+ // users see a clear pointer to link() before their org's cutover lands.
258
+ const responseAuthScheme = response.connectionData?.authScheme;
259
+ if (
260
+ !_legacyInitiateWarningEmitted &&
261
+ typeof responseAuthScheme === 'string' &&
262
+ LEGACY_RETIRING_OAUTH_SCHEMES.has(responseAuthScheme)
263
+ ) {
264
+ _legacyInitiateWarningEmitted = true;
265
+ logger.warn(
266
+ '[Deprecation] composio.connectedAccounts.initiate() will stop ' +
267
+ 'working for Composio-managed OAuth auth configs on 2026-05-08 ' +
268
+ '(new orgs) and 2026-07-03 (all orgs). If this auth config is ' +
269
+ 'Composio-managed, switch to composio.connectedAccounts.link() ' +
270
+ 'before then. Custom auth configs are unaffected. See ' +
271
+ 'https://docs.composio.dev/docs/changelog/2026/04/24'
272
+ );
273
+ }
274
275
const redirectUrl =
276
typeof response.connectionData?.val?.redirectUrl === 'string'