@wix/himalaya-cli 0.1591.0 → 0.1593.0

package/guides/sdk-reference.json

@@ -1180,6 +1180,66 @@
         "jsdoc": "/** Search contacts by name (requires read permission). [] when denied/no match. */",
         "decl": "export async function search(query: string, limit?: number): Promise<Contact[]>;"
       },
+      {
+        "name": "ContactField",
+        "kind": "interface",
+        "jsdoc": "/** One labelled phone number or email address. `label` is free text (\"work\", \"mobile\"…);\n *  each host maps the common ones to its native label and keeps the rest as a custom label. */",
+        "decl": "export interface ContactField {\n  label?: string;\n  value: string;\n}"
+      },
+      {
+        "name": "NewContact",
+        "kind": "interface",
+        "jsdoc": "/** A contact to create. At least one of `givenName`, `familyName` or `organization` must be\n *  non-blank; every list holds at most {@link MAX_CONTACT_ENTRIES} entries. */",
+        "decl": "export interface NewContact {\n  givenName?: string;\n  familyName?: string;\n  organization?: string;\n  phones?: ContactField[];\n  emails?: ContactField[];\n  urls?: string[];\n  note?: string;\n}"
+      },
+      {
+        "name": "MAX_CONTACT_ENTRIES",
+        "kind": "const",
+        "jsdoc": "/** The most entries `phones`, `emails` or `urls` may carry. */",
+        "decl": "export const MAX_CONTACT_ENTRIES = 20;"
+      },
+      {
+        "name": "ContactsErrorCode",
+        "kind": "type",
+        "jsdoc": "/** Why a create verb rejected. */",
+        "decl": "export type ContactsErrorCode = \"invalid_contact\" | \"permission_denied\" | \"unavailable\";"
+      },
+      {
+        "name": "ContactsError",
+        "kind": "interface",
+        "jsdoc": "/** A create-verb rejection: an `Error` named \"ContactsError\" carrying a stable `code`. (A plain\n *  Error, not a subclass — Tier-5 bundles target an engine without class syntax.) Branch on\n *  `isContactsError(e) && e.code === \"permission_denied\"`. */",
+        "decl": "export interface ContactsError extends Error {\n  name: \"ContactsError\";\n  code: ContactsErrorCode;\n}"
+      },
+      {
+        "name": "contactsError",
+        "kind": "function",
+        "jsdoc": "/** Build a coded contacts rejection. */",
+        "decl": "export function contactsError(code: ContactsErrorCode, message?: string): ContactsError;"
+      },
+      {
+        "name": "isContactsError",
+        "kind": "function",
+        "jsdoc": "/** Whether `e` is a coded contacts rejection. */",
+        "decl": "export function isContactsError(e: unknown): e is ContactsError;"
+      },
+      {
+        "name": "normalizeNewContact",
+        "kind": "function",
+        "jsdoc": "/** Validate and normalize a {@link NewContact}: strings trimmed, blank entries dropped, blank\n *  fields omitted. Throws `invalid_contact` when there is no name or organization, or a list\n *  holds more than {@link MAX_CONTACT_ENTRIES} entries. Every host re-checks the same rules. */",
+        "decl": "export function normalizeNewContact(contact: NewContact): NewContact;"
+      },
+      {
+        "name": "presentNewContact",
+        "kind": "function",
+        "jsdoc": "/** Open the OS new-contact sheet prefilled with `contact` — the recommended way to save a\n *  contact: it needs NO contacts permission, because the user reviews and confirms the save.\n *  Resolves `{ saved: true }` when the user saved it, `{ saved: false }` on cancel. Web\n *  downloads a `.vcf` instead (and resolves `saved: true` once the download is handed off).\n *  Rejects `invalid_contact` (see {@link normalizeNewContact}) or `unavailable`. */",
+        "decl": "export async function presentNewContact(contact: NewContact): Promise<{ saved: boolean }>;"
+      },
+      {
+        "name": "add",
+        "kind": "function",
+        "jsdoc": "/** Write `contact` straight into the address book and resolve its new `id`. Needs contacts\n *  WRITE permission — ask with {@link requestPermission} first; without it this rejects\n *  `permission_denied` (it never prompts). Rejects `invalid_contact`, or `unavailable` where\n *  the host has no address book (web). Prefer {@link presentNewContact} unless the app already\n *  holds the permission. */",
+        "decl": "export async function add(contact: NewContact): Promise<{ id: string }>;"
+      },
       {
         "name": "version",
         "kind": "const",
@@ -1472,11 +1532,71 @@
         "jsdoc": "/** Stat a path, or `null` if it doesn't exist (the existence check for handles). */",
         "decl": "export async function stat(path: string): Promise<FileStat | null>;"
       },
