@wix/himalaya-cli 0.956.0 → 0.958.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/push/src/index.d.ts

@@ -18,7 +18,10 @@ export interface ScheduleLocalOptions {
     link?: string;
     /** Actionable category id (must match a `PushConfig.categories[].id`). */
     category?: string;
-    /** App-icon badge number to set when this notification is delivered. */
+    /** App-icon badge number to set when this notification is delivered. `0` clears
+     *  it; omit to leave the current badge alone. Honored on iOS (`aps.badge`) and
+     *  Android (the shared badge slot, see `setBadge`). Web cannot badge from a
+     *  notification — call `setBadge` directly there. */
     badge?: number;
     /** Rich media: an image URL. iOS attaches it (UNNotificationAttachment),
      *  Android renders it as a BigPicture. Omit for a plain text notification. */
@@ -42,10 +45,47 @@ export declare function scheduleLocal(options: ScheduleLocalOptions): Promise<{
 export declare function cancelLocal(id: string): Promise<void>;
 /** Cancel every pending local notification this app scheduled. */
 export declare function cancelAllLocal(): Promise<void>;
-/** Set the app-icon badge count. `0` clears it. */
+/**
+ * Set the app-icon badge count ("the pimple"). `0` clears it; negatives and
+ * fractions are clamped/truncated. The badge persists until you change it — it is
+ * not tied to any notification, and nothing decrements it for you.
+ *
+ * How each surface draws it, because the differences are visible to users:
+ * - **iOS / macOS** — `UNUserNotificationCenter.setBadgeCount`. Needs the `.badge`
+ *   notification authorization, so call `requestPermission()` first or the number
+ *   is stored and never shown.
+ * - **Android** — stock Android has no set-count API and a third-party badger
+ *   dependency is disallowed, so the count rides on ONE silent, low-importance
+ *   notification in a dedicated `himalaya.badge` channel. Consequences worth
+ *   designing around: it is **visible in the notification shade**, the user can
+ *   turn that channel off, launchers that only do dots show a dot rather than the
+ *   number, and without the API 33+ `POST_NOTIFICATIONS` grant it is a silent no-op.
+ * - **Web** — `navigator.setAppBadge`, which needs an installed PWA and notification
+ *   permission; unsupported browsers no-op.
+ *
+ * Best-effort everywhere: this never throws when the platform refuses.
+ */
 export declare function setBadge(count: number): Promise<void>;
-/** Clear the app-icon badge (equivalent to `setBadge(0)`). */
+/** Clear the app-icon badge — exactly `setBadge(0)`. On Android this cancels the
+ *  badge-carrier notification, so it also disappears from the shade. */
 export declare function clearBadge(): Promise<void>;
+/**
+ * Read the current app-icon badge count.
+ *
+ * What "current" means differs by surface, and the difference is worth knowing
+ * before you build an increment on top of it:
+ * - **iOS** — the real OS value, so it survives a cold start and reflects a badge a
+ *   remote push set. (Read through `applicationIconBadgeNumber`: notifications has a
+ *   `setBadgeCount` setter but no matching reader, so write and read are asymmetric.)
+ * - **macOS / Android / web** — the last value THIS PROCESS set. None of the three
+ *   can read the badge back (macOS exposes only a display string, Android derives
+ *   the badge from a notification, the web Badging API is write-only), so a cold
+ *   start reports `0` even when the icon still shows a number.
+ *
+ * Because of that, prefer deriving the badge from your own state and calling
+ * `setBadge(total)` over a read-modify-write of this value.
+ */
+export declare function getBadge(): Promise<number>;
 /** The registered remote device token (APNs hex / FCM token), or null if the
  *  app has not registered for remote notifications yet. */
 export declare function getDeviceToken(): Promise<string | null>;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/sdk/sdk-types/src/capabilities.generated.d.ts

@@ -26,7 +26,7 @@ export declare const CAPABILITY_REGISTRY: {
     readonly pdf: readonly ["isAvailable", "open"];
     readonly photos: readonly ["getSavePermissionStatus", "pick", "saveToLibrary"];
     readonly presigned_upload: readonly ["put", "putFile"];
-    readonly push: readonly ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"];
+    readonly push: readonly ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"];
     readonly release_control: readonly ["active", "available", "list", "select"];
     readonly secure_storage: readonly ["availability", "read", "remove", "write"];
     readonly share: readonly ["availability", "share"];

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/audio-record.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/calendar.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/calls.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/contacts.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/location.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/motion.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/photos.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/push.mjs

@@ -50,6 +50,11 @@ async function setBadge(count) {
 async function clearBadge() {
   await dispatch("capability.push.setBadge", { count: 0 });
 }
+async function getBadge() {
+  const r = await dispatch("capability.push.getBadge");
+  const n = Number(r?.count);
+  return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+}
 async function getDeviceToken() {
   const r = await dispatch("capability.push.getDeviceToken");
   return r?.token && r.token.length > 0 ? r.token : null;
@@ -70,6 +75,7 @@ export {
   cancelLocal,
   clearBadge,
   clearDelivered,
+  getBadge,
   getDeviceToken,
   getPermissionStatus,
   listDelivered,

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/sdk-types.mjs

@@ -26,7 +26,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/tasks.mjs

@@ -41,7 +41,7 @@ var CAPABILITY_REGISTRY = {
   "pdf": ["isAvailable", "open"],
   "photos": ["getSavePermissionStatus", "pick", "saveToLibrary"],
   "presigned_upload": ["put", "putFile"],
-  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
+  "push": ["cancelAllLocal", "cancelLocal", "clearDelivered", "getBadge", "getDeviceToken", "getPermissionStatus", "listDelivered", "requestPermission", "scheduleLocal", "setBadge"],
   "release_control": ["active", "available", "list", "select"],
   "secure_storage": ["availability", "read", "remove", "write"],
   "share": ["availability", "share"],

package/dist/cli.mjs

@@ -39201,7 +39201,7 @@ var init_preview_token = __esm({
     SUBTLE_ALGO = { name: "HMAC", hash: "SHA-256" };
     PREVIEW_TOKEN_VERSION = 1;
     DEFAULT_PREVIEW_TOKEN_TTL_SECONDS = 5 * 60;
-    WEB_PREVIEW_TOKEN_TTL_SECONDS = 15 * 60;
+    WEB_PREVIEW_TOKEN_TTL_SECONDS = 45 * 60;
   }
 });
 
@@ -43359,19 +43359,19 @@ var init_preview_assets_generated = __esm({
   "../../packages/serve/src/preview-assets.generated.ts"() {
     init_preview_assets_format();
     PREVIEW_ASSET_MANIFEST = [
-      { key: "assets/index-BjeU573D.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 984799, sha256: "c9d1cae4cb78ee9be62f41d1f84c87599fa347404cc256580bca700f71f0c045" },
-      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 984807, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
-      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1075731, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
-      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1166715, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
-      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1257695, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
-      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 1348567, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
-      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 1439547, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
-      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 1548183, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
-      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 1657267, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
-      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 1766315, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
-      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 1874015, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
-      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 1962123, length: 4448, sha256: "5f8763e9a491dc85c1c0dd52572d5f61bf4c3f978e4fd39262bae1f46e101a54" },
-      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 1966571, length: 13784, sha256: "cfb9465254fab84f0e084bb4542c282758ea29774b5f172840cc0b9e4194ef89" }
+      { key: "assets/index-BdjUMoXo.js", contentType: "application/javascript; charset=utf-8", offset: 8, length: 985049, sha256: "f401b5ebead76d81b1f3d1d401b77925b53123856ababfc4d2d407656c10601d" },
+      { key: "fonts/WixMadeforDisplay-Bold.ttf", contentType: "font/ttf", offset: 985057, length: 90924, sha256: "ec4c7d63772d980d6e147b2df6215fd2737e4b04cebe0cf7e11dc695fb63cdcf" },
+      { key: "fonts/WixMadeforDisplay-ExtraBold.ttf", contentType: "font/ttf", offset: 1075981, length: 90984, sha256: "bf4c16a2774edd38a921edf3099469866cd74c094fd596f3fa4e81f54a04dfaa" },
+      { key: "fonts/WixMadeforDisplay-Medium.ttf", contentType: "font/ttf", offset: 1166965, length: 90980, sha256: "368faca44fb9f7207e4af784e94750b1ee59c1098b8689e0f4a918926f244fb5" },
+      { key: "fonts/WixMadeforDisplay-Regular.ttf", contentType: "font/ttf", offset: 1257945, length: 90872, sha256: "97ed8f1a6772abe26e3d8af5cecfc4b02faa94497d585b0398b5053b739a70c1" },
+      { key: "fonts/WixMadeforDisplay-SemiBold.ttf", contentType: "font/ttf", offset: 1348817, length: 90980, sha256: "642feab8a48ddf6c7a89d7c2a7c0edfa0e6e773f671287e460e222703563191e" },
+      { key: "fonts/WixMadeforText-Bold.ttf", contentType: "font/ttf", offset: 1439797, length: 108636, sha256: "37c179b4fefb63ea9637322b84583a2df53aa226c150294eea1675c14b1b8e29" },
+      { key: "fonts/WixMadeforText-ExtraBold.ttf", contentType: "font/ttf", offset: 1548433, length: 109084, sha256: "62e2fe4718129f36ecdb0ae4de385bd6b81ecc876146447167c6c140fad699a9" },
+      { key: "fonts/WixMadeforText-Medium.ttf", contentType: "font/ttf", offset: 1657517, length: 109048, sha256: "4ecf270136af928612c76fe4ebade91d8156975e5ea4c0cf9225501dd1788e02" },
+      { key: "fonts/WixMadeforText-Regular.ttf", contentType: "font/ttf", offset: 1766565, length: 107700, sha256: "dee56f09fd3efc127c1ea95557edc74110c1460a46287da36e0af25efd341ef5" },
+      { key: "fonts/WixMadeforText-SemiBold.ttf", contentType: "font/ttf", offset: 1874265, length: 88108, sha256: "dced97a77624bc5f8b1ae65850360908297f4588e09feb6f22792d29dc7e765b" },
+      { key: "index.html", contentType: "text/html; charset=utf-8", offset: 1962373, length: 4448, sha256: "03bf2b6c0fec31fec522df8100cdc53a195a5fe4b792d9dc2888476cb5226624" },
+      { key: "t5-frame.html", contentType: "text/html; charset=utf-8", offset: 1966821, length: 13784, sha256: "cfb9465254fab84f0e084bb4542c282758ea29774b5f172840cc0b9e4194ef89" }
     ];
   }
 });

package/guides/headless-loop.md

@@ -252,10 +252,18 @@ The push JSON includes:
 - `next` — suggested `himi context` / `himi screens` follow-ups
 
 The browser-preview token embedded in `previewWeb` is scoped to this app + draft release and
-expires after **15 minutes**. The JSON also includes `previewTokenExpiresAt`. If review takes
-longer, run `himi preview --app my-app --release <id> --target wix`: it renews the browser token
-without promoting the draft. For header-only function calls against the same draft, pass the
-separately issued short-lived function token as `--preview-token <token>`.
+expires after **45 minutes**. The JSON also includes `previewTokenExpiresAt` — read that rather
+than this number when you are talking to a plane you did not start. If review takes longer, run
+`himi preview --app my-app --release <id> --target wix`: it renews the browser token without
+promoting the draft. For header-only function calls against the same draft, pass the separately
+issued short-lived function token as `--preview-token <token>`.
+
+**When you hand `previewWeb` to a person, the expiry is theirs, not yours.** Renewing it needs
+this CLI and your credentials, so a link handed over near the end of a session leaves the
+recipient with a deadline and no way to extend it. Re-mint immediately before handing it over
+rather than passing on a link minted earlier, and say the expiry in their timezone. If they sign
+in to the Wix account that owns the app, its own owner page previews it for them
+without this CLI and without you — that, not the link, is the durable way back in.
 
 ## 5b. Agent preview (machine-readable, no browser scrape)
 

package/guides/sdk-reference.json

@@ -2410,7 +2410,7 @@
         "name": "ScheduleLocalOptions",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface ScheduleLocalOptions {\n  /** Stable identifier. Reusing an id replaces the pending notification. Omit ⇒\n   *  the platform generates a UUID and returns it. */\n  id?: string;\n  title: string;\n  body: string;\n  /** Fire this many seconds from now (min 1). Mutually exclusive with `at`;\n   *  if both are set `at` wins. */\n  afterSeconds?: number;\n  /** Absolute fire time, epoch milliseconds. Mutually exclusive with `afterSeconds`. */\n  at?: number;\n  /** Repeat at the `afterSeconds` interval (iOS requires interval ≥ 60 to repeat). */\n  repeats?: boolean;\n  /** Deeplink routed on tap — same resolver as a remote push `link`\n   *  (`<scheme>://screen/<id>` or a curated pattern). Omit ⇒ just opens the app. */\n  link?: string;\n  /** Actionable category id (must match a `PushConfig.categories[].id`). */\n  category?: string;\n  /** App-icon badge number to set when this notification is delivered. */\n  badge?: number;\n  /** Rich media: an image URL. iOS attaches it (UNNotificationAttachment),\n   *  Android renders it as a BigPicture. Omit for a plain text notification. */\n  image?: string;\n}"
+        "decl": "export interface ScheduleLocalOptions {\n  /** Stable identifier. Reusing an id replaces the pending notification. Omit ⇒\n   *  the platform generates a UUID and returns it. */\n  id?: string;\n  title: string;\n  body: string;\n  /** Fire this many seconds from now (min 1). Mutually exclusive with `at`;\n   *  if both are set `at` wins. */\n  afterSeconds?: number;\n  /** Absolute fire time, epoch milliseconds. Mutually exclusive with `afterSeconds`. */\n  at?: number;\n  /** Repeat at the `afterSeconds` interval (iOS requires interval ≥ 60 to repeat). */\n  repeats?: boolean;\n  /** Deeplink routed on tap — same resolver as a remote push `link`\n   *  (`<scheme>://screen/<id>` or a curated pattern). Omit ⇒ just opens the app. */\n  link?: string;\n  /** Actionable category id (must match a `PushConfig.categories[].id`). */\n  category?: string;\n  /** App-icon badge number to set when this notification is delivered. `0` clears\n   *  it; omit to leave the current badge alone. Honored on iOS (`aps.badge`) and\n   *  Android (the shared badge slot, see `setBadge`). Web cannot badge from a\n   *  notification — call `setBadge` directly there. */\n  badge?: number;\n  /** Rich media: an image URL. iOS attaches it (UNNotificationAttachment),\n   *  Android renders it as a BigPicture. Omit for a plain text notification. */\n  image?: string;\n}"
       },
       {
         "name": "DeliveredNotification",
@@ -2451,15 +2451,21 @@
       {
         "name": "setBadge",
         "kind": "function",
-        "jsdoc": "/** Set the app-icon badge count. `0` clears it. */",
+        "jsdoc": "/**\n * Set the app-icon badge count (\"the pimple\"). `0` clears it; negatives and\n * fractions are clamped/truncated. The badge persists until you change it — it is\n * not tied to any notification, and nothing decrements it for you.\n *\n * How each surface draws it, because the differences are visible to users:\n * - **iOS / macOS** — `UNUserNotificationCenter.setBadgeCount`. Needs the `.badge`\n *   notification authorization, so call `requestPermission()` first or the number\n *   is stored and never shown.\n * - **Android** — stock Android has no set-count API and a third-party badger\n *   dependency is disallowed, so the count rides on ONE silent, low-importance\n *   notification in a dedicated `himalaya.badge` channel. Consequences worth\n *   designing around: it is **visible in the notification shade**, the user can\n *   turn that channel off, launchers that only do dots show a dot rather than the\n *   number, and without the API 33+ `POST_NOTIFICATIONS` grant it is a silent no-op.\n * - **Web** — `navigator.setAppBadge`, which needs an installed PWA and notification\n *   permission; unsupported browsers no-op.\n *\n * Best-effort everywhere: this never throws when the platform refuses.\n */",
         "decl": "export async function setBadge(count: number): Promise<void>;"
       },
       {
         "name": "clearBadge",
         "kind": "function",
-        "jsdoc": "/** Clear the app-icon badge (equivalent to `setBadge(0)`). */",
+        "jsdoc": "/** Clear the app-icon badge — exactly `setBadge(0)`. On Android this cancels the\n *  badge-carrier notification, so it also disappears from the shade. */",
         "decl": "export async function clearBadge(): Promise<void>;"
       },
+      {
+        "name": "getBadge",
+        "kind": "function",
+        "jsdoc": "/**\n * Read the current app-icon badge count.\n *\n * What \"current\" means differs by surface, and the difference is worth knowing\n * before you build an increment on top of it:\n * - **iOS** — the real OS value, so it survives a cold start and reflects a badge a\n *   remote push set. (Read through `applicationIconBadgeNumber`: notifications has a\n *   `setBadgeCount` setter but no matching reader, so write and read are asymmetric.)\n * - **macOS / Android / web** — the last value THIS PROCESS set. None of the three\n *   can read the badge back (macOS exposes only a display string, Android derives\n *   the badge from a notification, the web Badging API is write-only), so a cold\n *   start reports `0` even when the icon still shows a number.\n *\n * Because of that, prefer deriving the badge from your own state and calling\n * `setBadge(total)` over a read-modify-write of this value.\n */",
+        "decl": "export async function getBadge(): Promise<number>;"
+      },
       {
         "name": "getDeviceToken",
         "kind": "function",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.956.0",
+  "version": "0.958.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": [
@@ -64,5 +64,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "fb07bf20632ab00e2803dd1051fa69df3a13555e1691547c243d156c"
+  "falconPackageHash": "d7801908694db877e53dbcdb28836a858399f835aec0a43b73c80bec"
 }