@cosmoops/connect-sdk 0.1.0

package/dist/types/types.d.ts

@@ -0,0 +1,434 @@
+/**
+ * Wire types for the `/api/v1/service/*` surface - the service-partner API,
+ * and the only thing this SDK covers.
+ *
+ * Hand-written rather than generated so the published package carries no
+ * dependency on Connect's internals. `src/conformance.test.ts` type-checks
+ * these against the server's own DTOs, so drift fails the build here instead
+ * of surfacing as a runtime surprise in a partner's integration.
+ *
+ * Dates cross the wire as ISO 8601 strings and are left that way - parsing
+ * them into `Date` would be a lossy guess about what the caller wants, and
+ * `new Date(value)` is right there.
+ */
+export interface ConnectUser {
+    userId: string;
+    email: string | null;
+    emailVerified: boolean;
+    displayName: string | null;
+    organizationId: string;
+    organizationName: 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. */
+export interface SessionSubscription {
+    planId: string;
+    status: SubscriptionStatus;
+    nextBillingDate: string | null;
+    /** `status` alone cannot tell trialing from paying; both are `"active"`. */
+    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
+ * match no single defined role, including when they have no access at all.
+ */
+export interface ServiceRole {
+    role: string | null;
+    granted: string[];
+}
+export interface TokenResponse {
+    idToken: string;
+    tokenType: "Bearer";
+    /** Seconds until `idToken` expires - about 5 minutes. */
+    expiresIn: number;
+    /** Opaque, revocable. Store this; it is the only part of the response meant to outlive the callback. */
+    sessionToken: string;
+    /** Seconds until `sessionToken` expires - about 15 days. */
+    sessionTokenExpiresIn: number;
+    user: ConnectUser;
+    subscription: SessionSubscription | null;
+    serviceRole: ServiceRole;
+}
+export interface UserResponse {
+    user: ConnectUser;
+    subscription: SessionSubscription | null;
+    serviceRole: ServiceRole;
+    /** ISO 8601. Refresh proactively off this rather than waiting for a 401. */
+    sessionExpiresAt: string;
+}
+/** Verified claims from an `idToken`. */
+export interface IdTokenClaims {
+    /** Connect user id. */
+    sub: string;
+    /** Your `client_id`. */
+    aud: string;
+    iss: string;
+    exp: number;
+    iat: number;
+    org_id: string;
+    email?: string | null;
+    email_verified?: boolean;
+    [claim: string]: unknown;
+}
+export type LogoutScope = "device" | "all";
+export interface UserRolesResponse {
+    userId: string;
+    organizationId: string;
+    role: string | null;
+    granted: string[];
+}
+export interface ServicePermission {
+    id: string;
+    label: string;
+    description: string;
+}
+export interface ServiceRoleDefinition {
+    key: string;
+    name: string;
+    description: string;
+    permissions: string[];
+}
+export interface RolesResponse {
+    serviceId: string;
+    serviceKey: string | null;
+    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 interface ReadinessBlocker {
+    /**
+     * Branch on this. Typed as a union for the codes that exist today, widened
+     * with `(string & {})` because the server adds codes without a major
+     * version - an unrecognised one should be treated as blocking.
+     */
+    code: ReadinessBlockerCode | (string & {});
+    severity: "blocking" | "advisory";
+    /** Human-facing and subject to rewording. Show it, do not parse it. */
+    message: string;
+    /** Where in Connect the customer resolves this. `null` when nothing they do helps (e.g. a review in progress). */
+    resolveUrl: string | null;
+}
+export interface ReadinessResponse {
+    organizationId: string;
+    serviceId: string;
+    /** `false` if any blocker is `"blocking"`. */
+    ready: boolean;
+    readiness: {
+        source: "connect";
+        blockers: ReadinessBlocker[];
+    };
+}
+export interface PlanSeats {
+    model: "unlimited" | "fixed" | "per-seat";
+    included: number | null;
+    pricePerExtraSeat: number | null;
+}
+export interface PlanStorage {
+    model: "unlimited" | "fixed";
+    includedBytes: number | null;
+}
+export interface PlanAddonConsumable {
+    unit: string;
+    includedPerCycle: number;
+    carryForward: boolean;
+    overagePolicy: "reject" | "bill";
+    overagePricePerUnit: number | null;
+    maxOverageUnits: number | null;
+}
+export interface PlanAddon {
+    id: string;
+    name: string;
+    /** GST-exclusive, in paise. */
+    price: number;
+    consumable?: PlanAddonConsumable | null;
+}
+/**
+ * A plan feature with its label, as the **catalogue** read reports it.
+ *
+ * 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
+ * `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
+ * meant "Campaign module".
+ *
+ * `key` is carried here too, so a component doing both needs no second lookup.
+ */
+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. */
+    name: string;
+    /** Empty string when the catalog carries no description. */
+    description: string;
+}
+export interface Plan {
+    id: string;
+    name: string;
+    /**
+     * The *tier* this plan prices, independent of how often it bills. A tier's
+     * monthly and annual plans share one - so `"growth"` covers both the
+     * "Growth" monthly row and the "Growth" annual row.
+     *
+     * This is what `ConnectPlans` groups its cards by. Before it existed the
+     * grid paired plans by matching `name`, which Connect neither enforces to be
+     * unique nor keeps stable across a rename or a clone - so a catalog could
+     * silently split one tier across two cards, or show a saving computed from
+     * two plans that had nothing to do with each other.
+     */
+    planGroup: string;
+    description: string;
+    /** GST-exclusive, in paise. */
+    price: number;
+    currency: "INR";
+    billingInterval: "monthly" | "annual";
+    gstRate: number;
+    addons: PlanAddon[];
+    seats: PlanSeats;
+    storage: PlanStorage;
+    trialDays: number | null;
+    /** What this plan unlocks, labelled for display - see `PlanFeature`. */
+    features: PlanFeature[];
+}
+export interface PlansResponse {
+    plans: Plan[];
+}
+/** The plan as attached to a live subscription - a narrower view than the catalog's `Plan`. */
+export interface SubscribedPlan {
+    id: string;
+    name: string;
+    billingInterval: "monthly" | "annual";
+    price: number;
+    currency: "INR";
+    gstRate: number;
+    seats: PlanSeats;
+    /**
+     * Feature **keys** this plan unlocks. Your backend gates plan-restricted
+     * modules on this, and `ConnectFeatureGate` matches on it.
+     *
+     * Deliberately bare keys, unlike the catalogue's `Plan.features` - see
+     * `PlanFeature`. This is a contract, not a label: a key is stable and
+     * comparable, a display name is neither.
+     */
+    features: string[];
+}
+export interface AppliedDiscount {
+    source: "coupon" | "admin";
+    /** Display code - `null` for an admin-applied discount with no coupon behind it. */
+    code: string | null;
+    discountType: "percentage" | "fixed";
+    /** 1-90 for `"percentage"`; GST-exclusive paise for `"fixed"`. */
+    value: number;
+    duration: "once" | "repeating" | "forever";
+    /** Decremented each captured cycle. `null` only for `"forever"`. */
+    cyclesRemaining: number | null;
+}
+export interface SubscriptionDetail {
+    /** Deep-link target: `/billing/subscriptions/{id}` manages this subscription. */
+    id: string;
+    status: SubscriptionStatus;
+    cancelAtPeriodEnd: boolean;
+    seatCount: number;
+    addons: string[];
+    currentBillingCycle: {
+        startDate: string;
+        endDate: string;
+    } | null;
+    nextBillingDate: string | null;
+    subscribedAt: string;
+    /** `null` when no coupon or admin discount is in effect. */
+    appliedDiscount: AppliedDiscount | null;
+}
+export interface SubscriptionResponse {
+    organizationId: string;
+    serviceId: 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. */
+export interface AddonUsage {
+    addonId: string;
+    name: string;
+    /** What one unit is called - "messages", "credits", "minutes". */
+    unit: string;
+    /** Units granted at the start of each billing cycle. */
+    includedPerCycle: number;
+    /**
+     * Units left to spend.
+     *
+     * Can exceed `includedPerCycle` when `carryForward`, and goes negative only
+     * when `overagePolicy` is `"bill"` - that is accrued overage, floored at
+     * `-maxOverageUnits`.
+     */
+    balance: number;
+    carryForward: boolean;
+    overagePolicy: "reject" | "bill";
+    /** GST-exclusive paise per unit past the balance. `null` under `"reject"`. */
+    overagePricePerUnit: number | null;
+    maxOverageUnits: number | null;
+}
+export interface AddonUsageResponse {
+    organizationId: string;
+    serviceId: string;
+    /**
+     * Empty when the organization 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.
+     *
+     * Note there is no "used this cycle" figure: with `carryForward` a balance
+     * survives the cycle boundary, so `includedPerCycle - balance` can go
+     * negative and would render as a meter running backwards. Show `balance`
+     * against `includedPerCycle`.
+     */
+    addons: AddonUsage[];
+    /** ISO 8601. End of the current billing cycle, when balances are re-granted. */
+    resetsAt: string | null;
+}
+export interface ConsumeAddonInput {
+    organizationId: string;
+    addonId: string;
+    /** Whole units of the add-on's `unit`. */
+    quantity: number;
+    description?: string;
+}
+export interface ConsumeAddonResponse {
+    addonId: string;
+    consumed: number;
+    /** Remaining immediately after this call. Negative only when `overagePolicy` is `"bill"`. */
+    balance: number;
+    overageUnits: number;
+}
+export type OtpChannel = "whatsapp" | "sms";
+export interface SendOtpInput {
+    /** E.164, e.g. `+919876543210`. */
+    phoneNumber: string;
+    channel?: OtpChannel;
+}
+export interface SendOtpResponse {
+    verificationId: string;
+    status: "pending";
+    channel: OtpChannel;
+    expiresIn: number;
+    /** Test mode only. */
+    code?: string;
+}
+export interface VerifyOtpInput {
+    verificationId: string;
+    /** 6 digits. */
+    code: string;
+}
+export interface VerifyOtpResponse {
+    verificationId: string;
+    status: "pending" | "approved" | "expired" | "max_attempts_exceeded";
+    phoneNumber: string;
+}
+export interface UploadedFile {
+    id: string;
+    fileName: string;
+    mimeType: string;
+    size: number;
+    url: string;
+}
+export type ThumbnailSize = "small" | "medium" | "large";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface WriteLogInput {
+    level?: LogLevel;
+    message: string;
+    metadata?: Record<string, unknown>;
+    /** ISO 8601 or a `Date`. Defaults to now. */
+    timestamp?: string | Date;
+    /**
+     * Attribute this event to an end user, by their opaque Connect
+     * `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
+     * 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.
+     */
+    sessionToken?: string;
+}
+export interface WriteLogResponse {
+    /** `false` when the write failed - see `LogsResource.write`, which never throws. */
+    delivered: boolean;
+    /**
+     * Whether a supplied `sessionToken` resolved to a user.
+     *
+     * `false` with `delivered: true` means the line was stored unattributed - an
+     * expired or revoked token. The event is deliberately kept rather than
+     * rejected: losing telemetry because attribution failed is the worse of the
+     * two outcomes. Always `false` when no `sessionToken` was sent.
+     */
+    attributed: boolean;
+}
+/** One turn of a RAG chat. Matches the AI SDK's `UIMessage` loosely enough to pass one straight through. */
+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;
+    name: string;
+    /** Plain text, HTML already stripped server-side. */
+    description: string;
+    /** Uploaded brand icon. `null` falls back to `icon`. */
+    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. */
+    launchUrl: string | null;
+    /** True for the service 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;
+}
+export type SessionDeviceType = "desktop" | "mobile" | "tablet" | "unknown";
+export interface SessionDevice {
+    userAgent: string;
+    browser: string | null;
+    browserVersion: string | null;
+    os: string | null;
+    osVersion: string | null;
+    deviceType: SessionDeviceType;
+}
+/**
+ * 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()`
+ * returns every one of them, exactly like Connect's own account settings
+ * page does for the user themselves.
+ */
+export interface ConnectUserSession {
+    id: string;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601. */
+    lastActiveAt: string;
+    /** ISO 8601. */
+    expiresAt: string;
+    device: SessionDevice;
+    ip: string | null;
+    ipCity: string | null;
+    ipCountry: string | null;
+    /** Whether this is the session your `sessionToken` was minted from. */
+    isCurrent: boolean;
+}
+export interface SessionsListResponse {
+    items: ConnectUserSession[];
+}
+export interface RevokeOtherSessionsResponse {
+    success: true;
+    revokedCount: number;
+}
+/** Host-controlled - the SDK has no theme provider of its own. See `ConnectUserMenuProps.theme`. */
+export type ThemeMode = "light" | "dark" | "system";

package/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@cosmoops/connect-sdk",
+  "version": "0.1.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",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./server": {
+      "types": "./dist/types/server/index.d.ts",
+      "import": "./dist/esm/server/index.js",
+      "require": "./dist/cjs/server/index.js"
+    },
+    "./next": {
+      "types": "./dist/types/next/index.d.ts",
+      "import": "./dist/esm/next/index.js",
+      "require": "./dist/cjs/next/index.js"
+    },
+    "./client": {
+      "types": "./dist/types/client/index.d.ts",
+      "import": "./dist/esm/client/index.js",
+      "require": "./dist/cjs/client/index.js"
+    },
+    "./theme.css": "./dist/theme.css",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "connect-sdk": "dist/cjs/cli/bin.js"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "cosmoops",
+    "connect",
+    "sso",
+    "oauth2",
+    "billing",
+    "entitlements"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "bun run clean && tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && tsc -p tsconfig.types.json && bun run scripts/finalize-dist.ts",
+    "verify:pack": "bun run scripts/verify-pack.ts",
+    "prepublishOnly": "bun run build && bun run verify:pack",
+    "test": "bun test",
+    "storybook": "storybook dev -p 6106",
+    "build:storybook": "storybook build -o storybook-static"
+  },
+  "devDependencies": {
+    "@connect/data": "workspace:*",
+    "@heroui/react": "^3.2.2",
+    "@heroui/styles": "^3.2.2",
+    "@storybook/addon-a11y": "^10.5.10",
+    "@storybook/react-vite": "^10.5.10",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "lucide-react": "^0.545.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "storybook": "^10.5.10",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5",
+    "vite": "^8.2.2"
+  },
+  "peerDependencies": {
+    "@heroui/react": ">=3.2.0",
+    "lucide-react": ">=0.400.0",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@heroui/react": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  }
+}