@wix/himalaya-cli 0.1406.0 → 0.1407.0

package/guides/sdk-reference.json

@@ -5234,6 +5234,12 @@
         "kind": "const",
         "jsdoc": "/** Capability version, for bundles that gate on min binary version. */",
         "decl": "export const version = 2;"
+      },
+      {
+        "name": "\"./offline.js\"",
+        "kind": "reexport",
+        "jsdoc": "",
+        "decl": "export {\n  offline, isOfflineWriteBlocked, isOfflineWriteOutcomeUnknown,\n  type Sent, type Queued, type OfflineResult, type OfflineEvent, type OfflineEventType, type PendingWrite, type RejectedWrite,\n} from \"./offline.js\";"
       }
     ]
   },

package/guides/wix-api-usage.md

@@ -222,6 +222,55 @@ hosts will require. (Contrast: the cross-cutting facade `@himalaya/wix-platform`
 provisioned — decide per call whether to surface, fall back, or render an empty state (don't crash the worker).
 Produce complete results synchronously in the action (the ambient tick is unreliable — see the Tier-5 notes).
 
+## Offline writes — `{ offline: "queue" }`
+
+A write a member makes offline can wait in an on-device outbox and go out on reconnect, but only
+when BOTH keys turn:
+
+1. **The app's cache rule opts the endpoint in**, naming it exactly, with a `method` and a `tag`:
+
+   ```ts
+   cache: { rules: [
+     { method: "POST", pathPrefix: "/form-submission-service/v4/submissions", cacheable: false, ttl: 0,
+       tag: "forms", queueOffline: true },
+   ] }
+   ```
+
+   The platform queues it only if the endpoint is one it lists as safe to resend (each verified
+   live for how a repeated request is deduplicated), and never for payments, checkout, orders,
+   auth, gift cards, loyalty or bookings. It decides the dedupe mechanism and a max age (7 days,
+   24 hours for personal data). App validation reports a rule that asks but cannot queue, and why.
+
+2. **The call site asks**, so a worker that never heard of this keeps today's behaviour:
+
+   ```ts
+   import { offline, isOfflineWriteOutcomeUnknown } from "@himalaya/wix-platform";
+
+   const r = await offline.call("POST", "/form-submission-service/v4/submissions", body);
+   if (r.status === "queued") markPending(r.writeId);   // show the row as "Pending"
+   else render(r.value);                                // r.status === "sent"
+   offline.on("applied", (e) => clearPending(e.writeId));
+   offline.on("rejected", (e) => showFailed(e.writeId, e.code));
+   ```
+
+   (`himalaya.wixApi.call(method, path, body, headers, { offline: "queue" })` is the raw form.)
+
+What a worker gets back:
+
+- `sent` — online and nothing of the same `tag` waiting: the endpoint's own answer.
+- `queued` — offline, or behind an earlier write of the same `tag`, or the live attempt failed in a
+  way the outbox will retry. Never resubmit it: that would be a real duplicate.
+- a thrown response error — a definite rejection (a 4xx), exactly as without the option.
+- `err.code === "offline_write_outcome_unknown"` — an endpoint with no server-side dedupe whose
+  attempt may or may not have landed. Say "we couldn't confirm this went through".
+- `err.code === "offline_write_blocked"` — offline and the write may not queue (`err.reason`:
+  `not_queueable`, `no_outbox` for a visitor or a host with no member, `queue_full`).
+
+Only a signed-in member has an outbox; it is dropped on sign-out, account switch and
+`AppContext.forget`. `offline.pending()` lists what waits (no bodies), `offline.rejected()` what was
+refused (with its body until the write's max age), `offline.dismiss(writeId)` clears one. The shell
+banner shows "Offline · Pending sync (n)" and "Syncing (n)…" for the app on screen.
+
 ## Visitor vs owner scope — a data-surface cheat-sheet
 
 The currency trap below is just the sharpest edge of one rule: a **visitor / consumer** session reads site

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1406.0",
+  "version": "0.1407.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "964966afc4bcb743188c9fdf21d84de92fb1d9a392e0a48b0644a39a"
+  "falconPackageHash": "b802acb38e0b8d9b19d1d1d61a60d51aff08fee456a640e590e83157"
 }