@biab-dev/sdk 0.2.1 → 0.7.2

package/README.md

@@ -45,29 +45,439 @@ The scaffold currently provides:
 
 ## Example
 
+The SDK has two surfaces: a low-level client over the package API, and
+site-scoped helpers under `client.site(siteId)`.
+
 ```ts
 import { createBiabDevClient } from "@biab-dev/sdk";
 
 const client = createBiabDevClient({
-	baseUrl: "https://host.example.com/api/package/v1",
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!, // ends in /api/package/v1
 	apiKey: process.env.BIAB_API_KEY!,
 });
 
-const site = client.site("00000000-0000-0000-0000-000000000000");
+// Identity probe — always the first call in a fresh integration.
+const auth = await client.introspect();
+
+const site = client.site(process.env.BIAB_SITE_ID!);
+
+// Marketing-page JSON edited from Site Builder → Marketing pages
+const { page } = await site.marketingPages.get("home");
 
-await client.introspect();
+// Custom collections
 await site.collections.list();
-await site.collections.get("products");
-await site.rows.query("products", {
-	filters: [{ fieldName: "title", operator: "contains", value: "chair" }],
+await site.rows.query("page-content", {
+	filters: [{ fieldName: "pageKey", operator: "equals", value: "home" }],
 	limit: 10,
 });
 ```
 
