@cosmoops/connect-sdk 0.1.0

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

@@ -0,0 +1,83 @@
+import type { FetchLike } from "./http.js";
+import { AccessResource } from "./resources/access.js";
+import { AppsResource } from "./resources/apps.js";
+import { AiResource } from "./resources/ai.js";
+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 { LogsResource } from "./resources/logs.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
+     * creation.
+     *
+     * One credential does three jobs: it is the `Authorization: Bearer` value
+     * for every endpoint, the OAuth2 `client_secret` for the `/sso/*` exchange,
+     * and the HMAC key `identity.verifyIdToken()` checks against. Revoking the
+     * key revokes all three.
+     */
+    apiKey: string;
+    /** Required only for `identity.*`. Public - it goes in the authorize URL. */
+    clientId?: string;
+    /** Defaults to `https://connect.cosmoops.com`. Point at your own instance if you run one. */
+    baseUrl?: string;
+    /** Per attempt, not per call. Defaults to 20s. */
+    timeoutMs?: number;
+    /**
+     * Extra attempts after the first, for requests that are safe to repeat.
+     * Defaults to 2. See `request()` in `http.ts` for what qualifies - a bare
+     * POST never does.
+     */
+    maxRetries?: number;
+    /** Swap in your own instrumented `fetch`. Defaults to the runtime's. */
+    fetch?: FetchLike;
+}
+/**
+ * The CosmoOps Connect service-partner API.
+ *
+ * Covers `/api/v1/service/*` and nothing else - the surface a service platform
+ * integrates against. Connect's internal API is not part of this package and
+ * never will be.
+ *
+ * ```ts
+ * const connect = new ConnectClient({
+ *   apiKey: process.env.CONNECT_API_KEY!,
+ *   clientId: process.env.CONNECT_CLIENT_ID,
+ * });
+ *
+ * const session = await connect.identity.exchangeCode({ code, redirectUri });
+ * const { ready } = await connect.entitlements.getReadiness(session.user.organizationId);
+ * ```
+ *
+ * Every failure throws a `ConnectError` carrying a stable `code`. Nothing here
+ * holds state between calls, so one client can be built once and shared.
+ */
+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. */
+    readonly access: AccessResource;
+    /** The services an organization can open - for a launcher grid. */
+    readonly apps: AppsResource;
+    /** Whether a workspace may use your service, 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. */
+    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. */
+    readonly logs: LogsResource;
+    /** This Connect account's own login sessions - account-wide, not scoped to this service. Requires the `sessions:manage` scope. */
+    readonly sessions: SessionsResource;
+    constructor(options: ConnectClientOptions);
+}
+/** Kept in step with `package.json` by `sdk.test.ts`. */
+export declare const SDK_VERSION = "0.1.0";

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

@@ -0,0 +1,67 @@
+import type { ConnectClient } from "./client.js";
+/**
+ * What the bridge needs from the partner's own session, and what it may change
+ * about it.
+ *
+ * Deliberately an interface rather than a cookie this SDK sets: the partner
+ * already has a session mechanism, and a second one owned by a dependency
+ * would be a second source of truth about who is signed in.
+ */
+export interface ConnectSessionStore {
+    /** The Connect `sessionToken` for this caller, or `null` if signed out. */
+    read(request: Request): Promise<string | null> | string | null;
+    /**
+     * Persist a freshly exchanged session. Supplying this turns on `/signin` and
+     * `/callback`, so the handler runs the whole OAuth round trip instead of
+     * leaving you to write the callback route - see `createConnectHandler`.
+     * Set cookies on `response`.
+     */
+    write?(request: Request, response: Response, sessionToken: string): Promise<void> | void;
+    /** Called on sign-out, before Connect is told. Clear your own session here - set cookies on `response`. */
+    clear?(request: Request, response: Response): Promise<void> | void;
+}
+export interface ConnectHandlerOptions {
+    client: ConnectClient;
+    session: ConnectSessionStore;
+    /**
+     * Where this handler is mounted, so it can strip the prefix off incoming
+     * paths. Must match `basePath` on `<ConnectProvider>`. Defaults to
+     * `/api/connect`.
+     */
+    basePath?: string;
+    /**
+     * Where `/callback` sends the user when the request carried no `next`.
+     * Defaults to `/`.
+     */
+    defaultRedirect?: string;
+    /**
+     * Name of the short-lived cookie holding the OAuth `state`. Only change it
+     * if it collides with something you already set.
+     */
+    stateCookieName?: string;
+}
+/**
+ * The browser half of this SDK cannot hold an API key - so it does not.
+ *
+ * `@cosmoops/connect-sdk/client` talks only to your own origin, and this
+ * handler is what answers. It lives in your backend, holds the key, and
+ * exposes a fixed, named set of reads plus sign-out and session revocation.
+ * Nothing here proxies arbitrary paths: a generic passthrough would hand the
+ * browser your whole API surface under your credentials, which is the same
+ * leak with extra steps.
+ *
+ * Framework-agnostic - `Request` in, `Response` out, so it mounts anywhere
+ * that shape exists.
+ *
+ * ```ts
+ * // app/api/connect/[...route]/route.ts
+ * const handler = createConnectHandler({ client, session });
+ * export { handler as GET, handler as POST };
+ * ```
+ *
+ * Every route resolves the organization 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`
+ * is exactly that hole.
+ */
+export declare function createConnectHandler(options: ConnectHandlerOptions): (request: Request) => Promise<Response>;

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

