react-shopwave-connect 0.4.2 → 0.4.4

package/dist/next/index.d.cts

@@ -87,8 +87,9 @@ interface ShopwaveOAuthClient {
 //#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.
+ * and the server route handlers in `react-shopwave-connect/server` (wrapped with
+ * the session by `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>`. */
@@ -148,7 +149,7 @@ declare const SHOPWAVE_ENTITIES: Readonly<Record<EntityKind, EntityDefinition>>;
  *
  * 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
+ * handlers in `react-shopwave-connect/server`, 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.
  */
@@ -181,6 +182,50 @@ declare const SHOPWAVE_RESOURCES: Readonly<Record<ResourceKind, ResourceDefiniti
 type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
 /** `UploadKind` → the API's `contentType` value. */
 declare const UPLOAD_KINDS: Readonly<Record<UploadKind, string>>;
+/**
+ * The role an image plays, sent to Shopwave as the uploader's `prefix` header.
+ * The uploader names the file `<prefix>_<hash>.<ext>`, so the role travels with
+ * the file wherever a record stores it (a product's `images`). Live, merchant
+ * 5644, 4 Nov 2026: all four values answered 201.
+ * - `product`: a product gallery image;
+ * - `product_thumbnail`: the product's lead image, shown in lists;
+ * - `variant` / `variant_thumbnail`: a variant's own image and its lead image
+ *   (used by the Connect integrations).
+ *
+ * Values are the ones Connect's `uploadFileToShopwave` sends.
+ */
+type UploadPrefix = "product" | "product_thumbnail" | "variant" | "variant_thumbnail";
+/** Every `UploadPrefix`, longest first so a name check never takes `product` for `product_thumbnail`. */
+declare const UPLOAD_PREFIXES: ReadonlyArray<UploadPrefix>;
+/**
+ * Read-only lists that aren't records: the merchant's distinct tags.
+ *
+ * Like `SHOPWAVE_RESOURCES`, shared by the client functions
+ * (`fetchProductTags`, `fetchProductInstanceTags`) and the server route
+ * handlers (`shopwave.lookup(kind)`), so the two halves can't drift apart.
+ *
+ * - productTags: `GET /product/tags` → `{ tags: string[] }`, every distinct tag
+ *   on the merchant's products. No parameters. The API reference says
+ *   "internal SKU tags are excluded", but the live API includes system tags
+ *   written by imports and syncs (`PID-133`, `VID-137`, `#Hash:…`, `upc-…`;
+ *   test merchant 5644, 29 Oct 2026). Apps that offer the list as suggestions
+ *   filter those themselves. Tags of deleted products drop out of the list.
+ * - productInstanceTags: `GET /product/instance/tags` → `{ tags: string[] }`,
+ *   the same for price instances (channels such as "Eat In", "Takeout").
+ *
+ * The app route for instance tags is `products/instance-tags`, one segment
+ * under `products`, so it sits beside `products/[id]` without nesting deeper.
+ */
+interface LookupDefinition {
+  /** App route: `/api/<route>`. */
+  route: string;
+  /** Key of the list in the response (`{ tags: [...] }`). */
+  key: string;
+  /** Shopwave API path. */
+  upstream: string;
+}
+type LookupKind = "productTags" | "productInstanceTags";
+declare const SHOPWAVE_LOOKUPS: Readonly<Record<LookupKind, LookupDefinition>>;
 //#endregion
 //#region src/server/api.d.ts
 /**
@@ -284,9 +329,11 @@ interface UploadOptions {
 }
 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.
+   * Multipart `file` + `kind` (see `UploadKind`), and optionally `prefix`
+   * (see `UploadPrefix`) → `PUT {apiUrl}/uploader` with the `contentType` and
+   * `prefix` headers. Answers with Shopwave's reply (201 `{ fileName, path, api }`);
+   * 400 for a missing file or an unknown kind or prefix, 413 when too large,
+   * 415 for other types.
    */
   POST: RouteHandler;
 }
@@ -303,6 +350,14 @@ interface ShopwaveApiHandlers {
   passthrough(path: string): {
     GET: RouteHandler;
   };
+  /**
+   * Handler for a read-only list (see `SHOPWAVE_LOOKUPS`), e.g.
+   * `app/api/products/tags/route.ts`: `export const { GET } = shopwave.lookup("productTags")`.
+   * Takes no parameters, so the caller's `extras` aren't forwarded.
+   */
+  lookup(kind: LookupKind): {
+    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`. */
@@ -510,9 +565,12 @@ interface ShopwaveNextApiConfig extends Omit<ShopwaveApiConfig, "getAuthorizatio
  * export const { GET } = shopwave.resource("user");
  * // app/api/upload/route.ts
  * export const { POST } = shopwave.upload();
+ * // app/api/products/tags/route.ts, app/api/products/instance-tags/route.ts
+ * export const { GET } = shopwave.lookup("productTags");
+ * export const { GET } = shopwave.lookup("productInstanceTags");
  * ```
  */
 declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-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 };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, type LookupKind, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, UPLOAD_PREFIXES, type UploadHandlers, type UploadKind, type UploadOptions, type UploadPrefix, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.cts.map

package/dist/next/index.d.ts

@@ -87,8 +87,9 @@ interface ShopwaveOAuthClient {
 //#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.
+ * and the server route handlers in `react-shopwave-connect/server` (wrapped with
+ * the session by `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>`. */
@@ -148,7 +149,7 @@ declare const SHOPWAVE_ENTITIES: Readonly<Record<EntityKind, EntityDefinition>>;
  *
  * 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
+ * handlers in `react-shopwave-connect/server`, 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.
  */
@@ -181,6 +182,50 @@ declare const SHOPWAVE_RESOURCES: Readonly<Record<ResourceKind, ResourceDefiniti
 type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
 /** `UploadKind` → the API's `contentType` value. */
 declare const UPLOAD_KINDS: Readonly<Record<UploadKind, string>>;
+/**
+ * The role an image plays, sent to Shopwave as the uploader's `prefix` header.
+ * The uploader names the file `<prefix>_<hash>.<ext>`, so the role travels with
+ * the file wherever a record stores it (a product's `images`). Live, merchant
+ * 5644, 4 Nov 2026: all four values answered 201.
+ * - `product`: a product gallery image;
+ * - `product_thumbnail`: the product's lead image, shown in lists;
+ * - `variant` / `variant_thumbnail`: a variant's own image and its lead image
+ *   (used by the Connect integrations).
+ *
+ * Values are the ones Connect's `uploadFileToShopwave` sends.
+ */
+type UploadPrefix = "product" | "product_thumbnail" | "variant" | "variant_thumbnail";
+/** Every `UploadPrefix`, longest first so a name check never takes `product` for `product_thumbnail`. */
+declare const UPLOAD_PREFIXES: ReadonlyArray<UploadPrefix>;
+/**
+ * Read-only lists that aren't records: the merchant's distinct tags.
+ *
+ * Like `SHOPWAVE_RESOURCES`, shared by the client functions
+ * (`fetchProductTags`, `fetchProductInstanceTags`) and the server route
+ * handlers (`shopwave.lookup(kind)`), so the two halves can't drift apart.
+ *
+ * - productTags: `GET /product/tags` → `{ tags: string[] }`, every distinct tag
+ *   on the merchant's products. No parameters. The API reference says
+ *   "internal SKU tags are excluded", but the live API includes system tags
+ *   written by imports and syncs (`PID-133`, `VID-137`, `#Hash:…`, `upc-…`;
+ *   test merchant 5644, 29 Oct 2026). Apps that offer the list as suggestions
+ *   filter those themselves. Tags of deleted products drop out of the list.
+ * - productInstanceTags: `GET /product/instance/tags` → `{ tags: string[] }`,
+ *   the same for price instances (channels such as "Eat In", "Takeout").
+ *
+ * The app route for instance tags is `products/instance-tags`, one segment
+ * under `products`, so it sits beside `products/[id]` without nesting deeper.
+ */
+interface LookupDefinition {
+  /** App route: `/api/<route>`. */
+  route: string;
+  /** Key of the list in the response (`{ tags: [...] }`). */
+  key: string;
+  /** Shopwave API path. */
+  upstream: string;
+}
+type LookupKind = "productTags" | "productInstanceTags";
+declare const SHOPWAVE_LOOKUPS: Readonly<Record<LookupKind, LookupDefinition>>;
 //#endregion
 //#region src/server/api.d.ts
 /**
@@ -284,9 +329,11 @@ interface UploadOptions {
 }
 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.
+   * Multipart `file` + `kind` (see `UploadKind`), and optionally `prefix`
+   * (see `UploadPrefix`) → `PUT {apiUrl}/uploader` with the `contentType` and
+   * `prefix` headers. Answers with Shopwave's reply (201 `{ fileName, path, api }`);
+   * 400 for a missing file or an unknown kind or prefix, 413 when too large,
+   * 415 for other types.
    */
   POST: RouteHandler;
 }
@@ -303,6 +350,14 @@ interface ShopwaveApiHandlers {
   passthrough(path: string): {
     GET: RouteHandler;
   };
+  /**
+   * Handler for a read-only list (see `SHOPWAVE_LOOKUPS`), e.g.
+   * `app/api/products/tags/route.ts`: `export const { GET } = shopwave.lookup("productTags")`.
+   * Takes no parameters, so the caller's `extras` aren't forwarded.
+   */
+  lookup(kind: LookupKind): {
+    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`. */
@@ -510,9 +565,12 @@ interface ShopwaveNextApiConfig extends Omit<ShopwaveApiConfig, "getAuthorizatio
  * export const { GET } = shopwave.resource("user");
  * // app/api/upload/route.ts
  * export const { POST } = shopwave.upload();
+ * // app/api/products/tags/route.ts, app/api/products/instance-tags/route.ts
+ * export const { GET } = shopwave.lookup("productTags");
+ * export const { GET } = shopwave.lookup("productInstanceTags");
  * ```
  */
 declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-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 };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, type LookupKind, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, UPLOAD_PREFIXES, type UploadHandlers, type UploadKind, type UploadOptions, type UploadPrefix, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.ts.map

package/dist/next/index.js

@@ -248,6 +248,74 @@ function safeEqual(a, b) {
 	return diff === 0;
 }
 
+//#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"
+});
+/** Every `UploadPrefix`, longest first so a name check never takes `product` for `product_thumbnail`. */
+const UPLOAD_PREFIXES = Object.freeze([
+	"product_thumbnail",
+	"variant_thumbnail",
+	"product",
+	"variant"
+]);
+/** How uploads are addressed (app route and Shopwave uploader). */
+const SHOPWAVE_UPLOAD = Object.freeze({
+	route: "upload",
+	upstream: "uploader",
+	kindHeader: "contentType",
+	prefixHeader: "prefix",
+	fileField: "file",
+	kindField: "kind",
+	prefixField: "prefix"
+});
+function isUploadKind(value) {
+	return typeof value === "string" && Object.prototype.hasOwnProperty.call(UPLOAD_KINDS, value);
+}
+function isUploadPrefix(value) {
+	return typeof value === "string" && UPLOAD_PREFIXES.includes(value);
+}
+const SHOPWAVE_LOOKUPS = Object.freeze({
+	productTags: {
+		route: "products/tags",
+		key: "tags",
+		upstream: "product/tags"
+	},
+	productInstanceTags: {
+		route: "products/instance-tags",
+		key: "tags",
+		upstream: "product/instance/tags"
+	}
+});
+
 //#endregion
 //#region src/core/entities.ts
 /**
@@ -324,50 +392,6 @@ 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
 /**
@@ -696,6 +720,8 @@ function createShopwaveApiHandlers(config) {
 		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(", ")}`);
+		const prefix = form.get(SHOPWAVE_UPLOAD.prefixField);
+		if (prefix !== null && !isUploadPrefix(prefix)) return jsonError(400, "invalid_body", `"${SHOPWAVE_UPLOAD.prefixField}" must be one of ${UPLOAD_PREFIXES.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();
@@ -703,7 +729,10 @@ function createShopwaveApiHandlers(config) {
 		return forward(request, {
 			method: "PUT",
 			path: SHOPWAVE_UPLOAD.upstream,
-			headers: { [SHOPWAVE_UPLOAD.kindHeader]: UPLOAD_KINDS[kind] },
+			headers: {
+				[SHOPWAVE_UPLOAD.kindHeader]: UPLOAD_KINDS[kind],
+				...prefix !== null ? { [SHOPWAVE_UPLOAD.prefixHeader]: prefix } : {}
+			},
 			formData: upstreamForm,
 			forwardExtras: false
 		});
@@ -808,6 +837,14 @@ function createShopwaveApiHandlers(config) {
 		passthrough(path) {
 			return { GET: (request) => forward(request, { path }) };
 		},
+		lookup(kind) {
+			const def = SHOPWAVE_LOOKUPS[kind];
+			if (!def) throw new Error(`Unknown Shopwave lookup "${kind}"`);
+			return { GET: (request) => forward(request, {
+				path: def.upstream,
+				forwardExtras: false
+			}) };
+		},
 		resource(kind) {
 			const def = resourceDef(kind);
 			const save = (request) => writeResource(request, def);
@@ -1150,6 +1187,9 @@ function createShopwaveAuth(config) {
 * export const { GET } = shopwave.resource("user");
 * // app/api/upload/route.ts
 * export const { POST } = shopwave.upload();
+* // app/api/products/tags/route.ts, app/api/products/instance-tags/route.ts
+* export const { GET } = shopwave.lookup("productTags");
+* export const { GET } = shopwave.lookup("productInstanceTags");
 * ```
 */
 function createShopwaveApi(config) {
@@ -1162,5 +1202,5 @@ function createShopwaveApi(config) {
 }
 
 //#endregion
-export { SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, ShopwaveAuthError, UPLOAD_KINDS, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
+export { SHOPWAVE_ENTITIES, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, ShopwaveAuthError, UPLOAD_KINDS, UPLOAD_PREFIXES, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.js.map