@loopwise/sdk 0.1.0-beta.0

package/README.md

@@ -0,0 +1,90 @@
+# @loopwise/sdk
+
+Storefront GraphQL client for Loopwise / Teachify. The SDK has no concept of
+"tenant" in its public surface — calls hit the same-origin BFF at
+`/api/graphql`, which derives the tenant from the request host and binds it
+to the response on the trusted server side.
+
+## Quick start
+
+```ts
+import { createClient } from '@loopwise/sdk';
+
+const loopwise = createClient({});
+const { items } = await loopwise.courses.list({ limit: 20 });
+```
+
+That's the entire happy path. Whether the page is on `acme.kaik.io`,
+`acme.myteachify.com`, or `nii.school`, the BFF on each origin already knows
+which tenant it's serving — the SDK just talks to its own origin.
+
+### Cross-origin / SSR (advanced)
+
+When the SDK runs outside a tenant origin (build pipeline, third-party site,
+SSR worker), pass `tenant` explicitly so the SDK knows where to send the
+request. An `apiKey` is required outside the browser to bypass cookie auth.
+
+```ts
+const loopwise = createClient({
+  tenant: 'acme',
+  apiKey: process.env.LOOPWISE_API_KEY, // SSR / build only
+});
+```
+
+## Cache option (`cache`)
+
+Read-only resource calls accept an opt-in `cache` option that flips the
+request to a GraphQL-over-HTTP `GET` and asks the BFF to apply a
+`Cache-Control` hint so Vercel's edge can serve repeats without a Rails
+round-trip.
+
+```ts
+// 60s fresh + 300s stale-while-revalidate at the edge.
+const { items } = await loopwise.courses.list({ limit: 20 }, { cache: 60 });
+
+// Force fresh; never share the response across visitors.
+const fresh = await loopwise.courses.list({ limit: 20 }, { cache: 'no-store' });
+```
+
+`courses.list()` returns a thenable `QueryBuilder` — without `await` (or
+`.then()` / passing it to `batch()`) the call is a no-op and no HTTP request
+is sent.
+
+### When to use which
+
+| Context | What to pass | Why |
+|---------|--------------|-----|
+| Storefront list / detail (public, semi-static) | `{ cache: 60 }` | Tenant-public, OK to share across visitors. |
+| Storefront very-static metadata (school info, footer) | `{ cache: 300 }` | Capped at 300s by the BFF; rarely changes. |
+| **Admin / preview path** | **`{ cache: 'no-store' }`** | Admin previewing a draft must always see fresh, never share their response. |
+| Mutations | (n/a — never cached) | SDK always POSTs mutations. |
+| Per-user data (cart, viewer profile) | `{ cache: 'no-store' }` (or omit entirely) | Caching per-user data on a shared edge would leak across visitors. |
+
+### Defence in depth — what happens if you get it wrong
+
+The BFF refuses to cache any response when:
+
+1. The request carries `Cookie` or `Authorization` (admin sessions, logged-in
+   visitors). Even if you pass `cache: 60`, the cookie strips the hint.
+2. The upstream Rails response sets `Set-Cookie` (session establishment).
+3. The upstream returns a non-2xx status.
+
+So a misconfigured `cache: 60` on an admin path is still safe — the cookie
+guard prevents the response from reaching Vercel's shared cache. `cache: 'no-store'`
+is the explicit, type-system-visible declaration of "this must never be cached".
+
+### Propagation delay after content updates
+
+`cache: 60` ⇒ a publish becomes visible to visitors in roughly 1–6 minutes
+per Vercel POP, depending on traffic. Use shorter TTLs for time-sensitive
+content; use `cache: 'no-store'` for admin previews.
+
+## Public API
+
+- `createClient(config)` — storefront client. `config.tenant` is optional
+  in the browser (BFF derives it from host) and required in SSR / build.
+- `loopwise.courses.list(args, options?)` / `.get(args, options?)`.
+- `loopwise.batch(builders, options?)` — composes N queries into one HTTP request.
+- `loopwise.query<T>(document, variables?, operationName?, options?)` — raw GraphQL.
+
+See `apps/sdk-runtime-poc/` for a runnable browser validation page.

package/dist/config.d.mts

