react-shopwave-connect 0.2.0 → 0.4.0

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,524 @@ 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/core/resources.ts
+/**
+* - merchant: `GET /merchant`; `POST /merchant` with `{ merchant: { id, … } }`
+*   updates it (without an `id` the API would create a second merchant, so the
+*   route requires one).
+* - user: `GET /user` (read-only here; the API's `POST /user` invites users and
+*   needs the admin scope).
+*/
+const SHOPWAVE_RESOURCES = Object.freeze({
+	merchant: {
+		route: "merchant",
+		key: "merchant",
+		upstream: "merchant",
+		writable: true
+	},
+	user: {
+		route: "user",
+		key: "user",
+		upstream: "user",
+		writable: false
+	}
+});
+/** `UploadKind` → the API's `contentType` value. */
+const UPLOAD_KINDS = Object.freeze({
+	merchant: "merchant",
+	merchantFeature: "merchantFeature",
+	product: "product",
+	user: "user",
+	applicationLogo: "applicaionLogo",
+	applicationImages: "applicaionImages"
+});
+/** How uploads are addressed (app route and Shopwave uploader). */
+const SHOPWAVE_UPLOAD = Object.freeze({
+	route: "upload",
+	upstream: "uploader",
+	kindHeader: "contentType",
+	fileField: "file",
+	kindField: "kind"
+});
+function isUploadKind(value) {
+	return typeof value === "string" && Object.prototype.hasOwnProperty.call(UPLOAD_KINDS, value);
+}
+
+//#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 ? new URLSearchParams({ postBody: JSON.stringify(init.postBody) }) : init.formData;
+		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 instanceof URLSearchParams) headers.set("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
+			else if (body) headers.delete("Content-Type");
+			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 resourceDef(kind) {
+		const def = SHOPWAVE_RESOURCES[kind];
+		if (!def) throw new Error(`Unknown Shopwave resource "${kind}"`);
+		return def;
+	}
+	async function writeResource(request, def) {
+		if (!def.writable) return jsonError(405, "method_not_allowed", `The Shopwave API doesn't support writes for ${def.key}`);
+		let record;
+		try {
+			const body = await readJsonBody(request);
+			if (!isPlainObject(body)) throw new RequestBodyError("Request body must be a JSON object");
+			const inner = body[def.key];
+			if (inner !== void 0 && !isPlainObject(inner)) throw new RequestBodyError(`"${def.key}" must be an object`);
+			record = { ...inner ?? body };
+			const id = record.id;
+			if (id == null || id === "" || !ID_PATTERN.test(String(id))) throw new RequestBodyError(`Missing or invalid ${def.key} id`);
+			record.id = /^\d+$/.test(String(id)) ? Number(id) : id;
+		} catch (error) {
+			if (error instanceof RequestBodyError) return jsonError(400, "invalid_body", error.message);
+			throw error;
+		}
+		return forward(request, {
+			method: "POST",
+			path: def.upstream,
+			postBody: { [def.key]: record }
+		});
+	}
+	function acceptsType(type, accept) {
+		const t = type.toLowerCase().split(";")[0].trim();
+		return accept.some((a) => {
+			const rule = a.toLowerCase();
+			return rule.endsWith("/") ? t.startsWith(rule) : t === rule;
+		});
+	}
+	async function uploadFile(request, options) {
+		const maxBytes = options.maxBytes ?? 10 * 1024 * 1024;
+		const accept = options.accept ?? ["image/"];
+		if (Number(request.headers.get("content-length") ?? 0) > maxBytes + 64 * 1024) return jsonError(413, "too_large", `The file is larger than ${maxBytes} bytes`);
+		let form;
+		try {
+			form = await request.formData();
+		} catch {
+			return jsonError(400, "invalid_body", "Expected a multipart/form-data body");
+		}
+		const file = form.get(SHOPWAVE_UPLOAD.fileField);
+		if (!file || typeof file === "string" || file.size === 0) return jsonError(400, "invalid_body", `Missing "${SHOPWAVE_UPLOAD.fileField}"`);
+		const kind = form.get(SHOPWAVE_UPLOAD.kindField);
+		if (!isUploadKind(kind)) return jsonError(400, "invalid_body", `"${SHOPWAVE_UPLOAD.kindField}" must be one of ${Object.keys(UPLOAD_KINDS).join(", ")}`);
+		if (file.size > maxBytes) return jsonError(413, "too_large", `The file is larger than ${maxBytes} bytes`);
+		if (!acceptsType(file.type || "", accept)) return jsonError(415, "unsupported_type", `Files of type "${file.type || "unknown"}" aren't accepted`);
+		const upstreamForm = new FormData();
+		upstreamForm.append(SHOPWAVE_UPLOAD.fileField, file, file.name || "upload");
+		return forward(request, {
+			method: "PUT",
+			path: SHOPWAVE_UPLOAD.upstream,
+			headers: { [SHOPWAVE_UPLOAD.kindHeader]: UPLOAD_KINDS[kind] },
+			formData: upstreamForm,
+			forwardExtras: false
+		});
+	}
+	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 }) };
+		},
+		resource(kind) {
+			const def = resourceDef(kind);
+			const save = (request) => writeResource(request, def);
+			return {
+				GET: (request) => forward(request, { path: def.upstream }),
+				PUT: save,
+				POST: save
+			};
+		},
+		upload(options = {}) {
+			return { POST: (request) => uploadFile(request, options) };
+		}
+	};
+}
+
 //#endregion
 //#region src/next/index.ts
 function normalizePath(p) {
@@ -525,8 +1044,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 +1071,39 @@ 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");
+* // app/api/merchant/route.ts, app/api/user/route.ts
+* export const { GET, PUT } = shopwave.resource("merchant");
+* export const { GET } = shopwave.resource("user");
+* // app/api/upload/route.ts
+* export const { POST } = shopwave.upload();
+* ```
+*/
+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, SHOPWAVE_RESOURCES, ShopwaveAuthError, UPLOAD_KINDS, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.js.map