@fonoster/common 0.30.0 → 0.31.0

package/dist/filters/index.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioFilterConfigError = exports.audioFilterConfigSchema = exports.FILTER_NAMES = exports.FILTER_BY_PROVIDER = exports.FILTER_SCHEMAS = exports.aiCousticsPublicOptionsSchema = exports.AI_COUSTICS_FILTER = void 0;
+exports.providerOfFilter = providerOfFilter;
+exports.parseFilters = parseFilters;
+/**
+ * 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.
+ */
+const zod_1 = require("zod");
+/**
+ * The audio filters an app may configure (voice-session, "An app's audio filters are set through
+ * the Applications API"). Apps are untrusted input, so each filter exposes a public option schema
+ * here, shared by the apiserver (validation on write) and the appbridge (the filter factory).
+ * Anything that touches the media server's filesystem, environment or credentials stays out.
+ */
+exports.AI_COUSTICS_FILTER = "aiCoustics";
+/** The ai-coustics filter's public options. */
+exports.aiCousticsPublicOptionsSchema = zod_1.z
+    .object({
+    // The vendor's model id; restricted to its shape so it cannot name a path
+    model: zod_1.z
+        .string()
+        .regex(/^[a-z0-9]+(-[a-z0-9.]+)*$/, { message: "Invalid model name" })
+        .default("quail-vf-2.2-s-16khz"),
+    // Higher values suppress more, competing speech included
+    enhancementLevel: zod_1.z.number().min(0).max(1).default(1),
+    // Keeps the delay but stops enhancing (for A/B tests)
+    bypass: zod_1.z.boolean().default(false)
+})
+    // Reject anything else outright, so a server-only option (or a key) is refused, not ignored
+    .strict();
+/** Public option schemas by filter name. */
+exports.FILTER_SCHEMAS = {
+    [exports.AI_COUSTICS_FILTER]: exports.aiCousticsPublicOptionsSchema
+};
+/** The filter a noise-cancelling (`nc`) provider runs, by provider id. */
+exports.FILTER_BY_PROVIDER = {
+    aicoustics: exports.AI_COUSTICS_FILTER
+};
+exports.FILTER_NAMES = Object.keys(exports.FILTER_SCHEMAS);
+/** The `nc` provider whose credential a filter runs with, or undefined for a filter without one. */
+function providerOfFilter(name) {
+    var _a;
+    return (_a = Object.entries(exports.FILTER_BY_PROVIDER).find(([, f]) => f === name)) === null || _a === void 0 ? void 0 : _a[0];
+}
+exports.audioFilterConfigSchema = zod_1.z
+    .object({
+    name: zod_1.z.string().min(1),
+    options: zod_1.z.record(zod_1.z.unknown()).optional()
+})
+    .strict();
+class AudioFilterConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AudioFilterConfigError";
+    }
+}
+exports.AudioFilterConfigError = AudioFilterConfigError;
+/**
+ * Validates an app's `filters` list: known names and public options only. Returns the list with
+ * each filter's options as given (defaults are applied by the filter itself). Throws
+ * AudioFilterConfigError naming the first offending filter or option.
+ */
+function parseFilters(input) {
+    const list = zod_1.z.array(exports.audioFilterConfigSchema).safeParse(input);
+    if (!list.success) {
+        throw new AudioFilterConfigError(`filters must be a list of { name, options? }: ${issues(list.error)}`);
+    }
+    return list.data.map((f) => {
+        var _a;
+        const schema = exports.FILTER_SCHEMAS[f.name];
+        if (!schema) {
+            throw new AudioFilterConfigError(`unknown audio filter "${f.name}" (known: ${exports.FILTER_NAMES.join(", ")})`);
+        }
+        const parsed = schema.safeParse((_a = f.options) !== null && _a !== void 0 ? _a : {});
+        if (!parsed.success) {
+            throw new AudioFilterConfigError(`invalid options for audio filter "${f.name}": ${issues(parsed.error)}`);
+        }
+        return f.options ? { name: f.name, options: f.options } : { name: f.name };
+    });
+}
+function issues(error) {
+    return error.issues
+        .map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message)
+        .join("; ");
+}

package/dist/identity/roles.js