+### End-to-end consumer pattern
+
+`custom-demo/src/lib/biab/get-home-content.ts` in this monorepo is the
+canonical consumer pattern: it normalizes the base URL (https-only, ends in
+`/api/package/v1`), reads the marketing-page JSON via the SDK, and falls back
+to a local `content.md` document if the env is not configured. Copy that file
+when you build a new frontend that consumes BIAB content.
+
+## Tenant auth (sign-in / sign-up / sign-out)
+
+The SDK includes per-tenant authentication built on WorkOS Organizations. A
+visitor who clicks "Sign in" on your site is signed in to **the org bound to
+your API key** — not to BIAB itself. Sign-up, sign-in, password reset, MFA,
+social login, and invitations are all handled by WorkOS's hosted page.
+
+### How it works
+
+1. Visitor clicks `<SignIn />` (a styled link).
+2. Browser hits your installed `/api/biab-auth/sign-in` route.
+3. SDK redirects to WorkOS's hosted page, scoped to your org.
+4. After auth, WorkOS redirects to your installed `/api/biab-auth/callback`.
+5. SDK exchanges the code, sets an httpOnly session cookie on **your domain**,
+   redirects the user to `returnTo`.
+6. Subsequent requests can read the session via `useUser()` (client) or
+   `getTenantSession()` (server / SSR).
+
+Cookie lives on your tenant's domain, not BIAB's — so your SSR can read it,
+and there's no XSS-readable token floating around.
+
+### One-time WorkOS configuration
+
+Before the SDK auth flow works for your site, your BIAB platform admin (or
+you, via the WorkOS dashboard if you have access) must register your
+callback URL as an allowed **Redirect URI** for the WorkOS Organization
+bound to your API key:
+
+1. Open the [WorkOS dashboard](https://dashboard.workos.com).
+2. Go to **Configuration → Redirects**.
+3. Click **Add Redirect URI** and enter your callback URL exactly:
+   - Production: `https://your-site.com/api/biab-auth/callback`
+   - Local dev: `http://localhost:3000/api/biab-auth/callback`
+4. Save. WorkOS will reject the auth flow with `redirect_uri_mismatch` if
+   this URL isn't registered byte-for-byte.
+
+If you self-host BIAB or are using a sandbox, the same applies to the WorkOS
+project that issued your platform's `WORKOS_CLIENT_ID`.
+
+### Install the auth handler
+
+`createAuthHandler` returns Fetch-standard handlers — they accept a `Request`
+and return a `Response`. Mount the same factory in any framework that speaks
+Web standards. The React components below are framework-agnostic; only the
+handler install line differs.
+
+In every example, mount the handler at a path that **matches the
+`callbackUrl` you registered with WorkOS** — a mismatch produces
+`redirect_uri_mismatch`.
+
+#### Next.js (App Router)
+
+```ts
+// app/api/biab-auth/[...biab]/route.ts
+import { createAuthHandler } from "@biab-dev/sdk";
+
+const handler = createAuthHandler({
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+	apiKey: process.env.BIAB_API_KEY!,
+	callbackUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/api/biab-auth/callback`,
+});
+
+export const GET = handler.GET;
+export const POST = handler.POST;
+```
+
+#### Next.js (Pages Router)
+
+Pages Router uses Node `req`/`res`, not Fetch. Wrap the handler:
+
+```ts
+// pages/api/biab-auth/[...biab].ts
+import { createAuthHandler } from "@biab-dev/sdk";
+import type { NextApiRequest, NextApiResponse } from "next";
+
+const handler = createAuthHandler({
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+	apiKey: process.env.BIAB_API_KEY!,
+	callbackUrl: `${process.env.NEXT_PUBLIC_SITE_URL}/api/biab-auth/callback`,
+});
+
+export default async function (req: NextApiRequest, res: NextApiResponse) {
+	const url = new URL(req.url!, `https://${req.headers.host}`);
+	const request = new Request(url, {
+		method: req.method,
+		headers: new Headers(req.headers as Record<string, string>),
+		body: req.method === "GET" || req.method === "HEAD"
+			? undefined
+			: JSON.stringify(req.body),
+	});
+	const response = await (req.method === "POST" ? handler.POST : handler.GET)(
+		request,
+	);
+	response.headers.forEach((v, k) => res.setHeader(k, v));
+	res.status(response.status).send(await response.text());
+}
+```
+
+#### Remix
+
+```ts
+// app/routes/api.biab-auth.$.tsx
+import { createAuthHandler } from "@biab-dev/sdk";
+import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";
+
+const handler = createAuthHandler({
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+	apiKey: process.env.BIAB_API_KEY!,
+	callbackUrl: `${process.env.SITE_URL}/api/biab-auth/callback`,
+});
+
+export const loader = ({ request }: LoaderFunctionArgs) => handler.GET(request);
+export const action = ({ request }: ActionFunctionArgs) => handler.POST(request);
+```
+
+#### SvelteKit
+
+```ts
+// src/routes/api/biab-auth/[...biab]/+server.ts
+import { createAuthHandler } from "@biab-dev/sdk";
+import { env } from "$env/dynamic/private";
+import { env as pubEnv } from "$env/dynamic/public";
+
+const handler = createAuthHandler({
+	baseUrl: env.BIAB_PACKAGE_API_BASE_URL,
+	apiKey: env.BIAB_API_KEY,
+	callbackUrl: `${pubEnv.PUBLIC_SITE_URL}/api/biab-auth/callback`,
+});
+
+export const GET = ({ request }) => handler.GET(request);
+export const POST = ({ request }) => handler.POST(request);
+```
+
+#### Astro
+
+```ts
+// src/pages/api/biab-auth/[...biab].ts
+import { createAuthHandler } from "@biab-dev/sdk";
+import type { APIRoute } from "astro";
+
+const handler = createAuthHandler({
+	baseUrl: import.meta.env.BIAB_PACKAGE_API_BASE_URL,
+	apiKey: import.meta.env.BIAB_API_KEY,
+	callbackUrl: `${import.meta.env.PUBLIC_SITE_URL}/api/biab-auth/callback`,
+});
+
+export const GET: APIRoute = ({ request }) => handler.GET(request);
+export const POST: APIRoute = ({ request }) => handler.POST(request);
+```
+
+> Astro requires `output: "server"` (or `"hybrid"`) and an SSR-capable adapter
+> for cookies and `Response.redirect` to work. Static-only Astro can't host
+> the auth handler.
+
+#### Hono / Cloudflare Workers / Bun / Deno
+
+These runtimes are already Fetch-native — pass the raw `Request` through:
+
+```ts
+// Hono
+import { Hono } from "hono";
+import { createAuthHandler } from "@biab-dev/sdk";
+
+const app = new Hono();
+const handler = createAuthHandler({
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+	apiKey: process.env.BIAB_API_KEY!,
+	callbackUrl: `${process.env.SITE_URL}/api/biab-auth/callback`,
+});
+
+app.all("/api/biab-auth/*", (c) =>
+	c.req.method === "POST" ? handler.POST(c.req.raw) : handler.GET(c.req.raw),
+);
+```
+
+```ts
+// Cloudflare Worker (or Bun.serve / Deno.serve)
+import { createAuthHandler } from "@biab-dev/sdk";
+
+const handler = createAuthHandler({
+	baseUrl: env.BIAB_PACKAGE_API_BASE_URL,
+	apiKey: env.BIAB_API_KEY,
+	callbackUrl: `${env.SITE_URL}/api/biab-auth/callback`,
+});
+
+export default {
+	async fetch(request: Request) {
+		const { pathname } = new URL(request.url);
+		if (pathname.startsWith("/api/biab-auth")) {
+			return request.method === "POST"
+				? handler.POST(request)
+				: handler.GET(request);
+		}
+		return new Response("Not found", { status: 404 });
+	},
+};
+```
+
+#### Express / Fastify (Node)
+
+Use a Web-standards adapter such as `@whatwg-node/server` or
+`fastify-web-standards` to bridge Node `req`/`res` ↔ Fetch `Request`/`Response`,
+then call `handler.GET(request)` / `handler.POST(request)`. The adapter does
+the conversion the Pages Router example does inline.
+
+#### Nuxt 3 (Nitro)
+
+Nitro server routes get a Fetch-style `event.node.req`. Use `toWebRequest`
+from `h3` to bridge:
+
+```ts
+// server/api/biab-auth/[...biab].ts
+import { createAuthHandler } from "@biab-dev/sdk";
+import { toWebRequest } from "h3";
+
+const handler = createAuthHandler({
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+	apiKey: process.env.BIAB_API_KEY!,
+	callbackUrl: `${process.env.NUXT_PUBLIC_SITE_URL}/api/biab-auth/callback`,
+});
+
+export default defineEventHandler(async (event) => {
+	const request = toWebRequest(event);
+	return event.node.req.method === "POST"
+		? handler.POST(request)
+		: handler.GET(request);
+});
+```
+
+#### TanStack Start
+
+TanStack Start API routes return Web-standards Responses directly.
+
+```ts
+// app/routes/api/biab-auth.$.ts
+import { createAPIFileRoute } from "@tanstack/start/api";
+import { createAuthHandler } from "@biab-dev/sdk";
+
+const handler = createAuthHandler({
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+	apiKey: process.env.BIAB_API_KEY!,
+	callbackUrl: `${process.env.SITE_URL}/api/biab-auth/callback`,
+});
+
+export const Route = createAPIFileRoute("/api/biab-auth/$")({
+	GET: ({ request }) => handler.GET(request),
+	POST: ({ request }) => handler.POST(request),
+});
+```
+
+#### SolidStart
+
+```ts
+// src/routes/api/biab-auth/[...biab].ts
+import { createAuthHandler } from "@biab-dev/sdk";
+import type { APIEvent } from "@solidjs/start/server";
+
+const handler = createAuthHandler({
+	baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+	apiKey: process.env.BIAB_API_KEY!,
+	callbackUrl: `${process.env.SITE_URL}/api/biab-auth/callback`,
+});
+
+export const GET = ({ request }: APIEvent) => handler.GET(request);
+export const POST = ({ request }: APIEvent) => handler.POST(request);
+```
+
+#### Vite SPA, plain Svelte, plain Vue, plain Solid
+
+Pure client-side apps **don't have a server**, so they can't mount
+`createAuthHandler` directly — there's no place to store a secret API key
+or set an httpOnly cookie. You need an adjacent server runtime:
+
+- Cloudflare Workers / Deno Deploy / Bun.serve / Express → use the example
+  above for that runtime, then point your Vite SPA at its hostname.
+- Or upgrade to the framework's full-stack variant (SvelteKit instead of
+  Svelte, Nuxt instead of Vue, SolidStart instead of Solid).
+
+There's no client-only mode for the auth handler by design — the API key
+must stay on a server.
+
+### Non-React UI components
+
+The `<SignIn />` / `<SignUp />` / `<SignOut />` / `useUser()` exports under
+`@biab-dev/sdk/react` are React-specific. Other frameworks can build the
+exact same UI with two trivial primitives once the auth handler is mounted:
+
+1. **Buttons are links.** Sign-in/up/out are plain anchors:
+
+```html
+<a href="/api/biab-auth/sign-in">Sign in</a>
+<a href="/api/biab-auth/sign-up">Create account</a>
+<a href="/api/biab-auth/sign-out">Sign out</a>
+```
+
+Add `?returnTo=/dashboard` or `?loginHint=user@example.com` query params
+as needed.
+
+2. **Reading the session.** `GET /api/biab-auth/me` returns the current user
+   or `null`. Same shape as `useUser()`'s React hook:
+
+```js
+const session = await fetch("/api/biab-auth/me", { credentials: "include" })
+	.then((r) => r.json());
+// → { user: {...}, organizationId, role } | null
+```
+
+Wire that into your framework's reactivity primitive of choice (Svelte
+stores, Vue `ref`, Solid signals, vanilla `useState`).
+
+### Drop the components into your pages
+
+These are plain React components — they work in any framework that can render
+React (Next.js, Remix, SvelteKit-with-React, Astro, Vite SPAs, etc.). Only
+the handler install above differs per framework.
+
+```tsx
+// app/page.tsx
+import { SignIn, SignOut, SignUp, useUser } from "@biab-dev/sdk/react";
+
+export default function Home() {
+	const me = useUser();
+
+	if (me.status === "loading") return null;
+
+	if (me.status === "signed-in") {
+		return (
+			<div>
+				<p>Hi, {me.user.user.firstName ?? me.user.user.email}.</p>
+				<SignOut className="btn">Sign out</SignOut>
+			</div>
+		);
+	}
+
+	return (
+		<div>
+			<SignIn className="btn">Sign in</SignIn>
+			<SignUp className="btn btn-secondary">Create account</SignUp>
+		</div>
+	);
+}
+```
+
+### Reading the session in SSR
+
+```ts
+// app/dashboard/page.tsx
+import { cookies } from "next/headers";
+import { DEFAULT_AUTH_COOKIE_NAME, getTenantSession } from "@biab-dev/sdk";
+
+export default async function Dashboard() {
+	const cookieValue = (await cookies()).get(DEFAULT_AUTH_COOKIE_NAME)?.value;
+	const session = await getTenantSession({
+		cookieValue,
+		baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+		apiKey: process.env.BIAB_API_KEY!,
+	});
+
+	if (!session) redirect("/");
+	return <p>Welcome, {session.user.email}.</p>;
+}
+```
+
+### Invitations (existing-vs-new users)
+
+Invitations sent from the WorkOS dashboard work for both cases automatically:
+
+- **Existing user** → invitation link signs them in and adds them to the org.
+- **New user** → invitation link prompts them to set a password, creates the
+  user, and adds them to the org.
+
+In both cases the BIAB host syncs the membership into its database on the
+first authed callback. You don't need to write any invitation acceptance
+code — link them at the WorkOS-generated URL and the rest is handled.
+
+## Configuration
+
+| Env var | Where it comes from |
+| --- | --- |
+| `BIAB_API_KEY` | One-time reveal in **Site Builder → Developer → Package API & Unkey keys** in the host app. |
+| `BIAB_SITE_ID` | The "Site ID" shown directly above the API key list in the same panel. |
+| `BIAB_PACKAGE_API_BASE_URL` | The "Package API base URL" shown above — **always `https://` for production**, and the URL **must** end in `/api/package/v1`. |
+
+> **Two production traps to avoid:**
+> 1. `http://` against a production host. The host responds `308 → https://`,
+>    and `fetch` strips the `Authorization` header on cross-scheme redirects
+>    per the WHATWG fetch spec — the redirected request lands unauthenticated.
+> 2. A base URL that does **not** include `/api/package/v1`. SDK versions
+>    ≤ 0.2.0 silently drop the base URL's pathname when constructing site-scoped
+>    requests; 0.2.1 fixes this. Either upgrade or include the path component
+>    in the env var.
+
 ## Notes
 
