@cosmoops/connect-sdk 0.3.0 → 0.7.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
@@ -16,11 +16,20 @@ export interface ConnectUser {
     email: string | null;
     emailVerified: boolean;
     displayName: string | null;
-    organizationId: string;
-    organizationName: string;
+    /**
+     * 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;
+    workspaceId: string;
+    workspaceName: string;
 }
 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;
@@ -29,11 +38,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[];
 }
@@ -48,12 +57,12 @@ export interface TokenResponse {
     sessionTokenExpiresIn: number;
     user: ConnectUser;
     subscription: SessionSubscription | null;
-    serviceRole: ServiceRole;
+    applicationRole: ApplicationRole;
 }
 export interface UserResponse {
     user: ConnectUser;
     subscription: SessionSubscription | null;
-    serviceRole: ServiceRole;
+    applicationRole: ApplicationRole;
     /** ISO 8601. Refresh proactively off this rather than waiting for a 401. */
     sessionExpiresAt: string;
 }
@@ -74,28 +83,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";
+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
@@ -108,10 +117,12 @@ 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;
-    serviceId: string;
+    workspaceId: string;
+    applicationId: string;
     /** `false` if any blocker is `"blocking"`. */
     ready: boolean;
     readiness: {
@@ -148,7 +159,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
@@ -159,7 +170,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;
@@ -242,15 +253,15 @@ 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 consumable add-on's remaining balance on a workspace's subscription. */
 export interface AddonUsage {
     addonId: string;
     name: string;
@@ -273,10 +284,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.
      *
@@ -290,7 +301,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;
@@ -347,8 +358,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.
@@ -373,10 +384,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;
@@ -384,9 +395,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;
@@ -402,9 +413,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.
  */
@@ -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 `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 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 {
+    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 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
+ * 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 workspace. */
+    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 = "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
+ * `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 WorkspaceDeletionScheduledEvent {
+    workspaceId: 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: 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 WorkspaceDeletionCancelledEvent {
+    workspaceId: string;
+}
+/** The grace window closed and Connect purged the workspace. Purge your own copy. */
+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 {
+    workspaceId: string;
+    subscriptionId: string;
+    applicationId: string;
+}
+/** Maps each event type to the shape of its `data`. */
+export interface ConnectWebhookEventMap {
+    "workspace.deletion_scheduled": WorkspaceDeletionScheduledEvent;
+    "workspace.deletion_cancelled": WorkspaceDeletionCancelledEvent;
+    "workspace.deleted": WorkspaceDeletedEvent;
+    "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.3.0",
+  "version": "0.7.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",
@@ -47,7 +47,8 @@
     "node": ">=18"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "cosmoops",
@@ -82,6 +83,7 @@
     "@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",
@@ -94,8 +96,9 @@
   "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": {
@@ -104,6 +107,9 @@
     "lucide-react": {
       "optional": true
     },
+    "motion": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },