@ai-matrx/desktop-protocol 0.6.0 → 0.7.0

package/dist/react.d.cts

@@ -23,6 +23,23 @@ interface ErrorData {
     } | undefined;
 }
 
+/**
+ * What a connecting side does after each WebSocket close — the ONE table every client reads (the
+ * package client, the desktop's relay transport, any other dialer). Never keep a local list of
+ * "terminal" codes: a code added to CloseCode without a rule here fails to compile.
+ *
+ *   reconnect_now  the far side went away on purpose or the socket died; dial again at once if the
+ *                  connection had opened, with backoff otherwise (a dead network never spins).
+ *   reconnect      transient refusal; dial again with backoff.
+ *   reauth         the token was refused; get a FRESH token and dial once more. A second refusal in
+ *                  a row (no successful open between) is terminal with outcome "signed_out".
+ *   stop           retrying cannot help: stop dialing until something changes (a new sign-in, a
+ *                  new device, an update) and show the outcome.
+ */
+
+/** The one state a person is shown when dialing stops. */
+type CloseOutcome = "signed_out" | "not_owned" | "removed" | "revoked" | "replaced" | "upgrade_required";
+
 /**
  * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a
  * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on
@@ -839,6 +856,8 @@ interface DesktopClientState {
     retryInMs: number | null;
     lastError: DesktopProtocolError | null;
     lastCloseCode: number | null;
+    /** Why dialing stopped, when the far side refused us for good (CLOSE_RULES); null otherwise. */
+    outcome: CloseOutcome | null;
 }
 interface RequestOptions {
     signal?: AbortSignal;

package/dist/react.d.ts

@@ -23,6 +23,23 @@ interface ErrorData {
     } | undefined;
 }
 
+/**
+ * What a connecting side does after each WebSocket close — the ONE table every client reads (the
+ * package client, the desktop's relay transport, any other dialer). Never keep a local list of
+ * "terminal" codes: a code added to CloseCode without a rule here fails to compile.
+ *
+ *   reconnect_now  the far side went away on purpose or the socket died; dial again at once if the
+ *                  connection had opened, with backoff otherwise (a dead network never spins).
+ *   reconnect      transient refusal; dial again with backoff.
+ *   reauth         the token was refused; get a FRESH token and dial once more. A second refusal in
+ *                  a row (no successful open between) is terminal with outcome "signed_out".
+ *   stop           retrying cannot help: stop dialing until something changes (a new sign-in, a
+ *                  new device, an update) and show the outcome.
+ */
+
+/** The one state a person is shown when dialing stops. */
+type CloseOutcome = "signed_out" | "not_owned" | "removed" | "revoked" | "replaced" | "upgrade_required";
+
 /**
  * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a
  * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on
@@ -839,6 +856,8 @@ interface DesktopClientState {
     retryInMs: number | null;
     lastError: DesktopProtocolError | null;
     lastCloseCode: number | null;
+    /** Why dialing stopped, when the far side refused us for good (CLOSE_RULES); null otherwise. */
+    outcome: CloseOutcome | null;
 }
 interface RequestOptions {
     signal?: AbortSignal;

package/dist/{registry-jTmq1CsI.d.cts → registry-Duc_VFN8.d.cts}

@@ -22,6 +22,96 @@ interface ErrorData {
     } | undefined;
 }
 
