@fonoster/sdk 0.27.0 → 0.31.0

package/dist/node/Regions.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegionsError = exports.Regions = void 0;
+/** An error answer from the regions API (status and its `error` code). */
+class RegionsError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message ?? `regions API: ${status} ${code}`);
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.RegionsError = RegionsError;
+/**
+ * @classdesc Regions (add-private-regions, PR-12..PR-21) through the HTTP API (`/api/regions`).
+ * Regions belong to the signed-in user: create a private region (id, display name, SIP domain),
+ * get its one-time enrollment token, watch its status, re-issue the token, disconnect or delete
+ * it. A workspace picks a region when it is created (`workspaces.createWorkspace({name, region})`).
+ *
+ * @example
+ * const regions = new SDK.Regions(client);
+ * const { items } = await regions.listRegions();
+ * const { ref, token } = await regions.createRegion({
+ *   id: "acme-hq", displayName: "Acme HQ", sipDomain: "sip.acme.com"
+ * });
+ * const region = await regions.getRegion("acme-hq");
+ */
+class Regions {
+    client;
+    baseUrl;
+    fetchFn;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.baseUrl = options.baseUrl?.replace(/\/+$/, "");
+        // Called as a method below, so never store the global unbound: in browsers a detached
+        // `fetch` throws "Illegal invocation".
+        this.fetchFn =
+            options.fetch ??
+                ((input, init) => globalThis.fetch(input, init));
+    }
+    headers(auth, body) {
+        const h = {};
+        if (body !== undefined)
+            h["content-type"] = "application/json";
+        if (!auth)
+            return h;
+        const token = this.client.getAccessToken?.();
+        if (token)
+            h.authorization = `Bearer ${token}`;
+        const accessKeyId = this.client.getAccessKeyId?.();
+        if (accessKeyId)
+            h["x-accesskey-id"] = accessKeyId;
+        return h;
+    }
+    async json(path, method = "GET", body, auth = true) {
+        const base = this.baseUrl ?? this.client.getHttpUrl?.() ?? "https://api.fonoster.ai";
+        const attempt = () => this.fetchFn(`${base}/api/regions${path}`, {
+            method,
+            headers: this.headers(auth, body),
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {})
+        });
+        let res = await attempt();
+        if (res.status === 401 && auth) {
+            await this.client.refreshToken();
+            res = await attempt();
+        }
+        const out = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new RegionsError(res.status, String(out.error ?? "error"), out.message);
+        return out;
+    }
+    static path(region) {
+        return `/${encodeURIComponent(region)}`;
+    }
+    /**
+     * The regions a new workspace can pick: the offered public regions and, when signed in, your
+     * private regions (with status).
+     */
+    async listRegions() {
+        let signedIn = false;
+        try {
+            signedIn = !!this.client.getAccessToken?.();
+        }
+        catch {
+            signedIn = false;
+        }
+        return this.json("", "GET", undefined, signedIn);
+    }
+    /**
+     * Creates a private region (PR-15, PR-16, PR-18). The token (`token`, also `enrollmentToken`)
+     * is returned once; run `fonoster-region enroll <token>` on the region machine.
+     */
+    async createRegion(request) {
+        return this.json("", "POST", request);
+    }
+    /**
+     * One region by id or ref; without an argument, the current workspace's region (its status,
+     * secrets and connection details).
+     */
+    async getRegion(region) {
+        return this.json(region ? Regions.path(region) : "/current");
+    }
+    /** Changes a private region's display name (the id never changes). */
+    async updateRegion(region, request) {
+        return this.json(Regions.path(region), "PATCH", request);
+    }
+    /** A new one-time enrollment token; enrolling with it revokes the current cell. */
+    async reissueRegionToken(region) {
+        return this.json(`${Regions.path(await this.refOf(region))}/token`, "POST");
+    }
+    /** Revokes the region's cell now; the region goes back to `waiting`. */
+    async disconnectRegion(region) {
+        await this.json(`${Regions.path(await this.refOf(region))}/disconnect`, "POST");
+    }
+    /** Deletes a private region; refused (`region_in_use`) while any workspace uses it. */
+    async deleteRegion(region) {
+        return this.json(Regions.path(region), "DELETE");
+    }
+    /** The given region, or the current workspace's region. */
+    async refOf(region) {
+        if (region)
+            return region;
+        return (await this.getRegion()).ref;
+    }
+}
+exports.Regions = Regions;

package/dist/node/Usage.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { GetUsageRequest, GetUsageResponse } from "@fonoster/types";
+import { FonosterClient } from "./client/types";
+/**
+ * @classdesc What the workspace consumed: call minutes, speech, language-model tokens, noise
+ * cancelling, answering-machine detections, recordings and storage. Quantities only, never money.
+ * Each total says whose key a vendor was called with (`keySource`: `workspace` or `platform`).
+ *
+ * @example
+ * const usage = new SDK.Usage(client);
+ * const { rows } = await usage.getUsage({
+ *   fromDay: "2026-10-01",
+ *   toDay: "2026-10-31",
+ *   groupBy: ["key_source"]
+ * });
+ */
+declare class Usage {
+    private readonly client;
+    constructor(client: FonosterClient);
+    /**
+     * Usage totals for a range of days (UTC, inclusive), split by meter and by the dimensions in
+     * `groupBy` (day, workspace, provider, model, key_source, origin). With `allOwned`, a workspace
+     * owner gets every workspace they own.
+     */
+    getUsage(request: GetUsageRequest): Promise<GetUsageResponse>;
+}
+export { Usage };

package/dist/node/Usage.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Usage = void 0;
+const makeRpcRequest_1 = require("./client/makeRpcRequest");
+const usage_pb_1 = require("./generated/node/usage_pb");
+/**
+ * @classdesc What the workspace consumed: call minutes, speech, language-model tokens, noise
+ * cancelling, answering-machine detections, recordings and storage. Quantities only, never money.
+ * Each total says whose key a vendor was called with (`keySource`: `workspace` or `platform`).
+ *
+ * @example
+ * const usage = new SDK.Usage(client);
+ * const { rows } = await usage.getUsage({
+ *   fromDay: "2026-10-01",
+ *   toDay: "2026-10-31",
+ *   groupBy: ["key_source"]
+ * });
+ */
+class Usage {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Usage totals for a range of days (UTC, inclusive), split by meter and by the dimensions in
+     * `groupBy` (day, workspace, provider, model, key_source, origin). With `allOwned`, a workspace
+     * owner gets every workspace they own.
+     */
+    async getUsage(request) {
+        const client = this.client.getUsageClient();
+        const raw = await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.getUsage.bind(client),
+            requestPBObjectConstructor: usage_pb_1.GetUsageRequest,
+            metadata: this.client.getMetadata(),
+            request: { groupBy: [], ...request },
+            repeatableObjectMapping: [["rowsList", usage_pb_1.UsageRow]]
+        });
+        return { rows: raw.rows ?? [] };
+    }
+}
+exports.Usage = Usage;

package/dist/node/Users.d.ts

