react-shopwave-connect 0.2.0 → 0.3.0

package/dist/next/index.d.ts

@@ -84,6 +84,143 @@ interface ShopwaveOAuthClient {
   refreshToken(token: ShopwaveToken | string): Promise<ShopwaveToken>;
 }
 //#endregion
+//#region src/core/entities.d.ts
+/**
+ * How each Shopwave entity is addressed, shared by the client functions below
+ * and the server route handlers in `react-shopwave-connect/next`, so the two
+ * halves of the contract can't drift apart.
+ */
+interface EntityDefinition {
+  /** App route segment: `/api/<route>` and `/api/<route>/<id>`. */
+  route: string;
+  /** Key of the entity map in requests and responses (`{ products: { … } }`). */
+  collection: string;
+  /** Shopwave API path (`GET/POST/DELETE {apiUrl}/<upstream>`). */
+  upstream: string;
+  /** Header that filters reads by id (`productIds: 1,2`). */
+  idsHeader: string;
+  /** Header that names the record to delete (`productId: 1`). */
+  idHeader: string;
+  /** False for read-only entities (the API has no POST for them). */
+  writable: boolean;
+  /**
+   * How a delete is done upstream:
+   * - `"delete"`: `DELETE {apiUrl}/<upstream>` with the `idHeader` (205, empty body)
+   * - `"retire"`: the API has no DELETE; the record is retired by POSTing
+   *   `{ id, [retireField]: <now> }` (employees: `exitDate`, promotions: `endDate`)
+   * - `"none"`: can't be deleted
+   */
+  deleteMode: "delete" | "retire" | "none";
+  /** Date field set to "now" when `deleteMode` is `"retire"`. */
+  retireField?: string;
+}
+type EntityKind = "product" | "category" | "store" | "promotion" | "employee" | "consumer";
+/**
+ * Addressing per entity, following the Shopwave API reference
+ * (https://developer.merchantstack.com/api-reference.html) and checked against
+ * the live API where noted:
+ * - category/product/store: GET filtered by `<x>Ids`, POST upsert, DELETE with `<x>Id` → 205.
+ * - promotion: no DELETE; "deleting" a promotion ends it by setting `endDate` to now.
+ * - employee: POST updates `roleId`, `joinedDate`, `exitDate` (names can't be
+ *   changed); no DELETE (live API: "Cannot DELETE /employee") → retired via `exitDate`.
+ * - consumer: read-only (`GET` with `ids`, comma-separated); live POST → 404.
+ */
+declare const SHOPWAVE_ENTITIES: Readonly<Record<EntityKind, EntityDefinition>>;
+//#endregion
+//#region src/server/api.d.ts
+/**
+ * The OAuth token a caller sent with the request, without its scheme, or `null`.
+ *
+ * Reads, in order: `Authorization: OAuth|Bearer <token>` (what the SDK sends
+ * from 0.3), the `token` header (SDK ≤ 0.2 writes), and `extras.token`
+ * (SDK ≤ 0.2 reads).
+ */
+declare function readRequestToken(request: Request): string | null;
+interface ShopwaveApiConfig {
+  /** Shopwave API base URL, e.g. `process.env.SHOPWAVE_API_SERVER_URL`. */
+  apiUrl: string;
+  /**
+   * `Authorization` header value for the logged-in user (`"OAuth <token>"`),
+   * or `null` when logged out. Called again with `forceRefresh: true` when the
+   * API reports the token expired.
+   */
+  getAuthorization?: (options?: {
+    forceRefresh?: boolean;
+  }) => Promise<string | null>;
+  /**
+   * Accept a token sent by the caller (`Authorization: OAuth <token>`, or the
+   * legacy `token` header / `extras.token`) instead of the session. The token
+   * is only forwarded to the Shopwave API, which validates it. Defaults to `true`
+   * (SDK integration tests, scripts and server-to-server calls rely on it).
+   */
+  allowRequestToken?: boolean;
+  /** `x-accept-version` sent upstream. Defaults to `"2.0"`. */
+  apiVersion?: string;
+  /** Custom fetch for the upstream call. */
+  fetch?: typeof fetch;
+  /** Override how an entity is addressed (e.g. a different id header). */
+  entities?: Partial<Record<EntityKind, Partial<EntityDefinition>>>;
+  /** Extra `extras` keys to drop, on top of {@link BLOCKED_EXTRAS}. */
+  blockedExtras?: string[];
+  /**
+   * Called when the upstream call throws (network error). Defaults to a
+   * `console.error` with the method and path only — never headers or tokens.
+   */
+  onError?: (error: unknown, context: {
+    method: string;
+    path: string;
+  }) => void;
+}
+interface ForwardInit {
+  /** HTTP method sent upstream. Defaults to `GET`. */
+  method?: string;
+  /** Shopwave API path, e.g. `"product"`. */
+  path: string;
+  /** Extra upstream headers; they win over `extras`. */
+  headers?: Record<string, string>;
+  /** Sent as the form field `postBody=<JSON>`. */
+  postBody?: unknown;
+  /** Forward the caller's `extras` header as upstream headers. Defaults to `true`. */
+  forwardExtras?: boolean;
+}
+/** Second argument Next.js (and similar) pass to dynamic route handlers. */
+interface RouteContext {
+  params?: Promise<Record<string, string | string[] | undefined>> | Record<string, string | string[] | undefined>;
+}
+type RouteHandler = (request: Request, context?: RouteContext) => Promise<Response>;
+interface CollectionHandlers {
+  /** List/filter via `extras` (e.g. `productIds`, `deleted`). */
+  GET: RouteHandler;
+  /** Create or update (Shopwave upserts: an `id` means update). */
+  POST: RouteHandler;
+  /** Same as POST (kept for older clients). */
+  PUT: RouteHandler;
+}
+interface ItemHandlers {
+  /** Read one record by the `[id]` route param. */
+  GET: RouteHandler;
+  /** Update the record at `[id]` (the id in the URL wins). */
+  PUT: RouteHandler;
+  /** Delete the record at `[id]`. Shopwave answers 205 with an empty body. */
+  DELETE: RouteHandler;
+}
+interface ShopwaveApiHandlers {
+  /** Calls the Shopwave API for this request (token, extras, refresh-retry) and returns its answer. */
+  forward(request: Request, init: ForwardInit): Promise<Response>;
+  /** Handlers for `app/api/<route>/route.ts`. */
+  collection(kind: EntityKind): CollectionHandlers;
+  /** Handlers for `app/api/<route>/[id]/route.ts`. */
+  item(kind: EntityKind, options?: {
+    param?: string;
+  }): ItemHandlers;
+  /** GET-only proxy for a Shopwave path (e.g. `"report"`, `"user"`, `"merchant"`). */
+  passthrough(path: string): {
+    GET: RouteHandler;
+  };
+  /** The entity table in use (defaults merged with `config.entities`). */
+  entity(kind: EntityKind): EntityDefinition;
+}
+//#endregion
 //#region src/core/session.d.ts
 /**
  * Login status returned by the app's `/api/session` route. It deliberately
@@ -192,6 +329,13 @@ interface ProtectOptions {
   publicPaths?: string[];
   /** Paths that get a 401 JSON response instead of a login redirect. Defaults to `["/api"]`. */
   apiPaths?: string[];