@@ -0,0 +1,26 @@
+//#region src/config.d.ts
+interface LoopwiseConfig {
+  /**
+   * Tenant identifier (subdomain "acme" or full FQDN "nii.school").
+   *
+   * Optional in browser runtime — SDK auto-resolves from `window.location.hostname`
+   * (e.g. `acme.kaik.io` -> `"acme"`). Required in build/SSR runtime.
+   */
+  tenant?: string;
+  /**
+   * API key for build/SSR (Bearer auth). Reads from `LOOPWISE_API_KEY` env if
+   * omitted. NEVER bundle this into a browser build — `defineConfig` runs at
+   * build/SSR; the value never reaches client-side code unless the consumer
+   * misuses it.
+   */
+  apiKey?: string;
+  /**
+   * Override the GraphQL endpoint. Defaults to:
+   *   - Browser: same-origin `/api/graphql`
+   *   - Build/SSR: `https://{tenant}/api/graphql` (or kaik.io fallback)
+   */
+  endpoint?: string;
+}
+declare function defineConfig(config: LoopwiseConfig): LoopwiseConfig;
+//#endregion
+export { LoopwiseConfig, defineConfig };

package/dist/config.mjs

@@ -0,0 +1,7 @@
+//#region src/config.ts
+function defineConfig(config) {
+	return config;
+}
+
+//#endregion
+export { defineConfig };

package/dist/index.d.mts

