react-shopwave-connect 0.4.3 → 0.4.5

package/dist/index.d.cts

@@ -676,6 +676,9 @@ declare function fetchEntityById<K extends EntityKind>(kind: K, id: EntityId, pa
  * read) so an edited price is sent as a new instance. As a safeguard, a new
  * product (no `id`, e.g. a duplicate) never sends instance ids: an id copied from
  * another product would otherwise point the save at that product's instances.
+ *
+ * `images` is sent as file names ({@link toStoredProductImages}), so the URLs a
+ * read returns can be passed straight back; leaving `images` out keeps them.
  */
 declare const saveProduct: (product: ProductSaveInput, options?: RequestOptions) => Promise<Saved<Product>>;
 declare const deleteProduct: (id: EntityId, options?: RequestOptions) => Promise<void>;
@@ -844,20 +847,40 @@ 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>;
 /** How uploads are addressed (app route and Shopwave uploader). */
 declare const SHOPWAVE_UPLOAD: Readonly<{
-  /** App route: `POST /api/<route>` (multipart `file` + `kind`). */
+  /** App route: `POST /api/<route>` (multipart `file` + `kind`, optional `prefix`). */
   route: "upload";
   /** Shopwave path: `PUT {apiUrl}/uploader` (multipart `file`). */
   upstream: "uploader";
   /** Header that carries the upload kind upstream. */
   kindHeader: "contentType";
+  /** Header that carries the image role upstream (see `UploadPrefix`). */
+  prefixHeader: "prefix";
   /** Multipart field name for the file, on both sides. */
   fileField: "file";
   /** Multipart field name for the kind in the app request. */
   kindField: "kind";
+  /** Multipart field name for the image role in the app request. */
+  prefixField: "prefix";
 }>;
 declare function isUploadKind(value: unknown): value is UploadKind;