@@ -77,6 +77,7 @@ const workspaceResourceAccess = [
     "/fonoster.secrets.v1beta2.Secrets/GetSecret",
     "/fonoster.secrets.v1beta2.Secrets/DeleteSecret",
     "/fonoster.secrets.v1beta2.Secrets/ListSecrets",
+    "/fonoster.usage.v1beta2.Usage/GetUsage",
     "/fonoster.calls.v1beta2.Calls/CreateCall",
     "/fonoster.calls.v1beta2.Calls/ListCalls",
     "/fonoster.calls.v1beta2.Calls/GetCall",
@@ -99,6 +100,14 @@ const workspaceResourceOwnerOrAdminAccess = [
     "/fonoster.identity.v1beta2.Identity/RegenerateApiKey"
 ];
 exports.workspaceResourceOwnerOrAdminAccess = workspaceResourceOwnerOrAdminAccess;
+// Billing belongs to the owner (add-billing-service): only owners see or change it.
+const workspaceOwnerAccess = [
+    "/fonoster.billing.v1beta2.Billing/GetBilling",
+    "/fonoster.billing.v1beta2.Billing/UpdateAutoRecharge",
+    "/fonoster.billing.v1beta2.Billing/CreateTopUp",
+    "/fonoster.billing.v1beta2.Billing/Subscribe",
+    "/fonoster.billing.v1beta2.Billing/CreatePortalSession"
+];
 const fullIdentityAccess = [
     "/fonoster.identity.v1beta2.Identity/GetUser",
     "/fonoster.identity.v1beta2.Identity/UpdateUser",
@@ -122,7 +131,8 @@ const roles = [
         access: [
             ...fullIdentityAccess,
             ...workspaceResourceAccess,
-            ...workspaceResourceOwnerOrAdminAccess
+            ...workspaceResourceOwnerOrAdminAccess,
+            ...workspaceOwnerAccess
         ]
     },
     {

package/dist/index.d.ts

@@ -16,7 +16,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export * from "./assistants";
+export * from "./agents";
 export * from "./config";
 export * from "./GrpcError";
 export * from "./constants";
@@ -36,9 +36,12 @@ export * from "./identity";
 export { getRootDomain, setRootDomain } from "./envs";
 export * from "./session";
 export * as Registry from "./registry";
+export * as AudioFilters from "./filters";
 export * as Webhooks from "./webhooks";
+export * as Usage from "./usage";
 export * as CellSecrets from "./cellsecrets";
 export * from "./telemetry";
 export * from "./net";
 export * as Sessions from "./sessions";
 export * as RegionHub from "./regions/hub";
+export * as Roomr from "./roomr";

package/dist/index.js

@@ -36,7 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RegionHub = exports.Sessions = exports.CellSecrets = exports.Webhooks = exports.Registry = exports.setRootDomain = exports.getRootDomain = exports.Validators = exports.Messages = void 0;
+exports.Roomr = exports.RegionHub = exports.Sessions = exports.CellSecrets = exports.Usage = exports.Webhooks = exports.AudioFilters = exports.Registry = exports.setRootDomain = exports.getRootDomain = exports.Validators = exports.Messages = void 0;
 /**
  * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
  * http://github.com/fonoster/fonoster
@@ -55,7 +55,7 @@ exports.RegionHub = exports.Sessions = exports.CellSecrets = exports.Webhooks =
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-__exportStar(require("./assistants"), exports);
+__exportStar(require("./agents"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./GrpcError"), exports);
 __exportStar(require("./constants"), exports);
@@ -77,9 +77,12 @@ Object.defineProperty(exports, "getRootDomain", { enumerable: true, get: functio
 Object.defineProperty(exports, "setRootDomain", { enumerable: true, get: function () { return envs_1.setRootDomain; } });
 __exportStar(require("./session"), exports);
 exports.Registry = __importStar(require("./registry"));
+exports.AudioFilters = __importStar(require("./filters"));
 exports.Webhooks = __importStar(require("./webhooks"));
+exports.Usage = __importStar(require("./usage"));
 exports.CellSecrets = __importStar(require("./cellsecrets"));
 __exportStar(require("./telemetry"), exports);
 __exportStar(require("./net"), exports);
 exports.Sessions = __importStar(require("./sessions"));
 exports.RegionHub = __importStar(require("./regions/hub"));
+exports.Roomr = __importStar(require("./roomr"));

package/dist/protos/applications.proto

@@ -53,7 +53,7 @@ message SpeechDefaults {
   string stt_model = 3;
   // Text-to-speech model (empty: the voice's default)
   string tts_model = 4;
-  // Silence timeout in milliseconds (0: the gateway default)
+  // Silence timeout in milliseconds (0: AppBridge default)
   int32 silence_timeout_ms = 5;
   // The Pacing policy's patience: low, normal or high (empty: normal)
   string patience = 6;
@@ -114,6 +114,14 @@ message ProductContainer {
   google.protobuf.Struct credentials = 3;
 }
 
+// An audio filter run on the caller's audio before speech recognition
+message AudioFilter {
+  // Filter name (aiCoustics)
+  string name = 1;
+  // The filter's public options (model, enhancement_level, bypass)
+  google.protobuf.Struct options = 2;
+}
+
 // Application definition
 message Application {
   // Reference to the application
@@ -134,7 +142,7 @@ message Application {
   int32 created_at = 8;
   // Update time
   int32 updated_at = 9;
-  // The WebSocket URL the gateway dials
+  // The WebSocket URL AppBridge dials
   string url = 10;
   // Stream protocol: fonoster or twilio
   string protocol = 11;
@@ -154,6 +162,8 @@ message Application {
   string recording = 18;
   // Answering-machine detection (off when unset)
   AmdSettings amd = 19;
+  // Audio filters in order (empty: none)
+  repeated AudioFilter filters = 20;
 }
 
 // Request to create a new application
@@ -188,6 +198,8 @@ message CreateApplicationRequest {
   string recording = 14;
   // Answering-machine detection (off when unset)
   AmdSettings amd = 15;
+  // Audio filters in order (empty: none)
+  repeated AudioFilter filters = 20;
 }
 
 // Response for create application
@@ -256,6 +268,8 @@ message UpdateApplicationRequest {
   string recording = 15;
   // Answering-machine detection (off when unset)
   AmdSettings amd = 16;
+  // Audio filters in order (the update replaces the app: left out clears them)
+  repeated AudioFilter filters = 20;
 }
 
 // Response for update application

package/dist/protos/authz.proto

@@ -60,6 +60,9 @@ message CheckSessionAuthorizedResponse {
   // to determine if the request is authorized. If the request is authorized, the
   // response will have the value true.
   bool authorized = 1;
+  // Why the session was refused, when it was: insufficient_balance, concurrency_limit or
+  // trial_ended (add-billing-service D7). Empty when authorized.
+  string reason = 2;
 }
 
 // Request message for the CheckMethodAuthorized method

package/dist/protos/billing.proto

@@ -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.
+ */
+syntax = "proto3";
+
+package fonoster.billing.v1beta2;
+
+// Billing for Fonoster Cloud (add-billing-service): the owner's credits, plan, auto-recharge,
+// top-ups and the Stripe Customer Portal. The billing service serves it with owner_ref set; the
+// apiserver serves it to the dashboard for workspace owners and sets owner_ref from the caller.
+service Billing {
+  // The balance by source, the plan and auto-recharge
+  rpc GetBilling (GetBillingRequest) returns (BillingSummary) {}
+  // Turns auto-recharge on or off, with its threshold and amount in credits
+  rpc UpdateAutoRecharge (UpdateAutoRechargeRequest) returns (BillingSummary) {}
+  // Buys top-up credits; they are added once the payment succeeds
+  rpc CreateTopUp (CreateTopUpRequest) returns (BillingSummary) {}
+  // Moves the owner to Pay-as-you-go (needs a payment method, added in the portal)
+  rpc Subscribe (SubscribeRequest) returns (BillingSummary) {}
+  // A Stripe Customer Portal link for payment methods and invoices
+  rpc CreatePortalSession (CreatePortalSessionRequest) returns (CreatePortalSessionResponse) {}
+}
+
+message GetBillingRequest {
+  string owner_ref = 1;
+}
+
+// Credits of one source: plan, top-up or trial
+message CreditSource {
+  string kind = 1;
+  double credits = 2;
+  // ISO 8601; empty when it does not expire
+  string expires_at = 3;
+}
+
+message BillingSummary {
+  // trial or payg
+  string plan = 1;
+  // active, past_due, closed, or ended (a Trial past its 30 days; calls are refused until the
+  // owner subscribes)
+  string status = 2;
+  // Credits; negative while in the overdraft
+  double balance = 3;
+  // How far below zero the balance may go, in credits
+  double overdraft = 4;
+  repeated CreditSource sources = 5;
+  // ISO 8601; empty on the trial
+  string period_end = 6;
+  bool auto_recharge = 7;
+  double recharge_threshold = 8;
+  double recharge_amount = 9;
+}
+
+message UpdateAutoRechargeRequest {
+  string owner_ref = 1;
+  bool enabled = 2;
+  double threshold = 3;
+  double amount = 4;
+}
+
+message CreateTopUpRequest {
+  string owner_ref = 1;
+  int32 credits = 2;
+}
+
+message SubscribeRequest {
+  string owner_ref = 1;
+}
+
+message CreatePortalSessionRequest {
+  string owner_ref = 1;
+  string return_url = 2;
+}
+
+message CreatePortalSessionResponse {
+  string url = 1;
+}

package/dist/protos/calls.proto

@@ -104,6 +104,8 @@ message CallDetailRecord {
   int32 amd_latency_ms = 14;
   // Detector-specific cause code (e.g. Asterisk's AMDCAUSE), useful for tuning
   string amd_cause = 15;
+  // The reference of the app that handled the call, empty when no app did
+  string app_ref = 16;
 }
 
 // The request message for Calls.Call
@@ -144,6 +146,8 @@ message ListCallsRequest {
   int32 page_size = 7;
   // The page token
   string page_token = 8;
+  // Optional app reference; lists only the calls that app handled
+  string app_ref = 9;
 }
 
 // The response message for Calls.ListCalls

package/dist/protos/capabilities.proto

@@ -61,6 +61,13 @@ message RegionsCapabilities {
   bool private = 1;
 }
 
+// How SIP names (trunk inbound URIs, domains) are checked (features.sip.names).
+message SipCapabilities {
+  // "domain": one DNS label under sip.<domain> (the default). "any": any host
+  // or IP, for installs whose carriers and phones reach them by address.
+  string names = 1;
+}
+
 message SipEndpoint {
   string host = 1;
   int32 port = 2;
@@ -91,4 +98,5 @@ message GetCapabilitiesResponse {
   string app_url = 5;
   RegionsCapabilities regions = 6;
   ConnectionCapabilities connection = 7;
+  SipCapabilities sip = 8;
 }

package/dist/protos/providers.proto

@@ -58,12 +58,16 @@ message CatalogItem {
   // Deprecated items: the suggested replacement and the retirement date (YYYY-MM-DD)
   string replacement = 11;
   string retire_on = 12;
+  // Providers: the adapter needs no key (fake, local models); no vendor key to ask for
+  bool keyless = 13;
+  // A display name ("Aura 2 Thalia"); empty when the entry has none
+  string label = 14;
 }
 
 message ListCatalogRequest {
   // Optional: provider, model or voice
   string kind = 1;
-  // Optional: stt, tts or llm (models and providers)
+  // Optional: stt, tts, llm or nc (models by type; providers by capability)
   string type = 2;
 }
 
@@ -101,7 +105,7 @@ message DeleteProviderKeyResponse {
 }
 
 message WarningUse {
-  // app or assistant
+  // app or agent
   string kind = 1;
   string ref = 2;
   string name = 3;

package/dist/protos/roomr.proto

@@ -0,0 +1,146 @@
+// Roomr: the Roomr node's control service for its controller.
+// Spec: openspec/changes/redesign-roomr/specs/media-control ("Roomr is a gRPC service with
+// three nouns"). Roomr is the SIP and media edge, not an app server: no play, record or DTMF RPCs
+// (an app does those on its call's control stream; recording is a listener). Messages only grow: add fields, never renumber or reuse them, and receivers
+// ignore fields they do not know.
+//
+// Regenerate the Go code with go/roomr/api/generate.sh.
+syntax = "proto3";
+
+package roomr.v1;
+
+option go_package = "github.com/fonoster/roomr/api/roomr/v1;roomrv1";
+
+service Roomr {
+  // Dial out. The room is created, or room_ref is joined (created when it does not exist yet).
+  rpc CreateCall(CreateCallRequest) returns (Call);
+  // End any call, inbound or outbound (CANCEL while ringing, BYE once answered).
+  rpc EndCall(EndCallRequest) returns (Empty);
+  // Rooms that do not start from a call.
+  rpc CreateRoom(CreateRoomRequest) returns (Room);
+  // End every call and participant in the room.
+  rpc EndRoom(EndRoomRequest) returns (Empty);
+  // Add an RTP participant, a listen-only participant or (not yet) a WebRTC participant.
+  rpc AddParticipant(AddParticipantRequest) returns (Participant);
+  // Remove a participant (cause "removed").
+  rpc RemoveParticipant(RemoveParticipantRequest) returns (Empty);
+}
+
+message Empty {}
+
+// Digest credentials for the INVITE's 401/407 challenge.
+message SipAuth {
+  string username = 1;
+  string password = 2;
+}
+
+// Where and how to dial.
+message SipTarget {
+  // Request-URI, for example "sip:+15551234567@carrier".
+  string uri = 1;
+  // Where the INVITE is sent ("sip:proxy:5060", "sip:proxy:5061;transport=tls" or "proxy:5060");
+  // empty sends it to the Request-URI's host.
+  string proxy = 2;
+  // Added to the INVITE untouched. Core SIP headers (Via, From, To, Call-ID, CSeq, Contact, ...)
+  // cannot be set here.
+  map<string, string> headers = 3;
+  SipAuth auth = 4;
+}
+
+message CreateCallRequest {
+  // Chosen by the caller; repeating it returns the existing Call and sends no second INVITE.
+  string call_ref = 1;
+  SipTarget to = 2;
+  // The From user ("+15550001") or a full URI ("sip:+15550001@example.com").
+  string from = 3;
+  // Join this room, or create it with this ref; empty creates a new room.
+  string room_ref = 4;
+  // Session endpoint for the call's control stream (not implemented yet: UNIMPLEMENTED).
+  string session = 5;
+  // How long the callee may ring (default 60 s).
+  uint32 ring_timeout_s = 6;
+  // Passed through untouched in the events the node publishes for this call (opaque to the
+  // node; callers use it for their own references, e.g. app_ref).
+  map<string, string> metadata = 7;
+  // Lowers the node's maximum call duration for this call's room; higher values are ignored.
+  uint32 max_duration_s = 8;
+}
+
+message Call {
+  string call_ref = 1;
+  string room_ref = 2;
+  enum State {
+    RINGING = 0;
+    ANSWERED = 1;
+    ENDED = 2;
+  }
+  State state = 3;
+  // The call's participant in its room, once answered (inbound calls: always).
+  string participant_ref = 4;
+}
+
+message EndCallRequest {
+  string call_ref = 1;
+}
+
+message CreateRoomRequest {
+  // Empty: the node picks one. A ref already in use fails with ALREADY_EXISTS.
+  string room_ref = 1;
+  uint32 max_duration_s = 2;
+  // Overrides the node's emptyRoomTimeout for this room; 0 keeps the node's setting.
+  uint32 empty_room_timeout_s = 3;
+  // Overrides the node's maxParticipants for this room; 0 keeps the node's setting.
+  uint32 max_participants = 4;
+}
+
+message Room {
+  string room_ref = 1;
+}
+
+message EndRoomRequest {
+  string room_ref = 1;
+}
+
+// An RTP address. codec is an rtpmap name such as "L16/16000" or "PCMU/8000".
+message MediaEndpoint {
+  string ip = 1;
+  uint32 port = 2;
+  string codec = 3;
+  // SDES key (AES_CM_128_HMAC_SHA1_80, 30 bytes of base64); empty for plain RTP.
+  string srtp_key = 4;
+}
+
+message WebRtcOffer {
+  string sdp = 1;
+}
+
+// One track forwarded, unmixed, to its own RTP destination.
+message ListenTrack {
+  uint32 track_id = 1;
+  MediaEndpoint rtp = 2;
+}
+
+message AddParticipantRequest {
+  string room_ref = 1;
+  oneof endpoint {
+    MediaEndpoint rtp = 2;
+    WebRtcOffer webrtc = 3;
+  }
+  // Listen-only participant: one RTP destination per selected track. Set without an endpoint.
+  repeated ListenTrack listen = 4;
+}
+
+message Participant {
+  string participant_ref = 1;
+  string room_ref = 2;
+  // RTP participants: where the participant sends its audio (the node's side of the leg).
+  MediaEndpoint rtp = 3;
+  // WebRTC participants: the SDP answer.
+  string sdp_answer = 4;
+  uint32 track_id = 5;
+}
+
+message RemoveParticipantRequest {
+  string room_ref = 1;
+  string participant_ref = 2;
+}