@wix/himalaya-cli 0.1304.0 → 0.1305.0

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

@@ -109,7 +109,7 @@ export function call<T = unknown>(capability: string, method: string, args: unkn
     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"));
+      reject(new HimalayaError("The app's bridge refused the message", "bridge_refused"));
     }
   });
 }
@@ -226,7 +226,13 @@ The same page must keep working in an ordinary browser (and in Base44 / Lovable
   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.
+  strings), `Blob`s or class instances.
+- **Keep what you send small.** The app checks every message a page sends and silently drops one
+  that breaks a rule — your call then times out. Per call: at most 12 arguments, nested at most
+  10 levels deep, 1 MB in total, **each string at most 2,048 characters**, and no strings
+  containing `<script`, control characters or bidirectional-override characters. So a page cannot
+  pass a long text or a base64 file *into* a call (`files.write`, a large
+  `secure_storage.write`); results coming *back* are not limited this way.
 - **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
@@ -242,8 +248,8 @@ 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 |
+| `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` |
+| `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 |
 | `invalid_argument` | Wrong argument shape | Fix the call — check the reference |
@@ -276,11 +282,66 @@ Codes other than the first three come from the capability itself; its reference
 - **On a phone** — open the page inside the app build the owner configured. Check each feature
   once with permission granted and once denied.
 
+## 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";
+
+// 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" });
+
+// Where am I? Ask first, then read once. getCurrent answers null when no fix arrives in time.
+const status = await himalaya.location.requestPermission();
+if (status === "granted") {
+  const here = await himalaya.location.getCurrent({ timeoutMs: 10_000 });
+  if (here) console.log(here.lat, here.lng, `±${here.accuracy}m`);
+}
+
+// Keep a small secret on the device (encrypted storage, not localStorage).
+await himalaya.secure_storage.write("refresh-token", "the-token-value");
+const saved = await himalaya.secure_storage.read("refresh-token"); // string | null
+
+// 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");
+```
+
+**Files arrive as handles.** Methods that return a photo, recording or file give you a
+`FileHandle` (or an object with a device `uri`): a token for a file on the device, not the bytes.
+You cannot put it in an `<img>` directly. Hand it to another call that takes one — share it,
+save it to the photo library:
+
+```ts
+const [photo] = await himalaya.photos.pick({ limit: 1 });
+if (photo) await himalaya.share.share({ files: [photo] });
+```
+
+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 });
+if (photo) {
+  const base64 = await himalaya.files.readBase64(photo);
+  const img = document.createElement("img");
+  img.src = `data:${photo.mimeType};base64,${base64}`;
+  document.body.append(img); // or set the src of an <img> your component renders
+}
+```
+
+For larger files, or to keep a copy on your server, upload straight from the device with
+`presigned_upload.putFile(url, handle)` and use the uploaded URL. Going the other way, a page
+cannot send large content in: see the size rules below.
+
 ## 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).
+- [Web page SDK reference](https://apps.wix.com/_api/himi-serve/docs/web-page-sdk-reference.md) — the
+  index: one line per capability a page can call, each linking its own page.
+- Each capability page — `https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2F<capability>?format=md`,
+  for example [health](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhealth?format=md)
+  and [haptic](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhaptic?format=md) —
+  lists the callable methods, defines every type they use and the capability's error codes, and
+  gives a typed module to save as `src/lib/himalaya-<capability>.ts` next to `himalaya.ts`.
+  **Open only the pages for the capabilities your page uses.**