@camstack/types 1.2.396 → 1.2.398

package/dist/interfaces/auth.d.ts

@@ -1,4 +1,4 @@
-export { type UserRecord, type ApiKeyRecord, type TokenScope } from '../schemas/auth-records.js';
+export { type UserRecord, type TokenScope } from '../schemas/auth-records.js';
 import type { TokenScope } from '../schemas/auth-records.js';
 export interface UserPermissions {
     isAdmin: boolean;

package/dist/interfaces/event-bus.d.ts

@@ -484,6 +484,15 @@ export interface StorageLocationsChangedPayload {
  * when a camera is assigned to or unassigned from an agent runner. Used by
  * the UI / metrics dashboard. No frame data.
  */
+export type PipelineMotionNoisePayload = {
+    readonly deviceId: number;
+    /** The rolling window the figures are over, in ms. */
+    readonly windowMs: number;
+    /** Share of the window with a detection session open, whole percent. */
+    readonly dutyPct: number;
+    /** Sessions opened in the window. */
+    readonly sessions: number;
+};
 export interface PipelineCameraAssignmentPayload {
     readonly deviceId: number;
     readonly agentNodeId: string;
@@ -1122,6 +1131,25 @@ export interface EventCatalog {
         nodeId?: string;
         locationName?: string;
     };
+    'notification.rule-broken': {
+        ruleId: string;
+        /** `null` when the row was too broken to say. */
+        ruleName: string | null;
+        /** The first reason; `reasons` carries them all. */
+        reason: 'unparseable' | 'device-deleted' | 'target-deleted';
+        reasons: readonly {
+            code: 'unparseable' | 'device-deleted' | 'target-deleted';
+            /** Device ids (decimal) or target ids; empty for `unparseable`. */
+            ids: readonly string[];
+            /** The first schema issue, for `unparseable`. */
+            detail?: string;
+        }[];
+        offendingIds: readonly string[];
+    };
+    'notification.rule-repaired': {
+        ruleId: string;
+        ruleName: string | null;
+    };
     'recording.segment.written': {
         deviceId: number;
         path?: string;
@@ -1251,15 +1279,25 @@ export interface EventCatalog {
         /** The enabled device keys the live probe did not report. */
         readonly unavailableDeviceKeys: readonly string[];
     };
-    /** A camera with an open detection session that has detected nothing for
-     *  longer than the blind threshold. */
+    /** A camera that MOVED (enough session time over enough sessions), was
+     *  analysed, and whose detector produced no raw output at all (D907). */
     'pipeline.detection-blind': {
         readonly deviceId: number;
-        /** How long it has been blind, in ms. */
+        /** Wall time since its last detection, in ms — context, not the gate. */
         readonly blindForMs: number;
-        /** The threshold that was crossed, in ms. */
+        /** The motion bar that was crossed, in ms. */
         readonly thresholdMs: number;
-    };
+        /** Session-open time since the detector last produced anything, in ms. */
+        readonly motionMs: number;
+        /** Sessions opened in that time. */
+        readonly sessions: number;
+        /** Frames since the last detection where candidates fell under the floor. */
+        readonly belowFloor: number;
+    };
+    /** A camera whose motion has been constant with no detection (D907). */
+    'pipeline.motion-noisy': PipelineMotionNoisePayload;
+    /** The camera's motion fell back, or a detection arrived (D907). */
+    'pipeline.motion-calm': PipelineMotionNoisePayload;
     /** Per-camera pipeline config changed — orchestrator hot-reloads the assigned runner. */
     'pipeline.camera-updated': {
         readonly deviceId: number;

package/dist/notification/alert-episode.d.ts

@@ -59,4 +59,11 @@ export declare function alertNodeId(alert: Pick<Alert, 'source' | 'metadata'>):
  * (an `error` episode announces its opening only).
  */
 export declare function alertEpisodeKind(severity: AlertSeverity, phase: AlertEpisodePhase): NcSystemEventKind | null;
+/**
+ * The kind of a CRITICAL episode edge about a DEVICE (D911): the alert's source
+ * is `device`, so it is announced in the devices family as
+ * `device-attention-required` / `-resolved` INSTEAD of `alert-critical`. One
+ * alert notifies once, through one family. `null` for any other severity.
+ */
+export declare function deviceAttentionKind(severity: AlertSeverity, phase: AlertEpisodePhase): NcSystemEventKind | null;
 export declare function alertEpisodePayload(alert: Alert, phase: AlertEpisodePhase, at: number): AlertEpisodePayload;

package/dist/notification/system-event-classes.d.ts

@@ -0,0 +1,73 @@
+/**
+ * D906 — system events that come in PAIRS are one CLASS: a "went bad" edge and
+ * a "came back" edge of the same condition (a stream offline / back online, a
+ * recording stalled / writing again, a rule broken / repaired).
+ *
+ * Nothing new is STORED: a rule keeps listing edge kinds, and a class is the
+ * set of its edges. What the class decides:
+ *
+ *  - an IMMEDIATE system rule that selects a class is told about BOTH edges.
+ *    A stored instant rule listing only one edge of a class is read as the
+ *    whole class (`withSystemEventClasses`) — the operator asked for both
+ *    fronts, and a rule that heard "offline" and never "back online" left
+ *    every outage open-ended on the phone.
+ *  - a SCHEDULED STATE SUMMARY (`systemEventDelivery.mode: 'summary'`) reads a
+ *    class as a SNAPSHOT of the bad state at the scheduled time — never edges,
+ *    never recoveries — so it is NOT widened. The summary already reports a
+ *    state per kind group regardless of which edge was selected (D647).
+ *
+ * One-edge kinds (a node restarting, an update available, a backup done, the
+ * alarm's transitions) stay single. Pure.
+ */
+import type { NcSystemEventCondition, NcSystemEventDelivery, NcSystemEventKind } from '../capabilities/notification-rules.cap.js';
+import { type NcSystemEventFamily } from './system-event-families.js';
+export interface NcSystemEventClassSpec {
+    readonly id: string;
+    readonly family: NcSystemEventFamily;
+    /** The editor's one checkbox. */
+    readonly label: string;
+    /** The edges into the bad state. */
+    readonly bad: readonly NcSystemEventKind[];
+    /** The edges out of it. */
+    readonly recovery: readonly NcSystemEventKind[];
+    /** What the class means on a SCHEDULED summary: the bad state, as a list. */
+    readonly snapshotLabel: string;
+    /**
+     * The state-summary section that snapshots the bad state, or `null` when the
+     * summary has no source for this class (it then reports nothing for it).
+     */
+    readonly snapshotSection: string | null;
+}
+export declare const NC_SYSTEM_EVENT_CLASS_SPECS: readonly NcSystemEventClassSpec[];
+/** Every edge of a class: what an instant rule selecting it listens to. */
+export declare function systemEventClassKinds(spec: NcSystemEventClassSpec): readonly NcSystemEventKind[];
+/** The class a kind belongs to, or `undefined` for a one-edge kind. */
+export declare function systemEventClassOf(kind: string): NcSystemEventClassSpec | undefined;
+/** Is this kind a RECOVERY edge of some class? */
+export declare function isSystemEventRecoveryKind(kind: string): boolean;
+/** The classes of ONE family, for that family's editor. */
+export declare function systemEventClassesFor(family: NcSystemEventFamily): readonly NcSystemEventClassSpec[];
+/**
+ * A kind list with the OTHER front of every class it touches: a bad edge
+ * brings the class's recovery, a recovery brings the class's bad edges. A
+ * sibling bad edge is never added by a bad edge — a rule on
+ * `storage-location-critical` does not start hearing `storage-location-low`.
+ * Input order is kept, each added edge right after the kind that brought it.
+ * Kinds of no class (and legacy names) pass through.
+ */
+export declare function expandSystemEventClasses(kinds: readonly NcSystemEventKind[]): NcSystemEventKind[];
+/** The part of a rule {@link withSystemEventClasses} reads. */
+export interface NcSystemEventClassSubject {
+    readonly delivery: string;
+    readonly conditions: {
+        readonly systemEvent?: NcSystemEventCondition;
+    };
+    readonly systemEventDelivery?: NcSystemEventDelivery;
+}
+/**
+ * An INSTANT system rule with each class it touches completed with both edges;
+ * the rule itself (same object) when there is nothing to add, a summary rule,
+ * or a rule spanning families (`mixed` stays read-only, D637). A copy, never a
+ * mutation.
+ */
+export declare function withSystemEventClasses<T extends NcSystemEventClassSubject>(rule: T): T;

package/dist/records/errors.d.ts

@@ -8,7 +8,7 @@
  * A failed read is never `[]` or `undefined`: it throws one of these.
  */
 /** Every code a records failure carries. */
-export declare const RECORDS_ERROR_CODES: readonly ['rev-conflict', 'too-large', 'unindexed-filter', 'filter-required', 'unknown-kind', 'not-found', 'unique-violation', 'plaintext-secret', 'foreign-marker', 'secret-unavailable', 'invalid-record', 'declaration-refused', 'no-caller', 'batch-too-large'];
+export declare const RECORDS_ERROR_CODES: readonly ['rev-conflict', 'too-large', 'unindexed-filter', 'filter-required', 'unknown-kind', 'not-found', 'unique-violation', 'plaintext-secret', 'foreign-marker', 'secret-unavailable', 'invalid-record', 'declaration-refused', 'no-caller', 'batch-too-large', 'transact-refused'];
 export type RecordsErrorCode = (typeof RECORDS_ERROR_CODES)[number];
 /** The base of every records failure. `detail` is the human part of the message. */
 export declare class RecordsError extends Error {
@@ -68,6 +68,14 @@ export declare class NoCallerError extends RecordsError {
 export declare class BatchTooLargeError extends RecordsError {
     constructor(detail: string);
 }
+/**
+ * A `transact` the engine refuses before touching a row: an op on a kind the
+ * caller did not declare in ONE file and ONE `transactFamily`. The detail names
+ * which rule (`cross-file`, `cross-family`, `no-family`); it is never a silent split.
+ */
+export declare class TransactRefusedError extends RecordsError {
+    constructor(detail: string);
+}
 /**
  * Rebuild the typed error from a message that crossed a wire; `null` when the
  * message is not a records failure.

package/dist/records/index.d.ts

@@ -2,6 +2,7 @@ export * from './constants.js';
 export * from './errors.js';
 export * from './record-kind.js';
 export * from './secret-paths.js';
+export * from './transact-rules.js';
 export * from './records-access.js';
 export * from './entry-kind.js';
 export { makeInMemoryRecords, type InMemoryRecords, type InMemoryRecordsOptions, type InMemorySeedRow, type InMemoryStoredRow, } from './in-memory-records.js';

package/dist/records/record-kind.d.ts

@@ -42,7 +42,7 @@ export declare const EntryDescriptorSchema: z.ZodObject<{
     fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strict>;
 export type EntryDescriptor = z.infer<typeof EntryDescriptorSchema>;
-/** What crosses the wire and sits in the engine's catalog: JSON only, no Zod. */
+/** What crosses the wire from an addon: JSON only, no Zod. An unknown key is refused. */
 export declare const RecordKindDeclarationSchema: z.ZodObject<{
     database: z.ZodDefault<z.ZodEnum<{
         events: "events";
@@ -92,7 +92,6 @@ export declare const RecordKindDeclarationSchema: z.ZodObject<{
     maxDataBytes: z.ZodDefault<z.ZodNumber>;
     secretPaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
     secretArrayKeys: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-    adoptsFrom: z.ZodOptional<z.ZodString>;
     transactFamily: z.ZodOptional<z.ZodString>;
     entry: z.ZodOptional<z.ZodObject<{
         title: z.ZodString;
@@ -100,6 +99,67 @@ export declare const RecordKindDeclarationSchema: z.ZodObject<{
         fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+/**
+ * A declaration as the engine's catalog stored it: an unknown key is DROPPED,
+ * because a row written by an older engine must never stop records from
+ * starting. Only for rows read back from the catalog, never for input.
+ */
+export declare const StoredRecordKindDeclarationSchema: z.ZodObject<{
+    database: z.ZodDefault<z.ZodEnum<{
+        events: "events";
+        settings: "settings";
+    }>>;
+    class: z.ZodEnum<{
+        audit: "audit";
+        config: "config";
+        ephemeral: "ephemeral";
+        ledger: "ledger";
+        mirror: "mirror";
+    }>;
+    writeTrigger: z.ZodString;
+    device: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        optional: "optional";
+        required: "required";
+    }>>;
+    at: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        required: "required";
+    }>>;
+    indexes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        fields: z.ZodArray<z.ZodString>;
+        unique: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    retention: z.ZodUnion<readonly [z.ZodObject<{
+        ttlMs: z.ZodNumber;
+        from: z.ZodEnum<{
+            at: "at";
+            write: "write";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        maxRows: z.ZodOptional<z.ZodNumber>;
+        maxRowsPerDevice: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        owner: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        none: z.ZodString;
+    }, z.core.$strict>]>;
+    deviceRemoval: z.ZodDefault<z.ZodEnum<{
+        delete: "delete";
+        none: "none";
+    }>>;
+    maxDataBytes: z.ZodDefault<z.ZodNumber>;
+    secretPaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    secretArrayKeys: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    transactFamily: z.ZodOptional<z.ZodString>;
+    entry: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        nameField: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
 export type RecordKindDeclaration = z.infer<typeof RecordKindDeclarationSchema>;
 /** The kind names: lower-case, dash separated, short enough for an index name. */
 export declare const RecordKindNameSchema: z.ZodString;

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

@@ -24,7 +24,7 @@
  *  - **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 { DeclareKindResult, IRecordsProvider, RecordQueryInput, RecordTransactOp, RecordWhere } from '../capabilities/records.cap.js';
 import type { SecretsAccess } from '../keychain/secrets-access.js';
 import { type DefinedRecordKind } from './record-kind.js';
 /** The wire: the `records` provider's methods. The owner is never an argument. */
@@ -64,8 +64,36 @@ export interface RecordQueryOptions {
     /** Resolve the secret fields of the page in ONE keychain call. A failure throws. */
     readonly resolveSecrets?: boolean;
 }
+/**
+ * One write prepared for {@link RecordsAccess.transact}: the wire op plus the
+ * undo of the keychain writes made for it (a refused transaction puts the
+ * previous secret values back). Build it with the kind handle's `txPut`,
+ * `txPatch` and `txDelete`, which run the same validation and secret handling
+ * as the single `put` / `patch` / `delete`.
+ */
+export interface PreparedTransactOp {
+    readonly wire: RecordTransactOp;
+    readonly rollback: () => Promise<void>;
+}
+/** What one op of a transaction did, in op order. `rev` is `null` for a delete. */
+export interface TransactOpResult {
+    readonly rev: number | null;
+    readonly deleted: boolean;
+}
 export interface RecordKindHandle<T> {
     readonly name: string;
+    /** `put` as an op of {@link RecordsAccess.transact}. */
+    txPut(input: RecordPut<T>, opts?: {
+        readonly ifRev?: number;
+    }): Promise<PreparedTransactOp>;
+    /** `patch` as an op of {@link RecordsAccess.transact}. */
+    txPatch(id: string, partial: Readonly<Record<string, unknown>>, opts?: {
+        readonly ifRev?: number;
+        readonly at?: number | null;
+        readonly expiresAt?: number | null;
+    }): Promise<PreparedTransactOp>;
+    /** `delete` as an op of {@link RecordsAccess.transact}. */
+    txDelete(id: string): PreparedTransactOp;
     get(id: string): Promise<RecordRow<T> | null>;
     getMany(ids: readonly string[]): Promise<readonly RecordRow<T>[]>;
     /** `get` with the secret fields resolved from the keychain. */
@@ -133,6 +161,13 @@ export interface RecordsAccess {
      */
     declare(kinds: Readonly<Record<string, DefinedRecordKind>>): Promise<Readonly<Record<string, DeclareKindResult>>>;
     kind<S extends z.ZodType>(definition: DefinedRecordKind<S>): RecordKindHandle<z.infer<S>>;
+    /**
+     * Several writes in ONE transaction: all land or none does. Every op's kind
+     * must be declared by this owner in ONE database file under ONE
+     * `transactFamily`; anything else throws `records/transact-refused` before a
+     * row is touched. Results are in op order.
+     */
+    transact(ops: readonly PreparedTransactOp[]): Promise<readonly TransactOpResult[]>;
     /**
      * 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

package/dist/records/transact-rules.d.ts

@@ -0,0 +1,7 @@
+import type { RecordKindDeclaration } from './record-kind.js';
+export interface TransactMember {
+    readonly kind: string;
+    readonly declaration: Pick<RecordKindDeclaration, 'database' | 'transactFamily'>;
+}
+/** Throws {@link TransactRefusedError} unless the kinds may share one transaction. */
+export declare function assertTransactScope(members: readonly TransactMember[]): void;

package/dist/schemas/auth-records.d.ts

@@ -202,18 +202,6 @@ export declare const UserRecordSchema: z.ZodObject<{
     updatedAt: z.ZodNumber;
 }, z.core.$strip>;
 export type UserRecord = z.infer<typeof UserRecordSchema>;
-export declare const ApiKeyRecordSchema: z.ZodObject<{
-    id: z.ZodString;
-    label: z.ZodString;
-    isAdmin: z.ZodDefault<z.ZodBoolean>;
-    allowedProviders: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>;
-    allowedDevices: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>;
-    tokenHash: z.ZodString;
-    tokenPrefix: z.ZodString;
-    createdAt: z.ZodNumber;
-    lastUsedAt: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export type ApiKeyRecord = z.infer<typeof ApiKeyRecordSchema>;
 export declare const ScopedTokenSchema: z.ZodObject<{
     id: z.ZodString;
     userId: z.ZodString;