@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/utils/json.js

@@ -0,0 +1,276 @@
+/**
+ * json.ts — key-order-insensitive comparison helpers for JSON-shaped values.
+ *
+ * Why this exists as a first-class, exported util:
+ *
+ * A `field.json()` value may be backed by a Postgres `jsonb` column, and **jsonb
+ * does not preserve object key order** (it reorders keys by length, then
+ * bytewise, and drops insignificant whitespace — see
+ * https://www.postgresql.org/docs/current/datatype-json.html). So a document an
+ * app wrote as `{type,text}` streams back in a delta as `{text,type}`: the same
+ * value, a different serialization.
+ *
+ * That bites any app that reconciles an Ablo row against an *external* state
+ * container it doesn't control — a rich-text editor (Tiptap/ProseMirror/Slate),
+ * a `useState`, a form buffer. The natural guard, `JSON.stringify(remote) ===
+ * JSON.stringify(local)`, is silently wrong because the two sides serialize keys
+ * in different orders, so it never matches — and the app re-applies the remote
+ * value on every render, clobbering in-flight edits and fighting the cursor.
+ *
+ * The fix is to compare order-insensitively. `deepEqual` does structural
+ * equality directly; `stableStringify` produces a canonical string (recursively
+ * sorted keys) for when you need a stable cache key / dependency value. The SDK
+ * already uses `deepEqual` internally for store-level echo detection; this
+ * module makes the same guarantee available to app authors so they don't each
+ * reinvent it.
+ *
+ * (If you need byte-exact key order preserved end-to-end, store the field in a
+ * `text` column instead of `jsonb` — Ablo's adaptive codec serializes verbatim
+ * there, matching Postgres's `json` type behavior.)
+ */
+import { AbloValidationError } from '../errors.js';
+/**
+ * Takes an immutable, plain snapshot at a JSON persistence/wire boundary.
+ *
+ * Traversal intentionally creates fresh objects and arrays instead of relying
+ * on a framework-specific unwrapping API. That makes Proxy-wrapped plain data
+ * (including MobX observables) safe for IndexedDB's structured-clone algorithm
+ * while keeping the settlement core independent of any reactive framework.
+ *
+ * The accepted contract is deliberately narrower than `JSON.stringify`:
+ * values that JSON would silently corrupt (`NaN` to `null`, `Map` to `{}`) or
+ * cannot encode are rejected with a stable, path-aware validation error.
+ * Valid dates retain normal JSON semantics and become ISO strings. Undefined
+ * object properties are omitted for compatibility with optional object keys;
+ * root/array `undefined` and sparse arrays are rejected rather than becoming
+ * an ambiguous `null`.
+ */
+export function snapshotJsonValue(value, path = '$') {
+    try {
+        return snapshotJsonNode(value, path, new WeakMap());
+    }
+    catch (error) {
+        if (error instanceof AbloValidationError)
+            throw error;
+        throw invalidJsonValue(path, 'could not be read safely', value, error);
+    }
+}
+function snapshotJsonNode(value, path, active) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw invalidJsonValue(path, 'must be a finite number', value);
+        }
+        return Object.is(value, -0) ? 0 : value;
+    }
+    if (value === undefined) {
+        throw invalidJsonValue(path, 'cannot be undefined here', value);
+    }
+    if (typeof value === 'bigint') {
+        throw invalidJsonValue(path, 'cannot be a bigint', value);
+    }
+    if (typeof value === 'function') {
+        throw invalidJsonValue(path, 'cannot be a function', value);
+    }
+    if (typeof value === 'symbol') {
+        throw invalidJsonValue(path, 'cannot be a symbol', value);
+    }
+    if (value instanceof Date) {
+        const timestamp = value.getTime();
+        if (!Number.isFinite(timestamp)) {
+            throw invalidJsonValue(path, 'cannot be an invalid Date', value);
+        }
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        const firstPath = active.get(value);
+        if (firstPath !== undefined) {
+            throw invalidJsonValue(path, `forms a cycle back to ${firstPath}`, value);
+        }
+        active.set(value, path);
+        try {
+            const output = [];
+            for (let index = 0; index < value.length; index += 1) {
+                const itemPath = `${path}[${index}]`;
+                if (!(index in value)) {
+                    throw invalidJsonValue(itemPath, 'cannot be a sparse array hole', undefined);
+                }
+                output.push(snapshotJsonNode(value[index], itemPath, active));
+            }
+            return Object.freeze(output);
+        }
+        finally {
+            active.delete(value);
+        }
+    }
+    const object = value;
+    const firstPath = active.get(object);
+    if (firstPath !== undefined) {
+        throw invalidJsonValue(path, `forms a cycle back to ${firstPath}`, value);
+    }
+    let prototype;
+    try {
+        prototype = Object.getPrototypeOf(object);
+    }
+    catch (cause) {
+        throw invalidJsonValue(path, 'has an unreadable prototype', value, cause);
+    }
+    if (prototype !== null) {
+        const constructorDescriptor = Object.getOwnPropertyDescriptor(prototype, 'constructor');
+        const constructor = constructorDescriptor?.value;
+        if (typeof constructor !== 'function' || constructor.name !== 'Object') {
+            throw invalidJsonValue(path, 'must be a plain object', value);
+        }
+    }
+    active.set(object, path);
+    try {
+        let keys;
+        try {
+            keys = Reflect.ownKeys(object);
+        }
+        catch (cause) {
+            throw invalidJsonValue(path, 'has unreadable keys', value, cause);
+        }
+        for (const key of keys) {
+            if (typeof key !== 'symbol')
+                continue;
+            let enumerable = false;
+            try {
+                enumerable = Object.getOwnPropertyDescriptor(object, key)?.enumerable === true;
+            }
+            catch (cause) {
+                throw invalidJsonValue(path, 'has an unreadable symbol property', value, cause);
+            }
+            if (enumerable) {
+                throw invalidJsonValue(path, 'cannot contain enumerable symbol keys', value);
+            }
+        }
+        const output = {};
+        for (const key of keys) {
+            if (typeof key !== 'string')
+                continue;
+            let descriptor;
+            try {
+                descriptor = Object.getOwnPropertyDescriptor(object, key);
+            }
+            catch (cause) {
+                throw invalidJsonValue(jsonPath(path, key), 'has an unreadable property', value, cause);
+            }
+            if (!descriptor?.enumerable)
+                continue;
+            let child;
+            try {
+                child = Reflect.get(object, key);
+            }
+            catch (cause) {
+                throw invalidJsonValue(jsonPath(path, key), 'could not be read', value, cause);
+            }
+            // Matches JSON object semantics for optional fields without allowing
+            // undefined to become null inside arrays.
+            if (child === undefined)
+                continue;
+            Object.defineProperty(output, key, {
+                configurable: true,
+                enumerable: true,
+                value: snapshotJsonNode(child, jsonPath(path, key), active),
+                writable: true,
+            });
+        }
+        return Object.freeze(output);
+    }
+    finally {
+        active.delete(object);
+    }
+}
+function jsonPath(parent, key) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+        ? `${parent}.${key}`
+        : `${parent}[${JSON.stringify(key)}]`;
+}
+function invalidJsonValue(path, reason, value, cause) {
+    const valueType = jsonValueType(value);
+    return new AbloValidationError(`Write payload ${path} ${reason}.`, {
+        code: 'write_payload_invalid',
+        param: path,
+        details: { path, reason, valueType },
+        ...(cause !== undefined ? { cause } : {}),
+    });
+}
+function jsonValueType(value) {
+    if (value === null)
+        return 'null';
+    try {
+        if (Array.isArray(value))
+            return 'array';
+        if (value instanceof Date)
+            return 'Date';
+        if (typeof value === 'object') {
+            const name = Reflect.get(value, 'constructor')?.name;
+            return typeof name === 'string' ? name : 'object';
+        }
+    }
+    catch {
+        return typeof value;
+    }
+    return typeof value;
+}
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects); key order is ignored. */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++) {
+            if (!deepEqual(av[i], bv[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!deepEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Canonical JSON serialization: recursively sorts object keys so two values that
+ * differ only in key order (e.g. a jsonb round-trip) produce the same string.
+ * Use this when you need a comparable/cacheable string rather than a boolean —
+ * e.g. an echo guard or a `useEffect`/`useMemo` dependency.
+ */
+export function stableStringify(value) {
+    return JSON.stringify(sortKeysDeep(value));
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value && typeof value === 'object') {
+        const source = value;
+        return Object.keys(source)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = sortKeysDeep(source[key]);
+            return acc;
+        }, {});
+    }
+    return value;
+}

package/dist/transaction/wire/accountResponses.d.ts

@@ -0,0 +1,420 @@
+/**
+ * What the ACCOUNT routes answer with — the surface you reach through the
+ * `ablo` CLI rather than through a model: `GET /v1/projects`, `GET /api/schema`,
+ * `GET /v1/logs`, `GET /v1/usage`.
+ *
+ * These are the shapes the server, the CLI, and the MCP server all have to
+ * agree on. Before this module each of them spelled the shape out again — the
+ * server inline in `c.json({ … })`, the others in hand-written interfaces — so
+ * a renamed field broke a consumer at runtime with nothing failing in between.
+ *
+ * None of these endpoints appear in the published OpenAPI contract yet (they
+ * sit in the spec test's `NOT_YET_PUBLISHED` set). Deriving the spec from these
+ * schemas is what removes them from it.
+ */
+import { z } from 'zod';
+import type { SyncDeltaAction } from './delta.js';
+/**
+ * One project — an app's own schema, data planes, and keys. `default` marks the
+ * organization's implicit project, whose id is the organization's own.
+ */
+export declare const projectResponseSchema: z.ZodObject<{
+    object: z.ZodLiteral<"project">;
+    id: z.ZodString;
+    slug: z.ZodString;
+    name: z.ZodString;
+    default: z.ZodBoolean;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type ProjectResponse = z.infer<typeof projectResponseSchema>;
+/**
+ * `GET /v1/projects`.
+ *
+ * Note what this is NOT: the canonical {@link ListEnvelope}. An org's projects
+ * are returned whole, so the route emits `data` with no `has_more`/`next_cursor`
+ * beside it. That divergence is real and this schema states it rather than
+ * describing a pagination the endpoint does not implement — adding the two
+ * fields is an API change, not a documentation fix.
+ */
+export declare const projectListResponseSchema: z.ZodObject<{
+    object: z.ZodLiteral<"list">;
+    data: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        object: z.ZodLiteral<"project">;
+        id: z.ZodString;
+        slug: z.ZodString;
+        name: z.ZodString;
+        default: z.ZodBoolean;
+        created_at: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProjectListResponse = z.infer<typeof projectListResponseSchema>;
+/** One minted key, returned exactly once — the plaintext is never readable again. */
+export declare const provisionedKeySchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    expiresAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ProvisionedKey = z.infer<typeof provisionedKeySchema>;
+/**
+ * What the CLI device flow gets back once a browser approval is exchanged for
+ * credentials: the sandbox key `ablo push` authors with, and the restricted
+ * production key that only observes.
+ *
+ * `project` is the project both keys are scoped to, resolved SERVER-SIDE from
+ * the requested slug — null means the organization's default. The server's
+ * answer is authoritative because it is what resolved the slug to an id, so the
+ * CLI stores keys under the project named here rather than the one it asked
+ * for.
+ */
+export declare const provisionKeyResponseSchema: z.ZodObject<{
+    test: z.ZodObject<{
+        apiKey: z.ZodString;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    live: z.ZodOptional<z.ZodObject<{
+        apiKey: z.ZodString;
+        expiresAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    organizationSlug: z.ZodOptional<z.ZodString>;
+    project: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ProvisionKeyResponse = z.infer<typeof provisionKeyResponseSchema>;
+/**
+ * A model's declared conflict disposition as it travels on the wire, keyed by
+ * committer kind.
+ *
+ * Spelled here rather than imported from the policy layer, which states the same
+ * three members as a TypeScript interface: `wire/` holds runtime-validatable
+ * schemas, and it is the protocol leaf — everything depends on it and it depends
+ * on nothing. The check that the two never drift therefore lives on the policy
+ * side of that edge, next to the interface, in `../policy/types.ts`.
+ */
+export declare const conflictAxisWireSchema: z.ZodObject<{
+    user: z.ZodOptional<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>;
+    agent: z.ZodOptional<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>;
+    system: z.ZodOptional<z.ZodEnum<{
+        reject: "reject";
+        overwrite: "overwrite";
+        notify: "notify";
+    }>>;
+}, z.core.$strip>;
+/** One model in the deployed schema, as the schema read reports it. */
+export declare const schemaModelResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+    typename: z.ZodString;
+    conflict: z.ZodNullable<z.ZodObject<{
+        user: z.ZodOptional<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>;
+        agent: z.ZodOptional<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>;
+        system: z.ZodOptional<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>;
+    }, z.core.$strip>>;
+    hash: z.ZodString;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+            enum: "enum";
+            json: "json";
+        }>;
+        isOptional: z.ZodBoolean;
+        isIndexed: z.ZodBoolean;
+        column: z.ZodOptional<z.ZodString>;
+        enumValues: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>>;
+    relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            belongsTo: "belongsTo";
+            hasMany: "hasMany";
+            hasOne: "hasOne";
+        }>;
+        target: z.ZodString;
+        foreignKey: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type SchemaModelResponse = z.infer<typeof schemaModelResponseSchema>;
+/**
+ * `GET /api/schema` — the schema active on the caller's plane.
+ *
+ * A discriminated union because the two answers carry different fields, and the
+ * difference is the one a caller must act on: `active: false` means nothing has
+ * been pushed to this plane, so `models` is empty and `ablo push` is the fix.
+ * Reporting that as an inactive artifact with absent metadata, rather than as
+ * optional fields on one shape, is what stops a consumer from reading a missing
+ * `version` as a version of zero.
+ */
+export declare const schemaReadResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    active: z.ZodLiteral<false>;
+    environment: z.ZodString;
+    project: z.ZodNullable<z.ZodString>;
+    models: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        typename: z.ZodString;
+        conflict: z.ZodNullable<z.ZodObject<{
+            user: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+            agent: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+            system: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+        }, z.core.$strip>>;
+        hash: z.ZodString;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                date: "date";
+                enum: "enum";
+                json: "json";
+            }>;
+            isOptional: z.ZodBoolean;
+            isIndexed: z.ZodBoolean;
+            column: z.ZodOptional<z.ZodString>;
+            enumValues: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        }, z.core.$strip>>>;
+        relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                belongsTo: "belongsTo";
+                hasMany: "hasMany";
+                hasOne: "hasOne";
+            }>;
+            target: z.ZodString;
+            foreignKey: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    active: z.ZodLiteral<true>;
+    environment: z.ZodString;
+    project: z.ZodNullable<z.ZodString>;
+    models: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        typename: z.ZodString;
+        conflict: z.ZodNullable<z.ZodObject<{
+            user: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+            agent: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+            system: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+        }, z.core.$strip>>;
+        hash: z.ZodString;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                date: "date";
+                enum: "enum";
+                json: "json";
+            }>;
+            isOptional: z.ZodBoolean;
+            isIndexed: z.ZodBoolean;
+            column: z.ZodOptional<z.ZodString>;
+            enumValues: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        }, z.core.$strip>>>;
+        relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                belongsTo: "belongsTo";
+                hasMany: "hasMany";
+                hasOne: "hasOne";
+            }>;
+            target: z.ZodString;
+            foreignKey: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    schemaId: z.ZodString;
+    version: z.ZodNumber;
+    hash: z.ZodString;
+    pushedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>], "active">;
+export type SchemaReadResponse = z.infer<typeof schemaReadResponseSchema>;
+/**
+ * What a log reader calls each kind of entry.
+ *
+ * The log carries the full delta vocabulary, not just writes, so this has a
+ * word for every one of them — a reader should never be shown the stored
+ * letter. The eight are the plain-language face of {@link SyncDeltaAction}.
+ */
+export declare const logOpSchema: z.ZodEnum<{
+    update: "update";
+    visible: "visible";
+    create: "create";
+    delete: "delete";
+    archive: "archive";
+    revive: "revive";
+    group_added: "group_added";
+    group_removed: "group_removed";
+}>;
+export type LogOp = z.infer<typeof logOpSchema>;
+/**
+ * The stored action letter, as a log reader sees it.
+ *
+ * Typed against {@link SyncDeltaAction} so it is total by construction: adding
+ * a ninth action to the vocabulary stops this compiling until it has a word.
+ * The alternative — a lookup with a fallback — is what let `A` reach callers
+ * as the bare letter "a".
+ */
+export declare const LOG_OP_BY_ACTION: Readonly<Record<SyncDeltaAction, LogOp>>;
+/** One entry in the log: what changed, and who changed it. */
+export declare const logEventSchema: z.ZodObject<{
+    object: z.ZodLiteral<"log_event">;
+    id: z.ZodNumber;
+    at: z.ZodString;
+    model: z.ZodString;
+    op: z.ZodEnum<{
+        update: "update";
+        visible: "visible";
+        create: "create";
+        delete: "delete";
+        archive: "archive";
+        revive: "revive";
+        group_added: "group_added";
+        group_removed: "group_removed";
+    }>;
+    recordId: z.ZodString;
+    actor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type LogEvent = z.infer<typeof logEventSchema>;
+/**
+ * One day's usage. `results` is one row per `group_by` combination, carrying
+ * the requested dimensions plus `total` and `count`; with no `group_by` it is a
+ * single ungrouped row. The keys therefore depend on the request, which is why
+ * the row stays open rather than claiming a fixed shape.
+ *
+ * `total` arrives as a string — it is a bigint in the database, and JSON has no
+ * lossless number for it.
+ */
+export declare const usageBucketSchema: z.ZodObject<{
+    starting_at: z.ZodString;
+    ending_at: z.ZodString;
+    results: z.ZodReadonly<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export type UsageBucket = z.infer<typeof usageBucketSchema>;
+/**
+ * One of the org's keys, as a management surface may show it.
+ *
+ * Everything here is safe to display: the prefix identifies a key without being
+ * one. There is deliberately no field for the key itself — plaintext exists only
+ * in the response to the mint that created it, and the store keeps a SHA-256
+ * hash, so no later read can return it.
+ */
+export declare const controlKeySchema: z.ZodObject<{
+    id: z.ZodString;
+    keyPrefix: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    kind: z.ZodString;
+    scopes: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodString;
+    lastUsedAt: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodNullable<z.ZodString>;
+    projectId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ControlKey = z.infer<typeof controlKeySchema>;
+/**
+ * `GET /v1/dashboard/keys` — the org's live, hand-managed keys.
+ *
+ * Like the project list, this is not the canonical {@link ListEnvelope}: it
+ * answers with a bare `keys` array. Stated as it is rather than as the envelope
+ * it resembles.
+ */
+export declare const controlKeyListResponseSchema: z.ZodObject<{
+    keys: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        keyPrefix: z.ZodString;
+        label: z.ZodNullable<z.ZodString>;
+        kind: z.ZodString;
+        scopes: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        createdAt: z.ZodString;
+        lastUsedAt: z.ZodNullable<z.ZodString>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        projectId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ControlKeyListResponse = z.infer<typeof controlKeyListResponseSchema>;
+/**
+ * `POST /v1/dashboard/keys` — the mint.
+ *
+ * `plaintext` is the only place the secret ever appears. The store keeps a
+ * SHA-256 hash, so nothing can return it again: a consumer that reads the wrong
+ * field name here does not get an error, it gets `undefined`, and the key is
+ * gone. That is the whole reason this shape is defined once rather than
+ * described at each end.
+ */
+export declare const keyMintedResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    keyPrefix: z.ZodString;
+    createdAt: z.ZodString;
+    createdBy: z.ZodNullable<z.ZodString>;
+    projectId: z.ZodNullable<z.ZodString>;
+    plaintext: z.ZodString;
+}, z.core.$strip>;
+export type KeyMintedResponse = z.infer<typeof keyMintedResponseSchema>;
+/**
+ * `DELETE /v1/dashboard/keys/:id`. `activeSessionsClosed` reports how many live
+ * connections the revocation cut, so a caller can see it took effect on sessions
+ * already open rather than only on future ones. A second revoke of the same key
+ * is not an error — it answers `alreadyRevoked` and closes nothing.
+ */
+export declare const keyRevokedResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    revoked: z.ZodLiteral<true>;
+    revokedAt: z.ZodOptional<z.ZodString>;
+    alreadyRevoked: z.ZodOptional<z.ZodBoolean>;
+    activeSessionsClosed: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type KeyRevokedResponse = z.infer<typeof keyRevokedResponseSchema>;
+/** `GET /v1/usage` — daily buckets, shaped after a usage report. */
+export declare const usageReportResponseSchema: z.ZodObject<{
+    object: z.ZodLiteral<"usage_report">;
+    buckets: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        starting_at: z.ZodString;
+        ending_at: z.ZodString;
+        results: z.ZodReadonly<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>>;
+    has_more: z.ZodBoolean;
+    data_freshness_seconds: z.ZodNumber;
+}, z.core.$strip>;
+export type UsageReportResponse = z.infer<typeof usageReportResponseSchema>;