@@ -0,0 +1,52 @@
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface RequestSpec {
+    method: "GET" | "POST";
+    /** Relative to the API base, e.g. `/plans`. */
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    /** Sent as JSON. Mutually exclusive with `form` and `multipart`. */
+    json?: unknown;
+    /** Sent as `application/x-www-form-urlencoded` - what the `/sso/*` endpoints take. */
+    form?: Record<string, string | undefined>;
+    multipart?: FormData;
+    headers?: Record<string, string>;
+    /** Bearer API key (default), or none - the `/sso/*` endpoints authenticate inside the form body instead. */
+    auth?: "bearer" | "none";
+    /** Skip JSON parsing and hand back the raw `Response` - for streaming endpoints. */
+    raw?: boolean;
+    signal?: AbortSignal;
+}
+export interface TransportOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+    maxRetries: number;
+    fetch: FetchLike;
+    userAgent: string;
+}
+/**
+ * One id, safe to interpolate into a request path.
+ *
+ * `encodeURIComponent` alone is not enough, and the gap is easy to miss: it
+ * leaves `.` untouched, so an id of `".."` survives into the URL and the URL
+ * parser then collapses the segment *before* it - `/drive/files/../url`
+ * resolves to `/drive/url`, a different endpoint reached under the same API
+ * key. Slashes are encoded, so the traversal cannot chain past one segment,
+ * but one is already an endpoint the caller did not ask for.
+ *
+ * Relevant whenever an id reaches the SDK from a partner's own end users,
+ * which is the normal case for a file id.
+ */
+export declare function pathSegment(value: string, name: string): string;
+/**
+ * The one place a request leaves this SDK: builds it, applies the per-attempt
+ * timeout, retries what is safe to retry, and turns every failure into a
+ * `ConnectError`.
+ *
+ * **On retries.** Only idempotent requests are retried without a caller
+ * opt-in: every `GET`, plus any `POST` carrying an `Idempotency-Key` (the
+ * resources that mutate - `billing.consumeAddon`, `otp.send` - always set
+ * one). A bare `POST` is attempted exactly once, because a 429 or a 504 says
+ * nothing about whether the server already did the work.
+ */
+export declare function request<T>(options: TransportOptions, spec: RequestSpec): Promise<T>;

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

@@ -0,0 +1,15 @@
+/**
+ * Server-only half of `@cosmoops/connect-sdk`.
+ *
+ * Everything here handles the API key, so none of it may run in a browser.
+ * The browser half is `@cosmoops/connect-sdk/client`, which talks to your own
+ * origin and reaches Connect through `createConnectHandler` below.
+ */
+export { ConnectClient, DEFAULT_BASE_URL, SDK_VERSION } from "./client.js";
+export type { ConnectClientOptions } from "./client.js";
+export { createConnectHandler } from "./handler.js";
+export type { ConnectHandlerOptions, ConnectSessionStore } from "./handler.js";
+export { createState } from "./resources/identity.js";
+export type { AuthorizeUrlInput, ExchangeCodeInput } from "./resources/identity.js";
+export type { UploadInput } from "./resources/drive.js";
+export type { FetchLike } from "./http.js";

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

@@ -0,0 +1,17 @@
+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. */
+export declare class AccessResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Re-check one member's role and granted permissions, live. The same block
+     * `identity.getUser()` returns - use this when you need only the role axis
+     * and already know who the user is.
+     */
+    getUserRoles(userId: string, input: {
+        organizationId: string;
+    }): Promise<UserRolesResponse>;
+    /** Your service's own permission catalog and role definitions - the definitions `getUserRoles` resolves against. */
+    listRoles(): Promise<RolesResponse>;
+}

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

@@ -0,0 +1,24 @@
+import { type TransportOptions } from "../http.js";
+import type { ChatMessage } from "../../types.js";
+/** RAG chat and structured extraction against an organization's data. */
+export declare class AiResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * RAG-grounded chat. Returns the raw streaming `Response` rather than a
+     * parsed body - this endpoint answers with server-sent events, and buffering
+     * it here would throw away the only reason to stream. Pipe
+     * `response.body` onward, or hand it to the AI SDK's own reader.
+     */
+    chat(input: {
+        organizationId: string;
+        messages: ChatMessage[];
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /** Extract structured JSON from a file or image URL, against a platform extraction schema referenced by id. */
+    extract<T = unknown>(input: {
+        schemaId: string;
+        fileUrl: string;
+    }): Promise<T>;
+}

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

@@ -0,0 +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. */
+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.
+     */
+    list(organizationId: string): Promise<OrganizationApp[]>;
+}

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

@@ -0,0 +1,41 @@
+import { type TransportOptions } from "../http.js";
+import type { AddonUsageResponse, ConsumeAddonInput, ConsumeAddonResponse, PlansResponse } from "../../types.js";
+/** The plan catalog you sell, and metering usage back against a subscriber's add-on balance. */
+export declare class BillingResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Your service'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
+     * independently of the instance it talks to. Without the coercion a partner
+     * pointed at a Connect that has not upgraded yet renders a feature list of
+     * blanks - which is exactly what happened. See `normalizePlanFeatures`.
+     */
+    listPlans(): Promise<PlansResponse>;
+    /**
+     * What is left of every consumable add-on on an organization's
+     * subscription - the read half of `consumeAddon`.
+     *
+     * Needs a key scoped to `addons:read`, which is separate from
+     * `addons:consume` on purpose: a key that only renders a usage meter should
+     * not also be able to spend the balance down.
+     *
+     * 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>;
+    /**
+     * Debit a consumable add-on's per-cycle balance on behalf of an
+     * organization'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
+     * key double-debits. Pass your own when the natural unit of work is
+     * something you can name (a job id, a message id) and might submit twice.
+     */
+    consumeAddon(input: ConsumeAddonInput, options?: {
+        idempotencyKey?: string;
+    }): Promise<ConsumeAddonResponse>;
+}

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

@@ -0,0 +1,26 @@
+import { type TransportOptions } from "../http.js";
+import type { ThumbnailSize, UploadedFile } from "../../types.js";
+export interface UploadInput {
+    organizationId: 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. */
+    fileName?: string;
+    /** Target folder. Omit for the Drive root. */
+    parentId?: string;
+}
+/** Files in an organization'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;
+    }): Promise<string>;
+    /** A signed URL for the thumbnail. Same lifetime caveat as `getFileUrl`. */
+    getPreviewUrl(fileId: string, input: {
+        organizationId: string;
+        size?: ThumbnailSize;
+    }): Promise<string>;
+}

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

@@ -0,0 +1,31 @@
+import { type TransportOptions } from "../http.js";
+import type { ReadinessResponse, SubscriptionResponse } from "../../types.js";
+/**
+ * The two checks worth making on every request: may this workspace be here at
+ * all, and what is it paying for.
+ */
+export declare class EntitlementsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Every gate Connect owns between an organization and your service -
+     * subscription, KYC/KYB, a chargeable payment method, seat headroom -
+     * resolved in one call.
+     *
+     * Blocked users are the point: each blocker carries a `resolveUrl` into the
+     * 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>;
+    /** The live plan and subscription, including `plan.features`. */
+    getSubscription(organizationId: string): Promise<SubscriptionResponse>;
+    /**
+     * Whether an active subscription unlocks a plan feature - the check that
+     * gates a plan-restricted module.
+     *
+     * Deliberately `false` rather than a throw when there is no subscription at
+     * 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>;
+}

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

@@ -0,0 +1,76 @@
+import { type TransportOptions } from "../http.js";
+import type { IdTokenClaims, LogoutScope, TokenResponse, UserResponse } from "../../types.js";
+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. */
+    codeChallenge?: string;
+}
+export interface ExchangeCodeInput {
+    code: string;
+    /** Must be byte-identical to the one sent to `authorizeUrl()`. */
+    redirectUri: string;
+    codeVerifier?: string;
+}
+/** A URL-safe random string, suitable for `state` or a PKCE verifier. */
+export declare function createState(byteLength?: number): string;
+/**
+ * "Login with Connect" - the OAuth2 handshake, and the session that outlives
+ * it.
+ *
+ * The whole flow is five calls: `authorizeUrl` to send them out,
+ * `exchangeCode` when they come back, `verifyIdToken` once, then `getUser` on
+ * each later request and `logout` at the end.
+ */
+export declare class IdentityResource {
+    private readonly transport;
+    private readonly clientId;
+    private readonly appBaseUrl;
+    constructor(transport: TransportOptions, clientId: string | null, appBaseUrl: string);
+    /** Step 1 - the URL to send the user's browser to. */
+    authorizeUrl(input: AuthorizeUrlInput): string;
+    /** Step 2 - trade the one-time `code` for a session. Server-side only. */
+    exchangeCode(input: ExchangeCodeInput): Promise<TokenResponse>;
+    /**
+     * Step 3 - verify the `id_token` once, then discard it.
+     *
+     * HS256 over `header.payload`, keyed with your API key, plus the `exp` and
+     * `aud` checks. There is no JWKS to fetch: Connect stores only your key's
+     * sha256 hash, so the token is signed with the shared secret rather than an
+     * asymmetric key. Signature comparison goes through WebCrypto's own
+     * `verify`, which is why this is async - hand-rolling the compare is the
+     * step integrations most often get wrong.
+     */
+    verifyIdToken(idToken: string): Promise<IdTokenClaims>;
+    /**
+     * Step 4 - who is signed in, right now. Same blocks as `exchangeCode`,
+     * re-resolved live, so a role change or a lapsed subscription shows up here
+     * without another sign-in.
+     *
+     * Any `ConnectError` with `isSessionExpired` means send them back through
+     * `authorizeUrl()`.
+     */
+    getUser(sessionToken: string): Promise<UserResponse>;
+    /**
+     * Step 5 - end the sign-in immediately rather than leaving it valid for the
+     * 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
+     * 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.
+     *
+     * Always succeeds. An unknown or already-revoked token is an
+     * indistinguishable no-op, so there is nothing to branch on.
+     */
+    logout(sessionToken: string, options?: {
+        scope?: LogoutScope;
+    }): Promise<void>;
+    private post;
+    private requireClientId;
+    private tokenError;
+}

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

@@ -0,0 +1,20 @@
+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. */
+export declare class LogsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Never throws. A logging call that takes down the code path it was
+     * observing is worse than a lost line, so a failure here is swallowed and
+     * 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
+     * from your API key, the user from that token, which Connect checks was
+     * minted for your service 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.
+     */
+    write(input: WriteLogInput): Promise<WriteLogResponse>;
+}

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

@@ -0,0 +1,17 @@
+import { type TransportOptions } from "../http.js";
+import type { SendOtpInput, SendOtpResponse, VerifyOtpInput, VerifyOtpResponse } from "../../types.js";
+/** WhatsApp/SMS phone verification. */
+export declare class OtpResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Send a code. As with `billing.consumeAddon`, an `Idempotency-Key` always
+     * goes along - a retried send would otherwise deliver a second message and
+     * invalidate the first code the user is looking at.
+     */
+    send(input: SendOtpInput, options?: {
+        idempotencyKey?: string;
+    }): Promise<SendOtpResponse>;
+    /** Check a 6-digit code against a `verificationId`. */
+    verify(input: VerifyOtpInput): Promise<VerifyOtpResponse>;
+}

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

@@ -0,0 +1,37 @@
+import { type TransportOptions } from "../http.js";
+import type { ConnectUserSession, RevokeOtherSessionsResponse } from "../../types.js";
+/**
+ * This Connect account's own login sessions - device, approximate location,
+ * 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.
+ * `list()` returns every session on the account, including ones that
+ * originated from a completely different, unrelated service. 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.
+ *
+ * Authenticated like `identity.*` - `client_id`+`client_secret`, never a
+ * Bearer key - because every call here is really "resolve identity from a
+ * `sessionToken`", the same shape `identity.getUser`/`identity.logout` are.
+ */
+export declare class SessionsResource {
+    private readonly transport;
+    private readonly clientId;
+    constructor(transport: TransportOptions, clientId: string | null);
+    /** Every active session on the account behind `sessionToken`. `isCurrent` marks the one it was minted from. */
+    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
+     * originated from that same browser, same as Connect's own "sign out this
+     * device".
+     */
+    revoke(sessionToken: string, sessionId: string): Promise<void>;
+    /** "Sign out everywhere else" - keeps the session `sessionToken` was minted from, ends every other one. */
+    revokeOthers(sessionToken: string): Promise<RevokeOtherSessionsResponse>;
+    private post;
+    private requireClientId;
+}