react-shopwave-connect 0.4.4 → 0.4.5

package/dist/index.d.cts

@@ -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 {
@@ -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

@@ -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 {
@@ -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

package/dist/index.js

@@ -638,6 +638,35 @@ async function readImageSize(file) {
 		bitmap.close?.();
 	}
 }
+/** Draws `crop` of the bitmap at `width × height` and encodes it (one resample). */
+async function drawCrop(bitmap, crop, width, height, type, quality, fn) {
+	const { sx, sy, sw, sh } = crop;
+	if (typeof OffscreenCanvas === "function") {
+		const canvas$1 = new OffscreenCanvas(width, height);
+		const ctx$1 = canvas$1.getContext("2d");
+		if (!ctx$1) throw new Error(`${fn}: no 2D canvas context`);
+		ctx$1.imageSmoothingQuality = "high";
+		ctx$1.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
+		return canvas$1.convertToBlob({
+			type,
+			quality
+		});
+	}
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+	const ctx = canvas.getContext("2d");
+	if (!ctx) throw new Error(`${fn}: no 2D canvas context`);
+	ctx.imageSmoothingQuality = "high";
+	ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
+	return new Promise((resolve, reject) => canvas.toBlob((b) => b ? resolve(b) : reject(/* @__PURE__ */ new Error(`${fn}: encoding failed`)), type, quality));
+}
+/** The input's name with the output type's extension. */
+function outputName(file, type) {
+	const name = file.name || "image";
+	const ext = type === "image/jpeg" ? "jpg" : type.split("/")[1];
+	return `${name.replace(/\.[^.]+$/, "")}.${ext}`;
+}
 /**
 * Returns the image at exactly `width × height`: scaled and centre-cropped
 * (never stretched). Browser only. The result is a `File` named like the
@@ -646,39 +675,194 @@ async function readImageSize(file) {
 async function fitImageToSize(file, width, height, options = {}) {
 	requireBrowserImages("fitImageToSize");
 	const { type = "image/png", quality, keepIfExact = true } = options;
-	const name = file.name || "image";
-	const ext = type === "image/jpeg" ? "jpg" : type.split("/")[1];
-	const outName = `${name.replace(/\.[^.]+$/, "")}.${ext}`;
+	const outName = outputName(file, type);
 	const bitmap = await createImageBitmap(file);
 	try {
 		if (keepIfExact && bitmap.width === width && bitmap.height === height && file.type === type) return file instanceof File ? file : new File([file], outName, { type });
-		const { sx, sy, sw, sh } = coverCrop(bitmap.width, bitmap.height, width, height);
-		let blob;
-		if (typeof OffscreenCanvas === "function") {
-			const canvas = new OffscreenCanvas(width, height);
-			const ctx = canvas.getContext("2d");
-			if (!ctx) throw new Error("fitImageToSize: no 2D canvas context");
-			ctx.imageSmoothingQuality = "high";
-			ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
-			blob = await canvas.convertToBlob({
-				type,
-				quality
-			});
-		} else {
-			const canvas = document.createElement("canvas");
-			canvas.width = width;
-			canvas.height = height;
-			const ctx = canvas.getContext("2d");
-			if (!ctx) throw new Error("fitImageToSize: no 2D canvas context");
-			ctx.imageSmoothingQuality = "high";
-			ctx.drawImage(bitmap, sx, sy, sw, sh, 0, 0, width, height);
-			blob = await new Promise((resolve, reject) => canvas.toBlob((b) => b ? resolve(b) : reject(/* @__PURE__ */ new Error("fitImageToSize: encoding failed")), type, quality));
-		}
+		const blob = await drawCrop(bitmap, coverCrop(bitmap.width, bitmap.height, width, height), width, height, type, quality, "fitImageToSize");
 		return new File([blob], outName, { type });
 	} finally {
 		bitmap.close?.();
 	}
 }
