@aexhq/sdk 0.46.4-canary → 0.50.0

package/dist/_contracts/account-types.d.ts

@@ -1,461 +0,0 @@
-/**
- * Client record types for the ACCOUNT and WORKSPACE-MANAGEMENT surfaces.
- *
- * Split out of `runtime-types.ts`, which keeps the PUBLIC SESSION LIFECYCLE —
- * sessions, runs, messages, files, run webhooks, whoami and runtime
- * capabilities. Nothing in that module describes an org, a plan, a key or a
- * persisted workspace resource, and nothing here is part of a caller's session
- * loop. Three families live below, each behind the section banner it arrived
- * with:
- *
- *   1. workspace secret metadata, billing (customer-facing summary, hosted
- *      checkout/portal, credit ledger) and the webhook signing secret;
- *   2. the control-plane resources served by the dashboard BFF — orgs,
- *      workspaces, API keys, members, invites;
- *   3. the route families that had NO declared client type, each DERIVED from
- *      its response schema rather than restated. That set is kept whole rather
- *      than redistributed: it includes the two WRITER-TOKEN child hops, which
- *      are session routes but not session-lifecycle types — the in-container
- *      runtime reads them with a child's writer token, never a workspace key,
- *      and no SDK caller ever holds one.
- *
- * Re-exported from the package root barrel (`index.ts`) exactly as these types
- * were when they lived in `runtime-types.ts`: this is a file boundary, not a
- * surface boundary, and every name below is still public.
- */
-import type * as z from "zod/mini";
-import type { McpServerRecordSchema, McpServerListResponseSchema } from "./schemas/response-mcp-servers.js";
-import type { WorkspaceWebhookDeliverySchema } from "./schemas/response-webhooks.js";
-import type { WorkspaceEraseResponseSchema } from "./schemas/response-workspace.js";
-import type { AdminBillingAccountTypeResponseSchema, AdminBillingPaymentMethodResponseSchema, AdminBillingTopupResponseSchema } from "./schemas/response-billing.js";
-import type { ChildFinalizeResponseSchema, ChildResultResponseSchema } from "./schemas/response-sessions-internal.js";
-import type { BillingAdmissionState } from "./billing-admission.js";
-/**
- * Wire-level record for a workspace secret as returned by the BFF.
- *
- * Workspace secrets share the lifecycle semantic of skills/files: a
- * `Secret.value(...)` is per-session and gone at terminal, while
- * `aex.workspace.secrets.set(...)` persists a named reusable value. Use
- * `Secret.ref(name)` to bind that persisted value to a session. The
- * identity is the `name` (the handle a `Secret.ref` points at); the value
- * rotates under that stable name, bumping `version`.
- *
- * This record is METADATA ONLY — it never carries the secret value. Persisted
- * values are write-only through the public workspace-secret API.
- */
-export interface SecretRecord {
-    readonly id: string;
-    readonly name: string;
-    readonly version: number;
-    readonly state: "ready";
-    /** ISO-8601 with a `Z` suffix. */
-    readonly createdAt?: string;
-    /** ISO-8601 with a `Z` suffix. */
-    readonly updatedAt?: string;
-    readonly deletedAt?: string | null;
-}
-/**
- * One free monthly allowance, as reported by `GET /api/billing`.
- *
- * `dimension`, `unit` and `label` are OPEN strings on purpose. The quantities a
- * free allowance is denominated in, and what each one is worth, are hosted
- * billing policy; this contract states the SHAPE the server reports them in so a
- * client can render the panel without keeping a second copy of the numbers. A
- * closed union here would be exactly the duplication the prepaid model removed.
- * Contrast `admissionState`, which IS a closed union — three states, public
- * contract, not policy.
- */
-export interface BillingAllowance {
-    /** Server-owned dimension key, e.g. `llm_token_usd`. */
-    readonly dimension: string;
-    /** This period's quota, counted in {@link unit}. */
-    readonly quota: number;
-    readonly used: number;
-    readonly remaining: number;
-    /** What the quota counts, e.g. `GB`, `calls`, `USD`. */
-    readonly unit: string;
-    /** The customer-facing name of the dimension, e.g. `model usage`. */
-    readonly label: string;
-    /** ISO-8601 instant the allowance resets — the start of the next UTC month. */
-    readonly resetAt: string;
-    /**
-     * What the remaining USD buys in tokens, on the workspace's most-used model.
-     * Rides only on the USD-denominated token allowance, and only when there is
-     * usage to infer a model from.
-     */
-    readonly approximateTokens?: {
-        readonly model: string;
-        readonly tokens: number;
-    };
-}
-/** Auto-recharge settings plus the guards a top-up form has to respect. */
-export interface BillingAutoTopup {
-    /** Opt-in and OFF by default: a card being on file never enables recharge. */
-    readonly enabled: boolean;
-    /** Balance below which a recharge is triggered. */
-    readonly thresholdUsd: number;
-    /** Amount charged per recharge. */
-    readonly amountUsd: number;
-    /** Smallest accepted top-up; a smaller `amountUsd` is a `400`. */
-    readonly minimumAmountUsd: number;
-    /** Ceiling on successful automatic recharges per rolling 24h. */
-    readonly maxPerDay: number;
-}
-/**
- * The saved card. `present` is authoritative and decides whether top-up and
- * auto-recharge are reachable at all; `brand`/`last4` are cosmetic and are
- * `null` when the payment provider could not be reached.
- */
-export interface BillingPaymentMethod {
-    readonly present: boolean;
-    readonly brand: string | null;
-    readonly last4: string | null;
-}
-/** A live block on the organization — new work is refused with `402 account_blocked`. */
-export interface BillingBlock {
-    /** ISO-8601 instant the block was applied. */
-    readonly at: string;
-    readonly reason: string;
-}
-/**
- * Customer-facing billing summary — `GET /api/billing` (scope `billing:read`).
- * All money fields are USD numbers.
- *
- * `planKey`, `subscriptionStatus` and `pastDueAt` are GONE with the catalog they
- * described. What replaces them is the prepaid surface: the period, the
- * card-derived {@link admissionState}, the allowance rows, the auto-recharge
- * block, the saved card, and any live block.
- *
- * This shape used to carry `[key: string]: unknown` as an "additive server
- * fields pass through" promise. That promise is precisely why `accountType` —
- * sent unconditionally — went undeclared for as long as it did, and why no
- * conformance check could notice: an index signature makes every undeclared
- * field structurally legal. It is gone; every field is declared.
- */
-export interface BillingSummary {
-    /** Prepaid balance (authoritative ledger sum). */
-    readonly balanceUsd: number;
-    /** Accrued spend for the current calendar month. */
-    readonly monthSpendUsd: number;
-    /** Monthly spend cap enforced on new sessions. */
-    readonly spendCapUsd: number;
-    /** The UTC allowance period these figures cover, `YYYY-MM`. */
-    readonly period: string;
-    /** What the money gates sized this workspace at. */
-    readonly admissionState: BillingAdmissionState;
-    /** `"internal"` marks an account exempt from the standard rate card. */
-    readonly accountType: "standard" | "internal";
-    /** `"active"` once a payment method is bound. Aurora-authoritative. */
-    readonly paymentMethodStatus: "none" | "active";
-    readonly autoTopupEnabled: boolean;
-    /** `null` when the organization is not blocked. */
-    readonly blocked: BillingBlock | null;
-    readonly paymentMethod: BillingPaymentMethod;
-    readonly autoTopup: BillingAutoTopup;
-    /** One entry per free monthly allowance, in the server's canonical order. */
-    readonly allowances: readonly BillingAllowance[];
-}
-/**
- * `POST /api/billing/topup/checkout`. One hosted Checkout does card capture,
- * address/tax collection and the credit purchase; `amountUsd` is rejected below
- * the server's minimum ({@link BillingAutoTopup.minimumAmountUsd}).
- */
-export interface BillingTopupCheckoutRequest {
-    readonly amountUsd: number;
-    /** Optional return URL after successful hosted checkout. */
-    readonly successUrl?: string;
-    /** Optional return URL after checkout cancellation. */
-    readonly cancelUrl?: string;
-}
-/**
- * `PATCH /api/billing/autotopup`. Every field is optional: an omitted field
- * keeps its stored value. Enabling requires a saved card, and `thresholdUsd`
- * must stay strictly below `amountUsd` — a threshold at or above the amount is a
- * recharge loop.
- */
-export interface BillingAutoTopupRequest {
-    readonly enabled?: boolean;
-    readonly thresholdUsd?: number;
-    readonly amountUsd?: number;
-}
-/** What `PATCH /api/billing/autotopup` echoes back: the stored settings. */
-export interface BillingAutoTopupUpdate {
-    readonly autoTopup: BillingAutoTopup;
-}
-/**
- * One issued monthly statement as listed by `GET /api/billing/statements`.
- *
- * Only ISSUED periods are listed: a month the generator withheld because it did
- * not reconcile is absent rather than rendered on demand.
- */
-export interface BillingStatementSummary {
-    /** The UTC month the statement covers, `YYYY-MM`. */
-    readonly period: string;
-    /** ISO-8601 instant the statement was issued. */
-    readonly issuedAt: string;
-    readonly openingBalanceUsd: number;
-    readonly creditsPurchasedUsd: number;
-    readonly usageUsd: number;
-    readonly adjustmentsUsd: number;
-    readonly closingBalanceUsd: number;
-}
-/** `GET /api/billing/statements` — the months a customer can download, newest first. */
-export interface BillingStatementList {
-    readonly statements: readonly BillingStatementSummary[];
-}
-export interface BillingPortalRequest {
-    /** Optional return URL after leaving the hosted billing portal. */
-    readonly returnUrl?: string;
-}
-/** Hosted checkout/portal session. The client should open `url`. One key. */
-export interface BillingHostedSession {
-    readonly url: string;
-}
-/**
- * One row of the ORG credit ledger as returned by `GET /api/billing/ledger`
- * (newest first). `amountUsd` is signed: top-ups are positive, run charges
- * negative.
- *
- * Every field below is selected by the handler on every row, so none is
- * optional; the nullable ones are nullable, which is a different statement. The
- * index signature this shape used to carry is gone for the reason given on
- * {@link BillingSummary}.
- */
-export interface BillingLedgerEntry {
-    readonly id: string;
-    /** e.g. `top_up`, `session_charge`. Open server vocabulary. */
-    readonly entryType: string;
-    readonly amountUsd: number;
-    readonly currency: string;
-    /** The session this entry charges, `null` for non-run entries. */
-    readonly sessionId: string | null;
-    /**
-     * Cost-attribution tag: the workspace the charge belongs to, `null` for
-     * org-level rows such as a top-up.
-     *
-     * A RAW workspace id (a UUID), not the public `wsp_<hex>` form that
-     * `whoami.workspaceId` and the MCP-server records carry. Same concept, two
-     * renderings; compare with care.
-     */
-    readonly workspaceId: string | null;
-    readonly description: string | null;
-    readonly createdBy: string;
-    /**
-     * **NOT ISO-8601** — selected raw, so it arrives as the Aurora Data API's
-     * `"YYYY-MM-DD HH:MM:SS"` text, no `T` and no zone. It is the last such field
-     * on this surface; every other billing timestamp ({@link BillingAllowance.resetAt},
-     * {@link BillingBlock.at}, {@link BillingStatementSummary.issuedAt}) is
-     * constructed by its handler and IS ISO-8601 with a `Z`.
-     */
-    readonly createdAt: string;
-}
-/** Query for the billing ledger read. `limit` is clamped server-side to [1, 100] (default 25). */
-export interface BillingLedgerQuery {
-    readonly limit?: number;
-}
-/** One page of recent ledger rows (newest first). Not cursor-paged — `limit` bounds the read. */
-export interface BillingLedgerPage {
-    readonly entries: readonly BillingLedgerEntry[];
-}
-/**
- * The workspace webhook signing secret reveal — `POST /api/webhook/signing-secret`.
- * `whsec` is the Standard-Webhooks style `whsec_<base64>` string that
- * `verifyAexWebhook` accepts as `secret`. The endpoint reveals the current
- * secret, CREATING one on first use; it does not rotate (a repeat call returns
- * the same value). POST (not GET) so every reveal is a logged action.
- */
-export interface WebhookSigningSecret {
-    readonly whsec: string;
-}
-/**
- * One org the caller belongs to — the ownership / billing / roles wrapper ABOVE
- * workspaces. `role` is the caller's own membership role in this org
- * (`admin | member`); billing and the per-org workspace cap live at this level.
- */
-export interface OrgRecord {
-    readonly id: string;
-    readonly name: string;
-    /** Globally-unique org slug (`/org/<slug>`); omitted by older deployments. */
-    readonly slug?: string;
-    /** The caller's role in this org: `admin` or `member`. */
-    readonly role?: string;
-    readonly createdAt?: string;
-}
-/** Request body for {@link createOrg} — a display name; the server assigns id/slug. */
-export interface CreateOrgRequest {
-    readonly name: string;
-}
-/**
- * A workspace as seen from the CONTROL plane (management view): its id, name,
- * and owning org. Distinct from the data-plane view — this never carries the
- * workspace's files/skills/secrets, only the row a dashboard/CLI lists.
- */
-export interface WorkspaceRecord {
-    readonly id: string;
-    readonly name: string;
-    /** Globally-unique workspace slug (`/workspace/<slug>`); omitted by older deployments. */
-    readonly slug?: string;
-    /** The org that owns this workspace. */
-    readonly orgId: string;
-    readonly createdAt?: string;
-}
-/** Request body for {@link createWorkspace}; hosted policy owns any org workspace limit. */
-export interface CreateWorkspaceRequest {
-    /** The org to create the workspace under. */
-    readonly orgId: string;
-    readonly name: string;
-}
-/**
- * One-time reveal returned by {@link createWorkspace}: the new workspace's id
- * plus its FIRST workspace-scoped, data-plane API key. The key is shown exactly
- * once at creation — the creating (account) principal has no other data-plane
- * access to it, though the owning user can see/delete it in the dashboard
- * (orphan recovery). The SDK wraps `apiKey` in a redacted `SecretString`.
- */
-export interface NewWorkspace {
-    readonly workspaceId: string;
-    /** The workspace-scoped API key (`aex_<plane>_…`), revealed ONCE. */
-    readonly apiKey: string;
-    /** Globally-unique workspace slug, when the server assigns one. */
-    readonly slug?: string;
-    /** The org that owns the new workspace. */
-    readonly orgId?: string;
-}
-/**
- * Metadata for one API key (data-plane workspace key OR account PAT). NEVER
- * carries the secret value — the value is write-only and revealed only once via
- * {@link NewApiKey}. `kind` distinguishes a `workspace` key from an `account`
- * PAT; `workspaceId` is present only for workspace keys.
- */
-export interface ApiKeyRecord {
-    readonly id: string;
-    readonly name?: string;
-    /** `workspace` (data-plane) or `account` (control-plane PAT). */
-    readonly kind?: string;
-    /** Present for workspace keys; absent for account PATs. */
-    readonly workspaceId?: string;
-    readonly scopes?: readonly string[];
-    readonly createdAt?: string;
-    readonly lastUsedAt?: string | null;
-    readonly revokedAt?: string | null;
-}
-/**
- * Request body for {@link createApiKey}. Mint EITHER a workspace-scoped
- * data-plane key (pass `workspaceId`) or an account PAT (`account: true`) — the
- * two are mutually exclusive. Anti-escalation: an account PAT can mint workspace
- * keys but not another PAT (enforced server-side).
- */
-export interface CreateApiKeyRequest {
-    /** Mint a WORKSPACE-scoped data-plane key for this workspace. */
-    readonly workspaceId?: string;
-    /** Mint an ACCOUNT PAT (control-plane) instead. Mutually exclusive with `workspaceId`. */
-    readonly account?: boolean;
-    /** Optional human label for the key. */
-    readonly name?: string;
-    /** Optional scope restriction; defaults server-side. */
-    readonly scopes?: readonly string[];
-}
-/**
- * One-time reveal returned by {@link createApiKey}: the key id plus the freshly
- * minted secret value, shown exactly once. The SDK wraps `apiKey` in a redacted
- * `SecretString`.
- */
-export interface NewApiKey {
-    readonly id: string;
-    /** The freshly minted key value, revealed ONCE. */
-    readonly apiKey: string;
-    readonly name?: string;
-    readonly kind?: string;
-    readonly workspaceId?: string;
-    readonly scopes?: readonly string[];
-}
-/** One member of an org (from {@link listOrgMembers}). Never carries credentials. */
-export interface OrgMemberRecord {
-    /** The member's stable account (app-user) id. */
-    readonly appUserId: string;
-    readonly email?: string;
-    /** `admin` or `member`. */
-    readonly role: string;
-    /** `active` or `pending` (an unaccepted invite). */
-    readonly status?: string;
-    readonly createdAt?: string;
-}
-/** Request body for {@link createOrgInvite} — invite an email at a role. */
-export interface CreateOrgInviteRequest {
-    readonly email: string;
-    /** `admin` or `member`; defaults server-side to `member`. */
-    readonly role?: string;
-}
-/**
- * A pending team invite created by {@link createOrgInvite}. Metadata only — the
- * invite token itself is delivered out-of-band (email), never returned here.
- */
-export interface OrgInvite {
-    readonly id: string;
-    readonly orgId: string;
-    readonly email: string;
-    readonly role: string;
-    /** `pending` until accepted. */
-    readonly status?: string;
-    readonly expiresAt?: string;
-    readonly createdAt?: string;
-}
-/**
- * One persisted workspace MCP server — `POST/GET /api/mcp-servers`,
- * `GET/DELETE /api/mcp-servers/{id}`.
- *
- * `headerShape` lists header NAMES ONLY. The values live in the secret store and
- * are write-only through this API; a `headers` or `authorization` key appearing
- * on a read is a leak, and the response schema fails the suite if one does.
- *
- * `workspaceId` is the PUBLIC `wsp_<hex>` form (the handler runs it through
- * `publicWorkspaceId`), matching `whoami.workspaceId` — and NOT matching
- * {@link BillingLedgerEntry.workspaceId} or {@link WorkspaceEraseResult}, which
- * are raw ids. `createdAt` / `updatedAt` are ISO-8601 with a `Z`.
- */
-export type McpServerRecord = z.infer<typeof McpServerRecordSchema>;
-/** `GET /api/mcp-servers` — every workspace MCP server, newest first. Not paged. */
-export type McpServerList = z.infer<typeof McpServerListResponseSchema>;
-/**
- * One row of `GET /api/webhook/deliveries` — the WORKSPACE view of the delivery
- * ledger, which is {@link SessionWebhookDelivery} plus the `sessionId` and
- * `callbackUrl` it belongs to. Server-capped at the 100 most recent: no `limit`,
- * no cursor.
- */
-export type WorkspaceWebhookDelivery = z.infer<typeof WorkspaceWebhookDeliverySchema>;
-/**
- * `DELETE /api/workspaces/{workspaceId}` on the DATA plane — the owner's GDPR
- * hard-erase, answering 200 with counters rather than 204. Idempotent: erasing
- * an absent workspace answers 200 with every counter at zero, indistinguishable
- * from erasing an empty one.
- *
- * NOT the same route as {@link deleteWorkspace}, which is the CONTROL plane's
- * `DELETE /api/workspaces/{id}` and returns no body. Same method, same path
- * pattern, different plane and different response.
- *
- * `workspaceId` here is the RAW id, not the public `wsp_<hex>` form.
- */
-export type WorkspaceEraseResult = z.infer<typeof WorkspaceEraseResponseSchema>;
-/** `POST /api/admin/billing/topup` — operator credit grant. */
-export type AdminBillingTopupResult = z.infer<typeof AdminBillingTopupResponseSchema>;
-/** `POST /api/admin/billing/payment-method` — operator payment-method override. */
-export type AdminBillingPaymentMethodResult = z.infer<typeof AdminBillingPaymentMethodResponseSchema>;
-/** `POST /api/admin/billing/account-type` — operator account-type override. */
-export type AdminBillingAccountTypeResult = z.infer<typeof AdminBillingAccountTypeResponseSchema>;
-/**
- * `GET /api/sessions/{id}/result` — a subagent child's result, read by the
- * in-container runtime with the child's WRITER TOKEN, not a workspace API key.
- * Either still in flight (`settling` / `running` / `queued`) or `finished` with
- * an outcome.
- *
- * Its files key the workspace-relative path as **`path`**, where the public
- * `/files` routes call the same thing `filename` ({@link SessionFile}). Two
- * server projections of one concept differing in one key name.
- */
-export type ChildResult = z.infer<typeof ChildResultResponseSchema>;
-/**
- * `POST /api/sessions/{id}/finalize` — the writer-token child settle hop. Note
- * the absence of a `session` envelope: this route is not shaped like the public
- * session routes.
- */
-export type ChildFinalizeResult = z.infer<typeof ChildFinalizeResponseSchema>;

