react-shopwave-connect 0.3.0 → 0.4.0

package/dist/next/index.d.ts

@@ -127,6 +127,46 @@ type EntityKind = "product" | "category" | "store" | "promotion" | "employee" |
  */
 declare const SHOPWAVE_ENTITIES: Readonly<Record<EntityKind, EntityDefinition>>;
 //#endregion
+//#region src/core/resources.d.ts
+/**
+ * Singleton resources (one per logged-in user) and the uploader.
+ *
+ * Like `SHOPWAVE_ENTITIES`, this table is shared by the client functions
+ * (`fetchMerchant`, `fetchUser`, `uploadImage`, …) and the server route
+ * handlers in `react-shopwave-connect/next`, so the two halves of the contract
+ * can't drift apart. These aren't in `SHOPWAVE_ENTITIES` because they aren't
+ * keyed collections: `GET /merchant` answers `{ merchant: {…} }`, not a map by id.
+ */
+interface ResourceDefinition {
+  /** App route: `/api/<route>`. */
+  route: string;
+  /** Key of the object in requests and responses (`{ merchant: {…} }`). */
+  key: string;
+  /** Shopwave API path. */
+  upstream: string;
+  /** False for read-only resources. */
+  writable: boolean;
+}
+type ResourceKind = "merchant" | "user";
+/**
+ * - 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).
+ */
+declare const SHOPWAVE_RESOURCES: Readonly<Record<ResourceKind, ResourceDefinition>>;
+/**
+ * What an upload is for. Sent to Shopwave as the `contentType` header of
+ * `PUT /uploader`. `merchant` is for the receipt and square logos (stored
+ * under `…/merchant/<id>/logo/`), `merchantFeature` for the featured image.
+ * The API spells two of its values `applicaionLogo` / `applicaionImages`; use
+ * the correctly spelt names here and the server maps them.
+ */
+type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
+/** `UploadKind` → the API's `contentType` value. */
+declare const UPLOAD_KINDS: Readonly<Record<UploadKind, string>>;
+//#endregion
 //#region src/server/api.d.ts
 /**
  * The OAuth token a caller sent with the request, without its scheme, or `null`.
@@ -180,6 +220,8 @@ interface ForwardInit {
   headers?: Record<string, string>;
   /** Sent as the form field `postBody=<JSON>`. */
   postBody?: unknown;
+  /** Sent as a multipart body (e.g. uploads). Ignored when `postBody` is set. */
+  formData?: FormData;
   /** Forward the caller's `extras` header as upstream headers. Defaults to `true`. */
   forwardExtras?: boolean;
 }
@@ -204,6 +246,35 @@ interface ItemHandlers {
   /** Delete the record at `[id]`. Shopwave answers 205 with an empty body. */
   DELETE: RouteHandler;
 }
+interface ResourceHandlers {
+  /** Read the resource (`GET {apiUrl}/<upstream>`). */
+  GET: RouteHandler;
+  /**
+   * Update it: body `{ <key>: { id, … } }` or the bare object. The `id` is
+   * required (without one Shopwave would create a new record). 405 for
+   * read-only resources.
+   */
+  PUT: RouteHandler;
+  /** Same as PUT. */
+  POST: RouteHandler;
+}
+interface UploadOptions {
+  /** Largest accepted file, in bytes. Defaults to 10 MB. */
+  maxBytes?: number;
+  /**
+   * Accepted MIME types. An entry ending in `/` is a prefix (`"image/"`).
+   * Defaults to `["image/"]`.
+   */
+  accept?: string[];
+}
+interface UploadHandlers {
+  /**
+   * Multipart `file` + `kind` (see `UploadKind`) → `PUT {apiUrl}/uploader`.
+   * Answers with Shopwave's reply (201 `{ fileName, path, api }`); 400 for a
+   * missing file or unknown kind, 413 when too large, 415 for other types.
+   */
+  POST: 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>;
@@ -213,10 +284,14 @@ interface ShopwaveApiHandlers {
   item(kind: EntityKind, options?: {
     param?: string;
   }): ItemHandlers;
-  /** GET-only proxy for a Shopwave path (e.g. `"report"`, `"user"`, `"merchant"`). */
+  /** GET-only proxy for a Shopwave path (e.g. `"report"`). */
   passthrough(path: string): {
     GET: RouteHandler;
   };
+  /** Handlers for a singleton resource: `app/api/merchant/route.ts`, `app/api/user/route.ts`. */
+  resource(kind: ResourceKind): ResourceHandlers;
+  /** Handler for `app/api/upload/route.ts`. */
+  upload(options?: UploadOptions): UploadHandlers;
   /** The entity table in use (defaults merged with `config.entities`). */
   entity(kind: EntityKind): EntityDefinition;
 }
@@ -415,9 +490,14 @@ interface ShopwaveNextApiConfig extends Omit<ShopwaveApiConfig, "getAuthorizatio
  * 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();
  * ```
  */
 declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-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 };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.ts.map

package/dist/next/index.js

@@ -319,6 +319,50 @@ const SHOPWAVE_ENTITIES = Object.freeze({
 	}
 });
 
+//#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
 /**
@@ -517,13 +561,14 @@ function createShopwaveApiHandlers(config) {
 			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 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) headers.set("Content-Type", "application/x-www-form-urlencoded;charset=UTF-8");
+			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,
@@ -586,6 +631,66 @@ function createShopwaveApiHandlers(config) {
 			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");
 	}
@@ -645,6 +750,18 @@ function createShopwaveApiHandlers(config) {
 		},
 		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) };
 		}
 	};
 }
@@ -971,6 +1088,11 @@ function createShopwaveAuth(config) {
 * 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) {
@@ -983,5 +1105,5 @@ function createShopwaveApi(config) {
 }
 
 //#endregion
-export { SHOPWAVE_ENTITIES, ShopwaveAuthError, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
+export { SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, ShopwaveAuthError, UPLOAD_KINDS, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.js.map