+  /**
+   * Let API requests that carry their own token (`Authorization: OAuth <token>`,
+   * or the legacy `token` header / `extras.token`) through without a session
+   * cookie. The route handlers from {@link createShopwaveApi} forward that token
+   * to the Shopwave API, which validates it. Defaults to `false`.
+   */
+  allowRequestToken?: boolean;
 }
 interface ShopwaveAuth {
   /** The underlying framework-agnostic OAuth client. */
@@ -250,6 +394,30 @@ interface ShopwaveAuth {
  * a missing env var doesn't fail `next build`.
  */
 declare function createShopwaveAuth(config: ShopwaveAuthConfig): ShopwaveAuth;
+interface ShopwaveNextApiConfig extends Omit<ShopwaveApiConfig, "getAuthorization"> {
+  /** The app's auth instance: supplies (and refreshes) the logged-in user's token. */
+  auth: Pick<ShopwaveAuth, "getAuthorizationHeader">;
+}
+/**
+ * Ready-made Next.js route handlers for the SDK's `/api/*` contract, using the
+ * session from `createShopwaveAuth`. Create once (e.g. `lib/shopwave.ts`):
+ *
+ * ```ts
+ * export const shopwave = createShopwaveApi({ auth, apiUrl: process.env.SHOPWAVE_API_SERVER_URL! });
+ * ```
+ *
+ * then each route file is one line:
+ *
+ * ```ts
+ * // app/api/products/route.ts
+ * export const { GET, POST, PUT } = shopwave.collection("product");
+ * // app/api/products/[id]/route.ts
+ * export const { GET, PUT, DELETE } = shopwave.item("product");
+ * // app/api/report/route.ts
+ * export const { GET } = shopwave.passthrough("report");
+ * ```
+ */
+declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-export { AuthContext, ProtectOptions, type SessionStatus, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, authorizationHeader, createShopwaveAuth, isExpiredTokenResponse };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, ProtectOptions, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.ts.map

package/dist/next/index.js

@@ -90,7 +90,8 @@ function authorizationHeader(token) {
 */
 function isExpiredTokenResponse(status, body) {
 	if (status === 401) return true;
-	const errors = body?.api?.message?.errors;
+	const message = body?.api?.message;
+	const errors = message?.errors ?? message?.error;
 	if (!errors || typeof errors !== "object") return false;
 	return Object.entries(errors).some(([key, value]) => key === String(SHOPWAVE_TOKEN_EXPIRED_ERROR_ID) || Number(value?.id) === SHOPWAVE_TOKEN_EXPIRED_ERROR_ID);
 }
@@ -247,6 +248,407 @@ function safeEqual(a, b) {
 	return diff === 0;
 }
 
+//#endregion
+//#region src/core/entities.ts
+/**
+* Addressing per entity, following the Shopwave API reference
+* (https://developer.merchantstack.com/api-reference.html) and checked against
+* the live API where noted:
+* - category/product/store: GET filtered by `<x>Ids`, POST upsert, DELETE with `<x>Id` → 205.
+* - promotion: no DELETE; "deleting" a promotion ends it by setting `endDate` to now.
+* - employee: POST updates `roleId`, `joinedDate`, `exitDate` (names can't be
+*   changed); no DELETE (live API: "Cannot DELETE /employee") → retired via `exitDate`.
+* - consumer: read-only (`GET` with `ids`, comma-separated); live POST → 404.
+*/
+const SHOPWAVE_ENTITIES = Object.freeze({
+	product: {
+		route: "products",
+		collection: "products",
+		upstream: "product",
+		idsHeader: "productIds",
+		idHeader: "productId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	category: {
+		route: "categories",
+		collection: "categories",
+		upstream: "category",
+		idsHeader: "categoryIds",
+		idHeader: "categoryId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	store: {
+		route: "stores",
+		collection: "stores",
+		upstream: "store",
+		idsHeader: "storeIds",
+		idHeader: "storeId",
+		writable: true,
+		deleteMode: "delete"
+	},
+	promotion: {
+		route: "promotions",
+		collection: "promotions",
+		upstream: "promotion",
+		idsHeader: "promotionIds",
+		idHeader: "promotionId",
+		writable: true,
+		deleteMode: "retire",
+		retireField: "endDate"
+	},
+	employee: {
+		route: "employees",
+		collection: "employees",
+		upstream: "employee",
+		idsHeader: "employeeIds",
+		idHeader: "employeeId",
+		writable: true,
+		deleteMode: "retire",
+		retireField: "exitDate"
+	},
+	consumer: {
+		route: "consumer",
+		collection: "consumers",
+		upstream: "consumer",
+		idsHeader: "ids",
+		idHeader: "consumerId",
+		writable: false,
+		deleteMode: "none"
+	}
+});
+
+//#endregion
+//#region src/server/api.ts
+/**
+* The OAuth token a caller sent with the request, without its scheme, or `null`.
+*
+* Reads, in order: `Authorization: OAuth|Bearer <token>` (what the SDK sends
+* from 0.3), the `token` header (SDK ≤ 0.2 writes), and `extras.token`
+* (SDK ≤ 0.2 reads).
+*/
+function readRequestToken(request) {
+	const authz = request.headers.get("authorization");
+	if (authz) {
+		const match = /^(?:oauth|bearer)\s+(\S+)\s*$/i.exec(authz);
+		if (match) return match[1];
+	}
+	const legacyHeader = request.headers.get("token");
+	if (legacyHeader && legacyHeader.trim()) return legacyHeader.trim();
+	const extras = request.headers.get("extras");
+	if (extras) try {
+		const token = JSON.parse(extras)?.token;
+		if (typeof token === "string" && token.trim()) return token.trim();
+	} catch {}
+	return null;
+}
+/**
+* `extras` keys that are never forwarded upstream (case-insensitive).
+* `Content-Type` is allowed (SDK clients have always sent `application/json`
+* on reads) but is replaced by the form content type on writes.
+*/
+const BLOCKED_EXTRAS = new Set([
+	"authorization",
+	"token",
+	"cookie",
+	"host",
+	"x-accept-version",
+	"content-length",
+	"connection",
+	"transfer-encoding",
+	"te",
+	"upgrade",
+	"expect",
+	"keep-alive",
+	"proxy-authorization",
+	"forwarded"
+]);
+const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+function headerValue(value) {
+	if (value == null) return null;
+	let text;
+	if (Array.isArray(value)) text = value.map((v) => v != null && typeof v === "object" ? JSON.stringify(v) : String(v)).join(",");
+	else if (typeof value === "object") text = JSON.stringify(value);
+	else text = String(value);
+	return /[\r\n\0]/.test(text) ? null : text;
+}
+/**
+* Parses the `extras` request header into upstream headers.
+* Returns `null` when the header isn't a JSON object.
+*/
+function parseExtras(raw, blocked = BLOCKED_EXTRAS) {
+	if (!raw) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+	const headers = {};
+	for (const [key, value] of Object.entries(parsed)) {
+		const lower = key.toLowerCase();
+		if (!HEADER_NAME.test(key) || blocked.has(lower) || lower.startsWith("x-forwarded-") || lower.startsWith("proxy-")) continue;
+		const text = headerValue(value);
+		if (text !== null) headers[key] = text;
+	}
+	return headers;
+}
+var RequestBodyError = class extends Error {};
+function isPlainObject(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Normalises a write request body into the Shopwave envelope
+* `{ <collection>: { <ref>: entity, … } }`.
+*
+* Accepts:
+*  - the SDK ≥ 0.3 shape `{ <collection>: { "0": {...}, "1": {...} } }` (refs kept),
+*  - the older AdminUI shapes `{ <collection>: { new: {...} } }` / `{ updated: {...} }`,
+*  - a bare entity object `{ title: … }`.
+*
+* With `forcedId` (item routes) exactly one entity is allowed and its `id` is
+* set from the URL.
+*/
+function normalizeWriteBody(def, body, forcedId) {
+	if (!isPlainObject(body)) throw new RequestBodyError("Request body must be a JSON object");
+	let refs;
+	const wrapped = body[def.collection];
+	if (wrapped !== void 0) {
+		if (!isPlainObject(wrapped)) throw new RequestBodyError(`"${def.collection}" must be an object keyed by ref`);
+		const keys = Object.keys(wrapped);
+		const entries = keys.length === 1 && (keys[0] === "new" || keys[0] === "updated") ? [["0", wrapped[keys[0]]]] : Object.entries(wrapped);
+		refs = {};
+		for (const [ref, entity] of entries) {
+			if (!isPlainObject(entity)) throw new RequestBodyError(`"${def.collection}.${ref}" must be an object`);
+			refs[ref] = { ...entity };
+		}
+	} else refs = { "0": { ...body } };
+	const count = Object.keys(refs).length;
+	if (count === 0) throw new RequestBodyError(`No ${def.collection} to save`);
+	if (forcedId !== void 0) {
+		if (count !== 1) throw new RequestBodyError("Only one entity can be saved at an id route");
+		const only = refs[Object.keys(refs)[0]];
+		only.id = /^\d+$/.test(forcedId) ? Number(forcedId) : forcedId;
+	}
+	return { [def.collection]: refs };
+}
+const NO_STORE = { "Cache-Control": "no-store" };
+function jsonError(status, error, message) {
+	return new Response(JSON.stringify({
+		error,
+		message
+	}), {
+		status,
+		headers: {
+			"Content-Type": "application/json",
+			...NO_STORE
+		}
+	});
+}
+/** `YYYY-MM-DD HH:mm:ss` in UTC, the datetime format Shopwave writes use (e.g. promotions). */
+function shopwaveDateTime(date = /* @__PURE__ */ new Date()) {
+	return date.toISOString().slice(0, 19).replace("T", " ");
+}
+const NULL_BODY_STATUS = new Set([
+	101,
+	103,
+	204,
+	205,
+	304
+]);
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+async function readUpstream(response) {
+	const text = await response.text();
+	if (!text) return {
+		text,
+		json: null
+	};
+	try {
+		return {
+			text,
+			json: JSON.parse(text)
+		};
+	} catch {
+		return {
+			text,
+			json: null
+		};
+	}
+}
+async function routeParam(context, name) {
+	const value = (await context?.params)?.[name];
+	const id = Array.isArray(value) ? value[0] : value;
+	return typeof id === "string" && ID_PATTERN.test(id) ? id : null;
+}
+function createShopwaveApiHandlers(config) {
+	const allowRequestToken = config.allowRequestToken ?? true;
+	const apiVersion = config.apiVersion ?? "2.0";
+	const blocked = new Set([...BLOCKED_EXTRAS, ...(config.blockedExtras ?? []).map((k) => k.toLowerCase())]);
+	const onError = config.onError ?? ((error, ctx) => console.error(`[react-shopwave-connect] Shopwave API ${ctx.method} /${ctx.path} failed:`, error?.message ?? error));
+	function apiBase() {
+		const url = config.apiUrl;
+		if (!url) throw new Error("Shopwave API: apiUrl is not set (e.g. SHOPWAVE_API_SERVER_URL).");
+		return url.replace(/\/+$/, "");
+	}
+	function entity(kind) {
+		const base = SHOPWAVE_ENTITIES[kind];
+		if (!base) throw new Error(`Unknown Shopwave entity "${kind}"`);
+		return {
+			...base,
+			...config.entities?.[kind] ?? {}
+		};
+	}
+	async function forward(request, init) {
+		const method = (init.method ?? "GET").toUpperCase();
+		const path = init.path.replace(/^\/+/, "");
+		const extras = init.forwardExtras === false ? {} : parseExtras(request.headers.get("extras"), blocked);
+		if (!extras) return jsonError(400, "invalid_extras", "The extras header must be a JSON object");
+		const requestToken = allowRequestToken ? readRequestToken(request) : null;
+		let authorization;
+		try {
+			authorization = requestToken ? `OAuth ${requestToken}` : await config.getAuthorization?.() ?? null;
+		} catch (error) {
+			onError(error, {
+				method,
+				path: "oauth/token"
+			});
+			return jsonError(502, "auth_unavailable", "Could not refresh the Shopwave session");
+		}
+		if (!authorization) return jsonError(401, "unauthorized", "Not logged in");
+		const body = init.postBody === void 0 ? void 0 : new URLSearchParams({ postBody: JSON.stringify(init.postBody) });
+		const call = (authz) => {
+			const headers = new Headers(extras);
+			for (const [k, v] of Object.entries(init.headers ?? {})) headers.set(k, v);
+			headers.set("Authorization", authz);
+			headers.set("x-accept-version", apiVersion);
+			if (body) headers.set("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
+			return (config.fetch ?? fetch)(`${apiBase()}/${path}`, {
+				method,
+				headers,
+				body,
+				cache: "no-store"
+			});
+		};
+		try {
+			let response = await call(authorization);
+			let upstream = await readUpstream(response);
+			if (!requestToken && config.getAuthorization && isExpiredTokenResponse(response.status, upstream.json)) {
+				const fresh = await config.getAuthorization({ forceRefresh: true });
+				if (!fresh) return jsonError(401, "unauthorized", "The Shopwave session has expired");
+				response = await call(fresh);
+				upstream = await readUpstream(response);
+			}
+			if (NULL_BODY_STATUS.has(response.status) || !upstream.text) return new Response(null, {
+				status: response.status,
+				headers: NO_STORE
+			});
+			return new Response(upstream.text, {
+				status: response.status,
+				headers: {
+					"Content-Type": upstream.json !== null ? "application/json" : response.headers.get("content-type") ?? "text/plain",
+					...NO_STORE
+				}
+			});
+		} catch (error) {
+			onError(error, {
+				method,
+				path
+			});
+			return jsonError(502, "upstream_unavailable", "The Shopwave API could not be reached");
+		}
+	}
+	async function readJsonBody(request) {
+		const text = await request.text();
+		if (!text) throw new RequestBodyError("Request body is empty");
+		try {
+			return JSON.parse(text);
+		} catch {
+			throw new RequestBodyError("Request body is not valid JSON");
+		}
+	}
+	function notSupported(def, what) {
+		return jsonError(405, "method_not_allowed", `The Shopwave API doesn't support ${what} for ${def.collection}`);
+	}
+	async function write(request, def, forcedId) {
+		if (!def.writable) return notSupported(def, "writes");
+		let postBody;
+		try {
+			postBody = normalizeWriteBody(def, await readJsonBody(request), forcedId);
+		} catch (error) {
+			if (error instanceof RequestBodyError) return jsonError(400, "invalid_body", error.message);
+			throw error;
+		}
+		return forward(request, {
+			method: "POST",
+			path: def.upstream,
+			postBody
+		});
+	}
+	function badId() {
+		return jsonError(400, "invalid_id", "Missing or invalid id");
+	}
+	return {
+		forward,
+		entity,
+		collection(kind) {
+			const def = entity(kind);
+			const save = (request) => write(request, def);
+			return {
+				GET: (request) => forward(request, { path: def.upstream }),
+				POST: save,
+				PUT: save
+			};
+		},
+		item(kind, options = {}) {
+			const def = entity(kind);
+			const param = options.param ?? "id";
+			return {
+				async GET(request, context) {
+					const id = await routeParam(context, param);
+					if (!id) return badId();
+					return forward(request, {
+						path: def.upstream,
+						headers: { [def.idsHeader]: id }
+					});
+				},
+				async PUT(request, context) {
+					const id = await routeParam(context, param);
+					if (!id) return badId();
+					return write(request, def, id);
+				},
+				async DELETE(request, context) {
+					const id = await routeParam(context, param);
+					if (!id) return badId();
+					if (def.deleteMode === "none") return notSupported(def, "deletes");
+					if (def.deleteMode === "retire") {
+						const field = def.retireField ?? "exitDate";
+						return forward(request, {
+							method: "POST",
+							path: def.upstream,
+							postBody: { [def.collection]: { 0: {
+								id: /^\d+$/.test(id) ? Number(id) : id,
+								[field]: shopwaveDateTime()
+							} } },
+							forwardExtras: false
+						});
+					}
+					return forward(request, {
+						method: "DELETE",
+						path: def.upstream,
+						headers: { [def.idHeader]: id },
+						forwardExtras: false
+					});
+				}
+			};
+		},
+		passthrough(path) {
+			return { GET: (request) => forward(request, { path }) };
+		}
+	};
+}
+
 //#endregion
 //#region src/next/index.ts
 function normalizePath(p) {
@@ -525,8 +927,10 @@ function createShopwaveAuth(config) {
 				sessionPath,
 				...options.publicPaths ?? []
 			])) return;
+			const isApi = pathMatches(pathname, options.apiPaths ?? ["/api"]);
+			if (isApi && options.allowRequestToken && readRequestToken(request)) return void 0;
 			if (await isAuthenticated(request)) return void 0;
-			if (pathMatches(pathname, options.apiPaths ?? ["/api"])) return NextResponse.json({ error: "unauthorized" }, {
+			if (isApi) return NextResponse.json({ error: "unauthorized" }, {
 				status: 401,
 				headers: noStore
 			});
@@ -550,7 +954,34 @@ function createShopwaveAuth(config) {
 		}
 	};
 }
+/**
+* Ready-made Next.js route handlers for the SDK's `/api/*` contract, using the
+* session from `createShopwaveAuth`. Create once (e.g. `lib/shopwave.ts`):
+*
+* ```ts
+* export const shopwave = createShopwaveApi({ auth, apiUrl: process.env.SHOPWAVE_API_SERVER_URL! });
+* ```
+*
+* then each route file is one line:
+*
+* ```ts
+* // app/api/products/route.ts
+* export const { GET, POST, PUT } = shopwave.collection("product");
+* // app/api/products/[id]/route.ts
+* export const { GET, PUT, DELETE } = shopwave.item("product");
+* // app/api/report/route.ts
+* export const { GET } = shopwave.passthrough("report");
+* ```
+*/
+function createShopwaveApi(config) {
+	if (typeof window !== "undefined") throw new Error("react-shopwave-connect/next is server-only. Import it from route handlers or server code.");
+	const { auth,...rest } = config;
+	return createShopwaveApiHandlers({
+		...rest,
+		getAuthorization: (options) => auth.getAuthorizationHeader(options)
+	});
+}
 
 //#endregion
-export { ShopwaveAuthError, authorizationHeader, createShopwaveAuth, isExpiredTokenResponse };
+export { SHOPWAVE_ENTITIES, ShopwaveAuthError, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.js.map