Theme SDK and App SDK

Quick-starts for the contracts that exist now

Theme packages use the theme-engine JSON-contract bundle with LiquidJS rendering support. Apps use app-engine registration, app extension, app block, checkout-function, OAuth scope, webhook contracts, and the minimal createLetbuyyAppSdk wrapper in @letbuyy/api-client. CLI and full browser bridge SDKs remain planned.

{
  "schema_version": "2026-05-json-contract",
  "package": {
    "slug": "starter-commerce",
    "name": "Starter Commerce",
    "author_name": "Example Studio",
    "site_types": ["store"],
    "pricing_type": "free",
    "currency": "INR",
    "version": "1.0.0"
  },
  "config": {
    "settings_schema": {
      "settings": {
        "brand": {
          "label": "Brand",
          "fields": {
            "accent": { "type": "color", "label": "Accent", "default": "rgb(15 118 110)" }
          }
        }
      }
    },
    "settings_data": { "current": {}, "presets": {} }
  },
  "templates": {
    "index": {
      "sections": {
        "hero": { "type": "hero", "settings": {}, "blocks": {}, "block_order": [] }
      },
      "order": ["hero"]
    }
  },
  "sections": {
    "hero": {
      "type": "hero",
      "name": "Hero",
      "liquid_template": "<section>{{ section.settings.heading }}</section>",
      "renderer_key": "hero",
      "settings_schema": {},
      "block_types": []
    }
  },
  "blocks": {},
  "locales": { "en": {} }
}

Live contract

Theme bundle contract

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_schema.json` defines grouped editable settings.
`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.

Live contract

App manifest and extensions

App-engine publishes manifest schema `2026-06-05.ws13`, the extension registry, and lifecycle contract `2026-06-05.ws13.lifecycle` for Admin UI, Checkout UI, theme app blocks, and Wasm Functions.

`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/extension-host` sandbox policies.
Theme app blocks install as WS11 portable Liquid app blocks and require no storefront source changes.
Checkout Functions are advisory only: they can apply discount codes, select shipping methods, restrict payment methods, and return validation errors; they cannot set arbitrary totals, taxes, line prices, or payment amounts.
Wasm Functions use HTTPS module URLs, SHA-256 verification, no imports, typed JSON I/O, and 1-5ms budgets.
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 for now.
Local dev scaffolding 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.

3. Webhooks

Use HTTPS webhook targets, verify the HMAC signature, dedupe by event id, and handle mandatory compliance topics.

Quick-starts for the contracts that exist now

{ "schema_version": "2026-05-json-contract", "package": { "slug": "starter-commerce", "name": "Starter Commerce", "author_name": "Example Studio", "site_types": ["store"], "pricing_type": "free", "currency": "INR", "version": "1.0.0" }, "config": { "settings_schema": { "settings": { "brand": { "label": "Brand", "fields": { "accent": { "type": "color", "label": "Accent", "default": "rgb(15 118 110)" } } } } }, "settings_data": { "current": {}, "presets": {} } }, "templates": { "index": { "sections": { "hero": { "type": "hero", "settings": {}, "blocks": {}, "block_order": [] } }, "order": ["hero"] } }, "sections": { "hero": { "type": "hero", "name": "Hero", "liquid_template": "<section>{{ section.settings.heading }}</section>", "renderer_key": "hero", "settings_schema": {}, "block_types": [] } }, "blocks": {}, "locales": { "en": {} } }