@wix/himalaya-cli 0.1475.0 → 0.1476.0

package/guides/recipe-four-state.md

@@ -3,8 +3,9 @@
 **The rule every recipe follows:** a screen that loads or writes data shows a
 **loading state**, a **classified error state**, and a **recovery action where the
 user can fix the failure** — retry for an offline or a server failure, and for a failed
-write; Sign in when the user is signed out; nothing for a permission failure, an empty result
-or a field error, where the same request gives the same answer. This recipe is the shared
+write; Sign in when the user is signed out; the site's join flow for a non-member when
+available; nothing for a permission failure, an empty result or a field error, where the same
+request gives the same answer. This recipe is the shared
 idiom; the other recipes link here for it. Design guidance for the states:
 `himi docs designing-himi-screens` §5 ("Loading states", "Error states").
 
@@ -22,7 +23,7 @@ more than half model error, and the reference apps (`apps/himi-owner-lite`,
 ## 1. One status field, a classified error, derived flags
 
 ```ts
-type ErrorKind = "" | "offline" | "server" | "signIn" | "permission";
+type ErrorKind = "" | "offline" | "server" | "signIn" | "membership" | "permission";
 
 interface State {
   status: "loading" | "ready" | "error";
@@ -34,6 +35,7 @@ interface State {
   hideOfflineError: boolean; // one EmptyState per error class …
   hideServerError: boolean;
   hideSignInError: boolean;
+  hideMembershipError: boolean;
   hidePermissionError: boolean;
   hideRefreshError: boolean; // … and a Banner when a refresh fails over rows we kept
 }
@@ -50,6 +52,7 @@ function shape(s: Partial<State>): State {
     hideOfflineError: !(blank && errorKind === "offline"),
     hideServerError: !(blank && errorKind === "server"),
     hideSignInError: !(blank && errorKind === "signIn"),
+    hideMembershipError: !(blank && errorKind === "membership"),
     hidePermissionError: !(blank && errorKind === "permission"),
     // Only a failure a retry can fix gets the banner over kept rows.
     hideRefreshError: !(!blank && (errorKind === "offline" || errorKind === "server")),
@@ -66,31 +69,49 @@ const TRANSPORT = /NSURLErrorDomain|(?:UnknownHost|Connect|SocketTimeout|NoRoute
 // A pinned site with no member session: iOS `siteNotPermitted(requested: "account", …)`,
 // Android `site account is not the bound site …`.
 const SIGNED_OUT = /wixApi not enabled|session unavailable|PRINCIPAL_CHANGED|not signed in|siteNotPermitted\(requested: "account"|site account is not the bound site/i;
+// The account is not a member of this site: iOS `NotSiteMember(metaSiteId: …)`,
+// Android `not a member of site …`. NOT `WDE0027` — that is Wix Data's generic
+// permission refusal, which a signed-in member and a visitor both get.
+const NOT_MEMBER = /\bNotSiteMember\b|\bnot a member of site\b/i;
 
-function classifyError(e: unknown): ErrorKind {
+function classifyError(e: unknown, authState: "signedIn" | "signedOut" | "unknown" = "unknown"): ErrorKind {
   const msg = String((e as Error)?.message ?? e ?? "");
-  const code = String((e as { code?: unknown })?.code ?? "");
+  // Some bridges put the Wix code in the response body rather than Error.code.
+  const code = String((e as { code?: unknown })?.code ?? /"(?:code|error)"\s*:\s*"([^"]+)"/.exec(msg)?.[1] ?? "");
   const status = Number(STATUS.exec(msg)?.[1] ?? 0);
-  if (status === 401) return "signIn";        // signed out (or the session expired)
-  if (status === 403) return "permission";    // signed in, without access
-  if (SIGNED_OUT.test(msg)) return "signIn";
+  if (code === "AccountSessionExpired" || code === "webwix_account_signed_out" || SIGNED_OUT.test(msg)) return "signIn";
+  if (code === "NotSiteMember" || NOT_MEMBER.test(msg)) return "membership";
+  // A 401 is a missing or expired session — unless the host knows the user is signed
+  // in, when it is a policy refusal. Never "server": a retry sends the same 401 back.
+  if (status === 401) return authState === "signedIn" ? "permission" : "signIn";
+  // A 403 is a missing permission — but a visitor the host knows is signed out gets
+  // `403 WDE0027` on member-only data too, and signing in is what fixes that.
+  if (status === 403) return authState === "signedOut" ? "signIn" : "permission";
   if (code === "offline_write_blocked") return "offline";   // a write refused before it left
   // A web call that never reached Wix arrives as
   // `HTTP 502: {"error":"webwix_direct_failed","detail":"Failed to fetch"}` — judge its detail.
-  if (status && !msg.includes("webwix_direct_failed")) return "server";
-  if (TRANSPORT.test(msg)) return "offline";
+  // The top-level 502 is the bridge wrapper, not the underlying transport result.
+  const detail = msg.includes("webwix_direct_failed")
+    ? /"detail"\s*:\s*"([^"]+)"/.exec(msg)?.[1] ?? msg
+    : msg;
+  if (status && detail === msg) return "server";
+  if (TRANSPORT.test(detail)) return "offline";
   return "server";   // anything else — a bug, a malformed row — is not the user's connection
 }
 
+// App-specific host integration. If the host does not expose auth state here,
+// keep "unknown": a 401 then shows Sign in, which is what a session that ended needs.
+function currentAuthState(): "signedIn" | "signedOut" | "unknown" { return "unknown"; }
+
 async function load(s: State): Promise<State> {
   try {
     const items = (await fetchRows()).map(normalize);
     return shape({ status: "ready", items });
   } catch (e) {
-    const errorKind = classifyError(e);
+    const errorKind = classifyError(e, currentAuthState()); // use host/session state when available
     // Keep the rows: a refresh that fails must not blank a screen that had content —
     // unless access is gone, when the rows must not stay on screen either.
-    const lostAccess = errorKind === "signIn" || errorKind === "permission";
+    const lostAccess = errorKind === "signIn" || errorKind === "membership" || errorKind === "permission";
     return shape({ ...s, items: lostAccess ? [] : s.items, status: "error", errorKind });
   }
 }
@@ -140,9 +161,16 @@ only when the screen shows the user something different for it.
   "body": { "package": "himalaya", "type": "EmptyState",
     "props": { "title": "Sign in to view products",
                "subtitle": "Your session has ended.",
-               "action": { "actionId": "tier5.products.signIn" },   // a worker action that dispatches himi.wix.signInDirect
+               "action": { "actionId": "tier5.products.openSignIn" },
                "actionLabel": "Sign in" } },
   "modifiers": { "hiddenPath": "$service:products.hideSignInError" } },
+{ "id": "error.membership",
+  "body": { "package": "himalaya", "type": "EmptyState",
+    "props": { "title": "Join this site to view products",
+               "subtitle": "Use this site's join flow, or ask the owner for access.",
+               "action": { "actionId": "tier5.products.openJoin" },
+               "actionLabel": "Join this site" } },
+  "modifiers": { "hiddenPath": "$service:products.hideMembershipError" } },
 { "id": "error.permission",           // no action: retrying gives the same answer
   "body": { "package": "himalaya", "type": "EmptyState",
     "props": { "title": "You need permission to view this screen",
@@ -164,10 +192,21 @@ only when the screen shows the user something different for it.
   the binding reads without negation.
 - Ready state is simply the data itself (the list rows, the detail fields) — it
   needs no dedicated marker.
-- **Sign in is a worker action.** A renderer cannot dispatch `himi.wix.*`, so the
-  sign-in `EmptyState` calls `tier5.products.signIn`, which the worker defines:
-  it dispatches `himi.wix.signInDirect` and then reloads
-  (`himi docs wix-login-integration`).
+- **Sign in uses a real auth flow.** A renderer cannot dispatch `himi.wix.*`, so
+  the sign-in `EmptyState` calls an app action that opens its configured auth gate
+  or sign-in screen, then reloads after authentication. Do not dispatch
+  `himi.wix.signInDirect` from this button: it requires the email and password
+  collected by a credential form (`himi docs wix-login-integration`).
+- **Membership is not sign-in.** `NotSiteMember` (Android: `not a member of
+  site`) means the account must join this site. Route it to the membership state;
+  wire its action to the app's join/registration UI, or omit the action when no
+  such flow exists. A `403 WDE0027` is NOT membership: Wix Data returns it to a
+  signed-in member without access too, so it stays a permission error.
+- **A 403 is a permission error** — the user lacks access and signing in again
+  changes nothing — unless the host's auth state says the user is signed out: a
+  visitor gets `403 WDE0027` on member-only data, and signing in fixes it. A 401 is
+  the session that ended — unless the host says the user is signed in, when it is a
+  permission refusal.
 - **Loading is a `Skeleton` shaped like the loaded content** when you know the
   layout — the same rows at about the same size. `StatefulSection` or
   `ActivityIndicator` are fine where they fit better. A plain `"Loading…"` `Text`
@@ -194,7 +233,7 @@ only when the screen shows the user something different for it.
 | loading | initial state (`status: "loading"`) | content-shaped skeleton; NO retry |
 | error, nothing on screen | `catch` in the first load | the class's `EmptyState`: user-facing copy + a recovery action where one exists |
 | error, rows on screen | `catch` in a refresh (offline or server) | rows stay; a `Banner` with **Try again** above them |
-| sign-in or permission | `catch` in any load | rows go; the class's `EmptyState` (Sign in, or no action) |
+| sign-in, membership or permission | `catch` in any load | rows go; the class's `EmptyState` (auth flow, join flow, or no action) |
 | empty | derived: ready + 0 rows | say what *would* fill it, and how |
 | ready | successful fetch | the content |
 
@@ -227,9 +266,10 @@ only when the screen shows the user something different for it.
   (`dev/net-mocks.json`, CMS seed rows). `himi render <screenId> --no-mocks` shows
   the initial frame — the loading state — and
   `--state '{"products":{"status":"error","errorKind":"offline","hideOfflineError":false,…}}'`
-  forces an error class without the network. A `dev/net-mocks.json` rule that
-  answers 401, 403 or 500 previews the sign-in, permission and server classes
-  through the real `classifyError`.
+  forces an error class without the network. A `dev/net-mocks.json` rule reaches
+  the worker only as `Wix <status> for …` — the hermetic crawl drops the response
+  body — so a 401, 403 or 500 rule previews the sign-in, permission and server
+  classes. Preview the membership class with `--state`.
 
 ## See also
 

package/guides/recipe-search.md

@@ -66,7 +66,7 @@ not say why there are no rows.
 | Results | Matching rows, result count, and the available sort/filter controls. |
 | No matches | An `EmptyState` explaining that the current query or filters found nothing; offer a way to adjust them, and Clear only where the field is controlled (the native slot) — the inline `SearchField` is uncontrolled, so Clear there empties the query but not the field. |
 | Empty catalog | Explain that the catalog itself has no items yet, independent of the query; provide a useful browse/back action. |
-| Error | Classified as in `himi docs recipe-four-state`: an icon-less `EmptyState` per class with user-facing copy, Try again only for offline and server, Sign in for sign-in, no action for permission. Retain the query and controls, and keep it distinct from no matches. |
+| Error | Classified as in `himi docs recipe-four-state`: an icon-less `EmptyState` per class with user-facing copy, Try again only for offline and server, the app's auth flow for sign-in, the site's join flow for `NotSiteMember`, and no action for permission. Retain the query and controls, and keep it distinct from no matches. |
 
 ### Native slot and old-client fallback
 
@@ -172,9 +172,9 @@ interface PostsState {
   query: string;
   hideNoPosts: boolean;  // the EmptyState for "loaded, and there is nothing at all"
   hideNoMatches: boolean; // the EmptyState for "there are posts, none match the query"
-  errorKind: "" | "offline" | "server" | "signIn" | "permission";  // classifyError(e)
+  errorKind: "" | "offline" | "server" | "signIn" | "membership" | "permission";  // classifyError(e, currentAuthState())
   hideLoading: boolean; hideOfflineError: boolean; hideServerError: boolean;
-  hideSignInError: boolean; hidePermissionError: boolean;
+  hideSignInError: boolean; hideMembershipError: boolean; hidePermissionError: boolean;
   hideRefreshError: boolean;                    // hiddenPath flags, as in recipe-four-state
 }
 
@@ -219,7 +219,7 @@ clear: (s) => { currentQuery = ""; return shape({ ...s, query: "", items: s.all
 ```
 
 - `load()` fetches once, fills `all`, and sets `items = visible(all, currentQuery)`.
-  On a `signIn` or `permission` failure it clears **`all` as well as `items`** —
+  On a `signIn`, `membership` or `permission` failure it clears **`all` as well as `items`** —
   `search`, `clear` and `retry` rebuild rows from `all`, so rows left there come
   back on the next keystroke.
 - The shipped Blog v3 `WixPost` type includes `categoryIds` and both Wix-image and
@@ -261,8 +261,11 @@ A searchable list loads data, so it carries the four states of
   while the first `load()` runs. The search field is usable at once.
 - **Error, nothing loaded** — one `EmptyState` per class `classifyError` can
   return, **no icon**, user-facing copy; offline and server get **Try again** →
-  `tier5.posts.retry`, sign-in gets **Sign in**, permission gets no action. The
-  `catch` sets `errorKind` from `classifyError(e)`; it never shows `e.message`.
+  `tier5.posts.retry`, sign-in opens the app's configured auth flow, `NotSiteMember`
+  opens the site's join flow when the app provides one, and permission gets no
+  action. The `catch` sets `errorKind` from `classifyError(e, currentAuthState())`
+  (both from `himi docs recipe-four-state`); it never
+  shows `e.message`.
 - **Retry keeps the query.** `retry` re-runs `load()` and then re-applies
   `currentQuery` — not `s.query`, which is the query from when the retry
   STARTED — so what the user typed during the fetch is not lost.
@@ -273,7 +276,8 @@ A searchable list loads data, so it carries the four states of
 retry: async (s) => {
   const next = await load(s);                            // classified on failure
   // Lost access clears the rows; any other failure keeps them for the Banner.
-  const lostAccess = next.errorKind === "signIn" || next.errorKind === "permission";
+  const lostAccess = next.errorKind === "signIn" || next.errorKind === "membership"
+    || next.errorKind === "permission";
   const all = lostAccess ? [] : next.all;
   return shape({ ...next, all, query: currentQuery, items: visible(all, currentQuery) });
 },

package/guides/tier-5-add-a-screen.md

@@ -112,10 +112,16 @@ The first arg after `state` is the action's payload object: the descriptor's `Ac
 | `Rating` | `onChange` | `{ value }` — the 1-based star index |
 | `ColorPicker` | `onChange` | `{ value }` — the hex string |
 | `DatePicker` | `onChange` | `{ value }` — unix **seconds**, string-encoded |
-| `OtpInput` | `onChange`, `onComplete` | `{ value }` — the assembled code (dispatched on React Native today; the other renderers show the boxes read-only) |
-| `ChipsInput` | `onRemove` | `{ value }` — the removed chip |
+| `OtpInput` | `onChange`, `onComplete` | `{ value }` — the assembled code: `onChange` on every edit, `onComplete` once, on the edit that fills the last box |
+| `ChipsInput` | `onAdd`, `onRemove` | `{ value }` — the new token (trimmed; committed by Return or a comma, and the field clears) / the removed chip. Append the token to `valuesPath` to show it |
 | `Button` / `ListItem` | `action` / `onTap` | exactly the descriptor's `params` (no injected value) |
 
+For a controlled `OtpInput`, bind `valuePath` and have `onChange` store `payload.value` in that
+bound field. An `onComplete` reducer can then clear it to empty the boxes. Service subscriptions
+report **changes**: returning an already-empty bound field without first storing the user's edit
+is a no-op and does not reset the local input. A completion-only input can omit `valuePath` and
+submit the assembled code directly from `payload.value`.
+
 The payload rides in **`args`**. Some arms also mirror it into `params`; that is permitted only
 for string-encoded values, because `Action.params` is `map<string,string>` in the proto. Every
 host merges `{...params, ...args}` (args winning) before invoking the reducer, so a worker sees

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1475.0",
+  "version": "0.1476.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": "224e56d2071ce0050cf65a861313895b2147862685f52d1f6b8abd95"
+  "falconPackageHash": "ca87854bfed096bc30428a79c429e7d947beb42046c8ac0d46dd613b"
 }