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

package/CHANGELOG.md

@@ -9,6 +9,38 @@ 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
@@ -62,8 +94,14 @@ follow the same rules as a single 0.x line.
   (not line total), and null-guards the `tradeNo` URL-param lookup
   example.
 
-## [0.1.0-beta.1]
+## [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.
 
@@ -63,6 +63,16 @@ 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`):
 
@@ -123,6 +133,37 @@ 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:
@@ -145,7 +186,7 @@ resolve under `/_preview/<scriptName>/`; root-absolute paths like
 
 ## 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

package/dist/config.d.mts

@@ -32,6 +32,17 @@ interface LoopwiseConfig {
    * 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' | 'CONFIG';
+type LoopwiseErrorCode = "NETWORK" | "AUTH" | "GRAPHQL" | "RATE_LIMIT" | "CONFIG";
 interface GraphQLError {
   message: string;
   path?: (string | number)[];
@@ -17,7 +16,8 @@ declare class LoopwiseError extends Error {
   readonly graphqlErrors?: GraphQLError[];
   readonly requestId?: string;
   constructor(code: LoopwiseErrorCode, message: string, detail?: {
-    site?: string; /** @deprecated Renamed to `site`. Removed in 0.2.0. */
+    site?: string;
+    /** @deprecated Renamed to `site`. Removed in 0.2.0. */
     tenant?: string;
     endpoint?: string;
     graphqlErrors?: GraphQLError[];
@@ -26,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
@@ -64,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 {
   /**
@@ -96,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;
@@ -144,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;
@@ -161,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).
@@ -331,7 +331,7 @@ 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).

package/dist/index.mjs

@@ -36,6 +36,7 @@ var LoopwiseClient = class {
 	constructor(config) {
 		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,
 			site,
@@ -101,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;
@@ -134,11 +136,16 @@ var LoopwiseClient = class {
 			site: this.config.site,
 			endpoint: this.endpoint
 		});
-		if (!response.ok) throw new LoopwiseError("NETWORK", `Upstream ${response.status}`, {
-			site: this.config.site,
-			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", {
 			site: this.config.site,
 			endpoint: this.endpoint,
@@ -168,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loopwise/sdk",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "description": "Loopwise platform SDK — agent-friendly headless API client",
   "repository": {
     "type": "git",
@@ -43,16 +43,17 @@
   "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"