+/**
+ * What a connecting side does after each WebSocket close — the ONE table every client reads (the
+ * package client, the desktop's relay transport, any other dialer). Never keep a local list of
+ * "terminal" codes: a code added to CloseCode without a rule here fails to compile.
+ *
+ *   reconnect_now  the far side went away on purpose or the socket died; dial again at once if the
+ *                  connection had opened, with backoff otherwise (a dead network never spins).
+ *   reconnect      transient refusal; dial again with backoff.
+ *   reauth         the token was refused; get a FRESH token and dial once more. A second refusal in
+ *                  a row (no successful open between) is terminal with outcome "signed_out".
+ *   stop           retrying cannot help: stop dialing until something changes (a new sign-in, a
+ *                  new device, an update) and show the outcome.
+ */
+
+type CloseAction = "reconnect_now" | "reconnect" | "reauth" | "stop";
+/** The one state a person is shown when dialing stops. */
+type CloseOutcome = "signed_out" | "not_owned" | "removed" | "revoked" | "replaced" | "upgrade_required";
+interface CloseRule {
+    readonly action: CloseAction;
+    /** Set for `stop` and `reauth` (the outcome when the fresh token is refused too). */
+    readonly outcome?: CloseOutcome;
+    /** The error a caller's pending work is failed with. */
+    readonly error: readonly [ErrorCodeName, string];
+}
+declare const CLOSE_RULES: {
+    readonly 1000: {
+        readonly action: "reconnect";
+        readonly error: readonly ["DEVICE_OFFLINE", "Connection closed"];
+    };
+    readonly 1001: {
+        readonly action: "reconnect_now";
+        readonly error: readonly ["DEVICE_OFFLINE", "Connection lost"];
+    };
+    readonly 1006: {
+        readonly action: "reconnect_now";
+        readonly error: readonly ["DEVICE_OFFLINE", "Connection lost"];
+    };
+    readonly 1012: {
+        readonly action: "reconnect_now";
+        readonly error: readonly ["DEVICE_OFFLINE", "Device reconnected"];
+    };
+    readonly 1013: {
+        readonly action: "reconnect";
+        readonly error: readonly ["DEVICE_OFFLINE", "Relay busy; retrying"];
+    };
+    readonly 4001: {
+        readonly action: "reauth";
+        readonly outcome: "signed_out";
+        readonly error: readonly ["AUTH_INVALID", "Sign-in was not accepted"];
+    };
+    readonly 4003: {
+        readonly action: "stop";
+        readonly outcome: "not_owned";
+        readonly error: readonly ["AUTH_FORBIDDEN", "Not this device's owner"];
+    };
+    readonly 4004: {
+        readonly action: "stop";
+        readonly outcome: "removed";
+        readonly error: readonly ["NOT_FOUND", "Device not found"];
+    };
+    readonly 4008: {
+        readonly action: "reauth";
+        readonly outcome: "signed_out";
+        readonly error: readonly ["AUTH_EXPIRED", "Sign-in expired"];
+    };
+    readonly 4009: {
+        readonly action: "stop";
+        readonly outcome: "replaced";
+        readonly error: readonly ["CONFLICT", "Replaced by a newer connection"];
+    };
+    readonly 4010: {
+        readonly action: "stop";
+        readonly outcome: "revoked";
+        readonly error: readonly ["AUTH_DEVICE_REVOKED", "This device was revoked"];
+    };
+    readonly 4400: {
+        readonly action: "reconnect";
+        readonly error: readonly ["PROTOCOL_ERROR", "Connection reset by the relay"];
+    };
+    readonly 4426: {
+        readonly action: "stop";
+        readonly outcome: "upgrade_required";
+        readonly error: readonly ["PROTOCOL_VERSION_UNSUPPORTED", "Protocol upgrade required"];
+    };
+};
+/** The rule for any close code; one this table does not know (or null: no close frame) reconnects with backoff. */
+declare function closeRule(code: number | null | undefined): CloseRule;
+/** True when dialing must stop after this close (no retry will help). */
+declare function isTerminalClose(code: number | null | undefined): boolean;
+
 /**
  * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a
  * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on
@@ -2445,4 +2535,4 @@ declare const NAMED_SCHEMAS: {
 };
 type NamedSchemaId = keyof typeof NAMED_SCHEMAS;
 
-export { ResponseMsg as A, BEARER_PREFIX as B, ClientType as C, DesktopProtocolError as D, EndReason as E, FsPatchEditFailure as F, SUBPROTOCOL as G, HelloMsg as H, StreamMsg as I, Limits as L, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, RelayMsg as R, StreamMeta as S, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, CancelMsg as e, ClientToCoreMsg as f, CloseCode as g, CloseCodeValue as h, isDesktopProtocolError as i, CoreToClientMsg as j, CreditMsg as k, EndMsg as l, ErrorCode as m, type ErrorCodeName as n, type ErrorData as o, ErrorMsg as p, ErrorReason as q, type ErrorReasonName as r, EventMsg as s, type EventName as t, type NamedSchemaId as u, OpDescriptor as v, type OpSpec as w, PONG_TEXT as x, ProtocolErrorBody as y, RequestMsg as z };
+export { type OpSpec as A, BEARER_PREFIX as B, type CloseOutcome as C, DesktopProtocolError as D, EndReason as E, FsPatchEditFailure as F, PONG_TEXT as G, HelloMsg as H, ProtocolErrorBody as I, RequestMsg as J, ResponseMsg as K, Limits as L, SUBPROTOCOL as M, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, StreamMsg as Q, RelayMsg as R, StreamMeta as S, closeRule as T, isTerminalClose as U, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, ClientType as e, CLOSE_RULES as f, CancelMsg as g, ClientToCoreMsg as h, isDesktopProtocolError as i, type CloseAction as j, CloseCode as k, CloseCodeValue as l, type CloseRule as m, CoreToClientMsg as n, CreditMsg as o, EndMsg as p, ErrorCode as q, type ErrorCodeName as r, type ErrorData as s, ErrorMsg as t, ErrorReason as u, type ErrorReasonName as v, EventMsg as w, type EventName as x, type NamedSchemaId as y, OpDescriptor as z };

package/dist/{registry-jTmq1CsI.d.ts → registry-Duc_VFN8.d.ts}

@@ -22,6 +22,96 @@ interface ErrorData {
     } | undefined;
 }
 
+/**
+ * What a connecting side does after each WebSocket close — the ONE table every client reads (the
+ * package client, the desktop's relay transport, any other dialer). Never keep a local list of
+ * "terminal" codes: a code added to CloseCode without a rule here fails to compile.
+ *
+ *   reconnect_now  the far side went away on purpose or the socket died; dial again at once if the
+ *                  connection had opened, with backoff otherwise (a dead network never spins).
+ *   reconnect      transient refusal; dial again with backoff.
+ *   reauth         the token was refused; get a FRESH token and dial once more. A second refusal in
+ *                  a row (no successful open between) is terminal with outcome "signed_out".
+ *   stop           retrying cannot help: stop dialing until something changes (a new sign-in, a
+ *                  new device, an update) and show the outcome.
+ */
+
+type CloseAction = "reconnect_now" | "reconnect" | "reauth" | "stop";
+/** The one state a person is shown when dialing stops. */
+type CloseOutcome = "signed_out" | "not_owned" | "removed" | "revoked" | "replaced" | "upgrade_required";
+interface CloseRule {
+    readonly action: CloseAction;
+    /** Set for `stop` and `reauth` (the outcome when the fresh token is refused too). */
+    readonly outcome?: CloseOutcome;
+    /** The error a caller's pending work is failed with. */
+    readonly error: readonly [ErrorCodeName, string];
+}
+declare const CLOSE_RULES: {
+    readonly 1000: {
+        readonly action: "reconnect";
+        readonly error: readonly ["DEVICE_OFFLINE", "Connection closed"];
+    };
+    readonly 1001: {
+        readonly action: "reconnect_now";
+        readonly error: readonly ["DEVICE_OFFLINE", "Connection lost"];
+    };
+    readonly 1006: {
+        readonly action: "reconnect_now";
+        readonly error: readonly ["DEVICE_OFFLINE", "Connection lost"];
+    };
+    readonly 1012: {
+        readonly action: "reconnect_now";
+        readonly error: readonly ["DEVICE_OFFLINE", "Device reconnected"];
+    };
+    readonly 1013: {
+        readonly action: "reconnect";
+        readonly error: readonly ["DEVICE_OFFLINE", "Relay busy; retrying"];
+    };
+    readonly 4001: {
+        readonly action: "reauth";
+        readonly outcome: "signed_out";
+        readonly error: readonly ["AUTH_INVALID", "Sign-in was not accepted"];
+    };
+    readonly 4003: {
+        readonly action: "stop";
+        readonly outcome: "not_owned";
+        readonly error: readonly ["AUTH_FORBIDDEN", "Not this device's owner"];
+    };
+    readonly 4004: {
+        readonly action: "stop";
+        readonly outcome: "removed";
+        readonly error: readonly ["NOT_FOUND", "Device not found"];
+    };
+    readonly 4008: {
+        readonly action: "reauth";
+        readonly outcome: "signed_out";
+        readonly error: readonly ["AUTH_EXPIRED", "Sign-in expired"];
+    };
+    readonly 4009: {
+        readonly action: "stop";
+        readonly outcome: "replaced";
+        readonly error: readonly ["CONFLICT", "Replaced by a newer connection"];
+    };
+    readonly 4010: {
+        readonly action: "stop";
+        readonly outcome: "revoked";
+        readonly error: readonly ["AUTH_DEVICE_REVOKED", "This device was revoked"];
+    };
+    readonly 4400: {
+        readonly action: "reconnect";
+        readonly error: readonly ["PROTOCOL_ERROR", "Connection reset by the relay"];
+    };
+    readonly 4426: {
+        readonly action: "stop";
+        readonly outcome: "upgrade_required";
+        readonly error: readonly ["PROTOCOL_VERSION_UNSUPPORTED", "Protocol upgrade required"];
+    };
+};
+/** The rule for any close code; one this table does not know (or null: no close frame) reconnects with backoff. */
+declare function closeRule(code: number | null | undefined): CloseRule;
+/** True when dialing must stop after this close (no retry will help). */
+declare function isTerminalClose(code: number | null | undefined): boolean;
+
 /**
  * The one error type every package entry throws. It carries the wire ErrorCode (SPEC §5), so a
  * caller branches on `code`/`retryable`/`data.reason` and never parses a message. Zod-free on
@@ -2445,4 +2535,4 @@ declare const NAMED_SCHEMAS: {
 };
 type NamedSchemaId = keyof typeof NAMED_SCHEMAS;
 
-export { ResponseMsg as A, BEARER_PREFIX as B, ClientType as C, DesktopProtocolError as D, EndReason as E, FsPatchEditFailure as F, SUBPROTOCOL as G, HelloMsg as H, StreamMsg as I, Limits as L, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, RelayMsg as R, StreamMeta as S, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, CancelMsg as e, ClientToCoreMsg as f, CloseCode as g, CloseCodeValue as h, isDesktopProtocolError as i, CoreToClientMsg as j, CreditMsg as k, EndMsg as l, ErrorCode as m, type ErrorCodeName as n, type ErrorData as o, ErrorMsg as p, ErrorReason as q, type ErrorReasonName as r, EventMsg as s, type EventName as t, type NamedSchemaId as u, OpDescriptor as v, type OpSpec as w, PONG_TEXT as x, ProtocolErrorBody as y, RequestMsg as z };
+export { type OpSpec as A, BEARER_PREFIX as B, type CloseOutcome as C, DesktopProtocolError as D, EndReason as E, FsPatchEditFailure as F, PONG_TEXT as G, HelloMsg as H, ProtocolErrorBody as I, RequestMsg as J, ResponseMsg as K, Limits as L, SUBPROTOCOL as M, NAMED_SCHEMAS as N, type OpName as O, PING_TEXT as P, StreamMsg as Q, RelayMsg as R, StreamMeta as S, closeRule as T, isTerminalClose as U, Welcome as W, type OpParams as a, type OpResult as b, OPS as c, EVENTS as d, ClientType as e, CLOSE_RULES as f, CancelMsg as g, ClientToCoreMsg as h, isDesktopProtocolError as i, type CloseAction as j, CloseCode as k, CloseCodeValue as l, type CloseRule as m, CoreToClientMsg as n, CreditMsg as o, EndMsg as p, ErrorCode as q, type ErrorCodeName as r, type ErrorData as s, ErrorMsg as t, ErrorReason as u, type ErrorReasonName as v, EventMsg as w, type EventName as x, type NamedSchemaId as y, OpDescriptor as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/desktop-protocol",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The one wire contract between Matrx 2 (the desktop app) and every client that drives it — phone, web app, extension, server: zod schemas for the envelope and every cap.op, the 16-byte binary frame codec, a reconnecting request/stream/credit/reattach client, React hooks, and a generated JSON Schema + Pydantic twin that CI keeps byte-identical.",
   "type": "module",
   "main": "./dist/index.cjs",