@cosmoops/connect-sdk 0.46.0 → 0.47.0

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.47.0
+
+### `connect.integrations.request()` reaches the endpoints a toolkit has no action for
+
+A Composio toolkit's action catalogue is not the provider's API: Zoho Books
+ships no action to create a sales order, an estimate or an invoice.
+`integrations.request(workspaceId, { toolkitSlug, method, endpoint, query, body })`
+sends one request to the provider through the workspace's connected account,
+under the `integrations:execute` scope - Connect still holds the credential.
+
+`endpoint` is a path relative to the provider's API base (`/salesorders`).
+Connect refuses an absolute URL, a query string in the path and dot segments,
+and there is no way to set a header: whoever chooses the host chooses where
+the credential goes. The call resolves whenever Connect relayed it - read the
+provider's own `status` and `data` from the result.
+
+### `initiateConnect` takes `connectionData`
+
+Pre-fills a toolkit's own connection fields on the provider's screen.
+`{ extension: "in" }` puts a Zoho connection on the India data centre, which
+otherwise defaults to `zoho.com`.
+
+### A 503 without `Retry-After` is no longer retried
+
+The SDK retried every 503 on an idempotent request, twice, sleeping the
+server's `Retry-After` between. Connect now leaves that header off a 503 it
+knows will not heal - a dependency rejecting Connect's own credential, such
+as the provider behind `connect.integrations.list()` - and the SDK now takes
+that at its word: no `Retry-After`, no retry, and `ConnectError.isRetryable`
+is `false`. A misconfigured dependency used to cost every read three round
+trips and about four seconds of sleeping to return the same error. Every 503
+Connect means to be retried still carries the header, so nothing that
+recovers today stops recovering.
+
 ## 0.46.0
 
 ### `secondary` buttons are soft indigo

package/dist/cjs/client/portal-links.js

@@ -11,7 +11,7 @@ const provider_js_1 = require("./provider.js");
  *
  * Connect answers any of these paths for a signed-in user on the bare URL -
  * these two params only add the `"Back to <your app>"` banner
