@cosmoops/connect-sdk 0.7.0 → 0.15.0

package/dist/esm/server/resources/data.js

@@ -0,0 +1,369 @@
+import { ConnectError } from "../../errors.js";
+import { pathSegment, request } from "../http.js";
+import { actingAs } from "./acting-as.js";
+/**
+ * Your application's own document store - a dedicated Firestore database that
+ * only Connect can reach.
+ *
+ * You hold no Firebase credential and write no security rules. Collections are
+ * declared in the Console; an undeclared name is refused rather than created,
+ * and `workspaceId` is a path segment rather than a filter, so a query cannot
+ * cross tenants.
+ *
+ * **A query needs an index for its shape, and there are two ways to have one.**
+ * Firestore maintains a single-field index automatically, which covers one
+ * filter, or an `orderBy` on that same field. Anything wider - two filters, or
+ * a filter ordered by a different field - needs a composite index **declared
+ * on your application's Store tab**, which Connect then builds in your
+ * database. A query with no matching index is refused up front, naming the
+ * index to declare, rather than failing later with a Firestore index error
+ * pointing at a console you cannot open.
+ *
+ * **Dates are ISO-8601 strings.** The store writes what you send it, and JSON
+ * has no date type, so a `Date` must be sent as `toISOString()`. That is not a
+ * compromise: UTC ISO strings sort lexicographically in chronological order,
+ * so ordering and range filters on them behave exactly as they would on a
+ * timestamp - and Connect's own `_createdAt`/`_updatedAt` come back in the
+ * same form.
+ *
+ * **`workspaceId` is omitted for master data.** A collection declared
+ * application-scoped in the Console belongs to no workspace - one copy, owned
+ * by you, read by every tenant. Those are written with your API key only,
+ * never on behalf of a user: a write permission is something a *workspace*
+ * grants, so honouring one on shared data would give one tenant's admin reach
+ * over every other tenant's reference data.
+ *
+ * **`asUser` is how you act on behalf of a signed-in user.** Pass the opaque
+ * `sessionToken` you were given at sign-in and Connect resolves the user and
+ * their workspace from it - checking the collection's declared permission
+ * against what that member actually holds, and **ignoring `workspaceId`
+ * entirely**. Without it you are the application itself: your API key's scopes
+ * are the only gate, and the per-user permissions do not apply. The bridge
+ * (`createConnectHandler`) always passes it, which is what makes the browser
+ * path safe.
+ */
+export class DataResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Reads one document. Throws `ConnectError` with status 404 when it does not exist. */
+    get(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/data/${pathSegment(input.collection, "collection")}/${pathSegment(input.id, "id")}`,
+            query: { workspaceId: input.workspaceId },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Lists a collection, one page at a time.
+     *
+     * `filters` are ANDed. More than one, or one combined with an `orderBy` on a
+     * different field, needs a composite index declared on the Store tab - see
+     * the class note above.
+     *
+     * `limit` defaults to 50 and caps at 200. Page by passing the previous
+     * page's `nextCursor`; a `null` `nextCursor` is the end of the collection.
+     */
+    query(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/data/${pathSegment(input.collection, "collection")}`,
+            headers: actingAs(input.asUser),
+            query: {
+                workspaceId: input.workspaceId,
+                // JSON rather than flattened params: a filter *value* is typed, and
+                // `42`, `"42"` and `true` are three different queries that a flattened
+                // form collapses into one.
+                filters: input.filters?.length ? JSON.stringify(input.filters) : undefined,
+                orderBy: input.orderBy ? JSON.stringify(input.orderBy) : undefined,
+                limit: input.limit,
+                cursor: input.cursor ?? undefined,
+            },
+        });
+    }
+    /**
+     * Counts, sums and averages a filtered collection - **in Firestore**, not by
+     * reading the rows back and adding them up.
+     *
+     * That distinction is the whole point. An aggregation is billed by the index
+     * entries it scans rather than by the documents it would have returned, so a
+     * dashboard tile over ten thousand rows costs a handful of reads and stays
+     * flat as the collection grows. Paging the rows into your own process to sum
+     * them is an unbounded read, and it is what every integration does when
+     * there is no aggregate call to reach for.
+     *
+     * ```ts
+     * const { values } = await connect.data.aggregate({
+     *   workspaceId,
+     *   collection: "deals",
+     *   filters: [{ field: "outcome", op: "==", value: "won" }],
+     *   aggregations: [
+     *     { op: "count", alias: "count" },
+     *     { op: "sum", field: "value", alias: "total" },
+     *   ],
+     * });
+     * ```
+     *
+     * A `sum` or `avg` over nothing answers `null` rather than `0`, because
+     * "nothing matched" and "the total is zero" are different facts.
+     *
+     * The index it needs is the one its **filters** need plus the aggregated
+     * field - Firestore reads a sum out of the index rather than out of the
+     * documents.
+     *
+     * There is no `orderBy`, `limit` or `cursor`: the aggregate of an ordered
+     * page is the aggregate of the whole filtered set.
+     */
+    aggregate(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/data-aggregate/${pathSegment(input.collection, "collection")}`,
+            headers: actingAs(input.asUser),
+            query: {
+                workspaceId: input.workspaceId,
+                aggregations: JSON.stringify(input.aggregations.map((aggregation) => ({
+                    op: aggregation.op,
+                    field: aggregation.field ?? null,
+                    alias: aggregation.alias,
+                }))),
+                filters: input.filters?.length ? JSON.stringify(input.filters) : undefined,
+            },
+        });
+    }
+    /**
+     * Reads one collection across **every workspace at once** - your own
+     * back-office view of your whole customer base. Each row carries the
+     * `workspaceId` it came from.
+     *
+     * Needs the `data:read:all` scope, and the collection must be marked
+     * cross-workspace in the Console. There is deliberately **no `asUser`**: a
+     * scan is never available on behalf of a signed-in user, because a workspace
+     * admin is an admin of their own workspace and not of your other customers.
+     *
+     * Filtering and ordering follow the same index rules as `query`, and
+     * additionally need collection-group scope. Connect creates those from the
+     * declaration - the single-field ones when you mark a field queryable, and a
+     * group-scoped copy of every composite index the collection declares. A scan
+     * issued in the minutes after that declaration may fail while the index
+     * builds.
+     */
+    scan(input) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/data-scan/${pathSegment(input.collection, "collection")}`,
+            query: {
+                filters: input.filters?.length ? JSON.stringify(input.filters) : undefined,
+                orderBy: input.orderBy ? JSON.stringify(input.orderBy) : undefined,
+                limit: input.limit,
+                cursor: input.cursor ?? undefined,
+            },
+        });
+    }
+    /**
+     * Creates a document. Pass `id` to choose it, or omit it and one is
+     * allocated. An `id` that already exists throws with status 409 - use
+     * `replace` to overwrite deliberately.
+     */
+    create(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: `/data/${pathSegment(input.collection, "collection")}`,
+            headers: actingAs(input.asUser),
+            json: { workspaceId: input.workspaceId, id: input.id ?? null, data: input.data },
+        });
+    }
+    /** Replaces every field, creating the document if it does not exist. `_createdAt`/`_createdBy` survive. */
+    replace(input) {
+        return this.write(input, "replace");
+    }
+    /** Merges top-level fields into an existing document. Throws with status 404 if it does not exist. */
+    update(input) {
+        return this.write(input, "merge");
+    }
+    /** Idempotent - deleting a document that is not there succeeds. */
+    async delete(input) {
+        await request(this.transport, {
+            method: "DELETE",
+            path: `/data/${pathSegment(input.collection, "collection")}/${pathSegment(input.id, "id")}`,
+            query: { workspaceId: input.workspaceId },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * Applies a set of writes atomically, across as many of your collections as
+     * they name. All of them land, or none.
+     *
+     * This is the store's answer to a database transaction, and the shape is
+     * deliberate: **you never hold one**. A transaction handle passed across an
+     * HTTP boundary is a server-side lock whose duration your network controls,
+     * with Firestore's sixty-second ceiling and lock contention as the failure
+     * mode. Instead you read, decide, and commit *conditional on nothing having
+     * moved* - Connect runs the whole set as one short transaction on its side.
+     *
+     * ```ts
+     * await connect.data.commit({
+     *   workspaceId,
+     *   operations: [
+     *     { op: "create", collection: "ledger", id, data: entry },
+     *     {
+     *       op: "merge",
+     *       collection: "funds",
+     *       id: entry.fundId,
+     *       data: { balancePaise: increment(entry.amountPaise) },
+     *     },
+     *   ],
+     * });
+     * ```
+     *
+     * A precondition that no longer holds throws `ConnectError` with status 409
+     * and **writes nothing** - see `transaction`, which re-reads and retries for
+     * you. Note that the example above needs no precondition at all: an
+     * `increment` is commutative, so concurrent commits both land correctly.
+     *
+     * Returns the id each operation wrote, in order - which is how you learn the
+     * id a `create` without one was given.
+     */
+    commit(input) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/data-commit",
+            headers: actingAs(input.asUser),
+            json: {
+                workspaceId: input.workspaceId,
+                operations: input.operations.map((operation) => ({
+                    op: operation.op,
+                    collection: operation.collection,
+                    id: operation.id ?? null,
+                    data: operation.data ?? null,
+                    precondition: operation.precondition ?? null,
+                })),
+            },
+        });
+    }
+    /**
+     * Read, decide, commit - retried when the world moved underneath you.
+     *
+     * The optimistic-concurrency loop, written once. `build` reads whatever it
+     * needs and returns the operations to apply; if any precondition among them
+     * has gone stale by the time Connect looks, the commit is rejected whole and
+     * `build` runs again against fresh reads.
+     *
+     * ```ts
+     * await connect.data.transaction(async () => {
+     *   const fund = await connect.data.get({ workspaceId, collection: "funds", id });
+     *   if (!fund.data.active) throw new Error("That fund is closed.");
+     *   return [
+     *     {
+     *       op: "merge",
+     *       collection: "funds",
+     *       id,
+     *       data: { balancePaise: increment(amount) },
+     *       precondition: unchangedSince(fund),
+     *     },
+     *   ];
+     * });
+     * ```
+     *
+     * **Only a 409 is retried.** A 403 or a validation error means the operation
+     * was wrong rather than late, and retrying it would turn one clear failure
+     * into `attempts` identical ones. An error thrown by `build` itself - the
+     * closed-fund check above - is not retried either: it is a decision, not a
+     * collision.
+     *
+     * `build` must be free of side effects outside the returned operations,
+     * because it can run more than once. That is the price of not holding a
+     * lock, and it is the same contract Firestore's own `runTransaction` states
+     * for the same reason.
+     */
+    async transaction(build, options = {}) {
+        const attempts = options.attempts ?? 4;
+        let lastConflict;
+        for (let attempt = 0; attempt < attempts; attempt += 1) {
+            const operations = await build();
+            try {
+                return await this.commit({
+                    workspaceId: options.workspaceId,
+                    operations,
+                    asUser: options.asUser,
+                });
+            }
+            catch (error) {
+                if (!isConflict(error))
+                    throw error;
+                lastConflict = error;
+            }
+        }
+        throw lastConflict;
+    }
+    write(input, mode) {
+        return request(this.transport, {
+            method: "PUT",
+            path: `/data/${pathSegment(input.collection, "collection")}/${pathSegment(input.id, "id")}`,
+            headers: { "x-store-write-mode": mode, ...actingAs(input.asUser) },
+            json: { workspaceId: input.workspaceId, data: input.data },
+        });
+    }
+}
+/**
+ * A stale precondition, as opposed to any other refusal.
+ *
+ * Matched on the status rather than on the message, which is not part of any
+ * contract - and narrowly, because retrying anything else turns one honest
+ * failure into four.
+ */
+function isConflict(error) {
+    return error instanceof ConnectError && error.status === 409;
+}
+/**
+ * A raw store passthrough, for `createConnectHandler` and nothing else.
+ *
+ * The bridge relays a browser's `/data/*` and `/kv/*` request without
+ * reconstructing it into a typed call - it has a path, a body and a session
+ * token, and re-parsing them into `get`/`query`/`create` only to serialise
+ * them again would be a second implementation of the same URL grammar, drifting
+ * from this one.
+ *
+ * **Deliberately not a generic proxy.** The path is refused unless it is one
+ * of the store endpoints, so this cannot become a way to reach the rest of the
+ * application API under a browser's control - which is the property the bridge
+ * has always been careful to keep.
+ *
+ * `/data-scan/` is deliberately **not** in that set. A scan crosses every
+ * tenant, and Connect refuses one made on behalf of a user anyway - but a
+ * browser should not be able to *ask*, so the refusal happens here rather than
+ * a round trip away.
+ */
+/**
+ * The store paths a browser may reach through the bridge: documents, the
+ * key/value store, aggregations, and atomic commits. Anchored, so a path like
+ * `/data-scan/tickets` cannot slip through on a prefix match.
+ */
+const STORE_PATHS = /^\/(?:data|kv|data-aggregate)\/|^\/data-commit$/;
+// `async` so the refusal below arrives as a rejected promise rather than a
+// synchronous throw. A function typed `Promise<Response>` that sometimes
+// throws before returning one is the kind of thing a caller's `.catch()`
+// misses.
+export async function storePassthrough(transport, spec) {
+    // The query string is stripped first: the bridge appends `?workspaceId=…`
+    // to every relayed path, and an anchored match against the whole thing would
+    // reject `/data-commit?workspaceId=…` for having one.
+    if (!STORE_PATHS.test(spec.path.split("?")[0] ?? "")) {
+        throw new ConnectError({
+            status: 0,
+            code: "validation_error",
+            message: `storePassthrough only serves the store endpoints, not "${spec.path}"`,
+            endpoint: "client",
+        });
+    }
+    return request(transport, {
+        method: spec.method,
+        path: spec.path,
+        json: spec.json,
+        headers: spec.headers,
+        // The bridge hands Connect's response straight back to the browser, status
+        // and all, rather than parsing and re-encoding it.
+        raw: true,
+    });
+}

