@cosmoops/connect-sdk 0.6.0 → 0.9.0

package/dist/types/client/use-checkout.d.ts

@@ -57,7 +57,7 @@ export declare function useConnectCheckout(): ConnectCheckoutState & {
 export interface CheckoutUrlOptions {
     /** Connect's origin, from `useConnect().appUrl`. */
     appUrl: string;
-    serviceId: string;
+    applicationId: string;
     planId: string;
     /**
      * The live subscription's id, when there is one. Present means "change the
@@ -85,9 +85,9 @@ export declare function buildCancelUrl({ appUrl, subscriptionId }: {
  * The Connect URL that completes a subscribe or a plan change.
  *
  * Both land on a modal Connect renders over the relevant page (an intercepted
- * parallel route - `app/@modal/(.)services/...` and
+ * parallel route - `app/@modal/(.)applications/...` and
  * `app/@modal/(.)billing/...`), so the customer arrives already looking at the
  * confirmation for the plan they picked here, not at a catalogue they have to
  * find it in again.
  */
-export declare function buildCheckoutUrl({ appUrl, serviceId, planId, subscriptionId, coupon, }: CheckoutUrlOptions): string;
+export declare function buildCheckoutUrl({ appUrl, applicationId, planId, subscriptionId, coupon, }: CheckoutUrlOptions): string;

package/dist/types/errors.d.ts

@@ -1,8 +1,8 @@
 /**
- * Every failure the Connect service API can report, as one class.
+ * Every failure the Connect application API can report, as one class.
  *
  * The API speaks two error dialects and this collapses them: the
- * `/api/v1/service/*` endpoints use `{ error: { code, message } }`, while the
+ * `/api/v1/application/*` endpoints use `{ error: { code, message } }`, while the
  * three `/sso/*` ones use OAuth2's `{ error, error_description }` (RFC 6749
  * §5.2). Both land here with `code` populated, so integrating code branches on
  * one field either way.
@@ -40,7 +40,7 @@ export declare class ConnectError extends Error {
      * Whether the user's Connect sign-in is over and they need to go back
      * through `identity.authorizeUrl()`. Collapses every session-side failure,
      * matching how the API reports them - unknown, expired, revoked, or issued
-     * to a different service all arrive as one `invalid_token`.
+     * to a different application all arrive as one `invalid_token`.
      */
     get isSessionExpired(): boolean;
     /**
@@ -52,7 +52,7 @@ export declare class ConnectError extends Error {
      * guessing keys. These two are the exception: reaching them required
      * presenting a key whose hash matched, so you already hold it, and what you
      * need to know is that no retry and no scope change will fix this - the key
-     * has to be reissued from the service's Integration tab.
+     * has to be reissued from the application's Integration tab.
      *
      * Worth alerting on. It is the one failure that will not resolve itself and
      * takes down every call your integration makes.

package/dist/types/helpers.d.ts

@@ -21,7 +21,7 @@ export type WirePlanFeature = string | PlanFeature;
  * Coerces either wire shape into `PlanFeature[]`.
  *
  * A bare key becomes `{ key, name: key, description: "" }` - the same
- * fallback the server applies for a plan older than its service's feature
+ * fallback the server applies for a plan older than its application's feature
  * catalog, so an un-upgraded Connect renders exactly what it always did
  * rather than a column of blanks.
  *

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * `@cosmoops/connect-sdk` - the official client for the CosmoOps Connect
- * **service-partner API** (`/api/v1/service/*`).
+ * **application-partner API** (`/api/v1/application/*`).
  *
  * This root entry is the isomorphic surface: wire types, the error class, and
  * pure helpers. It pulls in neither Node-only code nor React, so it is safe to

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

@@ -125,7 +125,7 @@ export declare function getConnectSession(request?: Request, options?: {
  * A thin wrapper, not a framework of its own - reach for `getConnectSession`
  * plus your own check when "not signed in" isn't "redirect to sign-in"
  * (an API route returning 401, say). Role and entitlement checks stay
- * outside this function on purpose: `session.serviceRole.granted` and
+ * outside this function on purpose: `session.applicationRole.granted` and
  * `connect.entitlements.*` are one line each on top of the session this
  * already gives you, and where that line redirects (a plans page, a
  * "forbidden" screen) is a decision only your app can make - see

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

@@ -14,7 +14,7 @@ import { SessionsResource } from "./resources/sessions.js";
 export declare const DEFAULT_BASE_URL = "https://connect.cosmoops.com";
 export interface ConnectClientOptions {
     /**
-     * The API key plaintext from this service's Integration tab, shown once at
+     * The API key plaintext from this application's Integration tab, shown once at
      * creation.
      *
      * One credential does three jobs: it is the `Authorization: Bearer` value
@@ -39,9 +39,9 @@ export interface ConnectClientOptions {
     fetch?: FetchLike;
 }
 /**
- * The CosmoOps Connect service-partner API.
+ * The CosmoOps Connect application-partner API.
  *
- * Covers `/api/v1/service/*` and nothing else - the surface a service platform
+ * Covers `/api/v1/application/*` and nothing else - the surface an application platform
  * integrates against. Connect's internal API is not part of this package and
  * never will be.
  *
@@ -52,7 +52,7 @@ export interface ConnectClientOptions {
  * });
  *
  * const session = await connect.identity.exchangeCode({ code, redirectUri });
- * const { ready } = await connect.entitlements.getReadiness(session.user.organizationId);
+ * const { ready } = await connect.entitlements.getReadiness(session.user.workspaceId);
  * ```
  *
  * Every failure throws a `ConnectError` carrying a stable `code`. Nothing here
@@ -61,29 +61,29 @@ export interface ConnectClientOptions {
 export declare class ConnectClient {
     /** "Login with Connect" - the OAuth2 handshake and the session after it. */
     readonly identity: IdentityResource;
-    /** What a signed-in member may do on your service. */
+    /** What a signed-in member may do on your application. */
     readonly access: AccessResource;
-    /** The services an organization can open - for a launcher grid. */
+    /** The applications a workspace can open - for a launcher grid. */
     readonly apps: AppsResource;
-    /** Whether a workspace may use your service, and on what plan. */
+    /** Whether a workspace may use your application, and on what plan. */
     readonly entitlements: EntitlementsResource;
     /** Your plan catalog, and metering usage against add-on balances. */
     readonly billing: BillingResource;
-    /** Files in an organization's Drive. */
+    /** Files in a workspace's Drive. */
     readonly drive: DriveResource;
     /** RAG chat and structured extraction. */
     readonly ai: AiResource;
     /** WhatsApp/SMS phone verification. */
     readonly otp: OtpResource;
-    /** Feature events into the Console's audit log, filterable to your service. */
+    /** Feature events into the Console's audit log, filterable to your application. */
     readonly logs: LogsResource;
-    /** Emit product events and read back this service's aggregated numbers. */
+    /** Emit product events and read back this application's aggregated numbers. */
     readonly analytics: AnalyticsResource;
-    /** This Connect account's own login sessions - account-wide, not scoped to this service. Requires the `sessions:manage` scope. */
+    /** This Connect account's own login sessions - account-wide, not scoped to this application. Requires the `sessions:manage` scope. */
     readonly sessions: SessionsResource;
-    /** Composio-hosted third-party connections (Google Calendar, Slack, ...) an organization has connected. */
+    /** Composio-hosted third-party connections (Google Calendar, Slack, ...) a workspace has connected. */
     readonly integrations: IntegrationsResource;
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.9.0";

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

@@ -59,9 +59,9 @@ export interface ConnectHandlerOptions {
  * export { handler as GET, handler as POST };
  * ```
  *
- * Every route resolves the organization from the caller's *own* session, never
+ * Every route resolves the workspace from the caller's *own* session, never
  * from a query parameter. A browser must not be able to ask about an
- * organization it is not signed into, and a client-supplied `organizationId`
+ * workspace it is not signed into, and a client-supplied `workspaceId`
  * is exactly that hole.
  */
 export declare function createConnectHandler(options: ConnectHandlerOptions): (request: Request) => Promise<Response>;

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

@@ -12,7 +12,12 @@ export interface RequestSpec {
     headers?: Record<string, string>;
     /** Bearer API key (default), or none - the `/sso/*` endpoints authenticate inside the form body instead. */
     auth?: "bearer" | "none";
-    /** Skip JSON parsing and hand back the raw `Response` - for streaming endpoints. */
+    /**
+     * Skip JSON parsing and hand back the raw `Response` - for streaming
+     * endpoints.
+     *
+     * Also stops `timeoutMs` from applying to the *body*: see `request`.
+     */
     raw?: boolean;
     signal?: AbortSignal;
 }

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

@@ -1,6 +1,6 @@
 import { type TransportOptions } from "../http.js";
 import type { RolesResponse, UserRolesResponse } from "../../types.js";
-/** What a signed-in member may do on your service, and the role catalog behind it. */
+/** What a signed-in member may do on your application, and the role catalog behind it. */
 export declare class AccessResource {
     private readonly transport;
     constructor(transport: TransportOptions);
@@ -10,8 +10,8 @@ export declare class AccessResource {
      * and already know who the user is.
      */
     getUserRoles(userId: string, input: {
-        organizationId: string;
+        workspaceId: string;
     }): Promise<UserRolesResponse>;
-    /** Your service's own permission catalog and role definitions - the definitions `getUserRoles` resolves against. */
+    /** Your application's own permission catalog and role definitions - the definitions `getUserRoles` resolves against. */
     listRoles(): Promise<RolesResponse>;
 }

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

@@ -1,6 +1,6 @@
 import { type TransportOptions } from "../http.js";
 import type { ChatMessage } from "../../types.js";
-/** RAG chat and structured extraction against an organization's data. */
+/** RAG chat and structured extraction against a workspace's data. */
 export declare class AiResource {
     private readonly transport;
     constructor(transport: TransportOptions);
@@ -11,7 +11,7 @@ export declare class AiResource {
      * `response.body` onward, or hand it to the AI SDK's own reader.
      */
     chat(input: {
-        organizationId: string;
+        workspaceId: string;
         messages: ChatMessage[];
     }, options?: {
         signal?: AbortSignal;

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

@@ -1,10 +1,10 @@
 import { type TransportOptions } from "../http.js";
 import type { AnalyticsQuery, AnalyticsResponse, EmitEventInput, EmitEventsResponse } from "../../types.js";
 /**
- * Your service's own analytics: emit product events, and read back the daily
+ * Your application's own analytics: emit product events, and read back the daily
  * numbers Connect aggregates from them.
  *
- * There is no way to name a service in either call. The scope is always the one
+ * There is no way to name an application in either call. The scope is always the one
  * your API key belongs to - that is the endpoint's security model, not an
  * omission.
  */

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

@@ -1,12 +1,12 @@
 import { type TransportOptions } from "../http.js";
-import type { OrganizationApp } from "../../types.js";
-/** The services an organization can open - the data behind a launcher grid. */
+import type { WorkspaceApp } from "../../types.js";
+/** The applications a workspace can open - the data behind a launcher grid. */
 export declare class AppsResource {
     private readonly transport;
     constructor(transport: TransportOptions);
     /**
      * Launchable apps only, so a grid tile is never a dead end. The calling
-     * service is included and flagged `isCurrent` rather than filtered out.
+     * application is included and flagged `isCurrent` rather than filtered out.
      */
-    list(organizationId: string): Promise<OrganizationApp[]>;
+    list(workspaceId: string): Promise<WorkspaceApp[]>;
 }

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

@@ -5,7 +5,7 @@ export declare class BillingResource {
     private readonly transport;
     constructor(transport: TransportOptions);
     /**
-     * Your service's active plans - render live pricing instead of hardcoding it.
+     * Your application's active plans - render live pricing instead of hardcoding it.
      *
      * `features` is normalised on the way out: Connect used to send bare keys
      * and now sends `{ key, name, description }`, and this SDK is versioned
@@ -15,7 +15,7 @@ export declare class BillingResource {
      */
     listPlans(): Promise<PlansResponse>;
     /**
-     * What is left of every consumable add-on on an organization's
+     * What is left of every consumable add-on on a workspace's
      * subscription - the read half of `consumeAddon`.
      *
      * Needs a key scoped to `addons:read`, which is separate from
@@ -25,10 +25,10 @@ export declare class BillingResource {
      * Returns an empty `addons` array rather than throwing when there is
      * nothing to meter, so a caller can render it unconditionally.
      */
-    getAddonUsage(organizationId: string): Promise<AddonUsageResponse>;
+    getAddonUsage(workspaceId: string): Promise<AddonUsageResponse>;
     /**
      * Debit a consumable add-on's per-cycle balance on behalf of an
-     * organization's users. Call it at whatever cadence your usage happens.
+     * workspace's users. Call it at whatever cadence your usage happens.
      *
      * An `Idempotency-Key` is always sent, generated per call when you do not
      * supply one: a balance cannot be un-spent, so a retried consume without a

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

@@ -1,7 +1,7 @@
 import { type TransportOptions } from "../http.js";
 import type { ThumbnailSize, UploadedFile } from "../../types.js";
 export interface UploadInput {
-    organizationId: string;
+    workspaceId: string;
     /** Any `Blob`/`File`. In Node, `new Blob([buffer])` or `fs.openAsBlob(path)`. */
     file: Blob;
     /** Defaults to the `Blob`'s own name when it has one. */
@@ -9,18 +9,18 @@ export interface UploadInput {
     /** Target folder. Omit for the Drive root. */
     parentId?: string;
 }
-/** Files in an organization's Drive - upload, and signed URLs to read back. */
+/** Files in a workspace's Drive - upload, and signed URLs to read back. */
 export declare class DriveResource {
     private readonly transport;
     constructor(transport: TransportOptions);
     upload(input: UploadInput): Promise<UploadedFile>;
     /** A signed URL for the original bytes. Short-lived - fetch it when you need it, do not store it. */
     getFileUrl(fileId: string, input: {
-        organizationId: string;
+        workspaceId: string;
     }): Promise<string>;
     /** A signed URL for the thumbnail. Same lifetime caveat as `getFileUrl`. */
     getPreviewUrl(fileId: string, input: {
-        organizationId: string;
+        workspaceId: string;
         size?: ThumbnailSize;
     }): Promise<string>;
 }

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { ReadinessResponse, SubscriptionResponse } from "../../types.js";
+import type { ApplicationSubscriber, ReadinessResponse, SubscribersResponse, SubscriptionResponse } from "../../types.js";
 /**
  * The two checks worth making on every request: may this workspace be here at
  * all, and what is it paying for.
@@ -8,7 +8,7 @@ export declare class EntitlementsResource {
     private readonly transport;
     constructor(transport: TransportOptions);
     /**
-     * Every gate Connect owns between an organization and your service -
+     * Every gate Connect owns between a workspace and your application -
      * subscription, KYC/KYB, a chargeable payment method, seat headroom -
      * resolved in one call.
      *
@@ -16,9 +16,9 @@ export declare class EntitlementsResource {
      * Connect screen that fixes it, so you can route them somewhere useful
      * instead of refusing them with nowhere to go.
      */
-    getReadiness(organizationId: string): Promise<ReadinessResponse>;
+    getReadiness(workspaceId: string): Promise<ReadinessResponse>;
     /** The live plan and subscription, including `plan.features`. */
-    getSubscription(organizationId: string): Promise<SubscriptionResponse>;
+    getSubscription(workspaceId: string): Promise<SubscriptionResponse>;
     /**
      * Whether an active subscription unlocks a plan feature - the check that
      * gates a plan-restricted module.
@@ -27,5 +27,37 @@ export declare class EntitlementsResource {
      * all: "not entitled" is the same answer either way, and a feature gate
      * should not need a try/catch around it.
      */
-    hasFeature(organizationId: string, feature: string): Promise<boolean>;
+    hasFeature(workspaceId: string, feature: string): Promise<boolean>;
+    /**
+     * One page of the workspaces subscribed to your application, newest first.
+     *
+     * The inverse of `getSubscription`, which asks about one workspace you
+     * already know. This asks who your subscribers *are* - what a partner
+     * dashboard, an MRR total or a churn report is built on.
+     *
+     * Rate-limited far more tightly than the per-workspace read (10/min per
+     * key, against 60): it walks your whole subscriber base and is a reporting
+     * call, not a per-request gate. Use `getSubscription` in a hot path.
+     *
+     * Your application is resolved from the API key, so there is no parameter
+     * for it and no way to ask about anyone else's.
+     */
+    listSubscribers(options?: {
+        status?: ApplicationSubscriber["status"];
+        /** Cursor from a previous page's `nextBefore`. */
+        before?: string;
+        /** 1..100, default 25. */
+        limit?: number;
+    }): Promise<SubscribersResponse>;
+    /**
+     * Every subscriber, paged through for you.
+     *
+     * An async generator rather than an array: a large subscriber base is
+     * exactly where an accidental full materialisation hurts, and `for await`
+     * reads the same as a loop over one page.
+     */
+    iterateSubscribers(options?: {
+        status?: ApplicationSubscriber["status"];
+        pageSize?: number;
+    }): AsyncGenerator<ApplicationSubscriber>;
 }

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

@@ -16,7 +16,7 @@ export interface AuthorizeUrlInput {
      * sign-in, since by definition it will never show them a login screen.
      */
     prompt?: "create" | "none";
-    /** Required only if this service enforces PKCE. */
+    /** Required only if this application enforces PKCE. */
     codeChallenge?: string;
 }
 export interface ExchangeCodeInput {
@@ -69,7 +69,7 @@ export declare class IdentityResource {
      * rest of its ~15-day life. Discard your own copy of `sessionToken` too;
      * this does not do that for you.
      *
-     * `scope` defaults to `"device"`: this sign-in, every other service signed
+     * `scope` defaults to `"device"`: this sign-in, every other application signed
      * into from the same browser, and Connect's own session on that one device.
      * `"all"` ends every session on every device - an explicit "sign out
      * everywhere" action only.

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

@@ -8,15 +8,15 @@ export interface ExecuteIntegrationActionInput {
 }
 /**
  * Composio-hosted third-party connections (Google Calendar, Slack,
- * Twitter/X, ...) an organization has connected. Connect proxies every call
- * here - your service never sees or holds the underlying OAuth token, which
+ * Twitter/X, ...) a workspace has connected. Connect proxies every call
+ * here - your application never sees or holds the underlying OAuth token, which
  * stays with Composio.
  */
 export declare class IntegrationsResource {
     private readonly transport;
     constructor(transport: TransportOptions);
-    /** Enabled toolkits and this organization's connection status for each. */
-    list(organizationId: string): Promise<IntegrationsListResponse["toolkits"]>;
+    /** Enabled toolkits and this workspace's connection status for each. */
+    list(workspaceId: string): Promise<IntegrationsListResponse["toolkits"]>;
     /**
      * Starts a Composio-hosted connection for one toolkit. The returned
      * `redirectUrl` is where the browser completes the provider's OAuth
@@ -28,13 +28,13 @@ export declare class IntegrationsResource {
      * itself. Reconnecting a disconnected/failed toolkit calls this same
      * method - there is no separate reconnect.
      *
-     * Meant to be called on behalf of a signed-in org admin (this is what the
+     * Meant to be called on behalf of a signed-in workspace admin (this is what the
      * bridge's fixed `POST /integrations/connect` route does), not as a bare
      * background action with no admin present to complete the OAuth screen.
      */
-    initiateConnect(organizationId: string, toolkitSlug: string, returnUrl: string): Promise<InitiateIntegrationConnectionResponse>;
+    initiateConnect(workspaceId: string, toolkitSlug: string, returnUrl: string): Promise<InitiateIntegrationConnectionResponse>;
     /** Idempotent - disconnecting a toolkit that was never connected, or is already disconnected, is a success. */
-    disconnect(organizationId: string, toolkitSlug: string): Promise<DisconnectIntegrationResponse>;
-    /** Calls a Composio action against this organization's connected account for the named toolkit. */
-    execute(organizationId: string, input: ExecuteIntegrationActionInput): Promise<ExecuteIntegrationActionResponse>;
+    disconnect(workspaceId: string, toolkitSlug: string): Promise<DisconnectIntegrationResponse>;
+    /** 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/logs.d.ts

@@ -1,6 +1,6 @@
 import { type TransportOptions } from "../http.js";
 import type { WriteLogInput, WriteLogResponse } from "../../types.js";
-/** Push feature events into the Console's audit log, filterable to your service. */
+/** Push feature events into the Console's audit log, filterable to your application. */
 export declare class LogsResource {
     private readonly transport;
     constructor(transport: TransportOptions);
@@ -10,9 +10,9 @@ export declare class LogsResource {
      * reported through the return value.
      *
      * Pass `sessionToken` to attribute the event to the end user it belongs to.
-     * Both scopes on the stored entry come from something verified - the service
+     * Both scopes on the stored entry come from something verified - the application
      * from your API key, the user from that token, which Connect checks was
-     * minted for your service before attributing anything. `attributed` in the
+     * minted for your application before attributing anything. `attributed` in the
      * result says whether it resolved; a `false` there still means the line was
      * stored, just without a user on it.
      */

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

@@ -5,11 +5,11 @@ import type { ConnectUserSession, RevokeOtherSessionsResponse } from "../../type
  * timestamps - the same list Connect's own account settings page shows the
  * user themselves.
  *
- * **Account-wide, not scoped to this service.** A Connect session is one
- * browser's login to Connect, and it fans out to every partner service's own
- * `sessionToken` - Connect has no per-service session concept to filter by.
+ * **Account-wide, not scoped to this application.** A Connect session is one
+ * browser's login to Connect, and it fans out to every partner application's own
+ * `sessionToken` - Connect has no per-application session concept to filter by.
  * `list()` returns every session on the account, including ones that
- * originated from a completely different, unrelated service. Requires the
+ * originated from a completely different, unrelated application. Requires the
  * `sessions:manage` scope on your API key - unlike `identity`'s base `sso`
  * capability, this is never granted to a zero-scope legacy key by default.
  *
@@ -25,7 +25,7 @@ export declare class SessionsResource {
     list(sessionToken: string): Promise<ConnectUserSession[]>;
     /**
      * Ends one specific session by id - not necessarily the one `sessionToken`
-     * itself was minted from. Cascades to every partner-service sign-in that
+     * itself was minted from. Cascades to every partner-application sign-in that
      * originated from that same browser, same as Connect's own "sign out this
      * device".
      */

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

@@ -35,10 +35,10 @@ export interface ConnectWebhookHandlerOptions {
  * export const POST = createConnectWebhookHandler({
  *   secret: process.env.CONNECT_WEBHOOK_SECRET!,
  *   on: {
- *     "organization.deletion_scheduled": ({ organizationId, purgeAfter }) =>
- *       freeze(organizationId, purgeAfter),
- *     "organization.deletion_cancelled": ({ organizationId }) => unfreeze(organizationId),
- *     "organization.deleted": ({ organizationId }) => purge(organizationId),
+ *     "workspace.deletion_scheduled": ({ workspaceId, purgeAfter }) =>
+ *       freeze(workspaceId, purgeAfter),
+ *     "workspace.deletion_cancelled": ({ workspaceId }) => unfreeze(workspaceId),
+ *     "workspace.deleted": ({ workspaceId }) => purge(workspaceId),
  *   },
  * })
  * ```