@cosmoops/connect-sdk 0.2.0 → 0.6.0

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, ...) an organization has connected. Connect proxies every call
+ * here - your service 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"]>;
+    /**
+     * 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 org 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>;
+    /** 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>;
+}

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: {
+ *     "organization.deletion_scheduled": ({ organizationId, purgeAfter }) =>
+ *       freeze(organizationId, purgeAfter),
+ *     "organization.deletion_cancelled": ({ organizationId }) => unfreeze(organizationId),
+ *     "organization.deleted": ({ organizationId }) => purge(organizationId),
+ *   },
+ * })
+ * ```
+ *
+ * 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>;

package/dist/types/this-entry-is-server-only.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types.d.ts

@@ -16,6 +16,15 @@ export interface ConnectUser {
     email: string | null;
     emailVerified: boolean;
     displayName: string | null;
+    /**
+     * The member's profile picture, or `null` when they have not set one.
+     *
+     * Deliberately nullable rather than a generated placeholder: only you know
+     * what your fallback should look like. `<ConnectUserMenu>` renders initials
+     * via `<Avatar.Fallback>`, which also covers the URL loading slowly or
+     * failing outright - so pair the two rather than branching on `null`.
+     */
+    photoUrl: string | null;
     organizationId: string;
     organizationName: string;
 }
@@ -95,7 +104,7 @@ export interface RolesResponse {
     permissionCatalog: ServicePermission[];
     roles: ServiceRoleDefinition[];
 }
