@camstack/types 1.2.379 → 1.2.381

package/dist/records/records-access.d.ts

@@ -0,0 +1,153 @@
+/**
+ * `ctx.records` - an addon's handle on its OWN record kinds (D881).
+ *
+ * The owner is closed over at construction (the addon id) and the transport
+ * decides how it is proven: a hub in-process caller states it, a forked or
+ * agent addon sends the bare input and the parent stamps who is calling - the
+ * `ctx.secrets` model. Nothing a caller passes can change it.
+ *
+ * ## Secrets are a feature of the kind
+ *
+ * A field of the kind's Zod schema marked `.meta({ secret: true })` is stored
+ * as a keychain MARKER bound to the row's own ref and never as a value:
+ *
+ *  - **write**: a non-empty string goes to the keychain FIRST, then the row is
+ *    written holding the marker. The redaction token (or an empty/absent
+ *    value on a `patch`) keeps what is stored; `put` is a full replace, so a
+ *    secret field it omits is removed - and so is its keychain value. A locked
+ *    keychain refuses the whole write (`records/secret-unavailable`):
+ *    plaintext is never stored, never logged, never in an error message.
+ *  - **read**: every read shows the redaction token for a set secret. The
+ *    owner that needs the value asks for it (`getResolved`, `query` with
+ *    `resolveSecrets`); the keychain answering `unavailable` or `missing`
+ *    THROWS - a locked keychain is never read as an empty password.
+ *  - **delete**: the keychain values of the removed rows go with them.
+ */
+import type { z } from 'zod';
+import type { DeclareKindResult, IRecordsProvider, RecordQueryInput, RecordWhere } from '../capabilities/records.cap.js';
+import type { SecretsAccess } from '../keychain/secrets-access.js';
+import { type DefinedRecordKind } from './record-kind.js';
+import { collectSecretLeaves } from './secret-paths.js';
+/** The wire: the `records` provider's methods. The owner is never an argument. */
+export type RecordsTransport = IRecordsProvider;
+/** A row as the owner sees it. Secret fields hold the redaction token unless resolved. */
+export interface RecordRow<T> {
+    readonly id: string;
+    readonly deviceId: number | null;
+    readonly at: number | null;
+    readonly expiresAt: number | null;
+    readonly rev: number;
+    readonly updatedAt: number;
+    readonly data: T;
+}
+export interface RecordPut<T> {
+    readonly id: string;
+    readonly deviceId?: number;
+    readonly at?: number;
+    readonly expiresAt?: number;
+    readonly data: T;
+}
+export interface RecordsLogger {
+    warn(message: string, extras?: {
+        readonly meta?: Record<string, unknown>;
+    }): void;
+}
+export interface RecordsAccessOptions {
+    readonly owner: string;
+    readonly transport: RecordsTransport;
+    /** The owner's keychain handle; `null` where there is none (a kind with secrets then refuses). */
+    readonly secrets: SecretsAccess | null;
+    readonly logger?: RecordsLogger;
+    /** Builds the transport for another owner - in-process system builtins only. */
+    readonly transportForOwner?: (owner: string) => RecordsTransport;
+}
+export interface RecordQueryOptions {
+    /** Resolve the secret fields of the page in ONE keychain call. A failure throws. */
+    readonly resolveSecrets?: boolean;
+}
+export interface RecordKindHandle<T> {
+    readonly name: string;
+    get(id: string): Promise<RecordRow<T> | null>;
+    getMany(ids: readonly string[]): Promise<readonly RecordRow<T>[]>;
+    /** `get` with the secret fields resolved from the keychain. */
+    getResolved(id: string): Promise<RecordRow<T> | null>;
+    put(input: RecordPut<T>, opts?: {
+        readonly ifRev?: number;
+    }): Promise<{
+        readonly rev: number;
+    }>;
+    putMany(inputs: readonly RecordPut<T>[]): Promise<{
+        readonly count: number;
+    }>;
+    /** RFC 7396 merge in one statement. `null` removes a field. */
+    patch(id: string, partial: Readonly<Record<string, unknown>>, opts?: {
+        readonly ifRev?: number;
+        readonly at?: number | null;
+        readonly expiresAt?: number | null;
+    }): Promise<{
+        readonly rev: number;
+    }>;
+    delete(id: string): Promise<boolean>;
+    deleteMany(ids: readonly string[]): Promise<number>;
+    query(q: Omit<RecordQueryInput, 'kind' | 'limit'> & {
+        readonly limit?: number;
+    }, opts?: RecordQueryOptions): Promise<{
+        readonly records: readonly RecordRow<T>[];
+        readonly nextCursor: string | null;
+    }>;
+    count(q: {
+        readonly deviceId?: number;
+        readonly atFrom?: number;
+        readonly atTo?: number;
+        readonly where?: RecordWhere;
+    }): Promise<number>;
+    histogram(q: {
+        readonly deviceId?: number;
+        readonly from: number;
+        readonly to: number;
+        readonly bucketMs: number;
+    }): Promise<readonly {
+        readonly bucketStart: number;
+        readonly count: number;
+    }[]>;
+    aggregate(q: {
+        readonly op: 'sum' | 'min' | 'max' | 'count';
+        readonly field?: string;
+        readonly groupBy?: string;
+        readonly where?: RecordWhere;
+    }): Promise<readonly {
+        readonly group: string | number | null;
+        readonly value: number | null;
+    }[]>;
+    deleteWhere(q: {
+        readonly deviceId?: number;
+        readonly atBefore?: number;
+        readonly where?: RecordWhere;
+    }): Promise<number>;
+    allocateId(): Promise<number>;
+}
+export interface RecordsAccess {
+    readonly owner: string;
+    /**
+     * Reconcile this addon's kinds (the engine creates the indexes; additive
+     * only). THROWS {@link AdoptionPendingError} while a kind is empty and the
+     * legacy table it adopts from still holds rows - the boot guard (D853: no
+     * migration code in the product).
+     */
+    declare(kinds: Readonly<Record<string, DefinedRecordKind>>): Promise<Readonly<Record<string, DeclareKindResult>>>;
+    kind<S extends z.ZodType>(definition: DefinedRecordKind<S>): RecordKindHandle<z.infer<S>>;
+    /**
+     * In-process SYSTEM builtins only (the entries service): act as the door of
+     * another owner. `null` everywhere else - a forked addon has no way to state
+     * an identity the transport would accept.
+     */
+    readonly forOwner: ((owner: string) => RecordsAccess) | null;
+    /** The D865 hook body: delete the device's rows from every kind declared `deviceRemoval: 'delete'`. */
+    deleteDevice(deviceId: number, opts?: {
+        readonly kinds?: readonly string[];
+    }): Promise<Readonly<Record<string, number>>>;
+}
+/** Build the owner's records handle. */
+export declare function createRecordsAccess(options: RecordsAccessOptions): RecordsAccess;
+/** Re-exported so adoption tooling builds the same concrete paths the facade does. */
+export { collectSecretLeaves };

package/dist/records/secret-paths.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Secret fields of a record, addressed the way a Zod schema declares them
+ * (`collectZodSecretPaths`): dotted keys, `[]` for "each element of this array"
+ * (`auth.accessToken`, `headers[].value`).
+ *
+ * Array elements are matched by a DECLARED id key (`secretArrayKeys`:
+ * `{ headers: 'name' }`), never by index, so reordering a list keeps every
+ * keychain ref (the same rule as `arrayItemFieldPath`). The concrete path of a
+ * leaf names its element: `headers[X-Api].value`.
+ *
+ * Pure and browser-safe. Nothing here mutates: every transform returns a new value.
+ */
+import { arrayItemFieldPath } from '../keychain/secret-ref.js';
+/** One segment of a declared path. */
+export interface SecretPathSegment {
+    readonly key: string;
+    /** `true` when the key holds an array and the path continues into each element. */
+    readonly each: boolean;
+}
+/** The array prefixes (declared form, e.g. `headers` or `a.headers`) of a path. */
+export declare function parseSecretPath(path: string): readonly SecretPathSegment[];
+/** The declared array prefixes of `path` that need an id key (`headers`, `a.rows`). */
+export declare function secretArrayPrefixes(path: string): readonly string[];
+/** One secret leaf found in a record body. */
+export interface SecretLeaf {
+    /** The declared path it matched (`headers[].value`). */
+    readonly declared: string;
+    /** Its concrete path, naming array elements by id (`headers[X-Api].value`). */
+    readonly concrete: string;
+    readonly value: unknown;
+}
+/**
+ * Visit every secret leaf PRESENT in `data` (an absent branch has nothing to
+ * visit). `replace` returns the new leaf value, or {@link REMOVE_LEAF}; the
+ * result is a new body, `data` is untouched.
+ */
+export declare const REMOVE_LEAF: unique symbol;
+export type LeafReplacement = unknown | typeof REMOVE_LEAF;
+/** Replace/remove every present secret leaf; returns a NEW body. */
+export declare function mapSecretLeaves(data: unknown, paths: readonly string[], arrayKeys: Readonly<Record<string, string>>, visit: (leaf: SecretLeaf) => LeafReplacement): unknown;
+/** Every present secret leaf, read-only. */
+export declare function collectSecretLeaves(data: unknown, paths: readonly string[], arrayKeys: Readonly<Record<string, string>>): readonly SecretLeaf[];
+/**
+ * The keychain collection name a kind's secrets live under. Prefixed so a
+ * record's refs never collide with the refs a legacy collection of the same name
+ * already holds during an adoption.
+ */
+export declare function recordSecretCollection(kind: string): string;
+/** The ONE ref a row's secret field may carry: the engine and the facade both build it here. */
+export declare function recordSecretRef(owner: string, kind: string, rowId: string, concretePath: string): string;
+/** A concrete path built from a flat array item, re-exported for adoption tooling. */
+export declare const recordArrayItemPath: typeof arrayItemFieldPath;

package/dist/records/settings-array-adopts-from.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Legacy source for entry adoption (B3): a list stored under addon-settings
+ * `<addonId>.<key>` until records-adopt copies rows into the entry kind.
+ */
+export declare const SETTINGS_ARRAY_ADOPTS_PREFIX = "@settings-array/";
+/** The `adoptsFrom` value for an addon-settings array field. */
+export declare function settingsArrayAdoptsFrom(addonId: string, settingsKey: string): string;
+/** When non-null, `from` names an addon-settings array blob, not a SQL table. */
+export declare function parseSettingsArrayAdoptsFrom(from: string): {
+    readonly addonId: string;
+    readonly settingsKey: string;
+} | null;

package/dist/records/settings-brokers-adopts-from.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Legacy source for broker entry adoption (B2): brokers live in addon-settings
+ * as one row `<addonId>.brokers` whose value is an array until records-adopt
+ * copies them into the entry kind.
+ */
+export declare const SETTINGS_BROKERS_ADOPTS_PREFIX = "@settings-brokers/";
+/** The `adoptsFrom` value for an addon's broker entry kind. */
+export declare function settingsBrokersAdoptsFrom(addonId: string): string;
+/** When non-null, `from` names an addon-settings brokers blob, not a SQL table. */
+export declare function parseSettingsBrokersAdoptsFrom(from: string): string | null;