@robono/calling 0.0.0-stage → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# 0.1.3
+
+Authenticated event listening, no idle state polling, foreground reconciliation and silent idle-session expiry. Bounded event reconnects preserve existing call controls and optional UI.
+
+# Changelog
+
+## 0.1.2
+
+- Add an optional availability reason while preserving voiceAvailable and existing call-control behavior.
+
+## 0.1.1
+
+- Stop unanswered ringing locally at the server deadline even if polling stalls.
+- Add ordered, repeatable hold/resume, silenced tracks, a bounded held lease and fresh authorization before resuming.
+- Dismiss locally failed media instead of leaving connected controls visible.
+
+- Back off state polling after rate limits and temporary failures, honoring Retry-After.
+- Preserve HTTP failure status when a proxy returns a non-JSON response.
+- Share concurrent state refreshes so background scheduling and foreground polling cannot apply the same signaling state twice.
+- Keep the calling engine independent of the optional mobile screen package.
+
+## 0.1.0
+
+- One-to-one WebRTC audio with direct connections and relay fallback.
+- Stable start request IDs, cancellation during microphone permission or signaling, bounded transport deadlines and media cleanup.
+- Per-contact availability, answer, mute, hangup, connection state and call history.
+- Browser defaults and injectable media adapters for native hosts.
+- TypeScript declarations and history merge/display helpers.
+
+This headless package connects your app's own interface and native integrations. It does not install mobile screens, push credentials or native notification services. Calling access is configured separately for each network.

package/LICENSE