@@ -117,7 +117,8 @@ declare class Users {
      * @param {UpdateUserRequest} request - The request object that contains the necessary information to update a User
      * @param {string} request.ref - The reference of the User to update
      * @param {string} [request.name] - The name of the User
-     * @param {string} [request.password] - The password of the User
+     * @param {string} [request.password] - A new password for the User; requires currentPassword and signs the User out everywhere
+     * @param {string} [request.currentPassword] - The User's current password, required to set a new one
      * @param {string} [request.avatar] - The avatar of the User
      * @param {string} [request.phone] - The phone number of the User (optional)
      * @return {Promise<BaseApiObject>} - The response object that contains the reference to the updated User
@@ -127,7 +128,8 @@ declare class Users {
      * const request = {
      *   ref: "00000000-0000-0000-0000-000000000000",
      *   name: "John Doe",
-     *   password: "password",
+     *   password: "a-new-password",
+     *   currentPassword: "the-current-password",
      *   avatar: "https://example.com/avatar.jpg",
      *   phone: "+1234567890"
      * };

package/dist/node/Users.js

@@ -128,7 +128,8 @@ class Users {
      * @param {UpdateUserRequest} request - The request object that contains the necessary information to update a User
      * @param {string} request.ref - The reference of the User to update
      * @param {string} [request.name] - The name of the User
-     * @param {string} [request.password] - The password of the User
+     * @param {string} [request.password] - A new password for the User; requires currentPassword and signs the User out everywhere
+     * @param {string} [request.currentPassword] - The User's current password, required to set a new one
      * @param {string} [request.avatar] - The avatar of the User
      * @param {string} [request.phone] - The phone number of the User (optional)
      * @return {Promise<BaseApiObject>} - The response object that contains the reference to the updated User
@@ -138,7 +139,8 @@ class Users {
      * const request = {
      *   ref: "00000000-0000-0000-0000-000000000000",
      *   name: "John Doe",
-     *   password: "password",
+     *   password: "a-new-password",
+     *   currentPassword: "the-current-password",
      *   avatar: "https://example.com/avatar.jpg",
      *   phone: "+1234567890"
      * };

package/dist/node/Webhooks.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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 { BaseApiObject, CreateWebhookRequest, CreateWebhookResponse, ListWebhookDeliveriesRequest, ListWebhookDeliveriesResponse, ListWebhooksRequest, ListWebhooksResponse, RotateWebhookSecretResponse, UpdateWebhookRequest, Webhook, WebhookDelivery } from "@fonoster/types";
+import { FonosterClient } from "./client/types";
+/**
+ * @classdesc Fonoster Webhooks, a capability of Fonoster's Workspaces. Webhooks receive call
+ * events (call.started, call.ended, call.failed, call_record.sealed, provider.deprecated),
+ * signed with the endpoint's secret.
+ *
+ * @example
+ * const SDK = require("@fonoster/sdk");
+ *
+ * async function main() {
+ *   const client = new SDK.Client({ accessKeyId: "WO00000000000000000000000000000000" });
+ *   await client.loginWithApiKey("APXXXXXXXXXXXXXXXX", "YYYYYYYYYYYYYYYYY");
+ *   const webhooks = new SDK.Webhooks(client);
+ *   const { ref, secret } = await webhooks.createWebhook({
+ *     url: "https://example.com/fonoster",
+ *     events: ["call.ended"]
+ *   });
+ * }
+ */
+declare class Webhooks {
+    private readonly client;
+    constructor(client: FonosterClient);
+    /** Creates an endpoint. The secret is returned only here and on rotation. */
+    createWebhook(request: CreateWebhookRequest): Promise<CreateWebhookResponse>;
+    getWebhook(ref: string): Promise<Webhook>;
+    listWebhooks(request?: ListWebhooksRequest): Promise<ListWebhooksResponse>;
+    /** Changes the URL and/or events; fields left out are kept. */
+    updateWebhook(request: UpdateWebhookRequest): Promise<BaseApiObject>;
+    deleteWebhook(ref: string): Promise<BaseApiObject>;
+    /** A new secret; the previous one keeps verifying for 24 hours. */
+    rotateWebhookSecret(ref: string): Promise<RotateWebhookSecretResponse>;
+    /** The delivery log, newest first (optionally one endpoint's). */
+    listWebhookDeliveries(request?: ListWebhookDeliveriesRequest): Promise<ListWebhookDeliveriesResponse>;
+    /** Sends a delivery again now, with the same event id and a fresh signature. */
+    resendWebhookDelivery(ref: string): Promise<WebhookDelivery>;
+}
+export { Webhooks };

package/dist/node/Webhooks.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = void 0;
+const makeRpcRequest_1 = require("./client/makeRpcRequest");
+const webhooks_pb_1 = require("./generated/node/webhooks_pb");
+const date = (seconds) => typeof seconds === "number" && seconds > 0
+    ? new Date(seconds * 1000)
+    : undefined;
+function toWebhook(raw) {
+    const { eventsList, previousSecretUntil, ...rest } = raw;
+    return {
+        ...rest,
+        events: (raw.events ?? eventsList ?? []),
+        previousSecretUntil: date(previousSecretUntil)
+    };
+}
+function toDelivery(raw) {
+    return {
+        ...raw,
+        lastAttemptAt: date(raw.lastAttemptAt),
+        nextAttemptAt: date(raw.nextAttemptAt)
+    };
+}
+/**
+ * @classdesc Fonoster Webhooks, a capability of Fonoster's Workspaces. Webhooks receive call
+ * events (call.started, call.ended, call.failed, call_record.sealed, provider.deprecated),
+ * signed with the endpoint's secret.
+ *
+ * @example
+ * const SDK = require("@fonoster/sdk");
+ *
+ * async function main() {
+ *   const client = new SDK.Client({ accessKeyId: "WO00000000000000000000000000000000" });
+ *   await client.loginWithApiKey("APXXXXXXXXXXXXXXXX", "YYYYYYYYYYYYYYYYY");
+ *   const webhooks = new SDK.Webhooks(client);
+ *   const { ref, secret } = await webhooks.createWebhook({
+ *     url: "https://example.com/fonoster",
+ *     events: ["call.ended"]
+ *   });
+ * }
+ */
+class Webhooks {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Creates an endpoint. The secret is returned only here and on rotation. */
+    async createWebhook(request) {
+        const client = this.client.getWebhooksClient();
+        return await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.createWebhook.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.CreateWebhookRequest,
+            metadata: this.client.getMetadata(),
+            request
+        });
+    }
+    async getWebhook(ref) {
+        const client = this.client.getWebhooksClient();
+        const raw = await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.getWebhook.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.GetWebhookRequest,
+            metadata: this.client.getMetadata(),
+            request: { ref }
+        });
+        return toWebhook(raw);
+    }
+    async listWebhooks(request = {}) {
+        const client = this.client.getWebhooksClient();
+        const raw = await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.listWebhooks.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.ListWebhooksRequest,
+            metadata: this.client.getMetadata(),
+            request,
+            repeatableObjectMapping: [["itemsList", webhooks_pb_1.Webhook]]
+        });
+        return {
+            items: (raw.items ?? []).map(toWebhook),
+            nextPageToken: raw.nextPageToken
+        };
+    }
+    /** Changes the URL and/or events; fields left out are kept. */
+    async updateWebhook(request) {
+        const client = this.client.getWebhooksClient();
+        return await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.updateWebhook.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.UpdateWebhookRequest,
+            metadata: this.client.getMetadata(),
+            request
+        });
+    }
+    async deleteWebhook(ref) {
+        const client = this.client.getWebhooksClient();
+        return await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.deleteWebhook.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.DeleteWebhookRequest,
+            metadata: this.client.getMetadata(),
+            request: { ref }
+        });
+    }
+    /** A new secret; the previous one keeps verifying for 24 hours. */
+    async rotateWebhookSecret(ref) {
+        const client = this.client.getWebhooksClient();
+        const raw = await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.rotateWebhookSecret.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.RotateWebhookSecretRequest,
+            metadata: this.client.getMetadata(),
+            request: { ref }
+        });
+        return {
+            ref: raw.ref,
+            secret: raw.secret,
+            previousSecretUntil: date(raw.previousSecretUntil)
+        };
+    }
+    /** The delivery log, newest first (optionally one endpoint's). */
+    async listWebhookDeliveries(request = {}) {
+        const client = this.client.getWebhooksClient();
+        const raw = await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.listWebhookDeliveries.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.ListWebhookDeliveriesRequest,
+            metadata: this.client.getMetadata(),
+            request,
+            repeatableObjectMapping: [["itemsList", webhooks_pb_1.WebhookDelivery]]
+        });
+        return { items: (raw.items ?? []).map(toDelivery) };
+    }
+    /** Sends a delivery again now, with the same event id and a fresh signature. */
+    async resendWebhookDelivery(ref) {
+        const client = this.client.getWebhooksClient();
+        const raw = await (0, makeRpcRequest_1.makeRpcRequest)({
+            method: client.resendWebhookDelivery.bind(client),
+            requestPBObjectConstructor: webhooks_pb_1.ResendWebhookDeliveryRequest,
+            metadata: this.client.getMetadata(),
+            request: { ref }
+        });
+        return toDelivery(raw);
+    }
+}
+exports.Webhooks = Webhooks;