- * (`ApplicationReturnBar` on Connect's side). It validates `return_to`
+ * (the hand-off strip in `ShellAnnouncements` on Connect's side). It validates `return_to`
  * against this `client_id`'s registered redirect origins and silently drops
  * the banner if they don't match, so a wrong or stale `appUrl`/`clientId`
  * pairing degrades to what linking there did before rather than erroring.

package/dist/cjs/errors.js

@@ -37,8 +37,17 @@ class ConnectError extends Error {
      * already retries these internally (see `ConnectClientOptions.maxRetries`);
      * this is for callers deciding whether to queue their own retry after the
      * SDK has given up.
+     *
+     * **A 503 is retryable only when it carries `Retry-After`.** Connect sends
+     * that header on every 503 it means to be retried - a dependency blip, a
+     * contended transaction - and leaves it off when the dependency is
+     * *misconfigured* (a revoked provider key, say), where every retry gets the
+     * identical answer. Retrying those anyway cost a page three round trips and
+     * two sleeps per read to learn nothing.
      */
     get isRetryable() {
+        if (this.status === 503)
+            return this.retryAfterMs !== null;
         return this.status === 0 || this.status === 429 || this.status >= 500;
     }
     /**

package/dist/cjs/server/client.js

@@ -183,4 +183,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.46.0";
+exports.SDK_VERSION = "0.47.0";

package/dist/cjs/server/http.js

@@ -189,7 +189,10 @@ async function request(options, spec) {
                 return (await readBody(response));
             }
             lastError = toConnectError(response, await readBody(response), endpoint);
-            if (!RETRYABLE_STATUS.has(response.status))
+            // The status decides, and then the error's own verdict - which is what
+            // keeps a 503 sent without `Retry-After` from being replayed. See
+            // `ConnectError.isRetryable`.
+            if (!RETRYABLE_STATUS.has(response.status) || !lastError.isRetryable)
                 throw lastError;
         }
         finally {

package/dist/cjs/server/resources/integrations.js

@@ -56,6 +56,22 @@ class IntegrationsResource {
             json: { workspaceId, toolkitSlug },
         });
     }
+    /**
+     * One raw request to a connected provider's own API, for an endpoint the
+     * toolkit has no action for (Zoho Books ships no "create sales order").
+     *
+     * **Resolves whenever Connect relayed the request**, whatever the provider
+     * answered: read `status` and `data` for that. A provider-side 4xx is a
+     * business answer ("that GSTIN is invalid") rather than a transport
+     * failure, so it is not thrown as one.
+     */
+    async request(workspaceId, input) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "POST",
+            path: "/integrations/proxy",
+            json: { workspaceId, ...input },
+        });
+    }
     /** Calls a Composio action against this workspace's connected account for the named toolkit. */
     async execute(workspaceId, input) {
         return (0, http_js_1.request)(this.transport, {

package/dist/cjs/server/resources/workspaces.js

@@ -113,11 +113,20 @@ class WorkspacesResource {
      * Connect roles - so you never reimplement Connect's role resolution, and
      * you are told nothing about the customer's Connect account beyond what your
      * application needs.
+     *
+     * **Seat holders only, by default.** A workspace member with no seat on your
+     * application cannot sign in to it, so they are not part of your team and
+     * do not belong in an owner picker or an assignee list. Pass
+     * `includeUnassigned: true` from the screen where an admin *gives* a seat -
+     * it needs the people who do not have one yet. That form needs the signed-in
+     * member to be able to change access (a 403 otherwise), and every row
+     * carries `assigned` so the screen can tell the two apart.
      */
     async members(options) {
         const result = await (0, http_js_1.request)(this.transport, {
             method: "GET",
             path: "/workspaces/members",
+            query: { include: options.includeUnassigned ? "unassigned" : undefined },
             headers: (0, acting_as_js_1.actingAs)(options.asUser),
         });
         return result.members;

package/dist/esm/client/portal-links.js

@@ -7,7 +7,7 @@ import { useConnect } from "./provider.js";
  *
  * Connect answers any of these paths for a signed-in user on the bare URL -
  * these two params only add the `"Back to <your app>"` banner
- * (`ApplicationReturnBar` on Connect's side). It validates `return_to`
+ * (the hand-off strip in `ShellAnnouncements` on Connect's side). It validates `return_to`
  * against this `client_id`'s registered redirect origins and silently drops
  * the banner if they don't match, so a wrong or stale `appUrl`/`clientId`
  * pairing degrades to what linking there did before rather than erroring.

package/dist/esm/errors.js

@@ -33,8 +33,17 @@ export class ConnectError extends Error {
      * already retries these internally (see `ConnectClientOptions.maxRetries`);
      * this is for callers deciding whether to queue their own retry after the
      * SDK has given up.
+     *
+     * **A 503 is retryable only when it carries `Retry-After`.** Connect sends
+     * that header on every 503 it means to be retried - a dependency blip, a
+     * contended transaction - and leaves it off when the dependency is
+     * *misconfigured* (a revoked provider key, say), where every retry gets the
+     * identical answer. Retrying those anyway cost a page three round trips and
+     * two sleeps per read to learn nothing.
      */
     get isRetryable() {
+        if (this.status === 503)
+            return this.retryAfterMs !== null;
         return this.status === 0 || this.status === 429 || this.status >= 500;
     }
     /**

package/dist/esm/server/client.js

@@ -179,4 +179,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.46.0";
+export const SDK_VERSION = "0.47.0";

package/dist/esm/server/http.js

@@ -184,7 +184,10 @@ export async function request(options, spec) {
                 return (await readBody(response));
             }
             lastError = toConnectError(response, await readBody(response), endpoint);
-            if (!RETRYABLE_STATUS.has(response.status))
+            // The status decides, and then the error's own verdict - which is what
+            // keeps a 503 sent without `Retry-After` from being replayed. See
+            // `ConnectError.isRetryable`.
+            if (!RETRYABLE_STATUS.has(response.status) || !lastError.isRetryable)
                 throw lastError;
         }
         finally {

package/dist/esm/server/resources/integrations.js

@@ -53,6 +53,22 @@ export class IntegrationsResource {
             json: { workspaceId, toolkitSlug },
         });
     }
+    /**
+     * One raw request to a connected provider's own API, for an endpoint the
+     * toolkit has no action for (Zoho Books ships no "create sales order").
+     *
+     * **Resolves whenever Connect relayed the request**, whatever the provider
+     * answered: read `status` and `data` for that. A provider-side 4xx is a
+     * business answer ("that GSTIN is invalid") rather than a transport
+     * failure, so it is not thrown as one.
+     */
+    async request(workspaceId, input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/integrations/proxy",
+            json: { workspaceId, ...input },
+        });
+    }
     /** Calls a Composio action against this workspace's connected account for the named toolkit. */
     async execute(workspaceId, input) {
         return request(this.transport, {

package/dist/esm/server/resources/workspaces.js

@@ -110,11 +110,20 @@ export class WorkspacesResource {
      * Connect roles - so you never reimplement Connect's role resolution, and
      * you are told nothing about the customer's Connect account beyond what your
      * application needs.
+     *
+     * **Seat holders only, by default.** A workspace member with no seat on your
+     * application cannot sign in to it, so they are not part of your team and
+     * do not belong in an owner picker or an assignee list. Pass
+     * `includeUnassigned: true` from the screen where an admin *gives* a seat -
+     * it needs the people who do not have one yet. That form needs the signed-in
+     * member to be able to change access (a 403 otherwise), and every row
+     * carries `assigned` so the screen can tell the two apart.
      */
     async members(options) {
         const result = await request(this.transport, {
             method: "GET",
             path: "/workspaces/members",
+            query: { include: options.includeUnassigned ? "unassigned" : undefined },
             headers: actingAs(options.asUser),
         });
         return result.members;

package/dist/types/client/components/call-button.d.ts

@@ -25,7 +25,9 @@ import type { CallingAvailability } from "../../types.js";
  *    a number and the member must have "Make calls". What comes back lets this
  *    browser place exactly this call and no other.
  * 3. The browser places it. Connect dials the number from the workspace's own
- *    number; nothing is recorded.
+ *    number. It is recorded only when the workspace has turned recording on
+ *    (`connect.calls.getCallSettings`), and then the other party hears a
+ *    disclosure before the conversation starts.
  *
  * ## Logging a call
  *

package/dist/types/client/portal-links.d.ts

@@ -5,7 +5,7 @@
  *
  * Connect answers any of these paths for a signed-in user on the bare URL -
  * these two params only add the `"Back to <your app>"` banner
- * (`ApplicationReturnBar` on Connect's side). It validates `return_to`
+ * (the hand-off strip in `ShellAnnouncements` on Connect's side). It validates `return_to`
  * against this `client_id`'s registered redirect origins and silently drops
  * the banner if they don't match, so a wrong or stale `appUrl`/`clientId`
  * pairing degrades to what linking there did before rather than erroring.

package/dist/types/errors.d.ts

@@ -34,6 +34,13 @@ export declare class ConnectError extends Error {
      * already retries these internally (see `ConnectClientOptions.maxRetries`);
      * this is for callers deciding whether to queue their own retry after the
      * SDK has given up.
+     *
+     * **A 503 is retryable only when it carries `Retry-After`.** Connect sends
+     * that header on every 503 it means to be retried - a dependency blip, a
+     * contended transaction - and leaves it off when the dependency is
+     * *misconfigured* (a revoked provider key, say), where every retry gets the
+     * identical answer. Retrying those anyway cost a page three round trips and
+     * two sleeps per read to learn nothing.
      */
     get isRetryable(): boolean;
     /**

package/dist/types/server/client.d.ts

@@ -141,4 +141,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.46.0";
+export declare const SDK_VERSION = "0.47.0";

package/dist/types/server/index.d.ts

@@ -26,7 +26,7 @@ export type { OtpResource } from "./resources/otp.js";
 export type { LogsResource } from "./resources/logs.js";
 export type { AnalyticsResource } from "./resources/analytics.js";
 export type { SessionsResource } from "./resources/sessions.js";
-export type { ExecuteIntegrationActionInput, InitiateIntegrationConnectionInput, IntegrationsResource, } from "./resources/integrations.js";
+export type { ExecuteIntegrationActionInput, InitiateIntegrationConnectionInput, IntegrationsResource, ProxyIntegrationRequestInput, } from "./resources/integrations.js";
 export type { PlatformResource } from "./resources/platform.js";
 export type { SchedulingResource, FindSlotsInput, ListBookingsInput, CreateBookingInput, RescheduleBookingInput, } from "./resources/scheduling.js";
 export type { ContactsResource, LookupContactInput } from "./resources/contacts.js";

package/dist/types/server/resources/integrations.d.ts

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { DisconnectIntegrationResponse, ExecuteIntegrationActionResponse, InitiateIntegrationConnectionResponse, IntegrationsListResponse } from "../../types.js";
+import type { DisconnectIntegrationResponse, ExecuteIntegrationActionResponse, InitiateIntegrationConnectionResponse, IntegrationProxyMethod, IntegrationsListResponse, ProxyIntegrationRequestResponse } from "../../types.js";
 export interface InitiateIntegrationConnectionInput {
     toolkitSlug: string;
     returnUrl: string;
@@ -13,6 +13,13 @@ export interface InitiateIntegrationConnectionInput {
      * is present to finish the OAuth screen either.
      */
     userId: string;
+    /**
+     * Pre-fills the toolkit's own connection fields on the provider screen -
+     * `{ extension: "in" }` puts a Zoho connection on the India data centre,
+     * which otherwise defaults to `zoho.com`. Which keys a toolkit reads is
+     * Composio's catalogue; Connect passes them through.
+     */
+    connectionData?: Record<string, string>;
 }
 export interface ExecuteIntegrationActionInput {
     toolkitSlug: string;
@@ -20,6 +27,21 @@ export interface ExecuteIntegrationActionInput {
     /** Passed through to Composio verbatim - its shape is defined by the toolkit's own action schema, which Connect does not model. */
     params?: Record<string, unknown>;
 }
+export interface ProxyIntegrationRequestInput {
+    toolkitSlug: string;
+    method: IntegrationProxyMethod;
+    /**
+     * A path relative to the provider's API base - `/salesorders`, not a URL.
+     * Connect refuses anything with a scheme, a host, a `?` or a dot segment,
+     * because whoever picks the host picks where the workspace's credential
+     * goes. Parameters belong in `query`.
+     */
+    endpoint: string;
+    query?: Record<string, string>;
+    body?: unknown;
+    /** Whose connection to act through - omitted or `null` for the workspace's shared one. */
+    onBehalfOfUserId?: string | null;
+}
 /**
  * Composio-hosted third-party connections (Google Calendar, Slack,
  * Twitter/X, ...) a workspace has connected. Connect proxies every call
@@ -51,6 +73,16 @@ export declare class IntegrationsResource {
     initiateConnect(workspaceId: string, input: InitiateIntegrationConnectionInput): Promise<InitiateIntegrationConnectionResponse>;
     /** Idempotent - disconnecting a toolkit that was never connected, or is already disconnected, is a success. */
     disconnect(workspaceId: string, toolkitSlug: string): Promise<DisconnectIntegrationResponse>;
+    /**
+     * One raw request to a connected provider's own API, for an endpoint the
+     * toolkit has no action for (Zoho Books ships no "create sales order").
+     *
+     * **Resolves whenever Connect relayed the request**, whatever the provider
+     * answered: read `status` and `data` for that. A provider-side 4xx is a
+     * business answer ("that GSTIN is invalid") rather than a transport
+     * failure, so it is not thrown as one.
+     */
+    request(workspaceId: string, input: ProxyIntegrationRequestInput): Promise<ProxyIntegrationRequestResponse>;
     /** Calls a Composio action against this workspace's connected account for the named toolkit. */
     execute(workspaceId: string, input: ExecuteIntegrationActionInput): Promise<ExecuteIntegrationActionResponse>;
 }

package/dist/types/server/resources/workspaces.d.ts

@@ -104,9 +104,18 @@ export declare class WorkspacesResource {
      * Connect roles - so you never reimplement Connect's role resolution, and
      * you are told nothing about the customer's Connect account beyond what your
      * application needs.
+     *
+     * **Seat holders only, by default.** A workspace member with no seat on your
+     * application cannot sign in to it, so they are not part of your team and
+     * do not belong in an owner picker or an assignee list. Pass
+     * `includeUnassigned: true` from the screen where an admin *gives* a seat -
+     * it needs the people who do not have one yet. That form needs the signed-in
+     * member to be able to change access (a 403 otherwise), and every row
+     * carries `assigned` so the screen can tell the two apart.
      */
     members(options: {
         asUser: string;
+        includeUnassigned?: boolean;
     }): Promise<ConnectWorkspaceMember[]>;
     /**
      * Seats, what the caller may do with them, and the invitations already

package/dist/types/types.d.ts

@@ -1052,6 +1052,12 @@ export interface ExecuteIntegrationActionResponse {
     data: unknown;
     successful: boolean;
 }
+export type IntegrationProxyMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** See `IntegrationsResource.request` - `status` is the provider's, not Connect's. */
+export interface ProxyIntegrationRequestResponse {
+    status: number;
+    data: unknown;
+}
 /**
  * The metrics Connect can report for your application.
  *
@@ -1912,6 +1918,12 @@ export interface ConnectWorkspaceMember {
      */
     memberId: string;
     userId: string;
+    /**
+     * Whether this member holds a seat on your application. Only assigned
+     * members can sign in to it; unassigned rows appear only when you asked
+     * for them with `members({ includeUnassigned: true })`, to assign from.
+     */
+    assigned: boolean;
     email: string;
     displayName: string | null;
     photoUrl: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",