package/dist/esm/server/resources/entitlements.js

@@ -42,4 +42,45 @@ export class EntitlementsResource {
         const result = await this.getSubscription(workspaceId);
         return result.hasActiveSubscription && (result.plan?.features.includes(feature) ?? false);
     }
+    /**
+     * 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 = {}) {
+        return request(this.transport, {
+            method: "GET",
+            path: "/subscriptions",
+            query: { status: options.status, before: options.before, limit: options.limit },
+        });
+    }
+    /**
+     * 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.
+     */
+    async *iterateSubscribers(options = {}) {
+        let before;
+        do {
+            const page = await this.listSubscribers({
+                status: options.status,
+                limit: options.pageSize,
+                before,
+            });
+            for (const item of page.items)
+                yield item;
+            before = page.nextBefore ?? undefined;
+        } while (before);
+    }
 }

package/dist/esm/server/resources/identity.js

@@ -66,7 +66,10 @@ export class IdentityResource {
             sessionTokenExpiresIn: wire.session_token_expires_in,
             user: wire.user,
             subscription: wire.subscription,
-            applicationRole: wire.applicationRole,
+            role: wire.role,
+            permissions: wire.permissions,
+            staff: wire.staff,
+            audience: wire.audience,
         };
     }
     /**
@@ -136,7 +139,10 @@ export class IdentityResource {
         return {
             user: wire.user,
             subscription: wire.subscription,
-            applicationRole: wire.applicationRole,
+            role: wire.role,
+            permissions: wire.permissions,
+            staff: wire.staff,
+            audience: wire.audience,
             sessionExpiresAt: wire.session_expires_at,
         };
     }
@@ -177,7 +183,7 @@ export class IdentityResource {
             throw new ConnectError({
                 status: 0,
                 code: "missing_client_id",
-                message: "identity.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this application's Integration tab, under Connect client.",
+                message: "identity.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this application's Connect client section.",
                 endpoint: "identity",
             });
         }

package/dist/esm/server/resources/kv.js

@@ -0,0 +1,80 @@
+import { pathSegment, request } from "../http.js";
+import { actingAs } from "./acting-as.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 class KvResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * 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) {
+        return request(this.transport, {
+            method: "GET",
+            path: this.path(input.namespace, input.key),
+            query: { workspaceId: input.workspaceId },
+            headers: actingAs(input.asUser),
+        });
+    }
+    /**
+     * 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) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/kv/${pathSegment(input.namespace, "namespace")}`,
+            headers: actingAs(input.asUser),
+            query: {
+                workspaceId: input.workspaceId,
+                limit: input.limit,
+                cursor: input.cursor ?? undefined,
+            },
+        });
+    }
+    /** Sets a value, replacing whatever was there. `ttlSeconds` expires it; omit for no expiry. */
+    set(input) {
+        return request(this.transport, {
+            method: "PUT",
+            path: this.path(input.namespace, input.key),
+            headers: actingAs(input.asUser),
+            json: {
+                workspaceId: input.workspaceId,
+                value: input.value,
+                ttlSeconds: input.ttlSeconds ?? null,
+            },
+        });
+    }
+    /** Idempotent - deleting an absent key succeeds. */
+    async delete(input) {
+        await request(this.transport, {
+            method: "DELETE",
+            path: this.path(input.namespace, input.key),
+            query: { workspaceId: input.workspaceId },
+            headers: actingAs(input.asUser),
+        });
+    }
+    path(namespace, key) {
+        return `/kv/${pathSegment(namespace, "namespace")}/${pathSegment(key, "key")}`;
+    }
+}