package/dist/node/Workspaces.d.ts

@@ -16,7 +16,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { BaseApiObject, CreateWorkspaceRequest, InviteUserToWorkspaceRequest, ListWorkspaceMembersRequest, ListWorkspaceMembersResponse, ListWorkspacesResponse, RemoveUserFromWorkspaceResponse, ResendWorkspaceMembershipInvitationResponse, UpdateWorkspaceRequest, Workspace } from "@fonoster/types";
+import { BaseApiObject, CreateWorkspaceRequest, CreateWorkspaceResponse, InviteUserToWorkspaceRequest, ListWorkspaceMembersRequest, ListWorkspaceMembersResponse, ListWorkspacesResponse, Region, RegionEnrollmentToken, RemoveUserFromWorkspaceResponse, ResendWorkspaceMembershipInvitationResponse, UpdateWorkspaceRequest, Workspace } from "@fonoster/types";
 import { FonosterClient } from "./client/types";
 /**
  * @classdesc Fonoster Workspaces, part of the Fonoster Identity subsystem,
@@ -66,7 +66,8 @@ declare class Workspaces {
      *
      * @param {CreateWorkspaceRequest} request - The request object that contains the necessary information to create a new Workspace
      * @param {string} request.name - The name of the Workspace
-     * @return {Promise<BaseApiObject>} - The response object that contains the reference to the created Workspace
+     * @param {string} request.region - An offered public region id (default `default`) or one of your private regions (id or ref, see `Regions.createRegion`); fixed for life
+     * @return {Promise<CreateWorkspaceResponse>} - The reference and the stored region
      * @example
      * const workspaces = new SDK.Workspaces(client); // Existing client object
      *
@@ -79,7 +80,25 @@ declare class Workspaces {
      *   .then(console.log) // successful response
      *   .catch(console.error); // an error occurred
      */
