@robono/calling 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# 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,129 @@
-# 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.

package/SBOM.spdx.json

@@ -0,0 +1,44 @@
+{
+  "spdxVersion": "SPDX-2.3",
+  "dataLicense": "CC0-1.0",
+  "SPDXID": "SPDXRef-DOCUMENT",
+  "name": "@robono/calling@0.1.2",
+  "documentNamespace": "http://spdx.org/spdxdocs/@robono%2fcalling-0.1.2-***",
+  "creationInfo": {
+    "created": "2026-10-25T10:32:11.266Z",
+    "creators": [
+      "Tool: npm/cli-11.6.2"
+    ]
+  },
+  "documentDescribes": [
+    "SPDXRef-Package-robono.calling-0.1.2"
+  ],
+  "packages": [
+    {
+      "name": "@robono/calling",
+      "SPDXID": "SPDXRef-Package-robono.calling-0.1.2",
+      "versionInfo": "0.1.2",
+      "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.2"
+        }
+      ]
+    }
+  ],
+  "relationships": [
+    {
+      "spdxElementId": "SPDXRef-DOCUMENT",
+      "relatedSpdxElement": "SPDXRef-Package-robono.calling-0.1.2",
+      "relationshipType": "DESCRIBES"
+    }
+  ]
+}

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,23 @@
+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 { 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 type Request = (operation: string, payload?: Record<string, unknown>) => Promise<any>;
+export function createHttpTransport(options: { baseUrl: string; token: string; fetcher?: typeof fetch }): Request;
+export class RobonoCallingClient {
+  constructor(options: { request: Request; 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;
+  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,370 @@
+/** Audio-only calling client. Media and identity adapters are supplied by the host. */
+export function createHttpTransport({ baseUrl, token, fetcher = fetch }) {
+  return async (operation, payload = {}) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 4500);
+    try {
+      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;
+    } finally { clearTimeout(timer); }
+  };
+}
+
+export class RobonoCallingClient {
+  constructor({ request, 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, 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.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;
+    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.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);
+    await this.poll();
+  }
+  // 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) {
+        this.state.error = e.message;
+        if (e.status === 401 || e.status === 403) { this.resetMedia(); this.closed = true; clearInterval(this.watchdog); }
+        this.emit();
+      }
+    }
+    return false;
+  }
+  async poll() {
+    await this.refresh();
+    if (!this.closed) this.timer = setTimeout(() => this.poll(), Math.min(2147483647, Math.max(this.pollMs, this.pollNotBefore - Date.now())));
+  }
+  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(); }
+  }
+  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);
+      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 } });
+      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.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,57 @@
 {
+  "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.2",
+  "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"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "npm run build && node --test test/client.test.mjs test/package.test.mjs",
+    "test:integration": "node --test test/*.test.mjs",
+    "prepack": "npm run build && node ../../scripts/generate-package-sbom.mjs",
+    "prepublishOnly": "npm test"
+  }
+}