@onabl/next 0.1.2 → 0.1.4

package/README.md

@@ -1,18 +1,63 @@
 # `@onabl/next`
 
-Next.js integration for the onabl SDK. Owns the secret-key-holding server
-layer so an integrator's client components never see it — see
-`docs/SDK-DESIGN.md` §1 for the two-file, eleven-line target this package
-exists to make possible.
-
-**Status:** skeleton only (Phase 14 §14.5.4, not started — `@onabl/react`
-has to land first).
-
-## What belongs here
-
-- `createOnablClient(config)` — re-exported from `@onabl/react`/`@onabl/js`
-  with Next-aware cookie handling
-- `onabl.routes()` — the `{GET, POST, PATCH}` route-handler factory, mounted
-  at `app/api/onabl/[...onabl]/route.ts` in a consumer's app
-- The RSC-safe boundary that makes it structurally impossible to pass server
-  config (the secret key) into a client component
+Next.js integration for the onabl SDK. Provides the server-side route
+handlers and helpers that keep your onabl secret key out of the browser, so
+`@onabl/react`'s hooks have a same-origin proxy to call.
+
+## Install
+
+```bash
+npm install @onabl/next @onabl/react
+```
+
+## Usage
+
+Mount the route handlers at a catch-all API route:
+
+```ts
+// app/api/onabl/[...onabl]/route.ts
+import {createOnablRouteHandlers} from "@onabl/next";
+
+export const {GET, POST, PATCH} = createOnablRouteHandlers({
+  handle: "acme",
+  secretKey: process.env.ONABL_SECRET_KEY!,
+});
+```
+
+Then use `@onabl/react`'s hooks anywhere in your app — `OnablProvider`
+defaults to this route already:
+
+```tsx
+import {OnablProvider} from "@onabl/react";
+
+export default function RootLayout({children}: {children: React.ReactNode}) {
+  return <OnablProvider>{children}</OnablProvider>;
+}
+```
+
+For a Server Component quote or invoice page (e.g. an emailed link opened
+with `?token=`), use `createOnablServerClient` to fetch data directly, and
+`setAccessCookieOn` to persist the token so subsequent client-side actions
+(accept/decline, POP upload) are authenticated:
+
+```ts
+import {createOnablServerClient, setAccessCookieOn} from "@onabl/next";
+
+const onabl = createOnablServerClient({
+  handle: "acme",
+  secretKey: process.env.ONABL_SECRET_KEY!,
+});
+
+const quote = await onabl.quotes.get(uuid, {token});
+```
+
+## What's included
+
+- `createOnablRouteHandlers(config)` — the `{GET, POST, PATCH}` route
+  handler factory for your proxy route
+- `createOnablServerClient(config)` — a server-side client for Server
+  Components/Server Actions
+- `setAccessCookieOn(res, uuid, token)` — persists a customer access token
+  as an httpOnly cookie
+- `accessCookieName`, `ACCESS_COOKIE_MAX_AGE_SECONDS` — cookie naming/expiry
+  constants, if you need to read the cookie yourself (e.g. in middleware)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onabl/next",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Next.js integration for the onabl SDK — server-action-free route-handler factory, cookie-aware client, RSC-safe boundary. See docs/SDK-DESIGN.md.",
   "license": "MIT",
   "repository": {
@@ -31,12 +31,12 @@
     "tsup": "^8.0.0",
     "vitest": "^1.6.0",
     "typescript": "^5.4.0",
-    "@onabl/typescript-config": "0.0.1",
-    "@onabl/eslint-config": "0.0.1"
+    "@onabl/eslint-config": "0.0.1",
+    "@onabl/typescript-config": "0.0.1"
   },
   "dependencies": {
-    "@onabl/react": "0.1.2",
-    "@onabl/js": "0.1.2"
+    "@onabl/js": "0.1.4",
+    "@onabl/react": "0.1.4"
   },
   "peerDependencies": {
     "next": "^16",