-    createWorkspace(request: CreateWorkspaceRequest): Promise<BaseApiObject>;
+    createWorkspace(request: CreateWorkspaceRequest): Promise<CreateWorkspaceResponse>;
+    /**
+     * The current workspace's region (add-private-regions): for a private region, the cell's status,
+     * version, components, active calls and which secrets it needs and has.
+     *
+     * @return {Promise<Region>} - The region view
+     */
+    getRegion(): Promise<Region>;
+    /**
+     * Issues a new one-time enrollment token for the current workspace's region (its owner only).
+     * Enrolling a cell with it revokes the previous cell's credentials.
+     *
+     * @return {Promise<RegionEnrollmentToken>} - The token (shown once) and its expiry
+     */
+    reissueRegionToken(): Promise<RegionEnrollmentToken>;
+    /**
+     * Revokes the current workspace's region cell now; it goes back to `waiting` (region owner).
+     */
+    disconnectRegion(): Promise<void>;
     /**
      * Retrieves an existing Workspace in the system.
      *

package/dist/node/Workspaces.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Workspaces = void 0;
 const makeRpcRequest_1 = require("./client/makeRpcRequest");
 const identity_pb_1 = require("./generated/node/identity_pb");
+const Regions_1 = require("./Regions");
 /**
  * @classdesc Fonoster Workspaces, part of the Fonoster Identity subsystem,
  * allows you to create, update, retrieve, and delete Workspaces in the system.
@@ -53,7 +54,8 @@ class Workspaces {
      *
      * @param {CreateWorkspaceRequest} request - The request object that contains the necessary information to create a new Workspace
      * @param {string} request.name - The name of the Workspace
-     * @return {Promise<BaseApiObject>} - The response object that contains the reference to the created Workspace
+     * @param {string} request.region - An offered public region id (default `default`) or one of your private regions (id or ref, see `Regions.createRegion`); fixed for life
+     * @return {Promise<CreateWorkspaceResponse>} - The reference and the stored region
      * @example
      * const workspaces = new SDK.Workspaces(client); // Existing client object
      *
@@ -68,12 +70,37 @@ class Workspaces {
      */
     async createWorkspace(request) {
         const client = this.client.getIdentityClient();
-        return await (0, makeRpcRequest_1.makeRpcRequest)({
+        const res = await (0, makeRpcRequest_1.makeRpcRequest)({
             method: client.createWorkspace.bind(client),
             requestPBObjectConstructor: identity_pb_1.CreateWorkspaceRequest,
             metadata: this.client.getMetadata(),
             request
         });
+        return { ref: res.ref, region: res.region || undefined };
+    }
+    /**
+     * The current workspace's region (add-private-regions): for a private region, the cell's status,
+     * version, components, active calls and which secrets it needs and has.
+     *
+     * @return {Promise<Region>} - The region view
+     */
+    async getRegion() {
+        return new Regions_1.Regions(this.client).getRegion();
+    }
+    /**
+     * Issues a new one-time enrollment token for the current workspace's region (its owner only).
+     * Enrolling a cell with it revokes the previous cell's credentials.
+     *
+     * @return {Promise<RegionEnrollmentToken>} - The token (shown once) and its expiry
+     */
+    async reissueRegionToken() {
+        return new Regions_1.Regions(this.client).reissueRegionToken();
+    }
+    /**
+     * Revokes the current workspace's region cell now; it goes back to `waiting` (region owner).
+     */
+    async disconnectRegion() {
+        return new Regions_1.Regions(this.client).disconnectRegion();
     }
     /**
      * Retrieves an existing Workspace in the system.