+/** A rule that can't be met by any image (a mistake in the rule, not the image). */
+var ImageRuleError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ImageRuleError";
+	}
+};
+/** The image is smaller than the rule's minimum (and `allowUpscale` is off). */
+var ImageTooSmallError = class extends Error {
+	/** The smallest size the rule accepts. */
+	required;
+	/** The largest area of the right shape the image could give. */
+	actual;
+	constructor(required, actual) {
+		super(`The image is too small: it needs to be at least ${required.width} × ${required.height}, and it's ${actual.width} × ${actual.height}`);
+		this.name = "ImageTooSmallError";
+		this.required = required;
+		this.actual = actual;
+	}
+};
+const isPositive = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+/**
+* An aspect ratio as width ÷ height: `"100:77"`, `"100/77"`, `[100, 77]` →
+* 1.2987…; `1.3` → 1.3. Throws {@link ImageRuleError} for anything else.
+*/
+function parseAspectRatio(value) {
+	let parts = null;
+	if (typeof value === "number") return isPositive(value) ? value : badRatio(value);
+	if (Array.isArray(value)) parts = [value[0], value[1]];
+	else if (typeof value === "string") {
+		const text$1 = value.trim();
+		const match = /^(\d+(?:\.\d+)?)\s*[:/x×]\s*(\d+(?:\.\d+)?)$/i.exec(text$1);
+		if (match) parts = [Number(match[1]), Number(match[2])];
+		else if (/^\d+(?:\.\d+)?$/.test(text$1)) return isPositive(Number(text$1)) ? Number(text$1) : badRatio(value);
+	}
+	if (parts && isPositive(parts[0]) && isPositive(parts[1])) return parts[0] / parts[1];
+	return badRatio(value);
+}
+function badRatio(value) {
+	throw new ImageRuleError(`Not an aspect ratio: ${JSON.stringify(value)} (use e.g. "100:77", [100, 77] or 1.3)`);
+}
+/** Throws {@link ImageRuleError} when the rule contradicts itself. */
+function checkImageRule(rule) {
+	if (!rule || typeof rule !== "object") throw new ImageRuleError("An image rule must be an object");
+	for (const key of [
+		"width",
+		"height",
+		"minWidth",
+		"minHeight",
+		"maxWidth",
+		"maxHeight",
+		"maxLongSide"
+	]) if (rule[key] != null && !isPositive(rule[key])) throw new ImageRuleError(`${key} must be a positive number`);
+	if (rule.width != null || rule.height != null) {
+		if (rule.width == null || rule.height == null) throw new ImageRuleError("An exact size needs both width and height");
+		if (rule.aspectRatio != null) throw new ImageRuleError("Give an exact size or an aspectRatio, not both (the size sets the ratio)");
+		const extra = [
+			"minWidth",
+			"minHeight",
+			"maxWidth",
+			"maxHeight",
+			"maxLongSide"
+		].filter((key) => rule[key] != null);
+		if (extra.length > 0) throw new ImageRuleError(`An exact size is already the minimum and the maximum; remove ${extra.join(", ")}`);
+		return;
+	}
+	if (rule.aspectRatio != null) parseAspectRatio(rule.aspectRatio);
+	if (rule.minWidth != null && rule.maxWidth != null && rule.minWidth > rule.maxWidth) throw new ImageRuleError("minWidth is larger than maxWidth");
+	if (rule.minHeight != null && rule.maxHeight != null && rule.minHeight > rule.maxHeight) throw new ImageRuleError("minHeight is larger than maxHeight");
+	if (rule.maxLongSide != null && Math.max(rule.minWidth ?? 0, rule.minHeight ?? 0) > rule.maxLongSide) throw new ImageRuleError("The minimum size is larger than maxLongSide");
+}
+/**
+* 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
+*/
+function planImageFit(source, rule) {
+	checkImageRule(rule);
+	const { width: W, height: H } = source ?? {};
+	if (!isPositive(W) || !isPositive(H)) throw new Error("planImageFit: the image has no size");
+	const exact = rule.width != null && rule.height != null;
+	const ratio = exact ? rule.width / rule.height : rule.aspectRatio != null ? parseAspectRatio(rule.aspectRatio) : null;
+	const crop = ratio == null ? {
+		sx: 0,
+		sy: 0,
+		sw: W,
+		sh: H
+	} : coverCrop(W, H, ratio, 1);
+	const { sw, sh } = crop;
+	const kept = {
+		width: sw,
+		height: sh
+	};
+	let width;
+	let height;
+	if (exact) {
+		width = rule.width;
+		height = rule.height;
+		if ((sw < width || sh < height) && !rule.allowUpscale) throw new ImageTooSmallError({
+			width,
+			height
+		}, kept);
+	} else {
+		const minW = rule.minWidth ?? 0;
+		const minH = rule.minHeight ?? 0;
+		if ((sw < minW || sh < minH) && !rule.allowUpscale) throw new ImageTooSmallError(requiredSize(minW, minH, ratio), kept);
+		let scale = 1;
+		if (rule.maxWidth != null) scale = Math.min(scale, rule.maxWidth / sw);
+		if (rule.maxHeight != null) scale = Math.min(scale, rule.maxHeight / sh);
+		if (rule.maxLongSide != null) scale = Math.min(scale, rule.maxLongSide / Math.max(sw, sh));
+		scale = Math.max(scale, minW / sw, minH / sh);
+		width = Math.max(1, Math.round(sw * scale));
+		height = Math.max(1, Math.round(sh * scale));
+	}
+	const unchanged = crop.sx === 0 && crop.sy === 0 && sw === W && sh === H && width === W && height === H;
+	return {
+		crop,
+		width,
+		height,
+		unchanged
+	};
+}
+/** The minimum as a full size: a ratio rule with only one minimum implies the other. */
+function requiredSize(minW, minH, ratio) {
+	if (ratio == null) return {
+		width: minW,
+		height: minH
+	};
+	return {
+		width: Math.max(minW, Math.ceil(minH * ratio)),
+		height: Math.max(minH, Math.ceil(minW / ratio))
+	};
+}
+const OUTPUT_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp"
+];
+/**
+* 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" });
+*/
+async function prepareImage(file, rule, options = {}) {
+	checkImageRule(rule);
+	requireBrowserImages("prepareImage");
+	const sourceType = file.type && OUTPUT_TYPES.includes(file.type) ? file.type : "image/png";
+	const type = options.type ?? sourceType;
+	const quality = options.quality ?? (type === "image/png" ? void 0 : .9);
+	const bitmap = await createImageBitmap(file);
+	try {
+		const plan = planImageFit({
+			width: bitmap.width,
+			height: bitmap.height
+		}, rule);
+		if (plan.unchanged && type === file.type) return file instanceof File ? file : new File([file], outputName(file, type), { type });
+		const blob = await drawCrop(bitmap, plan.crop, plan.width, plan.height, type, quality, "prepareImage");
+		return new File([blob], outputName(file, type), { type });
+	} finally {
+		bitmap.close?.();
+	}
+}
 
 //#endregion
 //#region src/core/upload.ts
@@ -1971,5 +2155,5 @@ function useBasketReport(options) {
 }
 
 //#endregion
-export { DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, 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, PromotionRuleSet, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, ShopwaveApiError, UPLOAD_KINDS, UPLOAD_PREFIXES, apiDelete, apiGet, apiRequest, 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 { DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, ImageRuleError, ImageTooSmallError, 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, PromotionRuleSet, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_LOOKUPS, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, ShopwaveApiError, UPLOAD_KINDS, UPLOAD_PREFIXES, apiDelete, apiGet, apiRequest, 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.js.map