@cosmoops/connect-sdk 0.3.0 → 0.7.0

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

@@ -6,13 +6,15 @@ import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
 import { EntitlementsResource } from "./resources/entitlements.js";
 import { IdentityResource } from "./resources/identity.js";
+import { IntegrationsResource } from "./resources/integrations.js";
 import { LogsResource } from "./resources/logs.js";
+import { AnalyticsResource } from "./resources/analytics.js";
 import { OtpResource } from "./resources/otp.js";
 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 Setup 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
@@ -37,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.
  *
@@ -50,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
@@ -59,25 +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;
-    /** This Connect account's own login sessions - account-wide, not scoped to this service. Requires the `sessions:manage` scope. */
+    /** 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 application. Requires the `sessions:manage` scope. */
     readonly sessions: SessionsResource;
+    /** 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.3.0";
+export declare const SDK_VERSION = "0.7.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/index.d.ts

@@ -20,4 +20,11 @@ export type { BillingResource } from "./resources/billing.js";
 export type { AiResource } from "./resources/ai.js";
 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, IntegrationsResource } from "./resources/integrations.js";
+/**
+ * Webhook verification and a ready-made POST route. Server-only for the
+ * obvious reason: the signing secret must never reach a browser bundle.
+ */
+export { createConnectWebhookHandler, verifyConnectWebhook, type ConnectWebhookHandlers, type ConnectWebhookHandlerOptions, } from "./webhooks.js";

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

@@ -0,0 +1,31 @@
+import { type TransportOptions } from "../http.js";
+import type { AnalyticsQuery, AnalyticsResponse, EmitEventInput, EmitEventsResponse } from "../../types.js";
+/**
+ * Your application's own analytics: emit product events, and read back the daily
+ * numbers Connect aggregates from them.
+ *
+ * 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.
+ */
+export declare class AnalyticsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Daily series for the requested metrics, up to 90 days.
+     *
+     * **Throws on failure**, unlike `emit` below. A read whose result you are
+     * about to render has to be able to say "I could not load"; silently
+     * returning an empty series would draw a chart of zeroes.
+     */
+    series(query: AnalyticsQuery): Promise<AnalyticsResponse>;
+    /**
+     * Never throws - the same judgement `LogsResource.write` makes, for the same
+     * reason: telemetry that takes down the code path it was observing is worse
+     * than a lost event. A failure is reported through `delivered`.
+     *
+     * Up to 50 events per call. Pass `sessionToken` on an event to attribute it
+     * to the signed-in user; without one it still lands, just unattributed.
+     */
+    emit(events: EmitEventInput[]): Promise<EmitEventsResponse>;
+}

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

@@ -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,5 @@ 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>;
 }

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