@@ -0,0 +1,130 @@
+ROBONO SDK LICENSE AGREEMENT
+Version 1.0, July 20, 2026
+
+Copyright (c) 2026 Add to Loop LLC. All rights reserved.
+
+This Robono SDK License Agreement (the "Agreement") is between Add to Loop LLC,
+operating the Robono service ("Robono"), and the person or entity that downloads,
+installs, copies, or uses the Software ("You"). By downloading, installing,
+copying, or using the Software, You accept this Agreement. If You do not accept
+it, do not use the Software.
+
+1. Definitions
+
+"Software" means this Robono software development kit, its documentation, and
+any updates Robono provides under this Agreement.
+
+"Robono Service" means the messaging interoperability, routing, policy,
+conversion, delivery, and related services operated or expressly authorized by
+Robono.
+
+"Application" means a product or service owned or controlled by You that is
+authorized to connect to the Robono Service.
+
+2. Limited License
+
+Subject to this Agreement, Robono grants You a limited, non-exclusive,
+non-transferable, non-sublicensable, revocable license to:
+
+(a) install, copy, and use the Software internally to develop, test, and
+operate an Application that communicates with the Robono Service; and
+
+(b) reproduce and distribute the portions of the Software that are necessarily
+included in Your Application, solely in compiled, minified, bundled, or object
+code form and solely as needed for that Application to communicate with the
+Robono Service.
+
+No right is granted to distribute the Software as a standalone product or SDK.
+
+3. Restrictions
+
+You may not, and may not permit another person to:
+
+(a) sell, rent, lease, sublicense, publish, or redistribute the Software as a
+standalone product, library, SDK, or service;
+
+(b) use the Software or a modified or derivative version of it to develop,
+provide, or support a product or service that competes with the Robono Service;
+
+(c) use the Software to bypass Robono, avoid applicable usage controls or fees,
+or access the Robono Service without authorization;
+
+(d) remove or alter copyright, trademark, attribution, or proprietary notices;
+
+(e) reverse engineer, decompile, or disassemble the Software except to the
+limited extent applicable law expressly prohibits this restriction; or
+
+(f) use the Software in violation of applicable law, the rights of another
+person, or the terms governing access to the Robono Service.
+
+4. Ownership and Reserved Rights
+
+The Software is licensed, not sold. Robono and its licensors retain all right,
+title, and interest in the Software and all related intellectual property.
+Except for the limited rights expressly granted in Section 2, all rights are
+reserved.
+
+No patent license is granted except the minimum license, if any, necessarily
+required to exercise the rights expressly granted in Section 2, and that
+limited patent license applies only while the Software is used with an
+authorized Robono Service.
+
+5. Service Access
+
+This Agreement does not itself grant an account, API credentials, service
+availability, support, or a right to access the Robono Service. Service access
+may be governed by additional terms, plans, limits, and policies. Robono may
+suspend or terminate access to protect users, systems, legal compliance, or the
+integrity of the Robono Service.
+
+6. Updates and Support
+
+Robono is not required to provide maintenance, updates, support, or continued
+availability of any version of the Software unless separately agreed in
+writing.
+
+7. Term and Termination
+
+This Agreement continues until terminated. Your rights terminate automatically
+if You breach this Agreement. On termination, You must stop using the Software
+and delete copies under Your control, except for copies necessarily contained
+in previously distributed Applications. Sections 3, 4, 8, 9, 10, and 11
+survive termination.
+
+8. Disclaimer of Warranties
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS" AND
+"AS AVAILABLE," WITHOUT WARRANTIES OF ANY KIND, EXPRESS, IMPLIED, OR
+STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, ROBONO WILL NOT BE LIABLE FOR INDIRECT,
+INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR LOSS
+OF DATA, REVENUE, PROFITS, GOODWILL, OR BUSINESS OPPORTUNITY, ARISING FROM OR
+RELATING TO THE SOFTWARE. ROBONO'S TOTAL LIABILITY RELATING TO THE SOFTWARE
+WILL NOT EXCEED THE GREATER OF ONE HUNDRED U.S. DOLLARS (US $100) OR THE AMOUNT
+YOU PAID ROBONO FOR THE SOFTWARE DURING THE TWELVE MONTHS BEFORE THE EVENT
+GIVING RISE TO THE CLAIM. THESE LIMITATIONS APPLY TO THE MAXIMUM EXTENT
+PERMITTED BY LAW.
+
+10. Governing Law
+
+This Agreement is governed by the laws of the State of Florida, excluding its
+conflict-of-laws rules. The state and federal courts located in Palm Beach
+County, Florida have exclusive jurisdiction, and each party consents to their
+jurisdiction and venue.
+
+11. General
+
+You may not assign this Agreement without Robono's prior written consent.
+Robono may assign this Agreement in connection with a reorganization, transfer
+of intellectual property, financing, merger, acquisition, or sale of all or
+substantially all of the relevant assets. If a provision is unenforceable, it
+will be enforced to the maximum extent permitted and the remaining provisions
+will remain effective. A waiver must be in writing. This Agreement is the
+entire agreement concerning the Software unless You and Robono sign a separate
+written agreement that expressly replaces it.
+
+Questions about this license may be submitted at https://robono.com/contact.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# Robono Calling SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add one-to-one voice calls within your app or between people connected across Robono Bridge networks. The SDK manages WebRTC negotiation, direct connections, relay fallback, call state and microphone cleanup. Your app keeps its identity and platform notification integration. Use your own interface, or choose the separate optional mobile screen package. The calling engine never requires a Robono interface.
+
+## Install
+
+```sh
+npm install @robono/calling@0.1.2
+```
+
+This is a versioned npm-compatible package. Commit your package lockfile to retain its integrity checksum. The release includes `SHA256SUMS` and the package includes an SPDX software bill of materials.
+
+- [Calling integration guide](https://robono.com/docs#calling)
+- [HTTP API](https://robono.com/api-reference?spec=calling)
+- [Developer calling workspace](https://robono.com/calling)
+
+## Connect your backend
+
+Open Calling in your Robono developer workspace, enable calling for the integration, and copy its admission and service URLs. Your server authenticates the user, then posts the following to that URL using a network API key with `calling:connect` scope:
+
+```json
+{"operation":"admit","kind":"network","protocolVersion":1,"externalUserId":"YOUR_AUTHENTICATED_USER_ID"}
+```
+
+Use the exact external user ID from the accepted Bridge relationship. Validate the returned `serviceUrl` against your configured calling service, then exchange the returned `ticket` within 60 seconds at `serviceUrl + '/sessions'` using `{ticket, connectionId}`. A connection ID is `bridge:CONNECTION_ID` between networks or `app:CONVERSATION_ID` for a Robono Messenger endpoint. Omit `connectionId` to listen across authorized contacts.
+
+Return the service URL, resulting session token and expiry to that user's client over HTTPS. Keep network API keys on your server and tokens out of logs and URLs. Renew expired sessions through your authenticated backend; never silently reopen a microphone.
+
+Both networks must allow voice on the accepted relationship:
+
+```json
+{"calling":{"voice":true,"video":false,"protocol_version":1}}
+```
+
+Keep the existing messaging capabilities and protocol version. Check live availability before enabling a call action.
+
+## Browser integration
+
+Create one client per signed-in device and keep it alive across screen navigation. Here `session` comes from your backend, `audio` is an HTML audio element, and `renderCall` updates your app's UI:
+
+```js
+import { RobonoCallingClient, createHttpTransport } from '@robono/calling';
+
+const client = new RobonoCallingClient({
+  request: createHttpTransport({ baseUrl: session.serviceUrl, token: session.token }),
+  onChange: renderCall,
+  onRemoteStream(stream) {
+    audio.srcObject = stream;
+    if (stream) audio.play().catch(() => showEnableAudioButton());
+  }
+});
+await client.listen();
+const { voiceAvailable } = await client.availability(connectionId);
+
+// Bind these to user actions, with error handling in your UI:
+// await client.call(connectionId);
+// await client.answer();
+// client.mute(true); client.mute(false);
+// await client.hangUp();
+// await client.dispose(); // logout or destruction of this device session
+```
+
+Use HTTPS and request microphone permission from the Call or Answer action. Browsers may require a user gesture to play remote audio. Do not call `answer()` just because a notification arrived. `forceRelay: true` is available for your relay acceptance test; normal calls prefer a direct route.
+
+Use the `onChange` snapshot to render ringing, connecting and connected states. Start the timer at `call.connectedAt`, not when Answer is pressed. A preparation state can precede a server call ID; retain the same screen and allow cancellation. `hangUp()` handles cancellation, decline and ending an active call.
+
+## Optional mobile interface
+
+`@robono/calling-react-native` is a separate package for networks that want supplied React Native screens, sounds, controls and audio adapters. It is not a dependency of this engine. Existing WebRTC clients and networks with their own calling UI can continue using the engine or HTTP API without installing it.
+
+## Native hosts
+
+Supply `getUserMedia`, `createPeerConnection` and, if needed, `createRemoteStream` adapters through the constructor. The microphone adapter receives an optional `{isCurrent}` callback: check it before capture after asynchronous permission or audio-session work. A late returned stream is stopped if the call has already been cancelled.
+
+The headless SDK does not install iOS or Android native code. Your host manages microphone permission, audio sessions/focus, speaker/Bluetooth routing, interruptions, background execution, native incoming UI and push delivery. Select the speaker route before connection if requested and preserve it when media starts. Release native audio resources when the call ends. Use the same protocol on both platforms.
+
+## Incoming notifications
+
+Enable network notifications on your admission endpoint with `{"operation":"notifications","enabled":true}`. Robono sends signed `calling.incoming` and `calling.dismissed` events to your network webhook. Your backend sends push through your app's own provider; Robono does not receive your app's push keys through this SDK.
+
+Use the matching backend release:
+
+```sh
+npm install https://github.com/IMLX16/robono-sdks/releases/download/calling-v0.1.1/robono-server-0.11.0.tgz
+```
+
+Verify the raw webhook body with `verifyRobonoWebhook`, then use `toCallingPushPayload` from `@robono/server`. Route only to devices owned by `recipient.external_user_id` in `recipient.child_app_id`. Durably queue verified events before acknowledging them. Deduplicate by `event_id`; retain the highest per-call sequence for at least 24 hours. A dismissal (sequence 2) overrides an invitation (sequence 1), even if events arrive out of order. Never ring past `ring_expires_at`. Dismissal clears ringing; it does not end an answered call.
+
+When opened, a notification should authenticate the current user and refresh current call state. Notification content is routing information, not authorization. Platform settings control notification presentation and delivery.
+
+## History
+
+```js
+import { mergeCallHistory, describeCall } from '@robono/calling/history';
+const page = await client.history({ after: saved.cursor, limit: 100 });
+const updated = mergeCallHistory(saved, page);
+await saveHistory(updated); // Commit entries and cursor together.
+const label = describeCall(updated.entries.at(-1));
+```
+
+Initialize `saved` as `{cursor: 0, entries: []}`. Continue while `hasMore` is true. Keep separate history cursors per account and query scope. Store entries by call ID and show them on the caller's side of the conversation. `durationMs` excludes ringing and setup. Refresh history on resume and hangup, and recheck availability before callback.
+
+## Failure handling
+
+- 401: stop media and obtain a new session through your backend.
+- 403: refresh account and relationship permissions.
+- 409: refresh call state; another device may control the call or a participant may be busy.
+- 429: back off before retrying.
+- 503/network failure: use bounded retries and show a recoverable error.
+
+The client retries ambiguous Start responses with the same request ID, stops late microphone capture after cancellation, and releases media on signaling loss. Your UI should handle rejected actions and avoid automatic redial.
+
+## Verify your integration
+
+Use two sandbox networks and two devices. Check calls both ways, audible two-way speech, mute, speaker, Bluetooth, decline, caller cancellation, no answer, history, Wi-Fi/cellular and relay fallback. Repeat native foreground, background and locked-screen tests on iPhone and Android. Confirm messaging continues working during rollout.
+
+The package uses ESM and includes TypeScript declarations. Node.js 22+ runs its development tests; browser/native hosts provide WebRTC.
+
+## License and support
+
+Use is governed by the included Robono SDK License Agreement. Contact [Robono support](https://robono.com/contact?topic=sdk).
+
+## Ringing and interruptions
+
+Unanswered calls expire 30 seconds after creation. Stop ringing at `ringRemainingMs` (a duration from the response), or `ringExpiresAt` for older responses. A late Answer is rejected. Do not send End to represent a timeout: that action means user cancellation or decline. The service records `no_answer` independently, and the client also stops a stale ringing screen when polling stalls.
+
+For an established call, `client.hold()` silences local and remote tracks immediately and acknowledges the interruption to the service. A held endpoint can stop polling for up to five minutes; retries do not extend that deadline. The other endpoint keeps its normal signaling lease and may hang up. Show Call on hold when `localHeld` or `remoteHeld` is true. Keep the user's manual mute preference separate from hold.
+
+Call `client.resume(prepareAudio)` only when the OS permits audio to return, or when the person explicitly requests resume. The client first refreshes authorization and call state, then awaits your `prepareAudio` callback, acknowledges resume and restores tracks. The callback must reject if another call still owns audio. A stale response, remote hangup, expired session or ended call cannot restart capture. The optional mobile package supplies this wiring and a Resume call control. No voicemail is involved.
+
+## Event-based listening
+
+Use `@robono/calling@0.1.3` with `@robono/calling-react-native@0.2.2` when using the optional mobile interface. Existing custom interfaces remain supported. See https://robono.com/docs#calling-events for the lifecycle and recovery contract.
+
+- Foreground, idle: an authenticated WebSocket listens for incoming calls. No periodic state polling. A ping/pong every 20 seconds maintains presence.
+- Active calls: events trigger state reconciliation immediately; a state health check runs every 3 seconds. The native background fallback also checks every 3 seconds; overlapping checks are coalesced.
+- Idle in background: call `setForeground(false)`. The event socket and state checks stop. Your backend delivers Robono's signed incoming-call events through your app's APNs/FCM notifications. A WebSocket does not replace push delivery.
+- Return to foreground: call `setForeground(true)`. The socket reconnects and current state is checked. Do not create a new call to recover a listening session. The optional controller forwards this lifecycle method to the engine.
+- Event reconnection: delays start at 1 second, double to 30 seconds (plus up to 20% jitter), honor Retry-After, and stop after eight retries. Foreground re-entry can restart recovery. State recovery stops after six consecutive failed idle checks.
+- Expired idle sessions: `onSessionExpired` requests new admission without presenting a failed-call screen. Dispose the expired client and create a new one with a new session from your backend. Use bounded backoff for admission failures. Authorization revocation is not a retryable session expiration. An active call cannot be transferred to a new session.
+
+`createHttpTransport` supplies the event subscription automatically. If wrapping it, preserve `request.subscribe = transport.subscribe`. A custom request without `subscribe`, or `{events:false}`, retains the compatibility polling interval (`pollMs`, default 1000 ms).
+
+The 0.1.2 engine had polling and retry backoff but did not include this event transport. No native permissions or rebuild are added by this JavaScript patch to an app already using the native calling package.

package/SBOM.spdx.json

@@ -0,0 +1,44 @@
+{
+  "spdxVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "name": "@robono/calling@0.1.3",
+  "documentNamespace": "http://spdx.org/spdxdocs/@robono%2fcalling-0.1.3-***",
+  "creationInfo": {
+    "created": "2026-10-25T10:32:11.266Z",
+    "creators": [
+      "Tool: npm/cli-11.6.2"
+    ]
+  },
+  "documentDescribes": [
+    "SPDXRef-Package-robono.calling-0.1.3"
+  ],
+  "packages": [
+    {
+      "name": "@robono/calling",
+      "SPDXID": "SPDXRef-Package-robono.calling-0.1.3",
+      "versionInfo": "0.1.3",
+      "packageFileName": "",
+      "description": "One-to-one WebRTC voice calling for connected Robono Bridge networks.",
+      "primaryPackagePurpose": "LIBRARY",
+      "downloadLocation": "NOASSERTION",
+      "filesAnalyzed": false,
+      "homepage": "https://robono.com/docs#calling",
+      "licenseDeclared": "SEE LICENSE IN LICENSE",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/%40robono/calling@0.1.3"
+        }
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "spdxElementId": "SPDXRef-DOCUMENT",
+      "relatedSpdxElement": "SPDXRef-Package-robono.calling-0.1.3",
+      "relationshipType": "DESCRIBES"
+    }
+  ]
+}

package/dist/events.js

@@ -0,0 +1,38 @@
+/** Authenticated event hints with bounded reconnects. No idle state polling. */
+export function subscribeCallingEvents({baseUrl,token,WebSocketImpl}, {onEvent,onStatus=()=>{},onError=()=>{}}) {
+  let socket,timer,deadline,stable,stale,closed=false,paused=false,failures=0,retryAfter=0,terminal=false;
+  const url=baseUrl.replace(/^http/, 'ws').replace(/\/$/,'')+'/events';
+  function clear(){clearTimeout(timer);clearTimeout(deadline);clearTimeout(stable);clearTimeout(stale);}
+  function disconnect(){const previous=socket;socket=null;if(previous){previous.onclose=null;previous.onmessage=null;previous.onerror=()=>{};previous.close();}}
+  function retry(){
+    clear();if(closed||paused||terminal)return;
+    if(failures>=8){onStatus('disconnected');return;}
+    const delay=Math.max(retryAfter,Math.min(30000,1000*2**failures++)*(1+Math.random()*.2));retryAfter=0;
+    onStatus('reconnecting');timer=setTimeout(connect,delay);
+  }
+  function touch(){clearTimeout(stale);stale=setTimeout(()=>{disconnect();retry();},50000);}
+  function connect(){
+    if(closed||paused||terminal)return;
+    try{socket=new WebSocketImpl(url);}catch{retry();return;}
+    const ws=socket;onStatus('connecting');
+    deadline=setTimeout(()=>{disconnect();retry();},10000);
+    ws.onopen=()=>{if(ws===socket)ws.send(JSON.stringify({type:'authenticate',token}));};
+    ws.onmessage=event=>{
+      if(ws!==socket)return;
+      let data;try{data=JSON.parse(event.data);}catch{return;}
+      if(data.type==='ready'){clearTimeout(deadline);touch();stable=setTimeout(()=>{failures=0;},60000);onStatus('listening');onEvent();}
+      else if(data.type==='changed')onEvent();
+      else if(data.type==='ping'){touch();ws.send(JSON.stringify({type:'pong'}));}
+      else if(data.type==='error'){
+        retryAfter=Math.max(0,Number(data.retryAfterMs)||0);
+        if(data.status===401||data.status===403){terminal=true;clear();disconnect();onStatus(data.status===403?'access_revoked':'session_expired');onError(Object.assign(Error(data.error),{status:data.status}));}
+      }
+    };
+    ws.onerror=()=>{};ws.onclose=()=>{if(ws!==socket)return;socket=null;retry();};
+  }
+  connect();
+  return {
+    setEnabled(enabled){if(closed||terminal)return;if(enabled&&!paused&&socket)return;paused=!enabled;clear();disconnect();if(enabled){failures=0;connect();}else onStatus('paused');},
+    close(){closed=true;clear();disconnect();},
+  };
+}

package/dist/history.d.ts

@@ -0,0 +1,4 @@
+import type { CallHistoryEntry, CallHistoryPage } from './index.js';
+export interface SavedCallHistory { cursor: number; entries: CallHistoryEntry[] }
+export function mergeCallHistory(saved: SavedCallHistory, page: CallHistoryPage): SavedCallHistory;
+export function describeCall(entry: CallHistoryEntry): { label: string; detail: string; missed: boolean };

package/dist/history.js

@@ -0,0 +1,27 @@
+// Pure helpers shared by clients; only finalized server records enter history.
+export function mergeCallHistory(saved, page) {
+  if (!page || !Array.isArray(page.entries) || !Number.isSafeInteger(page.nextCursor) ||
+      page.nextCursor < saved.cursor || typeof page.hasMore !== 'boolean') throw Error('invalid_call_history');
+  const byId = new Map(saved.entries.map(entry => [entry.id, entry]));
+  let sequence = saved.cursor;
+  for (const entry of page.entries) {
+    if (!entry || typeof entry.id !== 'string' || typeof entry.connectionId !== 'string' ||
+        !['caller', 'callee'].includes(entry.role) || typeof entry.reason !== 'string' ||
+        !Number.isSafeInteger(entry.sequence) || entry.sequence <= sequence || entry.sequence > page.nextCursor ||
+        !Number.isFinite(entry.createdAt) || !Number.isFinite(entry.endedAt) ||
+        !Number.isFinite(entry.durationMs) || entry.durationMs < 0 ||
+        entry.connectedAt !== null && !Number.isFinite(entry.connectedAt)) throw Error('invalid_call_history');
+    sequence = entry.sequence;
+    byId.set(entry.id, entry);
+  }
+  if (page.hasMore && page.nextCursor <= saved.cursor) throw Error('invalid_call_history');
+  return { cursor: page.nextCursor, entries: [...byId.values()].sort((a,b) => a.sequence - b.sequence) };
+}
+export function describeCall(entry) {
+  const incoming = entry.role === 'callee';
+  if (entry.connectedAt != null) return { label: incoming ? 'Incoming voice call' : 'Outgoing voice call',
+    detail: `${Math.floor(entry.durationMs / 60000)}:${String(Math.floor(entry.durationMs / 1000) % 60).padStart(2, '0')}`, missed: false };
+  if (entry.reason === 'declined') return { label: incoming ? 'Declined voice call' : 'Call declined', detail: '', missed: incoming };
+  if (['cancelled', 'no_answer'].includes(entry.reason)) return { label: incoming ? 'Missed voice call' : entry.reason === 'cancelled' ? 'Cancelled voice call' : 'No answer', detail: '', missed: incoming };
+  return { label: 'Call couldn’t connect', detail: '', missed: incoming };
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export interface CallHistoryEntry { id: string; sequence: number; connectionId: string; role: 'caller' | 'callee'; reason: string; createdAt: number; answeredAt: number | null; connectedAt: number | null; endedAt: number; durationMs: number }
+export interface CallHistoryPage { entries: CallHistoryEntry[]; nextCursor: number; hasMore: boolean }
+export type CallState = 'ringing' | 'connecting' | 'connected' | 'ended';
+export interface Call { id: string; version: number; connectionId: string; state: CallState; role: 'caller' | 'callee'; controlled: boolean; reason?: string; remoteDescription: RTCSessionDescriptionInit | null; remoteCandidates: RTCIceCandidateInit[]; createdAt: number; ringExpiresAt?: number; ringRemainingMs?: number; localHeld?: boolean; remoteHeld?: boolean; holdExpiresAt?: number | null; holdRevision?: number; answeredAt?: number; connectedAt?: number; endedAt?: number }
+export interface Snapshot { listeningStatus?: EventStatus; voiceAvailable: boolean; call: Call | null; muted: boolean; localHeld?: boolean; error: string | null; preparing?: boolean; nativePresentation?: { mode?: string; dismissedCallIds?: string[]; speakerEnabled?: boolean; callerNames?: Record<string, string>; appOwnedCallIds?: string[]; appAnsweringCallIds?: string[]; appRingingCallIds: string[]; systemRingingCallIds: string[] } | null }
+export interface EventSubscription { setEnabled(enabled: boolean): void; close(): void }
+export type EventStatus = 'connecting' | 'listening' | 'reconnecting' | 'disconnected' | 'paused' | 'session_expired' | 'access_revoked';
+export interface Request { (operation: string, payload?: Record<string, unknown>): Promise<any>; subscribe?: (callbacks: {onEvent: () => void; onStatus?: (status: EventStatus) => void; onError?: (error: Error & {status?: number}) => void}) => EventSubscription }
+export function createHttpTransport(options: { baseUrl: string; token: string; fetcher?: typeof fetch; events?: boolean; WebSocketImpl?: typeof WebSocket }): Request;
+export class RobonoCallingClient {
+  constructor(options: { request: Request; onSessionExpired?: (error: Error) => void; onChange?: (state: Snapshot) => void; onRemoteStream?: (stream: MediaStream | null) => void; getUserMedia?: (context?: { isCurrent: () => boolean }) => Promise<MediaStream>; createPeerConnection?: (config: RTCConfiguration) => RTCPeerConnection; pollMs?: number; forceRelay?: boolean; createId?: () => string; createRemoteStream?: (track: MediaStreamTrack) => MediaStream });
+  state: Snapshot;
+  readonly closed: boolean;
+  setForeground(value: boolean): void;
+  listen(): Promise<void>;
+  refresh(): Promise<boolean>;
+  call(connectionId?: string): Promise<void>;
+  history(query?: { after?: number; limit?: number; connectionId?: string }): Promise<CallHistoryPage>;
+  availability(connectionId: string): Promise<{ voiceAvailable: boolean; reason?: 'ready' | 'calling_not_enabled' | 'contact_unavailable' }>;
+  answer(): Promise<void>;
+  hangUp(): Promise<void>;
+  hold(): Promise<void>;
+  resume(prepareAudio?: () => Promise<void>): Promise<void>;
+  mute(muted?: boolean): void;
+  dispose(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,403 @@
+import {subscribeCallingEvents} from './events.js';
+/** Audio-only calling client. Media and identity adapters are supplied by the host. */
+export function createHttpTransport({ baseUrl, token, fetcher = fetch, events = true, WebSocketImpl = globalThis.WebSocket }) {
+  const request = async (operation, payload = {}) => {
+    const controller = new AbortController();
+    let timer;
+    const work = (async () => {
+      const response = await fetcher(`${baseUrl}/${operation}`, {
+      method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify(payload), signal: controller.signal, redirect: 'error',
+      });
+      // Headers arriving does not mean the request completed. Keep the deadline
+      // through body consumption so a stalled response cannot freeze controls.
+      let data;
+      try { data = await response.json(); }
+      catch (error) {
+        if (response.ok) throw error;
+        // Proxies may return HTML for 429/503. Preserve status and Retry-After.
+        data = {};
+      }
+      if (!response.ok) {
+        const e = Error(typeof data.error === 'string' ? data.error : data.error?.message || 'request_failed');
+        e.status = response.status;
+        const retryAfter = response.headers?.get('Retry-After');
+        if (retryAfter) {
+          const seconds = /^\d+(?:\.\d+)?$/.test(retryAfter.trim()) ? Number(retryAfter) : null;
+          const delay = seconds == null ? Date.parse(retryAfter) - Date.now() : seconds * 1000;
+          if (Number.isFinite(delay)) e.retryAfterMs = Math.max(0, delay);
+        }
+        throw e;
+      }
+      return data;
+    })();
+    // Native fetch cancellation may abort the socket without settling its promise.
+    // Bound the complete operation ourselves, including response-body decoding.
+    const deadline = new Promise((_, reject) => { timer = setTimeout(() => {
+      controller.abort(); reject(Error('request_timeout'));
+    }, 4500); });
+    try { return await Promise.race([work, deadline]); } finally { clearTimeout(timer); }
+  };
+  if(events && WebSocketImpl) request.subscribe = callbacks => subscribeCallingEvents({baseUrl,token,WebSocketImpl},callbacks);
+  return request;
+}
+
+export class RobonoCallingClient {
+  constructor({ request, onSessionExpired = () => {}, onChange = () => {}, onRemoteStream = () => {},
+    getUserMedia = () => navigator.mediaDevices.getUserMedia({ audio: true, video: false }),
+    createPeerConnection = config => new RTCPeerConnection(config), pollMs = 1000, forceRelay = false, createId = () => crypto.randomUUID(),
+    createRemoteStream = track => new MediaStream([track]) } = {}) {
+    Object.assign(this, { request, onSessionExpired, onChange, onRemoteStream, getUserMedia, createPeerConnection, pollMs, forceRelay, createId, createRemoteStream });
+    this.state = { voiceAvailable: false, call: null, muted: false, error: null };
+    this.pc = null; this.stream = null; this.epoch = 0; this.busy = false; this.closed = false;
+    this.lastSuccess = Date.now(); this.started = false; this.remoteCount = 0;
+    this.pendingRTC = new Set(); this.mediaTimers = new Set();
+    this.locallyEnded = new Set(); this.endRequests = new Map();
+    this.expiredRings = new Set();
+    this.pollFailures = 0; this.pollNotBefore = 0; this.foreground = true;
+    this.localHeld = false; this.holdRevision = 0; this.holdDeadline = 0;
+  }
+  rtc(promise, phase, timeoutMs = 8000) {
+    return new Promise((resolve, reject) => {
+      const finish = (fn, value) => { clearTimeout(timer); this.pendingRTC.delete(cancel); fn(value); };
+      const cancel = () => finish(reject, Error('call_cancelled'));
+      const timer = setTimeout(() => finish(reject, Error(phase + '_timeout')), timeoutMs);
+      this.pendingRTC.add(cancel); promise.then(v => finish(resolve, v), e => finish(reject, e));
+    });
+  }
+  emit() {
+    const call = this.state.call;
+    if(this.events && call && call.state!=='ended' && !this.timer && !this.polling && !this.closed)this.timer=setTimeout(()=>this.poll(),3000);
+    this.scheduleRingDeadline(call);
+    // The local WebRTC transport, not a later server poll, determines when this
+    // device can communicate. Keep the server snapshot separate for sequencing.
+    const connected = this.mediaConnectedAt != null && this.mediaCallId === call?.id &&
+      call.controlled && ['connecting', 'connected'].includes(call.state);
+    this.onChange({ ...this.state, preparing: this.busy, localHeld: this.localHeld,
+      call: connected ? { ...call, state: this.pc?.connectionState === 'disconnected' ? 'connecting' : 'connected', connectedAt: this.mediaConnectedAt } : call });
+  }
+  scheduleRingDeadline(call) {
+    if (call?.state !== 'ringing' || !call.controlled) {
+      clearTimeout(this.ringTimer); this.ringCallId = null; return;
+    }
+    const remaining = Number.isFinite(call.ringRemainingMs) ? call.ringRemainingMs :
+      Number.isFinite(call.ringExpiresAt) ? call.ringExpiresAt - Date.now() : null;
+    if (remaining == null) return;
+    const deadline = Date.now() + Math.max(0, remaining);
+    if (this.ringCallId === call.id && this.ringDeadline <= deadline) return;
+    clearTimeout(this.ringTimer); this.ringCallId = call.id; this.ringDeadline = deadline;
+    this.ringTimer = setTimeout(() => {
+      if (this.state.call?.id !== call.id || this.state.call.state !== 'ringing') return;
+      // A stalled poll must not leave an unanswered phone ringing. The server
+      // independently finalizes No answer; never send End (which means Decline).
+      this.locallyEnded.add(call.id); this.expiredRings.add(call.id);
+      while (this.expiredRings.size > 256) this.expiredRings.delete(this.expiredRings.values().next().value);
+      while (this.locallyEnded.size > 256) this.locallyEnded.delete(this.locallyEnded.values().next().value);
+      this.resetMedia();
+      this.state.call = {...this.state.call, state: 'ended', reason: 'no_answer', endedAt: Date.now()};
+      this.emit();
+    }, Math.min(2147483647, Math.max(0, remaining)));
+  }
+  async listen() {
+    if (this.started) return; this.started = true;
+    this.watchdog = setInterval(() => {
+      // Match the service's ten-second endpoint lease. Six seconds left almost
+      // no recovery time after a 4.5-second request timeout plus the poll delay.
+      // Explicit authorization failures still stop media immediately in refresh.
+      const heldLease = this.localHeld && this.holdDeadline > Date.now();
+      const unconfirmedHold = this.pendingHold && Date.now() - this.pendingHold.at > 10000;
+      if (!this.busy && this.mediaCallId && (this.pc || this.stream) && (unconfirmedHold || !heldLease && Date.now() - this.lastSuccess > 10000)) {
+        const id = this.state.call?.id; this.finishLocal('connection_lost');
+        if (id) this.request('end', { callId: id }).catch(() => {});
+      }
+    }, 500);
+    if(this.request.subscribe) this.events=this.request.subscribe({
+      onEvent:()=>this.wake(), onStatus:status=>{this.state.listeningStatus=status;this.emit();},
+      onError:e=>this.sessionError(e),
+    });
+    await this.poll();
+  }
+  sessionError(e) {
+    const active=this.state.call && this.state.call.state!=='ended';
+    this.state.error=active?e.message:null;this.state.listeningStatus=e.status===403?'access_revoked':'session_expired';
+    this.resetMedia();this.closed=true;clearTimeout(this.timer);clearInterval(this.watchdog);this.events?.close();this.emit();
+    if(e.status===401)this.onSessionExpired(e);
+  }
+  wake(){if(this.closed)return;clearTimeout(this.timer);if(this.polling||this.busy){this.eventPending=true;return;}void this.poll();}
+  setForeground(value){this.foreground=value;this.events?.setEnabled(value||!!this.state.call&&this.state.call.state!=='ended');if(value)this.wake();else if(!this.state.call||this.state.call.state==='ended')clearTimeout(this.timer);}
+
+  // Refresh without scheduling a second poll loop (also used for native wake races).
+  // False means the cached snapshot is not authoritative for this attempt.
+  async refresh() {
+    if (this.refreshing) return this.refreshing;
+    const work = this.refreshState();
+    this.refreshing = work;
+    try { return await work; } finally { if (this.refreshing === work) this.refreshing = null; }
+  }
+  async refreshState() {
+    if (this.closed || Date.now() < this.pollNotBefore) return false;
+    const epoch = this.epoch;
+    try {
+      const state = await this.request('state');
+      if (this.closed) return false;
+      this.lastSuccess = Date.now();
+      this.pollFailures = 0; this.pollNotBefore = 0;
+      if (epoch === this.epoch) {
+        this.state.error = null;
+        if (!this.busy && !(state.version < (this.state.call?.version ?? -1))) {
+          this.state.voiceAvailable = state.voiceAvailable;
+          await this.apply(state.call);
+          if (this.pendingHold) await this.confirmHold(this.pendingHold);
+          return true;
+        }
+      }
+    } catch (e) {
+      if (this.closed) return false;
+      const delay = Math.min(30000, Math.max(1000, this.pollMs) * 2 ** Math.min(this.pollFailures++, 5));
+      this.pollNotBefore = Date.now() + Math.max(delay, Number.isFinite(e.retryAfterMs) ? e.retryAfterMs : 0);
+      // Credential revocations remain authoritative even after a local action.
+      if (epoch === this.epoch || e.status === 401 || e.status === 403) {
+        if(e.status===401||e.status===403){this.sessionError(e);return false;}
+        this.state.error = this.state.call && this.state.call.state!=='ended' ? e.message : null;
+        this.emit();
+      }
+    }
+    return false;
+  }
+  async poll() {
+    if(this.closed||this.polling)return;
+    this.polling=true;this.timer=null;
+    try{await this.refresh();
+    }finally{this.polling=false;}
+    if(this.closed)return;
+    const active=this.state.call&&this.state.call.state!=='ended';
+    if(!this.foreground&&!active){this.events?.setEnabled(false);return;}
+    const eventPending=this.eventPending;this.eventPending=false;
+    const retry=this.pollFailures>0&&this.pollFailures<6;
+    const delay=Math.max(eventPending?0:this.events?3000:this.pollMs,this.pollNotBefore-Date.now());
+    if(active||!this.events||retry||eventPending)this.timer=setTimeout(()=>this.poll(),Math.min(2147483647,delay));
+  }
+  async apply(call) {
+    // A pending/late server poll cannot reopen a call the person already ended.
+    if (call && call.state !== 'ended' && this.locallyEnded.has(call.id)) {
+      // Reconcile a lost End response on subsequent polls, without reopening UI.
+      if (!this.expiredRings.has(call.id)) await this.endRemote(call.id).catch(() => {});
+      return;
+    }
+    if (call && this.state.call && call.version < this.state.call.version) return;
+    if (!call) { if (this.pc) this.resetMedia(); this.state.call = null; this.emit(); return; }
+    const wasHeld = this.state.call?.remoteHeld;
+    this.state.call = call;
+    if (call.state === 'ended' || !call.controlled) this.resetMedia();
+    else if (this.pc && this.mediaCallId === call.id) {
+      const pc = this.pc;
+      if (call.remoteDescription && !pc.remoteDescription) await this.rtc(pc.setRemoteDescription(call.remoteDescription), 'remote_description');
+      if (pc !== this.pc) return;
+      if (pc.remoteDescription) {
+        for (const candidate of call.remoteCandidates.slice(this.remoteCount)) {
+          await this.rtc(pc.addIceCandidate(candidate), 'remote_candidate'); if (pc !== this.pc) return; this.remoteCount++;
+        }
+      }
+    }
+    if (wasHeld && !call.remoteHeld && !this.localHeld) this.checkResumedTransport();
+    this.syncAudioTracks();
+    this.emit();
+  }
+  syncAudioTracks() {
+    const held = this.localHeld || this.state.call?.localHeld || this.state.call?.remoteHeld;
+    this.stream?.getAudioTracks().forEach(t => { t.enabled = !held && !this.state.muted; });
+    this.remoteStream?.getAudioTracks().forEach(t => { t.enabled = !held; });
+  }
+  /** Silence immediately; only a server-acknowledged hold relaxes the lease. */
+  async hold() {
+    const call = this.state.call;
+    if (!call?.controlled || call.state !== 'connected' || !this.pc) throw Error('call_not_connected');
+    this.localHeld = true; this.syncAudioTracks(); this.emit();
+    const revision = this.holdRevision = Math.max(this.holdRevision, call.holdRevision || 0) + 1;
+    const intent = this.pendingHold = {callId: call.id, held: true, revision, at: Date.now()};
+    await this.confirmHold(intent);
+  }
+  async confirmHold(intent) {
+    const {callId, revision} = intent;
+    const result = await this.retry('hold', {callId, held: true, revision});
+    if (this.mediaCallId !== callId || !this.localHeld || revision !== this.holdRevision) return;
+    if (this.pendingHold === intent) this.pendingHold = null;
+    this.holdDeadline = result.holdExpiresAt || 0;
+    await this.apply(result);
+  }
+  /** Revalidate before activating audio; a late response cannot restart a call. */
+  async resume(prepareAudio = async () => {}) {
+    const id = this.mediaCallId, revision = this.holdRevision;
+    if (!id || !this.localHeld) return;
+    if (!await this.refresh()) throw Error('call_state_unavailable');
+    if (this.mediaCallId !== id || !this.localHeld || revision !== this.holdRevision) return;
+    await prepareAudio();
+    if (this.mediaCallId !== id || !this.localHeld || revision !== this.holdRevision) return;
+    const nextRevision = ++this.holdRevision;
+    this.pendingHold = null;
+    const result = await this.retry('hold', {callId: id, held: false, revision: nextRevision});
+    if (this.mediaCallId !== id || nextRevision !== this.holdRevision) return;
+    this.localHeld = false; this.holdDeadline = 0; this.lastSuccess = Date.now();
+    await this.apply(result);
+    // A transport that failed while iOS suspended the app cannot be presented
+    // as a resumed conversation. End it cleanly rather than expose dead audio.
+    this.checkResumedTransport();
+  }
+  checkResumedTransport() {
+    const pc = this.pc;
+    if (!pc) return;
+    if (['failed', 'closed'].includes(pc.connectionState)) { this.mediaError(Error('media_disconnected')); return; }
+    if (pc.connectionState === 'disconnected') {
+      const timer = setTimeout(() => {
+        this.mediaTimers.delete(timer);
+        if (this.pc === pc && pc.connectionState === 'disconnected' && !this.localHeld && !this.state.call?.remoteHeld) this.mediaError(Error('media_disconnected'));
+      }, 10000);
+      this.mediaTimers.add(timer);
+    }
+  }
+  resetMedia() {
+    this.epoch++;
+    for (const timer of this.mediaTimers) clearTimeout(timer); this.mediaTimers.clear();
+    for (const cancel of this.pendingRTC) cancel();
+    const pc = this.pc; this.pc = null;
+    if (pc) { pc.onicecandidate = pc.onconnectionstatechange = pc.ontrack = null; pc.close(); }
+    this.stream?.getTracks().forEach(t => t.stop()); this.stream = null;
+    this.remoteStream = null; this.localHeld = false; this.holdDeadline = 0; this.holdRevision = 0; this.pendingHold = null;
+    this.candidates = []; this.remoteCount = 0; this.mediaCallId = null; this.mediaConnectedAt = null; this.state.muted = false;
+    this.onRemoteStream(null);
+  }
+  async prepare(connectionId) {
+    this.resetMedia(); const epoch = this.epoch;
+    const ice = await this.request('ice', connectionId ? { connectionId } : {});
+    if (this.closed || epoch !== this.epoch) throw Error('call_cancelled');
+    if (this.forceRelay && !ice.relayAvailable) throw Error('relay_not_configured');
+    const stream = await this.rtc(this.getUserMedia({ isCurrent: () => !this.closed && epoch === this.epoch }).then(stream => {
+      if (this.closed || epoch !== this.epoch) stream.getTracks().forEach(t => t.stop());
+      return stream;
+    }), 'microphone', 30000);
+    if (this.closed || epoch !== this.epoch) { stream.getTracks().forEach(t => t.stop()); throw Error('call_cancelled'); }
+    if (!stream.getAudioTracks().length || stream.getVideoTracks().length) { stream.getTracks().forEach(t => t.stop()); throw Error('audio_only'); }
+    this.stream = stream;
+    const pc = this.pc = this.createPeerConnection({ iceServers: ice.iceServers, iceTransportPolicy: this.forceRelay ? 'relay' : 'all' });
+    this.candidates = []; this.sendTail = Promise.resolve();
+    for (const track of stream.getAudioTracks()) pc.addTrack(track, stream);
+    pc.ontrack = e => { if (this.pc === pc) { this.remoteStream = e.streams[0] || this.createRemoteStream(e.track); this.syncAudioTracks(); this.onRemoteStream(this.remoteStream); } };
+    pc.onicecandidate = e => {
+      if (!e.candidate || this.pc !== pc) return;
+      this.candidates.push(e.candidate.toJSON()); this.flushCandidates();
+    };
+    pc.onconnectionstatechange = () => {
+      if (this.pc !== pc || !this.mediaCallId) return;
+      if (pc.connectionState === 'connected') { this.reportMediaConnection(pc); this.emit(); }
+      if (pc.connectionState === 'failed' && !this.localHeld && !this.state.call?.remoteHeld) this.mediaError(Error('media_failed'));
+      if (pc.connectionState === 'disconnected') {
+        const timer = setTimeout(() => {
+          this.mediaTimers.delete(timer);
+          if (this.pc === pc && pc.connectionState === 'disconnected' && !this.localHeld && !this.state.call?.remoteHeld) this.mediaError(Error('media_disconnected'));
+        }, 10000);
+        this.mediaTimers.add(timer);
+      }
+    };
+    return pc;
+  }
+  reportMediaConnection(pc) {
+    if (pc !== this.pc || pc.connectionState !== 'connected' || !this.mediaCallId || this.mediaConnectedAt != null) return;
+    const callId = this.mediaCallId;
+    this.mediaConnectedAt = Date.now();
+    this.emit();
+    // Acknowledge promptly; never let an old request alter a later call.
+    void this.retry('connected', { callId }).then(call => {
+      if (this.pc === pc && this.mediaCallId === callId && call?.id === callId) return this.apply(call);
+    }).catch(e => { if (this.pc === pc && this.mediaCallId === callId) this.mediaError(e); });
+  }
+  flushCandidates() {
+    if (!this.mediaCallId || !this.pc) return;
+    const callId = this.mediaCallId, pc = this.pc, candidates = this.candidates.splice(0);
+    for (const candidate of candidates) this.sendTail = this.sendTail.then(async () => {
+      if (this.pc === pc) await this.retry('candidate', { callId, candidate });
+    }).catch(e => { if (this.pc === pc) this.mediaError(e); });
+  }
+  mediaError(e) {
+    const callId = this.mediaCallId; this.finishLocal(e.message);
+    if (callId) this.request('failed', { callId }).catch(() => {});
+  }
+  finishLocal(error) {
+    const call = this.state.call;
+    this.resetMedia(); this.state.error = error;
+    if (call && call.state !== 'ended' && call.controlled) {
+      this.locallyEnded.add(call.id);
+      while (this.locallyEnded.size > 256) this.locallyEnded.delete(this.locallyEnded.values().next().value);
+      this.state.call = {...call, state: 'ended', reason: 'media_failed', endedAt: Date.now()};
+    }
+    this.emit();
+  }
+  async action(fn) {
+    if (this.busy || this.closed) throw Error('client_not_ready');
+    this.busy = true; this.state.error = null; this.emit();
+    try { return await fn(); }
+    catch (e) { this.mediaError(e); throw e; }
+    finally { this.busy = false; this.emit(); if(this.eventPending){this.eventPending=false;this.wake();} }
+  }
+  async history(query = {}) { return this.request('history', query); }
+  async availability(connectionId) { return this.request('availability', { connectionId }); }
+  async retry(operation, payload) {
+    try { return await this.request(operation, payload); }
+    catch (e) { if (e.status && e.status < 500) throw e; return this.request(operation, payload); }
+  }
+  async call(connectionId) {
+    if (this.state.call && this.state.call.state !== 'ended') throw Error('busy');
+    return this.action(async () => {
+      const pc = await this.prepare(connectionId); const epoch = this.epoch;
+      await this.rtc(pc.setLocalDescription(await this.rtc(pc.createOffer(), 'create_offer')), 'local_description');
+      if (this.epoch !== epoch || this.closed) throw Error('call_cancelled');
+      const payload = { ...(connectionId ? { connectionId } : {}), requestId: this.createId(), description: { type: 'offer', sdp: pc.localDescription.sdp } };
+      // Retrying this exact request is safe: the service deduplicates requestId.
+      const call = await this.retry('start', payload); this.lastSuccess = Date.now();
+      if (this.epoch !== epoch) { await this.retry('end', { callId: call.id }); return; }
+      this.state.call = call; this.mediaCallId = call.id; this.flushCandidates(); this.reportMediaConnection(pc); this.emit();
+    });
+  }
+  async answer() {
+    const call = this.state.call;
+    if (!call || call.role !== 'callee' || call.state !== 'ringing' || !call.controlled) throw Error('no_incoming_call');
+    return this.action(async () => {
+      const pc = await this.prepare(call.connectionId), epoch = this.epoch;
+      await this.rtc(pc.setRemoteDescription(call.remoteDescription), 'remote_description');
+      await this.rtc(pc.setLocalDescription(await this.rtc(pc.createAnswer(), 'create_answer')), 'local_description');
+      if (this.epoch !== epoch || this.closed) throw Error('call_cancelled');
+      const result = await this.retry('answer', { callId: call.id, description: { type: 'answer', sdp: pc.localDescription.sdp } }); this.lastSuccess = Date.now();
+      if (this.epoch !== epoch) { await this.retry('end', { callId: call.id }); return; }
+      this.state.call = result; this.mediaCallId = call.id; this.flushCandidates(); this.reportMediaConnection(pc); await this.apply(result);
+    });
+  }
+  async endRemote(callId) {
+    if (this.endRequests.has(callId)) return this.endRequests.get(callId);
+    const pending = this.retry('end', { callId }); this.endRequests.set(callId, pending);
+    try { return await pending; } finally { if (this.endRequests.get(callId) === pending) this.endRequests.delete(callId); }
+  }
+  async hangUp() {
+    const call = this.state.call; this.resetMedia();
+    if (call && call.state !== 'ended' && call.controlled) {
+      this.locallyEnded.add(call.id);
+      while (this.locallyEnded.size > 256) this.locallyEnded.delete(this.locallyEnded.values().next().value);
+      // Stop the local screen/audio immediately; server acknowledgement can be
+      // slow. The remote end remains retried using this same immutable call ID.
+      this.state.call = { ...call, state: 'ended', endedAt: Date.now(), reason: 'hangup' };
+      this.emit();
+      try {
+        const ended = await this.endRemote(call.id);
+        if (this.state.call?.id === call.id) this.state.call = ended;
+      } catch (e) { if (this.state.call?.id === call.id) this.state.error = e.message; }
+    }
+    this.emit();
+  }
+  mute(muted = true) { this.state.muted = muted; this.syncAudioTracks(); this.emit(); }
+  async dispose() {
+    this.events?.close();
+    this.closed = true; clearTimeout(this.timer); clearInterval(this.watchdog);
+    clearTimeout(this.ringTimer);
+    await this.hangUp();
+    // Older sandbox hosts may not have close; media is already released.
+    await this.request('close').catch(() => {});
+  }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
+  "bugs": {
+    "url": "https://robono.com/contact?topic=sdk",
+    "email": "support@robono.com"
+  },
+  "support": "https://robono.com/contact?topic=sdk",
+  "author": {
+    "name": "Add to Loop LLC",
+    "email": "support@robono.com",
+    "url": "https://robono.com"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "name": "@robono/calling",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "One-to-one WebRTC voice calling for connected Robono Bridge networks.",
+  "homepage": "https://robono.com/docs#calling",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IMLX16/robono-sdks.git",
+    "directory": "packages/calling"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./history": {
+      "types": "./dist/history.d.ts",
+      "import": "./dist/history.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SBOM.spdx.json"
+  ],
+  "engines": {
+    "node": ">=22"
+  }
+}