@substrat-run/control-plane-client 0.1.0 → 0.1.1

package/dist/client.js

@@ -0,0 +1,122 @@
+import { denialQuery } from '@substrat-run/contracts';
+import { ControlPlaneError, ControlPlaneTransport } from './transport.js';
+import { identityTenantsResponse } from './identity-tenants.js';
+// The error is raised by the transport; this is the path callers (and `errors.ts`)
+// have always imported it from.
+export { ControlPlaneError };
+export class ControlPlaneClient extends ControlPlaneTransport {
+    constructor(options) {
+        super(options);
+    }
+    // -- registration (idempotent, mirrors HostAdmin) --------------------------
+    createTenant(input) {
+        return this.call('/tenants', { method: 'POST', body: JSON.stringify(input) });
+    }
+    grantEntitlement(tenantId, key, plan) {
+        return this.call(`/tenants/${tenantId}/entitlements/${key}`, {
+            method: 'PUT',
+            body: plan === undefined ? undefined : JSON.stringify(plan),
+        });
+    }
+    provisionScope(input) {
+        return this.call('/scopes', { method: 'POST', body: JSON.stringify(input) });
+    }
+    /**
+     * Confirm the scope exists here, moving the directory row provisioning → active.
+     *
+     * In this (push) direction the vertical has already built the scope locally, so
+     * registering and confirming are the same moment — but they stay two calls so
+     * `provisionScope` means one thing everywhere, and so the directory is never the
+     * one deciding a scope is ready (K-31).
+     */
+    activateScope(tenantId, scopeId) {
+        return this.call(`/tenants/${tenantId}/scopes/${scopeId}/activate`, { method: 'POST' });
+    }
+    // -- reads used for gating -------------------------------------------------
+    getTenant(tenantId) {
+        return this.call(`/tenants/${tenantId}`, undefined, true);
+    }
+    getScopeRecord(tenantId, scopeId) {
+        return this.call(`/tenants/${tenantId}/scopes/${scopeId}`, undefined, true);
+    }
+    listEntitlements(tenantId) {
+        return this.call(`/tenants/${tenantId}/entitlements`);
+    }
+    /**
+     * The tenants a login builds for, each flagged with whether it holds the `builder`
+     * entitlement — the builder studio's membership read (builder-plane.md §4). `externalId`
+     * is the login's OIDC subject. Service-token gated: an unset token is refused by the
+     * plane, never bypassed.
+     *
+     * The answer is PARSED, not asserted: a plane that renamed `entitled`, or answered an
+     * `{ error }` body with a 200, would hand a cast `entitled: undefined` — falsy, so the
+     * studio would lock the tenant out with the ordinary "not enabled" page and nothing
+     * anywhere would say the directory had changed shape. A refused parse throws instead.
+     * The message names the shape that was wrong, never the body — the body is directory
+     * facts about a person's tenants.
+     */
+    async identityTenants(externalId) {
+        const res = await this.send('/internal/builder/identity-tenants', {
+            method: 'POST',
+            body: JSON.stringify({ externalId }),
+        });
+        const parsed = identityTenantsResponse.safeParse(await res.json().catch(() => null));
+        if (!parsed.success) {
+            throw new ControlPlaneError(res.status, `identity-tenants returned an unexpected shape: ${parsed.error.message}`);
+        }
+        return parsed.data.tenants;
+    }
+    // -- read-only scope-DB introspection (§5.4 admin-query RPC) ----------------
+    /** Every table in the scope's own database, with row counts (Data view). */
+    listScopeTables(tenantId, scopeId) {
+        return this.call(`/tenants/${tenantId}/scopes/${scopeId}/tables`);
+    }
+    /** A bounded page of one table of the scope's database. */
+    readScopeTable(tenantId, scopeId, input) {
+        const q = new URLSearchParams({ limit: String(input.limit), offset: String(input.offset) });
+        return this.call(`/tenants/${tenantId}/scopes/${scopeId}/tables/${encodeURIComponent(input.table)}?${q}`);
+    }
+    /** One read-only SQL statement against the scope's database — the console (#219). */
+    queryScope(tenantId, scopeId, input) {
+        return this.call(`/tenants/${tenantId}/scopes/${scopeId}/query`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    // -- the denial log (K-35, #867) --------------------------------------------
+    /**
+     * The scope's recorded permission refusals, bucketed per (actor, permission) with the
+     * window's own facts beside them — the view to open first, because the raw log's
+     * volume is attacker-influenceable and a prober can flood a newest-first page.
+     */
+    summarizeDenials(tenantId, scopeId, filter) {
+        return this.call(`/tenants/${tenantId}/scopes/${scopeId}/denials/summary${denialQuery(filter)}`);
+    }
+    /** The raw rows behind a bucket, newest first. */
+    listDenials(tenantId, scopeId, filter) {
+        return this.call(`/tenants/${tenantId}/scopes/${scopeId}/denials${denialQuery(filter)}`);
+    }
+    /**
+     * The gate. Throws unless the tenant is active AND the scope exists and is
+     * active — the same fail-closed logic the kernel's `validateScopeAccess`
+     * applies locally, so a tenant-level cascade suspend bites too, not just a
+     * per-scope one. Call it before handing a request to the local scope host.
+     */
+    async assertScopeActive(tenantId, scopeId) {
+        const [tenant, scope] = await Promise.all([
+            this.getTenant(tenantId),
+            this.getScopeRecord(tenantId, scopeId),
+        ]);
+        if (!tenant)
+            throw new ControlPlaneError(403, `unknown tenant: ${tenantId}`);
+        if (tenant.status !== 'active') {
+            throw new ControlPlaneError(403, `tenant not active (status: ${tenant.status}): ${tenantId}`);
+        }
+        if (!scope)
+            throw new ControlPlaneError(403, `unknown scope for tenant: (${tenantId}, ${scopeId})`);
+        if (scope.status !== 'active') {
+            throw new ControlPlaneError(403, `scope not active (status: ${scope.status}): ${scopeId}`);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/headers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The header names a caller and the control plane agree on. They live in the client
+ * package because it is the side every caller can import without taking the server with
+ * it; `@substrat-run/control-plane-api` re-exports them from its `auth.ts`, so the server
+ * and the clients read one spelling (#971).
+ */
+/** Header the dev stub reads. Mirrors the demos' `x-principal` dev affordance. */
+export declare const DEV_ACTOR_HEADER = "x-platform-actor";
+/** Header a SERVICE (a vertical registering itself) presents — not a staff subject. */
+export declare const SERVICE_TOKEN_HEADER = "x-service-token";
+/**
+ * Header naming the tenant a caller ACTS FOR. For a builder session it selects the
+ * workspace (`--tenant`) the builder reader narrows to. For a staff/service caller it is
+ * the slug-resolution pin (#417): vertical routes form `<tenantSlug>/<slug>` from it the
+ * way a pinned push does, so `versions <bare> --tenant <t>` over a service token reaches
+ * the same registry row a builder session would. It never widens access — staff reach
+ * everything already, and for builders the tenant must be one of their memberships.
+ */
+export declare const TENANT_HEADER = "x-substrat-tenant";
+//# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD,uFAAuF;AACvF,eAAO,MAAM,oBAAoB,oBAAoB,CAAC;AAEtD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,sBAAsB,CAAC"}

package/dist/headers.js

@@ -0,0 +1,20 @@
+/**
+ * The header names a caller and the control plane agree on. They live in the client
+ * package because it is the side every caller can import without taking the server with
+ * it; `@substrat-run/control-plane-api` re-exports them from its `auth.ts`, so the server
+ * and the clients read one spelling (#971).
+ */
+/** Header the dev stub reads. Mirrors the demos' `x-principal` dev affordance. */
+export const DEV_ACTOR_HEADER = 'x-platform-actor';
+/** Header a SERVICE (a vertical registering itself) presents — not a staff subject. */
+export const SERVICE_TOKEN_HEADER = 'x-service-token';
+/**
+ * Header naming the tenant a caller ACTS FOR. For a builder session it selects the
+ * workspace (`--tenant`) the builder reader narrows to. For a staff/service caller it is
+ * the slug-resolution pin (#417): vertical routes form `<tenantSlug>/<slug>` from it the
+ * way a pinned push does, so `versions <bare> --tenant <t>` over a service token reaches
+ * the same registry row a builder session would. It never widens access — staff reach
+ * everything already, and for builders the tenant must be one of their memberships.
+ */
+export const TENANT_HEADER = 'x-substrat-tenant';
+//# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAEnD,uFAAuF;AACvF,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,mBAAmB,CAAC"}

package/dist/identity-tenants.d.ts

@@ -0,0 +1,30 @@
+import { z } from '@substrat-run/contracts';
+/**
+ * A tenant a login builds for, as the control plane's studio membership read states it
+ * (`POST /internal/builder/identity-tenants`, builder-plane.md §4).
+ *
+ * The three directory fields are parsed with the SAME schemas the `tenant` record
+ * publishes (`contracts/src/tenancy.ts`), not with generic strings: the id is a ULID, the
+ * slug is the constrained slug, the name is non-empty. That costs nothing in lockout risk
+ * — `createTenantInput` picks those same three, so a tenant that exists satisfied them at
+ * creation — and it buys the half a loose parse would miss. A non-empty but malformed id
+ * passes `z.string()` and then becomes a Durable Object key and a team route, which is the
+ * downstream use this parse exists to protect.
+ */
+export declare const identityTenant: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+    slug: z.ZodString;
+    name: z.ZodString;
+    entitled: z.ZodBoolean;
+}, z.core.$strip>;
+/** The `/internal/builder/identity-tenants` response body. */
+export declare const identityTenantsResponse: z.ZodObject<{
+    tenants: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "TenantId", "out">;
+        slug: z.ZodString;
+        name: z.ZodString;
+        entitled: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type IdentityTenant = z.infer<typeof identityTenant>;
+//# sourceMappingURL=identity-tenants.d.ts.map

package/dist/identity-tenants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-tenants.d.ts","sourceRoot":"","sources":["../src/identity-tenants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,CAAC,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;;iBAMzB,CAAC;AAEH,8DAA8D;AAC9D,eAAO,MAAM,uBAAuB;;;;;;;iBAAiD,CAAC;AAEtF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/identity-tenants.js

@@ -0,0 +1,23 @@
+import { slug, tenantId, z } from '@substrat-run/contracts';
+/**
+ * A tenant a login builds for, as the control plane's studio membership read states it
+ * (`POST /internal/builder/identity-tenants`, builder-plane.md §4).
+ *
+ * The three directory fields are parsed with the SAME schemas the `tenant` record
+ * publishes (`contracts/src/tenancy.ts`), not with generic strings: the id is a ULID, the
+ * slug is the constrained slug, the name is non-empty. That costs nothing in lockout risk
+ * — `createTenantInput` picks those same three, so a tenant that exists satisfied them at
+ * creation — and it buys the half a loose parse would miss. A non-empty but malformed id
+ * passes `z.string()` and then becomes a Durable Object key and a team route, which is the
+ * downstream use this parse exists to protect.
+ */
+export const identityTenant = z.object({
+    id: tenantId,
+    slug,
+    name: z.string().min(1),
+    /** Whether the tenant holds the `builder` entitlement (the control plane applies expiry at read). */
+    entitled: z.boolean(),
+});
+/** The `/internal/builder/identity-tenants` response body. */
+export const identityTenantsResponse = z.object({ tenants: z.array(identityTenant) });
+//# sourceMappingURL=identity-tenants.js.map

package/dist/identity-tenants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-tenants.js","sourceRoot":"","sources":["../src/identity-tenants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,EAAE,EAAE,QAAQ;IACZ,IAAI;IACJ,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,qGAAqG;IACrG,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;CACtB,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@substrat-run/control-plane-client` — the typed HTTP client for the control-plane API.
+ *
+ * Apache-2.0 on purpose (LICENSING.md): the CLI a builder runs against their own code, and
+ * the console and the connect seam, all import it, and a client library that
+ * copyleft-captured its callers would capture every vertical built on Substrat. The AGPL
+ * server it talks to is `@substrat-run/control-plane-api`, which re-exports this surface.
+ *
+ * Everything reachable from here is `fetch` + `@substrat-run/contracts` — never `hono`,
+ * never a Node builtin — so a bundler can follow it into a page. `test/entry.test.ts`
+ * holds that line.
+ */
+export { ControlPlaneTransport, ControlPlaneError, ControlPlaneUsageError, provesNothingChanged } from './transport.js';
+export type { ControlPlaneTransportOptions, ControlPlaneErrorDetail } from './transport.js';
+export { ControlPlaneClient } from './client.js';
+export type { ControlPlaneClientOptions, ClientProvisionScopeInput } from './client.js';
+export { identityTenant, identityTenantsResponse } from './identity-tenants.js';
+export type { IdentityTenant } from './identity-tenants.js';
+export { DEV_ACTOR_HEADER, SERVICE_TOKEN_HEADER, TENANT_HEADER } from './headers.js';
+export { ControlPlaneBuilderClient, WALK_PAGE_LIMIT, walkPages } from './builder-client.js';
+export type { PageRequest } from './builder-client.js';
+export type * from './builder-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACxH,YAAY,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,yBAAyB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChF,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC5F,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,mBAAmB,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `@substrat-run/control-plane-client` — the typed HTTP client for the control-plane API.
+ *
+ * Apache-2.0 on purpose (LICENSING.md): the CLI a builder runs against their own code, and
+ * the console and the connect seam, all import it, and a client library that
+ * copyleft-captured its callers would capture every vertical built on Substrat. The AGPL
+ * server it talks to is `@substrat-run/control-plane-api`, which re-exports this surface.
+ *
+ * Everything reachable from here is `fetch` + `@substrat-run/contracts` — never `hono`,
+ * never a Node builtin — so a bundler can follow it into a page. `test/entry.test.ts`
+ * holds that line.
+ */
+export { ControlPlaneTransport, ControlPlaneError, ControlPlaneUsageError, provesNothingChanged } from './transport.js';
+export { ControlPlaneClient } from './client.js';
+export { identityTenant, identityTenantsResponse } from './identity-tenants.js';
+export { DEV_ACTOR_HEADER, SERVICE_TOKEN_HEADER, TENANT_HEADER } from './headers.js';
+export { ControlPlaneBuilderClient, WALK_PAGE_LIMIT, walkPages } from './builder-client.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAExH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAEhF,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,162 @@
+import type { ConnectionProbe } from '@substrat-run/contracts';
+/**
+ * The one HTTP seam every control-plane caller shares (#971): how a request is
+ * authenticated, how a failure is read, and what an empty answer is. The callers
+ * differ in what they ask — `ControlPlaneClient` is the vertical's connect seam,
+ * `ControlPlaneStaffClient` the console's staff surface — not in how they ask it.
+ *
+ * Browser-safe: nothing here reaches past `fetch` and `@substrat-run/contracts`, which is
+ * why the console can import it (`@substrat-run/control-plane-client`).
+ */
+export interface ControlPlaneTransportOptions {
+    /** Base URL of the control-plane API; a path such as `/api` is fine in a browser. */
+    baseUrl: string;
+    /**
+     * The dev-only `x-platform-actor` header, sent only when no `serviceToken` is set. `null`
+     * sends none: the console's session mode, where the staff cookie authenticates instead.
+     */
+    actor: string | null;
+    serviceToken?: string;
+    /**
+     * Defaults to the global `fetch`, looked up at CALL time rather than captured when the
+     * client is built — so a caller that swaps `globalThis.fetch` afterwards (a test, an
+     * instrumented runtime) is honoured, and workerd still sees the global as the receiver.
+     */
+    fetch?: typeof globalThis.fetch;
+    /** Passed to `fetch` only when set — `'include'` carries the console's staff session cookie. */
+    credentials?: RequestCredentials;
+    /**
+     * Extra headers sent with every request — for a caller that already holds a resolved
+     * credential header map (the CLI's `Authorization: Bearer …` / `x-service-token`, plus the
+     * tenant it acts for). PRECEDENCE, lowest first: these, then the transport's own
+     * credential (`serviceToken` / `actor`), then the content type, then the request's own
+     * `init.headers`. A client that has a credential of its own ignores any credential header
+     * (`x-service-token`, `x-platform-actor`, any case) in this map, and a call that names a
+     * credential replaces the client's, so exactly one credential leaves per request — two are
+     * refused with a `ControlPlaneUsageError` before anything is sent; a single call can still override
+     * anything else.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The `content-type` sent on every request. Defaults to `'application/json'` (what every
+     * existing caller has always sent, bodyless GETs included); `null` sends none, for a caller
+     * whose requests set their own per call.
+     */
+    contentType?: string | null;
+    /**
+     * Called with every response that arrives — success or refusal — before it is read: the
+     * hook for a header the plane stamps on any answer (the CLI's version advisory). Never
+     * called for a transport failure, and a throw from it is the caller's own.
+     */
+    onResponse?: (res: {
+        status: number;
+        headers: Headers;
+    }) => void;
+}
+/** What a refusal carried beyond its sentence, for a caller that renders its own. */
+export interface ControlPlaneErrorDetail {
+    /**
+     * The response body as text, exactly as it arrived. `''` is a body that was empty;
+     * `undefined` is one that could not be read (the stream failed), which a caller that
+     * prints a status line instead — as the CLI does — tells apart.
+     */
+    body?: string;
+    /** The status line's reason phrase (`Bad Gateway`). */
+    statusText?: string;
+    /** The response headers. */
+    headers?: Headers;
+    /** The full URL requested. */
+    url?: string;
+    /** Set on a 2xx whose body was not the JSON the route promises — `body` says what it was. */
+    malformed?: true;
+    /** The underlying failure, for a transport error (`status` 0): the error `fetch` threw. */
+    cause?: unknown;
+}
+/** A non-2xx (or unreachable) control-plane response. `status` is 0 on a transport error. */
+export declare class ControlPlaneError extends Error {
+    readonly status: number;
+    /**
+     * The provider's own answer, when the plane refused a connect because the credential
+     * was rejected upstream (#605, 422). Carried so a console can show WHY — "Scrive:
+     * No valid access credentials were provided" — instead of a generic save failure.
+     */
+    readonly probe?: ConnectionProbe | undefined;
+    constructor(status: number, message: string, 
+    /**
+     * The provider's own answer, when the plane refused a connect because the credential
+     * was rejected upstream (#605, 422). Carried so a console can show WHY — "Scrive:
+     * No valid access credentials were provided" — instead of a generic save failure.
+     */
+    probe?: ConnectionProbe | undefined, detail?: ControlPlaneErrorDetail);
+    /** The refusal's raw body text; `undefined` for an error the transport did not read off a response. */
+    readonly body: string | undefined;
+    readonly statusText: string | undefined;
+    readonly headers: Headers | undefined;
+    readonly url: string | undefined;
+    /** True for a 2xx answer that was not the JSON the route promises. */
+    readonly malformed: boolean;
+}
+/**
+ * Whether a failed call proves it changed nothing (#2010): the plane or the deployment behind it
+ * refused it (a 4xx), or that deployment does not have the route (501). Any other failure — a
+ * 502 that lost the deployment's answer, another 5xx, a malformed 2xx, a transport error
+ * (status 0), or no status at all — may follow a write that landed, so what it did is unknown
+ * and the caller reads the state before retrying. Takes any error carrying a numeric `status`,
+ * so an app's own error class for the same responses reads the same way.
+ */
+export declare function provesNothingChanged(error: unknown): boolean;
+/**
+ * The caller built a request the client refuses to send — today, one that would carry two
+ * credentials. A mistake in how the client was used, raised BEFORE anything leaves, so it is
+ * not a `ControlPlaneError` (no plane answered, none was found unreachable) and not a
+ * `TypeError` either: `fetch` itself throws `TypeError` for a network failure, and a caller
+ * that retries on transport errors must be able to tell the two apart by class.
+ */
+export declare class ControlPlaneUsageError extends Error {
+    constructor(message: string);
+}
+export declare class ControlPlaneTransport {
+    private readonly baseUrl;
+    private readonly actor;
+    private readonly serviceToken?;
+    private readonly fetchImpl;
+    private readonly credentials?;
+    private readonly extraHeaders?;
+    private readonly contentType;
+    private readonly onResponse?;
+    constructor(options: ControlPlaneTransportOptions);
+    /**
+     * One request on the wire, exactly as `send` makes it, and nothing more: the base URL, the
+     * credential and the headers are applied, and the `Response` comes back whatever its status.
+     * A `fetch` rejection propagates unchanged. For a caller that owns its own reading of
+     * the answer — a retry loop, a multipart upload — and wants the transport's addressing and
+     * credentials without its error policy.
+     */
+    request(path: string, init?: RequestInit): Promise<Response>;
+    /**
+     * The headers one request goes out with, merged through the `Headers` API so that names
+     * compare case-insensitively and every `HeadersInit` shape — a record, a tuple array or a
+     * `Headers` instance — is read the same way. Spreading the call's headers as if they were a
+     * record dropped a `Headers` instance's entries altogether, and let `Content-Type` and
+     * `content-type` ride side by side. Lowest first: the `headers` option, the transport's own
+     * credential, the content type, then the call's own.
+     */
+    private headersFor;
+    /** The full URL a path is requested at — for a message that names it. */
+    urlFor(path: string): string;
+    /**
+     * One request, and the one place a failure is read: a transport error or a non-2xx answer
+     * throws `ControlPlaneError`, so what comes back is always a successful `Response`. A 404
+     * is handed back as-is when the caller allows it.
+     */
+    protected send(path: string, init?: RequestInit, allow404?: boolean): Promise<Response>;
+    protected call<T>(path: string, init?: RequestInit, allow404?: boolean): Promise<T>;
+    /**
+     * A JSON answer, read from its text so a 2xx that is not JSON says what it was: a
+     * `ControlPlaneError` flagged `malformed`, carrying the `body` and `url` — the common
+     * misconfiguration being a base URL that points at a web page rather than the API. Unlike
+     * `call`, no status is special-cased: a 204 is an empty body, which is not JSON.
+     */
+    protected read<T>(path: string, init?: RequestInit): Promise<T>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}