@wix/himalaya-cli 0.1622.0 → 0.1624.0

package/templates/branded-lite/tier5-src/_shared/access-gates.ts

@@ -0,0 +1,341 @@
+// One App access gates: who may open a tab, decided in the app-level nav worker.
+//
+// A One App owner can lock a page (layout item) for members only, for holders of a badge, or for holders of a
+// paid plan, and choose whether a viewer who may not enter sees a lock screen or no tab at all. The One App
+// evaluates that per viewer on its server (`DisplayCriteria.getLayoutItemContentDisplayInfo`, `EnrichedViewer`)
+// and draws the lock on the client. A migrated Himi app carries the same rules in `access-gates-table.ts`
+// (written by `himi one-app access`) and this module answers them for the viewer.
+//
+// PRESENTATION ONLY. The data behind a gated tab stays protected by its own Wix API (a Visitor's call still
+// gets a 401/403/428). The descriptor is served to every device, so static content in it is not a secret; the
+// One App also sends a gated page's structure to the viewer it denies. This is the rule an owner set on the
+// tab, kept, and nothing stronger.
+//
+// FAIL CLOSED. Every gate starts `pending` (locked, and hidden when it may be hidden) and opens only on
+// positive proof. A read that fails leaves the member locked with the call to action for that rule. The state is
+// declared `notPersisted` and `notHydrated` on the service, so a restored snapshot can never unlock a tab, and a
+// new identity drops every gate back to `pending` before the next answer is read.
+//
+// ONE FLAG PER GATE, bound by the app: the tab bar binds `$service:brandedLiteNav.accessHidden.<key>` (with
+// `hiddenUntilResolved`), and the gated screen's `FragmentSlot` binds `$app:brandedLiteNav.accessState.<key>` (a screen's
+// own worker is not this one, so `$app:` reads the app-level nav worker), with the locked case as its default, so an unresolved value renders the lock and the page body is not mounted.
+//
+// Shared by the two app-level nav workers (`himi-branded-lite-nav`, `himi-branded-lite-header-badges`), which
+// name the same service. With an empty table nothing here reads anything.
+import { hostSessionFromGlobal } from "@himalaya/iap";
+import { activePlanIds } from "@himalaya/checkout";
+import { queryBadgeAssignments } from "@himalaya/wix-badges";
+import { getMyMember } from "@himalaya/wix-members";
+import { listPublicPlans } from "@himalaya/wix-pricing-plans";
+import { ACCESS_GATES } from "./access-gates-table.js";
+
+// ───────────────────────────── the table ─────────────────────────────
+
+/** What the owner required, as the One App stores it on the layout item. */
+export type AccessRule =
+  | { kind: "membersOnly" }
+  | { kind: "badges"; ids: string[] }
+  | { kind: "paidPlans"; ids: string[] };
+
+export interface AccessGate {
+  /** Flag-safe id (`[a-z0-9_]`), the key under `accessState` and `accessHidden`. */
+  key: string;
+  /** The One App layout item the rule was authored on. */
+  layoutItemId: string;
+  /** The Himi screen whose body is gated. */
+  screenId: string;
+  /** The page's title, for the lock screen. */
+  title: string;
+  rule: AccessRule;
+  /** `accessScreenSettings.screenVisible`: `locked` shows a lock screen, `hidden` removes the tab. */
+  mode: "locked" | "hidden";
+  /** `accessScreenSettings.membersOnly`: only a signed-in member may see the lock; a Visitor gets no tab. */
+  hideFromVisitors: boolean;
+  /** The owner's lock message and button label, or "" for the stock copy. */
+  message: string;
+  ctaTitle: string;
+}
+
+/** The lock screen a gated screen shows, and the one `pending` that renders until the first answer lands. */
+export type AccessCase = "pending" | "open" | "signIn" | "plans" | "contact";
+
+export interface AccessOutcome {
+  state: AccessCase;
+  /** The tab should not be listed at all. */
+  hidden: boolean;
+}
+
+/** Everything the rules ask about the viewer. */
+export interface AccessViewer {
+  member: boolean;
+  badgeIds: ReadonlySet<string>;
+  /** Plans the member holds an active order for. */
+  planIds: ReadonlySet<string>;
+  /** Plans the site offers (public, not archived): a lock can only offer a plan that can still be bought. */
+  publicPlanIds: ReadonlySet<string>;
+}
+
+const anyIn = (ids: readonly string[], held: ReadonlySet<string>): boolean => ids.some((id) => held.has(id));
+
+/** The plan ids a gate asks for; none for a rule of another kind. */
+const requiredPlanIds = (gate: AccessGate): readonly string[] => gate.rule.kind === "paidPlans" ? gate.rule.ids : [];
+
+/** Whether a Visitor or a member who may not enter should still see the tab (as a lock). */
+function listed(gate: AccessGate, visitor: boolean): boolean {
+  if (gate.mode === "hidden") return false;
+  return !(visitor && gate.hideFromVisitors);
+}
+
+/**
+ * The One App's rule for one gate. Mirrors `DisplayCriteria.getLayoutItemContentDisplayInfo` and
+ * `EnrichedViewer.filterLayoutItems`:
+ *  - a Visitor is blocked by every rule kind, and always gets the members-only lock (`signIn`);
+ *  - a member holds the badge (one of its ids), holds an active plan (one of its ids), or passes a members-only rule;
+ *  - a blocked member gets the lock for the rule's own kind: a badge asks to contact the business, a plan offers the
+ *    plans, or asks to contact the business when none of its plans is on offer any more (hidden or archived), as the
+ *    One App does (`LayoutItem.ts` `onPermissionZeroPlansClick`).
+ * There is no owner or admin bypass: an owner uses the owner app.
+ */
+export function decide(gate: AccessGate, viewer: AccessViewer): AccessOutcome {
+  if (!viewer.member) return { state: "signIn", hidden: !listed(gate, true) };
+  switch (gate.rule.kind) {
+    case "membersOnly":
+      return { state: "open", hidden: false };
+    case "badges":
+      return anyIn(gate.rule.ids, viewer.badgeIds) ? { state: "open", hidden: false } : { state: "contact", hidden: !listed(gate, false) };
+    case "paidPlans":
+      if (anyIn(gate.rule.ids, viewer.planIds)) return { state: "open", hidden: false };
+      return { state: anyIn(gate.rule.ids, viewer.publicPlanIds) ? "plans" : "contact", hidden: !listed(gate, false) };
+  }
+}
+
+/** Before any answer: locked, and hidden for every gate that some viewer would not see listed. */
+export function pendingOutcome(gate: AccessGate): AccessOutcome {
+  return { state: "pending", hidden: gate.mode === "hidden" || gate.hideFromVisitors };
+}
+
+// ───────────────────────────── the state ─────────────────────────────
+
+export interface AccessGateState {
+  /** `AccessCase` per gate key. Bound by the gated screen's `FragmentSlot`. */
+  accessState: Record<string, AccessCase>;
+  /** True per gate key when the tab is not listed. Bound by the tab bar, fail-closed. */
+  accessHidden: Record<string, boolean>;
+}
+
+export const ACCESS_STATE_KEYS: ("accessState" | "accessHidden")[] = ["accessState", "accessHidden"];
+
+export function pendingAccessState(gates: readonly AccessGate[]): AccessGateState {
+  const accessState: Record<string, AccessCase> = {};
+  const accessHidden: Record<string, boolean> = {};
+  for (const gate of gates) {
+    const outcome = pendingOutcome(gate);
+    accessState[gate.key] = outcome.state;
+    accessHidden[gate.key] = outcome.hidden;
+  }
+  return { accessState, accessHidden };
+}
+
+/** The initial service state: every gate pending. Empty for an app with no gates. */
+export const ACCESS_GATES_INITIAL: AccessGateState = pendingAccessState(ACCESS_GATES);
+
+/** The action signatures a service that uses `accessGates` declares in its `defineService` generic. */
+// A `type` for the same reason as `HeaderBadgeActionSignatures`: `defineService` wants an index signature.
+export type AccessGateActionSignatures<S> = {
+  /** Re-read who the viewer is and what they hold, then re-decide every gate. Only the newest read lands. */
+  refreshAccess: (s: S) => Promise<S>;
+  /** Put every gate back to pending (a new identity), committed at once so nothing stale stays open. */
+  dropAccess: (s: S) => Promise<S>;
+  /** Reserved lifecycle hooks the app-service host delivers to every service that declares them. */
+  onForeground: (s: S) => Promise<S>;
+  onIdentityChange: (s: S) => Promise<S>;
+};
+
+export interface AccessGates<S> {
+  actions: AccessGateActionSignatures<S>;
+  /** Call once after `defineService`: the launch read, and the session clock's notifications. */
+  start(): void;
+}
+
+type Update<S> = (s: S, change: (current: S) => Promise<S>) => Promise<S>;
+type Self = () => { refreshAccess(): Promise<unknown>; dropAccess(): Promise<unknown> };
+
+const sameJson = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b);
+
+/** The plans the site offers: public and not archived (the public list already leaves archived plans out). */
+async function readPublicPlanIds(): Promise<Set<string>> {
+  const res = await listPublicPlans();
+  return new Set((res.plans ?? []).filter((plan) => plan.id && !plan.archived).map((plan) => plan.id));
+}
+
+/** The bridge's refusal of a viewer who is not a member: `HTTP 401` or `HTTP 403` in its rejection text (which a caller
+ *  may prefix). A Visitor gets exactly `403 PERMISSION_DENIED` from `/members/my` (observed live). Any other status
+ *  (a 408, a 429, a 5xx) or a network failure says nothing about who the viewer is, so it must not decide anyone as a Visitor. */
+function isRefusal(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : String(error);
+  const at = text.indexOf("HTTP ");
+  if (at < 0) return false;
+  const status = Number(text.slice(at + 5, at + 8));
+  return status === 401 || status === 403;
+}
+
+/** Most pages of badge assignments one member can need (100 per page). A member past this is not realistic. */
+const MAX_BADGE_PAGES = 20;
+
+/** The badge ids a member holds. A read that cannot finish rejects, so the caller keeps the member locked. */
+async function readBadgeIds(memberId: string): Promise<Set<string>> {
+  const held = new Set<string>();
+  const seen = new Set<string>();
+  let cursor: string | undefined;
+  for (let page = 0; page < MAX_BADGE_PAGES; page++) {
+    // The cursor encodes the filter: a Wix query refuses a filter sent beside a cursor, so only the first page carries it.
+    const res = await queryBadgeAssignments({
+      query: cursor ? { cursorPaging: { limit: 100, cursor } } : { filter: { memberId: { $in: [memberId] } }, cursorPaging: { limit: 100 } },
+    });
+    for (const assignment of res.badgeAssignments ?? []) if (assignment.badgeId) held.add(assignment.badgeId);
+    const next = res.pagingMetadata?.cursors?.next;
+    if (!res.pagingMetadata?.hasNext) return held;
+    // More pages were promised but no cursor to reach them: a truncated answer, not a complete one. It must fail the read (the
+    // member stays locked, or an already-open page stays open) instead of passing a partial set off as everything.
+    if (!next) throw new Error("Badge assignment page said more were available but gave no cursor.");
+    if (seen.has(next)) throw new Error("Badge assignment pagination did not advance.");
+    seen.add(next);
+    cursor = next;
+  }
+  throw new Error("A member holds more badge assignments than one read pages.");
+}
+
+/**
+ * @param gates the app's table (a test passes its own)
+ * @param update serializes state changes for the worker, so overlapping actions build on the preceding result
+ * @param self the worker's own service handle (read lazily: it does not exist yet when this is called)
+ */
+export function accessGates<S extends AccessGateState>(update: Update<S>, self: Self, gates: readonly AccessGate[] = ACCESS_GATES): AccessGates<S> {
+  /** Which read is the newest: an older one that finishes later must not overwrite a newer answer. */
+  let read = 0;
+  /** The host session generation the gates on show were decided under. */
+  let generation = -1;
+  const session = hostSessionFromGlobal();
+  const needsBadges = gates.some((gate) => gate.rule.kind === "badges");
+  const needsPlans = gates.some((gate) => gate.rule.kind === "paidPlans");
+
+  /** The signed-in member's id, `null` for a Visitor, `undefined` when it could not be told (a failed read that is
+   *  not a refusal, such as being offline). A host that fences calls to the member publishes the id with its
+   *  session clock; any other host (web) answers it from the member record, which a Visitor cannot read. */
+  async function memberIdOf(): Promise<string | null | undefined> {
+    if (session.identityBound) {
+      const snapshot = session.current();
+      if (snapshot.kind !== "member") return null;
+      const id = session.identity(snapshot)?.memberId;
+      if (id) return id;
+    }
+    try {
+      return (await getMyMember({ fieldsets: ["PUBLIC"] })).member?.id || null;
+    } catch (error) {
+      return isRefusal(error) ? null : undefined;
+    }
+  }
+
+  const pending = (current: S): S => ({ ...current, ...pendingAccessState(gates) });
+
+  const actions: AccessGateActionSignatures<S> = {
+    refreshAccess: async (s) => {
+      if (!gates.length) return s;
+      const mine = ++read;
+      const startedUnder = session.current().generation;
+      const memberId = await memberIdOf();
+      let badgeIds = new Set<string>();
+      let planIds = new Set<string>();
+      let publicPlanIds = new Set<string>();
+      let badgesFailed = false;
+      let plansFailed = false;
+      if (memberId) {
+        const [badges, plans] = await Promise.all([
+          needsBadges ? readBadgeIds(memberId).catch(() => { badgesFailed = true; return new Set<string>(); }) : Promise.resolve(new Set<string>()),
+          needsPlans ? activePlanIds().then((ids) => new Set(ids)).catch(() => { plansFailed = true; return new Set<string>(); }) : Promise.resolve(new Set<string>()),
+        ]);
+        badgeIds = badges;
+        planIds = plans;
+        // Which plans can still be bought matters only to a member a plan gate blocks: read it then, not for everyone.
+        const required = gates.map(requiredPlanIds);
+        if (plansFailed) {
+          // What the member holds is unknown: offer every required plan, the plans list is the useful action.
+          publicPlanIds = new Set(required.flat());
+        } else if (needsPlans && required.some((ids) => ids.length > 0 && !anyIn(ids, planIds))) {
+          // A read of the offer that fails offers every required plan too, and the plans list reads for itself.
+          publicPlanIds = await readPublicPlanIds().catch(() => new Set(required.flat()));
+        }
+      }
+      const viewer: AccessViewer = { member: memberId !== null && memberId !== undefined, badgeIds, planIds, publicPlanIds };
+      return update(s, async (current) => {
+        // Drop an answer read for another read or another identity: the newer one decides.
+        if (mine !== read || session.current().generation !== startedUnder) return current;
+        // Who the viewer is could not be told: change nothing (pending stays pending, so locked).
+        if (memberId === undefined) return current;
+        const accessState: Record<string, AccessCase> = {};
+        const accessHidden: Record<string, boolean> = {};
+        for (const gate of gates) {
+          const readFailed = (gate.rule.kind === "badges" && badgesFailed) || (gate.rule.kind === "paidPlans" && plansFailed);
+          // A failed read must not lock out a member already shown the page (a blip while offline). Otherwise the
+          // member is treated as not holding the badge or plan: locked, with that rule's call to action.
+          if (readFailed && current.accessState[gate.key] === "open") {
+            accessState[gate.key] = "open";
+            accessHidden[gate.key] = false;
+            continue;
+          }
+          const outcome = decide(gate, viewer);
+          accessState[gate.key] = outcome.state;
+          accessHidden[gate.key] = outcome.hidden;
+        }
+        // Publish only a change: an unchanged answer reaches no view (and costs the worker nothing).
+        if (sameJson(current.accessState, accessState) && sameJson(current.accessHidden, accessHidden)) return current;
+        return { ...current, accessState, accessHidden };
+      });
+    },
+    dropAccess: async (s) => {
+      ++read; // a read already in flight belongs to the previous identity
+      return update(s, async (current) => pending(current));
+    },
+    onForeground: async (s) => update(s, async (current) => current).finally(() => { void self().refreshAccess(); }),
+    onIdentityChange: async (s) => {
+      ++read;
+      const dropped = await update(s, async (current) => pending(current));
+      void self().refreshAccess();
+      return dropped;
+    },
+  };
+
+  /** A session notification: a new generation is a new identity, so the previous one's gates close first. */
+  async function onSession(): Promise<void> {
+    const now = session.current().generation;
+    if (now !== generation) {
+      generation = now;
+      await self().dropAccess();
+    }
+    await self().refreshAccess();
+  }
+
+  return {
+    actions,
+    start(): void {
+      if (!gates.length) return;
+      // Subscribing notifies at once, which is the launch read; a host with no clock needs the explicit one.
+      let notified = false;
+      session.subscribe(() => { notified = true; void onSession(); });
+      if (!notified) void self().refreshAccess();
+    },
+  };
+}
+
+/**
+ * The reserved lifecycle hooks of a service that serves more than one piece (header badges, access gates): the host
+ * calls one `onForeground` and one `onIdentityChange`, so each piece's hook runs in turn.
+ */
+export function chainLifecycle<S>(
+  ...pieces: Array<{ onForeground: (s: S) => Promise<S>; onIdentityChange: (s: S) => Promise<S> }>
+): { onForeground: (s: S) => Promise<S>; onIdentityChange: (s: S) => Promise<S> } {
+  return {
+    onForeground: async (s) => { let next = s; for (const piece of pieces) next = await piece.onForeground(next); return next; },
+    onIdentityChange: async (s) => { let next = s; for (const piece of pieces) next = await piece.onIdentityChange(next); return next; },
+  };
+}

