@cosmoops/connect-sdk 0.7.0 → 0.15.0

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

@@ -1,5 +1,5 @@
 import { type TransportOptions } from "../http.js";
-import type { ReadinessResponse, SubscriptionResponse } from "../../types.js";
+import type { ApplicationSubscriber, ReadinessResponse, SubscribersResponse, 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.
@@ -28,4 +28,36 @@ export declare class EntitlementsResource {
      * should not need a try/catch around it.
      */
     hasFeature(workspaceId: string, feature: string): Promise<boolean>;
+    /**
+     * One page of the workspaces subscribed to your application, newest first.
+     *
+     * The inverse of `getSubscription`, which asks about one workspace you
+     * already know. This asks who your subscribers *are* - what a partner
+     * dashboard, an MRR total or a churn report is built on.
+     *
+     * Rate-limited far more tightly than the per-workspace read (10/min per
+     * key, against 60): it walks your whole subscriber base and is a reporting
+     * call, not a per-request gate. Use `getSubscription` in a hot path.
+     *
+     * Your application is resolved from the API key, so there is no parameter
+     * for it and no way to ask about anyone else's.
+     */
+    listSubscribers(options?: {
+        status?: ApplicationSubscriber["status"];
+        /** Cursor from a previous page's `nextBefore`. */
+        before?: string;
+        /** 1..100, default 25. */
+        limit?: number;
+    }): Promise<SubscribersResponse>;
+    /**
+     * Every subscriber, paged through for you.
+     *
+     * An async generator rather than an array: a large subscriber base is
+     * exactly where an accidental full materialisation hurts, and `for await`
+     * reads the same as a loop over one page.
+     */
+    iterateSubscribers(options?: {
+        status?: ApplicationSubscriber["status"];
+        pageSize?: number;
+    }): AsyncGenerator<ApplicationSubscriber>;
 }

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

@@ -0,0 +1,63 @@
+import { type TransportOptions } from "../http.js";
+import type { KvEntry, KvPage } from "../../types.js";
+/**
+ * Your application's key/value store - small values addressed by namespace and
+ * key, per workspace.
+ *
+ * Use it for what a document store is bad at: a feature flag, a cached
+ * computation, a counter, a draft nobody needs to query. Anything you want to
+ * *find* rather than *fetch* belongs in `data`.
+ *
+ * Namespaces are declared in the Console exactly like collections. Keys are
+ * `[A-Za-z0-9_-]` up to 64 characters, and values are JSON up to 128 KB.
+ *
+ * `asUser` behaves exactly as it does on `DataResource` - pass a signed-in
+ * user's `sessionToken` and Connect derives the user and workspace from it,
+ * checking the namespace's declared permission against their live roles.
+ */
+export declare class KvResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * Reads one key. Throws `ConnectError` with status 404 when the key is
+     * absent **or expired** - expiry is evaluated on read, so there is no window
+     * where a stale value is still served.
+     */
+    get(input: {
+        workspaceId?: string;
+        namespace: string;
+        key: string;
+        asUser?: string;
+    }): Promise<KvEntry>;
+    /**
+     * Pages a namespace in key order.
+     *
+     * Expired entries are filtered out after paging, so a page can come back
+     * shorter than `limit` while still having a `nextCursor` - treat
+     * `nextCursor` as the only signal that more keys exist, never an empty page.
+     */
+    list(input: {
+        workspaceId?: string;
+        namespace: string;
+        limit?: number;
+        cursor?: string | null;
+        asUser?: string;
+    }): Promise<KvPage>;
+    /** Sets a value, replacing whatever was there. `ttlSeconds` expires it; omit for no expiry. */
+    set(input: {
+        workspaceId?: string;
+        namespace: string;
+        key: string;
+        value: unknown;
+        ttlSeconds?: number;
+        asUser?: string;
+    }): Promise<KvEntry>;
+    /** Idempotent - deleting an absent key succeeds. */
+    delete(input: {
+        workspaceId?: string;
+        namespace: string;
+        key: string;
+        asUser?: string;
+    }): Promise<void>;
+    private path;
+}

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

@@ -0,0 +1,32 @@
+import { type TransportOptions } from "../http.js";
+import type { CompanyProfile } from "../../types.js";
+/**
+ * Facts about the platform itself, rather than about a workspace or a user.
+ *
+ * One method today, and the resource exists anyway rather than hanging
+ * `getCompanyProfile` off `identity` or `workspaces`: neither of those is
+ * what it is about. This answers "who operates the thing my application runs
+ * on", which is a different subject from every other resource here, and a
+ * misfiled method is harder to find than an obvious one-method namespace.
+ */
+export declare class PlatformResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * The operating entity's legal identity and its DPDP grievance channel.
+     *
+     * Takes no `workspaceId` and takes no `asUser` - the answer is the same for
+     * every tenant and every caller, because it is a fact about the platform.
+     *
+     * Returns the inner `companyProfile` rather than the envelope, matching
+     * `apps.list()` and `billing.listPlans()`: the wrapper is a wire detail, and
+     * every caller would destructure it on the next line.
+     *
+     * **Do not copy the result into your own configuration.** Cache it if you
+     * render it on a hot path - Connect already sends
+     * `s-maxage=3600, stale-while-revalidate=86400` - but the reason this is an
+     * endpoint at all is that a grievance officer copied into `.env` goes stale
+     * without anyone finding out.
+     */
+    getCompanyProfile(): Promise<CompanyProfile>;
+}

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

@@ -0,0 +1,55 @@
+import { type TransportOptions } from "../http.js";
+import type { ConnectWorkspaceMember, UserWorkspace, WorkspaceSwitchResult } from "../../types.js";
+/**
+ * Which workspaces the signed-in user belongs to, moving between them, and who
+ * else is on the team.
+ *
+ * **Every call here needs `asUser`** - the signed-in user's opaque
+ * `sessionToken`. There is no application-wide form of any of these: they take
+ * no `userId` and no `workspaceId`, and resolve both from the token. That is
+ * what makes the whole module safe to reach from a browser through
+ * `createConnectHandler`, and it is why a partner cannot enumerate another
+ * tenant's team with their own API key.
+ */
+export declare class WorkspacesResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * The workspaces this user could switch to.
+     *
+     * Rows carry `inAudience` and `subscribed` so a switcher can show a
+     * workspace it cannot select, with the reason. Hiding it instead reads as
+     * data loss to the person who owns it.
+     */
+    list(options: {
+        asUser: string;
+    }): Promise<UserWorkspace[]>;
+    /**
+     * Moves this session to another workspace, returning a **new session
+     * token**. The one you passed is revoked.
+     *
+     * Persist the result before navigating - dropping it signs the user out,
+     * because the old token no longer works.
+     *
+     * Throws with status 404 when the workspace does not exist *or* the user is
+     * not a member (deliberately indistinguishable), and 403 when it is outside
+     * your audience, requires an MFA factor they have not enrolled, or is the
+     * workspace they are already on.
+     */
+    switch(input: {
+        workspaceId: string;
+    }, options: {
+        asUser: string;
+    }): Promise<WorkspaceSwitchResult>;
+    /**
+     * The team of the workspace this session is on.
+     *
+     * Members carry permissions already resolved for *your* application, not raw
+     * Connect roles - so you never reimplement Connect's role resolution, and
+     * you are told nothing about the customer's Connect account beyond what your
+     * application needs.
+     */
+    members(options: {
+        asUser: string;
+    }): Promise<ConnectWorkspaceMember[]>;
+}

package/dist/types/store.d.ts

@@ -0,0 +1,96 @@
+import type { StoreDocument, StoreFieldTransform, StoreOrderBy, StorePrecondition, StoreQueryFilter } from "./types.js";
+/**
+ * Building blocks for `data.commit` - the transform sentinels, and the two
+ * ways to say "only if nothing has moved".
+ *
+ * Isomorphic and dependency-free, so a Server Component and a client component
+ * building the same write use the same constructors. They are functions rather
+ * than object literals you write by hand because the sentinel shape is an
+ * encoding, not an API: `{ __transform: "increment", by: 1 }` is what goes over
+ * the wire, and nothing outside this file should have to know that.
+ */
+/**
+ * Add to a number, atomically.
+ *
+ * **The one operation you genuinely cannot do yourself.** Increments are
+ * commutative, so two concurrent `increment(500)` calls both land - where
+ * read-add-write from your own process loses one of them however carefully it
+ * retries, because the read and the write are two round trips with a gap in
+ * between. Use this for balances, counters and tallies, and reach for a
+ * precondition only when the new value depends on the old one in a way
+ * addition cannot express.
+ *
+ * Negative to subtract; there is no separate `decrement`.
+ */
+export declare function increment(by: number): StoreFieldTransform;
+/** Connect's own write time, rather than a clock reading from your process. */
+export declare function serverTimestamp(): StoreFieldTransform;
+/** Adds the values not already in the array. Order is not preserved. */
+export declare function arrayUnion(...values: unknown[]): StoreFieldTransform;
+/** Removes every occurrence of each value. */
+export declare function arrayRemove(...values: unknown[]): StoreFieldTransform;
+/**
+ * Removes the field entirely.
+ *
+ * `merge` only - a `replace` already drops every field it does not list, so
+ * asking it to delete one is a contradiction rather than a narrowing.
+ */
+export declare function deleteField(): StoreFieldTransform;
+/**
+ * "Only if this document has not changed since I read it."
+ *
+ * Pass the document a read returned, and the precondition is built from its
+ * `_updateTime`. Taking the document rather than the timestamp is deliberate:
+ * a caller who has to reach for `doc.data._updateTime` themselves is one typo
+ * away from a precondition that silently does nothing.
+ *
+ * Throws rather than degrading when the document carries no `_updateTime` -
+ * that only happens for a document you built yourself rather than read, and a
+ * precondition that quietly became "no precondition" is worse than a crash at
+ * the call site.
+ */
+export declare function unchangedSince(document: StoreDocument): StorePrecondition;
+/** "Only if this document exists" / "only if it does not." */
+export declare function documentExists(exists?: boolean): StorePrecondition;
+/** How one field sits in a composite index. `array-contains` is a position, not an order. */
+export type StoreIndexDirection = "asc" | "desc" | "array-contains";
+export interface StoreIndexField {
+    field: string;
+    direction: StoreIndexDirection;
+}
+/**
+ * The composite index a query shape needs, or `null` when Firestore's
+ * automatic single-field indexes already serve it.
+ *
+ * Use it to generate your Store tab declarations from the queries your code
+ * actually makes, rather than transcribing them by hand and discovering the
+ * gap in production:
+ *
+ * ```ts
+ * const needed = MY_QUERY_SHAPES.map(storeIndexFor).filter(Boolean);
+ * ```
+ *
+ * **Field order is Firestore's, not yours.** Equality fields first (sorted, so
+ * the order you passed them in cannot produce two different declarations for
+ * one query), then the `array-contains` field, then the field the query orders
+ * by. Declaring the same shape twice in two orders builds two indexes, one of
+ * which is dead weight on every document write.
+ *
+ * Connect runs the same derivation server-side and is the authority: a query
+ * with no matching declared index is refused with the index it needs spelled
+ * out, so a disagreement here surfaces on the first call rather than silently.
+ *
+ * Throws for a query Firestore cannot serve at all - two `array-contains`
+ * filters, ranges over two fields, or a range ordered by a different field.
+ */
+export declare function storeIndexFor(query: {
+    filters?: readonly StoreQueryFilter[];
+    orderBy?: StoreOrderBy | null;
+}): StoreIndexField[] | null;
+/**
+ * An index as one comparable string - `"status:asc,createdAt:desc"`.
+ *
+ * Deduplicate a generated list on this before declaring it: a dozen query
+ * shapes across a screen usually collapse to two or three distinct indexes.
+ */
+export declare function storeIndexSignature(fields: readonly StoreIndexField[]): string;