-- This package is scaffolded first; the host package routes still need to be implemented.
-- Collection contracts intentionally mirror the current BIAB `site_data_*` model instead of inventing a second schema system.
+- Collection contracts intentionally mirror the current BIAB `site_data_*`
+  model instead of inventing a second schema system.
+- The host owns API key verification, scope enforcement, RBAC, persistence,
+  and audit. The SDK is a transport + typed contract layer.
 
 ## Publishing to npm
 

package/dist/auth-handler.d.ts

@@ -0,0 +1,91 @@
+/**
+ * SDK auth handler — the file a tenant developer mounts on their own site
+ * to handle the WorkOS callback. Cookie lives on the tenant's domain so the
+ * tenant's SSR can read it via standard cookie APIs.
+ *
+ * Usage (Next.js App Router):
+ *
+ *   // app/api/biab-auth/[...biab]/route.ts
+ *   import { createAuthHandler } from "@biab-dev/sdk";
+ *
+ *   const handler = createAuthHandler({
+ *     baseUrl: process.env.BIAB_PACKAGE_API_BASE_URL!,
+ *     apiKey: process.env.BIAB_API_KEY!,
+ *     callbackUrl: "https://my-site.com/api/biab-auth/callback",
+ *   });
+ *
+ *   export const GET = handler.GET;
+ *   export const POST = handler.POST;
+ *
+ * Then drop <SignIn />, <SignUp />, <SignOut /> into your pages — they call
+ * `/api/biab-auth/sign-in?intent=sign-in` etc., which 302s through the WorkOS
+ * hosted page and back to `callbackUrl`. The handler exchanges the code,
+ * sets the session cookie, and redirects the user to `returnTo`.
+ */
+import { type BiabDevClientOptions } from "./client";
+export declare const DEFAULT_AUTH_COOKIE_NAME = "biab_session";
+export declare const DEFAULT_AUTH_BASE_PATH = "/api/biab-auth";
+export type CreateAuthHandlerOptions = {
+    /** BIAB platform base URL — e.g. https://app.biab.com/api/package/v1 */
+    baseUrl: string;
+    /** Org-bound package API key (server-side secret). */
+    apiKey: string;
+    /**
+     * Public, fully-qualified URL of THIS handler's `/callback` route on the
+     * tenant's domain. Must be registered as a redirect URI in WorkOS.
+     */
+    callbackUrl: string;
+    /** Where to send the user after successful sign-in if no `returnTo` was passed. */
+    defaultReturnTo?: string;
+    /** Where to send the user after sign-out. Defaults to "/". */
+    signOutReturnTo?: string;
+    /** Cookie name. Defaults to "biab_session". */
+    cookieName?: string;
+    /**
+     * Cookie domain. Leave undefined to scope to current host. Set if you want
+     * to share the session across subdomains (e.g. ".my-site.com").
+     */
+    cookieDomain?: string;
+    /**
+     * The base path this handler is mounted at — used to derive sub-routes.
+     * Defaults to "/api/biab-auth". Must match the route file location.
+     */
+    basePath?: string;
+    /** Optional fetch override (testing, edge runtimes). */
+    fetch?: BiabDevClientOptions["fetch"];
+    /**
+     * Origin sent on every server-to-server request to the platform. Defaults
+     * to the origin of `callbackUrl`. Override only when your dev/prod hosts
+     * differ from the callback (rare).
+     */
+    siteOrigin?: string;
+};
+type SimpleHandler = (request: Request) => Promise<Response>;
+export type AuthHandlerRoutes = {
+    GET: SimpleHandler;
+    POST: SimpleHandler;
+};
+export declare function createAuthHandler(options: CreateAuthHandlerOptions): AuthHandlerRoutes;
+/**
+ * Server-side helper for tenant SSR: read the current session from the cookie.
+ * Returns null when the user isn't signed in.
+ */
+export declare function getTenantSession(input: {
+    cookieValue: string | null | undefined;
+    baseUrl: string;
+    apiKey: string;
+    /** Required when the API key has Allowed Host set; see {@link BiabDevClientOptions.siteOrigin}. */
+    siteOrigin?: string;
+    fetch?: BiabDevClientOptions["fetch"];
+}): Promise<{
+    role: string | null;
+    user: {
+        id: string;
+        email: string | null;
+        firstName: string | null;
+        lastName: string | null;
+    };
+    organizationId: string;
+} | null>;
+export {};
+//# sourceMappingURL=auth-handler.d.ts.map

package/dist/auth-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-handler.d.ts","sourceRoot":"","sources":["../src/auth-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAEN,KAAK,oBAAoB,EACzB,MAAM,UAAU,CAAC;AAGlB,eAAO,MAAM,wBAAwB,iBAAiB,CAAC;AACvD,eAAO,MAAM,sBAAsB,mBAAmB,CAAC;AAEvD,MAAM,MAAM,wBAAwB,GAAG;IACtC,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,KAAK,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,KAAK,aAAa,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE7D,MAAM,MAAM,iBAAiB,GAAG;IAC/B,GAAG,EAAE,aAAa,CAAC;IACnB,IAAI,EAAE,aAAa,CAAC;CACpB,CAAC;AAkGF,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,wBAAwB,GAC/B,iBAAiB,CA0GnB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE;IAC7C,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,mGAAmG;IACnG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;CACtC;;;;;;;;;UASA"}