@fonoster/sdk 0.26.0 → 0.30.0

package/README.md

@@ -92,7 +92,7 @@ async function main() {
   const applications = new SDK.Applications(client);
   await applications.createApplication({
     name: "MyApp",
-    type: "EXTERNAL",
+    type: "STREAM",
     endpoint: "localhost:50061" // Your app's endpoint
  });
 }
@@ -694,7 +694,8 @@ apiKeys
 
 ## Applications
 Fonoster Applications, part of the Fonoster Voice Subsystem,
-allow you to create, update, retrieve, and delete Voice Applications.
+allow you to create, update, retrieve, and delete Applications: streams (your own WebSocket
+server) and Autopilot agents.
 Note that an active Fonoster deployment is required.
 
 **Kind**: global class  
@@ -747,7 +748,7 @@ async function main(request) {
 
 const request = {
   name: "My application",
-  type: "EXTERNAL",
+  type: "STREAM",
   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
   speechToText: {
     productRef: "stt.deepgram",
@@ -778,7 +779,7 @@ Creates a new Application in Fonoster. The only required fields are the name and
 | --- | --- | --- |
 | request | <code>CreateApplicationRequest</code> | The request object that contains the necessary information to create a new application |
 | request.name | <code>string</code> | The name of the application |
-| request.type | <code>ApplicationType</code> | The type of application (e.g., EXTERNAL) |
+| request.type | <code>ApplicationType</code> | The type of application: STREAM or AUTOPILOT |
 | request.endpoint | <code>string</code> | The endpoint where the application is hosted |
 | request.speechToText | <code>SpeechToText</code> | The speech-to-text configuration |
 | request.speechToText.productRef | <code>string</code> | The product reference of the speech-to-text engine (e.g., stt.deepgram) |
@@ -796,7 +797,7 @@ const apps = new SDK.Applications(client); // Existing client object
 
 const request = {
   name: "My application",
-  type: "EXTERNAL",
+  type: "STREAM",
   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
   speechToText: {
     productRef: "stt.deepgram",

package/dist/node/Applications.d.ts

@@ -16,57 +16,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Application, BaseApiObject, CreateApplicationRequest, EvaluateIntelligenceEvent, EvaluateIntelligenceRequest, ListApplicationsRequest, ListApplicationsResponse, UpdateApplicationRequest } from "@fonoster/types";
+import { Application, BaseApiObject, CreateApplicationRequest, CreateApplicationResponse, EvaluateIntelligenceEvent, EvaluateIntelligenceRequest, ListApplicationsRequest, ListApplicationsResponse, RotateSigningSecretResponse, UpdateApplicationRequest, UpdateApplicationResponse } from "@fonoster/types";
 import { FonosterClient } from "./client/types";
 import { TestTokenResponse } from "./generated/node/applications_pb";
-/**
- * @classdesc Fonoster Applications, part of the Fonoster Voice Subsystem,
- * allow you to create, update, retrieve, and delete Voice Applications.
- * Note that an active Fonoster deployment is required.
- *
- * @example
- *
- * const SDK = require("@fonoster/sdk");
- *
- * async function main(request) {
- *   const apiKey = "your-api-key";
- *   const apiSecret = "your-api-secret"
- *   const accessKeyId = "WO00000000000000000000000000000000";
- *
- *   try {
- *     const client = SDK.Client({ accessKeyId });
- *     await client.loginWithApiKey(apiKey, apiSecret);
- *
- *     const apps = new SDK.Applications(client);
- *     const response = await apps.createApplication(request);
- *
- *     console.log(response); // successful response
- *   } catch (e) {
- *     console.error(e); // an error occurred
- *   }
- * }
- *
- * const request = {
- *   name: "My application",
- *   type: "EXTERNAL",
- *   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
- *   speechToText: {
- *     productRef: "stt.deepgram",
- *     config: {
- *       model: "nova-2",
- *       languageCode: "en-US"
- *     }
- *   },
- *   textToSpeech: {
- *     productRef: "tts.elevenlabs",
- *     config: {
- *       voice: "lrTWbMInQjSJ9q5ywFKP"
- *     }
- *   }
- * };
- *
- * main(request);
- */
 declare class Applications {
     private readonly client;
     /**
@@ -82,37 +34,19 @@ declare class Applications {
      *
      * @param {CreateApplicationRequest} request - The request object that contains the necessary information to create a new application
      * @param {string} request.name - The name of the application
-     * @param {ApplicationType} request.type - The type of application (e.g., EXTERNAL)
+     * @param {ApplicationType} request.type - The type of application: STREAM or AUTOPILOT
      * @param {string} request.endpoint - The endpoint where the application is hosted
-     * @param {SpeechToText} request.speechToText - The speech-to-text configuration
-     * @param {string} request.speechToText.productRef - The product reference of the speech-to-text engine (e.g., stt.deepgram)
-     * @param {object} request.speechToText.config - The configuration object for the speech-to-text engine (e.g., { model: "nova-2", languageCode: "en-US" })
-     * @param {TextToSpeech} request.textToSpeech - The text-to-speech configuration
-     * @param {string} request.textToSpeech.productRef - The product reference of the text-to-speech engine (e.g., tts.elevenlabs)
-     * @param {object} request.textToSpeech.config - The configuration object for the text-to-speech engine (e.g., { voice: "lrTWbMInQjSJ9q5ywFKP" })
      * @param {Intelligence} request.intelligence - The intelligence configuration
-     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., llm.groq)
-     * @param {object} request.intelligence.config - The configuration object for the intelligence engine
+     * @param {object} request.intelligence.config - Autopilot agents: the agent (its model is a catalog id such as openai/gpt-4o-mini)
      * @return {Promise<CreateAppResponse>} - The response object that contains the reference to the newly created application
      * @example
      * const apps = new SDK.Applications(client); // Existing client object
      *
      * const request = {
      *   name: "My application",
-     *   type: "EXTERNAL",
-     *   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
-     *   speechToText: {
-     *     productRef: "stt.deepgram",
-     *     config: {
-     *       languageCode: "en-US"
-     *     }
-     *   },
-     *   textToSpeech: {
-     *     productRef: "tts.elevenlabs",
-     *     config: {
-     *       voice: "lrTWbMInQjSJ9q5ywFKP"
-     *     }
-     *   }
+     *   type: "STREAM",
+     *   url: "wss://bot.example.com/session",
+     *   speech: { voice: "elevenlabs/21m00Tcm4TlvDq8ikWAM", language: "en-US" }
      * };
      *
      * apps
@@ -120,7 +54,7 @@ declare class Applications {
      *   .then(console.log) // successful response
      *   .catch(console.error); // an error occurred
      */
-    createApplication(request: CreateApplicationRequest): Promise<BaseApiObject>;
+    createApplication(request: CreateApplicationRequest): Promise<CreateApplicationResponse>;
     /**
      * Retrieves an existing Application in the Workspace.
      *
@@ -144,15 +78,8 @@ declare class Applications {
      * @param {string} request.ref - The reference of the application to update
      * @param {string} request.name - The name of the application
      * @param {string} request.endpoint - The endpoint where the application is hosted
-     * @param {SpeechToText} request.speechToText - The speech-to-text configuration
-     * @param {string} request.speechToText.productRef - The product reference of the speech-to-text engine (e.g., stt.deepgram)
-     * @param {object} request.speechToText.config - The configuration object for the speech-to-text engine (e.g., { model: "nova-2", languageCode: "en-US" })
-     * @param {TextToSpeech} request.textToSpeech - The text-to-speech configuration
-     * @param {string} request.textToSpeech.productRef - The product reference of the text-to-speech engine (e.g., tts.elevenlabs)
-     * @param {object} request.textToSpeech.config - The configuration object for the text-to-speech engine (e.g., { voice: "lrTWbMInQjSJ9q5ywFKP" })
      * @param {Intelligence} request.intelligence - The intelligence configuration
-     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., llm.groq)
-     * @param {object} request.intelligence.config - The configuration object for the intelligence engine
+     * @param {object} request.intelligence.config - Autopilot agents: the agent (its model is a catalog id such as openai/gpt-4o-mini)
      * @return {Promise<BaseApiObject>} - The response object that contains the reference to the updated application
      * @example
      * const apps = new SDK.Applications(client); // Existing client object
@@ -160,7 +87,7 @@ declare class Applications {
      * const request = {
      *   ref: "00000000-0000-0000-0000-000000000000",
      *   name: "My application",
-     *   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
+     *   url: "wss://bot.example.com/session"
      * };
      *
      * apps
@@ -168,7 +95,7 @@ declare class Applications {
      *   .then(console.log) // successful response
      *   .catch(console.error); // an error occurred
      */
-    updateApplication(request: UpdateApplicationRequest): Promise<BaseApiObject>;
+    updateApplication(request: UpdateApplicationRequest): Promise<UpdateApplicationResponse>;
     /**
      * Retrieves a list of Applications from Fonoster.
      *
@@ -206,13 +133,22 @@ declare class Applications {
      *   .then(console.log) // successful response
      *   .catch(console.error); // an error occurred
      */
+    /**
+     * Replaces the app's signing secret. The old secret stops working at once (no overlap window),
+     * so redeploy the app with the new one. The secret is returned only here.
+     *
+     * @param {string} ref - The application's reference
+     * @return {Promise<RotateSigningSecretResponse>} - The new secret and its hint
+     * @example
+     * const { signingSecret } = await applications.rotateSigningSecret("00000000-...");
+     */
+    rotateSigningSecret(ref: string): Promise<RotateSigningSecretResponse>;
     deleteApplication(ref: string): Promise<BaseApiObject>;
     /**
      * Evaluates the intelligence of an application.
      *
      * @param {EvaluateIntelligenceRequest} request - The request object that contains the necessary information to evaluate the intelligence of an application
-     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., llm.groq)
-     * @param {object} request.intelligence.config - The configuration object for the intelligence engine
+     * @param {object} request.intelligence.config - Autopilot agents: the agent (its model is a catalog id such as openai/gpt-4o-mini)
      * @return {AsyncGenerator<EvaluateIntelligenceEvent>} - Stream of evaluation events (step results, scenario summaries, or errors)
      * @example
      * const apps = new SDK.Applications(client);

package/dist/node/Applications.js

@@ -27,7 +27,8 @@ const applications_pb_1 = require("./generated/node/applications_pb");
 const utils_1 = require("./utils");
 /**
  * @classdesc Fonoster Applications, part of the Fonoster Voice Subsystem,
- * allow you to create, update, retrieve, and delete Voice Applications.
+ * allow you to create, update, retrieve, and delete Applications: streams (your own WebSocket
+ * server) and Autopilot agents.
  * Note that an active Fonoster deployment is required.
  *
  * @example
@@ -54,25 +55,30 @@ const utils_1 = require("./utils");
  *
  * const request = {
  *   name: "My application",
- *   type: "EXTERNAL",
- *   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
- *   speechToText: {
- *     productRef: "stt.deepgram",
- *     config: {
- *       model: "nova-2",
- *       languageCode: "en-US"
- *     }
- *   },
- *   textToSpeech: {
- *     productRef: "tts.elevenlabs",
- *     config: {
- *       voice: "lrTWbMInQjSJ9q5ywFKP"
- *     }
- *   }
+ *   type: "STREAM",
+ *   url: "wss://bot.example.com/session", // Serves the session protocol (@fonoster/voice)
+ *   protocol: "fonoster", // or "twilio" for a Twilio Media Streams server
+ *   speech: { voice: "elevenlabs/21m00Tcm4TlvDq8ikWAM", language: "en-US" }
  * };
  *
  * main(request);
  */
+/** Nested messages of create and update requests (the application model). */
+const REQUEST_OBJECTS = [
+    ["intelligence", applications_pb_1.ProductContainer],
+    ["speech", applications_pb_1.SpeechDefaults],
+    ["audio", applications_pb_1.AudioFormat],
+    ["listeners", applications_pb_1.Listener],
+    ["amd", applications_pb_1.AmdSettings]
+];
+/** Repeated fields come back as `listenersList` when empty; always return `listeners`. */
+function withSessionFields(app) {
+    const { listenersList, ...rest } = app;
+    return {
+        ...rest,
+        listeners: (rest.listeners ?? listenersList ?? [])
+    };
+}
 class Applications {
     client;
     /**
@@ -90,37 +96,19 @@ class Applications {
      *
      * @param {CreateApplicationRequest} request - The request object that contains the necessary information to create a new application
      * @param {string} request.name - The name of the application
-     * @param {ApplicationType} request.type - The type of application (e.g., EXTERNAL)
+     * @param {ApplicationType} request.type - The type of application: STREAM or AUTOPILOT
      * @param {string} request.endpoint - The endpoint where the application is hosted
-     * @param {SpeechToText} request.speechToText - The speech-to-text configuration
-     * @param {string} request.speechToText.productRef - The product reference of the speech-to-text engine (e.g., stt.deepgram)
-     * @param {object} request.speechToText.config - The configuration object for the speech-to-text engine (e.g., { model: "nova-2", languageCode: "en-US" })
-     * @param {TextToSpeech} request.textToSpeech - The text-to-speech configuration
-     * @param {string} request.textToSpeech.productRef - The product reference of the text-to-speech engine (e.g., tts.elevenlabs)
-     * @param {object} request.textToSpeech.config - The configuration object for the text-to-speech engine (e.g., { voice: "lrTWbMInQjSJ9q5ywFKP" })
      * @param {Intelligence} request.intelligence - The intelligence configuration
-     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., llm.groq)
-     * @param {object} request.intelligence.config - The configuration object for the intelligence engine
+     * @param {object} request.intelligence.config - Autopilot agents: the agent (its model is a catalog id such as openai/gpt-4o-mini)
      * @return {Promise<CreateAppResponse>} - The response object that contains the reference to the newly created application
      * @example
      * const apps = new SDK.Applications(client); // Existing client object
      *
      * const request = {
      *   name: "My application",
-     *   type: "EXTERNAL",
-     *   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
-     *   speechToText: {
-     *     productRef: "stt.deepgram",
-     *     config: {
-     *       languageCode: "en-US"
-     *     }
-     *   },
-     *   textToSpeech: {
-     *     productRef: "tts.elevenlabs",
-     *     config: {
-     *       voice: "lrTWbMInQjSJ9q5ywFKP"
-     *     }
-     *   }
+     *   type: "STREAM",
+     *   url: "wss://bot.example.com/session",
+     *   speech: { voice: "elevenlabs/21m00Tcm4TlvDq8ikWAM", language: "en-US" }
      * };
      *
      * apps
@@ -137,11 +125,7 @@ class Applications {
             metadata: this.client.getMetadata(),
             request: reqWithStructOverride,
             enumMapping: [["type", applications_pb_1.ApplicationType]],
-            objectMapping: [
-                ["textToSpeech", applications_pb_1.ProductContainer],
-                ["speechToText", applications_pb_1.ProductContainer],
-                ["intelligence", applications_pb_1.ProductContainer]
-            ]
+            objectMapping: REQUEST_OBJECTS
         });
     }
     /**
@@ -167,13 +151,9 @@ class Applications {
             metadata: this.client.getMetadata(),
             request: { ref },
             enumMapping: [["type", applications_pb_1.ApplicationType]],
-            objectMapping: [
-                ["textToSpeech", applications_pb_1.ProductContainer],
-                ["speechToText", applications_pb_1.ProductContainer],
-                ["intelligence", applications_pb_1.ProductContainer]
-            ]
+            objectMapping: [["intelligence", applications_pb_1.ProductContainer]]
         });
-        return (0, utils_1.buildStructOverrideReverse)(response);
+        return withSessionFields((0, utils_1.buildStructOverrideReverse)(response));
     }
     /**
      * Updates an existing application in Fonoster.
@@ -182,15 +162,8 @@ class Applications {
      * @param {string} request.ref - The reference of the application to update
      * @param {string} request.name - The name of the application
      * @param {string} request.endpoint - The endpoint where the application is hosted
-     * @param {SpeechToText} request.speechToText - The speech-to-text configuration
-     * @param {string} request.speechToText.productRef - The product reference of the speech-to-text engine (e.g., stt.deepgram)
-     * @param {object} request.speechToText.config - The configuration object for the speech-to-text engine (e.g., { model: "nova-2", languageCode: "en-US" })
-     * @param {TextToSpeech} request.textToSpeech - The text-to-speech configuration
-     * @param {string} request.textToSpeech.productRef - The product reference of the text-to-speech engine (e.g., tts.elevenlabs)
-     * @param {object} request.textToSpeech.config - The configuration object for the text-to-speech engine (e.g., { voice: "lrTWbMInQjSJ9q5ywFKP" })
      * @param {Intelligence} request.intelligence - The intelligence configuration
-     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., llm.groq)
-     * @param {object} request.intelligence.config - The configuration object for the intelligence engine
+     * @param {object} request.intelligence.config - Autopilot agents: the agent (its model is a catalog id such as openai/gpt-4o-mini)
      * @return {Promise<BaseApiObject>} - The response object that contains the reference to the updated application
      * @example
      * const apps = new SDK.Applications(client); // Existing client object
@@ -198,7 +171,7 @@ class Applications {
      * const request = {
      *   ref: "00000000-0000-0000-0000-000000000000",
      *   name: "My application",
-     *   endpoint: "welcome.demo.fonoster.local", // Built-in demo application
+     *   url: "wss://bot.example.com/session"
      * };
      *
      * apps
@@ -215,11 +188,7 @@ class Applications {
             metadata: this.client.getMetadata(),
             request: reqWithStructOverride,
             enumMapping: [["type", applications_pb_1.ApplicationType]],
-            objectMapping: [
-                ["textToSpeech", applications_pb_1.ProductContainer],
-                ["speechToText", applications_pb_1.ProductContainer],
-                ["intelligence", applications_pb_1.ProductContainer]
-            ]
+            objectMapping: REQUEST_OBJECTS
         });
     }
     /**
@@ -250,15 +219,11 @@ class Applications {
             metadata: this.client.getMetadata(),
             request,
             enumMapping: [["type", applications_pb_1.ApplicationType]],
-            objectMapping: [
-                ["speechToText", applications_pb_1.ProductContainer],
-                ["textToSpeech", applications_pb_1.ProductContainer],
-                ["intelligence", applications_pb_1.ProductContainer]
-            ],
+            objectMapping: [["intelligence", applications_pb_1.ProductContainer]],
             repeatableObjectMapping: [["itemsList", applications_pb_1.Application]]
         });
         return {
-            items: response.items.map(utils_1.buildStructOverrideReverse),
+            items: response.items.map((item) => withSessionFields((0, utils_1.buildStructOverrideReverse)(item))),
             nextPageToken: response.nextPageToken
         };
     }
@@ -278,6 +243,24 @@ class Applications {
      *   .then(console.log) // successful response
      *   .catch(console.error); // an error occurred
      */
+    /**
+     * Replaces the app's signing secret. The old secret stops working at once (no overlap window),
+     * so redeploy the app with the new one. The secret is returned only here.
+     *
+     * @param {string} ref - The application's reference
+     * @return {Promise<RotateSigningSecretResponse>} - The new secret and its hint
+     * @example
+     * const { signingSecret } = await applications.rotateSigningSecret("00000000-...");
+     */
+    async rotateSigningSecret(ref) {
+        const applicationsClient = this.client.getApplicationsClient();
+        return await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: applicationsClient.rotateSigningSecret.bind(applicationsClient),
+            requestPBObjectConstructor: applications_pb_1.RotateSigningSecretRequest,
+            metadata: this.client.getMetadata(),
+            request: { ref }
+        });
+    }
     async deleteApplication(ref) {
         const applicationsClient = this.client.getApplicationsClient();
         return await (0, makeRpcRequest_1.makeRpcRequest)({
@@ -291,8 +274,7 @@ class Applications {
      * Evaluates the intelligence of an application.
      *
      * @param {EvaluateIntelligenceRequest} request - The request object that contains the necessary information to evaluate the intelligence of an application
-     * @param {string} request.intelligence.productRef - The product reference of the intelligence engine (e.g., llm.groq)
-     * @param {object} request.intelligence.config - The configuration object for the intelligence engine
+     * @param {object} request.intelligence.config - Autopilot agents: the agent (its model is a catalog id such as openai/gpt-4o-mini)
      * @return {AsyncGenerator<EvaluateIntelligenceEvent>} - Stream of evaluation events (step results, scenario summaries, or errors)
      * @example
      * const apps = new SDK.Applications(client);
@@ -329,7 +311,7 @@ class Applications {
             streamError = err instanceof Error ? err : new Error(String(err));
             done = true;
         });
-        while (!done || queue.length > 0) {
+        while (!done || queue.length > 0 || streamError) {
             if (streamError)
                 throw streamError;
             if (queue.length > 0) {

package/dist/node/CallRecords.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { CallRecordAuditEntry, CallRecordDetail, ListCallRecordsRequest, ListCallRecordsResponse, RetentionPolicy } from "@fonoster/types";
+import { FonosterClient } from "./client/types";
+type FetchLike = (url: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+/** An error answer from the records API (status and its `error` code). */
+declare class CallRecordsError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message?: string);
+}
+/**
+ * @classdesc Call records (vCon) through the HTTP records API (`/api/records`): search, one
+ * record (redacted unless you ask for the original and have the owner or admin role), the
+ * recording, the audit log, erasure and retention.
+ *
+ * @example
+ * const records = new SDK.CallRecords(client);
+ * const { items } = await records.listRecords({ after: "2026-10-01T00:00:00Z" });
+ * const record = await records.getRecord(items[0].callRef);
+ */
+declare class CallRecords {
+    private readonly client;
+    private readonly baseUrl?;
+    private readonly fetchFn;
+    /**
+     * @param {FonosterClient} client - A logged-in client
+     * @param {object} options - `baseUrl` of the HTTP API (default: the client's), `fetch`
+     */
+    constructor(client: FonosterClient, options?: {
+        baseUrl?: string;
+        fetch?: FetchLike;
+    });
+    private url;
+    /** Sends a request, refreshing the access token once on 401. */
+    private send;
+    private json;
+    /** Searches the workspace's records, newest first. */
+    listRecords(request?: ListCallRecordsRequest): Promise<ListCallRecordsResponse>;
+    /** One record; the latest version unless `version` is given. */
+    getRecord(callRef: string, options?: {
+        version?: number;
+        original?: boolean;
+    }): Promise<CallRecordDetail>;
+    /** The recording (WAV) with its content hash. */
+    getRecording(callRef: string, options?: {
+        version?: number;
+        original?: boolean;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+        contentHash: string;
+    }>;
+    /** Deletions and erasures of a record (owner or admin). */
+    getAudit(callRef: string): Promise<CallRecordAuditEntry[]>;
+    /** Erases the call: every object is deleted and a signed tombstone remains (owner or admin). */
+    eraseRecord(callRef: string, reason?: string): Promise<unknown>;
+    /** Deletes one part (recording, transcript, messages) of a record (owner or admin). */
+    deletePart(callRef: string, part: string, reason?: string): Promise<unknown>;
+    getRetention(): Promise<RetentionPolicy[]>;
+    /** Sets how many days a part is kept; `null` removes the policy (owner or admin). */
+    setRetention(part: string, days: number | null): Promise<RetentionPolicy>;
+}
+export { CallRecords, CallRecordsError };

package/dist/node/CallRecords.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallRecordsError = exports.CallRecords = void 0;
+/** An error answer from the records API (status and its `error` code). */
+class CallRecordsError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message ?? `records API: ${status} ${code}`);
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.CallRecordsError = CallRecordsError;
+/**
+ * @classdesc Call records (vCon) through the HTTP records API (`/api/records`): search, one
+ * record (redacted unless you ask for the original and have the owner or admin role), the
+ * recording, the audit log, erasure and retention.
+ *
+ * @example
+ * const records = new SDK.CallRecords(client);
+ * const { items } = await records.listRecords({ after: "2026-10-01T00:00:00Z" });
+ * const record = await records.getRecord(items[0].callRef);
+ */
+class CallRecords {
+    client;
+    baseUrl;
+    fetchFn;
+    /**
+     * @param {FonosterClient} client - A logged-in client
+     * @param {object} options - `baseUrl` of the HTTP API (default: the client's), `fetch`
+     */
+    constructor(client, options = {}) {
+        this.client = client;
+        this.baseUrl = options.baseUrl?.replace(/\/+$/, "");
+        this.fetchFn =
+            options.fetch ?? globalThis.fetch;
+    }
+    url(path, query = {}) {
+        const base = this.baseUrl ?? this.client.getHttpUrl?.() ?? "https://api.fonoster.com";
+        const qs = Object.entries(query)
+            .filter(([, v]) => v !== undefined && v !== null && v !== "")
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join("&");
+        return `${base}/api/records${path}${qs ? `?${qs}` : ""}`;
+    }
+    /** Sends a request, refreshing the access token once on 401. */
+    async send(path, init = {}) {
+        const attempt = () => this.fetchFn(this.url(path, init.query), {
+            method: init.method ?? "GET",
+            headers: {
+                authorization: `Bearer ${this.client.getAccessToken()}`,
+                "x-accesskey-id": this.client.getAccessKeyId(),
+                ...(init.body ? { "content-type": "application/json" } : {})
+            },
+            body: init.body ? JSON.stringify(init.body) : undefined
+        });
+        let res = await attempt();
+        if (res.status === 401) {
+            await this.client.refreshToken();
+            res = await attempt();
+        }
+        if (!res.ok) {
+            const body = (await res.json().catch(() => ({})));
+            throw new CallRecordsError(res.status, body.error ?? "error", body.message);
+        }
+        return res;
+    }
+    async json(path, init) {
+        return (await (await this.send(path, init)).json());
+    }
+    /** Searches the workspace's records, newest first. */
+    async listRecords(request = {}) {
+        return this.json("", { query: request });
+    }
+    /** One record; the latest version unless `version` is given. */
+    async getRecord(callRef, options = {}) {
+        return this.json(`/${encodeURIComponent(callRef)}`, {
+            query: {
+                version: options.version,
+                original: options.original ? "true" : undefined
+            }
+        });
+    }
+    /** The recording (WAV) with its content hash. */
+    async getRecording(callRef, options = {}) {
+        const res = await this.send(`/${encodeURIComponent(callRef)}/recording`, {
+            query: {
+                version: options.version,
+                original: options.original ? "true" : undefined
+            }
+        });
+        return {
+            data: await res.arrayBuffer(),
+            contentType: res.headers.get("content-type") ?? "audio/x-wav",
+            contentHash: res.headers.get("x-content-hash") ?? ""
+        };
+    }
+    /** Deletions and erasures of a record (owner or admin). */
+    async getAudit(callRef) {
+        const { items } = await this.json(`/${encodeURIComponent(callRef)}/audit`);
+        return items;
+    }
+    /** Erases the call: every object is deleted and a signed tombstone remains (owner or admin). */
+    async eraseRecord(callRef, reason) {
+        return this.json(`/${encodeURIComponent(callRef)}`, {
+            method: "DELETE",
+            body: reason ? { reason } : undefined
+        });
+    }
+    /** Deletes one part (recording, transcript, messages) of a record (owner or admin). */
+    async deletePart(callRef, part, reason) {
+        return this.json(`/${encodeURIComponent(callRef)}/parts/${encodeURIComponent(part)}`, { method: "DELETE", body: reason ? { reason } : undefined });
+    }
+    async getRetention() {
+        const { items } = await this.json("/retention");
+        return items;
+    }
+    /** Sets how many days a part is kept; `null` removes the policy (owner or admin). */
+    async setRetention(part, days) {
+        return this.json("/retention", { method: "PUT", body: { part, days } });
+    }
+}
+exports.CallRecords = CallRecords;