+      {
+        "name": "FilesErrorCode",
+        "kind": "type",
+        "jsdoc": "/** Stable failure codes for the v3 verbs. Branch on `FilesError.code` (see `isFilesError`), never on\n *  the message text.\n *  - `invalid_url`  — not an absolute `https:` URL, carries userinfo, or names a\n *                     loopback / private-network / link-local host (checked on every\n *                     redirect hop; natively also on the resolved DNS records).\n *  - `too_large`    — the response is (or announces it will be) over `maxBytes`.\n *  - `http_error`   — the server answered a non-2xx status (`status` is set).\n *  - `network`      — the transfer failed (DNS, TLS, reset, CORS on web, …).\n *  - `unavailable`  — this host cannot do it: no implementation for the verb, no save\n *                     picker or volume reading to hand, or (`download`) the account signed\n *                     out mid-transfer, so the file was not kept. */",
+        "decl": "export type FilesErrorCode = \"invalid_url\" | \"too_large\" | \"http_error\" | \"network\" | \"unavailable\";"
+      },
+      {
+        "name": "FilesError",
+        "kind": "interface",
+        "jsdoc": "/** A v3 verb failure: an `Error` whose `code` is stable and `message` is for humans.\n *  (A plain Error with fields, not a subclass — worker bundles target a syntax level\n *  without `class`.) Narrow with {@link isFilesError}. */",
+        "decl": "export interface FilesError extends Error {\n  name: \"FilesError\";\n  code: FilesErrorCode;\n  status?: number;\n}"
+      },
+      {
+        "name": "filesError",
+        "kind": "function",
+        "jsdoc": "/** Build a FilesError. */",
+        "decl": "export function filesError(code: FilesErrorCode, message: string, status?: number): FilesError;"
+      },
+      {
+        "name": "isFilesError",
+        "kind": "function",
+        "jsdoc": "/** Whether `e` is a FilesError thrown by a v3 verb. */",
+        "decl": "export function isFilesError(e: unknown): e is FilesError;"
+      },
+      {
+        "name": "DEFAULT_DOWNLOAD_MAX_BYTES",
+        "kind": "const",
+        "jsdoc": "/** The download cap when `maxBytes` is omitted: 100 MiB. */",
+        "decl": "export const DEFAULT_DOWNLOAD_MAX_BYTES = 100 * 1024 * 1024;"
+      },
+      {
+        "name": "MAX_DOWNLOAD_BYTES",
+        "kind": "const",
+        "jsdoc": "/** The hard ceiling every arm clamps `maxBytes` to: 1 GiB. */",
+        "decl": "export const MAX_DOWNLOAD_BYTES = 1024 * 1024 * 1024;"
+      },
+      {
+        "name": "download",
+        "kind": "function",
+        "jsdoc": "/**\n * Stream an `https:` URL straight into the sandbox and resolve with its FileHandle —\n * the same shape `write` returns. The bytes never cross the worker bridge.\n *\n * - No credentials are attached: a fresh cookie-less session, no auth provider (the\n *   `presigned_upload` rule). Use it for public / pre-signed URLs.\n * - `http:`, userinfo, and loopback / private-network / link-local hosts are refused\n *   (`invalid_url`); every redirect hop is re-checked before it is followed, and the\n *   native arms validate the resolved DNS records too.\n * - `name` is the destination path relative to the files root (like `write`'s\n *   `path`); default `downloads/<last URL path segment>`. An existing file is replaced.\n * - `maxBytes` defaults to 100 MiB (clamped to 1 GiB); over it the transfer is aborted (`too_large`) and\n *   nothing is left behind.\n */",
+        "decl": "export async function download(url: string, opts?: { name?: string; maxBytes?: number }): Promise<FileHandle>;"
+      },
+      {
+        "name": "export",
+        "kind": "function",
+        "jsdoc": "/**\n * Let the user save a sandbox file OUTSIDE the app through the OS save picker: the\n * Files app on iOS, `NSSavePanel` on macOS, the Storage Access Framework on Android\n * (no storage permission — the user picks the folder), a download on web. Resolves\n * `{ exported: false }` when the user cancels.\n *\n * Exported as `export`, so call it as `files.export(handle)` (namespace import) or\n * `import { export as exportFile } from \"@himalaya/files\"`.\n */",
+        "decl": "export async function exportFile(\n  file: FileHandle | string,\n  opts?: { suggestedName?: string; mimeType?: string },\n): Promise<{ exported: boolean }>;"
+      },
+      {
+        "name": "StorageInfo",
+        "kind": "interface",
+        "jsdoc": "/** Storage figures, in bytes. `source` says what they measure:\n *  - `\"device\"`   — the device volume (iOS `volumeAvailableCapacityForImportantUsage`,\n *                   Android `StatFs`) and the bytes in this app's files root.\n *  - `\"estimate\"` — web: the origin's `navigator.storage.estimate()` quota/usage. */",
+        "decl": "export interface StorageInfo {\n  freeBytes: number;\n  totalBytes: number;\n  appBytes: number;\n  source: \"device\" | \"estimate\";\n}"
+      },
+      {
+        "name": "storageInfo",
+        "kind": "function",
+        "jsdoc": "/** How much space is left before a large write, and how much this app's files use. */",
+        "decl": "export async function storageInfo(): Promise<StorageInfo>;"
+      },
       {
         "name": "version",
         "kind": "const",
-        "jsdoc": "/** Capability version, for bundles that gate on min binary version. */",
-        "decl": "export const version = 2;"
+        "jsdoc": "/** Capability version, for bundles that gate on min binary version.\n *  3 — `download`, `export`, `storageInfo`. */",
+        "decl": "export const version = 3;"
       }
     ]
   },

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