package/dist/_contracts/account-types.js

@@ -1 +0,0 @@
-export {};

package/dist/_contracts/api-key.d.ts

@@ -1,61 +0,0 @@
-/**
- * Self-describing API-key codec (SSoT).
- *
- * An aex API key is `aex_<plane>_<regionCode>_<workspaceId>_<secret>_<crc>` —
- * it embeds its own plane and region, CRC-protected. This is the canonical
- * client-side codec: the SDK constructor parses the key to DERIVE the target
- * plane (zero-network) and to fail fast on a plane/baseUrl mismatch instead of
- * surfacing a bare `token_invalid` after a full round-trip.
- *
- * The embedded workspace id is a whole `wsp_<32hex>` id ({@link ID_PREFIXES}),
- * which makes the key SEVEN underscore-separated fields rather than six. The old
- * six-field layout stripped the `wsp_` prefix to fit the workspace id into one
- * field; that strip existed because of this wire format, not because of the
- * database, and it is what let four workspace-id string forms coexist.
- *
- * Pinned to the platform codec (`@aexhq/contract-core/token-codec`) by a
- * cross-repo parity test. Parse-only: it makes NO trust decision (the server
- * still validates the secret).
- */
-export declare const API_KEY_PLANES: readonly ["dev", "prd"];
-export type ApiKeyPlane = (typeof API_KEY_PLANES)[number];
-/**
- * Supported region → embedded region code. Mirrors
- * `@aexhq/contract-core/src/supported-regions.ts` (`REGION_TOKEN_CODES`), which
- * is exhaustive over the launch region set by `satisfies`; the two are pinned to
- * each other by `platform/scripts/validate/api-key-codec-parity.test.ts`. These
- * codes are FROZEN — a code is a permanent field of every key minted with it.
- */
-export declare const API_KEY_REGION_TO_CODE: Readonly<Record<string, string>>;
-/** `aex_<plane>_<regionCode>_<wsp>_<hex>_<secret>_<tag>`. */
-export declare const API_KEY_FIELD_COUNT = 7;
-export interface ParsedApiKey {
-    readonly plane: ApiKeyPlane;
-    readonly regionCode: string;
-    readonly region: string;
-    /** The workspace id embedded in the key, in its one canonical `wsp_<32hex>` form. */
-    readonly workspaceId: string;
-}
-/**
- * Parse a self-describing API key, or `null` for any opaque or STRUCTURALLY malformed value.
- * Validates the `aex_` prefix, the 7-part shape, a known plane + region code, and that the
- * embedded workspace id is a canonical id. The trailing tag is an HMAC keyed by the server
- * pepper (WS6/P4) which the SDK does not hold, so this is the pure routing parse; authenticity
- * is verified server-side. A tampered tag parses (routes) and is rejected at auth.
- */
-export declare function tryParseApiKey(token: string): ParsedApiKey | null;
-/** @deprecated Use {@link tryParseApiKey}; this compatibility wrapper is identical. */
-export declare function parseApiKey(token: string): ParsedApiKey | null;
-/**
- * Assemble a valid API key from its parts (the inverse of {@link parseApiKey}).
- * Unlike the server's `mintApiKeyValue` this takes an EXPLICIT `secret` so it is
- * deterministic — used by codec round-trip / cross-repo parity tests. The
- * workspace id must ALREADY be canonical: there is no normalizer, so a dashed
- * uuid or a bare hex string throws instead of being silently reshaped.
- */
-export declare function formatApiKey(input: {
-    readonly plane: ApiKeyPlane;
-    readonly region: string;
-    readonly workspaceId: string;
-    readonly secret: string;
-}): string;

package/dist/_contracts/api-key.js

@@ -1,101 +0,0 @@
-/**
- * Self-describing API-key codec (SSoT).
- *
- * An aex API key is `aex_<plane>_<regionCode>_<workspaceId>_<secret>_<crc>` —
- * it embeds its own plane and region, CRC-protected. This is the canonical
- * client-side codec: the SDK constructor parses the key to DERIVE the target
- * plane (zero-network) and to fail fast on a plane/baseUrl mismatch instead of
- * surfacing a bare `token_invalid` after a full round-trip.
- *
- * The embedded workspace id is a whole `wsp_<32hex>` id ({@link ID_PREFIXES}),
- * which makes the key SEVEN underscore-separated fields rather than six. The old
- * six-field layout stripped the `wsp_` prefix to fit the workspace id into one
- * field; that strip existed because of this wire format, not because of the
- * database, and it is what let four workspace-id string forms coexist.
- *
- * Pinned to the platform codec (`@aexhq/contract-core/token-codec`) by a
- * cross-repo parity test. Parse-only: it makes NO trust decision (the server
- * still validates the secret).
- */
-import { assertId, isId } from "./ids.js";
-export const API_KEY_PLANES = ["dev", "prd"];
-/**
- * Supported region → embedded region code. Mirrors
- * `@aexhq/contract-core/src/supported-regions.ts` (`REGION_TOKEN_CODES`), which
- * is exhaustive over the launch region set by `satisfies`; the two are pinned to
- * each other by `platform/scripts/validate/api-key-codec-parity.test.ts`. These
- * codes are FROZEN — a code is a permanent field of every key minted with it.
- */
-export const API_KEY_REGION_TO_CODE = {
-    "eu-west-1": "euw1",
-    "us-west-1": "usw1",
-    "ap-northeast-1": "apne1"
-};
-const CODE_TO_REGION = Object.fromEntries(Object.entries(API_KEY_REGION_TO_CODE).map(([region, code]) => [code, region]));
-const API_KEY_PLANE_SET = new Set(API_KEY_PLANES);
-/** `aex_<plane>_<regionCode>_<wsp>_<hex>_<secret>_<tag>`. */
-export const API_KEY_FIELD_COUNT = 7;
-/**
- * Parse a self-describing API key, or `null` for any opaque or STRUCTURALLY malformed value.
- * Validates the `aex_` prefix, the 7-part shape, a known plane + region code, and that the
- * embedded workspace id is a canonical id. The trailing tag is an HMAC keyed by the server
- * pepper (WS6/P4) which the SDK does not hold, so this is the pure routing parse; authenticity
- * is verified server-side. A tampered tag parses (routes) and is rejected at auth.
- */
-export function tryParseApiKey(token) {
-    if (typeof token !== "string" || !token.startsWith("aex_"))
-        return null;
-    const parts = token.split("_");
-    if (parts.length !== API_KEY_FIELD_COUNT)
-        return null;
-    const [prefix, plane, regionCode, workspacePrefix, workspaceBody, secret, tag] = parts;
-    if (prefix !== "aex" || !API_KEY_PLANE_SET.has(plane) || !regionCode || !secret || !tag) {
-        return null;
-    }
-    const workspaceId = `${workspacePrefix}_${workspaceBody}`;
-    if (!isId("workspace", workspaceId))
-        return null;
-    // WS6/P4: the tag is an HMAC keyed by the server pepper, which the SDK does not hold — so this is
-    // the PURE routing parse (structure only). Authenticity is enforced server-side by verifyTokenTag
-    // before any store touch; a tag-tampered token routes and is then rejected at auth.
-    const region = CODE_TO_REGION[regionCode];
-    if (region === undefined)
-        return null;
-    return { plane: plane, regionCode, region, workspaceId };
-}
-/** @deprecated Use {@link tryParseApiKey}; this compatibility wrapper is identical. */
-export function parseApiKey(token) {
-    return tryParseApiKey(token);
-}
-/**
- * Assemble a valid API key from its parts (the inverse of {@link parseApiKey}).
- * Unlike the server's `mintApiKeyValue` this takes an EXPLICIT `secret` so it is
- * deterministic — used by codec round-trip / cross-repo parity tests. The
- * workspace id must ALREADY be canonical: there is no normalizer, so a dashed
- * uuid or a bare hex string throws instead of being silently reshaped.
- */
-export function formatApiKey(input) {
-    const code = API_KEY_REGION_TO_CODE[input.region];
-    if (code === undefined) {
-        throw new Error(`API key region is not supported: ${input.region}`);
-    }
-    const workspaceField = assertId("workspace", input.workspaceId, "API key workspaceId");
-    if (!input.secret || input.secret.includes("_")) {
-        throw new Error("secret must be non-empty and contain no '_'");
-    }
-    const body = ["aex", input.plane, code, workspaceField, input.secret].join("_");
-    return `${body}_${crc32Base36(body)}`;
-}
-function crc32Base36(input) {
-    return crc32(input).toString(36);
-}
-function crc32(input) {
-    let crc = 0xffffffff;
-    for (const byte of Buffer.from(input, "utf8")) {
-        crc ^= byte;
-        for (let i = 0; i < 8; i += 1) {
-            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
-        }
-    }
-    return (crc ^ 0xffffffff) >>> 0;
-}

package/dist/_contracts/api-routes.d.ts

@@ -1,20 +0,0 @@
-/**
- * The authenticated data-plane HTTP route table.
- *
- * This is the single machine-readable description of the data-plane surface:
- * the platform api lambda dispatches and scope-gates from it, and the OpenAPI
- * generator in this repo reads the same table. It is declared here exactly
- * once so the two can never drift.
- *
- * Declaration-only and dependency-free: matching, scope lookup and route
- * classification stay with the server that dispatches them.
- */
-export type RequiredApiScope = string;
-export type AuthenticatedApiRouteDescriptor = {
-    readonly name: string;
-    readonly method: string;
-    readonly pattern: RegExp;
-    readonly samplePath: string;
-    readonly requiredScope: RequiredApiScope | null;
-};
-export declare const AUTHENTICATED_API_ROUTE_DESCRIPTORS: readonly AuthenticatedApiRouteDescriptor[];