@fonoster/common 0.27.0 → 0.31.0

package/dist/protos/authz.proto

@@ -23,24 +23,46 @@ package fonoster.authz.v1beta2;
 import "google/protobuf/struct.proto";
 import "google/protobuf/empty.proto";
 
-import "voice.proto";
-
 // Authentication service definition
 service Authz {
   // Check if a user has permission to perform an action
-  rpc CheckSessionAuthorized (fonoster.voice.v1beta2.CreateSessionRequest) returns (CheckSessionAuthorizedResponse) {}
+  rpc CheckSessionAuthorized (CheckSessionAuthorizedRequest) returns (CheckSessionAuthorizedResponse) {}
   // Check if a given accessKeyId has permission to access a method
   rpc CheckMethodAuthorized (CheckMethodAuthorizedRequest) returns (CheckMethodAuthorizedResponse) {}
   // Add billing meter event to an account
   rpc AddBillingMeterEvent (AddBillingMeterEventRequest) returns (google.protobuf.Empty) {}
 }
 
-// Response message for the CheckVoiceRequestAuthorized method
+// The call a session would serve. Field numbers match the retired
+// fonoster.voice.v1beta2.CreateSessionRequest, so existing authorization servers keep decoding it.
+message CheckSessionAuthorizedRequest {
+  string access_key_id = 1;
+  string app_ref = 2;
+  string endpoint = 3;
+  string ingress_number = 4;
+  string caller_name = 5;
+  string caller_number = 6;
+  string media_session_ref = 7;
+  string session_token = 8;
+  enum CallDirection {
+    FROM_PSTN = 0;
+    TO_PSTN = 1;
+    INTRA_NETWORK = 2;
+  }
+  CallDirection call_direction = 9;
+  map<string, string> metadata = 10;
+  string call_ref = 11;
+}
+
+// Response message for the CheckSessionAuthorized method
 message CheckSessionAuthorizedResponse {
   // The authorization server will look for one or more parameters in the request
   // 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

@@ -0,0 +1,102 @@
+/*
+ * 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.capabilities.v1beta2;
+
+import "google/protobuf/empty.proto";
+
+// What this deployment supports, from fonoster.yaml. Public (no credentials
+// needed) so sign-in screens can render from it; it never returns secrets.
+service Capabilities {
+  // Gets the deployment's capabilities
+  rpc GetCapabilities (google.protobuf.Empty) returns (GetCapabilitiesResponse) {}
+}
+
+message GitHubCapability {
+  string client_id = 1;
+  string authorize_url = 2;
+}
+
+message AuthCapabilities {
+  // Enabled sign-in methods: password | email_code | github
+  repeated string methods = 1;
+  // Who may create an account: invite | open
+  string signup = 2;
+  // Set when github is among the methods
+  GitHubCapability github = 3;
+}
+
+message BillingCapabilities {
+  bool enabled = 1;
+}
+
+message CostsCapabilities {
+  // none | usage | prices
+  string display = 1;
+}
+
+// Private regions (customer-run regions enrolled through the region hub).
+// The local public region always exists and is not reported here.
+message RegionsCapabilities {
+  // True when the operator configured the region hub and the region-signing
+  // key (regions.hub and regions.signingKey), so workspaces can enroll
+  // private regions. Never carries hub URLs or keys.
+  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;
+  // udp | tcp | tls | ws | wss
+  string transport = 3;
+}
+
+message PortRange {
+  int32 min = 1;
+  int32 max = 2;
+}
+
+// Where carriers and softphones reach this deployment: the default public
+// region's endpoints (regions.public in fonoster.yaml). Addresses and ports
+// only, never credentials. Empty when the operator listed none.
+message ConnectionCapabilities {
+  repeated SipEndpoint sip = 1;
+  repeated string signaling_addresses = 2;
+  repeated string media_addresses = 3;
+  PortRange rtp_ports = 4;
+}
+
+message GetCapabilitiesResponse {
+  AuthCapabilities auth = 1;
+  BillingCapabilities billing = 2;
+  CostsCapabilities costs = 3;
+  string domain = 4;
+  string app_url = 5;
+  RegionsCapabilities regions = 6;
+  ConnectionCapabilities connection = 7;
+  SipCapabilities sip = 8;
+}

package/dist/protos/identity.proto

@@ -56,6 +56,8 @@ service Identity {
   rpc ExchangeApiKey (ExchangeApiKeyRequest) returns (ExchangeApiKeyResponse) {}
   rpc ExchangeOauth2Code (ExchangeOauth2CodeRequest) returns (ExchangeOauth2CodeResponse) {}
   rpc ExchangeRefreshToken (ExchangeRefreshTokenRequest) returns (ExchangeRefreshTokenResponse) {}
+  // Trade an emailed sign-in code for tokens (passwordless sign-in)
+  rpc ExchangeVerificationCode (ExchangeVerificationCodeRequest) returns (ExchangeVerificationCodeResponse) {}
   rpc RevokeToken (RevokeTokenRequest) returns (RevokeTokenResponse) {}
 
   // Get the public key for verifying JWTs
@@ -78,14 +80,22 @@ message Workspace {
   int32 created_at = 5;
   int32 updated_at = 6;
   Owner owner = 7;
+  // A public region id (default, us-east-1) or a private region ref (rg_...). Immutable.
+  string region = 8;
 }
 
 message CreateWorkspaceRequest {
   string name = 1;
+  // A public region id, or one of the caller's private regions (id or rg_ ref). Empty means "default".
+  string region = 2;
 }
 
 message CreateWorkspaceResponse {
   string ref = 1;
+  string region = 2;
+  // Unused since PR-15 (regions are created at the user level, POST /api/regions); kept reserved.
+  string enrollment_token = 3;
+  string expires_at = 4;
 }
 
 message DeleteWorkspaceRequest {
@@ -113,6 +123,8 @@ message ListWorkspacesResponse {
 message UpdateWorkspaceRequest {
   string ref = 1;
   string name = 2;
+  // Accepted only when unchanged (the region is immutable).
+  string region = 3;
 }
 
 message UpdateWorkspaceResponse {
@@ -204,10 +216,12 @@ message User {
 
 message UpdateUserRequest {
   string ref = 1;
+  // A new password; current_password must be the account's password.
   string password = 2;
   string name = 3;
   string avatar = 4;
   string phone = 5;
+  string current_password = 6;
 }
 
 message UpdateUserResponse {
@@ -356,4 +370,15 @@ message RevokeTokenResponse {
 // Message with response with the public key
 message GetPublicKeyResponse {
   string public_key = 1;
-}
+}
+
+message ExchangeVerificationCodeRequest {
+  string email = 1;
+  string code = 2;
+}
+
+message ExchangeVerificationCodeResponse {
+  string id_token = 1;
+  string access_token = 2;
+  string refresh_token = 3;
+}

package/dist/protos/providers.proto

@@ -0,0 +1,139 @@
+/*
+ * 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.providers.v1beta2;
+
+// The provider catalog (read-only) and the workspace's own vendor keys (add-provider-registry)
+service Providers {
+  // Catalog entries this workspace can use: providers, models and voices (not retired)
+  rpc ListCatalog(ListCatalogRequest) returns (ListCatalogResponse) {}
+  // Store or replace the workspace's key for a provider (kept in a write-only Secret)
+  rpc SetProviderKey(SetProviderKeyRequest) returns (ProviderKey) {}
+  // The workspace's provider keys (never the key itself)
+  rpc ListProviderKeys(ListProviderKeysRequest) returns (ListProviderKeysResponse) {}
+  // Remove the workspace's key for a provider (and its Secret)
+  rpc DeleteProviderKey(DeleteProviderKeyRequest) returns (DeleteProviderKeyResponse) {}
+  // Deprecated or retired items this workspace uses, with where they are used
+  rpc ListWarnings(ListWarningsRequest) returns (ListWarningsResponse) {}
+}
+
+message CatalogItem {
+  // Catalog id, e.g. deepgram/nova-3 or elevenlabs/rachel; a provider's id has no slash
+  string id = 1;
+  // provider, model or voice
+  string kind = 2;
+  // active or deprecated
+  string state = 3;
+  // The provider id (the item's own id for providers)
+  string provider_id = 4;
+  // Models: stt, tts or llm
+  string type = 5;
+  // Providers: capabilities (stt, tts, llm)
+  repeated string capabilities = 6;
+  // Models: languages; voices: their language
+  repeated string languages = 7;
+  // Models: features
+  repeated string features = 8;
+  // Voices: the models they work on
+  repeated string models = 9;
+  // Voices: gender, when known
+  string gender = 10;
+  // 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, llm or nc (models by type; providers by capability)
+  string type = 2;
+}
+
+message ListCatalogResponse {
+  repeated CatalogItem items = 1;
+}
+
+message ProviderKey {
+  string ref = 1;
+  string provider_id = 2;
+  // The Secret holding the key
+  string secret_ref = 3;
+  int32 created_at = 4;
+  int32 updated_at = 5;
+}
+
+message SetProviderKeyRequest {
+  string provider_id = 1;
+  // The vendor key; write-only
+  string key = 2;
+}
+
+message ListProviderKeysRequest {}
+
+message ListProviderKeysResponse {
+  repeated ProviderKey items = 1;
+}
+
+message DeleteProviderKeyRequest {
+  string provider_id = 1;
+}
+
+message DeleteProviderKeyResponse {
+  string provider_id = 1;
+}
+
+message WarningUse {
+  // app or agent
+  string kind = 1;
+  string ref = 2;
+  string name = 3;
+  // The config field naming the item: voice, ttsModel, sttModel or llm
+  string field = 4;
+  // For a TTS model: the voice the config uses with it (e.g. the workspace's cloned voice)
+  string voice = 5;
+}
+
+message Warning {
+  string id = 1;
+  // provider, model or voice
+  string kind = 2;
+  // deprecated or retired
+  string state = 3;
+  string replacement = 4;
+  string retire_on = 5;
+  // Saved configs that reference the item
+  repeated WarningUse used_by = 6;
+  // Apps whose sessions used it in the last days, including ids no saved config names
+  repeated string runtime_apps = 7;
+  int32 runtime_sessions = 8;
+  // ISO 8601; empty without recent runtime use
+  string last_used_at = 9;
+}
+
+message ListWarningsRequest {}
+
+message ListWarningsResponse {
+  repeated Warning items = 1;
+}

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;
+}