@@ -0,0 +1,193 @@
+import { LoopwiseConfig } from "./config.mjs";
+
+//#region src/error.d.ts
+type LoopwiseErrorCode = 'NETWORK' | 'AUTH' | 'GRAPHQL' | 'RATE_LIMIT' | 'TENANT_NOT_FOUND' | 'CONFIG';
+interface GraphQLError {
+  message: string;
+  path?: (string | number)[];
+  extensions?: Record<string, unknown>;
+}
+declare class LoopwiseError extends Error {
+  readonly code: LoopwiseErrorCode;
+  readonly tenant?: string;
+  readonly endpoint?: string;
+  readonly graphqlErrors?: GraphQLError[];
+  readonly requestId?: string;
+  constructor(code: LoopwiseErrorCode, message: string, detail?: {
+    tenant?: string;
+    endpoint?: string;
+    graphqlErrors?: GraphQLError[];
+    requestId?: string;
+  });
+}
+//#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 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 Selected<T, S> = SelectedInner<T, S>;
+//#endregion
+//#region src/query.d.ts
+interface QueryDescriptor {
+  /** GraphQL operation name (used as alias key inside batch documents). */
+  operation: string;
+  /** Pre-built selection set string ("id title { x }"). */
+  selectionSet: string;
+  /** Top-level field name on the GraphQL schema (e.g. "courses", "course"). */
+  field: string;
+  /** Top-level field arguments rendered as inline literals. */
+  args: Record<string, unknown>;
+  /**
+   * Top-level field arguments rendered as GraphQL variables. The renderer
+   * emits `query Op($name: Type, ...) { field(name: $name, ...) }` and
+   * places `value` into the request's `variables` payload. Variable values
+   * stay JSON-shaped on the wire, which is what lets the BFF / proxy layer
+   * rewrite tenant-scoped variables (`subdomain`) without parsing the
+   * GraphQL document.
+   */
+  vars?: Record<string, {
+    type: string;
+    value: unknown;
+  }>;
+  /** Optional response transform (e.g. wrap into ListResult shape). */
+  transform?: (raw: unknown) => unknown;
+}
+interface FetchOptions {
+  /**
+   * Cache hint. A positive number opts the call into GraphQL-over-HTTP GET
+   * mode (per spec §5.1) so HTTP caches and CDNs can serve repeat hits, and
+   * sends `X-Loopwise-Cache: <seconds>` so the BFF can echo it as
+   * `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';
+}
+interface BatchedFetcher {
+  /**
+   * Execute one descriptor. Implementations may either fire an HTTP request
+   * immediately, or buffer for `batch()` to flush.
+   */
+  execute<T>(descriptor: QueryDescriptor, options?: FetchOptions): Promise<T>;
+}
+declare class QueryBuilder<T> implements PromiseLike<T> {
+  readonly descriptor: QueryDescriptor;
+  readonly fetchOptions: FetchOptions;
+  private fetcher;
+  constructor(fetcher: BatchedFetcher, descriptor: QueryDescriptor, fetchOptions?: FetchOptions);
+  then<R1 = T, R2 = never>(onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+}
+//#endregion
+//#region src/client.d.ts
+declare class LoopwiseClient implements BatchedFetcher {
+  readonly config: {
+    tenant?: string;
+  } & LoopwiseConfig;
+  private endpoint;
+  constructor(config: LoopwiseConfig);
+  private defaultEndpoint;
+  execute<T>(descriptor: QueryDescriptor, options?: FetchOptions): Promise<T>;
+  /**
+   * Raw GraphQL escape hatch. Caller writes the query/mutation document and
+   * receives the typed `data` payload. Variables are sent as-is. Errors are
+   * still mapped to LoopwiseError.
+   */
+  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>;
+  private fetchGraphQL;
+  private shouldUseGet;
+  private buildGetUrl;
+  private resolveApiKey;
+}
+//#endregion
+//#region src/types.d.ts
+interface Course {
+  id: string;
+  slug: string;
+  /** Maps to schema `Course.name`. */
+  title: string;
+  description: string | null;
+  /** Maps to schema `Course.image`. */
+  coverImage: string | null;
+  createdAt: number;
+  lecturer: Lecturer | null;
+}
+interface Lecturer {
+  id: string;
+  /** Maps to schema `Lecturer.name`. */
+  name: string;
+  avatar: string | null;
+}
+interface PageInfo {
+  page: number;
+  totalPages: number;
+  totalCount: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+interface ListResult<T> {
+  items: T[];
+  pageInfo: PageInfo;
+}
+//#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> {
+  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> {
+  slug: string;
+  select?: S;
+}
+declare class CoursesResource {
+  private client;
+  constructor(client: LoopwiseClient);
+  /**
+   * List courses for the current tenant.
+   * @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>>>;
+  /**
+   * Get a single course by slug. Returns `null` if not found.
+   * @example
+   * const course = await loopwise.courses.get({ slug: 'finance' })
+   * if (!course) return Astro.redirect('/404')
+   */
+  get<S extends Selection<Course> = typeof DEFAULT_GET_FIELDS>(args: CourseGetArgs<S>, options?: FetchOptions): QueryBuilder<Selected<Course, S> | null>;
+}
+//#endregion
+//#region src/index.d.ts
+interface Loopwise {
+  readonly courses: CoursesResource;
+  /**
+   * Compose multiple resource queries into a single GraphQL HTTP request.
+   * @example
+   * const home = await loopwise.batch({
+   *   featured: loopwise.courses.list({ limit: 6 }),
+   *   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 }>;
+  /**
+   * Raw GraphQL escape hatch. Use when a typed resource method doesn't cover
+   * what you need (new schema fields, custom queries, ad-hoc inspection).
+   * @example
+   * const data = await loopwise.query<{ school: { name: string } }>(`
+   *   query { school(subdomain: "acme") { name } }
+   * `)
+   */
+  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 };

package/dist/index.mjs

@@ -0,0 +1,390 @@
+//#region src/error.ts
+var LoopwiseError = class extends Error {
+	code;
+	tenant;
+	endpoint;
+	graphqlErrors;
+	requestId;
+	constructor(code, message, detail = {}) {
+		super(message);
+		this.name = "LoopwiseError";
+		this.code = code;
+		this.tenant = detail.tenant;
+		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;
+const GRAPHQL_NAME_RE = /^[_A-Za-z][_0-9A-Za-z]*$/;
+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 }).");
+		this.config = {
+			...config,
+			tenant
+		};
+		this.endpoint = config.endpoint ?? this.defaultEndpoint();
+	}
+	defaultEndpoint() {
+		if (detectRuntime() === "browser") return "/api/graphql";
+		const tenant = this.config.tenant;
+		if (tenant.includes(".")) return `https://${tenant}/api/graphql`;
+		return `https://${tenant}.kaik.io/api/graphql`;
+	}
+	async execute(descriptor, options = {}) {
+		const document = renderSingleDocument(descriptor);
+		const payload = {
+			query: document.query,
+			variables: document.variables,
+			operationName: descriptor.operation
+		};
+		const raw = (await this.fetchGraphQL(payload, options))?.[descriptor.field];
+		return descriptor.transform ? descriptor.transform(raw) : raw;
+	}
+	/**
+	* Raw GraphQL escape hatch. Caller writes the query/mutation document and
+	* receives the typed `data` payload. Variables are sent as-is. Errors are
+	* still mapped to LoopwiseError.
+	*/
+	async raw(document, variables = {}, operationName, options = {}) {
+		return await this.fetchGraphQL({
+			query: document,
+			variables,
+			operationName
+		}, options);
+	}
+	async batch(builders, options = {}) {
+		const entries = Object.entries(builders);
+		if (entries.length === 0) return {};
+		for (const [alias, builder] of entries) {
+			const aliasStr = String(alias);
+			if (!GRAPHQL_NAME_RE.test(aliasStr)) throw new LoopwiseError("CONFIG", `batch() alias "${aliasStr}" is not a valid GraphQL Name`);
+			const builderOptions = builder.fetchOptions;
+			if (builderOptions && Object.keys(builderOptions).length > 0) throw new LoopwiseError("CONFIG", `batch() builder "${aliasStr}" has per-call FetchOptions; pass them to batch(builders, options) instead so they apply to the whole request.`);
+		}
+		const document = renderBatchDocument(entries.map(([alias, b]) => ({
+			alias: String(alias),
+			descriptor: b.descriptor
+		})));
+		const data = await this.fetchGraphQL({
+			query: document.query,
+			variables: document.variables,
+			operationName: "BatchQuery"
+		}, options);
+		const result = {};
+		for (const [alias, builder] of entries) {
+			const raw = data?.[String(alias)];
+			result[alias] = builder.descriptor.transform ? builder.descriptor.transform(raw) : raw;
+		}
+		return result;
+	}
+	async fetchGraphQL(payload, options = {}) {
+		const headers = { accept: "application/graphql-response+json, application/json" };
+		const apiKey = this.resolveApiKey();
+		if (apiKey) headers.authorization = `Bearer ${apiKey}`;
+		const useGet = this.shouldUseGet(payload, options);
+		if (typeof options.cache === "number" && options.cache > 0) headers["x-loopwise-cache"] = String(options.cache);
+		let response;
+		try {
+			if (useGet) response = await fetch(this.buildGetUrl(payload), {
+				method: "GET",
+				credentials: "omit",
+				headers
+			});
+			else response = await fetch(this.endpoint, {
+				method: "POST",
+				credentials: detectRuntime() === "browser" ? "same-origin" : "omit",
+				headers: {
+					...headers,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(payload)
+			});
+		} catch (err) {
+			throw new LoopwiseError("NETWORK", `Network error: ${err.message}`, {
+				tenant: this.config.tenant,
+				endpoint: this.endpoint
+			});
+		}
+		if (response.status === 401 || response.status === 403) throw new LoopwiseError("AUTH", `Auth failed (${response.status})`, {
+			tenant: this.config.tenant,
+			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,
+			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();
+		if (body.errors?.length) throw new LoopwiseError("GRAPHQL", body.errors[0]?.message ?? "GraphQL error", {
+			tenant: this.config.tenant,
+			endpoint: this.endpoint,
+			graphqlErrors: body.errors
+		});
+		return body.data ?? null;
+	}
+	shouldUseGet(payload, options) {
+		if (typeof options.cache !== "number" || options.cache <= 0) return false;
+		if (detectRuntime() !== "browser" || this.resolveApiKey()) return false;
+		const op = firstOperationKeyword(payload.query);
+		if (op === "mutation" || op === "subscription") return false;
+		if (containsNonQueryOperation(payload.query)) return false;
+		return this.buildGetUrl(payload).length <= GET_URL_MAX_LENGTH;
+	}
+	buildGetUrl(payload) {
+		const params = new URLSearchParams();
+		params.set("query", payload.query);
+		if (payload.variables && Object.keys(payload.variables).length > 0) params.set("variables", JSON.stringify(payload.variables));
+		if (payload.operationName) params.set("operationName", payload.operationName);
+		const sep = this.endpoint.includes("?") ? "&" : "?";
+		return `${this.endpoint}${sep}${params.toString()}`;
+	}
+	resolveApiKey() {
+		if (detectRuntime() === "browser") return void 0;
+		if (this.config.apiKey) return this.config.apiKey;
+		return globalThis.process?.env?.LOOPWISE_API_KEY;
+	}
+};
+function firstOperationKeyword(document) {
+	let i = 0;
+	if (document.charCodeAt(0) === 65279) i = 1;
+	while (i < document.length) {
+		const ch = document[i];
+		if (ch === " " || ch === "	" || ch === "\r" || ch === "\n" || ch === ",") {
+			i++;
+			continue;
+		}
+		if (ch === "#") {
+			while (i < document.length && document[i] !== "\n") i++;
+			continue;
+		}
+		break;
+	}
+	const rest = document.slice(i);
+	if (/^mutation\b/.test(rest)) return "mutation";
+	if (/^subscription\b/.test(rest)) return "subscription";
+	if (/^query\b/.test(rest) || rest.startsWith("{")) return "query";
+	return null;
+}
+function containsNonQueryOperation(document) {
+	const stripped = document.replace(/#[^\n]*/g, "").replace(/"""[\s\S]*?"""/g, "\"\"").replace(/"(?:\\.|[^"\\])*"/g, "\"\"");
+	return /\b(mutation|subscription)\b\s*[A-Za-z_][\w]*?\s*[({@]?[\s\S]{0,256}?\{/m.test(stripped) || /\b(mutation|subscription)\b\s*\{/m.test(stripped);
+}
+function composeFieldCall(descriptor) {
+	const inline = stringifyArgs(descriptor.args);
+	const allArgs = [Object.keys(descriptor.vars ?? {}).map((name) => `${name}: $${name}`).join(", "), inline].filter(Boolean).join(", ");
+	return allArgs ? `${descriptor.field}(${allArgs})` : descriptor.field;
+}
+function renderSingleDocument(descriptor) {
+	const fieldCall = composeFieldCall(descriptor);
+	const varDecls = Object.entries(descriptor.vars ?? {}).map(([name, { type }]) => `$${name}: ${type}`).join(", ");
+	const query = `query ${varDecls ? `${descriptor.operation}(${varDecls})` : descriptor.operation} { ${fieldCall} { ${descriptor.selectionSet} } }`;
+	const variables = {};
+	for (const [name, { value }] of Object.entries(descriptor.vars ?? {})) variables[name] = value;
+	return {
+		query,
+		variables
+	};
+}
+function renderBatchDocument(entries) {
+	const mergedVars = {};
+	for (const { descriptor } of entries) for (const [name, def] of Object.entries(descriptor.vars ?? {})) mergedVars[name] = def;
+	const varDecls = Object.entries(mergedVars).map(([name, { type }]) => `$${name}: ${type}`).join(", ");
+	const opSig = varDecls ? `BatchQuery(${varDecls})` : "BatchQuery";
+	const fields = entries.map(({ alias, descriptor }) => `${alias}: ${composeFieldCall(descriptor)} { ${descriptor.selectionSet} }`);
+	const variables = {};
+	for (const [name, { value }] of Object.entries(mergedVars)) variables[name] = value;
+	return {
+		query: `query ${opSig} { ${fields.join(" ")} }`,
+		variables
+	};
+}
+function stringifyArgs(args) {
+	const parts = [];
+	for (const [k, v] of Object.entries(args)) {
+		if (v === void 0) continue;
+		parts.push(`${k}: ${literal(v)}`);
+	}
+	return parts.join(", ");
+}
+function literal(value) {
+	if (value === null) return "null";
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (Array.isArray(value)) return `[${value.map(literal).join(", ")}]`;
+	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 {
+	descriptor;
+	fetchOptions;
+	fetcher;
+	constructor(fetcher, descriptor, fetchOptions = {}) {
+		this.fetcher = fetcher;
+		this.descriptor = descriptor;
+		this.fetchOptions = fetchOptions;
+	}
+	then(onFulfilled, onRejected) {
+		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. */
+function buildCourseSelection(select) {
+	const parts = ["id", "slug"];
+	const sel = select;
+	if (sel.title) parts.push("name");
+	if (sel.description) parts.push("description");
+	if (sel.coverImage) parts.push("image");
+	if (sel.createdAt) parts.push("createdAt");
+	if (sel.lecturer && typeof sel.lecturer === "object") {
+		const lec = sel.lecturer;
+		const lecParts = ["id"];
+		if (lec.name) lecParts.push("name");
+		if (lec.avatar) lecParts.push("avatar");
+		parts.push(`lecturer { ${lecParts.join(" ")} }`);
+	}
+	return parts.join(" ");
+}
+function mapCourse(raw) {
+	const out = {
+		id: raw.id,
+		slug: raw.slug
+	};
+	if (raw.name !== void 0) out.title = raw.name;
+	if (raw.description !== void 0) out.description = raw.description ?? null;
+	if (raw.image !== void 0) out.coverImage = raw.image ?? null;
+	if (raw.createdAt !== void 0) out.createdAt = raw.createdAt;
+	if (raw.lecturer !== void 0) out.lecturer = raw.lecturer ? mapLecturer(raw.lecturer) : null;
+	return out;
+}
+function mapLecturer(raw) {
+	const out = { id: raw.id };
+	if (raw.name !== void 0) out.name = raw.name;
+	if (raw.avatar !== void 0) out.avatar = raw.avatar ?? null;
+	return out;
+}
+function mapCoursePage(raw) {
+	return {
+		items: raw.nodes.map(mapCourse),
+		pageInfo: {
+			page: raw.currentPage,
+			totalPages: raw.totalPages,
+			totalCount: raw.nodesCount,
+			hasNext: raw.hasNextPage,
+			hasPrev: raw.hasPreviousPage
+		}
+	};
+}
+
+//#endregion
+//#region src/resources/courses.ts
+const DEFAULT_LIST_FIELDS = {
+	id: true,
+	slug: true,
+	title: true,
+	coverImage: true
+};
+const DEFAULT_GET_FIELDS = {
+	id: true,
+	slug: true,
+	title: true,
+	description: true,
+	coverImage: true,
+	lecturer: {
+		id: true,
+		name: true,
+		avatar: true
+	}
+};
+function tenantVars(client) {
+	return { subdomain: {
+		type: "String!",
+		value: client.config.tenant ?? ""
+	} };
+}
+var CoursesResource = class {
+	constructor(client) {
+		this.client = client;
+	}
+	/**
+	* List courses for the current tenant.
+	* @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(args = {}, options = {}) {
+		const selectionSet = `nodes { ${buildCourseSelection(args.select ?? DEFAULT_LIST_FIELDS)} } currentPage totalPages nodesCount hasNextPage hasPreviousPage`;
+		return new QueryBuilder(this.client, {
+			operation: "CourseList",
+			field: "courses",
+			selectionSet,
+			args: {
+				page: args.page,
+				perPage: args.limit
+			},
+			vars: tenantVars(this.client),
+			transform: (raw) => mapCoursePage(raw)
+		}, options);
+	}
+	/**
+	* Get a single course by slug. Returns `null` if not found.
+	* @example
+	* const course = await loopwise.courses.get({ slug: 'finance' })
+	* if (!course) return Astro.redirect('/404')
+	*/
+	get(args, options = {}) {
+		const sel = args.select ?? DEFAULT_GET_FIELDS;
+		return new QueryBuilder(this.client, {
+			operation: "CourseGet",
+			field: "course",
+			selectionSet: buildCourseSelection(sel),
+			args: { slug: args.slug },
+			vars: tenantVars(this.client),
+			transform: (raw) => raw == null ? null : mapCourse(raw)
+		}, options);
+	}
+};
+
+//#endregion
+//#region src/index.ts
+function createClient(config) {
+	const client = new LoopwiseClient(config);
+	return {
+		courses: new CoursesResource(client),
+		batch(builders, options) {
+			return client.batch(builders, options);
+		},
+		query(document, variables, operationName, options) {
+			return client.raw(document, variables, operationName, options);
+		}
+	};
+}
+
+//#endregion
+export { LoopwiseError, QueryBuilder, createClient };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@loopwise/sdk",
+  "version": "0.1.0-beta.0",
+  "description": "Loopwise platform SDK — agent-friendly headless API client",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaikhq/manekineko.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/kaikhq/manekineko/tree/develop/packages/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/kaikhq/manekineko/issues"
+  },
+  "keywords": [
+    "loopwise",
+    "teachify",
+    "graphql",
+    "headless",
+    "storefront",
+    "sdk"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "import": "./dist/config.mjs"
+    }
+  },
+  "files": [
+    "dist/*.mjs",
+    "dist/*.d.mts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "tsconfig": "workspace:*",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}