package/dist/esm/server/resources/platform.js

@@ -0,0 +1,39 @@
+import { request } from "../http.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 class PlatformResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * 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.
+     */
+    async getCompanyProfile() {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/company-profile",
+        });
+        return result.companyProfile;
+    }
+}

package/dist/esm/server/resources/sessions.js

@@ -69,7 +69,7 @@ export class SessionsResource {
             throw new ConnectError({
                 status: 0,
                 code: "missing_client_id",
-                message: "sessions.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this application's Integration tab, under Connect client.",
+                message: "sessions.* needs `clientId`. Pass it to `new ConnectClient({ clientId, apiKey })` - it is shown in this application's Connect client section.",
                 endpoint: "sessions",
             });
         }

package/dist/esm/server/resources/workspaces.js

@@ -0,0 +1,70 @@
+import { actingAs } from "./acting-as.js";
+import { request } from "../http.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 class WorkspacesResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * 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.
+     */
+    async list(options) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/workspaces",
+            headers: actingAs(options.asUser),
+        });
+        return result.workspaces;
+    }
+    /**
+     * 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, options) {
+        return request(this.transport, {
+            method: "POST",
+            path: "/workspaces/switch",
+            headers: actingAs(options.asUser),
+            json: input,
+        });
+    }
+    /**
+     * 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.
+     */
+    async members(options) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/workspaces/members",
+            headers: actingAs(options.asUser),
+        });
+        return result.members;
+    }
+}