@cosmoops/connect-sdk 0.6.0 → 0.9.0

package/dist/types/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * Wire types for the `/api/v1/service/*` surface - the service-partner API,
+ * Wire types for the `/api/v1/application/*` surface - the application-partner API,
  * and the only thing this SDK covers.
  *
  * Hand-written rather than generated so the published package carries no
@@ -25,11 +25,59 @@ export interface ConnectUser {
      * failing outright - so pair the two rather than branching on `null`.
      */
     photoUrl: string | null;
-    organizationId: string;
-    organizationName: string;
+    workspaceId: string;
+    workspaceName: string;
+    /**
+     * Whether this is a one-seat personal account or a team.
+     *
+     * The one fact about the signed-in workspace you cannot look up yourself -
+     * the application API has no workspace read - so branch on it rather than
+     * inferring an account's shape from whether it happens to have a second
+     * member. An `"individual"` workspace has exactly one seat and can never
+     * have another, so a members table, an invite button or a seat-count meter
+     * is dead UI for it.
+     *
+     * Re-read it from `identity.getUser()`; do not cache it past the sign-in.
+     * An `"individual"` workspace can convert to `"business"` under a live
+     * session (the reverse never happens).
+     */
+    workspaceType: WorkspaceType;
+}
+export type WorkspaceType = "individual" | "business";
+export type ApplicationAudience = "b2b" | "b2c" | "both";
+/**
+ * Whether the signed-in workspace is inside your application's audience -
+ * returned alongside `user` by both `exchangeCode()` and `getUser()`.
+ *
+ * `user.workspaceType` answers what the account *is*; this answers what your
+ * application is *sold to*, and whether the two agree. Both ship together so
+ * the check stays `!audience.matches` rather than a hardcoded audience
+ * constant in your own code that goes stale the moment the catalogue entry
+ * changes.
+ *
+ * `matches: false` means readiness will report an `audience_mismatch` blocker
+ * and any attempt to subscribe will be refused, so treat it as a hard block:
+ * `<ConnectAccessGate>` already does. What it is NOT is a reason to sign the
+ * user out - they have a valid Connect account, just the wrong kind of one
+ * for this application.
+ */
+export interface SessionAudience {
+    /** Your catalogue entry's setting - `"both"` if you have never narrowed it. */
+    application: ApplicationAudience;
+    /** The single `workspaceType` `application` demands - `null` for `"both"`, which accepts either. */
+    requiredWorkspaceType: WorkspaceType | null;
+    /** `false` means this user is outside your audience. */
+    matches: boolean;
+    /**
+     * Whether Connect refuses the sign-in itself on a mismatch. When `true`,
+     * a `matches: false` can only reach you on a session minted before the
+     * setting was turned on. When `false`, gating is entirely yours to do -
+     * which is what `<ConnectAccessGate>` is for.
+     */
+    enforcedAtSignIn: boolean;
 }
 export type SubscriptionStatus = "created" | "authenticated" | "active" | "paused" | "cancelled";