package/templates/branded-lite/tier5-src/himi-branded-lite-access-nav/index.ts

@@ -0,0 +1,45 @@
+// The app-level nav worker (`navigation.navLogicBundle`) of a migrated One App that keeps locked pages: the live counts
+// behind the header's bell, chat and cart buttons (the same piece as `himi-branded-lite-header-badges`), plus the page
+// access gates (members only, badge, paid plan) the source's owner set (`_shared/access-gates.ts`).
+//
+// It is a separate bundle on purpose. The gates read the member, their badges and their plans, which an app that locks
+// no page has no use for, and a worker's source is parsed at every boot. `himi one-app access` points an app's
+// `navLogicBundle` here only when the source locks a page; every other app keeps the badges-only worker, unchanged.
+//
+// The service is named `brandedLiteNav`, like the full worker's, so a top-bar action binds the same
+// `$service:brandedLiteNav.<field>` path and the tab bar and gated screens bind `accessHidden` and `accessState`
+// under it. A scaffold ships this source INERT: nothing loads it until the app's config names it.
+
+import { defineService } from "@himalaya/state";
+import { HEADER_BADGE_KEYS, headerBadges, type HeaderBadgeActionSignatures, type HeaderBadges, type HeaderBadgeState } from "../_shared/header-badges.js";
+import { ACCESS_GATES_INITIAL, ACCESS_STATE_KEYS, accessGates, chainLifecycle, type AccessGateActionSignatures, type AccessGates, type AccessGateState } from "../_shared/access-gates.js";
+
+type State = HeaderBadgeState & AccessGateState;
+
+// State changes await native work; overlapping actions must use the preceding result.
+let stateQueue: Promise<State> | undefined;
+function updateInOrder(s: State, update: (current: State) => Promise<State>): Promise<State> {
+  const previous = stateQueue ?? Promise.resolve(s);
+  const result = previous.then(update);
+  stateQueue = result.catch(() => previous);
+  return result;
+}
+
+const badges: HeaderBadges<State> = headerBadges<State>(updateInOrder, () => svc);
+const access: AccessGates<State> = accessGates<State>(updateInOrder, () => svc);
+
+const svc = defineService<State, HeaderBadgeActionSignatures<State> & AccessGateActionSignatures<State>>("brandedLiteNav", {
+  // Every count unavailable until the first read lands, and no failure to report. Every gate pending (locked).
+  state: { notificationsBadge: null, chatBadge: null, cartBadge: null, errorText: "", ...ACCESS_GATES_INITIAL },
+  // The counts and the gates describe THIS run (see _shared/header-badges.ts, _shared/access-gates.ts): never stored,
+  // never restored, so a snapshot can neither show another day's numbers nor keep a tab open.
+  notPersisted: [...HEADER_BADGE_KEYS, ...ACCESS_STATE_KEYS],
+  notHydrated: [...HEADER_BADGE_KEYS, ...ACCESS_STATE_KEYS],
+  // The host calls one `onForeground` and one `onIdentityChange`: each piece runs in turn.
+  actions: { ...badges.actions, ...access.actions, ...chainLifecycle<State>(badges.actions, access.actions) },
+});
+
+export { svc };
+
+badges.start();
+access.start();