@onabl/next 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2026 Onabl (Pty) Ltd. All rights reserved.
+
+This package is proprietary software owned by Onabl (Pty) Ltd ("Onabl").
+
+You may install and use this package only to connect your own websites and
+applications to the Onabl service, while you hold an Onabl account or have
+Onabl's written permission, and subject to Onabl's terms of service.
+
+Without Onabl's prior written permission, you may not:
+
+  1. copy, modify, publish, distribute, sublicense or sell this package or any
+     part of it, except as part of an application that uses the Onabl service;
+  2. decompile, reverse engineer or otherwise try to derive the source code,
+     algorithms or pricing logic of the Onabl service from it; or
+  3. use this package, or any part of it, to build or support a product or
+     service that competes with Onabl.
+
+THIS PACKAGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL ONABL
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM, OUT OF OR IN
+CONNECTION WITH THIS PACKAGE OR ITS USE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# `@onabl/next`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/dist/index.d.mts

@@ -0,0 +1,51 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { OnablClientConfig, OnablClient } from '@onabl/js';
+
+type OnablNextConfig = OnablClientConfig;
+
+interface OnablRouteHandlers {
+    GET: (req: NextRequest) => Promise<Response>;
+    POST: (req: NextRequest) => Promise<Response>;
+    PATCH: (req: NextRequest) => Promise<Response>;
+}
+/**
+ * Route-handler factory for the same-origin proxy every @onabl/react hook
+ * calls (see packages/react/src/context.tsx) — the reference implementation
+ * of onabl.routes() described in docs/SDK-DESIGN.md §14.5.4. Mount the
+ * returned {GET, POST, PATCH} at a single catch-all route matching
+ * `basePath`, e.g. `app/api/onabl/[...onabl]/route.ts`:
+ *
+ *   export const {GET, POST, PATCH} = createOnablRouteHandlers({
+ *     handle: "acme",
+ *     secretKey: process.env.ONABL_SECRET_KEY!,
+ *     basePath: "/api/onabl",
+ *   });
+ *
+ * Holds config.secretKey server-side only — it never reaches the browser.
+ * Customer access tokens (quote/invoice-scoped, not secrets in the same
+ * sense) are read from/written to an httpOnly cookie per resource UUID (see
+ * cookies.ts) so browser-side hooks never need to carry or send one.
+ */
+declare function createOnablRouteHandlers(config: OnablNextConfig & {
+    basePath?: string;
+}): OnablRouteHandlers;
+
+/**
+ * For Server Component pages (the quote/invoice view pages) to fetch data
+ * with a token read straight off the URL (or props) — not the cookie, since
+ * a Server Component can't set cookies itself. Use together with
+ * `setAccessCookieOn` in a Route Handler the page's first client-side
+ * interaction goes through, or call `setAccessCookieOn` on a redirect
+ * response if the page needs the cookie persisted from a bare `?token=`
+ * link (e.g. an emailed invoice link opened on a device that never went
+ * through the submission flow, so no cookie exists yet).
+ */
+declare function createOnablServerClient(config: OnablNextConfig): OnablClient;
+/** Persists a customer access token as the same httpOnly cookie createOnablRouteHandlers() reads — call this from a Route Handler or Server Action, never from render. */
+declare function setAccessCookieOn(res: NextResponse, uuid: string, token: string): void;
+
+declare function accessCookieName(uuid: string): string;
+/** 30 days — matches the quote/invoice UUID's own practical lifetime; the API is the real source of truth on expiry, this is just how long the browser bothers to keep offering the token. */
+declare const ACCESS_COOKIE_MAX_AGE_SECONDS: number;
+
+export { ACCESS_COOKIE_MAX_AGE_SECONDS, type OnablNextConfig, type OnablRouteHandlers, accessCookieName, createOnablRouteHandlers, createOnablServerClient, setAccessCookieOn };

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { OnablClientConfig, OnablClient } from '@onabl/js';
+
+type OnablNextConfig = OnablClientConfig;
+
+interface OnablRouteHandlers {
+    GET: (req: NextRequest) => Promise<Response>;
+    POST: (req: NextRequest) => Promise<Response>;
+    PATCH: (req: NextRequest) => Promise<Response>;
+}
+/**
+ * Route-handler factory for the same-origin proxy every @onabl/react hook
+ * calls (see packages/react/src/context.tsx) — the reference implementation
+ * of onabl.routes() described in docs/SDK-DESIGN.md §14.5.4. Mount the
+ * returned {GET, POST, PATCH} at a single catch-all route matching
+ * `basePath`, e.g. `app/api/onabl/[...onabl]/route.ts`:
+ *
+ *   export const {GET, POST, PATCH} = createOnablRouteHandlers({
+ *     handle: "acme",
+ *     secretKey: process.env.ONABL_SECRET_KEY!,
+ *     basePath: "/api/onabl",
+ *   });
+ *
+ * Holds config.secretKey server-side only — it never reaches the browser.
+ * Customer access tokens (quote/invoice-scoped, not secrets in the same
+ * sense) are read from/written to an httpOnly cookie per resource UUID (see
+ * cookies.ts) so browser-side hooks never need to carry or send one.
+ */
+declare function createOnablRouteHandlers(config: OnablNextConfig & {
+    basePath?: string;
+}): OnablRouteHandlers;
+
+/**
+ * For Server Component pages (the quote/invoice view pages) to fetch data
+ * with a token read straight off the URL (or props) — not the cookie, since
+ * a Server Component can't set cookies itself. Use together with
+ * `setAccessCookieOn` in a Route Handler the page's first client-side
+ * interaction goes through, or call `setAccessCookieOn` on a redirect
+ * response if the page needs the cookie persisted from a bare `?token=`
+ * link (e.g. an emailed invoice link opened on a device that never went
+ * through the submission flow, so no cookie exists yet).
+ */
+declare function createOnablServerClient(config: OnablNextConfig): OnablClient;
+/** Persists a customer access token as the same httpOnly cookie createOnablRouteHandlers() reads — call this from a Route Handler or Server Action, never from render. */
+declare function setAccessCookieOn(res: NextResponse, uuid: string, token: string): void;
+
+declare function accessCookieName(uuid: string): string;
+/** 30 days — matches the quote/invoice UUID's own practical lifetime; the API is the real source of truth on expiry, this is just how long the browser bothers to keep offering the token. */
+declare const ACCESS_COOKIE_MAX_AGE_SECONDS: number;
+
+export { ACCESS_COOKIE_MAX_AGE_SECONDS, type OnablNextConfig, type OnablRouteHandlers, accessCookieName, createOnablRouteHandlers, createOnablServerClient, setAccessCookieOn };