@@ -23,9 +23,9 @@ the SDK sources, so it matches the shipped SDKs.
 - [`calls`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcalls?format=md) — Real-time 1:1 audio calls (Stage 1). 16 methods.
 - [`camera`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcamera?format=md) — Camera capability. 4 methods · returns FileHandles.
 - [`clipboard`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fclipboard?format=md) — System clipboard. 5 methods.
-- [`contacts`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcontacts?format=md) — Device address book. 4 methods.
+- [`contacts`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fcontacts?format=md) — Device address book. 6 methods.
 - [`file_picker`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Ffile_picker?format=md) — User-mediated document access OUTSIDE the app sandbox. 3 methods · returns FileHandles.
-- [`files`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Ffiles?format=md) — App-scoped document storage. 6 methods · returns FileHandles.
+- [`files`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Ffiles?format=md) — App-scoped document storage. 9 methods · returns FileHandles.
 - [`godot`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fgodot?format=md) — A Godot game surface. 3 methods · not in Brandy.
 - [`haptic`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhaptic?format=md) — Haptic capability. 3 methods.
 - [`health`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fhealth?format=md) — Platform HEALTH store. 5 methods.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1591.0",
+  "version": "0.1593.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": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "ed70c40fd8301c23d93e03720c8e7707fcb10a588229994fc447fabb"
+  "falconPackageHash": "fb54e208c094140390368b7d75ef82ca0bffeb791cc24cb79670e599"
 }