@@ -4,9 +4,19 @@ export interface AuthorizeUrlInput {
     redirectUri: string;
     /** Fresh and random per request; check it matches on the way back. `createState()` makes one. */
     state: string;
-    /** `"create"` opens registration instead of sign-in, so one entry point serves both buttons. */
-    prompt?: "create";
-    /** Required only if this service enforces PKCE. */
+    /**
+     * `"create"` opens registration instead of sign-in, so one entry point
+     * serves both buttons.
+     *
+     * `"none"` is OIDC silent authentication: Connect answers from the
+     * visitor's existing session without showing them anything, returning a
+     * code if they are signed in and have already authorised this client, and
+     * `error=login_required`/`consent_required`/`interaction_required` if not.
+     * Use it to sign in a returning visitor with no click - never to *start* a
+     * sign-in, since by definition it will never show them a login screen.
+     */
+    prompt?: "create" | "none";
+    /** Required only if this application enforces PKCE. */
     codeChallenge?: string;
 }
 export interface ExchangeCodeInput {
@@ -59,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

@@ -0,0 +1,40 @@
+import { type TransportOptions } from "../http.js";
+import type { DisconnectIntegrationResponse, ExecuteIntegrationActionResponse, InitiateIntegrationConnectionResponse, IntegrationsListResponse } from "../../types.js";
+export interface ExecuteIntegrationActionInput {
+    toolkitSlug: string;
+    actionSlug: string;
+    /** 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>;
+}
+/**
+ * Composio-hosted third-party connections (Google Calendar, Slack,
+ * 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 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
+     * screen, then Composio bounces it back to `returnUrl`.
+     *
+     * **The connection is not active when this returns.** Treat the toolkit
+     * as `pending` until a later `list()` call reports `active` - only
+     * Connect's own webhook from Composio confirms that, never the redirect
+     * 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 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(workspaceId: string, toolkitSlug: string, returnUrl: string): Promise<InitiateIntegrationConnectionResponse>;
+    /** Idempotent - disconnecting a toolkit that was never connected, or is already disconnected, is a success. */
+    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

@@ -0,0 +1,67 @@
+import type { ConnectWebhookEnvelope, ConnectWebhookEventMap, ConnectWebhookEventType } from "../types.js";
+/**
+ * Verifies a `Connect-Signature` header against the raw request body.
+ *
+ * Exported on its own for anyone wiring this into a framework
+ * `createConnectWebhookHandler` does not cover. The **raw** body matters:
+ * verify before parsing, and never re-serialise - `JSON.stringify(await
+ * req.json())` produces a different string whenever key order or number
+ * formatting differs, and the signature will not match.
+ *
+ * Returns a boolean and never explains which check failed. Reporting "bad
+ * timestamp" separately from "bad signature" tells whoever is probing which
+ * half of a forgery to keep working on.
+ */
+export declare function verifyConnectWebhook(rawBody: string, signatureHeader: string | null | undefined, secret: string, now?: Date): boolean;
+/** One handler per event type. Every one is optional; unhandled types are acknowledged and ignored. */
+export type ConnectWebhookHandlers = {
+    [K in ConnectWebhookEventType]?: (data: ConnectWebhookEventMap[K], envelope: ConnectWebhookEnvelope<K>) => void | Promise<void>;
+};
+export interface ConnectWebhookHandlerOptions {
+    /** The endpoint's signing secret, from Console. Keep it in an environment variable. */
+    secret: string;
+    on: ConnectWebhookHandlers;
+    /**
+     * Called when a handler throws. Return nothing to have the delivery
+     * retried (Connect responds to a 5xx by retrying for about 33 hours);
+     * the default logs and rethrows, which produces exactly that.
+     */
+    onError?: (error: unknown, envelope: ConnectWebhookEnvelope) => void | Promise<void>;
+}
+/**
+ * A ready-made `POST` route for Connect's webhooks.
+ *
+ * ```ts
+ * export const POST = createConnectWebhookHandler({
+ *   secret: process.env.CONNECT_WEBHOOK_SECRET!,
+ *   on: {
+ *     "workspace.deletion_scheduled": ({ workspaceId, purgeAfter }) =>
+ *       freeze(workspaceId, purgeAfter),
+ *     "workspace.deletion_cancelled": ({ workspaceId }) => unfreeze(workspaceId),
+ *     "workspace.deleted": ({ workspaceId }) => purge(workspaceId),
+ *   },
+ * })
+ * ```
+ *
+ * Three behaviours worth knowing, because each of them is a decision rather
+ * than an accident:
+ *
+ * **An unverified request gets a 401 and nothing else happens.** No parsing,
+ * no logging of the body, no handler. The endpoint is a public URL, so
+ * anything reachable before the signature check is reachable by anyone.
+ *
+ * **An unhandled event type is a 200.** Connect adds event types over time,
+ * and answering 4xx to one you have not written code for would dead-letter
+ * it immediately and, after enough of them, disable your endpoint. Silence
+ * is the correct answer to "we do not care about this one".
+ *
+ * **A throwing handler produces a 500, on purpose.** That is what makes
+ * Connect retry. Swallowing the error would acknowledge an event you failed
+ * to process, and the retry ladder is the only thing standing between a
+ * transient failure and a permanently missed deletion.
+ *
+ * Delivery is at-least-once and unordered. Dedupe on `envelope.id`, and
+ * reconcile against the readiness endpoint rather than trusting arrival
+ * order - the pull channel is authoritative, this one is fast.
+ */
+export declare function createConnectWebhookHandler(options: ConnectWebhookHandlerOptions): (request: Request) => Promise<Response>;