-export type ReadinessBlockerCode = "subscription_missing" | "subscription_inactive" | "audience_mismatch" | "verification_required" | "verification_pending" | "verification_rejected" | "verification_expired" | "payment_method_missing" | "seat_limit_reached" | "organization_not_found" | "onboarding_approval_pending" | "onboarding_approval_rejected";
+export type ReadinessBlockerCode = "subscription_missing" | "subscription_inactive" | "audience_mismatch" | "verification_required" | "verification_pending" | "verification_rejected" | "verification_expired" | "payment_method_missing" | "seat_limit_reached" | "organization_not_found" | "onboarding_approval_pending" | "onboarding_approval_rejected" | "organization_suspended" | "payment_retry_pending";
 export interface ReadinessBlocker {
     /**
      * Branch on this. Typed as a union for the codes that exist today, widened
@@ -108,6 +117,8 @@ export interface ReadinessBlocker {
     message: string;
     /** Where in Connect the customer resolves this. `null` when nothing they do helps (e.g. a review in progress). */
     resolveUrl: string | null;
+    /** When this blocker resolves itself automatically - currently only set on `payment_retry_pending`, the deadline dunning suspends the subscription. `undefined`/`null` for every other code. */
+    graceEndsAt?: string | null;
 }
 export interface ReadinessResponse {
     organizationId: string;
@@ -432,3 +443,173 @@ export interface RevokeOtherSessionsResponse {
 }
 /** Host-controlled - the SDK has no theme provider of its own. See `ConnectUserMenuProps.theme`. */
 export type ThemeMode = "light" | "dark" | "system";
+/**
+ * `not_connected` never travels over the wire as a persisted state - it's
+ * what `ListOrganizationIntegrationsUseCase` reports for a toolkit this
+ * organization has no `IntegrationConnection` record for at all.
+ */
+export type IntegrationConnectionStatus = "not_connected" | "pending" | "active" | "failed" | "disconnected" | "expired";
+/**
+ * A Composio-hosted third-party toolkit (Google Calendar, Slack, Twitter/X,
+ * ...) this organization can see - only ever one a platform admin enabled in
+ * Connect's own Console, joined with this org's own connection status.
+ * Connections are org-shared: one covers every member, the way a Slack app
+ * install is shared rather than per-user.
+ */
+export interface IntegrationToolkit {
+    slug: string;
+    name: string;
+    description: string;
+    category: string | null;
+    logoUrl: string | null;
+    status: IntegrationConnectionStatus;
+}
+export interface IntegrationsListResponse {
+    toolkits: IntegrationToolkit[];
+}
+/** The connection isn't active yet when this returns - see `IntegrationsResource.initiateConnect`'s doc comment. */
+export interface InitiateIntegrationConnectionResponse {
+    /** Send the browser here to complete the provider's OAuth screen. */
+    redirectUrl: string;
+    connectionId: string;
+}
+export interface DisconnectIntegrationResponse {
+    success: true;
+}
+export interface ExecuteIntegrationActionResponse {
+    data: unknown;
+    successful: boolean;
+}
+/**
+ * The metrics Connect can report for your service.
+ *
+ * Hand-written here rather than imported from Connect's own registry, like
+ * every other wire type in this file, so the published package carries none of
+ * Connect's internals. `conformance.test.ts` type-checks these against the
+ * server DTOs, so drift fails the build in Connect's repo rather than in a
+ * partner's integration.
+ */
+export type ConnectMetric = "usage.events" | "usage.active_users" | "api.requests" | "api.errors" | "billing.mrr_paise" | "billing.active_subscriptions" | "metering.addon_consumed";
+export interface AnalyticsPoint {
+    /** `YYYY-MM-DD`, UTC. */
+    day: string;
+    /**
+     * **`null` is not zero.** It means the metric was not measurable that day -
+     * `usage.active_users` is a distinct count that only exists after Connect's
+     * nightly rollup, so today's is always `null`, as is any future day. Render
+     * it as a gap or a dash, never as a zero.
+     */
+    value: number | null;
+}
+export interface AnalyticsSeries {
+    metric: ConnectMetric;
+    points: AnalyticsPoint[];
+    /** Sum across measurable days only, or `null` if no day in the range was measurable. */
+    total: number | null;
+    /** True when at least one day was not measurable - caveat the total when this is set. */
+    partial: boolean;
+}
+export interface AnalyticsResponse {
+    from: string;
+    to: string;
+    series: AnalyticsSeries[];
+}
+export interface AnalyticsQuery {
+    metrics: ConnectMetric[];
+    /** Inclusive `YYYY-MM-DD`, UTC. The range must be shorter than 90 days. */
+    from: string;
+    to: string;
+}
+/** One event you push into Connect's analytics pipeline. */
+export interface EmitEventInput {
+    /**
+     * Dot-namespaced and lowercase, e.g. `checkout.completed`. Prefixes Connect
+     * emits itself - `api.`, `billing.`, `addon.`, `subscription.`, `connect.` -
+     * are rejected, so your events can never inflate a metered number.
+     */
+    name: string;
+    /** Defaults to now. Clamped server-side to within 48 hours. */
+    occurredAt?: string | Date;
+    /** Attributes the event to the signed-in user and their organization. */
+    sessionToken?: string;
+    /** A whole number in the smallest unit of `unit` - paise, bytes, milliseconds. */
+    value?: number;
+    unit?: string;
+    props?: Record<string, unknown>;
+}
+export interface EmitEventsResponse {
+    /** False when the call failed outright - see `AnalyticsResource.emit`. */
+    delivered: boolean;
+    accepted: number;
+    attributed: number;
+}
+/**
+ * Every event Connect will POST to your webhook endpoint.
+ *
+ * Additive only - Connect adds event types, never renames one - so a
+ * `switch` that does not handle a future type is safe, and
+ * `createConnectWebhookHandler` simply ignores anything you have not
+ * registered a handler for.
+ */
+export type ConnectWebhookEventType = "organization.deletion_scheduled" | "organization.deletion_cancelled" | "organization.deleted" | "subscription.cancelled";
+/**
+ * A workspace's deletion has been confirmed and the grace window is running.
+ *
+ * Access is *already* denied - readiness reports
+ * `organization_pending_deletion` from this moment - so treat this as "stop
+ * writing", not "start planning". `purgeAfter` is what makes this event worth
+ * having: the customer's data still exists until then, so an export or a
+ * wind-down can run on the same clock rather than after everything is gone.
+ */
+export interface OrganizationDeletionScheduledEvent {
+    organizationId: string;
+    /** ISO-8601. When Connect destroys the workspace. */
+    purgeAfter: string;
+    requestedBy: "owner" | "platform_admin";
+    graceDays: number;
+}
+/**
+ * The deletion was withdrawn and the workspace is live again.
+ *
+ * **Handle this one.** It is the event integrations forget, and its absence
+ * is the worst failure of the set: a service that froze a workspace on
+ * `organization.deletion_scheduled` and never unfreezes leaves a paying
+ * customer locked out of something that has no idea anything changed.
+ */
+export interface OrganizationDeletionCancelledEvent {
+    organizationId: string;
+}
+/** The grace window closed and Connect purged the workspace. Purge your own copy. */
+export interface OrganizationDeletedEvent {
+    organizationId: string;
+    /** ISO-8601. */
+    purgedAt: string;
+}
+/** A subscription ended. Fires on its own, not only as part of a deletion. */
+export interface SubscriptionCancelledEvent {
+    organizationId: string;
+    subscriptionId: string;
+    serviceId: string;
+}
+/** Maps each event type to the shape of its `data`. */
+export interface ConnectWebhookEventMap {
+    "organization.deletion_scheduled": OrganizationDeletionScheduledEvent;
+    "organization.deletion_cancelled": OrganizationDeletionCancelledEvent;
+    "organization.deleted": OrganizationDeletedEvent;
+    "subscription.cancelled": SubscriptionCancelledEvent;
+}
+/** The envelope, as it arrives on the wire. */
+export interface ConnectWebhookEnvelope<T extends ConnectWebhookEventType = ConnectWebhookEventType> {
+    /**
+     * Unique per delivery. **Dedupe on this.** Delivery is at-least-once and
+     * unordered: a partner that assumes exactly-once, or assumes order, will
+     * eventually be wrong.
+     */
+    id: string;
+    type: T;
+    /** ISO-8601. */
+    createdAt: string;
+    /** Bumped only for a breaking payload change - never for a new event type. */
+    apiVersion: string;
+    data: ConnectWebhookEventMap[T];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.2.0",
+  "version": "0.6.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",
@@ -15,11 +15,19 @@
     },
     "./server": {
       "types": "./dist/types/server/index.d.ts",
+      "browser": {
+        "import": "./dist/esm/this-entry-is-server-only.js",
+        "require": "./dist/cjs/this-entry-is-server-only.js"
+      },
       "import": "./dist/esm/server/index.js",
       "require": "./dist/cjs/server/index.js"
     },
     "./next": {
       "types": "./dist/types/next/index.d.ts",
+      "browser": {
+        "import": "./dist/esm/this-entry-is-server-only.js",
+        "require": "./dist/cjs/this-entry-is-server-only.js"
+      },
       "import": "./dist/esm/next/index.js",
       "require": "./dist/cjs/next/index.js"
     },
@@ -39,7 +47,8 @@
     "node": ">=18"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "cosmoops",
@@ -58,6 +67,8 @@
     "verify:pack": "bun run scripts/verify-pack.ts",
     "prepublishOnly": "bun run build && bun run verify:pack",
     "test": "bun test",
+    "docs": "typedoc",
+    "docs:md": "typedoc --options typedoc.markdown.json",
     "storybook": "storybook dev -p 6106",
     "build:storybook": "storybook build -o storybook-static"
   },
@@ -72,18 +83,22 @@
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "lucide-react": "^0.545.0",
+    "motion": "^13.1.1",
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "storybook": "^10.5.10",
     "tailwindcss": "^4.3.3",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0",
     "typescript": "^5",
     "vite": "^8.2.2"
   },
   "peerDependencies": {
     "@heroui/react": ">=3.2.0",
     "lucide-react": ">=0.400.0",
-    "react": ">=18",
-    "react-dom": ">=18"
+    "motion": ">=12",
+    "react": ">=19",
+    "react-dom": ">=19"
   },
   "peerDependenciesMeta": {
     "@heroui/react": {
@@ -92,6 +107,9 @@
     "lucide-react": {
       "optional": true
     },
+    "motion": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },