@wix/himalaya-cli 0.1149.0 → 0.1150.0

package/guides/app-config.md

@@ -109,7 +109,7 @@ worker may use. Enforcement is **fail-closed** at two layers (SDK import + nativ
 undeclared `capability.*` call is blocked at runtime. A worker hitting the Wix transport must
 declare `wix_api`; the Wix Platform facade needs `wix_platform`.
 
-App-level capability vocabulary: `camera`, `barcode_scanner`, `biometrics`, `secure_storage`, `share`, `push`, `file_picker`, `files`, `open_url`, `pdf`, `clipboard`, `photos`, `presigned_upload`, `ui`, `calendar`, `contacts`, `tasks`, `audio_record`, `audio_record_background`, `calls`, `location`, `location_background`, `motion`, `media_playback`, `webview`, `browser_auth`, `haptic`, `himi_apps`, `iap`, `keyboard`, `wix_cashier`, `live_activity`, `local_database`, `speech`, `speaker_diarization`, `system_intents`, `on_device_ai`, `app_info`, `release_control`, `godot`.
+App-level capability vocabulary: `camera`, `barcode_scanner`, `biometrics`, `secure_storage`, `share`, `push`, `file_picker`, `files`, `open_url`, `pdf`, `clipboard`, `photos`, `presigned_upload`, `ui`, `calendar`, `contacts`, `tasks`, `audio_record`, `audio_record_background`, `calls`, `location`, `location_background`, `motion`, `media_playback`, `webview`, `browser_auth`, `haptic`, `himi_apps`, `iap`, `keyboard`, `wix_cashier`, `live_activity`, `local_database`, `speech`, `speaker_diarization`, `system_intents`, `on_device_ai`, `app_info`, `release_control`, `godot`, `base44`.
 
 ## What `himi validate` checks (7 passes)
 

package/guides/iap-products.md

@@ -0,0 +1,215 @@
+# Registering digital products as App Store in-app purchases (`himi store iap`)
+
+`himi store iap` registers an app owner's **selected digital products** in the owner's
+existing App Store Connect app. It configures each product's draft metadata, an exact
+initial price and explicit territories. It then exports a Wix→Apple mapping for a future
+backend import.
+
+It is an administration workflow, not a build: it never builds, signs or bumps a version,
+and it runs anywhere `himi` is installed. An owner needs only a manifest and a credential
+profile. It does not run during an app build or a customer checkout.
+
+This version supports **one-time non-consumable** products only. Every other product type
+is refused before anything reaches Apple.
+
+## Before you start
+
+- **The Apple app record already exists.** This command never creates apps or accounts,
+  and never accepts agreements.
+- **You have an App Store Connect API key for the account that owns the app.** Managing
+  in-app purchases needs the **Admin** or **App Manager** role (or Account Holder). A
+  user's role in the web UI does not grant it to a key.
+- **You have a credential profile for that key** at
+  `~/.himalaya/store-credentials/<name>.json`. It holds identifiers plus a path to the
+  `.p8`, never the key itself:
+
+  ```json
+  { "team": "ABCDE12345", "ascKeyId": "…", "ascIssuerId": "…", "ascKeyPath": "/Users/you/.appstore/AuthKey_….p8" }
+  ```
+
+  The profile and the key must both live outside the repository. That is checked after
+  resolving symlinks. The profile's `team` must equal the manifest's `teamId`.
+
+There is **no ambient fallback**. `--profile` is required, and exported `ASC_*` variables
+are never used to decide which account to write to.
+
+## The manifest
+
+The manifest is an explicit, versioned selection. Nothing is inferred from names or prices,
+and nothing is crawled from a Wix catalog.
+
+```json
+{
+  "manifestVersion": 1,
+  "target": {
+    "himiApp": "fit-club",
+    "wixSiteId": "0d9c3e5a-1111-4222-8333-944455556666",
+    "appleAppId": "6450000001",
+    "bundleId": "com.example.fitclub",
+    "teamId": "ABCDE12345",
+    "profile": "fit-club-owner"
+  },
+  "items": [
+    {
+      "wix": { "entityType": "pricingPlan", "entityId": "plan-lifetime" },
+      "classification": "digital",
+      "entitlement": "nutrition-program",
+      "productId": "com.example.fitclub.nutrition.lifetime",
+      "type": "nonConsumable",
+      "referenceName": "Nutrition program (lifetime)",
+      "localizations": [
+        { "locale": "en-US", "name": "Nutrition Program", "description": "Lifetime access to the nutrition plan." }
+      ],
+      "price": { "baseTerritory": "USA", "currency": "USD", "amount": "0.99" },
+      "territories": ["USA", "CAN"]
+    }
+  ]
+}
+```
+
+Rules, all checked locally before any request:
+
+- **`appleAppId`** is the numeric App Store Connect id. The app is never looked up by name,
+  and never taken as "the first app".
+- **`classification`** must be `"digital"`. Physical goods and unclassified products are
+  refused. The classification is your configuration; this command does not make Apple's
+  policy decisions for you.
+- **`productId`** must be stable, and you supply it. Apple product ids and types are
+  **immutable** once created, so the id is never generated or regenerated.
+- **`price.amount`** is an exact decimal **string**. It must match one of Apple's price
+  points exactly. It is never rounded, and a nearby price is never substituted.
+- **`territories`** is an explicit list that includes the base territory. Availability
+  never extends to future territories automatically.
+- **Duplicates are refused:** a product id, Wix entity, entitlement or reference name
+  used twice.
+- **Unknown keys are refused, at every level.** So is any string that looks like a key or a token.
+
+## The workflow
+
+```bash
+himi store iap plan   --manifest ./iap-products.json --profile fit-club-owner --out ./iap-plan.json
+himi store iap apply  --plan ./iap-plan.json --profile fit-club-owner --out ./iap-result.json
+himi store iap status --manifest ./iap-products.json --profile fit-club-owner --json
+```
+
+**`plan` is read-only.** It:
+
+1. Verifies that the app has the manifest's bundle id and that the bundle id is registered
+   to the manifest's team under this key.
+2. Checks that each territory exists and that the base territory prices in the manifest's
+   currency.
+3. Reads every page of the app's in-app purchases, then decides per product:
+
+| Decision | Meaning |
+|---|---|
+| `create` | absent in Apple; apply will create it and configure it |
+| `update` | an editable draft exists; apply will add only what is missing |
+| `reuse` | already configured exactly as requested; nothing to do |
+| `conflict` | differs in a way this command will not change; nothing is written |
+
+A **conflict** is any of:
+
+- the same product id with another type;
+- the reference name already used by another product id;
+- a live or in-review product whose metadata, price or availability differs;
+- an existing price or availability that differs;
+- no exact price point for an existing product.
+
+Resolve conflicts in App Store Connect or in the manifest, then plan again.
+
+For a product that doesn't exist yet, Apple can only list its price points after it is
+created. The plan marks this in the item's `notes`.
+
+**`apply` is the only command that writes.** It:
+
+1. Prints the account, the app and the planned operations, then asks for confirmation.
+   Pass `--yes` for an intentional non-interactive run. Without `--yes`, a non-interactive
+   shell is refused before any request.
+2. Checks the plan and account:
+   - Re-validates the plan file. The manifest and plan digests detect edits; they are not
+     an authorization.
+   - Re-resolves the credential profile and refuses a different profile, team or key.
+3. Re-reads Apple:
+   - Verifies the target again.
+   - If anything changed that the plan did not list (**drift**), it stops before the first
+     write. Planned work that already happened is accepted as done.
+4. For each product, it creates the product, then a draft version, then its
+   localizations. Then it sets the exact initial price and the explicit territories. Then
+   it reads everything back.
+5. Writes the result file, even when the run is partial.
+
+**When a write's outcome is unknown** (a lost response, a timeout, a 409), apply reads
+Apple again before doing anything else:
+
+- A write is repeated **at most once**, and only after that read proves it didn't land.
+- An outcome that is still unknown stops that product as `partial`.
+
+So rerunning the same plan never creates a second product, version, locale or price
+schedule, even without the local journal. Nothing is ever deleted or rolled back.
+
+**`status` is read-only.** It reports what Apple has for each product. Add `--out <file>`
+to save it in the same shape as the result file.
+
+## Local state
+
+Local state lives in `~/.himalaya/store-iap/<appleAppId>/`:
+
+- **`journal.json`** is an append-only record of identifiers and step outcomes. Nothing
+  reads it back to decide anything. Every run re-reads the target app, and a product Apple
+  hasn't listed yet is caught by apply's read-before-retry, so deleting the journal is
+  always safe.
+- **`apply.lock`** prevents two local applies for the same app from interleaving. A lock
+  left behind by a crashed run names its pid; delete the file if no apply is running.
+
+## The result file
+
+Each item has two parts:
+
+- **`mapping`** — the Wix site/app/bundle, the Wix entity and entitlement, the Apple product
+  id, the Apple resource id and the product type.
+- **`provisioning`**:
+  - `outcome` — one of `created`, `updated`, `reused`, `conflict`, `partial`, `failed`
+    (`status` also reports `absent` and `incomplete`)
+  - per-step states and any conflicts
+  - `unmet` — where Apple still differs from the manifest
+  - the requested and observed price, availability and locales
+  - the draft version and Apple's review state
+  - `remainingRequirements`
+  - `lastReadAt`
+
+The top level always carries `"backendSync": "notConfigured"` and `"checkoutActive": false`.
+Creating a product in App Store Connect doesn't make it purchasable in any app, and doesn't
+update checkout.
+
+The file is administrative input, not proof that the listed site owns the Apple app. A
+future importer must authenticate ownership and re-read Apple before activating anything.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | everything requested is in place (`apply`, `status`), or the plan has no conflicts (`plan`) |
+| `1` | partial, conflict, drift, or a declined prompt |
+| `2` | usage, manifest, credential, target or access error; nothing was written |
+
+## What is still yours to do
+
+- **Finish the product in App Store Connect.** Upload the App Review screenshot and add
+  anything else App Store Connect lists as missing. `remainingRequirements` names what
+  Apple reports.
+- **Handle the business side.** Paid Apps agreement, banking and tax information go
+  through the owner's App Store Connect account.
+- **Submit for review.** Submit the product with an app version. This command never
+  submits, and never makes a product available for sale.
+- **Allow for Sandbox delay.** Product changes can take a while to appear in Sandbox
+  purchase testing. Sandbox is for purchases, not a separate product catalogue:
+  these API calls change the real product records.
+
+Not in this version:
+
+- subscriptions and consumables
+- review screenshot upload and submission
+- changing a live price
+- Wix catalog discovery
+- Google Play
+- backend import and checkout activation

package/guides/importable-sdks.md

@@ -16,6 +16,7 @@ package in one greppable file) or `GET /v1/sdk/<name>` over HTTP; in the CLI,
 - `@himalaya/agent` — Tier-5 agent integration.
 - `@himalaya/app-info` — Tier-5 typed binding for this app's OWN build + OTA metadata.
 - `@himalaya/audio-record` — Tier-5 typed binding for microphone recording.
