@wix/himalaya-cli 0.1296.0 → 0.1298.0

package/guides/index.json

@@ -95,6 +95,18 @@
       "category": "Workers & SDKs",
       "file": "webview-page-sdk.md"
     },
+    {
+      "id": "web-page-native-sdk",
+      "title": "Call native device features from a web page inside a Himi app",
+      "category": "Workers & SDKs",
+      "file": "web-page-native-sdk.md"
+    },
+    {
+      "id": "web-page-sdk-reference",
+      "title": "Web page SDK reference",
+      "category": "Workers & SDKs",
+      "file": "web-page-sdk-reference.md"
+    },
     {
       "id": "component-reference",
       "title": "Component reference",

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

@@ -0,0 +1,286 @@
+# Call native device features from a web page inside a Himi app
+
+This guide is for anyone — a person or a coding agent such as Base44, Lovable or Claude — building
+a web page (React or plain JavaScript) that will be shown **inside** a Himi mobile app, such as a
+Brandy app that wraps a website. From that page you can call the phone's native features: Health
+(HealthKit / Health Connect), haptics, camera, share, location, secure storage and more.
+
+You do **not** install any package. The app injects a small bridge into your page; you paste one
+file (below) that talks to it.
+
+```
+your page → window.HimalayaWorker → the app's companion worker → native iOS / Android
+```
+
+## Before you start: what the app owner must enable
+
+Your page can only use capabilities the **app owner** turned on for your site. In a Brandy app
+that is the `webSdk` block of the app's provisioning file:
+
+```json
+{
+  "webSdk": {
+    "bundle": "my-site-capabilities",
+    "capabilities": ["health", "haptic"],
+    "permissionCopy": {
+      "health": "Show your daily steps and save the workouts you finish."
+    }
+  }
+}
+```
+
+- `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.
+- `bundle` — the app's companion worker, which allowlists exactly which methods your page may
+  call. A health-only site can omit it; any other set needs one.
+
+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*).
+
+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.
+
+## Step 1 — add the client file
+
+Create `src/lib/himalaya.ts` with exactly this content. It has no dependencies and works with
+React, Vue, Svelte or plain JavaScript callers. It is TypeScript: Vite-based projects (including
+Lovable and Base44) compile it as is; a project with no TypeScript build step needs it compiled to
+JavaScript first (for example with `npx -p typescript tsc --target es2020 --module esnext himalaya.ts`).
+
+```ts
+// himalaya.ts — call native Himi app capabilities from a web page. No dependencies.
+// Protocol v1: the page posts {v, id, capability, method, args}; the app answers {v, id, ok, result | error}.
+
+type Bridge = { post(message: unknown): boolean; onMessage(handler: (message: unknown) => void): void };
+type Reply = { v: 1; id: string; ok: boolean; result?: unknown; error?: { message: string; code?: string } };
+
+export class HimalayaError extends Error {
+  /** "not_in_app" | "bridge_refused" | "timeout", or the capability's own code (e.g. "not_authorized"). */
+  readonly code: string;
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = "HimalayaError";
+    this.code = code;
+  }
+}
+
+const pending = new Map<string, { resolve(value: unknown): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }>();
+let listeningOn: Bridge | undefined;
+let counter = 0;
+
+function bridge(): Bridge | undefined {
+  const candidate = (globalThis as { HimalayaWorker?: Bridge }).HimalayaWorker;
+  if (!candidate || typeof candidate.post !== "function" || typeof candidate.onMessage !== "function") return undefined;
+  if (listeningOn !== candidate) {
+    candidate.onMessage((message) => {
+      const reply = message as Reply;
+      if (!reply || reply.v !== 1 || typeof reply.id !== "string" || typeof reply.ok !== "boolean") return;
+      const call = pending.get(reply.id);
+      if (!call) return;
+      pending.delete(reply.id);
+      clearTimeout(call.timer);
+      if (reply.ok) call.resolve(reply.result);
+      else call.reject(new HimalayaError(reply.error?.message ?? "Native call failed", reply.error?.code ?? "failed"));
+    });
+    listeningOn = candidate;
+  }
+  return candidate;
+}
+
+/** True when the page is running inside a Himi app WebView (false in a normal browser). */
+export function isInHimiApp(): boolean {
+  return bridge() !== undefined;
+}
+
+/** Call one native method, e.g. call("health", "query", [{ type: "steps", from, to }]). */
+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"));
+  const id = `page-${Date.now().toString(36)}-${++counter}`;
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new HimalayaError(`${capability}.${method} did not answer — is it enabled for this site?`, "timeout"));
+    }, timeoutMs);
+    pending.set(id, { resolve: resolve as (value: unknown) => void, reject, timer });
+    if (!target.post({ v: 1, id, capability, method, args })) {
+      clearTimeout(timer);
+      pending.delete(id);
+      reject(new HimalayaError("The app refused the message (too large or too frequent)", "bridge_refused"));
+    }
+  });
+}
+
+/** 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> {
+  try {
+    await call(capability, method, args, timeoutMs);
+    return true;
+  } catch (error) {
+    // Only an answer from the app (even an error) proves the method is enabled.
+    return !(error instanceof HimalayaError && ["timeout", "not_in_app", "bridge_refused"].includes(error.code));
+  }
+}
+
+type Namespace = { [method: string]: ((...args: any[]) => Promise<any>) & Namespace };
+
+function member(capability: string, path: string[]): Namespace {
+  return new Proxy(function () {} as unknown as Namespace, {
+    get: (_target, key) => (typeof key === "string" && key !== "then" ? member(capability, [...path, key]) : undefined),
+    apply: (_target, _this, args: unknown[]) => call(capability, path.join("."), args),
+  });
+}
+
+/** himalaya.<capability>.<method>(...args), e.g. himalaya.haptic.play("success"). Always returns a Promise. */
+export const himalaya = new Proxy({} as Record<string, Namespace>, {
+  get: (_target, key) => (typeof key === "string" && key !== "then" ? member(key, []) : undefined),
+});
+```
+
+Keep it as an ES module (`import` / `export`). In a classic `<script>` tag, do not create a global
+named `himalaya` — the app already defines a read-only `window.himalaya`.
+
+## Step 2 — call a capability
+
+Capability ids are snake_case (`health`, `haptic`, `secure_storage`, `local_database`); method
+names are exactly the SDK's function names. Arguments and results are plain JSON.
+
+```ts
+import { himalaya, HimalayaError } from "./lib/himalaya";
+
+// Light, fire-and-forget feedback.
+await himalaya.haptic.play("success");
+
+// Health: check, ask (from a button tap), then read.
+const { available } = await himalaya.health.availability();
+if (available) {
+  await himalaya.health.requestPermission({ read: ["steps"] });
+  const midnight = new Date();
+  midnight.setHours(0, 0, 0, 0);
+  const { samples } = await himalaya.health.query({
+    type: "steps",
+    from: midnight.toISOString(),
+    to: new Date().toISOString(),
+  });
+}
+```
+
+`call("health", "availability")` is the same thing without the proxy, and is handy when the
+capability or method name is a variable.
+
+## Step 3 — React pattern
+
+```tsx
+import { useEffect, useState } from "react";
+import { call, himalaya, isInHimiApp, HimalayaError } from "./lib/himalaya";
+
+export function StepsCard() {
+  const [state, setState] = useState<"checking" | "browser" | "off" | "ready" | "denied" | "failed">("checking");
+  const [steps, setSteps] = useState<number | null>(null);
+
+  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)
+      .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"));
+  }, []);
+
+  async function connect() {
+    try {
+      await himalaya.health.requestPermission({ read: ["steps"] });
+      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));
+      await himalaya.haptic.play("success").catch(() => {});
+    } catch (error) {
+      // Every outcome gets a state: a click handler that rethrows leaves an unhandled rejection.
+      const code = error instanceof HimalayaError ? error.code : "failed";
+      setState(code === "not_authorized" ? "denied" : code === "timeout" || code === "unavailable" ? "off" : "failed");
+    }
+  }
+
+  if (state === "checking") return null;
+  if (state === "browser") return <p>Open this page in our app to see your steps.</p>;
+  if (state === "off") return null; // no health store, or Health not enabled for this site — hide it
+  if (state === "denied") return <p>Health access is off. You can turn it on in your phone's Settings.</p>;
+  if (state === "failed") return <button onClick={connect}>Couldn't load your steps — try again</button>;
+  return steps === null ? <button onClick={connect}>Show today's steps</button> : <p>{steps} steps today</p>;
+}
+```
+
+The same page must keep working in an ordinary browser (and in Base44 / Lovable previews): check
+`isInHimiApp()` and render a fallback instead of calling.
+
+## Rules that keep a page working
+
+- **Ask for permission only from a user action** (a button tap), after explaining the benefit on
+  screen. Never prompt on page load.
+- **Handle "no" and "not available".** Every permission can be denied; Health may not exist on the
+  device (`availability()` tells you). Show a calm fallback, not an error.
+- **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 }`).
+- **Plain JSON only.** Arguments and results cross as JSON: no functions, `Date` objects (use ISO
+  strings), `Blob`s or class instances. At most 12 arguments; keep each message under 1 MB.
+- **Don't flood the bridge.** About 50 messages per second is the ceiling; debounce sliders and
+  scroll handlers.
+- **Request/response only.** Methods that return a stream (`AsyncIterable`) or take a callback are
+  not callable from a page — the reference marks them. Poll a read method instead, or ask the
+  app owner for a page-friendly method.
+- **Never put secrets in the page.** The page is public web code; native calls are authorized by
+  the app, not by anything you send.
+
+## Errors
+
+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, or not on this app build | Hide the feature; ask the app owner to enable `capability.method` |
+| `bridge_refused` | Message too large or too frequent | Send less, less often |
+| `not_authorized` | The user denied permission | Explain how to enable it in Settings |
+| `unavailable` | Not supported on this device | Hide the feature |
+| `invalid_argument` | Wrong argument shape | Fix the call — check the reference |
+| `failed` / other | The native call failed | Show a retry |
+
+Codes other than the first three come from the capability itself; its reference page lists them.
+
+## Test it
+
+- **In a browser** — `isInHimiApp()` is `false`; confirm your fallback renders.
+- **With a fake bridge** — for unit tests or a design preview, install a fake before your app code
+  runs:
+
+  ```ts
+  const answers: Record<string, unknown> = {
+    "health.availability": { available: true },
+    "health.requestPermission": undefined,
+    "health.query": { samples: [{ value: 4200 }] },
+    "haptic.play": undefined,
+  };
+  let reply: (message: unknown) => void = () => {};
+  (window as any).HimalayaWorker = {
+    post: (m: any) => (setTimeout(() => reply({ v: 1, id: m.id, ok: true, result: answers[`${m.capability}.${m.method}`] })), true),
+    onMessage: (handler: (message: unknown) => void) => { reply = handler; },
+  };
+  ```
+
+  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.
+
+## Reference
+
+- [Web page SDK reference](https://apps.wix.com/_api/himi-serve/docs/web-page-sdk-reference.md) — every capability id and the methods a
+  page can call, with signatures.
+- Per-package pages (type definitions and examples; long declarations are abridged there, the
+  reference above lists every callable signature in full): `https://apps.wix.com/_api/himi-serve/authoring/resource/sdks%2F<package>`,
+  for example [health](https://apps.wix.com/_api/himi-serve/authoring/resource/sdks%2Fhealth) and
+  [haptic](https://apps.wix.com/_api/himi-serve/authoring/resource/sdks%2Fhaptic).