@xema/omni-protocol 0.1.135 → 0.1.136

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -153,8 +153,11 @@ export interface PhoneState {
153
153
  muted?: true;
154
154
  /** When the status began, counted from the provider's clock. Omitted rather than invented. */
155
155
  since?: IsoTimestamp;
156
- /** The calls on the phone; `[]` when idle. None under `unregistered` or `off-hook`. */
157
- channels: PhoneChannel[];
156
+ /**
157
+ * The calls on the phone; `[]` when idle. None under `unregistered` or `off-hook`. Omitted only
158
+ * where the provider cannot see the calls on the device: present, it is every one of them.
159
+ */
160
+ channels?: PhoneChannel[];
158
161
  }
159
162
  /** Every idle capability a provider may declare. Only voice may `dial`; the channel arm says so. */
160
163
  export declare const IDLE_CAPABILITIES: readonly ["dial", "personalBrowser", "calendar", "contacts"];
@@ -2443,8 +2443,12 @@ function validatePhoneStateInto(value, path, context, into) {
2443
2443
  if (value.since !== undefined)
2444
2444
  into.timestamp(value.since, "phone.since", `${path}.since`);
2445
2445
  // The phone's own calls: one active at most, any number held, and none on a phone that cannot carry one.
2446
- if (!Array.isArray(value.channels)) {
2447
- into.add("phone.channels.shape", `${path}.channels`, "channels is the phone's calls, an array: [] when idle");
2446
+ // Omitted, the provider cannot see the device's calls, and there is nothing to hold them to.
2447
+ if (value.channels === undefined) {
2448
+ // The status still stands on its own.
2449
+ }
2450
+ else if (!Array.isArray(value.channels)) {
2451
+ into.add("phone.channels.shape", `${path}.channels`, "channels is the phone's calls, an array: [] when idle, omitted only where the provider cannot see them");
2448
2452
  }
2449
2453
  else {
2450
2454
  let active = 0;
package/guide/phone.md CHANGED
@@ -305,6 +305,8 @@ const busy: PhoneState = { phone: "hardphone", status: "ready", muted: true, cha
305
305
  const internal: PhoneState = { phone: "hardphone", status: "ready", channels: [{ state: "active", since: "2026-09-12T11:02:00Z" }] };
306
306
  // a hardphone the platform lost
307
307
  const down: PhoneState = { phone: "hardphone", status: "unregistered", since: "2026-09-12T10:41:00Z", channels: [] };
308
+ // a platform that sees the registration but not the calls on the device
309
+ const unseen: PhoneState = { phone: "softphone", status: "unregistered", since: "2026-09-12T10:41:00Z" };
308
310
  ```
309
311
 
310
312
  **The device.** `status` is the phone itself: `ready` is registered and usable, idle or busy, and
@@ -333,6 +335,14 @@ started, `held` with the task `paused`, `ringing` with the task `pending` or its
333
335
  phone carries every call the agent computer is on. A channel naming no task is the phone's alone, and the
334
336
  agent computer shows it as a call it cannot act on.
335
337
 
338
+ **Omitted only where the provider cannot see them.** Some platforms know whether the phone is
339
+ registered but not which calls are on it: an internal call, a lead's listening leg. Such a
340
+ provider still declares `phoneStatus` and publishes the status, and leaves `channels` out. Omitted
341
+ and empty are different claims: `[]` says the phone is idle, and no `channels` says nothing about
342
+ its calls, so none of the channel checks apply. Present, the list is every call on the device.
343
+ Leaving the status out instead would hide a phone that cannot take a call, which is the one thing
344
+ the agent and the lead most need to see.
345
+
336
346
  **The mute is the phone's, and it silences whatever is active.** It is one flag on the phone, not
337
347
  a property of a channel: whichever channel is active is silent while it is set, and the held
338
348
  channels are unaffected. Who owns it follows the phone. On a hardphone the mute button is the
package/guide.md CHANGED
@@ -217,7 +217,7 @@ type PhoneState = {
217
217
  status: PhoneStatus;
218
218
  muted?: true;
219
219
  since?: IsoTimestamp;
220
- channels: PhoneChannel[];
220
+ channels?: PhoneChannel[];
221
221
  };
222
222
 
223
223
  type IdleCapabilities<C extends Channel = Channel> = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xema/omni-protocol",
3
- "version": "0.1.135",
3
+ "version": "0.1.136",
4
4
  "description": "The Omni protocol: the contract every provider adapter implements",
5
5
  "type": "module",
6
6
  "license": "MIT",