Theme packages use the theme-engine JSON-contract bundle with LiquidJS rendering support. Apps use gateway app-store registration, app-platform manifest contracts, OAuth scope, webhook contracts, and the minimal createLetbuyyAppSdk wrapper in @letbuyy/api-client. CLI, browser bridge SDKs, and extension execution remain planned.
Theme packages use the JSON-contract bundle from `packages/theme-engine/src/theme-bundle.ts` and upload through `/v1/themes/packages/upload`. Liquid sections and blocks render through the LiquidJS-backed renderer in `packages/theme-engine/src/theme-renderer.ts`.
`config/settings_data.json` stores current and preset values.
`templates/*.json` references section and block instances across home, product, collection, page, cart, and blog templates.
`sections/manifest.json` and `blocks/definitions.json` define reusable section/block schemas.
`renderer.engine = liquid` is supported for Liquid templates; JSON-contract sections remain the portable configuration layer.
Merchant editor drafts are scoped by `template_key`, so editing Product does not overwrite Home.
`locales/*.json` stores translation dictionaries.
SKIP - EXTENSION EXECUTION
App manifest and extensions
The gateway app-store routes and `@letbuyy/shared-types` publish manifest schema `2026-06-05.ws13`, extension registry shapes, and lifecycle contract `2026-06-05.ws13.lifecycle`; live extension execution remains a recorded capability seam.
`POST /v1/app-store/developers/apps/manifest/validate` validates and normalizes manifests without creating an app.
Admin UI and Checkout UI extensions render through `@letbuyy/shared-types` sandbox policies.
Theme app blocks install as WS11 portable Liquid app blocks and require no storefront source changes.
Checkout Functions are advisory only; they cannot set arbitrary totals, taxes, line prices, or payment amounts.
Wasm/function execution is not available for production use; it remains recorded under the checkout extension capability seam.
Per-store registry rows expose `enabled`, `disabled`, and `revoked` lifecycle state.
Live contract
Extension lifecycle and observability
`GET /v1/app-store/installations/:id/extensions` returns extension/function rows plus a lifecycle snapshot, developer handoff, and app review checklist. Runtime metrics are optional-table safe and keyed by store, installation, app, registration, hook, and status.
`app_extension.lifecycle.status_changed` records merchant enable/disable state changes.
`app_function.execution.count`, `app_function.execution.duration_ms`, and `app_function.execution.failed_securely` record Function execution outcomes.
Uninstall revokes extension and Function registry rows, sets `revoked_at`, and removes them from public storefront/runtime resolution.
Marketplace app review packets include the same lifecycle checklist for platform operations.
Live contract
Minimal App SDK wrapper
`@letbuyy/api-client` exports `createLetbuyyAppSdk`, a small scoped-app wrapper over the versioned app API for installed app bearer tokens.
`sdk.products()` calls `/v1/app/products` with `read_products` scope.
`sdk.orders()` calls `/v1/app/orders` with `read_orders` scope.
`sdk.updateInstallationMetadata()` calls `/v1/app/installation/metadata` with `write_app_metadata` scope.
SKIP - NEEDS SDK/CLI
LetBuyy CLI
No tracked `@letbuyy/cli`, theme CLI, app CLI, or `create-letbuyy` package exists in the active workspace.
Use the JSON-contract schema and gateway upload endpoint until the SDK/CLI package exists.
Local dev generation remains a planned SDK/CLI artifact.
Do not publish CLI commands in docs as available until the package exists.
Live contract
Partner API keys
The gateway issues show-once app developer credentials during app submission and can rotate a show-once app API key for an owned app. Plaintext keys are never documented as persisted; the backend stores hash-only credential metadata.
`POST /v1/app-store/developers/apps` returns `credentials` with `oauth_client_id`, show-once `client_secret`, and show-once `api_key`.
`POST /v1/app-store/developers/apps/:id/api-key` rotates the show-once API key for an app owned by the current developer profile.
Credential metadata is stored hash-only in gateway-owned app records; plaintext keys must be copied by the developer at creation time.
Build your first integration
The current manual path
Until a real CLI ships, the safe path is to author JSON against the package-owned schemas, validate the app manifest through the versioned gateway, submit it for review, and verify install OAuth against the app-store routes.
1. Theme
Create a JSON-contract bundle with package metadata, settings schema/data, templates, Liquid or JSON sections, blocks, locales, and renderer manifest.
2. App
Register a developer profile, validate and submit a marketplace app manifest, copy the show-once credentials, then install through app OAuth authorization code flow. Checkout Functions can advise coupons, shipping, payment method availability, and validation only. Extension execution stays a recorded capability seam until its runtime is deliberately scoped.
3. Webhooks
Use HTTPS webhook targets, verify the HMAC signature, dedupe by event id, and handle mandatory compliance topics.
