@loopwise/sdk 0.1.0-beta.0 → 0.1.0-beta.1

package/README.md

@@ -1,37 +1,78 @@
 # @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.
+Storefront GraphQL client for Loopwise / Teachify. Pick your path:
 
-## Quick start
+| You are producing… | Install | Module spec |
+|---|---|---|
+| 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)) | — |
+
+Same package powers all three; the difference is the loader.
+
+## Quick start — bundler
 
 ```ts
 import { createClient } from '@loopwise/sdk';
 
+// Browser, same-origin (the page is served from the tenant origin):
 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.
+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.
+
+## Quick start — single-file HTML (no build)
+
+```html
+<!doctype html>
+<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.
+  const loopwise = createClient({});
+  const { items } = await loopwise.courses.list({ limit: 20 });
+  document.body.textContent = items.map(c => c.title).join(', ');
+</script>
+```
 
-### Cross-origin / SSR (advanced)
+## Cross-origin (Loopwise Pages preview, SSR, build pipelines)
 
-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.
+When the SDK runs **outside** a tenant origin, pass `tenant` explicitly so
+the SDK can pick the right Rails origin to call.
 
 ```ts
 const loopwise = createClient({
-  tenant: 'acme',
-  apiKey: process.env.LOOPWISE_API_KEY, // SSR / build only
+  tenant: 'acme',                       // required cross-origin
+  apiKey: process.env.LOOPWISE_API_KEY, // required in SSR / build (browser ignores)
 });
 ```
 
-## Cache option (`cache`)
+### Where this matters most: `deploy_static_page`
+
+Pages deployed via `deploy_static_page` live at `https://<script>.loopwise.page/`
+— that is **not** a tenant origin, so:
+
+- 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.
+
+```ts
+// Inside an HTML bundle deployed to https://lw-acme-home.loopwise.page/
+const loopwise = createClient({ tenant: 'acme' });
+const { items } = await loopwise.courses.list({ limit: 20 }, { cache: 60 });
+```
+
+For preview UX that needs authenticated state, see
+[Preview modes](#preview-modes) below.
+
+## `cache` option
 
 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
@@ -79,12 +120,46 @@ 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.
 
+## Preview modes
+
+Two preview surfaces exist, each with different capability:
+
+| Surface | Origin | Same-origin BFF? | 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 |
+
+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).
+
+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).
+
+## React — coming soon
+
+A `@loopwise/sdk-react` companion package is planned, providing:
+
+- `<LoopwiseProvider client={loopwise}>` context provider
+- `useCourses({ limit })`, `useCourse({ slug })` hooks with Suspense support
+- `useBatch(...)` for composed queries
+- Cache and refetch control matching the underlying SDK's `cache` option
+
+Until it ships, the vanilla SDK works inside React — you'll just wire up
+your own state (`useEffect` + `useState`, TanStack Query, etc.).
+
 ## Public API
 
-- `createClient(config)` — storefront client. `config.tenant` is optional
-  in the browser (BFF derives it from host) and required in SSR / build.
+- `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.
 - `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.
+- `loopwise.query<T>(document, variables?, operationName?, options?)` — raw GraphQL escape hatch.
 
 See `apps/sdk-runtime-poc/` for a runnable browser validation page.

package/dist/index.mjs

@@ -40,10 +40,11 @@ var LoopwiseClient = class {
 		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`;
+		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`;
 	}
 	async execute(descriptor, options = {}) {
 		const document = renderSingleDocument(descriptor);

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@loopwise/sdk",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.1",
   "description": "Loopwise platform SDK — agent-friendly headless API client",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kaikhq/manekineko.git",
+    "url": "git+https://github.com/kaikhq/manekineko.git",
     "directory": "packages/sdk"
   },
-  "homepage": "https://github.com/kaikhq/manekineko/tree/develop/packages/sdk#readme",
+  "homepage": "https://www.npmjs.com/package/@loopwise/sdk",
   "bugs": {
     "url": "https://github.com/kaikhq/manekineko/issues"
   },