package/dist/index.js

@@ -0,0 +1,156 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ACCESS_COOKIE_MAX_AGE_SECONDS: () => ACCESS_COOKIE_MAX_AGE_SECONDS,
+  accessCookieName: () => accessCookieName,
+  createOnablRouteHandlers: () => createOnablRouteHandlers,
+  createOnablServerClient: () => createOnablServerClient,
+  setAccessCookieOn: () => setAccessCookieOn
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/route-handlers.ts
+var import_js2 = require("@onabl/js");
+var import_server = require("next/server");
+
+// src/config.ts
+var import_js = require("@onabl/js");
+function buildClient(config) {
+  return (0, import_js.createOnablClient)(config);
+}
+
+// src/cookies.ts
+var COOKIE_PREFIX = "onabl_access_";
+function accessCookieName(uuid) {
+  return `${COOKIE_PREFIX}${uuid}`;
+}
+var ACCESS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30;
+
+// src/route-handlers.ts
+function errorResponse(err) {
+  if (err instanceof import_js2.OnablError) {
+    return import_server.NextResponse.json({ message: err.message }, { status: err.status ?? 400 });
+  }
+  return import_server.NextResponse.json({ message: "Unexpected error" }, { status: 500 });
+}
+function subpath(req, basePath) {
+  const { pathname } = req.nextUrl;
+  return pathname.startsWith(basePath) ? pathname.slice(basePath.length) : pathname;
+}
+function createOnablRouteHandlers(config) {
+  const basePath = config.basePath ?? "/api/onabl";
+  const client = buildClient(config);
+  async function handleGet(req) {
+    const path = subpath(req, basePath);
+    if (path === "/forms/validate-code") {
+      const code = req.nextUrl.searchParams.get("code") ?? "";
+      const result = await client.forms.validateDiscountCode(code);
+      return import_server.NextResponse.json(result);
+    }
+    return import_server.NextResponse.json({ message: "Not found" }, { status: 404 });
+  }
+  async function handlePost(req) {
+    const path = subpath(req, basePath);
+    if (path === "/submissions") {
+      const body = await req.json();
+      const created = await client.submissions.create(body.answers, {
+        consentGiven: body.consentGiven,
+        discountCode: body.discountCode
+      });
+      const res = import_server.NextResponse.json({ quoteId: created.quoteId, quoteUrl: created.quoteUrl });
+      res.cookies.set(accessCookieName(created.quoteId), created.token, {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: true,
+        maxAge: ACCESS_COOKIE_MAX_AGE_SECONDS,
+        path: "/"
+      });
+      return res;
+    }
+    if (path === "/storage/presign") {
+      const body = await req.json();
+      const token = req.cookies.get(accessCookieName(body.resourceId))?.value;
+      if (!token) return import_server.NextResponse.json({ message: "No access token for this resource" }, { status: 401 });
+      const result = await client.storage.presignPop(body.resourceId, body.filename, body.contentType, body.fileSize, { token });
+      return import_server.NextResponse.json(result);
+    }
+    const acceptMatch = /^\/quotes\/([^/]+)\/accept$/.exec(path);
+    if (acceptMatch) {
+      const uuid = acceptMatch[1];
+      const token = req.cookies.get(accessCookieName(uuid))?.value;
+      if (!token) return import_server.NextResponse.json({ message: "No access token for this quote" }, { status: 401 });
+      await client.quotes.accept(uuid, { token }, await req.json().catch(() => ({})));
+      return import_server.NextResponse.json({ accepted: true });
+    }
+    const declineMatch = /^\/quotes\/([^/]+)\/decline$/.exec(path);
+    if (declineMatch) {
+      const uuid = declineMatch[1];
+      const token = req.cookies.get(accessCookieName(uuid))?.value;
+      if (!token) return import_server.NextResponse.json({ message: "No access token for this quote" }, { status: 401 });
+      const body = await req.json();
+      await client.quotes.decline(uuid, body.declineReason, body.declineNote, { token });
+      return import_server.NextResponse.json({ declined: true });
+    }
+    return import_server.NextResponse.json({ message: "Not found" }, { status: 404 });
+  }
+  async function handlePatch(req) {
+    const path = subpath(req, basePath);
+    const popMatch = /^\/invoices\/([^/]+)\/pop$/.exec(path);
+    if (popMatch) {
+      const uuid = popMatch[1];
+      const token = req.cookies.get(accessCookieName(uuid))?.value;
+      if (!token) return import_server.NextResponse.json({ message: "No access token for this invoice" }, { status: 401 });
+      const body = await req.json();
+      await client.invoices.savePopUrl(uuid, body.key, body.milestone, { token });
+      return import_server.NextResponse.json({ saved: true });
+    }
+    return import_server.NextResponse.json({ message: "Not found" }, { status: 404 });
+  }
+  return {
+    GET: (req) => handleGet(req).catch(errorResponse),
+    POST: (req) => handlePost(req).catch(errorResponse),
+    PATCH: (req) => handlePatch(req).catch(errorResponse)
+  };
+}
+
+// src/server.ts
+var import_js3 = require("@onabl/js");
+function createOnablServerClient(config) {
+  return (0, import_js3.createOnablClient)(config);
+}
+function setAccessCookieOn(res, uuid, token) {
+  res.cookies.set(accessCookieName(uuid), token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: true,
+    maxAge: ACCESS_COOKIE_MAX_AGE_SECONDS,
+    path: "/"
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACCESS_COOKIE_MAX_AGE_SECONDS,
+  accessCookieName,
+  createOnablRouteHandlers,
+  createOnablServerClient,
+  setAccessCookieOn
+});

