@wix/himalaya-cli 0.1321.0 → 0.1322.0

package/guides/web-page-native-sdk.md

@@ -31,19 +31,30 @@ Your page can only use capabilities the **app owner** turned on for your site. I
 
 - `capabilities` — the capability ids your page will call (see the
   [Web page SDK reference](https://apps.wix.com/_api/himi-serve/docs/web-page-sdk-reference.md) for every id and method).
-- `permissionCopy` — the sentence the phone shows when it asks the user for permission. Write it
-  for the end user, about what *they* get.
+- `permissionCopy` — optional: the sentence the phone shows when it asks the user for permission,
+  at most 500 characters. Write it for the end user, about what *they* get. Only capabilities that
+  prompt need one (Health, camera, photos, location, microphone…); `haptic` and `share` never ask,
+  and a capability left out gets the app's built-in generic sentence.
 - No worker code is needed. Brandy generates the companion worker that answers your page from
-  `capabilities`, allowing every method the capability's page lists — except
+  `capabilities`, allowing **every** method the capability's page lists — except
   `presigned_upload.putFile`, which reads a device file and is allowed only when `files` is enabled
-  too. (An owner who wants a
-  narrower allowlist can still name their own worker in `bundle`.)
+  too. So enabling a capability is enough; the owner does not list methods.
 - Enabling a capability changes the app's native permissions, so the owner ships a **new app
   build** with it before your page can call it. Until then the call times out.
 
-When you hand work to the app owner, give them the list as `capability.method` pairs, for example
-`health.availability`, `health.requestPermission`, `health.query`, `haptic.play`. A method that is
-not on the allowlist never answers — your call times out (see *Errors*).
+**You cannot enable anything from the page, or with any public command.** The app owner is
+whoever builds the app (for an app Wix builds for a customer, the team that ships it). Hand them a
+request they can act on without asking you anything back — for example:
+
+> Please enable these web page capabilities for `https://www.example.com` in the app's `webSdk`
+> provisioning and ship a new build: `["health", "haptic", "share"]`, with
+> `permissionCopy.health` = "Show your step count for today." The page checks what is enabled and
+> hides the rest, so it is safe to ship before the build.
+
+An owner who wrote their own companion worker (named in `webSdk.bundle`) chooses methods one by
+one: for that app only, add the exact `capability.method` pairs your page calls, for example
+`health.availability`, `health.requestPermission`, `health.query`, `haptic.play`. A method that
+worker does not allow never answers — your call times out (see *Errors*).
 
 Your page must be served from the site origin the app was built for. Pages in iframes, and pages
 reached through a redirect to another origin, do not get the bridge.
@@ -100,7 +111,12 @@ export function isInHimiApp(): boolean {
   return bridge() !== undefined;
 }
 
-/** Call one native method, e.g. call("health", "query", [{ type: "steps", from, to }]). */
+/**
+ * Call one native method, e.g. call("health", "query", [{ type: "steps", from, to }]).
+ * A call that shows native UI (a permission prompt, the share sheet) answers only when the user is
+ * done: give it a long timeoutMs, such as 120_000. Never wait without a deadline — a message the app
+ * drops (see "Keep what you send small") gets no answer at all.
+ */
 export function call<T = unknown>(capability: string, method: string, args: unknown[] = [], timeoutMs = 30_000): Promise<T> {
   const target = bridge();
   if (!target) return Promise.reject(new HimalayaError("Not running inside a Himi app", "not_in_app"));
@@ -119,8 +135,86 @@ export function call<T = unknown>(capability: string, method: string, args: unkn
   });
 }
 
-/** True when `capability.method` answers within `timeoutMs`. Use a read-only method. */
-export async function isEnabled(capability: string, method: string, args: unknown[] = [], timeoutMs = 3_000): Promise<boolean> {
+let manifest: { on: Bridge; list: Record<string, string[]> } | undefined;
+
+let asking: { on: Bridge; until: number; answer: Promise<Record<string, string[]> | null> } | undefined;
+
+/**
+ * ONE question loop per bridge, however many callers wait on it: every message counts against the
+ * app's rate limit, so twenty gated controls must not ask twenty times a second. It asks every
+ * half second until the latest caller's deadline (a message sent before the app is ready is lost);
+ * each question listens for 2 s, so a slow answer still lands and at most four are in flight.
+ */
+function askShared(target: Bridge, budget: number): Promise<Record<string, string[]> | null> {
+  const until = Date.now() + budget;
+  if (asking?.on === target) {
+    asking.until = Math.max(asking.until, until);
+    return asking.answer;
+  }
+  const state = { on: target, until, answer: Promise.resolve<Record<string, string[]> | null>(null) };
+  asking = state; // before the first ask: a loop that ends at once must clear itself
+  state.answer = new Promise((resolve) => {
+    let done = false;
+    const finish = (list: Record<string, string[]> | null) => {
+      if (done) return;
+      done = true;
+      clearInterval(again);
+      if (asking === state) asking = undefined;
+      if (list) manifest = { on: target, list };
+      resolve(list);
+    };
+    const ask = () => {
+      if (done) return;
+      const left = state.until - Date.now();
+      if (left <= 0 || bridge() !== target) return finish(null); // deadline, or the page's bridge changed
+      call<{ capabilities?: Record<string, string[]> }>("himalaya", "capabilities", [], Math.max(1, Math.min(2_000, left))).then(
+        (reply) => finish(reply?.capabilities ?? null),
+        // A timed-out question is not an answer; the deadline decides. Anything else is final.
+        (error) => { if (!(error instanceof HimalayaError && error.code === "timeout")) finish(null); },
+      );
+    };
+    const again = setInterval(ask, 500);
+    ask();
+  });
+  return state.answer;
+}
+
+/**
+ * What this app lets the page call, as { capability: [method, …] }. null outside the app, in an app
+ * build older than this question, or when nothing answered within timeoutMs. A list is remembered
+ * (and returned at once, whatever timeoutMs); a miss is not, because an app that is still starting
+ * drops the first messages.
+ */
+export async function enabledCapabilities(timeoutMs = 3_000): Promise<Record<string, string[]> | null> {
+  const target = bridge();
+  if (!target) return null;
+  if (manifest?.on === target) return manifest.list;
+  if (!(timeoutMs > 0)) return null; // no time to ask: nothing can answer
+  // setTimeout cannot wait longer than 2^31-1 ms (a longer delay fires at once), so clamp it.
+  const budget = Math.min(timeoutMs, 2_147_483_647);
+  const answer = askShared(target, budget);
+  // This caller's own deadline; the shared question may keep going for a caller who waits longer.
+  return new Promise((resolve) => {
+    const stop = setTimeout(() => resolve(manifest?.on === target ? manifest.list : null), budget);
+    void answer.then((list) => { clearTimeout(stop); resolve(list); });
+  });
+}
+
+/**
+ * True when the app lets the page call `capability.method`, read from enabledCapabilities(): nothing
+ * is called and nothing happens on the phone. false when there is no list (outside the app, an app
+ * build older than the list, or no answer yet).
+ */
+export async function isEnabled(capability: string, method: string, timeoutMs = 3_000): Promise<boolean> {
+  const enabled = await enabledCapabilities(timeoutMs);
+  return enabled?.[capability]?.includes(method) ?? false;
+}
+
+/**
+ * For an app build older than enabledCapabilities(): CALL `capability.method` and report whether the
+ * app answered it (even with an error). It runs the method, so pass only a read-only one.
+ */
+export async function probe(capability: string, method: string, args: unknown[] = [], timeoutMs = 3_000): Promise<boolean> {
   try {
     await call(capability, method, args, timeoutMs);
     return true;
@@ -154,15 +248,15 @@ Capability ids are snake_case (`health`, `haptic`, `secure_storage`, `local_data
 names are exactly the SDK's function names. Arguments and results are plain JSON.
 
 ```ts
-import { himalaya, HimalayaError } from "./lib/himalaya";
+import { call, himalaya, HimalayaError } from "./lib/himalaya";
 
 // Light, fire-and-forget feedback.
 await himalaya.haptic.play("success");
 
-// Health: check, ask (from a button tap), then read.
+// Health: check, ask (from a button tap), then read. The prompt waits for the user: allow two minutes.
 const { available } = await himalaya.health.availability();
 if (available) {
-  await himalaya.health.requestPermission({ read: ["steps"] });
+  await call("health", "requestPermission", [{ read: ["steps"] }], 120_000);
   const midnight = new Date();
   midnight.setHours(0, 0, 0, 0);
   const { samples } = await himalaya.health.query({
@@ -174,13 +268,21 @@ if (available) {
 ```
 
 `call("health", "availability")` is the same thing without the proxy, and is handy when the
-capability or method name is a variable.
+capability or method name is a variable — or when you need a timeout other than the 30-second
+default. **Give every call that shows native UI a long deadline** — `call(..., 120_000)` for a
+permission prompt, the share sheet, the camera or a photo picker: it answers when the user is
+done, and the 30-second default can turn a slow user into a `timeout` your page reads as "not
+enabled". Keep a deadline even there: a message the app drops gets no answer at all.
+
+`steps`, `activeEnergy` and `distance` come back summed (one sample for the whole range, or one
+per `bucket: "hour" | "day"`), and `heartRate` averaged; summing `samples` for a total is right
+either way.
 
 ## Step 3 — React pattern
 
 ```tsx
 import { useEffect, useState } from "react";
-import { call, himalaya, isInHimiApp, HimalayaError } from "./lib/himalaya";
+import { call, himalaya, isEnabled, isInHimiApp, HimalayaError } from "./lib/himalaya";
 
 export function StepsCard() {
   const [state, setState] = useState<"checking" | "browser" | "off" | "ready" | "denied" | "failed">("checking");
@@ -188,8 +290,10 @@ export function StepsCard() {
 
   useEffect(() => {
     if (!isInHimiApp()) return setState("browser");
-    // Answering is not enough: a phone without a health store answers { available: false }.
-    call<{ available: boolean }>("health", "availability", [], 3_000)
+    // Enabled for this site? Answered from the app's list, without calling anything.
+    isEnabled("health", "availability")
+      .then((on) => (on ? call<{ available: boolean }>("health", "availability", [], 3_000) : { available: false }))
+      // Enabled is not enough: a phone without a health store answers { available: false }.
       .then(({ available }) => setState(available ? "ready" : "off"))
       // Not enabled for this site (timeout) hides the feature; any other failure offers a retry.
       .catch((error) => setState(error instanceof HimalayaError && error.code === "timeout" ? "off" : "failed"));
@@ -197,7 +301,7 @@ export function StepsCard() {
 
   async function connect() {
     try {
-      await himalaya.health.requestPermission({ read: ["steps"] });
+      await call("health", "requestPermission", [{ read: ["steps"] }], 120_000); // waits for the user
       const from = new Date(); from.setHours(0, 0, 0, 0);
       const { samples } = await himalaya.health.query({ type: "steps", from: from.toISOString(), to: new Date().toISOString() });
       setSteps(samples.reduce((sum: number, s: { value: number }) => sum + s.value, 0));
@@ -232,9 +336,21 @@ The same page must keep working in an ordinary browser (and in Base44 / Lovable
   device (`availability()` tells you). Show a calm fallback, not an error. On iOS a denied Health
   **read** is not reported as `not_authorized`: the read succeeds with no samples, exactly like a
   day with no data. Word an empty result so it also covers "access is off".
-- **Hide features the app doesn't enable.** Probe once with `isEnabled(...)` on a read-only method
-  and hide the UI when it is `false`. `true` only means the method is enabled — still read its
-  answer (`availability()` can say `{ available: false }`).
+- **Hide features the app doesn't enable.** Check with `isEnabled(capability, method)` and hide the
+  UI when it is `false`. The app answers from its list of enabled capabilities
+  (`enabledCapabilities()`), so nothing is called and nothing happens on the phone — this works
+  for `haptic.play` too. An app build older than that list has none, so `isEnabled` answers
+  `false` there. To support such a build, fall back to `probe(capability, method)`, which **calls**
+  the method — use it only with a read-only one (`health.availability`, never `haptic.play`).
+  `true` only means the method is enabled — still read its answer (`availability()` can say
+  `{ available: false }`).
+- **Ask for a permission once, then trust the result you read.** `health.requestPermission`
+  resolves with `{ granted }`, but on iOS a read type counts as granted once asked, whatever the
+  user chose — so read the data and treat an empty result as "no data or access off". The phone
+  shows each permission prompt once; asking again answers without showing anything.
+- **Check for the app when you need it.** In current app builds the bridge exists before your
+  first script runs. On an older Android System WebView it is added as the page loads, so call
+  `isInHimiApp()` where you use it (for example in `useEffect`), not once at module load.
 - **Plain JSON only.** Arguments and results cross as JSON: no functions, `Date` objects (use ISO
   strings), `Blob`s or class instances.
 - **Keep what you send small.** The app checks every message a page sends and silently drops one
@@ -258,7 +374,7 @@ Every failure rejects with a `HimalayaError` that has a `code`:
 | `code` | Meaning | What to do |
 |---|---|---|
 | `not_in_app` | Ordinary browser or preview, no bridge | Render the browser fallback |
-| `timeout` | No answer: capability or method not enabled for this site, not on this app build, or the message broke a size rule (see *Keep what you send small*) | Check your arguments; otherwise hide the feature and ask the app owner to enable `capability.method` |
+| `timeout` | No answer within `timeoutMs`: capability or method not enabled for this site, not on this app build, or the message broke a size rule (see *Keep what you send small*). A call that shows native UI can also time out while the user is still looking at it — give it a long `timeoutMs` (`120_000`) | Check your arguments; otherwise hide the feature and ask the app owner to enable the capability |
 | `bridge_refused` | The app's bridge refused the message outright | Retry later; send less often |
 | `not_authorized` | The user denied permission | Explain how to enable it in Settings |
 | `unavailable` | Not supported on this device | Hide the feature |
@@ -275,6 +391,8 @@ Codes other than the first three come from the capability itself; its reference
 
   ```ts
   const answers: Record<string, unknown> = {
+    // What the app answers when the page asks which capabilities it may call.
+    "himalaya.capabilities": { v: 1, capabilities: { health: ["availability", "query", "requestPermission"], haptic: ["play"] } },
     "health.availability": { available: true },
     "health.requestPermission": undefined,
     "health.query": { samples: [{ value: 4200 }] },
@@ -289,21 +407,24 @@ Codes other than the first three come from the capability itself; its reference
 
   Never ship the fake: a page that defines `HimalayaWorker` itself is lying to its own feature
   checks.
-- **On a phone** — open the page inside the app build the owner configured. Check each feature
-  once with permission granted and once denied.
+- **On a phone** — there is no public preview app that carries your site's capabilities: ask the
+  app owner for an installable test build of the app with your capabilities enabled, open your
+  page inside it, and check each feature once with permission granted and once denied. Until then,
+  the fake bridge above is the test.
 
 ## More recipes
 
 Each uses the client from Step 1. The exact types are on each capability's page (see *Reference*).
 
 ```ts
-import { himalaya, HimalayaError } from "./lib/himalaya";
+import { call, himalaya } from "./lib/himalaya";
 
-// Share a link through the phone's share sheet (from a tap).
-const { completed } = await himalaya.share.share({ text: "Join me on Friday", url: "https://example.com/e/42" });
+// Share a link through the phone's share sheet (from a tap). The sheet waits for the user: allow two minutes.
+// Outside the app, fall back to the browser's own share (or copy the link).
+const { completed } = await call<{ completed: boolean }>("share", "share", [{ text: "Join me on Friday", url: "https://example.com/e/42" }], 120_000);
 
 // Where am I? Ask first, then read once. getCurrent answers null when no fix arrives in time.
-const status = await himalaya.location.requestPermission();
+const status = await call("location", "requestPermission", [], 120_000);
 if (status === "granted") {
   const here = await himalaya.location.getCurrent({ timeoutMs: 10_000 });
   if (here) console.log(here.lat, here.lng, `±${here.accuracy}m`);
@@ -315,7 +436,7 @@ const saved = await himalaya.secure_storage.read("refresh-token"); // string | n
 
 // Scan a QR code with the camera (iOS). null when the user cancels — and always on Android,
 // which has no built-in QR decoder — so keep a way to type the code in.
-const code = (await himalaya.camera.scanQR()) ?? window.prompt("Enter the code");
+const code = (await call<string | null>("camera", "scanQR", [], 120_000)) ?? window.prompt("Enter the code");
 ```
 
 **Files arrive as handles.** Methods that return a photo, recording or file give you a
@@ -324,15 +445,15 @@ You cannot put it in an `<img>` directly. Hand it to another call that takes one
 save it to the photo library:
 
 ```ts
-const [photo] = await himalaya.photos.pick({ limit: 1 });
-if (photo) await himalaya.share.share({ files: [photo] });
+const [photo] = await call<any[]>("photos", "pick", [{ limit: 1 }], 120_000);
+if (photo) await call("share", "share", [{ files: [photo] }], 120_000);
 ```
 
 To get the bytes into the page, read them with the `files` capability (the app owner must enable
 it too). `files.readBase64` returns the contents as base64, up to 8 MiB:
 
 ```ts
-const [photo] = await himalaya.photos.pick({ limit: 1 });
+const [photo] = await call<any[]>("photos", "pick", [{ limit: 1 }], 120_000);
 if (photo) {
   const base64 = await himalaya.files.readBase64(photo);
   const img = document.createElement("img");

package/guides/webview-page-sdk.md

@@ -70,6 +70,17 @@ logicBundle: {
 }
 ```
 
+Every worker built on `exposeCapabilitiesToPage` also answers the page's handshake,
+`call("himalaya", "capabilities")`, with exactly the allowlist it was given
+(`{ v: 1, capabilities: { health: ["availability", …] } }`); the page client's
+`enabledCapabilities()` and `isEnabled()` (in both the pasted guide client and
+`@wix/himalaya/webview-page`) read it, so a page hides what is off without calling a method or
+waiting out a timeout. They share one question per page, re-asked every 0.5 s until answered or the latest caller's deadline (at most two messages a second, however many controls check), since a worker that is still
+booting drops the first messages. `isEnabled()` never calls the method: with no list (an app built
+before the handshake) it answers `false`, and a page that must support such a build calls
+`probe()` — which does call the method — with a read-only one. `himalaya` is reserved: exposing a capability under that name
+throws.
+
 Do not build one worker that imports every SDK. Static bundle scanning would correctly conclude
 that the release uses every capability, forcing unrelated permissions and native modules into the
 binary. One app-specific worker imports exactly the app’s selected subset.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1321.0",
+  "version": "0.1322.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": "3318113ec10ae018bbbe09e99bb3bef1207460516f9ca12d20e128ff"
+  "falconPackageHash": "bb7cc4c5d0d0841cd11950b890b11f51d812396f8f4a0649727b0501"
 }