+- `@himalaya/base44` — Tier-5 typed binding for a Base44 app's backend.
 - `@himalaya/biometrics` — Tier-5 typed binding to the platform's biometric authentication capability.
 - `@himalaya/browser-auth` — Tier-5 typed binding for native browser SSO.
 - `@himalaya/calendar` — Tier-5 typed binding for the device calendar.

package/guides/index.json

@@ -297,6 +297,12 @@
       "title": "Push notifications — optional setup and readiness checks",
       "category": "CLI & Loop",
       "file": "push-cli-onboarding.md"
+    },
+    {
+      "id": "iap-products",
+      "title": "Registering digital products as App Store in-app purchases",
+      "category": "CLI & Loop",
+      "file": "iap-products.md"
     }
   ],
   "componentReferenceFile": "component-reference.json",

package/guides/sdk-reference.json

@@ -309,6 +309,109 @@
       }
     ]
   },
+  {
+    "name": "@himalaya/base44",
+    "source": "core/sdk/base44/src/index.ts",
+    "description": "Tier-5 typed binding for a Base44 app's backend.",
+    "api": [
+      {
+        "name": "Json",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };"
+      },
+      {
+        "name": "JsonObject",
+        "kind": "type",
+        "jsdoc": "",
+        "decl": "export type JsonObject = { [key: string]: Json };"
+      },
+      {
+        "name": "Base44User",
+        "kind": "type",
+        "jsdoc": "/** A Base44 user record, as returned by `auth.me()`. Never carries a token. */",
+        "decl": "export type Base44User = JsonObject & { id?: string; email?: string; full_name?: string; role?: string };"
+      },
+      {
+        "name": "Base44Row",
+        "kind": "type",
+        "jsdoc": "/** An entity row. Base44 adds `id`, `created_date`, `updated_date`, `created_by`. */",
+        "decl": "export type Base44Row = JsonObject & { id?: string };"
+      },
+      {
+        "name": "ListOptions",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface ListOptions {\n  /** Field to sort by; prefix with `-` for descending (e.g. `\"-created_date\"`). */\n  sort?: string;\n  limit?: number;\n  skip?: number;\n  fields?: string[];\n}"
+      },
+      {
+        "name": "AuthStatus",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface AuthStatus {\n  signedIn: boolean;\n  user: Base44User | null;\n}"
+      },
+      {
+        "name": "LoginResult",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface LoginResult {\n  user: Base44User;\n}"
+      },
+      {
+        "name": "Base44Error",
+        "kind": "interface",
+        "jsdoc": "/** A rejected Base44 call. `status` is the HTTP status (0 when the request never got a reply).\n *  An `Error` with extra fields rather than a subclass: Tier-5 bundles target an engine\n *  profile without `class` syntax, so use {@link isBase44Error} instead of `instanceof`. */",
+        "decl": "export interface Base44Error extends Error {\n  name: \"Base44Error\";\n  status: number;\n  code: string;\n}"
+      },
+      {
+        "name": "base44Error",
+        "kind": "function",
+        "jsdoc": "/** Build a {@link Base44Error}. Exported for workers and hosts that need to raise one. */",
+        "decl": "export function base44Error(status: number, message: string, code: string): Base44Error;"
+      },
+      {
+        "name": "isBase44Error",
+        "kind": "function",
+        "jsdoc": "/** Whether `value` is a rejected Base44 call — the `instanceof` a bundle cannot use. */",
+        "decl": "export function isBase44Error(value: unknown): value is Base44Error;"
+      },
+      {
+        "name": "toBase44Error",
+        "kind": "function",
+        "jsdoc": "/** Normalize anything a native arm, the bridge, or the network produced into a Base44Error. */",
+        "decl": "export function toBase44Error(raw: unknown): Base44Error;"
+      },
+      {
+        "name": "auth",
+        "kind": "const",
+        "jsdoc": "",
+        "decl": "export const auth = {\n  /** Sign in with email + password. Native stores the token; you get the user. */\n  async loginViaEmailPassword(email: string, password: string): Promise<LoginResult> {\n    return unwrap<LoginResult>(await dispatch(\"capability.base44.authLoginViaEmailPassword\", { email, password }));\n  },\n  async register(email: string, password: string): Promise<JsonObject> {\n    return unwrap<JsonObject>(await dispatch(\"capability.base44.authRegister\", { email, password }));\n  },\n  /** Send a one-time login code to `email`. */\n  async loginViaOtp(email: string): Promise<JsonObject> {\n    return unwrap<JsonObject>(await dispatch(\"capability.base44.authLoginViaOtp\", { email }));\n  },\n  /** Verify the one-time code. Native stores the token; you get the user. */\n  async verifyOtp(email: string, otpCode: string): Promise<LoginResult> {\n    return unwrap<LoginResult>(await dispatch(\"capability.base44.authVerifyOtp\", { email, otpCode }));\n  },\n  /** Request a password-reset email. */\n  async resetPassword(email: string): Promise<void> {\n    unwrap<unknown>(await dispatch(\"capability.base44.authResetPassword\", { email }));\n  },\n  async me(): Promise<Base44User> {\n    return unwrap<Base44User>(await dispatch(\"capability.base44.authMe\"));\n  },\n  async updateMe(patch: JsonObject): Promise<Base44User> {\n    return unwrap<Base44User>(await dispatch(\"capability.base44.authUpdateMe\", { data: json(patch) }));\n  },\n  /** Whether a user is signed in, and who. Never rejects for a signed-out user. */\n  async status(): Promise<AuthStatus> {\n    const s = unwrap<Partial<AuthStatus> | nul\n/* … */"
+      },
+      {
+        "name": "EntityHandle",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface EntityHandle {\n  list(opts?: ListOptions): Promise<Base44Row[]>;\n  filter(query: JsonObject, opts?: ListOptions): Promise<Base44Row[]>;\n  get(id: string): Promise<Base44Row>;\n  create(data: JsonObject): Promise<Base44Row>;\n  update(id: string, patch: JsonObject): Promise<Base44Row>;\n  delete(id: string): Promise<void>;\n  bulkCreate(rows: JsonObject[]): Promise<Base44Row[]>;\n}"
+      },
+      {
+        "name": "entities",
+        "kind": "function",
+        "jsdoc": "/** Typed access to one entity of the configured Base44 app, e.g. `entities(\"Task\").list()`. */",
+        "decl": "export function entities(name: string): EntityHandle;"
+      },
+      {
+        "name": "functions",
+        "kind": "const",
+        "jsdoc": "",
+        "decl": "export const functions = {\n  /** Invoke a Base44 backend function by name. Resolves with its JSON reply. */\n  async invoke(name: string, data: JsonObject = {}): Promise<Json> {\n    if (!name) throw new Error(\"@himalaya/base44: functions.invoke: name is required\");\n    return unwrap<Json>(await dispatch(\"capability.base44.functionsInvoke\", { name, data: json(data) }));\n  },\n};"
+      },
+      {
+        "name": "version",
+        "kind": "const",
+        "jsdoc": "",
+        "decl": "export const version = 1;"
+      }
+    ]
+  },
   {
     "name": "@himalaya/biometrics",
     "source": "core/sdk/biometrics/src/index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1149.0",
+  "version": "0.1150.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": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "7dcb6d8baa768508ec09111079e55c159970ed86e7d815415c252815"
+  "falconPackageHash": "576a471c0c989054e6d74ba053f27d226189cdd8f88ec2feceeaadaa"
 }