-/** The compact subscription block returned alongside identity - `null` when the org has never subscribed to this service. */
+/** The compact subscription block returned alongside identity - `null` when the workspace has never subscribed to this application. */
 export interface SessionSubscription {
     planId: string;
     status: SubscriptionStatus;
@@ -38,11 +86,11 @@ export interface SessionSubscription {
     isTrialing: boolean;
 }
 /**
- * What this member may do on *your* service - resolved for your `client_id`,
- * not their org-wide roles. `role` is `null` when their granted permissions
+ * What this member may do on *your* application - resolved for your `client_id`,
+ * not their workspace-wide roles. `role` is `null` when their granted permissions
  * match no single defined role, including when they have no access at all.
  */
-export interface ServiceRole {
+export interface ApplicationRole {
     role: string | null;
     granted: string[];
 }
@@ -57,12 +105,16 @@ export interface TokenResponse {
     sessionTokenExpiresIn: number;
     user: ConnectUser;
     subscription: SessionSubscription | null;
-    serviceRole: ServiceRole;
+    applicationRole: ApplicationRole;
+    /** Whether this account is the kind your application serves - see `SessionAudience`. */
+    audience: SessionAudience;
 }
 export interface UserResponse {
     user: ConnectUser;
     subscription: SessionSubscription | null;
-    serviceRole: ServiceRole;
+    applicationRole: ApplicationRole;
+    /** Live, like `subscription` and `applicationRole` - a workspace that converted to a business since sign-in matches here without another sign-in. */
+    audience: SessionAudience;
     /** ISO 8601. Refresh proactively off this rather than waiting for a 401. */
     sessionExpiresAt: string;
 }
@@ -83,28 +135,28 @@ export interface IdTokenClaims {
 export type LogoutScope = "device" | "all";
 export interface UserRolesResponse {
     userId: string;
-    organizationId: string;
+    workspaceId: string;
     role: string | null;
     granted: string[];
 }
-export interface ServicePermission {
+export interface ApplicationPermission {
     id: string;
     label: string;
     description: string;
 }
-export interface ServiceRoleDefinition {
+export interface ApplicationRoleDefinition {
     key: string;
     name: string;
     description: string;
     permissions: string[];
 }
 export interface RolesResponse {
-    serviceId: string;
-    serviceKey: string | null;
-    permissionCatalog: ServicePermission[];
-    roles: ServiceRoleDefinition[];
+    applicationId: string;
+    applicationKey: string | null;
+    permissionCatalog: ApplicationPermission[];
+    roles: ApplicationRoleDefinition[];
 }
-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 type ReadinessBlockerCode = "subscription_missing" | "subscription_inactive" | "audience_mismatch" | "verification_required" | "verification_pending" | "verification_rejected" | "verification_expired" | "payment_method_missing" | "seat_limit_reached" | "workspace_not_found" | "onboarding_approval_pending" | "onboarding_approval_rejected" | "workspace_suspended" | "payment_retry_pending";
 export interface ReadinessBlocker {
     /**
      * Branch on this. Typed as a union for the codes that exist today, widened
@@ -119,10 +171,12 @@ export interface ReadinessBlocker {
     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;
+    /** The account type this application requires - set only on `audience_mismatch`, `undefined`/`null` otherwise. Branch on this rather than reading it out of `message`. */
+    requiredWorkspaceType?: "individual" | "business" | null;
 }
 export interface ReadinessResponse {
-    organizationId: string;
-    serviceId: string;
+    workspaceId: string;
+    applicationId: string;
     /** `false` if any blocker is `"blocking"`. */
     ready: boolean;
     readiness: {
@@ -159,7 +213,7 @@ export interface PlanAddon {
  *
  * Note the asymmetry with `SubscribedPlan.features`, which is bare
  * `string[]` and stays that way. That field is a gating contract - your
- * backend calls `hasFeature(orgId, "campaign-module")` against it, and
+ * backend calls `hasFeature(workspaceId, "campaign-module")` against it, and
  * `ConnectFeatureGate` matches on it - so turning it into objects would break
  * every check for a label nobody gates on. This one exists to be rendered,
  * and rendering a bare key puts "campaign-module" on a pricing card where it
@@ -170,7 +224,7 @@ export interface PlanAddon {
 export interface PlanFeature {
     /** The same value `SubscribedPlan.features` holds and `hasFeature` gates on. */
     key: string;
-    /** Human label. Falls back to `key` for a plan predating the service's feature catalog. */
+    /** Human label. Falls back to `key` for a plan predating the application's feature catalog. */
     name: string;
     /** Empty string when the catalog carries no description. */
     description: string;
@@ -253,15 +307,42 @@ export interface SubscriptionDetail {
     appliedDiscount: AppliedDiscount | null;
 }
 export interface SubscriptionResponse {
-    organizationId: string;
-    serviceId: string;
+    workspaceId: string;
+    applicationId: string;
     /** Equivalent to `subscription?.status === "active"`. */
     hasActiveSubscription: boolean;
     subscription: SubscriptionDetail | null;
     /** `null` exactly when `subscription` is. */
     plan: SubscribedPlan | null;
 }
-/** One consumable add-on's remaining balance on an organization's subscription. */
+/** One row of `subscribers.list()` - a workspace subscribed to your application. */
+export interface ApplicationSubscriber {
+    subscriptionId: string;
+    workspaceId: string;
+    /** `null` when the workspace has been purged and only its tombstone remains. */
+    workspaceName: string | null;
+    /** `"active"`, `"suspended"`, `"pending_deletion"`, `"deleted"` - or `null` alongside a null `workspaceName`. */
+    workspaceStatus: string | null;
+    planId: string;
+    /** `null` if the plan was hard-deleted rather than archived. */
+    planName: string | null;
+    status: "created" | "authenticated" | "active" | "paused" | "cancelled";
+    seatCount: number;
+    /** ISO 8601. */
+    subscribedAt: string;
+    /** ISO 8601, or `null` for a cancelled/paused subscription. */
+    nextBillingDate: string | null;
+}
+export interface SubscribersResponse {
+    items: ApplicationSubscriber[];
+    /**
+     * Pass back as `before` for the next page. `null` on the last page - which
+     * is the only reliable end-of-list signal, since a full page can still be
+     * the last one.
+     */
+    nextBefore: string | null;
+}
+/** One consumable add-on's remaining balance on a workspace's subscription. */
 export interface AddonUsage {
     addonId: string;
     name: string;
@@ -284,10 +365,10 @@ export interface AddonUsage {
     maxOverageUnits: number | null;
 }
 export interface AddonUsageResponse {
-    organizationId: string;
-    serviceId: string;
+    workspaceId: string;
+    applicationId: string;
     /**
-     * Empty when the organization has no subscription, the plan has no
+     * Empty when the workspace has no subscription, the plan has no
      * consumable add-ons, or none are selected. All three mean "nothing to
      * meter" and none is an error.
      *
@@ -301,7 +382,7 @@ export interface AddonUsageResponse {
     resetsAt: string | null;
 }
 export interface ConsumeAddonInput {
-    organizationId: string;
+    workspaceId: string;
     addonId: string;
     /** Whole units of the add-on's `unit`. */
     quantity: number;
@@ -358,8 +439,8 @@ export interface WriteLogInput {
      * `sessionToken` - the same one the token exchange handed you.
      *
      * **There is no `userId` to send, deliberately.** The token is verified and
-     * checked to have been minted for *your* service before anything is
-     * attributed, exactly as `serviceId` comes from your API key rather than
+     * checked to have been minted for *your* application before anything is
+     * attributed, exactly as `applicationId` comes from your API key rather than
      * your body. An actor a caller could type is not an actor worth recording.
      *
      * Omit it for genuine server-to-server events with no user behind them.
@@ -384,10 +465,10 @@ export interface ChatMessage {
     role: "user" | "assistant" | "system";
     [field: string]: unknown;
 }
-export interface OrganizationApp {
-    serviceId: string;
-    /** Stable, human-readable key - branch on this, not `serviceId`, which is per-environment. */
-    serviceKey: string | null;
+export interface WorkspaceApp {
+    applicationId: string;
+    /** Stable, human-readable key - branch on this, not `applicationId`, which is per-environment. */
+    applicationKey: string | null;
     name: string;
     /** Plain text, HTML already stripped server-side. */
     description: string;
@@ -395,9 +476,9 @@ export interface OrganizationApp {
     iconUrl: string | null;
     /** A `lucide-react` icon name from Connect's curated set. */
     icon: string;
-    /** Where a tile navigates. `null` when the service registered no site. */
+    /** Where a tile navigates. `null` when the application registered no site. */
     launchUrl: string | null;
-    /** True for the service whose API key made the call - render it as the active tile. */
+    /** True for the application whose API key made the call - render it as the active tile. */
     isCurrent: boolean;
     /** Launchable but not healthy (paused, or cancelling at period end) - badge it, do not hide it. */
     needsAttention: boolean;
@@ -413,9 +494,9 @@ export interface SessionDevice {
 }
 /**
  * One login to the Connect account behind the `sessionToken` you called with -
- * not scoped to this service. A Connect session is one browser's login to
- * Connect itself, and it fans out to every partner service's own session -
- * Connect has no per-service session concept to filter by. `sessions.list()`
+ * not scoped to this application. A Connect session is one browser's login to
+ * Connect itself, and it fans out to every partner application's own session -
+ * Connect has no per-application session concept to filter by. `sessions.list()`
  * returns every one of them, exactly like Connect's own account settings
  * page does for the user themselves.
  */
@@ -445,15 +526,15 @@ export interface RevokeOtherSessionsResponse {
 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.
+ * what `ListWorkspaceIntegrationsUseCase` reports for a toolkit this
+ * workspace 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
+ * ...) this workspace can see - only ever one a platform admin enabled in
+ * Connect's own Console, joined with this workspace's own connection status.
+ * Connections are workspace-shared: one covers every member, the way a Slack app
  * install is shared rather than per-user.
  */
 export interface IntegrationToolkit {
@@ -481,7 +562,7 @@ export interface ExecuteIntegrationActionResponse {
     successful: boolean;
 }
 /**
- * The metrics Connect can report for your service.
+ * The metrics Connect can report for your application.
  *
  * 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
@@ -530,7 +611,7 @@ export interface EmitEventInput {
     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. */
+    /** Attributes the event to the signed-in user and their workspace. */
     sessionToken?: string;
     /** A whole number in the smallest unit of `unit` - paise, bytes, milliseconds. */
     value?: number;
@@ -551,18 +632,18 @@ export interface EmitEventsResponse {
  * `createConnectWebhookHandler` simply ignores anything you have not
  * registered a handler for.
  */
-export type ConnectWebhookEventType = "organization.deletion_scheduled" | "organization.deletion_cancelled" | "organization.deleted" | "subscription.cancelled";
+export type ConnectWebhookEventType = "workspace.deletion_scheduled" | "workspace.deletion_cancelled" | "workspace.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
+ * `workspace_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;
+export interface WorkspaceDeletionScheduledEvent {
+    workspaceId: string;
     /** ISO-8601. When Connect destroys the workspace. */
     purgeAfter: string;
     requestedBy: "owner" | "platform_admin";
@@ -572,30 +653,30 @@ export interface OrganizationDeletionScheduledEvent {
  * 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
+ * is the worst failure of the set: an application that froze a workspace on
+ * `workspace.deletion_scheduled` and never unfreezes leaves a paying
  * customer locked out of something that has no idea anything changed.
  */
-export interface OrganizationDeletionCancelledEvent {
-    organizationId: string;
+export interface WorkspaceDeletionCancelledEvent {
+    workspaceId: string;
 }
 /** The grace window closed and Connect purged the workspace. Purge your own copy. */
-export interface OrganizationDeletedEvent {
-    organizationId: string;
+export interface WorkspaceDeletedEvent {
+    workspaceId: string;
     /** ISO-8601. */
     purgedAt: string;
 }
 /** A subscription ended. Fires on its own, not only as part of a deletion. */
 export interface SubscriptionCancelledEvent {
-    organizationId: string;
+    workspaceId: string;
     subscriptionId: string;
-    serviceId: string;
+    applicationId: 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;
+    "workspace.deletion_scheduled": WorkspaceDeletionScheduledEvent;
+    "workspace.deletion_cancelled": WorkspaceDeletionCancelledEvent;
+    "workspace.deleted": WorkspaceDeletedEvent;
     "subscription.cancelled": SubscriptionCancelledEvent;
 }
 /** The envelope, as it arrives on the wire. */
@@ -613,3 +694,96 @@ export interface ConnectWebhookEnvelope<T extends ConnectWebhookEventType = Conn
     apiVersion: string;
     data: ConnectWebhookEventMap[T];
 }
+/** How a scalar should be presented. See `AiValue` for what each one expects. */
+export type AiValueFormat = "text" | "number"
+/** A number in rupees - `12500`, not paise and not a formatted string. */
+ | "currency"
+/** A fraction - `0.42` renders as 42%. */
+ | "percent"
+/** An ISO 8601 date string. */
+ | "date"
+/** An ISO 8601 datetime string. */
+ | "datetime"
+/** A number of seconds. */
+ | "duration"
+/** A number of bytes. */
+ | "bytes"
+/** A short state word, drawn as a chip. */
+ | "status";
+export type AiTone = "neutral" | "positive" | "warning" | "danger";
+/** One cell. `null` is "no value" and renders as an em dash. */
+export type AiValue = string | number | null;
+export interface AiTableInput {
+    title?: string;
+    columns: {
+        label: string;
+        format: AiValueFormat;
+    }[];
+    /** Positional: one array per row, values in the same order as `columns`. */
+    rows: AiValue[][];
+    caption?: string;
+}
+export interface AiChartInput {
+    title?: string;
+    kind: "bar" | "line" | "area" | "pie";
+    xLabel?: string;
+    yLabel?: string;
+    valueFormat: AiValueFormat;
+    /** Every series shares the same x values, in the same order. */
+    series: {
+        name: string;
+        points: {
+            x: string;
+            y: number | null;
+        }[];
+    }[];
+    caption?: string;
+}
+export interface AiMetricsInput {
+    title?: string;
+    metrics: {
+        label: string;
+        value: AiValue;
+        format: AiValueFormat;
+        /** Signed change against the previous period, as a fraction. */
+        delta?: number | null;
+        /** Whether a rise is good - churn is `"down-is-good"`. Colouring a delta by sign alone gets this wrong half the time. */
+        deltaMeaning: "up-is-good" | "down-is-good" | "neutral";
+        hint?: string;
+    }[];
+}
+export interface AiTimelineInput {
+    title?: string;
+    /** Oldest first. */
+    events: {
+        at: string;
+        title: string;
+        detail?: string;
+        tone: AiTone;
+    }[];
+}
+export interface AiDetailsInput {
+    title?: string;
+    fields: {
+        label: string;
+        value: AiValue;
+        format: AiValueFormat;
+        tone: AiTone;
+    }[];
+}
+export interface AiStepsInput {
+    title?: string;
+    steps: {
+        title: string;
+        detail?: string;
+    }[];
+}
+export interface AiSourcesInput {
+    sources: {
+        title: string;
+        uri?: string;
+        snippet?: string;
+    }[];
+}
+/** The tools this client knows how to draw. Anything else in the stream is ignored. */
+export type AiToolName = "showTable" | "showChart" | "showMetrics" | "showTimeline" | "showDetails" | "showSteps" | "showSources";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.6.0",
+  "version": "0.9.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",
@@ -73,6 +73,7 @@
     "build:storybook": "storybook build -o storybook-static"
   },
   "devDependencies": {
+    "@connect/ai": "workspace:*",
     "@connect/data": "workspace:*",
     "@heroui/react": "^3.2.2",
     "@heroui/styles": "^3.2.2",
@@ -87,6 +88,7 @@
     "react": "19.2.8",
     "react-dom": "19.2.8",
     "storybook": "^10.5.10",
+    "streamdown": "^2.5.0",
     "tailwindcss": "^4.3.3",
     "typedoc": "^0.28.20",
     "typedoc-plugin-markdown": "^4.12.0",
@@ -98,7 +100,8 @@
     "lucide-react": ">=0.400.0",
     "motion": ">=12",
     "react": ">=19",
-    "react-dom": ">=19"
+    "react-dom": ">=19",
+    "streamdown": ">=2.5.0"
   },
   "peerDependenciesMeta": {
     "@heroui/react": {
@@ -115,6 +118,9 @@
     },
     "react-dom": {
       "optional": true
+    },
+    "streamdown": {
+      "optional": true
     }
   }
 }