Theme SDK and App SDK

Quick-starts for the contracts that exist now

Theme packages use the theme-engine JSON-contract bundle. Apps use app-engine registration, app extension, app block, OAuth scope, and webhook contracts. CLI and package SDKs are marked planned until they exist in the active workspace.

{
  "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": "#0f766e" }
          }
        }
      }
    },
    "settings_data": { "current": {}, "presets": {} }
  },
  "templates": {
    "index": {
      "sections": {
        "hero": { "type": "hero", "settings": {}, "blocks": {}, "block_order": [] }
      },
      "order": ["hero"]
    }
  },
  "sections": {
    "hero": {
      "type": "hero",
      "name": "Hero",
      "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`.

`config/settings_schema.json` defines grouped editable settings.
`config/settings_data.json` stores current and preset values.
`templates/*.json` references section and block instances.
`sections/manifest.json` and `blocks/definitions.json` define reusable section/block schemas.
`locales/*.json` stores translation dictionaries.

Live contract

App manifest and extensions

App-engine supports developer registration, marketplace app submissions, admin embed extensions, app blocks, OAuth scopes, and lifecycle webhook planning.

Admin embed extensions resolve URL, label, target, and bridge capabilities from app extension config.
Storefront app blocks carry app id, extension id, slot, render mode, settings, and optional iframe URL.
Scopes are validated against `marketplace_apps.api_scopes` during install authorization.

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.

SKIP - NEEDS BACKEND

Partner API keys

The gateway exposes OAuth tokens and bridge tokens for installed apps, but a self-serve API key inventory/rotation endpoint is not present.

Dashboard shell renders this as a planned capability.
Do not claim key creation, key reveal, or rotation until backend endpoints exist.
Future data must remain behind versioned `/v1` contracts.

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, submit through the versioned gateway, and verify install OAuth against the app-store routes.

1. Theme

Create a JSON-contract bundle with package metadata, settings schema/data, templates, sections, blocks, locales, and renderer manifest.

2. App

Register a developer profile, submit a marketplace app with scopes and extension config, then install through app OAuth authorization code flow.

3. Webhooks

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