@fonoster/callrecord 0.0.0-stage → 0.30.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fonoster Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/CallRecordWriter.d.ts

@@ -0,0 +1,135 @@
+import { RecordIndexEntry } from "./indexEntry";
+import { KeyCustody } from "./keys";
+import { SigningKey } from "./sign";
+import { FsWorkingStore, RecordStore } from "./storage";
+import { RecordEntry, SealingVersion } from "./types";
+/** Call-record open question O1: a record is sealed within 30 s of hangup. */
+export declare const SEAL_DEADLINE_MS = 30000;
+/** Parts a retention policy or a deletion request can name (call-record "Retention"). */
+export declare const RECORD_PARTS: readonly ["recording", "transcript", "messages"];
+export type RecordPart = (typeof RECORD_PARTS)[number];
+/** A maintenance request named another workspace than the stored record's (RV-B6). */
+export declare class WorkspaceMismatchError extends Error {
+    constructor(callRef: string);
+}
+/** One audited deletion (call-record "every deletion ... produces an audit entry"). */
+export type AuditEntry = {
+    callRef: string;
+    workspaceRef: string | null;
+    action: "delete_part" | "erase";
+    part: RecordPart | "all";
+    reason: string;
+    actor: string;
+    at: string;
+    /** The version that records the deletion. */
+    version: number;
+};
+export type CallRecordWriterOptions = {
+    working: FsWorkingStore;
+    /** The region's record store. */
+    store: RecordStore;
+    /**
+     * A workspace's own bucket, if it configured one (design V2). When it fails at seal the record
+     * stays in the region store and the index says so (open question O7, interim).
+     */
+    workspaceStore?: (workspaceRef: string) => RecordStore | undefined;
+    /** A fixed key, or a custody that names the current key and signs (task 2.6). */
+    key: SigningKey | KeyCustody;
+    region: string;
+    /** Called after each sealed version: index it, send `call_record.sealed`. */
+    onSealed?: (entry: RecordIndexEntry) => void;
+    /**
+     * How often this writer marks its live calls' working records as alive (ST-5), so a writer
+     * sweeping the same directory leaves them alone. Well under the sweep's deadline.
+     */
+    heartbeatMs?: number;
+};
+/**
+ * Builds call records live and seals them at hangup (call-record "The record is built during the
+ * call and sealed at hangup"). It implements the gateway's CallRecordSink interface.
+ */
+export declare class CallRecordWriter {
+    private readonly options;
+    /** Calls appended in this process and not closed yet; the sweep leaves them alone. */
+    private readonly active;
+    private readonly sealing;
+    private readonly custody;
+    /** Names this writer in seal locks on a shared working directory. */
+    private readonly owner;
+    private heartbeat?;
+    constructor(options: CallRecordWriterOptions);
+    get region(): string;
+    append(callRef: string, entry: RecordEntry): void;
+    /** Marks every live call of this writer as alive (see `heartbeatMs`). */
+    beat(): void;
+    /** Stops the heartbeat (shutdown; a writer that dies stops it too). */
+    stop(): void;
+    /** Where the recorder writes this call's tracks (removed once the record is sealed). */
+    recordingDir(callRef: string): string;
+    /** The call ended: seal its record in the background. */
+    close(callRef: string): void;
+    /** Resolves once every seal in progress has finished (tests, shutdown). */
+    flush(): Promise<void>;
+    /** The store a workspace's records go to. */
+    storeFor(workspaceRef?: string | null): RecordStore;
+    /**
+     * The store that holds an existing record. With its indexed location (RV-B10) that is the
+     * store at that location: a record whose workspace bucket failed at seal stays in the region
+     * store, and a workspace that configured a bucket later keeps its older records where they
+     * are. Without a location, the workspace's current store.
+     */
+    storeAt(location: string | undefined, workspaceRef?: string | null): RecordStore;
+    /** Seals a working record as version 1 and returns it; idempotent while in progress. */
+    seal(callRef: string): Promise<SealingVersion>;
+    /** The sealed version 1 another writer stored, once its seal lock is gone. */
+    private sealedByOther;
+    /**
+     * Seals under a lock in the working directory, so of all the writers that share it exactly one
+     * seals a call (its hangup on the owner, or a sweep elsewhere), once (ST-5).
+     */
+    private doSeal;
+    private sealLocked;
+    private sealed;
+    /**
+     * Seals records whose calls stopped appending more than `deadlineMs` ago without a hangup (a
+     * gateway that crashed). Returns the callRefs sealed.
+     */
+    sweep(now?: number, deadlineMs?: number): Promise<string[]>;
+    /** Adds a version derived from the current one (it references its predecessor). */
+    private newVersion;
+    /**
+     * Adds to a sealed record as a new version that references its predecessor (call-record
+     * "Additions after sealing create new versions"); the previous version is unchanged.
+     */
+    addVersion(callRef: string, additions: {
+        analysis?: Record<string, unknown>[];
+    }, workspaceRef?: string, location?: string): Promise<SealingVersion>;
+    /**
+     * Deletes parts of a record (retention policy or a request) and writes a version that records
+     * each removal (call-record "Retention follows workspace policy and deletions are audited").
+     * The recording and the messages are files; the transcript lives inside the vCons, so earlier
+     * versions' contents are deleted too and only their manifests remain.
+     */
+    deleteParts(callRef: string, requested: RecordPart[], by: {
+        reason: string;
+        actor: string;
+        workspaceRef?: string | null;
+        location?: string;
+    }): Promise<{
+        sealed: SealingVersion;
+        audit: AuditEntry[];
+    }>;
+    /**
+     * Erases one call (call-record "Erasing one call"): every file and version is deleted, and a
+     * signed tombstone version states when, why and by whom. It holds no call content.
+     */
+    erase(callRef: string, by: {
+        reason: string;
+        actor: string;
+        workspaceRef?: string | null;
+        location?: string;
+    }): Promise<{
+        audit: AuditEntry[];
+        version: number;
+    }>;
+}