@loopwise/sdk 0.1.0-beta.1 → 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/config.mjs

@@ -2,6 +2,5 @@
 function defineConfig(config) {
 	return config;
 }
-
 //#endregion
-export { defineConfig };
+export { defineConfig };

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;
@@ -119,6 +121,34 @@ interface Lecturer {
   name: string;
   avatar: string | null;
 }
+interface Post {
+  id: string;
+  slug: string;
+  title: string;
+  subtitle: string | null;
+  excerpt: string | null;
+  /** Full body HTML. Truncated server-side when access is gated and the
+   * viewer doesn't have permission (login_required without auth, or paid
+   * without an active subscription). */
+  body: string;
+  /** Maps to schema `Post.cover_photo`. */
+  coverImage: string | null;
+  /** Unix timestamp (seconds since epoch). */
+  publishedAt: number;
+  /** Unix timestamp of the last update — schema sources this from the
+   * post's `updated_at`, so for any persisted record this is populated
+   * (typically equal to or after `publishedAt`). The `null` is included
+   * for forward-compat with a hypothetical "never modified" sentinel
+   * but isn't observed in current production data. */
+  modifiedAt: number | null;
+  /** 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 & {});
+  tags: string[] | null;
+  noindex: boolean;
+  author: Lecturer | null;
+}
 interface PageInfo {
   page: number;
   totalPages: number;
@@ -130,18 +160,42 @@ interface ListResult<T> {
   items: T[];
   pageInfo: PageInfo;
 }
+/** Simplified order status. Mirrors the storefront `Order.status` enum. */
+type OrderStatus = 'PAID' | 'PENDING' | 'FAILED' | 'REFUNDED';
+interface OrderItem {
+  /**
+   * Meta-pixel-aligned identifier (Lineitem#tracking_id server-side).
+   * Use directly in `content_ids` / `contents[].id` for Purchase events.
+   */
+  id: string;
+  name: string | null;
+  quantity: number;
+  /** Per-unit price in the order currency. Maps to FB Pixel `contents[].item_price`. */
+  amount: number;
+}
+interface Order {
+  /** Stable order identifier — currently equals `Payment#trade_no` server-side. */
+  id: string;
+  status: OrderStatus;
+  /** Total paid amount in the order currency. Maps to FB Pixel `value`. */
+  total: number;
+  currency: string;
+  items: OrderItem[];
+  /** Unix timestamp (seconds since epoch). */
+  createdAt: number;
+}
 //#endregion
 //#region src/resources/courses.d.ts
-declare const DEFAULT_LIST_FIELDS: Selection<Course>;
-declare const DEFAULT_GET_FIELDS: Selection<Course>;
-interface CourseListArgs<S extends Selection<Course> = typeof DEFAULT_LIST_FIELDS> {
+declare const DEFAULT_LIST_FIELDS$1: Selection<Course>;
+declare const DEFAULT_GET_FIELDS$2: Selection<Course>;
+interface CourseListArgs<S extends Selection<Course> = typeof DEFAULT_LIST_FIELDS$1> {
   limit?: number;
   page?: number;
   /** SDK `limit` maps to schema `perPage`. Schema also has its own `limit`
    * which we expose as `topN` if needed (not in v0). */
   select?: S;
 }
-interface CourseGetArgs<S extends Selection<Course> = typeof DEFAULT_GET_FIELDS> {
+interface CourseGetArgs<S extends Selection<Course> = typeof DEFAULT_GET_FIELDS$2> {
   slug: string;
   select?: S;
 }
@@ -149,26 +203,126 @@ 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
    * // Opt into GET + Cache-Control hint (60s):
    * await loopwise.courses.list({ limit: 20 }, { cache: 60 })
    */
-  list<S extends Selection<Course> = typeof DEFAULT_LIST_FIELDS>(args?: CourseListArgs<S>, options?: FetchOptions): QueryBuilder<ListResult<Selected<Course, S>>>;
+  list<S extends Selection<Course> = typeof DEFAULT_LIST_FIELDS$1>(args?: CourseListArgs<S>, options?: FetchOptions): QueryBuilder<ListResult<Selected<Course, S>>>;
+  /**
+   * Get a single course by slug.
+   *
+   * Throws `LoopwiseError("GRAPHQL")` when the slug is not found
+   * (Storefront `Queries::Course` raises `service_error("Course-003")`
+   * on a `null: false` field). Wrap with try/catch to render 404 routes:
+   *
+   * @example
+   * try {
+   *   const course = await loopwise.courses.get({ slug: 'finance' })
+   *   // ...
+   * } catch (e) {
+   *   if (e instanceof LoopwiseError && e.code === 'GRAPHQL') {
+   *     return Astro.redirect('/404')
+   *   }
+   *   throw e
+   * }
+   */
+  get<S extends Selection<Course> = typeof DEFAULT_GET_FIELDS$2>(args: CourseGetArgs<S>, options?: FetchOptions): QueryBuilder<Selected<Course, S>>;
+}
+//#endregion
+//#region src/resources/orders.d.ts
+declare const DEFAULT_GET_FIELDS$1: Selection<Order>;
+interface OrderGetArgs<S extends Selection<Order> = typeof DEFAULT_GET_FIELDS$1> {
+  /**
+   * Order identifier — the value passed via `?tradeNo=...` on the post-checkout
+   * redirect to the merchant's success URL. Internally equals
+   * `Payment#trade_no` server-side.
+   */
+  id: string;
+  select?: S;
+}
+declare class OrdersResource {
+  private client;
+  constructor(client: LoopwiseClient);
+  /**
+   * Look up a PII-safe order projection by id (the value the storefront
+   * appends to a merchant's `checkoutSuccessUrl` as `?tradeNo=...`).
+   *
+   * 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');
+   * if (!id) return;
+   * const order = await loopwise.orders.get({ id });
+   * if (order?.status === 'PAID') {
+   *   fbq('track', 'Purchase', {
+   *     value: order.total,
+   *     currency: order.currency,
+   *     contents: order.items.map(i => ({
+   *       id: i.id, name: i.name, quantity: i.quantity, item_price: i.amount,
+   *     })),
+   *     content_ids: order.items.map(i => i.id),
+   *     content_type: 'product',
+   *     num_items: order.items.reduce((s, i) => s + i.quantity, 0),
+   *   }, { eventID: order.id });
+   * }
+   */
+  get<S extends Selection<Order> = typeof DEFAULT_GET_FIELDS$1>(args: OrderGetArgs<S>, options?: FetchOptions): QueryBuilder<Selected<Order, S> | null>;
+}
+//#endregion
+//#region src/resources/posts.d.ts
+declare const DEFAULT_LIST_FIELDS: Selection<Post>;
+declare const DEFAULT_GET_FIELDS: Selection<Post>;
+interface PostListArgs<S extends Selection<Post> = typeof DEFAULT_LIST_FIELDS> {
+  limit?: number;
+  page?: number;
+  /** SDK `limit` maps to schema `perPage`. */
+  select?: S;
+}
+interface PostGetArgs<S extends Selection<Post> = typeof DEFAULT_GET_FIELDS> {
+  slug: string;
+  select?: S;
+}
+declare class PostsResource {
+  private client;
+  constructor(client: LoopwiseClient);
+  /**
+   * List published posts, ordered by publishedAt desc.
+   * @example
+   * const { items, pageInfo } = await loopwise.posts.list({ limit: 10 })
+   * @example
+   * await loopwise.posts.list({ limit: 10 }, { cache: 60 })
+   */
+  list<S extends Selection<Post> = typeof DEFAULT_LIST_FIELDS>(args?: PostListArgs<S>, options?: FetchOptions): QueryBuilder<ListResult<Selected<Post, S>>>;
   /**
-   * Get a single course by slug. Returns `null` if not found.
+   * Get a single post by slug.
+   *
+   * Throws `LoopwiseError("GRAPHQL")` when the slug is not found
+   * (Storefront `Queries::Post` raises `service_error("Post-000")` on a
+   * `null: false` field). Wrap with try/catch to render 404 routes:
+   *
    * @example
-   * const course = await loopwise.courses.get({ slug: 'finance' })
-   * if (!course) return Astro.redirect('/404')
+   * try {
+   *   const post = await loopwise.posts.get({ slug: 'hello-world' })
+   *   // ...
+   * } catch (e) {
+   *   if (e instanceof LoopwiseError && e.code === 'GRAPHQL') {
+   *     return Astro.redirect('/404')
+   *   }
+   *   throw e
+   * }
    */
-  get<S extends Selection<Course> = typeof DEFAULT_GET_FIELDS>(args: CourseGetArgs<S>, options?: FetchOptions): QueryBuilder<Selected<Course, S> | null>;
+  get<S extends Selection<Post> = typeof DEFAULT_GET_FIELDS>(args: PostGetArgs<S>, options?: FetchOptions): QueryBuilder<Selected<Post, S>>;
 }
 //#endregion
 //#region src/index.d.ts
 interface Loopwise {
   readonly courses: CoursesResource;
+  readonly orders: OrdersResource;
+  readonly posts: PostsResource;
   /**
    * Compose multiple resource queries into a single GraphQL HTTP request.
    * @example
@@ -181,13 +335,22 @@ 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>;
 }
 declare function createClient(config: LoopwiseConfig): Loopwise;
 //#endregion
-export { type Course, type FetchOptions, type Lecturer, type ListResult, Loopwise, type LoopwiseConfig, LoopwiseError, type PageInfo, QueryBuilder, type Selected, type Selection, createClient };
+export { type Course, type FetchOptions, type Lecturer, type ListResult, Loopwise, type LoopwiseConfig, LoopwiseError, type Order, type OrderItem, type OrderStatus, type PageInfo, type Post, QueryBuilder, type Selected, type Selection, createClient };

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,20 +12,20 @@ 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;
 	}
 };
-
 //#endregion
 //#region src/runtime.ts
 function detectRuntime() {
 	if (typeof window !== "undefined" && typeof window.document !== "undefined") return "browser";
 	return "ssr";
 }
-
 //#endregion
 //#region src/client.ts
 const GET_URL_MAX_LENGTH = 2e3;
@@ -31,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);
@@ -117,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
 		});
@@ -234,7 +238,6 @@ function literal(value) {
 	if (typeof value === "object") return `{ ${Object.entries(value).filter(([, v]) => v !== void 0).map(([k, v]) => `${k}: ${literal(v)}`).join(", ")} }`;
 	throw new LoopwiseError("CONFIG", `Unsupported argument type for GraphQL literal: ${typeof value}`);
 }
-
 //#endregion
 //#region src/query.ts
 var QueryBuilder = class {
@@ -250,7 +253,6 @@ var QueryBuilder = class {
 		return this.fetcher.execute(this.descriptor, this.fetchOptions).then(onFulfilled, onRejected);
 	}
 };
-
 //#endregion
 //#region src/schema/courses.ts
 /** Map SDK Course selection -> schema field selection set. */
@@ -300,16 +302,15 @@ function mapCoursePage(raw) {
 		}
 	};
 }
-
 //#endregion
 //#region src/resources/courses.ts
-const DEFAULT_LIST_FIELDS = {
+const DEFAULT_LIST_FIELDS$1 = {
 	id: true,
 	slug: true,
 	title: true,
 	coverImage: true
 };
-const DEFAULT_GET_FIELDS = {
+const DEFAULT_GET_FIELDS$2 = {
 	id: true,
 	slug: true,
 	title: true,
@@ -321,18 +322,19 @@ const DEFAULT_GET_FIELDS = {
 		avatar: true
 	}
 };
-function tenantVars(client) {
+function tenantVars$2(client) {
 	return { subdomain: {
 		type: "String!",
-		value: client.config.tenant ?? ""
+		value: client.config.site ?? ""
 	} };
 }
 var CoursesResource = class {
+	client;
 	constructor(client) {
 		this.client = client;
 	}
 	/**
-	* List courses for the current tenant.
+	* List published courses.
 	* @example
 	* const { items, pageInfo } = await loopwise.courses.list({ limit: 20 })
 	* @example
@@ -340,7 +342,7 @@ var CoursesResource = class {
 	* await loopwise.courses.list({ limit: 20 }, { cache: 60 })
 	*/
 	list(args = {}, options = {}) {
-		const selectionSet = `nodes { ${buildCourseSelection(args.select ?? DEFAULT_LIST_FIELDS)} } currentPage totalPages nodesCount hasNextPage hasPreviousPage`;
+		const selectionSet = `nodes { ${buildCourseSelection(args.select ?? DEFAULT_LIST_FIELDS$1)} } currentPage totalPages nodesCount hasNextPage hasPreviousPage`;
 		return new QueryBuilder(this.client, {
 			operation: "CourseList",
 			field: "courses",
@@ -349,35 +351,290 @@ var CoursesResource = class {
 				page: args.page,
 				perPage: args.limit
 			},
-			vars: tenantVars(this.client),
+			vars: tenantVars$2(this.client),
 			transform: (raw) => mapCoursePage(raw)
 		}, options);
 	}
 	/**
-	* Get a single course by slug. Returns `null` if not found.
+	* Get a single course by slug.
+	*
+	* Throws `LoopwiseError("GRAPHQL")` when the slug is not found
+	* (Storefront `Queries::Course` raises `service_error("Course-003")`
+	* on a `null: false` field). Wrap with try/catch to render 404 routes:
+	*
 	* @example
-	* const course = await loopwise.courses.get({ slug: 'finance' })
-	* if (!course) return Astro.redirect('/404')
+	* try {
+	*   const course = await loopwise.courses.get({ slug: 'finance' })
+	*   // ...
+	* } catch (e) {
+	*   if (e instanceof LoopwiseError && e.code === 'GRAPHQL') {
+	*     return Astro.redirect('/404')
+	*   }
+	*   throw e
+	* }
 	*/
 	get(args, options = {}) {
-		const sel = args.select ?? DEFAULT_GET_FIELDS;
+		const sel = args.select ?? DEFAULT_GET_FIELDS$2;
 		return new QueryBuilder(this.client, {
 			operation: "CourseGet",
 			field: "course",
 			selectionSet: buildCourseSelection(sel),
 			args: { slug: args.slug },
+			vars: tenantVars$2(this.client),
+			transform: (raw) => mapCourse(raw)
+		}, options);
+	}
+};
+//#endregion
+//#region src/schema/orders.ts
+/** Map SDK Order selection -> schema field selection set. */
+function buildOrderSelection(select) {
+	const parts = ["id"];
+	const sel = select;
+	if (sel.status) parts.push("status");
+	if (sel.total) parts.push("total");
+	if (sel.currency) parts.push("currency");
+	if (sel.createdAt) parts.push("createdAt");
+	if (sel.items && typeof sel.items === "object") {
+		const itemSel = sel.items;
+		const itemParts = ["id"];
+		if (itemSel.name) itemParts.push("name");
+		if (itemSel.quantity) itemParts.push("quantity");
+		if (itemSel.amount) itemParts.push("amount");
+		parts.push(`items { ${itemParts.join(" ")} }`);
+	}
+	return parts.join(" ");
+}
+function mapOrderItem(raw) {
+	const out = { id: raw.id };
+	if (raw.name !== void 0) out.name = raw.name ?? null;
+	if (raw.quantity !== void 0) out.quantity = raw.quantity;
+	if (raw.amount !== void 0) out.amount = raw.amount;
+	return out;
+}
+function mapOrder(raw) {
+	const out = { id: raw.id };
+	if (raw.status !== void 0) out.status = raw.status;
+	if (raw.total !== void 0) out.total = raw.total;
+	if (raw.currency !== void 0) out.currency = raw.currency;
+	if (raw.createdAt !== void 0) out.createdAt = raw.createdAt;
+	if (raw.items !== void 0) out.items = raw.items.map(mapOrderItem);
+	return out;
+}
+//#endregion
+//#region src/resources/orders.ts
+const DEFAULT_GET_FIELDS$1 = {
+	id: true,
+	status: true,
+	total: true,
+	currency: true,
+	createdAt: true,
+	items: {
+		id: true,
+		name: true,
+		quantity: true,
+		amount: true
+	}
+};
+function tenantVars$1(client) {
+	return { subdomain: {
+		type: "String!",
+		value: client.config.site ?? ""
+	} };
+}
+var OrdersResource = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* Look up a PII-safe order projection by id (the value the storefront
+	* appends to a merchant's `checkoutSuccessUrl` as `?tradeNo=...`).
+	*
+	* 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');
+	* if (!id) return;
+	* const order = await loopwise.orders.get({ id });
+	* if (order?.status === 'PAID') {
+	*   fbq('track', 'Purchase', {
+	*     value: order.total,
+	*     currency: order.currency,
+	*     contents: order.items.map(i => ({
+	*       id: i.id, name: i.name, quantity: i.quantity, item_price: i.amount,
+	*     })),
+	*     content_ids: order.items.map(i => i.id),
+	*     content_type: 'product',
+	*     num_items: order.items.reduce((s, i) => s + i.quantity, 0),
+	*   }, { eventID: order.id });
+	* }
+	*/
+	get(args, options = {}) {
+		const sel = args.select ?? DEFAULT_GET_FIELDS$1;
+		return new QueryBuilder(this.client, {
+			operation: "OrderGet",
+			field: "order",
+			selectionSet: buildOrderSelection(sel),
+			args: { id: args.id },
+			vars: tenantVars$1(this.client),
+			transform: (raw) => raw == null ? null : mapOrder(raw)
+		}, options);
+	}
+};
+//#endregion
+//#region src/schema/posts.ts
+/** Map SDK Post selection -> schema field selection set. */
+function buildPostSelection(select) {
+	const parts = ["id", "slug"];
+	const sel = select;
+	if (sel.title) parts.push("title");
+	if (sel.subtitle) parts.push("subtitle");
+	if (sel.excerpt) parts.push("excerpt");
+	if (sel.body) parts.push("body");
+	if (sel.coverImage) parts.push("coverPhoto");
+	if (sel.publishedAt) parts.push("publishedAt");
+	if (sel.modifiedAt) parts.push("modifiedAt");
+	if (sel.accessType) parts.push("accessType");
+	if (sel.tags) parts.push("tags");
+	if (sel.noindex) parts.push("noindex");
+	if (sel.author && typeof sel.author === "object") {
+		const auth = sel.author;
+		const authParts = ["id"];
+		if (auth.name) authParts.push("name");
+		if (auth.avatar) authParts.push("avatar");
+		parts.push(`author { ${authParts.join(" ")} }`);
+	}
+	return parts.join(" ");
+}
+function mapPost(raw) {
+	const out = {
+		id: raw.id,
+		slug: raw.slug
+	};
+	if (raw.title !== void 0) out.title = raw.title;
+	if (raw.subtitle !== void 0) out.subtitle = raw.subtitle ?? null;
+	if (raw.excerpt !== void 0) out.excerpt = raw.excerpt ?? null;
+	if (raw.body !== void 0) out.body = raw.body;
+	if (raw.coverPhoto !== void 0) out.coverImage = raw.coverPhoto ?? null;
+	if (raw.publishedAt !== void 0) out.publishedAt = raw.publishedAt;
+	if (raw.modifiedAt !== void 0) out.modifiedAt = raw.modifiedAt ?? null;
+	if (raw.accessType !== void 0) out.accessType = raw.accessType;
+	if (raw.tags !== void 0) out.tags = raw.tags ?? null;
+	if (raw.noindex !== void 0) out.noindex = raw.noindex;
+	if (raw.author !== void 0) out.author = raw.author ? mapLecturer(raw.author) : null;
+	return out;
+}
+function mapPostPage(raw) {
+	return {
+		items: raw.nodes.map(mapPost),
+		pageInfo: {
+			page: raw.currentPage,
+			totalPages: raw.totalPages,
+			totalCount: raw.nodesCount,
+			hasNext: raw.hasNextPage,
+			hasPrev: raw.hasPreviousPage
+		}
+	};
+}
+//#endregion
+//#region src/resources/posts.ts
+const DEFAULT_LIST_FIELDS = {
+	id: true,
+	slug: true,
+	title: true,
+	excerpt: true,
+	coverImage: true,
+	publishedAt: true
+};
+const DEFAULT_GET_FIELDS = {
+	id: true,
+	slug: true,
+	title: true,
+	subtitle: true,
+	excerpt: true,
+	body: true,
+	coverImage: true,
+	publishedAt: true,
+	modifiedAt: true,
+	accessType: true,
+	author: {
+		id: true,
+		name: true,
+		avatar: true
+	}
+};
+function tenantVars(client) {
+	return { subdomain: {
+		type: "String!",
+		value: client.config.site ?? ""
+	} };
+}
+var PostsResource = class {
+	client;
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* List published posts, ordered by publishedAt desc.
+	* @example
+	* const { items, pageInfo } = await loopwise.posts.list({ limit: 10 })
+	* @example
+	* await loopwise.posts.list({ limit: 10 }, { cache: 60 })
+	*/
+	list(args = {}, options = {}) {
+		const selectionSet = `nodes { ${buildPostSelection(args.select ?? DEFAULT_LIST_FIELDS)} } currentPage totalPages nodesCount hasNextPage hasPreviousPage`;
+		return new QueryBuilder(this.client, {
+			operation: "PostList",
+			field: "posts",
+			selectionSet,
+			args: {
+				page: args.page,
+				perPage: args.limit
+			},
+			vars: tenantVars(this.client),
+			transform: (raw) => mapPostPage(raw)
+		}, options);
+	}
+	/**
+	* Get a single post by slug.
+	*
+	* Throws `LoopwiseError("GRAPHQL")` when the slug is not found
+	* (Storefront `Queries::Post` raises `service_error("Post-000")` on a
+	* `null: false` field). Wrap with try/catch to render 404 routes:
+	*
+	* @example
+	* try {
+	*   const post = await loopwise.posts.get({ slug: 'hello-world' })
+	*   // ...
+	* } catch (e) {
+	*   if (e instanceof LoopwiseError && e.code === 'GRAPHQL') {
+	*     return Astro.redirect('/404')
+	*   }
+	*   throw e
+	* }
+	*/
+	get(args, options = {}) {
+		const sel = args.select ?? DEFAULT_GET_FIELDS;
+		return new QueryBuilder(this.client, {
+			operation: "PostGet",
+			field: "post",
+			selectionSet: buildPostSelection(sel),
+			args: { slug: args.slug },
 			vars: tenantVars(this.client),
-			transform: (raw) => raw == null ? null : mapCourse(raw)
+			transform: (raw) => mapPost(raw)
 		}, options);
 	}
 };
-
 //#endregion
 //#region src/index.ts
 function createClient(config) {
 	const client = new LoopwiseClient(config);
 	return {
 		courses: new CoursesResource(client),
+		orders: new OrdersResource(client),
+		posts: new PostsResource(client),
 		batch(builders, options) {
 			return client.batch(builders, options);
 		},
@@ -386,6 +643,5 @@ function createClient(config) {
 		}
 	};
 }
-
 //#endregion
-export { LoopwiseError, QueryBuilder, createClient };
+export { LoopwiseError, QueryBuilder, createClient };

package/package.json

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