@robono/calling 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## 0.5.0 — release candidate
 
+## 0.6.0
+
+Adds consent-based managed recording and captions using the current authorized call tracks, immediate withdrawal, retry-safe requests and bounded recording startup/finalization.
+
 Add on-demand numeric connection diagnostics for direct and group calls without audio recording or raw network identifiers.
 
 ## 0.4.0 — 2026-11-04

package/README.md

@@ -180,3 +180,12 @@ The 0.1.2 engine had polling and retry backoff but did not include this event tr
 ## Connection details
 
 Direct and group clients expose `getDiagnostics()` for local connection measurements without addresses, media or credentials. The supplied call overlays include an optional Connection details panel; custom interfaces can use the same measurements. [Guide, fields and customization](https://robono.com/guides/call-diagnostics.html). Missing measurements remain unknown, and the first sample cannot calculate interval rates.
+
+
+## Recording, captions and local call tools
+
+Robono hosts optional call recording and transcription. Enable recording once in the existing Calling settings; every participant must agree before capture, and anyone can stop it. The supplied controls include the consent notice, active-recording status and captions. No customer recording server is required.
+
+The supplied adapters also offer camera/microphone/speaker checks and camera background blur. Screen sharing is separate. Phone blur requires rebuilding the native app; browser blur downloads its model only when selected and needs the documented content-security policy. Background processing stays on the device.
+
+See the [recording and call tools guide](https://robono.com/guides/call-recording.html) for prices, retention, short-lived downloads, deletion, platform requirements and label customization. Captions arrive in short batches with several seconds of delay and can be inaccurate; incomplete transcripts are marked.

package/SBOM.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@robono/calling@0.5.0",
-  "documentNamespace": "https://robono.com/sbom/calling/0.5.0/538ac95caa705ca94a9cea02897f2d1441d7d77e",
+  "name": "@robono/calling@0.6.0",
+  "documentNamespace": "https://robono.com/sbom/calling/0.6.0/c5987c1f423c9f088b93fbd9727b38beca106163",
   "creationInfo": {
-    "created": "2026-11-05T10:33:05.150Z",
+    "created": "2026-11-05T15:40:42.440Z",
     "creators": [
       "Organization: Robono (support@robono.com)"
     ]
@@ -14,11 +14,11 @@
     {
       "name": "@robono/calling",
       "SPDXID": "SPDXRef-Package",
-      "versionInfo": "0.5.0",
+      "versionInfo": "0.6.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": true,
       "packageVerificationCode": {
-        "packageVerificationCodeValue": "538ac95caa705ca94a9cea02897f2d1441d7d77e"
+        "packageVerificationCodeValue": "c5987c1f423c9f088b93fbd9727b38beca106163"
       },
       "licenseConcluded": "LicenseRef-RobonoSDK",
       "licenseDeclared": "LicenseRef-RobonoSDK",
@@ -36,11 +36,11 @@
       "checksums": [
         {
           "algorithm": "SHA256",
-          "checksumValue": "cc846301b9f9c1137f5ab4804ca72246f1e2762cb58cd3e50cf8cad87fa04322"
+          "checksumValue": "604c25bc9a6af29a7616e7d0a9a6146187ea34637029393a464c9c305b58acdb"
         },
         {
           "algorithm": "SHA1",
-          "checksumValue": "a95ae3a0a653ad842b0d11c0f42fae1704e56012"
+          "checksumValue": "d31e5c9fdd55f8af1d09c74220b95e9c40fd336d"
         }
       ],
       "licenseConcluded": "LicenseRef-RobonoSDK",
@@ -74,11 +74,11 @@
       "checksums": [
         {
           "algorithm": "SHA256",
-          "checksumValue": "a7f7fc393294454b889657b3f4213060512e1c16706a8db658b4953470c5b0f4"
+          "checksumValue": "9ce33cd3476398ba270658642687ef92c9acaf163819314435786efbca0777c7"
         },
         {
           "algorithm": "SHA1",
-          "checksumValue": "20b37f37d14cd2fc2d0f82aa938da68675a21c77"
+          "checksumValue": "1d0174393e6647e3f61e682ce4ff2eeb6cafa59d"
         }
       ],
       "licenseConcluded": "LicenseRef-RobonoSDK",
@@ -131,11 +131,11 @@
       "checksums": [
         {
           "algorithm": "SHA256",
-          "checksumValue": "3bdda72976a7714d76e5f856b4cbdff3823af06f624cc78de31e10fc19c8803e"
+          "checksumValue": "fe6bdfb3689635902da736e75684828b24db440cb1353eecd9e3a80fccdf60dc"
         },
         {
           "algorithm": "SHA1",
-          "checksumValue": "213076aa45a39797239b2808d986db45ec5c92c2"
+          "checksumValue": "f8bb212e7128842941a483cda4af81b56e4d9ed1"
         }
       ],
       "licenseConcluded": "LicenseRef-RobonoSDK",
@@ -150,11 +150,11 @@
       "checksums": [
         {
           "algorithm": "SHA256",
-          "checksumValue": "671d204c07477f2827b7bcd2a90ac7cc8ec56884c7d4f872a8dd62264a484393"
+          "checksumValue": "cc1bb25f4b12048b6d0254d108323cd0f759ba0bb9124d0f67699e384ff0f4a8"
         },
         {
           "algorithm": "SHA1",
-          "checksumValue": "9bbd521150d53e9060f75c02445e869ba0cd4985"
+          "checksumValue": "2abc7d893f4ed5304b019e4367370abff879ebd0"
         }
       ],
       "licenseConcluded": "LicenseRef-RobonoSDK",
@@ -207,11 +207,11 @@
       "checksums": [
         {
           "algorithm": "SHA256",
-          "checksumValue": "ba60c30ff9e5d84f563ab61b8157f303f34796dd767ce9909478d25aa151da1c"
+          "checksumValue": "60e4d3414d1a05555f709d1241a5d0a70604d4258898b031186f6050736bf103"
         },
         {
           "algorithm": "SHA1",
-          "checksumValue": "4b0341465a58e9a7ceff6c3e4b55132bc9ebbfe4"
+          "checksumValue": "87c966dd65e747b929a2f779678a0663b097a0b2"
         }
       ],
       "licenseConcluded": "LicenseRef-RobonoSDK",
@@ -226,11 +226,11 @@
       "checksums": [
         {
           "algorithm": "SHA256",
-          "checksumValue": "b1e1c9c9796a2228e95e1c645293be7afa40b3fb574d343461b717097d924bb0"
+          "checksumValue": "43fc3a380533b224941f2c3087905380ed5ad4078493dde16d504d11abc499cb"
         },
         {
           "algorithm": "SHA1",
-          "checksumValue": "44de0281a1c5c504a936ce9b1f384fd43fd45a5c"
+          "checksumValue": "51a42dd09073ff8d8522b29c67648f5bc94e56bb"
         }
       ],
       "licenseConcluded": "LicenseRef-RobonoSDK",
@@ -297,8 +297,46 @@
       "copyrightText": "Copyright (c) 2026 Add to Loop LLC."
     },
     {
-      "fileName": "./dist/sharing.js",
+      "fileName": "./dist/recording.d.ts",
       "SPDXID": "SPDXRef-File-14",
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "46ab2cbe35950e38b5218888a21a5abaa84f309adf31909c00899f7d7fbbc9c6"
+        },
+        {
+          "algorithm": "SHA1",
+          "checksumValue": "5febb29ab24d04d7574ac58088aa59b25a7474d0"
+        }
+      ],
+      "licenseConcluded": "LicenseRef-RobonoSDK",
+      "licenseInfoInFiles": [
+        "LicenseRef-RobonoSDK"
+      ],
+      "copyrightText": "Copyright (c) 2026 Add to Loop LLC."
+    },
+    {
+      "fileName": "./dist/recording.js",
+      "SPDXID": "SPDXRef-File-15",
+      "checksums": [
+        {
+          "algorithm": "SHA256",
+          "checksumValue": "878359d91e071cfddd15f26a46fd79efdb0c7a580ef8d7127266807b9d6f6123"
+        },
+        {
+          "algorithm": "SHA1",
+          "checksumValue": "dd6b38924bf9d7f3fae259f72cc0bb83207c15ab"
+        }
+      ],
+      "licenseConcluded": "LicenseRef-RobonoSDK",
+      "licenseInfoInFiles": [
+        "LicenseRef-RobonoSDK"
+      ],
+      "copyrightText": "Copyright (c) 2026 Add to Loop LLC."
+    },
+    {
+      "fileName": "./dist/sharing.js",
+      "SPDXID": "SPDXRef-File-16",
       "checksums": [
         {
           "algorithm": "SHA256",
@@ -317,7 +355,7 @@
     },
     {
       "fileName": "./dist/telemetry.js",
-      "SPDXID": "SPDXRef-File-15",
+      "SPDXID": "SPDXRef-File-17",
       "checksums": [
         {
           "algorithm": "SHA256",
@@ -336,15 +374,15 @@
     },
     {
       "fileName": "./package.json",
-      "SPDXID": "SPDXRef-File-16",
+      "SPDXID": "SPDXRef-File-18",
       "checksums": [
         {
           "algorithm": "SHA256",
-          "checksumValue": "a2d6530e9896ab1edb81d42afae746a902f3f9f8fb249adee9a5e78dc2fd67bb"
+          "checksumValue": "7fa0e72cfac51ab3a164ad821bf6dd9b157353b58856687f6fc124c0a3a11e08"
         },
         {
           "algorithm": "SHA1",
-          "checksumValue": "538d1e05ed1ab40adddf1c541de855c5c4cb8493"
+          "checksumValue": "d47d93563ec9e50154c9e4f372e13be27867e2c3"
         }
       ],
       "licenseConcluded": "LicenseRef-RobonoSDK",
@@ -444,6 +482,16 @@
       "spdxElementId": "SPDXRef-Package",
       "relationshipType": "CONTAINS",
       "relatedSpdxElement": "SPDXRef-File-16"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package",
+      "relationshipType": "CONTAINS",
+      "relatedSpdxElement": "SPDXRef-File-17"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package",
+      "relationshipType": "CONTAINS",
+      "relatedSpdxElement": "SPDXRef-File-18"
     }
   ],
   "hasExtractedLicensingInfos": [

package/dist/groups.d.ts

@@ -1,7 +1,9 @@
+import type {CallRecordingController,CallRecordingState} from './recording.js';
 import type {CallDiagnostics,Request,EventStatus} from './index.js';
-export interface GroupCall {screenSharingAvailable?:boolean;sharing?:boolean[];id:string;connectionId:string;group:true;kind:'voice'|'video';version:number;state:'ringing'|'connecting'|'connected'|'ended';reason?:string;createdAt:number;connectedAt:number|null;endedAt:number|null;ringRemainingMs:number;holdExpiresAt:number|null;self:number;controlled:boolean;memberState:'invited'|'joined'|'left'|'declined';localHeld:boolean;members:Array<{id:number;appId:string;userId:string;state:string;held:boolean;connectedAt:number|null}>;peers:Array<{id:string;participant:number;offerer:boolean;remoteDescription:RTCSessionDescriptionInit|null;remoteCandidates:RTCIceCandidateInit[];connected:boolean}>}
-export interface GroupSnapshot {listeningStatus?:EventStatus;screenSharing?:boolean;screenSharePending?:boolean;displayStream?:MediaStream|null;call:GroupCall|null;muted:boolean;cameraEnabled:boolean;localHeld:boolean;localStream:MediaStream|null;remoteStreams:Record<number,MediaStream>;error:string|null;preparing:boolean;connectedAt:number|null}
+export interface GroupCall {recordingAvailable?:boolean;recordingConfirmedAt?:number;recordingState?:import('./recording.js').CallRecordingState['recording'];screenSharingAvailable?:boolean;sharing?:boolean[];id:string;connectionId:string;group:true;kind:'voice'|'video';version:number;state:'ringing'|'connecting'|'connected'|'ended';reason?:string;createdAt:number;connectedAt:number|null;endedAt:number|null;ringRemainingMs:number;holdExpiresAt:number|null;self:number;controlled:boolean;memberState:'invited'|'joined'|'left'|'declined';localHeld:boolean;members:Array<{id:number;appId:string;userId:string;state:string;held:boolean;connectedAt:number|null}>;peers:Array<{id:string;participant:number;offerer:boolean;remoteDescription:RTCSessionDescriptionInit|null;remoteCandidates:RTCIceCandidateInit[];connected:boolean}>}
+export interface GroupSnapshot { recording?:CallRecordingState;listeningStatus?:EventStatus;screenSharing?:boolean;screenSharePending?:boolean;displayStream?:MediaStream|null;call:GroupCall|null;muted:boolean;cameraEnabled:boolean;localHeld:boolean;localStream:MediaStream|null;remoteStreams:Record<number,MediaStream>;error:string|null;preparing:boolean;connectedAt:number|null}
 export class RobonoGroupCallingClient {
+  readonly recording:CallRecordingController;
  constructor(options:{videoQuality?:'480p'|'720p';request:Request;onSessionExpired?:(error:Error)=>void;onChange?:(state:GroupSnapshot)=>void;getDisplayMedia?:(context?:{isCurrent:()=>boolean})=>Promise<MediaStream>;getUserMedia?:(context:{kind:'voice'|'video';videoQuality?:'480p'|'720p';isCurrent:()=>boolean})=>Promise<MediaStream>;createPeerConnection?:(config:RTCConfiguration)=>RTCPeerConnection;createRemoteStream?:(track:MediaStreamTrack)=>MediaStream;createId?:()=>string;forceRelay?:boolean;pollMs?:number});
  getDiagnostics():Promise<CallDiagnostics>;
  availability(connectionId:string,kind?:'voice'|'video'):Promise<{available:boolean;maxParticipants:number}>;startScreenSharing():Promise<void>;stopScreenSharing():Promise<void>;state:GroupSnapshot;closed:boolean;listen():Promise<void>;refresh():Promise<boolean>;call(connectionId:string,options?:{kind?:'voice'|'video'}):Promise<void>;answer():Promise<void>;leave():Promise<void>;hold():Promise<void>;resume(prepareAudio?:()=>Promise<void>):Promise<void>;mute(value?:boolean):void;setCamera(value:boolean):void;setForeground(value:boolean):void;setVideoForeground(value:boolean):void;dispose():Promise<void>;

package/dist/groups.js

@@ -1,3 +1,4 @@
+import {createCallRecording} from './recording.js';
 import {createTransportTelemetry} from './telemetry.js';
 import {createCallDiagnostics} from './diagnostics.js';
 import {mediaProfile,videoConstraints,limitSender} from './media-profile.js';
@@ -18,10 +19,11 @@ export class RobonoGroupCallingClient {
   this.reportTransport=createTransportTelemetry(request);this.peers=new Map();this.pendingRTC=new Set();this.state={call:null,muted:false,cameraEnabled:true,localHeld:false,localStream:null,remoteStreams:{},error:null,preparing:false,connectedAt:null};
   this.getDiagnostics=createCallDiagnostics(()=>({callId:!this.closed&&this.state.call?.controlled&&this.state.call.state!=='ended'?this.state.call.id:null,peers:[...this.peers.values()].map(p=>({pc:p.pc,participant:p.participant}))}));
   this.sharing=createScreenSharing({limitVideo:sender=>limitSender(sender,this.ice?.videoQuality==='480p'?'480p':this.videoQuality),request:input=>this.request('groups/sharing',input),call:()=>this.state.call,peers:()=>[...this.peers.values()].map(p=>p.pc),stream:()=>this.stream,capture:getDisplayMedia,emit:()=>this.emit(),fail:e=>{this.state.error=e.message;this.emit();}});
+  this.recording=createCallRecording({request,createPeerConnection,stream:()=>this.stream,videoTrack:()=>this.sharing.track(),iceServers:()=>this.ice?.iceServers??[],onChange:()=>this.emit(),createId});
   this.closed=false;this.epoch=0;this.foreground=true;this.failures=0;this.notBefore=0;this.lastSuccess=Date.now();this.holdRevision=0;
  }
  rtc(promise,phase){return new Promise((resolve,reject)=>{let finished=false;const finish=(fn,value)=>{if(finished)return;finished=true;clearTimeout(timer);this.pendingRTC.delete(cancel);fn(value);};const cancel=()=>finish(reject,Error('call_cancelled'));const timer=setTimeout(()=>finish(reject,Error(phase+'_timeout')),8000);this.pendingRTC.add(cancel);Promise.resolve(promise).then(v=>finish(resolve,v),e=>finish(reject,e));});}
- emit(){if(this.events&&this.state.call&&this.state.call.state!=='ended'&&!this.timer&&!this.polling&&!this.closed)this.timer=setTimeout(()=>this.poll(),3000);this.scheduleRingDeadline();Object.assign(this.state,this.sharing.state());this.onChange({...this.state,remoteStreams:{...this.state.remoteStreams}});}
+ emit(){this.recording?.update(this.state.call,this.state.call?.recordingAvailable===true);this.state.recording=this.recording?.snapshot();if(this.events&&this.state.call&&this.state.call.state!=='ended'&&!this.timer&&!this.polling&&!this.closed)this.timer=setTimeout(()=>this.poll(),3000);this.scheduleRingDeadline();Object.assign(this.state,this.sharing.state());this.onChange({...this.state,remoteStreams:{...this.state.remoteStreams}});}
  scheduleRingDeadline(){
   const call=this.state.call;
   if(!call?.controlled||call.state==='ended'||!(call.memberState==='invited'||call.state==='ringing')){clearTimeout(this.ringTimer);this.ringCallId=null;return;}
@@ -150,6 +152,6 @@ export class RobonoGroupCallingClient {
  async hold(){if(!this.state.call||this.state.localHeld)return;this.state.localHeld=true;this.syncTracks();this.emit();await this.sharing.stop().catch(()=>{});try{await this.request('groups/hold',{callId:this.state.call.id,held:true,revision:++this.holdRevision});this.holdDeadline=this.state.call.holdExpiresAt||Date.now()+300000;}catch(e){await this.leave();throw e;}}
  async resume(prepareAudio){if(!this.state.localHeld)return;await prepareAudio?.();await this.request('groups/hold',{callId:this.state.call.id,held:false,revision:++this.holdRevision});this.lastSuccess=Date.now();this.state.localHeld=false;this.syncTracks();this.emit();}
  async leave(){const call=this.state.call;++this.epoch;this.ended??=new Set();if(call)this.ended.add(call.id);while(this.ended.size>256)this.ended.delete(this.ended.values().next().value);this.reset();this.state.call=null;this.state.error=null;this.emit();if(call)await this.request('groups/leave',{callId:call.id});}
- reset(){clearTimeout(this.ringTimer);this.ringCallId=null;this.sharing.reset();++this.epoch;for(const cancel of this.pendingRTC)cancel();this.pendingRTC.clear();this.holdDeadline=0;for(const p of this.peers.values())p.pc.close();this.peers.clear();this.stream?.getTracks().forEach(t=>t.stop());this.stream=null;Object.assign(this.state,{localStream:null,remoteStreams:{},localHeld:false,connectedAt:null});this.holdRevision=0;}
+ reset(){this.recording?.update(null,false);clearTimeout(this.ringTimer);this.ringCallId=null;this.sharing.reset();++this.epoch;for(const cancel of this.pendingRTC)cancel();this.pendingRTC.clear();this.holdDeadline=0;for(const p of this.peers.values())p.pc.close();this.peers.clear();this.stream?.getTracks().forEach(t=>t.stop());this.stream=null;Object.assign(this.state,{localStream:null,remoteStreams:{},localHeld:false,connectedAt:null});this.holdRevision=0;}
  async dispose(){this.events?.close();if(this.closed)return;this.closed=true;clearTimeout(this.timer);clearInterval(this.watch);try{await this.leave();}finally{await this.request('close',{}).catch(()=>{});}}
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type {CallRecordingController,CallRecordingState} from './recording.js';
 export interface CallMediaDiagnostics {kind:'audio'|'video';sendKbps:number|null;receiveKbps:number|null;receiveLossPercent:number|null;jitterMs:number|null;width:number|null;height:number|null;framesPerSecond:number|null}
 export interface CallPeerDiagnostics {participant:number|null;connectionState:'new'|'connecting'|'connected'|'disconnected'|'failed'|'closed';quality:'unknown'|'good'|'fair'|'poor';roundTripMs:number|null;route:'unknown'|'direct'|'relay';protocol:'udp'|'tcp'|null;media:CallMediaDiagnostics[]}
 /** Local measurements only; contains no addresses, media, SDP or credentials. */
@@ -6,13 +7,14 @@ export interface CallHistoryEntry { id: string; sequence: number; connectionId:
 export interface CallHistoryPage { entries: CallHistoryEntry[]; nextCursor: number; hasMore: boolean }
 export type CallState = 'ringing' | 'connecting' | 'connected' | 'ended';
 export interface Call {
-  self?:number;screenSharingAvailable?:boolean;sharing?:boolean[]; id: string; version: number; connectionId: string; kind?: 'voice' | 'video'; 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;screenSharing?:boolean;screenSharePending?:boolean;displayStream?:MediaStream|null; voiceAvailable: boolean; videoAvailable?: boolean; cameraEnabled?: 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 }
+  self?:number;recordingAvailable?:boolean;recordingConfirmedAt?:number;recordingState?:import('./recording.js').CallRecordingState['recording'];screenSharingAvailable?:boolean;sharing?:boolean[]; id: string; version: number; connectionId: string; kind?: 'voice' | 'video'; 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 { recording?:CallRecordingState; listeningStatus?: EventStatus;screenSharing?:boolean;screenSharePending?:boolean;displayStream?:MediaStream|null; voiceAvailable: boolean; videoAvailable?: boolean; cameraEnabled?: 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 {
+  readonly recording:CallRecordingController;
   constructor(options: { videoQuality?: '480p' | '720p'; request: Request; onSessionExpired?: (error: Error) => void; onChange?: (state: Snapshot) => void; onLocalStream?: (stream: MediaStream | null) => void; onRemoteStream?: (stream: MediaStream | null) => void; getDisplayMedia?:(context?:{isCurrent:()=>boolean})=>Promise<MediaStream>;getUserMedia?: (context?: { kind?: 'voice' | 'video'; videoQuality?: '480p'|'720p'; isCurrent: () => boolean }) => Promise<MediaStream>; createPeerConnection?: (config: RTCConfiguration) => RTCPeerConnection; pollMs?: number; forceRelay?: boolean; createId?: () => string; createRemoteStream?: (track: MediaStreamTrack) => MediaStream });
   getDiagnostics():Promise<CallDiagnostics>;
   state: Snapshot;

package/dist/index.js

@@ -1,3 +1,4 @@
+import {createCallRecording} from './recording.js';
 import {subscribeCallingEvents} from './events.js';
 import {createTransportTelemetry} from './telemetry.js';
 import {createCallDiagnostics} from './diagnostics.js';
@@ -39,7 +40,7 @@ export function createHttpTransport({ baseUrl, token, fetcher = fetch, events =
     // Bound the complete operation ourselves, including response-body decoding.
     const deadline = new Promise((_, reject) => { timer = setTimeout(() => {
       controller.abort(); reject(Error('request_timeout'));
-    }, 4500); });
+    }, ['recording/consent','recording/stop'].includes(operation)?30000:operation==='recording/offer'?20000:operation==='recording/request'?10000:4500); });
     try { return await Promise.race([work, deadline]); } finally { clearTimeout(timer); }
   };
   if(events && WebSocketImpl) request.subscribe = callbacks => subscribeCallingEvents({baseUrl,token,WebSocketImpl},callbacks);
@@ -65,6 +66,7 @@ export class RobonoCallingClient {
     this.sharing=createScreenSharing({limitVideo:sender=>limitSender(sender,this.activeVideoQuality??this.videoQuality),request:input=>this.retry('sharing',input),call:()=>this.state.call,peers:()=>this.pc?[this.pc]:[],stream:()=>this.stream,capture:getDisplayMedia,emit:()=>this.emit(),fail:e=>{this.state.error=e.message;this.emit();}});
     this.reportTransport=createTransportTelemetry(request);
     this.getDiagnostics=createCallDiagnostics(()=>({callId:!this.closed&&this.state.call?.controlled&&this.state.call.state!=='ended'?this.state.call.id:null,peers:this.pc?[{pc:this.pc,participant:null}]:[]}));
+    this.recording=createCallRecording({request,createPeerConnection,stream:()=>this.stream,videoTrack:()=>this.sharing.track(),iceServers:()=>this.recordingIce??[],onChange:()=>this.emit(),createId});
     this.localHeld = false; this.holdRevision = 0; this.holdDeadline = 0;
   }
   rtc(promise, phase, timeoutMs = 8000) {
@@ -77,13 +79,14 @@ export class RobonoCallingClient {
   }
   emit() {
     const call = this.state.call;
+    this.recording?.update(call,call?.recordingAvailable===true);
     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,...this.sharing.state(), preparing: this.busy, localHeld: this.localHeld,
+    this.onChange({ ...this.state,recording:this.recording?.snapshot(),...this.sharing.state(), preparing: this.busy, localHeld: this.localHeld,
       call: connected ? { ...call, state: this.pc?.connectionState === 'disconnected' ? 'connecting' : 'connected', connectedAt: this.mediaConnectedAt } : call });
   }
   scheduleRingDeadline(call) {
@@ -269,6 +272,7 @@ export class RobonoCallingClient {
     }
   }
   resetMedia() {
+    this.recording?.update(null,false);
     this.sharing.reset();
     this.epoch++;
     for (const timer of this.mediaTimers) clearTimeout(timer); this.mediaTimers.clear();
@@ -285,6 +289,7 @@ export class RobonoCallingClient {
     const ice = await this.request('ice', { ...(connectionId ? { connectionId } : {}), kind });
     if (this.closed || epoch !== this.epoch) throw Error('call_cancelled');
     if (this.forceRelay && !ice.relayAvailable) throw Error('relay_not_configured');
+    this.recordingIce=ice.iceServers;
     this.activeVideoQuality=ice.videoQuality==='480p'?'480p':this.videoQuality;
     const stream = await this.rtc(this.getUserMedia({ kind, videoQuality: ice.videoQuality === '480p' ? '480p' : this.videoQuality, isCurrent: () => !this.closed && epoch === this.epoch }).then(stream => {
       if (this.closed || epoch !== this.epoch) stream.getTracks().forEach(t => t.stop());

package/dist/recording.d.ts

@@ -0,0 +1,16 @@
+export interface CallRecordingState {
+ available:boolean;
+ capabilities?:{available:boolean;audio?:boolean;video?:boolean;captions?:boolean;maxMinutes?:number;retentionDays?:number};
+ recording:null|{transcript?:{state:'live'|'complete'|'unavailable';error:string|null;captions:{participant:number;sequence:number;startMs:number;endMs:number;text:string}[]};id:string;revision?:number;createdAt?:number;callId:string;state:'awaiting_consent'|'preparing'|'recording'|'stopping'|'complete'|'failed'|'declined'|'cancelled'|'expired';mode:'audio'|'video';transcribe:boolean;requestedBy:number;consents:{participant:number;accepted:boolean}[];startedAt:number|null;endedAt:number|null;expiresAt:number;reason?:string};
+ error:string|null;
+}
+export interface CallRecordingController {
+ snapshot():CallRecordingState;
+ update(call:{id:string;controlled:boolean;state:string;self:number;recordingConfirmedAt?:number;recordingState?:CallRecordingState['recording']}|null,available:boolean):void;
+ start(options?:{mode?:'audio'|'video';transcribe?:boolean;requestId?:string}):Promise<unknown>;
+ consent(accept:boolean):Promise<unknown>;
+ stop():Promise<void>;
+ refresh():Promise<void>;
+ dispose():void;
+}
+export function createCallRecording(options:{request:(operation:string,input:Record<string,unknown>)=>Promise<any>;createPeerConnection:(config:{iceServers:RTCIceServer[]})=>RTCPeerConnection;stream:()=>MediaStream|null;videoTrack?:()=>MediaStreamTrack|null|undefined;iceServers?:()=>RTCIceServer[];onChange?:(state:CallRecordingState)=>void;createId?:()=>string;pollMs?:number}):CallRecordingController;

package/dist/recording.js

@@ -0,0 +1,116 @@
+/** Publishes the already-authorized call tracks to Robono's recorder.
+ * Never opens another microphone or records sound from the phone's speaker.
+ */
+export function createCallRecording({request,createPeerConnection,stream,videoTrack,iceServers=()=>[],onChange=()=>{},createId=()=>crypto.randomUUID(),pollMs=1500}){
+ if(!Number.isSafeInteger(pollMs)||pollMs<250||pollMs>5000)throw Error('invalid_recording_poll_interval');
+ let call=null,enabled=false,recording=null,error=null,timer=null,busy=false,pc=null,publishing=null,epoch=0,revision=0,disposed=false,lastGood=0,pendingStart=null;
+ const withdrawn=new Set();
+ let capabilities={available:false},capabilitiesKnown=false,confirmedAt=null;
+ const watchdog=setInterval(()=>{if(pc&&Date.now()-lastGood>10000){stopPublisher();error='recording_confirmation_lost';emit();}},1000);watchdog.unref?.();
+ const snapshot=()=>({available:enabled&&call?.controlled===true&&call?.state==='connected'&&(capabilities.available===true||!!recording),capabilities,recording,error});
+ const emit=()=>onChange(snapshot());
+ function stopPublisher(){epoch++;const old=pc;pc=null;publishing=null;if(old){old.onconnectionstatechange=null;old.close();}}
+ function setRecord(value){
+  if(value!==null&&(!value||value.callId!==call?.id||typeof value.id!=='string'||!['awaiting_consent','preparing','recording','stopping','complete','failed','declined','cancelled','expired'].includes(value.state)||!Array.isArray(value.consents)||value.consents.length>8))throw Error('invalid_recording_state');
+  if(recording&&value&&(value.createdAt<recording.createdAt||value.id===recording.id&&value.revision<recording.revision))return;
+  recording=value;lastGood=Date.now();error=null;
+  if(!value||!['preparing','recording'].includes(value.state))stopPublisher();
+  emit();
+ }
+ function schedule(){clearTimeout(timer);if(!disposed&&enabled&&call?.controlled&&call.state!=='ended'&&(!Object.hasOwn(call,'recordingState')||!capabilitiesKnown)){timer=setTimeout(()=>void refresh(),pollMs);timer.unref?.();}}
+ async function gather(connection,generation){
+  if(connection.iceGatheringState==='complete')return;
+  await new Promise((resolve,reject)=>{
+   // Some optional STUN/TURN addresses never finish gathering even after a usable
+   // route is available. Send the collected candidates at the deadline; the
+   // peer must still establish its authenticated WebRTC connection.
+   const deadline=setTimeout(()=>finish(/(?:^|\n)a=candidate:/.test(connection.localDescription?.sdp??'')?undefined:Error('recording_connection_timeout')),8000);
+   const interval=setInterval(()=>{if(generation!==epoch||disposed)finish(Error('recording_cancelled'));else if(connection.iceGatheringState==='complete')finish();},50);
+   function finish(failure){clearTimeout(deadline);clearInterval(interval);failure?reject(failure):resolve();}
+  });
+ }
+ async function publish(){
+  const selected=recording,c=call;
+  if(Date.now()-lastGood>10000)return;
+  if(selected&&withdrawn.has(selected.id))return;
+  if(!selected||!c||!['preparing','recording'].includes(selected.state)||selected.consents.some(p=>p.accepted!==true)||!selected.consents.some(p=>p.participant===c.self&&p.accepted))return;
+  if(pc){const sender=pc.getSenders().find(s=>s.track?.kind==='video'),track=videoTrack?.()??stream()?.getVideoTracks()[0];if(sender&&track&&sender.track!==track)await sender.replaceTrack(track);return;}
+  if(publishing)return publishing;
+  const local=stream();if(!local?.getAudioTracks().length)throw Error('recording_call_audio_unavailable');
+  const generation=++epoch;const connection=pc=createPeerConnection({iceServers:iceServers()});
+  const work=(async()=>{
+   for(const track of local.getAudioTracks())connection.addTrack(track,local);
+   if(selected.mode==='video'){const track=videoTrack?.()??local.getVideoTracks()[0];if(track)connection.addTrack(track,local);}
+   connection.onconnectionstatechange=()=>{if(pc===connection&&connection.connectionState==='failed'){stopPublisher();error='recording_connection_failed';emit();void request('recording/stop',{callId:c.id,id:selected.id}).catch(()=>{});}};
+   await connection.setLocalDescription(await connection.createOffer());await gather(connection,generation);
+   if(generation!==epoch||call?.id!==c.id)throw Error('recording_cancelled');
+   const response=await request('recording/offer',{callId:c.id,id:selected.id,description:{type:connection.localDescription.type,sdp:connection.localDescription.sdp}});
+   if(generation!==epoch||call?.id!==c.id)throw Error('recording_cancelled');
+   if(response?.description?.type!=='answer'||typeof response.description.sdp!=='string')throw Error('invalid_recording_answer');
+   await connection.setRemoteDescription(response.description);
+  })().catch(failure=>{if(generation===epoch){stopPublisher();error=failure.message;emit();void request('recording/stop',{callId:c.id,id:selected.id}).catch(()=>{});}throw failure;}).finally(()=>{if(publishing===work)publishing=null;});publishing=work;return work;
+ }
+ async function refresh(){
+  if(busy||disposed||!enabled||!call?.controlled||call.state==='ended')return;
+  const id=call.id,version=revision;busy=true;
+  try{const result=await request('recording/state',{callId:id});if(disposed||call?.id!==id||version!==revision)return;capabilities=result.capabilities??{available:false};capabilitiesKnown=typeof result.capabilities?.available==='boolean';setRecord(result.recording??null);
+   if(recording&&withdrawn.has(recording.id)&&['awaiting_consent','preparing','recording','stopping'].includes(recording.state)){
+    const stopped=await request('recording/stop',{callId:id,id:recording.id});
+    if(!disposed&&call?.id===id&&version===revision)setRecord(stopped);
+   }else await publish();}
+  catch(failure){if(!disposed&&call?.id===id&&version===revision){stopPublisher();error=failure.message;emit();}}
+  finally{busy=false;schedule();}
+ }
+ return {
+  snapshot,
+  update(next,available){
+   const callChanged=next?.id!==call?.id,changed=callChanged||!!available!==enabled;
+   if(changed){revision++;pendingStart=null;}if(callChanged){withdrawn.clear();capabilities={available:false};capabilitiesKnown=false;confirmedAt=null;}call=next;enabled=available===true;
+   if(Number.isSafeInteger(next?.recordingConfirmedAt)&&next.recordingConfirmedAt!==confirmedAt){confirmedAt=next.recordingConfirmedAt;lastGood=Date.now();}
+   if(!enabled||!call?.controlled||call.state==='ended'||disposed){revision++;clearTimeout(timer);stopPublisher();recording=null;return;}
+   if(changed){stopPublisher();recording=null;error=null;void refresh();}
+   else if(Object.hasOwn(call,'recordingState')){
+    const value=call.recordingState;
+    const newer=!recording||value&&(value.id===recording.id?value.revision>recording.revision:value.createdAt>=recording.createdAt);
+    if(newer&&JSON.stringify(value)!==JSON.stringify(recording)){try{setRecord(value);void publish().catch(()=>{});}catch{stopPublisher();error='invalid_recording_state';}}
+    if(recording&&['preparing','recording'].includes(recording.state)&&stream()?.getAudioTracks().length)void publish().catch(()=>{});
+    if(value&&withdrawn.has(value.id)&&recording&&['awaiting_consent','preparing','recording','stopping'].includes(recording.state)&&['awaiting_consent','preparing','recording'].includes(value.state))void refresh();
+   }
+   // A stalled status response cannot keep capture running without current consent.
+   if(pc&&Date.now()-lastGood>10000){stopPublisher();error='recording_confirmation_lost';emit();}
+  },
+  async start({mode='audio',transcribe=false,requestId}={}){
+   if(!enabled||!call?.controlled||call.state!=='connected')throw Error('recording_unavailable');
+   if(!['audio','video'].includes(mode)||typeof transcribe!=='boolean')throw Error('invalid_recording_request');
+   if(pendingStart&&(pendingStart.mode!==mode||pendingStart.transcribe!==transcribe||requestId&&pendingStart.requestId!==requestId))throw Error('recording_request_pending');
+   pendingStart??={mode,transcribe,requestId:requestId??createId()};
+   if(pendingStart.promise)return pendingStart.promise;
+   const pending=pendingStart,id=call.id,version=++revision;
+   const work=(async()=>{
+    const result=await request('recording/request',{callId:id,mode,transcribe,requestId:pending.requestId});
+    if(call?.id!==id||disposed||version!==revision)throw Error('recording_cancelled');
+    setRecord(result);pendingStart=null;schedule();return result;
+   })().catch(error=>{if(pendingStart===pending&&error?.status>=400&&error.status<500&&![408,429].includes(error.status))pendingStart=null;throw error;}).finally(()=>{if(pendingStart===pending)pending.promise=null;});
+   pending.promise=work;return work;
+  },
+  async consent(accept){
+   if(typeof accept!=='boolean'||!recording||!call)throw Error('recording_not_requested');
+   const id=call.id,recordId=recording.id,version=++revision;
+   if(accept&&withdrawn.has(recordId))throw Error('recording_consent_withdrawn');
+   if(!accept){withdrawn.add(recordId);stopPublisher();}
+   try{
+    const result=await request('recording/consent',{callId:id,id:recordId,accept});
+    if(call?.id!==id||disposed||version!==revision)return;
+    setRecord(result);await publish();return result;
+   }finally{schedule();}
+  },
+  async stop(){
+   const version=++revision;stopPublisher();if(!recording||!call)return;
+   const id=call.id,recordId=recording.id;withdrawn.add(recordId);
+   try{const result=await request('recording/stop',{callId:id,id:recordId});if(call?.id===id&&!disposed&&version===revision)setRecord(result);}
+   finally{schedule();}
+  },
+  refresh,
+  dispose(){revision++;disposed=true;clearTimeout(timer);clearInterval(watchdog);stopPublisher();call=null;recording=null;},
+ };
+}

package/package.json

@@ -17,7 +17,7 @@
     "provenance": true
   },
   "name": "@robono/calling",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "WebRTC voice, video, group calling and screen sharing within apps and across Robono Bridge networks.",
   "homepage": "https://robono.com/docs#calling",
   "repository": {
@@ -28,6 +28,10 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./recording": {
+      "types": "./dist/recording.d.ts",
+      "import": "./dist/recording.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"