package/dist/index.mjs

@@ -0,0 +1,125 @@
+// src/route-handlers.ts
+import { OnablError } from "@onabl/js";
+import { NextResponse } from "next/server";
+
+// src/config.ts
+import { createOnablClient } from "@onabl/js";
+function buildClient(config) {
+  return createOnablClient(config);
+}
+
+// src/cookies.ts
+var COOKIE_PREFIX = "onabl_access_";
+function accessCookieName(uuid) {
+  return `${COOKIE_PREFIX}${uuid}`;
+}
+var ACCESS_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30;
+
+// src/route-handlers.ts
+function errorResponse(err) {
+  if (err instanceof OnablError) {
+    return NextResponse.json({ message: err.message }, { status: err.status ?? 400 });
+  }
+  return NextResponse.json({ message: "Unexpected error" }, { status: 500 });
+}
+function subpath(req, basePath) {
+  const { pathname } = req.nextUrl;
+  return pathname.startsWith(basePath) ? pathname.slice(basePath.length) : pathname;
+}
+function createOnablRouteHandlers(config) {
+  const basePath = config.basePath ?? "/api/onabl";
+  const client = buildClient(config);
+  async function handleGet(req) {
+    const path = subpath(req, basePath);
+    if (path === "/forms/validate-code") {
+      const code = req.nextUrl.searchParams.get("code") ?? "";
+      const result = await client.forms.validateDiscountCode(code);
+      return NextResponse.json(result);
+    }
+    return NextResponse.json({ message: "Not found" }, { status: 404 });
+  }
+  async function handlePost(req) {
+    const path = subpath(req, basePath);
+    if (path === "/submissions") {
+      const body = await req.json();
+      const created = await client.submissions.create(body.answers, {
+        consentGiven: body.consentGiven,
+        discountCode: body.discountCode
+      });
+      const res = NextResponse.json({ quoteId: created.quoteId, quoteUrl: created.quoteUrl });
+      res.cookies.set(accessCookieName(created.quoteId), created.token, {
+        httpOnly: true,
+        sameSite: "lax",
+        secure: true,
+        maxAge: ACCESS_COOKIE_MAX_AGE_SECONDS,
+        path: "/"
+      });
+      return res;
+    }
+    if (path === "/storage/presign") {
+      const body = await req.json();
+      const token = req.cookies.get(accessCookieName(body.resourceId))?.value;
+      if (!token) return NextResponse.json({ message: "No access token for this resource" }, { status: 401 });
+      const result = await client.storage.presignPop(body.resourceId, body.filename, body.contentType, body.fileSize, { token });
+      return NextResponse.json(result);
+    }
+    const acceptMatch = /^\/quotes\/([^/]+)\/accept$/.exec(path);
+    if (acceptMatch) {
+      const uuid = acceptMatch[1];
+      const token = req.cookies.get(accessCookieName(uuid))?.value;
+      if (!token) return NextResponse.json({ message: "No access token for this quote" }, { status: 401 });
+      await client.quotes.accept(uuid, { token }, await req.json().catch(() => ({})));
+      return NextResponse.json({ accepted: true });
+    }
+    const declineMatch = /^\/quotes\/([^/]+)\/decline$/.exec(path);
+    if (declineMatch) {
+      const uuid = declineMatch[1];
+      const token = req.cookies.get(accessCookieName(uuid))?.value;
+      if (!token) return NextResponse.json({ message: "No access token for this quote" }, { status: 401 });
+      const body = await req.json();
+      await client.quotes.decline(uuid, body.declineReason, body.declineNote, { token });
+      return NextResponse.json({ declined: true });
+    }
+    return NextResponse.json({ message: "Not found" }, { status: 404 });
+  }
+  async function handlePatch(req) {
+    const path = subpath(req, basePath);
+    const popMatch = /^\/invoices\/([^/]+)\/pop$/.exec(path);
+    if (popMatch) {
+      const uuid = popMatch[1];
+      const token = req.cookies.get(accessCookieName(uuid))?.value;
+      if (!token) return NextResponse.json({ message: "No access token for this invoice" }, { status: 401 });
+      const body = await req.json();
+      await client.invoices.savePopUrl(uuid, body.key, body.milestone, { token });
+      return NextResponse.json({ saved: true });
+    }
+    return NextResponse.json({ message: "Not found" }, { status: 404 });
+  }
+  return {
+    GET: (req) => handleGet(req).catch(errorResponse),
+    POST: (req) => handlePost(req).catch(errorResponse),
+    PATCH: (req) => handlePatch(req).catch(errorResponse)
+  };
+}
+
+// src/server.ts
+import { createOnablClient as createOnablClient2 } from "@onabl/js";
+function createOnablServerClient(config) {
+  return createOnablClient2(config);
+}
+function setAccessCookieOn(res, uuid, token) {
+  res.cookies.set(accessCookieName(uuid), token, {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: true,
+    maxAge: ACCESS_COOKIE_MAX_AGE_SECONDS,
+    path: "/"
+  });
+}
+export {
+  ACCESS_COOKIE_MAX_AGE_SECONDS,
+  accessCookieName,
+  createOnablRouteHandlers,
+  createOnablServerClient,
+  setAccessCookieOn
+};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@onabl/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Next.js integration for the Onabl SDK — server-action-free route-handler factory, cookie-aware client, RSC-safe boundary.",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://onabl.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "eslint": "latest",
+    "next": "latest",
+    "tsup": "^8.0.0",
+    "vitest": "^1.6.0",
+    "typescript": "^5.4.0",
+    "@onabl/typescript-config": "0.0.1",
+    "@onabl/eslint-config": "0.0.1"
+  },
+  "dependencies": {
+    "@onabl/js": "1.0.0",
+    "@onabl/react": "1.0.0"
+  },
+  "peerDependencies": {
+    "next": "^16",
+    "react": "^19"
+  },
+  "scripts": {
+    "build": "tsup && node ../js/check-bundle.mjs",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
 }