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

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# 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.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]
+
+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.

package/README.md

@@ -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,47 @@ 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.
+
+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
@@ -124,22 +127,21 @@ content; use `cache: 'no-store'` for admin previews.
 
 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
 
@@ -155,10 +157,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,9 +27,9 @@ 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;
 }

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 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 +9,15 @@ 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[];
@@ -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;
@@ -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
@@ -334,9 +335,18 @@ interface Loopwise {
   /**
    * 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,21 @@ 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 }).");
 		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);
@@ -115,26 +121,26 @@ 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,
+			site: this.config.site,
 			endpoint: this.endpoint
 		});
 		const body = await response.json();
 		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
 		});
@@ -319,7 +325,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 +334,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 +439,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 +451,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 +568,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 +577,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.3",
   "description": "Loopwise platform SDK — agent-friendly headless API client",
   "repository": {
     "type": "git",
@@ -37,7 +37,8 @@
   "files": [
     "dist/*.mjs",
     "dist/*.d.mts",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsdown",