react-shopwave-connect 0.4.4 → 0.4.6

package/dist/index.d.cts

@@ -850,8 +850,8 @@ 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.
+ * the file wherever a record stores it (a product's `images`). Live, test
+ * merchant, 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
@@ -892,7 +892,7 @@ declare function isUploadPrefix(value: unknown): value is UploadPrefix;
  *   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
+ *   a test merchant, 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").
@@ -913,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 {
@@ -951,6 +952,102 @@ 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 {
@@ -982,7 +1079,7 @@ declare const SHOPWAVE_IMAGE_BASE_URL = "https://s3-eu-west-1.amazonaws.com/stat
 /**
  * Turns an image path from the API into a URL a page can load over HTTPS:
  * `http://static.merchantstack.com/images/x.png` → `<base>/x.png`, and a
- * relative path (`merchant/5644/logo/x.png`) → `<base>/merchant/5644/logo/x.png`.
+ * relative path (`merchant/123/logo/x.png`) → `<base>/merchant/123/logo/x.png`.
  * Other absolute URLs are returned unchanged; empty input gives `""`.
  */
 declare function getImageUrl(path: string | null | undefined, base?: string): string;
@@ -998,7 +1095,7 @@ declare function uploadImage(file: Blob, params: UploadImageParams, options?: Re
 //#endregion
 //#region src/core/merchantImages.d.ts
 /**
- * Merchant images, as adminV1 saves them and adminV2 reads them:
+ * Merchant images, as Shopwave's existing admin apps save and read them:
  *
  * ```
  * { logo: { receipt: "<file>", square: "<file>" }, feature: ["<file>"] }
@@ -1015,7 +1112,7 @@ declare function uploadImage(file: Blob, params: UploadImageParams, options?: Re
  *   So a featured image must be uploaded with kind `merchantFeature` (which
  *   stores it under `feature/`); a `merchant` upload lands under `logo/`.
  *
- * Confirmed on the live API, merchant 5644, 30 Sep 2026.
+ * Confirmed on the live API, 30 Sep 2026.
  */
 interface MerchantImageIds {
   logo?: {
@@ -1034,12 +1131,12 @@ interface MerchantImageSlotDefinition {
   field: "logo.receipt" | "logo.square" | "feature[0]";
   /** Uploader `contentType` (the featured image has its own). */
   uploadKind: UploadKind;
-  /** Exact size in pixels. adminV1 refuses any other size; the API doesn't resize. */
+  /** Exact size in pixels. Shopwave's existing admin refuses any other size; the API doesn't resize. */
   width: number;
   height: number;
 }
 /**
- * Where each slot lives, its upload kind and its exact size (from adminV1's
+ * Where each slot lives, its upload kind and its exact size (from the existing admin's
  * merchant settings page).
  */
 declare const MERCHANT_IMAGE_SLOTS: Readonly<Record<MerchantImageSlot, MerchantImageSlotDefinition>>;
@@ -1064,7 +1161,7 @@ declare function getMerchantImageUrl(imageIds: MerchantImageIds | null | undefin
 declare function setMerchantImage(imageIds: MerchantImageIds | null | undefined, slot: MerchantImageSlot, fileName: string | null): MerchantImageIds;
 /**
  * The `imageIds` to send on a save: every URL is turned back into its file
- * name (what adminV1 does with images you didn't change) and empty values
+ * name (what the existing admin does with images you didn't change) and empty values
  * are dropped. No images gives `{}`.
  */
 declare function toStoredImageIds(imageIds: unknown): MerchantImageIds;
@@ -1093,7 +1190,7 @@ interface MerchantColourSet {
   [key: string]: string | null | undefined;
 }
 /**
- * Brand colours, as adminV1 saves them and adminV2 reads them
+ * Brand colours, as Shopwave's existing admin apps save and read them
  * (`colours.primary.main` is the logo background): `{ primary: { main,
  * highlight, contrast } }`. `{}` when unset. Confirmed live, 30 Sep 2026.
  */
@@ -1105,7 +1202,7 @@ interface MerchantColours {
 declare const MERCHANT_COLOUR_KEYS: readonly ["main", "highlight", "contrast"];
 type MerchantColourKey = (typeof MERCHANT_COLOUR_KEYS)[number];
 /**
- * Web and social links, as adminV1 saves them:
+ * Web and social links, as Shopwave's existing admin saves them:
  * `{ website: { home }, social: { twitter, facebook, instagram } }`.
  * `{}` when empty (confirmed live, 30 Sep 2026). Use {@link normalizeMerchantLinks} to read older shapes and
  * {@link merchantLinksToForm} / {@link merchantLinksFromForm} for flat forms.
@@ -1131,9 +1228,9 @@ declare const MERCHANT_LINK_PATHS: Readonly<Record<MerchantLinkKey, readonly [st
 /**
  * Reads `merchant.links` as flat fields (`{ website, twitter, facebook,
  * instagram }`), whatever shape it was saved in:
- * - the nested shape adminV1 saves (`{ website: { home }, social: { … } }`);
+ * - the nested shape the existing admin saves (`{ website: { home }, social: { … } }`);
  * - flat keys (`{ website: "…" }`, what SDK 0.4.0 pre-releases sent);
- * - an array in {@link MERCHANT_LINK_KEYS} order (older AdminUI versions).
+ * - an array in {@link MERCHANT_LINK_KEYS} order (older app versions).
  * Empty values are dropped.
  */
 declare function merchantLinksToForm(links: unknown): Partial<Record<MerchantLinkKey, string>>;
@@ -1142,7 +1239,7 @@ declare function merchantLinksToForm(links: unknown): Partial<Record<MerchantLin
  * out, and so is a group with nothing in it; no links gives `{}`.
  */
 declare function merchantLinksFromForm(form: Partial<Record<MerchantLinkKey, string | null | undefined>>): MerchantLinks;
-/** Reads any stored or older `links` value into the nested shape adminV1 saves. */
+/** Reads any stored or older `links` value into the nested shape the existing admin saves. */
 declare function normalizeMerchantLinks(links: unknown): MerchantLinks;
 interface Merchant {
   id: number;
@@ -1255,7 +1352,7 @@ 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):
+ * Product images, as the live API stores them (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};
@@ -1511,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, UPLOAD_PREFIXES, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadPrefix, 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, isUploadPrefix, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseBasketReportData, 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 };
+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

@@ -850,8 +850,8 @@ 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.
+ * the file wherever a record stores it (a product's `images`). Live, test
+ * merchant, 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
@@ -892,7 +892,7 @@ declare function isUploadPrefix(value: unknown): value is UploadPrefix;
  *   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
+ *   a test merchant, 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").
@@ -913,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 {
@@ -951,6 +952,102 @@ 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 {
@@ -982,7 +1079,7 @@ declare const SHOPWAVE_IMAGE_BASE_URL = "https://s3-eu-west-1.amazonaws.com/stat
 /**
  * Turns an image path from the API into a URL a page can load over HTTPS:
  * `http://static.merchantstack.com/images/x.png` → `<base>/x.png`, and a
- * relative path (`merchant/5644/logo/x.png`) → `<base>/merchant/5644/logo/x.png`.
+ * relative path (`merchant/123/logo/x.png`) → `<base>/merchant/123/logo/x.png`.
  * Other absolute URLs are returned unchanged; empty input gives `""`.
  */
 declare function getImageUrl(path: string | null | undefined, base?: string): string;
@@ -998,7 +1095,7 @@ declare function uploadImage(file: Blob, params: UploadImageParams, options?: Re
 //#endregion
 //#region src/core/merchantImages.d.ts
 /**
- * Merchant images, as adminV1 saves them and adminV2 reads them:
+ * Merchant images, as Shopwave's existing admin apps save and read them:
  *
  * ```
  * { logo: { receipt: "<file>", square: "<file>" }, feature: ["<file>"] }
@@ -1015,7 +1112,7 @@ declare function uploadImage(file: Blob, params: UploadImageParams, options?: Re
  *   So a featured image must be uploaded with kind `merchantFeature` (which
  *   stores it under `feature/`); a `merchant` upload lands under `logo/`.
  *
- * Confirmed on the live API, merchant 5644, 30 Sep 2026.
+ * Confirmed on the live API, 30 Sep 2026.
  */
 interface MerchantImageIds {
   logo?: {
@@ -1034,12 +1131,12 @@ interface MerchantImageSlotDefinition {
   field: "logo.receipt" | "logo.square" | "feature[0]";
   /** Uploader `contentType` (the featured image has its own). */
   uploadKind: UploadKind;
-  /** Exact size in pixels. adminV1 refuses any other size; the API doesn't resize. */
+  /** Exact size in pixels. Shopwave's existing admin refuses any other size; the API doesn't resize. */
   width: number;
   height: number;
 }
 /**
- * Where each slot lives, its upload kind and its exact size (from adminV1's
+ * Where each slot lives, its upload kind and its exact size (from the existing admin's
  * merchant settings page).
  */
 declare const MERCHANT_IMAGE_SLOTS: Readonly<Record<MerchantImageSlot, MerchantImageSlotDefinition>>;
@@ -1064,7 +1161,7 @@ declare function getMerchantImageUrl(imageIds: MerchantImageIds | null | undefin
 declare function setMerchantImage(imageIds: MerchantImageIds | null | undefined, slot: MerchantImageSlot, fileName: string | null): MerchantImageIds;
 /**
  * The `imageIds` to send on a save: every URL is turned back into its file
- * name (what adminV1 does with images you didn't change) and empty values
+ * name (what the existing admin does with images you didn't change) and empty values
  * are dropped. No images gives `{}`.
  */
 declare function toStoredImageIds(imageIds: unknown): MerchantImageIds;
@@ -1093,7 +1190,7 @@ interface MerchantColourSet {
   [key: string]: string | null | undefined;
 }
 /**
- * Brand colours, as adminV1 saves them and adminV2 reads them
+ * Brand colours, as Shopwave's existing admin apps save and read them
  * (`colours.primary.main` is the logo background): `{ primary: { main,
  * highlight, contrast } }`. `{}` when unset. Confirmed live, 30 Sep 2026.
  */
@@ -1105,7 +1202,7 @@ interface MerchantColours {
 declare const MERCHANT_COLOUR_KEYS: readonly ["main", "highlight", "contrast"];
 type MerchantColourKey = (typeof MERCHANT_COLOUR_KEYS)[number];
 /**
- * Web and social links, as adminV1 saves them:
+ * Web and social links, as Shopwave's existing admin saves them:
  * `{ website: { home }, social: { twitter, facebook, instagram } }`.
  * `{}` when empty (confirmed live, 30 Sep 2026). Use {@link normalizeMerchantLinks} to read older shapes and
  * {@link merchantLinksToForm} / {@link merchantLinksFromForm} for flat forms.
@@ -1131,9 +1228,9 @@ declare const MERCHANT_LINK_PATHS: Readonly<Record<MerchantLinkKey, readonly [st
 /**
  * Reads `merchant.links` as flat fields (`{ website, twitter, facebook,
  * instagram }`), whatever shape it was saved in:
- * - the nested shape adminV1 saves (`{ website: { home }, social: { … } }`);
+ * - the nested shape the existing admin saves (`{ website: { home }, social: { … } }`);
  * - flat keys (`{ website: "…" }`, what SDK 0.4.0 pre-releases sent);
- * - an array in {@link MERCHANT_LINK_KEYS} order (older AdminUI versions).
+ * - an array in {@link MERCHANT_LINK_KEYS} order (older app versions).
  * Empty values are dropped.
  */
 declare function merchantLinksToForm(links: unknown): Partial<Record<MerchantLinkKey, string>>;
@@ -1142,7 +1239,7 @@ declare function merchantLinksToForm(links: unknown): Partial<Record<MerchantLin
  * out, and so is a group with nothing in it; no links gives `{}`.
  */
 declare function merchantLinksFromForm(form: Partial<Record<MerchantLinkKey, string | null | undefined>>): MerchantLinks;
-/** Reads any stored or older `links` value into the nested shape adminV1 saves. */
+/** Reads any stored or older `links` value into the nested shape the existing admin saves. */
 declare function normalizeMerchantLinks(links: unknown): MerchantLinks;
 interface Merchant {
   id: number;
@@ -1255,7 +1352,7 @@ 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):
+ * Product images, as the live API stores them (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};
@@ -1511,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, UPLOAD_PREFIXES, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadPrefix, 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, isUploadPrefix, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, normalizeTagList, parseBasketReportData, 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 };
+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