+declare function isUploadPrefix(value: unknown): value is UploadPrefix;
 /**
  * Read-only lists that aren't records: the merchant's distinct tags.
  *
@@ -890,11 +913,12 @@ declare const SHOPWAVE_LOOKUPS: Readonly<Record<LookupKind, LookupDefinition>>;
 //#endregion
 //#region src/core/imageFit.d.ts
 /**
- * Browser helpers for getting an image to an exact pixel size before upload.
+ * Browser helpers for getting an image to the right size before upload.
  *
- * Shopwave doesn't resize uploads, and the merchant image slots have fixed
- * sizes (adminV1 refuses any other size), so the SDK scales and centre-crops
- * the image in the browser instead.
+ * Shopwave doesn't resize uploads, so images are scaled and centre-cropped in
+ * the browser: to an exact size for the merchant image slots
+ * ({@link fitImageToSize}), or to a rule (ratio, minimum, maximum) with
+ * {@link prepareImage}, which apps use to give each kind of image its own rule.
  */
 /** Source rectangle to draw so the image covers `dstWidth × dstHeight` (centre crop, no stretching). */
 interface CropRect {
@@ -928,11 +952,113 @@ interface FitImageOptions {
  * input, with the output type's extension.
  */
 declare function fitImageToSize(file: Blob, width: number, height: number, options?: FitImageOptions): Promise<File>;
+/**
+ * How an image must end up before upload. Every field is optional; give an
+ * exact size (`width` + `height`) or an `aspectRatio`, not both.
+ *
+ * Images are always scaled down first and then centre-cropped (never
+ * stretched): the kept area is the largest one with the right shape.
+ *
+ * @example
+ * // "Cropped to 100:77, at least 600 × 462", at most 2000 px on the long side
+ * { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 }
+ * // Exactly 600 × 462
+ * { width: 600, height: 462 }
+ * // Any shape, scaled down to fit 2000 px
+ * { maxLongSide: 2000 }
+ */
+interface ImageRule {
+  /** Exact output width (needs `height`). */
+  width?: number;
+  /** Exact output height (needs `width`). */
+  height?: number;
+  /** Shape to crop to: `1.3`, `"100:77"`, `"100/77"` or `[100, 77]`. */
+  aspectRatio?: number | string | readonly [number, number];
+  /** Smallest acceptable output; a smaller image is refused (see `allowUpscale`). */
+  minWidth?: number;
+  minHeight?: number;
+  /** Largest output; a bigger image is scaled down to fit. */
+  maxWidth?: number;
+  maxHeight?: number;
+  /** Largest output on the longer side, whichever it is. */
+  maxLongSide?: number;
+  /** Enlarge a too-small image instead of refusing it. Default false. */
+  allowUpscale?: boolean;
+}
+/** What {@link prepareImage} will do to an image, worked out without touching it. */
+interface ImageFitPlan {
+  /** The area of the source that's kept. */
+  crop: CropRect;
+  /** Output size. */
+  width: number;
+  height: number;
+  /** True when the source already fits the rule, so it can be uploaded as it is. */
+  unchanged: boolean;
+}
+/** A rule that can't be met by any image (a mistake in the rule, not the image). */
+declare class ImageRuleError extends Error {
+  constructor(message: string);
+}
+/** The image is smaller than the rule's minimum (and `allowUpscale` is off). */
+declare class ImageTooSmallError extends Error {
+  /** The smallest size the rule accepts. */
+  readonly required: ImageSize;
+  /** The largest area of the right shape the image could give. */
+  readonly actual: ImageSize;
+  constructor(required: ImageSize, actual: ImageSize);
+}
+/**
+ * An aspect ratio as width ÷ height: `"100:77"`, `"100/77"`, `[100, 77]` →
+ * 1.2987…; `1.3` → 1.3. Throws {@link ImageRuleError} for anything else.
+ */
+declare function parseAspectRatio(value: number | string | readonly [number, number]): number;
+/** Throws {@link ImageRuleError} when the rule contradicts itself. */
+declare function checkImageRule(rule: ImageRule): void;
+/**
+ * Works out what to do to a `source`-sized image to meet `rule`: the centred
+ * crop of the right shape (the largest one), then the output size (scaled
+ * down to the maximum, never below the minimum). Pure: no browser needed.
+ *
+ * Throws {@link ImageTooSmallError} when the crop is below the minimum (or
+ * the exact size) and `allowUpscale` is off, and {@link ImageRuleError} for a
+ * contradictory rule.
+ *
+ * @example
+ * planImageFit({ width: 6000, height: 4000 }, { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 })
+ * // → crop { sx: 403, sy: 0, sw: 5194, sh: 4000 }, 2000 × 1540
+ */
+declare function planImageFit(source: ImageSize, rule: ImageRule): ImageFitPlan;
+interface PrepareImageOptions {
+  /** Output type. Default: the source's type when it's PNG, JPEG or WebP, else PNG. */
+  type?: "image/png" | "image/jpeg" | "image/webp";
+  /** 0–1, for JPEG and WebP. Default 0.9. */
+  quality?: number;
+}
+/**
+ * Returns the image meeting `rule` ({@link planImageFit}): centre-cropped to
+ * the right shape and scaled in a single draw. An image that already fits is
+ * returned untouched (same bytes). Browser only.
+ *
+ * Throws {@link ImageTooSmallError} (show `required` and `actual` to the
+ * person) or {@link ImageRuleError}; an unreadable file rejects with the
+ * browser's decoding error.
+ *
+ * @example
+ * const ready = await prepareImage(file, { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 });
+ * await uploadImage(ready, { kind: "product", prefix: "product" });
+ */
+declare function prepareImage(file: Blob, rule: ImageRule, options?: PrepareImageOptions): Promise<File>;
 //#endregion
 //#region src/core/upload.d.ts
 interface UploadImageParams {
   /** What the image is for (sent to Shopwave as the uploader's `contentType`). */
   kind: UploadKind;
+  /**
+   * The image's role (sent to Shopwave as the uploader's `prefix` header), e.g.
+   * `product_thumbnail` for a product's lead image. Leave it out for images
+   * without a role (merchant logos).
+   */
+  prefix?: UploadPrefix;
   /** File name to send when `file` is a Blob without one. Defaults to `File.name`, else `"upload"`. */
   fileName?: string;
 }
@@ -1224,6 +1350,31 @@ interface UserResponse {
 /** Reads the logged-in user, or `null` when the API returns none. */
 declare function fetchUser(options?: RequestOptions): Promise<User | null>;
 //#endregion
+//#region src/core/productImages.d.ts
+/**
+ * Product images, as the live API stores them (merchant 5644, 4 Nov 2026):
+ * - A product's `images` is a list. **Reads return full URLs**
+ *   (`http://static.merchantstack.com/images/merchant/<id>/product/<file>`);
+ *   **writes take the uploader's file names** ({@link toStoredProductImages};
+ *   `saveProduct` does this for you).
+ * - The uploader takes one file per request. With a `prefix` (see
+ *   `UploadPrefix`) it names the file `<prefix>_<hash>.<ext>`
+ *   (`product_thumbnail_1bdd…41090b.png`); without one, `<hash>.<ext>`. So an
+ *   image's role can be read back from its name ({@link productImageRole}).
+ */
+/**
+ * The role in an image's file name or URL, from the uploader's `prefix`:
+ * `"…/product_thumbnail_1bdd.png"` → `"product_thumbnail"`. `null` for a name
+ * without one (images uploaded without a prefix, e.g. before prefixes existed).
+ */
+declare function productImageRole(value: unknown): UploadPrefix | null;
+/**
+ * A product's `images` as the API takes them on a save: file names, not the
+ * URLs a read returns. Non-strings, blanks and duplicates are dropped; the
+ * order is kept.
+ */
+declare function toStoredProductImages(images: unknown): string[];
+//#endregion
 //#region src/hooks/shared.d.ts
 /**
  * Consistent return shape for every auto-fetching ("query") hook.
@@ -1457,5 +1608,5 @@ interface UseBasketReportReturn {
  */
 declare function useBasketReport(options?: RequestOptions): UseBasketReportReturn;
 //#endregion
-export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageSize, LookupDefinition, LookupKind, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProductInstanceTags, fetchProductTags, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, useProductInstanceTags, useProductTags, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
+export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageFitPlan, ImageRule, ImageRuleError, ImageSize, ImageTooSmallError, LookupDefinition, LookupKind, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, PrepareImageOptions, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UPLOAD_PREFIXES, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadPrefix, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, checkImageRule, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProductInstanceTags, fetchProductTags, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, isUploadPrefix, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseAspectRatio, parseBasketReportData, planImageFit, prepareImage, productImageRole, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, toStoredProductImages, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, useProductInstanceTags, useProductTags, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -676,6 +676,9 @@ declare function fetchEntityById<K extends EntityKind>(kind: K, id: EntityId, pa
  * read) so an edited price is sent as a new instance. As a safeguard, a new
  * product (no `id`, e.g. a duplicate) never sends instance ids: an id copied from
  * another product would otherwise point the save at that product's instances.
+ *
+ * `images` is sent as file names ({@link toStoredProductImages}), so the URLs a
+ * read returns can be passed straight back; leaving `images` out keeps them.
  */
 declare const saveProduct: (product: ProductSaveInput, options?: RequestOptions) => Promise<Saved<Product>>;
 declare const deleteProduct: (id: EntityId, options?: RequestOptions) => Promise<void>;
@@ -844,20 +847,40 @@ 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>;
 /** How uploads are addressed (app route and Shopwave uploader). */
 declare const SHOPWAVE_UPLOAD: Readonly<{
-  /** App route: `POST /api/<route>` (multipart `file` + `kind`). */
+  /** App route: `POST /api/<route>` (multipart `file` + `kind`, optional `prefix`). */
   route: "upload";
   /** Shopwave path: `PUT {apiUrl}/uploader` (multipart `file`). */
   upstream: "uploader";
   /** Header that carries the upload kind upstream. */
   kindHeader: "contentType";
+  /** Header that carries the image role upstream (see `UploadPrefix`). */
+  prefixHeader: "prefix";
   /** Multipart field name for the file, on both sides. */
   fileField: "file";
   /** Multipart field name for the kind in the app request. */
   kindField: "kind";
+  /** Multipart field name for the image role in the app request. */
+  prefixField: "prefix";
 }>;
 declare function isUploadKind(value: unknown): value is UploadKind;
+declare function isUploadPrefix(value: unknown): value is UploadPrefix;
 /**
  * Read-only lists that aren't records: the merchant's distinct tags.
  *
@@ -890,11 +913,12 @@ declare const SHOPWAVE_LOOKUPS: Readonly<Record<LookupKind, LookupDefinition>>;
 //#endregion
 //#region src/core/imageFit.d.ts
 /**
- * Browser helpers for getting an image to an exact pixel size before upload.
+ * Browser helpers for getting an image to the right size before upload.
  *
- * Shopwave doesn't resize uploads, and the merchant image slots have fixed
- * sizes (adminV1 refuses any other size), so the SDK scales and centre-crops
- * the image in the browser instead.
+ * Shopwave doesn't resize uploads, so images are scaled and centre-cropped in
+ * the browser: to an exact size for the merchant image slots
+ * ({@link fitImageToSize}), or to a rule (ratio, minimum, maximum) with
+ * {@link prepareImage}, which apps use to give each kind of image its own rule.
  */
 /** Source rectangle to draw so the image covers `dstWidth × dstHeight` (centre crop, no stretching). */
 interface CropRect {
@@ -928,11 +952,113 @@ interface FitImageOptions {
  * input, with the output type's extension.
  */
 declare function fitImageToSize(file: Blob, width: number, height: number, options?: FitImageOptions): Promise<File>;
+/**
+ * How an image must end up before upload. Every field is optional; give an
+ * exact size (`width` + `height`) or an `aspectRatio`, not both.
+ *
+ * Images are always scaled down first and then centre-cropped (never
+ * stretched): the kept area is the largest one with the right shape.
+ *
+ * @example
+ * // "Cropped to 100:77, at least 600 × 462", at most 2000 px on the long side
+ * { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 }
+ * // Exactly 600 × 462
+ * { width: 600, height: 462 }
+ * // Any shape, scaled down to fit 2000 px
+ * { maxLongSide: 2000 }
+ */
+interface ImageRule {
+  /** Exact output width (needs `height`). */
+  width?: number;
+  /** Exact output height (needs `width`). */
+  height?: number;
+  /** Shape to crop to: `1.3`, `"100:77"`, `"100/77"` or `[100, 77]`. */
+  aspectRatio?: number | string | readonly [number, number];
+  /** Smallest acceptable output; a smaller image is refused (see `allowUpscale`). */
+  minWidth?: number;
+  minHeight?: number;
+  /** Largest output; a bigger image is scaled down to fit. */
+  maxWidth?: number;
+  maxHeight?: number;
+  /** Largest output on the longer side, whichever it is. */
+  maxLongSide?: number;
+  /** Enlarge a too-small image instead of refusing it. Default false. */
+  allowUpscale?: boolean;
+}
+/** What {@link prepareImage} will do to an image, worked out without touching it. */
+interface ImageFitPlan {
+  /** The area of the source that's kept. */
+  crop: CropRect;
+  /** Output size. */
+  width: number;
+  height: number;
+  /** True when the source already fits the rule, so it can be uploaded as it is. */
+  unchanged: boolean;
+}
+/** A rule that can't be met by any image (a mistake in the rule, not the image). */
+declare class ImageRuleError extends Error {
+  constructor(message: string);
+}
+/** The image is smaller than the rule's minimum (and `allowUpscale` is off). */
+declare class ImageTooSmallError extends Error {
+  /** The smallest size the rule accepts. */
+  readonly required: ImageSize;
+  /** The largest area of the right shape the image could give. */
+  readonly actual: ImageSize;
+  constructor(required: ImageSize, actual: ImageSize);
+}
+/**
+ * An aspect ratio as width ÷ height: `"100:77"`, `"100/77"`, `[100, 77]` →
+ * 1.2987…; `1.3` → 1.3. Throws {@link ImageRuleError} for anything else.
+ */
+declare function parseAspectRatio(value: number | string | readonly [number, number]): number;
+/** Throws {@link ImageRuleError} when the rule contradicts itself. */
+declare function checkImageRule(rule: ImageRule): void;
+/**
+ * Works out what to do to a `source`-sized image to meet `rule`: the centred
+ * crop of the right shape (the largest one), then the output size (scaled
+ * down to the maximum, never below the minimum). Pure: no browser needed.
+ *
+ * Throws {@link ImageTooSmallError} when the crop is below the minimum (or
+ * the exact size) and `allowUpscale` is off, and {@link ImageRuleError} for a
+ * contradictory rule.
+ *
+ * @example
+ * planImageFit({ width: 6000, height: 4000 }, { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 })
+ * // → crop { sx: 403, sy: 0, sw: 5194, sh: 4000 }, 2000 × 1540
+ */
+declare function planImageFit(source: ImageSize, rule: ImageRule): ImageFitPlan;
+interface PrepareImageOptions {
+  /** Output type. Default: the source's type when it's PNG, JPEG or WebP, else PNG. */
+  type?: "image/png" | "image/jpeg" | "image/webp";
+  /** 0–1, for JPEG and WebP. Default 0.9. */
+  quality?: number;
+}
+/**
+ * Returns the image meeting `rule` ({@link planImageFit}): centre-cropped to
+ * the right shape and scaled in a single draw. An image that already fits is
+ * returned untouched (same bytes). Browser only.
+ *
+ * Throws {@link ImageTooSmallError} (show `required` and `actual` to the
+ * person) or {@link ImageRuleError}; an unreadable file rejects with the
+ * browser's decoding error.
+ *
+ * @example
+ * const ready = await prepareImage(file, { aspectRatio: "100:77", minWidth: 600, minHeight: 462, maxLongSide: 2000 });
+ * await uploadImage(ready, { kind: "product", prefix: "product" });
+ */
+declare function prepareImage(file: Blob, rule: ImageRule, options?: PrepareImageOptions): Promise<File>;
 //#endregion
 //#region src/core/upload.d.ts
 interface UploadImageParams {
   /** What the image is for (sent to Shopwave as the uploader's `contentType`). */
   kind: UploadKind;
+  /**
+   * The image's role (sent to Shopwave as the uploader's `prefix` header), e.g.
+   * `product_thumbnail` for a product's lead image. Leave it out for images
+   * without a role (merchant logos).
+   */
+  prefix?: UploadPrefix;
   /** File name to send when `file` is a Blob without one. Defaults to `File.name`, else `"upload"`. */
   fileName?: string;
 }
@@ -1224,6 +1350,31 @@ interface UserResponse {
 /** Reads the logged-in user, or `null` when the API returns none. */
 declare function fetchUser(options?: RequestOptions): Promise<User | null>;
 //#endregion
+//#region src/core/productImages.d.ts
+/**
+ * Product images, as the live API stores them (merchant 5644, 4 Nov 2026):
+ * - A product's `images` is a list. **Reads return full URLs**
+ *   (`http://static.merchantstack.com/images/merchant/<id>/product/<file>`);
+ *   **writes take the uploader's file names** ({@link toStoredProductImages};
+ *   `saveProduct` does this for you).
+ * - The uploader takes one file per request. With a `prefix` (see
+ *   `UploadPrefix`) it names the file `<prefix>_<hash>.<ext>`
+ *   (`product_thumbnail_1bdd…41090b.png`); without one, `<hash>.<ext>`. So an
+ *   image's role can be read back from its name ({@link productImageRole}).
+ */
+/**
+ * The role in an image's file name or URL, from the uploader's `prefix`:
+ * `"…/product_thumbnail_1bdd.png"` → `"product_thumbnail"`. `null` for a name
+ * without one (images uploaded without a prefix, e.g. before prefixes existed).
+ */
+declare function productImageRole(value: unknown): UploadPrefix | null;
+/**
+ * A product's `images` as the API takes them on a save: file names, not the
+ * URLs a read returns. Non-strings, blanks and duplicates are dropped; the
+ * order is kept.
+ */
+declare function toStoredProductImages(images: unknown): string[];
+//#endregion
 //#region src/hooks/shared.d.ts
 /**
  * Consistent return shape for every auto-fetching ("query") hook.
@@ -1457,5 +1608,5 @@ interface UseBasketReportReturn {
  */
 declare function useBasketReport(options?: RequestOptions): UseBasketReportReturn;
 //#endregion
-export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageSize, LookupDefinition, LookupKind, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProductInstanceTags, fetchProductTags, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, useProductInstanceTags, useProductTags, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
+export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, CropRect, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, FitImageOptions, ImageFitPlan, ImageRule, ImageRuleError, ImageSize, ImageTooSmallError, LookupDefinition, LookupKind, MERCHANT_COLOUR_KEYS, MERCHANT_FIELD_MAX_LENGTH, MERCHANT_IMAGE_SLOTS, MERCHANT_IMAGE_SLOT_KEYS, MERCHANT_LINK_KEYS, MERCHANT_LINK_PATHS, MERCHANT_OBJECT_FIELDS, MERCHANT_READ_ONLY_FIELDS, Merchant, MerchantColourKey, MerchantColourSet, MerchantColours, MerchantImageIds, MerchantImageSlot, MerchantImageSlotDefinition, MerchantLinkKey, MerchantLinks, MerchantPatch, MerchantResponse, MessageInfo, MutationState, ParsedBasket, PrepareImageOptions, Product, ProductInstance, ProductInstanceInput, ProductInstances, ProductResponse, ProductSaveInput, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RepricedInstance, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UPLOAD_PREFIXES, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadPrefix, UploadedImage, UseBasketReportReturn, User, UserEmployee, UserResponse, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, checkImageRule, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, coverCrop, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchMerchant, fetchProduct, fetchProductInstanceTags, fetchProductTags, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, findRepricedInstances, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isSameInstancePrice, isUploadKind, isUploadPrefix, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseAspectRatio, parseBasketReportData, planImageFit, prepareImage, productImageRole, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toProductInstancesForSave, toShopwaveApiError, toStoredImageIds, toStoredProductImages, updateMerchant, uploadImage, uploadMerchantImage, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, useProductInstanceTags, useProductTags, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
 //# sourceMappingURL=index.d.ts.map