@loopwise/sdk 0.1.0-beta.2 → 0.1.0-beta.4

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to `@loopwise/sdk` are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning: [SemVer](https://semver.org/) with pre-1.0 semantics — minor bumps
+(`0.x → 0.x+1`) may include breaking changes; beta tags (`0.1.0-beta.N`)
+follow the same rules as a single 0.x line.
+
+## [Unreleased]
+
+## [0.1.0-beta.4] — 2026-09-10
+
+Storefront schema pinning for browser clients. A design partner could
+not tell a honoured `API-Version` pin from an ignored header because the
+same-origin `/api/graphql` proxy dropped it (TEACH-22755, #16417); the
+proxy now forwards it, answers the CORS preflight for off-origin callers
+(TEACH-22760, #16429), and this release gives the SDK a first-class way
+to send the pin.
+
+### Added
+
+- `LoopwiseConfig.apiVersion` — pins the storefront schema to a release
+  date. Sent as the `API-Version` header on every request (GET and POST);
+  the server echoes the resolved version in the `API-Version` response
+  header. A blank value throws `LoopwiseError` code `'CONFIG'` at
+  `createClient()`, because the server would treat it as absent and serve
+  the baseline silently. (TEACH-22755)
+
+### Changed
+
+- **Breaking:** a non-2xx response whose body is a GraphQL errors payload
+  (objects with a `message`) now raises `LoopwiseError` with code
+  `'GRAPHQL'` and the errors on `graphqlErrors`, instead of `'NETWORK'` /
+  `Upstream <status>`. The first such response is the 400
+  `INVALID_API_VERSION` for a malformed `apiVersion`. Migration: code that
+  retries or branches on `code === 'NETWORK'` for a 4xx/5xx carrying a
+  GraphQL body should also handle `'GRAPHQL'` (check
+  `graphqlErrors[0].extensions.code` for the server's reason). Status
+  precedence is unchanged: 401/403 stay `'AUTH'` and 429 stays
+  `'RATE_LIMIT'` whatever their body, and other non-2xx responses without a
+  GraphQL body stay `'NETWORK'`.
+
+## [0.1.0-beta.3] — 2026-05-20
+
+### Added
+
+- `LoopwiseConfig.site` — preferred name for the site this client reads
+  from. Accepts a subdomain (`'acme'`) or full domain
+  (`'acme.myteachify.com'`, `'nii.school'`). Replaces the deprecated
+  `tenant` field; both fields are accepted, `site` wins when both are set.
+- `LoopwiseError.site` — mirror of the deprecated `tenant` property.
+  Catch-and-read consumers can migrate at their own pace.
+
+### Deprecated
+
+- `LoopwiseConfig.tenant` — renamed to `site`. Both fields still work;
+  `site` wins when both are set. **Removed in `0.2.0`.**
+- `LoopwiseError.tenant` — renamed to `site`. **Removed in `0.2.0`.**
+
+### Removed
+
+- `LoopwiseErrorCode = '…' | 'TENANT_NOT_FOUND'` — the literal was never
+  emitted by any SDK code path (it was a reserved/aspirational shape
+  that never got runtime mapping). Removed instead of renaming to
+  `'SITE_NOT_FOUND'` — no point preserving phantom API surface. If a
+  future SDK release adds actual runtime mapping (e.g. translating
+  Rails' `School-000` GraphQL error into a typed code), the canonical
+  `'SITE_NOT_FOUND'` literal will be added then. Removal is type-only
+  (narrowing checks like `case 'TENANT_NOT_FOUND':` were unreachable
+  branches in any consumer code).
+
+### Changed (non-breaking)
+
+- README + every user-visible JSDoc reframed to use "site" language
+  instead of "tenant" / "multi-tenant" / "BFF derives tenant from host"
+  — SDK consumers don't need to learn the platform's multi-tenancy
+  model, just the SDK's behaviour and limits (`createClient({})` reads
+  from the page's own site; `createClient({ site: '…' })` reads from a
+  different site at the cost of authenticated calls).
+
+## [0.1.0-beta.2] — 2026-05-19
+
+### Fixed
+
+- `orders.get` returns `null` from a null GraphQL payload instead of
+  throwing.
+- `orders.get` passes the `id` as an inline GraphQL argument rather than
+  a `$variable`, avoiding collision when composed via `batch()`.
+
+### Documentation
+
+- `orders.get` JSDoc clarifies `OrderItem.amount` is per-unit price
+  (not line total), and null-guards the `tradeNo` URL-param lookup
+  example.
+
+## [0.1.0-beta.1] — 2026-05-05
+
+Initial public beta. `courses.list/get`, `posts.list/get`, `orders.get`,
+`batch()`, raw `query()`. Schema-lock pipeline. Same-origin BFF and
+explicit cross-origin endpoint resolution.
+
+[Unreleased]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.4...HEAD
+[0.1.0-beta.4]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.3...@loopwise/sdk@0.1.0-beta.4
+[0.1.0-beta.3]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.2...@loopwise/sdk@0.1.0-beta.3
+[0.1.0-beta.2]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.1...@loopwise/sdk@0.1.0-beta.2
+[0.1.0-beta.1]: https://github.com/kaikhq/manekineko/compare/@loopwise/sdk@0.1.0-beta.0...@loopwise/sdk@0.1.0-beta.1

package/README.md

@@ -6,7 +6,7 @@ Storefront GraphQL client for Loopwise / Teachify. Pick your path:
 |---|---|---|
 | A single self-contained HTML file (no build step — for `deploy_static_page`, a Claude Design artifact, or a CodePen) | none — load from a CDN | `https://esm.sh/@loopwise/sdk@beta` |
 | A project with a bundler (Vite / Astro / Next.js / Remix) | `npm install @loopwise/sdk@beta` | `@loopwise/sdk` |
-| **React** UI in either of the above | (see [`@loopwise/sdk-react`](#react--coming-soon)) | — |
+| **React** UI in either of the above | (see [`@loopwise/react`](#react--coming-soon)) | — |
 
 Same package powers all three; the difference is the loader.
 
@@ -15,15 +15,15 @@ Same package powers all three; the difference is the loader.
 ```ts
 import { createClient } from '@loopwise/sdk';
 
-// Browser, same-origin (the page is served from the tenant origin):
+// Reads from the site this page is on. No config needed.
 const loopwise = createClient({});
 const { items } = await loopwise.courses.list({ limit: 20 });
 ```
 
-That's the entire happy path **when the page is served from the tenant
-origin** (`acme.kaik.io`, `acme.myteachify.com`, `nii.school`, etc.). The BFF
-on that origin derives the tenant from the request host and binds it to the
-response on the trusted server side.
+That's it. The SDK calls the site that's serving the page
+(`acme.kaik.io`, `acme.myteachify.com`, `nii.school`, etc.) and the
+site's API binds the response to itself — you never identify the site
+yourself. To call a different site, see [Calling a different site](#calling-a-different-site).
 
 ## Quick start — single-file HTML (no build)
 
@@ -32,44 +32,57 @@ response on the trusted server side.
 <script type="module">
   import { createClient } from 'https://esm.sh/@loopwise/sdk@beta';
 
-  // Same-origin variant — works when the HTML is served from the tenant origin
-  // (e.g. acme.kaik.io). Empty config; BFF derives the tenant from host.
+  // Reads from the site this HTML is loaded on.
   const loopwise = createClient({});
   const { items } = await loopwise.courses.list({ limit: 20 });
   document.body.textContent = items.map(c => c.title).join(', ');
 </script>
 ```
 
-## Cross-origin (Loopwise Pages preview, SSR, build pipelines)
+## Calling a different site
 
-When the SDK runs **outside** a tenant origin, pass `tenant` explicitly so
-the SDK can pick the right Rails origin to call.
+When your code runs **somewhere other than the site itself** — a Loopwise
+Pages preview at `<scriptName>.loopwise.page`, a build / SSR pipeline,
+server-to-server tooling — name the site you want to read from:
 
 ```ts
 const loopwise = createClient({
-  tenant: 'acme',                       // required cross-origin
-  apiKey: process.env.LOOPWISE_API_KEY, // required in SSR / build (browser ignores)
+  site: 'acme',                          // 'acme' or 'acme.myteachify.com'
+  apiKey: process.env.LOOPWISE_API_KEY,  // build/SSR only; browser ignores
 });
 ```
 
-### Where this matters most: `deploy_static_page`
+`site` accepts a subdomain (`'acme'`) or a full domain
+(`'acme.myteachify.com'`, `'nii.school'`). The SDK uses it to pick the
+right API origin.
 
-Pages deployed via `deploy_static_page` live at `https://<script>.loopwise.page/`
-— that is **not** a tenant origin, so:
+### Limits when not on the site itself
 
-- The BFF same-origin trick does not apply. You **must** pass `tenant`.
-- Browser cross-origin requests carry no first-party cookies, so anything
-  that requires a logged-in viewer (`cart`, `viewer.profile`,
-  authenticated mutations) **will not work** at preview time.
-- Public, anonymous reads (`courses.list`, `posts.list`, etc.) are fine.
+Cross-origin requests **do not carry first-party cookies**. So calls
+that require a signed-in visitor — `cart`, `viewer.profile`,
+authenticated mutations — **will not work** from off-site code.
+Public, anonymous reads (`courses.list`, `posts.list`, etc.) work fine.
+
+The site's `/api/graphql` answers the browser's CORS preflight with a
+static `Access-Control-Allow-Origin: *` and no credentials. The
+`Access-Control-Allow-Headers` grant names the non-safelisted headers
+this SDK sends (`content-type` with a JSON value, `api-version`,
+`x-loopwise-cache`); CORS-safelisted headers such as `Accept` need no
+grant. A hand-rolled `fetch` that adds any other non-safelisted header
+(`Authorization`, for one) fails the preflight, and
+`credentials: 'include'` is refused by the browser. The response exposes
+`API-Version` and `X-Request-Id`.
+
+This is the dominant case for `deploy_static_page` bundles (which
+serve at `<scriptName>.loopwise.page`):
 
 ```ts
 // Inside an HTML bundle deployed to https://lw-acme-home.loopwise.page/
-const loopwise = createClient({ tenant: 'acme' });
+const loopwise = createClient({ site: 'acme' });
 const { items } = await loopwise.courses.list({ limit: 20 }, { cache: 60 });
 ```
 
-For preview UX that needs authenticated state, see
+For preview UX that needs an authenticated viewer, see
 [Preview modes](#preview-modes) below.
 
 ## `cache` option
@@ -120,30 +133,60 @@ is the explicit, type-system-visible declaration of "this must never be cached".
 per Vercel POP, depending on traffic. Use shorter TTLs for time-sensitive
 content; use `cache: 'no-store'` for admin previews.
 
+## `apiVersion` option
+
+The storefront schema is versioned by release date. Pin the one your code
+was built against and the SDK sends it as the `API-Version` header on
+every request, GET and POST alike:
+
+```ts
+const loopwise = createClient({ apiVersion: '2027-01-01' });
+```
+
+Omit it to get the baseline schema. The server echoes the version it
+resolved in the `API-Version` response header (and lists the header in
+`Vary`), and this holds through the same-origin `/api/graphql` proxy too.
+The SDK's methods return parsed data only and do not surface response
+headers, so confirm the pin once with the browser's network inspector or
+a direct `fetch` to the same endpoint, not through an SDK return value:
+
+```ts
+const res = await fetch('/api/graphql', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json', 'API-Version': '2027-01-01' },
+  body: JSON.stringify({ query: '{ __typename }' }),
+});
+res.headers.get('API-Version'); // '2027-01-01' when the pin is honoured
+```
+
+A value that is not a date is rejected with a 400 whose body is a GraphQL
+errors payload; the SDK raises it as a `LoopwiseError` with code
+`'GRAPHQL'` and `graphqlErrors[0].extensions.code === 'INVALID_API_VERSION'`,
+so a malformed pin does fail loudly through the SDK.
+
 ## Preview modes
 
 Two preview surfaces exist, each with different capability:
 
-| Surface | Origin | Same-origin BFF? | Authenticated viewer? | Use for |
+| Surface | URL | Hosted on the site? | Authenticated viewer? | Use for |
 |---|---|---|---|---|
-| **Loopwise Pages preview** | `<scriptName>.loopwise.page` | ❌ cross-origin | ❌ no first-party cookies | Anonymous storefront, marketing pages, public listings |
-| **Tenant-origin preview** | `<tenant-origin>/_preview/<scriptName>/` | ✅ same-origin | ✅ admin can preview as a logged-in viewer | Cart, checkout, member-gated content, full storefront |
+| **Loopwise Pages preview** | `<scriptName>.loopwise.page` | ❌ separate origin | ❌ no first-party cookies | Anonymous storefront, marketing pages, public listings |
+| **Site-origin preview** | `<site>/_preview/<scriptName>/` | ✅ same origin as the site | ✅ admins can preview signed in | Cart, checkout, member-gated content, full storefront |
 
-The tenant origin can be `<sub>.kaik.io`, `<sub>.myteachify.com`, or a
-custom FQDN like `nii.school`. `deploy_static_page` returns both
-surfaces (`preview_url` + `tenant_preview_url_template` with a
-`<TENANT_ORIGIN>` placeholder).
+The site URL can be `<sub>.kaik.io`, `<sub>.myteachify.com`, or a custom
+domain like `nii.school`. `deploy_static_page` returns both URLs in its
+response.
 
-Pick the surface that matches what you're testing — anonymous storefront
-reads on Surface A (faster, edge-cacheable), authenticated flows on
-Surface B (logged-in only, never edge-cached). Surface B requires
-relative asset paths in your bundle (the proxy injects `<base>` so
-relative paths resolve under `/_preview/<scriptName>/`; root-absolute
-paths like `/style.css` still go to the tenant root and 404).
+Pick the surface that matches what you're testing — anonymous reads on
+Surface A (faster, edge-cacheable), authenticated flows on Surface B
+(signed-in only, never edge-cached). Surface B requires relative asset
+paths in your bundle (the proxy injects `<base>` so relative paths
+resolve under `/_preview/<scriptName>/`; root-absolute paths like
+`/style.css` still go to the site root and 404).
 
 ## React — coming soon
 
-A `@loopwise/sdk-react` companion package is planned, providing:
+A `@loopwise/react` companion package is planned, providing:
 
 - `<LoopwiseProvider client={loopwise}>` context provider
 - `useCourses({ limit })`, `useCourse({ slug })` hooks with Suspense support
@@ -155,10 +198,12 @@ your own state (`useEffect` + `useState`, TanStack Query, etc.).
 
 ## Public API
 
-- `createClient(config)` — storefront client. `config.tenant` is optional in
-  the browser when the page is on a tenant origin (BFF derives it from
-  host); required cross-origin and in SSR / build.
+- `createClient(config)` — storefront client. Pass `config.site` only
+  when calling a different site than the one your code is running on
+  (see [Calling a different site](#calling-a-different-site)).
 - `loopwise.courses.list(args, options?)` / `.get(args, options?)`.
+- `loopwise.posts.list(args, options?)` / `.get(args, options?)`.
+- `loopwise.orders.get(args, options?)` — post-checkout pixel-tracking pattern; see the method's JSDoc for the `?tradeNo=…` → `fbq('track', 'Purchase', …)` recipe.
 - `loopwise.batch(builders, options?)` — composes N queries into one HTTP request.
 - `loopwise.query<T>(document, variables?, operationName?, options?)` — raw GraphQL escape hatch.
 

package/dist/config.d.mts

@@ -1,10 +1,22 @@
 //#region src/config.d.ts
 interface LoopwiseConfig {
   /**
-   * Tenant identifier (subdomain "acme" or full FQDN "nii.school").
+   * The site this client reads from. Accepts a subdomain (`'acme'`) or a
+   * full domain (`'acme.myteachify.com'`, `'nii.school'`).
    *
-   * Optional in browser runtime — SDK auto-resolves from `window.location.hostname`
-   * (e.g. `acme.kaik.io` -> `"acme"`). Required in build/SSR runtime.
+   * Omit when your code runs on the site itself — the SDK calls the
+   * page's own origin. Required when running off-origin: cross-domain
+   * embeds (Loopwise Pages previews at `*.loopwise.page`), SSR / build
+   * pipelines, server-to-server tooling.
+   *
+   * Cross-origin requests carry no first-party cookies, so authenticated
+   * calls (`cart`, `viewer.profile`, mutations that need a signed-in
+   * visitor) won't work in that mode — public reads do.
+   */
+  site?: string;
+  /**
+   * @deprecated Renamed to `site`. Both fields work for now; if both are
+   * set, `site` wins. **Will be removed in `0.2.0`.**
    */
   tenant?: string;
   /**
@@ -15,11 +27,22 @@ interface LoopwiseConfig {
    */
   apiKey?: string;
   /**
-   * Override the GraphQL endpoint. Defaults to:
-   *   - Browser: same-origin `/api/graphql`
-   *   - Build/SSR: `https://{tenant}/api/graphql` (or kaik.io fallback)
+   * Override the GraphQL endpoint. You normally never set this — the SDK
+   * picks the right URL from `site` (or the page's own origin when `site`
+   * is omitted).
    */
   endpoint?: string;
+  /**
+   * Pin the storefront schema to a release date (`'2027-01-01'`). Sent as
+   * the `API-Version` header on every request; omit it to get the baseline
+   * schema. The server echoes the resolved version in the `API-Version`
+   * response header; SDK methods return parsed data only, so read that
+   * header with a network inspector or a direct `fetch`. A value that is
+   * not a date is rejected with a 400 whose GraphQL error carries
+   * `extensions.code: 'INVALID_API_VERSION'` (surfaced as a
+   * `LoopwiseError` with code `'GRAPHQL'`).
+   */
+  apiVersion?: string;
 }
 declare function defineConfig(config: LoopwiseConfig): LoopwiseConfig;
 //#endregion

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 import { LoopwiseConfig } from "./config.mjs";
-
 //#region src/error.d.ts
-type LoopwiseErrorCode = 'NETWORK' | 'AUTH' | 'GRAPHQL' | 'RATE_LIMIT' | 'TENANT_NOT_FOUND' | 'CONFIG';
+type LoopwiseErrorCode = "NETWORK" | "AUTH" | "GRAPHQL" | "RATE_LIMIT" | "CONFIG";
 interface GraphQLError {
   message: string;
   path?: (string | number)[];
@@ -9,11 +8,16 @@ interface GraphQLError {
 }
 declare class LoopwiseError extends Error {
   readonly code: LoopwiseErrorCode;
+  /** The site this client was configured for. */
+  readonly site?: string;
+  /** @deprecated Renamed to `site`. Holds the same resolved value. Removed in 0.2.0. */
   readonly tenant?: string;
   readonly endpoint?: string;
   readonly graphqlErrors?: GraphQLError[];
   readonly requestId?: string;
   constructor(code: LoopwiseErrorCode, message: string, detail?: {
+    site?: string;
+    /** @deprecated Renamed to `site`. Removed in 0.2.0. */
     tenant?: string;
     endpoint?: string;
     graphqlErrors?: GraphQLError[];
@@ -22,9 +26,9 @@ declare class LoopwiseError extends Error {
 }
 //#endregion
 //#region src/select.d.ts
-type SelectionInner<T> = T extends Array<infer U> ? SelectionInner<U> : T extends object ? { [K in keyof T]?: SelectionInner<T[K]> } : true;
+type SelectionInner<T> = T extends Array<infer U> ? SelectionInner<U> : T extends object ? { [K in keyof T]?: SelectionInner<T[K]>; } : true;
 type Selection<T> = SelectionInner<NonNullable<T>>;
-type SelectedInner<T, S> = T extends null | undefined ? T : S extends true ? T : T extends Array<infer U> ? Array<SelectedInner<U, S>> : T extends object ? { [K in keyof S & keyof T]: SelectedInner<T[K], S[K]> } : T;
+type SelectedInner<T, S> = T extends null | undefined ? T : S extends true ? T : T extends Array<infer U> ? Array<SelectedInner<U, S>> : T extends object ? { [K in keyof S & keyof T]: SelectedInner<T[K], S[K]>; } : T;
 type Selected<T, S> = SelectedInner<T, S>;
 //#endregion
 //#region src/query.d.ts
@@ -60,7 +64,7 @@ interface FetchOptions {
    * `Cache-Control: public, s-maxage=<seconds>`. `'no-store'` forces POST and
    * skips any cache hint. Omit for the legacy POST behaviour.
    */
-  cache?: number | 'no-store';
+  cache?: number | "no-store";
 }
 interface BatchedFetcher {
   /**
@@ -79,9 +83,7 @@ declare class QueryBuilder<T> implements PromiseLike<T> {
 //#endregion
 //#region src/client.d.ts
 declare class LoopwiseClient implements BatchedFetcher {
-  readonly config: {
-    tenant?: string;
-  } & LoopwiseConfig;
+  readonly config: LoopwiseConfig;
   private endpoint;
   constructor(config: LoopwiseConfig);
   private defaultEndpoint;
@@ -94,7 +96,7 @@ declare class LoopwiseClient implements BatchedFetcher {
   raw<T = unknown>(document: string, variables?: Record<string, unknown>, operationName?: string, options?: FetchOptions): Promise<T>;
   batch<R extends Record<string, unknown>>(builders: { [K in keyof R]: {
     descriptor: QueryDescriptor;
-  } }, options?: FetchOptions): Promise<R>;
+  }; }, options?: FetchOptions): Promise<R>;
   private fetchGraphQL;
   private shouldUseGet;
   private buildGetUrl;
@@ -142,7 +144,7 @@ interface Post {
   /** Known values: `login_required`, `paid`, `public_access`. The
    * `string & {}` escape hatch keeps autocomplete on the known set
    * while accepting forward-compat values the schema may add. */
-  accessType: 'login_required' | 'paid' | 'public_access' | (string & {});
+  accessType: "login_required" | "paid" | "public_access" | (string & {});
   tags: string[] | null;
   noindex: boolean;
   author: Lecturer | null;
@@ -159,7 +161,7 @@ interface ListResult<T> {
   pageInfo: PageInfo;
 }
 /** Simplified order status. Mirrors the storefront `Order.status` enum. */
-type OrderStatus = 'PAID' | 'PENDING' | 'FAILED' | 'REFUNDED';
+type OrderStatus = "PAID" | "PENDING" | "FAILED" | "REFUNDED";
 interface OrderItem {
   /**
    * Meta-pixel-aligned identifier (Lineitem#tracking_id server-side).
@@ -201,7 +203,7 @@ declare class CoursesResource {
   private client;
   constructor(client: LoopwiseClient);
   /**
-   * List courses for the current tenant.
+   * List published courses.
    * @example
    * const { items, pageInfo } = await loopwise.courses.list({ limit: 20 })
    * @example
@@ -248,9 +250,8 @@ declare class OrdersResource {
    * Look up a PII-safe order projection by id (the value the storefront
    * appends to a merchant's `checkoutSuccessUrl` as `?tradeNo=...`).
    *
-   * Returns `null`-shaped result via the GraphQL `null` payload when the
-   * id doesn't resolve in the current tenant — does NOT throw. Use the
-   * returned `status` to gate Meta Pixel `Purchase` events:
+   * Returns `null` when the id doesn't resolve on this site — does NOT
+   * throw. Use the returned `status` to gate Meta Pixel `Purchase` events:
    *
    * @example
    * const id = new URLSearchParams(location.search).get('tradeNo');
@@ -289,7 +290,7 @@ declare class PostsResource {
   private client;
   constructor(client: LoopwiseClient);
   /**
-   * List published posts for the current tenant, ordered by publishedAt desc.
+   * List published posts, ordered by publishedAt desc.
    * @example
    * const { items, pageInfo } = await loopwise.posts.list({ limit: 10 })
    * @example
@@ -330,13 +331,22 @@ interface Loopwise {
    *   recent:   loopwise.courses.list({ limit: 3, page: 2 }),
    * }, { cache: 60 })
    */
-  batch<R extends Record<string, QueryBuilder<unknown>>>(builders: R, options?: FetchOptions): Promise<{ [K in keyof R]: R[K] extends QueryBuilder<infer T> ? T : never }>;
+  batch<R extends Record<string, QueryBuilder<unknown>>>(builders: R, options?: FetchOptions): Promise<{ [K in keyof R]: R[K] extends QueryBuilder<infer T> ? T : never; }>;
   /**
    * Raw GraphQL escape hatch. Use when a typed resource method doesn't cover
    * what you need (new schema fields, custom queries, ad-hoc inspection).
+   * Variables are sent as-is; errors are still mapped to LoopwiseError.
+   *
+   * Most storefront fields (`courses`, `posts`, `order`, ...) take a
+   * required `subdomain: String!` argument. The BFF rewrites that variable
+   * to the trusted server-derived value on every request, so consumers
+   * declaring `$subdomain` see whatever value the BFF binds — not what
+   * they pass.
+   *
    * @example
-   * const data = await loopwise.query<{ school: { name: string } }>(`
-   *   query { school(subdomain: "acme") { name } }
+   * // Minimal shape demo (always valid, no scoping required):
+   * const data = await loopwise.query<{ __typename: string }>(`
+   *   query { __typename }
    * `)
    */
   query<T = unknown>(document: string, variables?: Record<string, unknown>, operationName?: string, options?: FetchOptions): Promise<T>;

package/dist/index.mjs

@@ -1,6 +1,9 @@
 //#region src/error.ts
 var LoopwiseError = class extends Error {
 	code;
+	/** The site this client was configured for. */
+	site;
+	/** @deprecated Renamed to `site`. Holds the same resolved value. Removed in 0.2.0. */
 	tenant;
 	endpoint;
 	graphqlErrors;
@@ -9,7 +12,9 @@ var LoopwiseError = class extends Error {
 		super(message);
 		this.name = "LoopwiseError";
 		this.code = code;
-		this.tenant = detail.tenant;
+		const site = detail.site ?? detail.tenant;
+		this.site = site;
+		this.tenant = site;
 		this.endpoint = detail.endpoint;
 		this.graphqlErrors = detail.graphqlErrors;
 		this.requestId = detail.requestId;
@@ -29,20 +34,22 @@ var LoopwiseClient = class {
 	config;
 	endpoint;
 	constructor(config) {
-		const tenant = config.tenant ?? void 0;
-		if (detectRuntime() !== "browser" && !tenant) throw new LoopwiseError("CONFIG", "tenant is required outside browser runtime. Pass it to createClient({ tenant }).");
+		const site = config.site ?? config.tenant;
+		if (detectRuntime() !== "browser" && !site) throw new LoopwiseError("CONFIG", "site is required outside browser runtime. Pass it to createClient({ site }).");
+		if (config.apiVersion !== void 0 && config.apiVersion.trim() === "") throw new LoopwiseError("CONFIG", "apiVersion must be a release date (YYYY-MM-DD) or omitted; a blank value would be served as the baseline schema.");
 		this.config = {
 			...config,
-			tenant
+			site,
+			tenant: site
 		};
 		this.endpoint = config.endpoint ?? this.defaultEndpoint();
 	}
 	defaultEndpoint() {
-		const tenant = this.config.tenant;
-		if (detectRuntime() === "browser" && !tenant) return "/api/graphql";
-		const t = tenant;
-		if (t.includes(".")) return `https://${t}/api/graphql`;
-		return `https://${t}.kaik.io/api/graphql`;
+		const site = this.config.site;
+		if (detectRuntime() === "browser" && !site) return "/api/graphql";
+		const s = site;
+		if (s.includes(".")) return `https://${s}/api/graphql`;
+		return `https://${s}.kaik.io/api/graphql`;
 	}
 	async execute(descriptor, options = {}) {
 		const document = renderSingleDocument(descriptor);
@@ -95,6 +102,7 @@ var LoopwiseClient = class {
 		const headers = { accept: "application/graphql-response+json, application/json" };
 		const apiKey = this.resolveApiKey();
 		if (apiKey) headers.authorization = `Bearer ${apiKey}`;
+		if (this.config.apiVersion) headers["api-version"] = this.config.apiVersion;
 		const useGet = this.shouldUseGet(payload, options);
 		if (typeof options.cache === "number" && options.cache > 0) headers["x-loopwise-cache"] = String(options.cache);
 		let response;
@@ -115,26 +123,31 @@ var LoopwiseClient = class {
 			});
 		} catch (err) {
 			throw new LoopwiseError("NETWORK", `Network error: ${err.message}`, {
-				tenant: this.config.tenant,
+				site: this.config.site,
 				endpoint: this.endpoint
 			});
 		}
 		if (response.status === 401 || response.status === 403) throw new LoopwiseError("AUTH", `Auth failed (${response.status})`, {
-			tenant: this.config.tenant,
+			site: this.config.site,
 			endpoint: this.endpoint,
 			requestId: response.headers.get("x-request-id") ?? void 0
 		});
 		if (response.status === 429) throw new LoopwiseError("RATE_LIMIT", "Rate limited", {
-			tenant: this.config.tenant,
+			site: this.config.site,
 			endpoint: this.endpoint
 		});
-		if (!response.ok) throw new LoopwiseError("NETWORK", `Upstream ${response.status}`, {
-			tenant: this.config.tenant,
-			endpoint: this.endpoint
-		});
-		const body = await response.json();
+		let body;
+		if (response.ok) body = await response.json();
+		else {
+			const errorBody = await parseGraphQLErrorBody(response);
+			if (!errorBody) throw new LoopwiseError("NETWORK", `Upstream ${response.status}`, {
+				site: this.config.site,
+				endpoint: this.endpoint
+			});
+			body = errorBody;
+		}
 		if (body.errors?.length) throw new LoopwiseError("GRAPHQL", body.errors[0]?.message ?? "GraphQL error", {
-			tenant: this.config.tenant,
+			site: this.config.site,
 			endpoint: this.endpoint,
 			graphqlErrors: body.errors
 		});
@@ -162,6 +175,18 @@ var LoopwiseClient = class {
 		return globalThis.process?.env?.LOOPWISE_API_KEY;
 	}
 };
+async function parseGraphQLErrorBody(response) {
+	let parsed;
+	try {
+		parsed = JSON.parse(await response.text());
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object") return null;
+	const errors = parsed.errors;
+	if (!Array.isArray(errors) || errors.length === 0) return null;
+	return errors.every((e) => e !== null && typeof e === "object" && typeof e.message === "string") ? parsed : null;
+}
 function firstOperationKeyword(document) {
 	let i = 0;
 	if (document.charCodeAt(0) === 65279) i = 1;
@@ -319,7 +344,7 @@ const DEFAULT_GET_FIELDS$2 = {
 function tenantVars$2(client) {
 	return { subdomain: {
 		type: "String!",
-		value: client.config.tenant ?? ""
+		value: client.config.site ?? ""
 	} };
 }
 var CoursesResource = class {
@@ -328,7 +353,7 @@ var CoursesResource = class {
 		this.client = client;
 	}
 	/**
-	* List courses for the current tenant.
+	* List published courses.
 	* @example
 	* const { items, pageInfo } = await loopwise.courses.list({ limit: 20 })
 	* @example
@@ -433,7 +458,7 @@ const DEFAULT_GET_FIELDS$1 = {
 function tenantVars$1(client) {
 	return { subdomain: {
 		type: "String!",
-		value: client.config.tenant ?? ""
+		value: client.config.site ?? ""
 	} };
 }
 var OrdersResource = class {
@@ -445,9 +470,8 @@ var OrdersResource = class {
 	* Look up a PII-safe order projection by id (the value the storefront
 	* appends to a merchant's `checkoutSuccessUrl` as `?tradeNo=...`).
 	*
-	* Returns `null`-shaped result via the GraphQL `null` payload when the
-	* id doesn't resolve in the current tenant — does NOT throw. Use the
-	* returned `status` to gate Meta Pixel `Purchase` events:
+	* Returns `null` when the id doesn't resolve on this site — does NOT
+	* throw. Use the returned `status` to gate Meta Pixel `Purchase` events:
 	*
 	* @example
 	* const id = new URLSearchParams(location.search).get('tradeNo');
@@ -563,7 +587,7 @@ const DEFAULT_GET_FIELDS = {
 function tenantVars(client) {
 	return { subdomain: {
 		type: "String!",
-		value: client.config.tenant ?? ""
+		value: client.config.site ?? ""
 	} };
 }
 var PostsResource = class {
@@ -572,7 +596,7 @@ var PostsResource = class {
 		this.client = client;
 	}
 	/**
-	* List published posts for the current tenant, ordered by publishedAt desc.
+	* List published posts, ordered by publishedAt desc.
 	* @example
 	* const { items, pageInfo } = await loopwise.posts.list({ limit: 10 })
 	* @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopwise/sdk",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Loopwise platform SDK — agent-friendly headless API client",
   "repository": {
     "type": "git",
@@ -37,21 +37,23 @@
   "files": [
     "dist/*.mjs",
     "dist/*.d.mts",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest run",
     "regen:lock": "node scripts/regen-lock.mjs"
   },
   "devDependencies": {
+    "@kaikhq/graphql-proxy": "workspace:*",
     "graphql": "16.13.1",
     "tsconfig": "workspace:*",
-    "tsdown": "0.22.0",
+    "tsdown": "catalog:",
     "typescript": "5.9.3",
-    "vitest": "4.1.0"
+    "vitest": "catalog:"
   },
   "publishConfig": {
     "access": "public"