@swell/apps-sdk 1.0.190 → 2.0.0-alpha.1

package/README.md

@@ -1,304 +1,238 @@
 # Swell Apps SDK
 
-The Swell Apps SDK is a TypeScript-based library designed to simplify the development of isomorphic Swell apps by providing streamlined API access, theme rendering capabilities, and comprehensive caching solutions.
-
-## Features
-
-### Core functionality
-- **Unified API access** - Seamless integration with both Swell Backend API and Storefront API
-- **Authentication handling** - Automatic scoped access token management based on app permissions
-- **Theme rendering** - Complete Shopify-compatible theme system with Liquid templating
-- **Resource management** - Deferred loading of storefront resources (products, categories, etc.)
-- **Caching system** - Multi-tier caching with Cloudflare KV integration
-- **Shopify compatibility** - Full compatibility layer for migrating Shopify themes and apps
-
-### Theme capabilities
-- **Liquid templating** - Enhanced Liquid engine with Swell-specific objects and filters
-- **Section rendering** - Dynamic section management with schema support
-- **Settings resolution** - Automatic theme and section settings processing
-- **Layout system** - Flexible layout rendering with section groups
-- **Asset management** - Optimized asset loading and URL generation
-- **Localization** - Multi-language support with translation rendering
-
-### Developer experience
-- **TypeScript support** - Full type safety with comprehensive type definitions
-- **Isomorphic design** - Works seamlessly in both browser and server environments
-- **Error handling** - Robust error management with detailed debugging information
-- **Performance optimized** - Built-in caching and resource optimization
-- **Extensible architecture** - Plugin system for custom resource types
+The Swell Apps SDK is a TypeScript library for building server-side Swell apps. It
+provides access to the Backend and Storefront APIs, along with helpers for app
+configuration, customer sessions and staff identity.
+
+Use it in Swell-hosted apps, Cloudflare Workers or Node.js servers. For browser
+applications, use [`swell-js`](https://github.com/swellstores/swell-js).
 
 ## Installation
 
-```bash
-npm install @swell/apps-sdk
+```sh
+npm install @swell/apps-sdk@next swell-js@^5.9.1
 ```
 
-## Getting started
-
-### Basic setup
-
-```typescript
-import { Swell } from '@swell/apps-sdk';
+Supports Node.js 22.22.2+ and Cloudflare Workers, with no Node compatibility flags
+needed in Workers. Includes ES modules, CommonJS and TypeScript declarations.
 
-// Initialize Swell instance in your app frontend
-const swell = new Swell({
-  serverHeaders: context.request.headers, // Headers from worker environment
-});
-
-// Make backend API calls
-const products = await swell.backend.get('/products');
+Version 2 replaces the 1.x theme API. Existing theme applications should remain on
+1.x until migrated to `@swell/themes-sdk`.
 
-// Make storefront API calls
-const cart = await swell.storefront.get('/cart');
-```
+## Getting started
 
-### Headers and app proxying
+### Request context
 
-When your Swell app is deployed, it runs behind Swell's proxy infrastructure. The proxy automatically injects essential headers that contain authentication tokens, store configuration, and storefront context. These headers are critical for the SDK to function properly:
+Swell supplies the current store's configuration, credentials and staff identity with
+each request. Verify this context once, then reuse it to create clients and check staff
+access. Use the same pattern for Swell-hosted and self-hosted frontends.
 
-```typescript
-// Headers passed from Swell's proxy contain:
-// - swell-store-id: The store identifier
-// - swell-public-key: Frontend API access key
-// - swell-access-token: Backend API access token (scoped to app permissions)
-// - swell-storefront-id: Current storefront instance
-// - swell-environment-id: Environment (development, staging, production)
-// - swell-theme-id: Active theme identifier
-// - swell-storefront-context: Preloaded cart/account data
+```ts
+import { verifySwellContext } from '@swell/apps-sdk';
 
-const swell = new Swell({
-  serverHeaders: context.request.headers, // Contains all proxy-injected headers
-  getCookie: (name) => getCookieValue(name),
-  setCookie: (name, value, options) => setCookieValue(name, value, options),
+const context = await verifySwellContext(request.headers, {
+  appId: 'my-app', // Your app's configured slug.
 });
 ```
 
-Without these headers, the SDK cannot:
-- Authenticate with Swell APIs
-- Determine which store and storefront to operate on
-- Access cached resources or maintain session state
-- Render themes with proper configuration
-
-The `serverHeaders` parameter should always be passed the complete headers object from your app's request context to ensure full functionality.
-
-### Theme rendering
-
-```typescript
-import { Swell, SwellTheme, SwellProduct } from '@swell/apps-sdk';
-
-const swell = new Swell({
-  serverHeaders: context.request.headers,
-  ...options,
-});
-
-// Initialize theme with optional configuration
-const theme = new SwellTheme(swell, {
-  forms: formConfigs,
-  resources: customResources,
-  globals: additionalGlobals,
-});
-
-// Fetch settings and set global context
-await theme.initGlobals('product'); // page ID
+In a server component, pass `await headers()`. Keep the context and clients on the
+server, scoped to the incoming request.
 
-// Create page data with deferred resource loading
-const data = {
-  product: new SwellProduct(swell, context.params.id),
-};
+### Backend API calls
 
-// Render theme page
-const renderedPage = await theme.renderPage(data);
-```
+```ts
+import { SwellBackendAPI } from '@swell/apps-sdk';
 
-## API reference
+// Reuse the context resolved for this request.
+const backend = new SwellBackendAPI({ context });
 
-### Swell class
-
-The main entry point for SDK functionality:
-
-```typescript
-class Swell {
-  // API access
-  backend: SwellBackendAPI;
-  storefront: typeof SwellJS;
-  
-  // Configuration
-  config: SwellAppConfig;
-  url: URL;
-  headers: Record<string, string>;
-  queryParams: ParsedQs;
-  
-  // State
-  isEditor: boolean;
-  isPreview: boolean;
-  storefrontContext: SwellData;
-  
-  // Methods
-  get<T>(url: string, query?: SwellData): Promise<T>;
-  post<T>(url: string, data: SwellData): Promise<T>;
-  put<T>(url: string, data: SwellData): Promise<T>;
-  delete<T>(url: string, data?: SwellData): Promise<T>;
-  getCachedResource<T>(key: string, args: unknown[], handler: () => T, isCacheble = true): Promise<T>;
-}
+// Fetch products from the Backend API.
+const products = await backend.get('/products', { limit: 10 });
 ```
 
-### SwellTheme class
-
-Handles theme rendering and management:
-
-```typescript
-class SwellTheme {
-  // Core properties
-  swell: Swell;
-  globals: ThemeGlobals;
-  liquidSwell: LiquidSwell;
-  
-  // Methods
-  initGlobals(pageId: string, altTemplate?: string): Promise<void>;
-  renderPage(pageData?: SwellData, altTemplate?: string): Promise<string>;
-  renderSection(sectionId: string, pageData?: SwellData): Promise<string>;
-  renderLayout(layoutName?: string, data?: SwellData): Promise<string>;
-  getSectionSchema(sectionName: string): Promise<ThemeSectionSchema>;
-  setGlobals(globals: Partial<ThemeGlobals>): void;
-}
-```
+For an external server, read credentials from your server configuration:
 
-### Resource classes
-
-Built-in storefront resource classes for deferred loading:
-
-#### Standard resources
-- `SwellAccount` - Customer account management
-- `SwellBlog` - Blog post content
-- `SwellBlogCategory` - Blog categorization
-- `SwellCart` - Shopping cart state
-- `SwellCategory` - Product categories
-- `SwellOrder` - Order information
-- `SwellPage` - Static pages
-- `SwellProduct` - Product details
-- `SwellVariant` - Product variants
-
-#### Primitive resources
-- `SwellStorefrontCollection` - Collection results with pagination
-- `SwellStorefrontRecord` - Individual records
-- `SwellStorefrontSingleton` - Unique resources (cart, account)
-
-```typescript
-// Create custom resource class
-class MyAppCollection extends SwellStorefrontCollection {
-  constructor(swell: Swell, query: SwellData = {}) {
-    super(swell, 'my-app-collection', query);
-    return this._getProxy();
-  }
-}
-
-// Usage in theme data
-const data = {
-  myCollection: new MyAppCollection(swell, { limit: 20 }),
-};
+```ts
+const backend = new SwellBackendAPI({ storeId, secretKey, apiHost });
 ```
 
-## Caching
+### Storefront API calls
 
-### Memory caching
-Resources are automatically cached in memory per worker instance:
+Use the Storefront API for customer-facing data and cart or account operations.
+In this example, `cookies` is your framework's cookie jar. Its reads must include
+pending writes and deletions.
 
-```typescript
-// Cached resource with custom handler
-const cachedData = await swell.getCachedResource(
-  'expensive-operation',
-  [param1, param2],
-  async () => {
-    return await performExpensiveOperation(param1, param2);
-  }
-);
-```
-
-### Cloudflare KV caching
-For production scalability, enable KV caching:
+```ts
+import { getStorefrontConfig } from '@swell/apps-sdk';
+import { createStorefrontClient } from '@swell/apps-sdk/storefront';
 
-```typescript
-const swell = new Swell({
-  serverHeaders: context.request.headers,
-  workerEnv: context.locals.runtime.env, // Contains THEME KV binding
-  workerCtx: context.locals.runtime.ctx,  // Worker context
+// Build public storefront configuration from the request context.
+const config = getStorefrontConfig(context);
+const storefront = createStorefrontClient(config, {
+  cookies: {
+    get: name => cookies.get(name)?.value,
+    set: (name, value, options) => { cookies.set(name, value, options); },
+  },
 });
+
+// Use the same methods available in swell-js.
+const products = await storefront.products.list({ limit: 10 });
 ```
 
-### Cache invalidation
-Caches are automatically invalidated based on:
-- Session cookies (for cart/account data)
-- Theme configuration versions
-- Storefront environment changes
+External servers can supply `storeId`, `publicKey` and `swell-js` options such as
+`url`, `locale` or `currency` directly as the config. Only the `/storefront` entry
+loads the `swell-js` runtime.
 
-## Shopify compatibility
+### Browser configuration
 
-The SDK includes comprehensive Shopify compatibility for theme migration.
+Send the public config from `getStorefrontConfig` to your browser app through a
+loader or endpoint with `Cache-Control: private, no-store`. Then initialize swell-js:
 
-### Supported Shopify features
-- **Template mapping** - Direct file path compatibility
-- **Liquid objects** - Full object structure compatibility
-- **Form handling** - Compatible form endpoints and validation
-- **Section schemas** - Shopify section configuration format
-- **Settings data** - `settings_data.json` and `settings_schema.json`
+```ts
+import swell from 'swell-js';
 
-## Liquid templating
+swell.init(config.storeId, config.publicKey, config);
+```
 
-Enhanced Liquid templating with Swell-specific features. See [Swell Liquid documentation](https://developers.swell.is/storefronts/swell-liquid-reference) for details.
+Send only this public config to the browser; the request context contains server credentials.
 
-## Performance optimization
+### Staff identity
 
-### Lazy loading
-Resources are loaded only when accessed in templates:
+Use `requireStaff` to check that a request belongs to a staff member of the current
+store before applying your application's permission checks:
 
-```liquid
-<!-- Product data is fetched only when this line executes -->
-{{ product.name }}
+```ts
+import { requireStaff } from '@swell/apps-sdk';
 
-<!-- Collection is fetched only when iteration begins -->
-{% for item in collection.products %}
-  {{ item.name }}
-{% endfor %}
+const staff = requireStaff(context); // { userId, storeId }, or a 401 SwellError.
+const optionalStaff = context.staff; // null for a visitor; no exception needed.
 ```
 
-## Development
-
-### Building the SDK
-```bash
-# Install dependencies
-npm install
+## API reference
 
-# Build for production
-npm run build
+### Backend client
 
-# Watch for changes
-npm run watch
+Pass `{ context }` for a frontend request, or explicit credentials for an external
+server. Backend calls require an access token or secret key and an absolute HTTP(S)
+`apiHost`. Do not mix input sources. Invalid constructor options throw immediately;
+all backend methods return promises and reject on failure.
+
+| Method | Result |
+| --- | --- |
+| `get(path, query?)` | Response data |
+| `post(path, data?)`, `put(path, data?)`, `delete(path, data?)` | Response data |
+| `settings(appId?)` | Installed-app settings; defaults to the configured app ID |
+| `workflows.create(name, params?)` | Created workflow instance |
+| `transaction(ops, options?)` | Operation results in input order |
+| `functions.call(appId, name, data?, options?)` | Function response payload |
+
+Response generics describe expected data without validating it. `SwellCollection<T>`
+is for ordinary paginated lists; aggregations and `page: false` return other shapes.
+
+Requests stay on the configured host; redirects are refused. Use endpoint paths,
+not absolute URLs. Request IDs are forwarded when supplied. GET queries use bracket
+notation, omit undefined values, encode Dates as ISO strings, and preserve native
+null separately from the string `'null'`. Other methods send JSON.
+
+**Workflows:** supplied parameters must be JSON-safe and at most 128 KiB of serialized
+UTF-8 JSON. Omitted parameters are not sent. Invalid or oversized parameters reject
+with `workflow_params_unserializable` or `workflow_params_too_large`.
+
+**Transactions:** each operation contains `method`, `url` and optional `data`.
+Retries are off by default. Set `retry: true` or
+`retry: { limit: 3, base: 100, max: 5000, jitter: true }` to enable them. These are the
+defaults: `limit` counts additional attempts, and delays are in milliseconds. Only
+`transaction_conflict` and `transaction_throttled` retry. Ordinary requests and network
+failures are not retried.
+
+**Private functions:** use the app slug from `context.appId` and authorize the caller
+first. `options.method` defaults to `post`; `get`, `put` and `delete` are also supported.
+GET data must contain only flat string, number or boolean values. Caller headers are
+not forwarded; response status and headers are not returned. Function errors and
+non-2xx statuses reject with `SwellError`.
+
+Private-app calls require platform support for app-slug lookup and fail on deployments
+without it. Function execution and `req.swell` remain managed by the CLI and platform.
+
+### Cookies and caching
+
+Cookie adapters exchange decoded values and own the current state. If your framework
+reads only incoming cookies, track pending writes and deletions in request-local state.
+The SDK keeps no cookie cache.
+
+Native cookie names and defaults apply: path `/`, one week, `sameSite: 'lax'`.
+`cookieOptions` replaces these defaults; `{}` delegates attributes to the adapter.
+Per-write attributes take precedence.
+
+Omit `cookies.set` for read-only access. Attempted writes then throw, including session
+rotation during GET requests. A supplied writer may throw or skip a write; after a skip,
+its reader must still report the actual state. Writer return values are ignored.
+Persist cookies in writable route handlers or actions.
+
+For API response caching, replace `storefront.request` before first use. The SDK
+leaves response caching to your application.
+
+### Request context options
+
+`verifySwellContext(headers, { env?, appId?, storeId?, vaultUrl? })` returns the request
+context or throws if verification fails. Set `appId` and, for a single-store app,
+`storeId` from trusted configuration to reject contexts intended for another app or
+store. Without these options, it verifies the source but does not restrict the
+destination. `vaultUrl` provides an optional vault endpoint override.
+
+Configuration is read from `process.env`, or from `env` when supplied. Workers without
+Node compatibility should pass their bindings as `env`.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SWELL_VERIFY_HEADERS` | enabled | Set exactly `"false"` to skip signature verification during local development. |
+| `SWELL_HEADERS_JWKS_URL` | `https://swell.store/.well-known/jwks.json` | Override the verification-key endpoint; its origin must match the token's issuer. |
+
+For local development against a local Swell instance, put `SWELL_VERIFY_HEADERS=false`
+in `.dev.vars`. Remove it or set it to `"true"` to restore verification. Token structure
+and claim validation still apply, but the context is no longer authenticated: anyone
+who can reach the frontend directly can supply forged context, including staff identity.
+Use this bypass only for local development.
+
+For server integrations, construct `SwellBackendAPI` with explicit credentials and
+`createStorefrontClient` with explicit public configuration. These clients do not
+require an HTTP request or staff identity.
+
+### Staff identity
+
+`requireStaff(context)` returns `{ userId, storeId }` or throws `SwellError` with
+status 401 and code `staff_required`. For optional staff access, read `context.staff`,
+which is null for visitors.
+
+Staff includes any signed-in dashboard user of the store, including partners and Swell
+support. Swell's proxy handles staff authentication and write-origin checks; your
+application decides what each staff member may do.
+
+### Errors
+
+Import `SwellError` from the root package. Use `status` and optional `code`/`body` for
+error handling; `message` is for people and may change.
+
+- Structured backend errors retain their body; string errors have no body.
+- HTTP-200 non-GET validation failures use status 400 and the `errors` field map as
+  `body`. Successful GET responses containing `errors` are returned as data.
+- Function invocation failures retain the response payload, or the invocation envelope
+  when the payload is null or absent, in `body`.
+- Header verification uses 401 / `invalid_swell_context` for absent, malformed, expired
+  or rejected tokens, and 503 / `swell_jwks_unavailable` for key-service failures.
+- Backend/storefront network errors remain native. Local configuration errors may be
+  ordinary `Error` instances; not every failure is a `SwellError`.
 
-# Run tests
-npm test
-```
+## Development
 
-### Project structure
-```
-src/
-├── api.ts              # Core Swell class and API handling
-├── theme.ts            # SwellTheme class and rendering
-├── resources.ts        # Storefront resource classes
-├── liquid/             # Liquid templating engine
-├── compatibility/      # Shopify compatibility layer
-├── cache/              # Caching implementations
-├── utils/              # Utility functions
-└── index.ts            # Main exports
+```sh
+npm ci
+npm run verify
 ```
 
-## Resources
-
-- [Swell Documentation](https://developers.swell.is/)
-- [Apps Development Guide](https://developers.swell.is/apps/overview)
-- [Proxima Example App](https://developers.swell.is/storefronts/proxima)
-- [Swell Liquid Reference](https://developers.swell.is/storefronts/swell-liquid-reference)
-- [GitHub Repository](https://github.com/swellstores/swell-apps-sdk)
+`verify` builds the SDK, runs unit tests and typechecks, then checks the packed package,
+browser/Worker boundaries and workerd execution.
 
-## 📄 License
+## License
 
-See the [LICENSE](LICENSE) file for details.
+[MIT](LICENSE)

package/dist/backend.d.cts

@@ -0,0 +1,81 @@
+import type { SwellRequestContext } from './request-context.cjs';
+export type SwellData = Record<string, any>;
+export type BackendOptions = {
+    context: SwellRequestContext;
+    storeId?: never;
+    apiHost?: never;
+    accessToken?: never;
+    secretKey?: never;
+    appId?: never;
+    requestId?: never;
+} | ({
+    context?: never;
+    storeId: string;
+    apiHost: string;
+    appId?: string;
+    requestId?: string;
+} & ({
+    accessToken: string;
+    secretKey?: never;
+} | {
+    secretKey: string;
+    accessToken?: never;
+}));
+/** Envelope of an ordinary paginated backend list. `page: false` and aggregations return other shapes. */
+export interface SwellCollection<T = SwellData> {
+    results: T[];
+    count: number;
+    page: number;
+    page_count: number;
+    limit: number;
+    pages?: Record<string, {
+        start: number;
+        end: number;
+    }>;
+}
+export interface TransactionOperation {
+    method: string;
+    url: string;
+    data?: any;
+}
+export interface TransactionOptions {
+    /** Opt in to retries: limit counts additional attempts (default 3); base/max are ms (100/5000); jitter defaults to true. */
+    retry?: true | {
+        limit?: number;
+        base?: number;
+        max?: number;
+        jitter?: boolean;
+    };
+}
+/** Backend client from a frontend request context or explicit server credentials. */
+export declare class SwellBackendAPI {
+    #private;
+    protected get userAgent(): string;
+    readonly workflows: {
+        /** Creates a workflow instance. Optional params must be JSON-safe and at most 128 KiB of UTF-8 JSON; invalid params reject. */
+        create: (name: string, params?: unknown) => Promise<SwellData>;
+    };
+    readonly functions: {
+        /**
+         * Invokes an app's private function from server code and resolves to its response payload,
+         * without the envelope's status or headers.
+         * `appId` is the app identifier from the request context (`context.appId`).
+         * `method` (default `post`) selects the function's handler. GET data reaches the function
+         * as query parameters, so its values must be flat strings, numbers or booleans.
+         * Throws `SwellError` when the function reports a non-2xx status or an error.
+         * Callers authorize the operation first; no caller headers are forwarded.
+         */
+        call: <T = SwellData>(appId: string, name: string, data?: SwellData, { method }?: {
+            method?: "get" | "post" | "put" | "delete";
+        }) => Promise<T>;
+    };
+    constructor(options: BackendOptions);
+    get<T = SwellData>(path: string, query?: SwellData): Promise<T>;
+    put<T = SwellData>(path: string, data?: any): Promise<T>;
+    post<T = SwellData>(path: string, data?: any): Promise<T>;
+    delete<T = SwellData>(path: string, data?: any): Promise<T>;
+    /** Reads installed-app settings; defaults to the configured app ID and rejects when neither ID is supplied. */
+    settings<T = SwellData>(appId?: string | undefined): Promise<T>;
+    /** Atomic operations returning results in operation order; only conflicts and throttling retry, and only when requested. */
+    transaction(ops: TransactionOperation[], options?: TransactionOptions): Promise<any[]>;
+}

package/dist/backend.d.ts

@@ -0,0 +1,81 @@
+import type { SwellRequestContext } from './request-context.js';
+export type SwellData = Record<string, any>;
+export type BackendOptions = {
+    context: SwellRequestContext;
+    storeId?: never;
+    apiHost?: never;
+    accessToken?: never;
+    secretKey?: never;
+    appId?: never;
+    requestId?: never;
+} | ({
+    context?: never;
+    storeId: string;
+    apiHost: string;
+    appId?: string;
+    requestId?: string;
+} & ({
+    accessToken: string;
+    secretKey?: never;
+} | {
+    secretKey: string;
+    accessToken?: never;
+}));
+/** Envelope of an ordinary paginated backend list. `page: false` and aggregations return other shapes. */
+export interface SwellCollection<T = SwellData> {
+    results: T[];
+    count: number;
+    page: number;
+    page_count: number;
+    limit: number;
+    pages?: Record<string, {
+        start: number;
+        end: number;
+    }>;
+}
+export interface TransactionOperation {
+    method: string;
+    url: string;
+    data?: any;
+}
+export interface TransactionOptions {
+    /** Opt in to retries: limit counts additional attempts (default 3); base/max are ms (100/5000); jitter defaults to true. */
+    retry?: true | {
+        limit?: number;
+        base?: number;
+        max?: number;
+        jitter?: boolean;
+    };
+}
+/** Backend client from a frontend request context or explicit server credentials. */
+export declare class SwellBackendAPI {
+    #private;
+    protected get userAgent(): string;
+    readonly workflows: {
+        /** Creates a workflow instance. Optional params must be JSON-safe and at most 128 KiB of UTF-8 JSON; invalid params reject. */
+        create: (name: string, params?: unknown) => Promise<SwellData>;
+    };
+    readonly functions: {
+        /**
+         * Invokes an app's private function from server code and resolves to its response payload,
+         * without the envelope's status or headers.
+         * `appId` is the app identifier from the request context (`context.appId`).
+         * `method` (default `post`) selects the function's handler. GET data reaches the function
+         * as query parameters, so its values must be flat strings, numbers or booleans.
+         * Throws `SwellError` when the function reports a non-2xx status or an error.
+         * Callers authorize the operation first; no caller headers are forwarded.
+         */
+        call: <T = SwellData>(appId: string, name: string, data?: SwellData, { method }?: {
+            method?: "get" | "post" | "put" | "delete";
+        }) => Promise<T>;
+    };
+    constructor(options: BackendOptions);
+    get<T = SwellData>(path: string, query?: SwellData): Promise<T>;
+    put<T = SwellData>(path: string, data?: any): Promise<T>;
+    post<T = SwellData>(path: string, data?: any): Promise<T>;
+    delete<T = SwellData>(path: string, data?: any): Promise<T>;
+    /** Reads installed-app settings; defaults to the configured app ID and rejects when neither ID is supplied. */
+    settings<T = SwellData>(appId?: string | undefined): Promise<T>;
+    /** Atomic operations returning results in operation order; only conflicts and throttling retry, and only when requested. */
+    transaction(ops: TransactionOperation[], options?: TransactionOptions): Promise<any[]>;
+}