react-shopwave-connect 0.3.0 → 0.4.0

package/dist/core/index.d.ts

@@ -696,5 +696,395 @@ declare function buildConsumerMap(consumers: Consumer[] | null | undefined): {
   [id: number]: Consumer;
 };
 //#endregion
-export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, DeletableEntityKind, Employee, EmployeeResponse, EntityDefinition, EntityId, EntityInput, EntityKind, EntityTypes, ErrorMessage, Extras, FetchByIdParams, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, MessageInfo, ParsedBasket, Product, ProductInstance, ProductResponse, Promotion, PromotionResponse, PromotionRuleSet, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RequestOptions, SHOPWAVE_ENTITIES, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, WritableEntityKind, apiDelete, apiGet, apiRequest, apiResponse, apiSend, assertNoApiErrors, authorizationFor, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, deleteCategory, deleteEmployee, deleteEntity, deleteEntityById, deleteProduct, deletePromotion, deleteStore, fetchCategories, fetchCategory, fetchConsumer, fetchConsumers, fetchEmployee, fetchEmployees, fetchEntityById, fetchProduct, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, formatDateForQuery, getApiErrorMap, getApiErrors, loginPath, logout, logoutPath, parseBasketReportData, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, submitEntity, toShopwaveApiError, withToken };
+//#region src/core/resources.d.ts
+/**
+ * Singleton resources (one per logged-in user) and the uploader.
+ *
+ * Like `SHOPWAVE_ENTITIES`, this table is shared by the client functions
+ * (`fetchMerchant`, `fetchUser`, `uploadImage`, …) and the server route
+ * handlers in `react-shopwave-connect/next`, so the two halves of the contract
+ * can't drift apart. These aren't in `SHOPWAVE_ENTITIES` because they aren't
+ * keyed collections: `GET /merchant` answers `{ merchant: {…} }`, not a map by id.
+ */
+interface ResourceDefinition {
+  /** App route: `/api/<route>`. */
+  route: string;
+  /** Key of the object in requests and responses (`{ merchant: {…} }`). */
+  key: string;
+  /** Shopwave API path. */
+  upstream: string;
+  /** False for read-only resources. */
+  writable: boolean;
+}
+type ResourceKind = "merchant" | "user";
+/**
+ * - merchant: `GET /merchant`; `POST /merchant` with `{ merchant: { id, … } }`
+ *   updates it (without an `id` the API would create a second merchant, so the
+ *   route requires one).
+ * - user: `GET /user` (read-only here; the API's `POST /user` invites users and
+ *   needs the admin scope).
+ */
+declare const SHOPWAVE_RESOURCES: Readonly<Record<ResourceKind, ResourceDefinition>>;
+/**
+ * What an upload is for. Sent to Shopwave as the `contentType` header of
+ * `PUT /uploader`. `merchant` is for the receipt and square logos (stored
+ * under `…/merchant/<id>/logo/`), `merchantFeature` for the featured image.
+ * The API spells two of its values `applicaionLogo` / `applicaionImages`; use
+ * the correctly spelt names here and the server maps them.
+ */
+type UploadKind = "merchant" | "merchantFeature" | "product" | "user" | "applicationLogo" | "applicationImages";
+/** `UploadKind` → the API's `contentType` value. */
+declare const UPLOAD_KINDS: Readonly<Record<UploadKind, string>>;
+/** How uploads are addressed (app route and Shopwave uploader). */
+declare const SHOPWAVE_UPLOAD: Readonly<{
+  /** App route: `POST /api/<route>` (multipart `file` + `kind`). */
+  route: "upload";
+  /** Shopwave path: `PUT {apiUrl}/uploader` (multipart `file`). */
+  upstream: "uploader";
+  /** Header that carries the upload kind upstream. */
+  kindHeader: "contentType";
+  /** Multipart field name for the file, on both sides. */
+  fileField: "file";
+  /** Multipart field name for the kind in the app request. */
+  kindField: "kind";
+}>;
+declare function isUploadKind(value: unknown): value is UploadKind;
+//#endregion
+//#region src/core/imageFit.d.ts
+/**
+ * Browser helpers for getting an image to an exact pixel 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.
+ */
+/** Source rectangle to draw so the image covers `dstWidth × dstHeight` (centre crop, no stretching). */
+interface CropRect {
+  sx: number;
+  sy: number;
+  sw: number;
+  sh: number;
+}
+/**
+ * The centred part of a `srcWidth × srcHeight` image with the aspect ratio of
+ * `dstWidth × dstHeight` (like CSS `object-fit: cover`).
+ */
+declare function coverCrop(srcWidth: number, srcHeight: number, dstWidth: number, dstHeight: number): CropRect;
+interface ImageSize {
+  width: number;
+  height: number;
+}
+/** Reads an image file's pixel size (browser only). */
+declare function readImageSize(file: Blob): Promise<ImageSize>;
+interface FitImageOptions {
+  /** Output type. Default `"image/png"`. */
+  type?: "image/png" | "image/jpeg" | "image/webp";
+  /** 0–1, for JPEG/WebP. */
+  quality?: number;
+  /** Return the file untouched when it's already the right size and type. Default true. */
+  keepIfExact?: boolean;
+}
+/**
+ * Returns the image at exactly `width × height`: scaled and centre-cropped
+ * (never stretched). Browser only. The result is a `File` named like the
+ * input, with the output type's extension.
+ */
+declare function fitImageToSize(file: Blob, width: number, height: number, options?: FitImageOptions): 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;
+  /** File name to send when `file` is a Blob without one. Defaults to `File.name`, else `"upload"`. */
+  fileName?: string;
+}
+interface UploadedImage {
+  /** The generated file name (products store it in `images`). */
+  id: string;
+  /** Public HTTPS URL of the file (see {@link getImageUrl}). */
+  url: string;
+  /** The URL exactly as the API returned it (`http://static.merchantstack.com/images/…`). */
+  path: string;
+}
+/**
+ * HTTPS host that serves the Shopwave CDN's images. The API returns
+ * `http://static.merchantstack.com/images/…`, which has no HTTPS endpoint
+ * (checked Sep 2026), so pages served over HTTPS can't show it.
+ */
+declare const SHOPWAVE_IMAGE_BASE_URL = "https://s3-eu-west-1.amazonaws.com/static.merchantstack.com/images";
+/**
+ * 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`.
+ * Other absolute URLs are returned unchanged; empty input gives `""`.
+ */
+declare function getImageUrl(path: string | null | undefined, base?: string): string;
+/**
+ * Uploads one image to the Shopwave CDN through the app's `/api/upload` route
+ * (`createShopwaveApi(...).upload()`), and returns its id and URL.
+ *
+ * The file only lands on the CDN (under `…/images/<kind>/<merchantId>/…`); a
+ * record has to point at it to use it. Live API (Sep 2026): the upload answers
+ * 201 `{ fileName, path }`.
+ */
+declare function uploadImage(file: Blob, params: UploadImageParams, options?: RequestOptions): Promise<UploadedImage>;
+//#endregion
+//#region src/core/merchantImages.d.ts
+/**
+ * Merchant images, as adminV1 saves them and adminV2 reads them:
+ *
+ * ```
+ * { logo: { receipt: "<file>", square: "<file>" }, feature: ["<file>"] }
+ * ```
+ *
+ * - **Writes** take the uploader's `fileName` (`<hash>.png`), not a URL.
+ * - **Reads** return full URLs (`http://static.merchantstack.com/images/…`),
+ *   so a value read back must be turned into a file name before it's saved
+ *   again ({@link toStoredImageIds}; `updateMerchant` does this for you).
+ * - Sending `imageIds` replaces the whole stored object (`{}` clears it);
+ *   leaving it out keeps it.
+ * - The API builds each URL from the key, not from where the file is:
+ *   `logo.*` → `…/merchant/<id>/logo/<file>`, `feature` → `…/feature/<file>`.
+ *   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.
+ */
+interface MerchantImageIds {
+  logo?: {
+    receipt?: string | null;
+    square?: string | null;
+    [key: string]: string | null | undefined;
+  } | null;
+  feature?: string[] | null;
+  [key: string]: unknown;
+}
+/** The three image slots on the merchant settings page. */
+declare const MERCHANT_IMAGE_SLOT_KEYS: readonly ["receipt", "square", "featured"];
+type MerchantImageSlot = (typeof MERCHANT_IMAGE_SLOT_KEYS)[number];
+interface MerchantImageSlotDefinition {
+  /** Where it's stored: `logo.receipt`, `logo.square` or `feature[0]`. */
+  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. */
+  width: number;
+  height: number;
+}
+/**
+ * Where each slot lives, its upload kind and its exact size (from adminV1's
+ * merchant settings page).
+ */
+declare const MERCHANT_IMAGE_SLOTS: Readonly<Record<MerchantImageSlot, MerchantImageSlotDefinition>>;
+/**
+ * The file name in an image value: `"http://…/logo/abc.png"` → `"abc.png"`,
+ * `"abc.png"` → `"abc.png"`. Query strings and fragments are ignored.
+ * Returns `null` for empty or non-string values.
+ */
+declare function imageFileName(value: unknown): string | null;
+/** The stored value for a slot (a URL when read from the API; a file name right after an upload). */
+declare function getMerchantImage(imageIds: MerchantImageIds | null | undefined, slot: MerchantImageSlot): string | null;
+/**
+ * An HTTPS URL for a slot's stored image, or `""` when the slot is empty or
+ * holds only a file name (a fresh upload not yet saved; use the upload's `url`).
+ */
+declare function getMerchantImageUrl(imageIds: MerchantImageIds | null | undefined, slot: MerchantImageSlot, base?: string): string;
+/**
+ * Returns a copy of `imageIds` with one slot set to `fileName` (or cleared
+ * with `null`). Other slots and unknown keys are kept; an empty `logo` or
+ * `feature` is removed.
+ */
+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
+ * are dropped. No images gives `{}`.
+ */
+declare function toStoredImageIds(imageIds: unknown): MerchantImageIds;
+interface UploadMerchantImageOptions extends RequestOptions {
+  /**
+   * Scale and centre-crop the image to the slot's exact size before upload
+   * (browser only). Default true. With `false` the file is sent as-is.
+   */
+  fit?: boolean;
+  /** Output type and quality when fitting. Default PNG. */
+  fitOptions?: FitImageOptions;
+}
+/**
+ * Uploads an image for a merchant slot: fits it to the slot's size, uploads
+ * it with the slot's kind, and returns `{ id, url, path }`. Put `id` into
+ * `imageIds` with {@link setMerchantImage} and save with `updateMerchant`.
+ */
+declare function uploadMerchantImage(file: Blob, slot: MerchantImageSlot, options?: UploadMerchantImageOptions): Promise<UploadedImage>;
+//#endregion
+//#region src/core/merchant.d.ts
+/** A colour set: hex strings (`"#1a2b3c"`). */
+interface MerchantColourSet {
+  main?: string | null;
+  highlight?: string | null;
+  contrast?: string | null;
+  [key: string]: string | null | undefined;
+}
+/**
+ * Brand colours, as adminV1 saves them and adminV2 reads them
+ * (`colours.primary.main` is the logo background): `{ primary: { main,
+ * highlight, contrast } }`. `{}` when unset. Confirmed live, 30 Sep 2026.
+ */
+interface MerchantColours {
+  primary?: MerchantColourSet | null;
+  [key: string]: MerchantColourSet | null | undefined;
+}
+/** Colour keys inside `colours.primary`, in display order. */
+declare const MERCHANT_COLOUR_KEYS: readonly ["main", "highlight", "contrast"];
+type MerchantColourKey = (typeof MERCHANT_COLOUR_KEYS)[number];
+/**
+ * Web and social links, as adminV1 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.
+ */
+interface MerchantLinks {
+  website?: {
+    home?: string | null;
+    [key: string]: string | null | undefined;
+  } | null;
+  social?: {
+    twitter?: string | null;
+    facebook?: string | null;
+    instagram?: string | null;
+    [key: string]: string | null | undefined;
+  } | null;
+  [key: string]: unknown;
+}
+/** Flat link fields a form edits, in display order. */
+declare const MERCHANT_LINK_KEYS: readonly ["website", "twitter", "facebook", "instagram"];
+type MerchantLinkKey = (typeof MERCHANT_LINK_KEYS)[number];
+/** Where each flat link field lives in `merchant.links`. */
+declare const MERCHANT_LINK_PATHS: Readonly<Record<MerchantLinkKey, readonly [string, string]>>;
+/**
+ * Reads `merchant.links` as flat fields (`{ website, twitter, facebook,
+ * instagram }`), whatever shape it was saved in:
+ * - the nested shape adminV1 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).
+ * Empty values are dropped.
+ */
+declare function merchantLinksToForm(links: unknown): Partial<Record<MerchantLinkKey, string>>;
+/**
+ * Builds the stored `links` object from flat fields. Empty values are left
+ * 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. */
+declare function normalizeMerchantLinks(links: unknown): MerchantLinks;
+interface Merchant {
+  id: number;
+  name: string;
+  description?: string | null;
+  /** Company registration number. */
+  companyNumber?: string | null;
+  vatNumber?: string | null;
+  categoryId?: number | null;
+  estAnnualRevenue?: number | string | null;
+  note?: string | null;
+  links?: MerchantLinks | null;
+  colours?: MerchantColours | null;
+  imageIds?: MerchantImageIds | null;
+  createdDate?: string;
+  modifiedDate?: string;
+  /** Other fields the API returns are kept as-is. */
+  [field: string]: unknown;
+}
+interface MerchantResponse {
+  merchant: Merchant;
+  api: apiResponse;
+}
+/** What `updateMerchant` accepts: any subset of the merchant's fields. */
+type MerchantPatch = Partial<Merchant> & {
+  [field: string]: unknown;
+};
+/**
+ * Object fields of the merchant. The API keeps one you leave out, and
+ * replaces it as a whole when you send it.
+ */
+declare const MERCHANT_OBJECT_FIELDS: ReadonlyArray<string>;
+/** Fields the API sets itself; `updateMerchant` never sends them back. */
+declare const MERCHANT_READ_ONLY_FIELDS: ReadonlyArray<string>;
+/**
+ * Longest values the API stores. Longer values are cut off silently
+ * (live API, Sep 2026), so `updateMerchant` rejects them instead.
+ * `vatNumber` fits a UK VAT number without the `GB` prefix.
+ */
+declare const MERCHANT_FIELD_MAX_LENGTH: Readonly<Record<string, number>>;
+/** Returns `"<field> is longer than <n> characters"` messages for over-long fields. */
+declare function validateMerchant(merchant: Record<string, unknown>): string[];
+/**
+ * Reads the logged-in user's merchant (a user has exactly one), or `null`
+ * when the API returns none.
+ */
+declare function fetchMerchant(options?: RequestOptions): Promise<Merchant | null>;
+interface UpdateMerchantOptions extends RequestOptions {
+  /**
+   * Read the merchant first and send the patch merged over it (the default).
+   * Scalar fields are merged over the stored ones. Object fields
+   * (`colours`, `links`, `imageIds`) are sent only when the patch has them,
+   * and then replace the stored one as a whole.
+   *
+   * Set to `false` to send only the patch (it must then include `id`). Only
+   * do that if you know the API keeps the fields you leave out.
+   */
+  merge?: boolean;
+}
+/**
+ * Updates the merchant and returns it as stored.
+ *
+ * Shopwave's `POST /merchant` replaces the whole record: a scalar field you
+ * leave out (`companyNumber`, `vatNumber`, `note`, …) is set to null, while
+ * an object field you leave out (`colours`, `links`, `imageIds`) is kept and
+ * one you send replaces the stored one; sending `{}` clears it (live API,
+ * Sep 2026). So by default the
+ * current merchant is read first and the patch is merged over it.
+ *
+ * `imageIds` is always sent as file names ({@link toStoredImageIds}), so you
+ * can pass back what you read. See `MerchantImageIds` for the shape.
+ *
+ * The API answers 205 with an empty body, so the merchant is read again after
+ * the save and that is what's returned (it shows exactly what was kept).
+ * Throws before sending when a value is longer than the API stores
+ * ({@link MERCHANT_FIELD_MAX_LENGTH}).
+ */
+declare function updateMerchant(patch: MerchantPatch, options?: UpdateMerchantOptions): Promise<Merchant>;
+//#endregion
+//#region src/core/user.d.ts
+/** The logged-in user's employee record (`GET /user` → `user.employee`). */
+interface UserEmployee {
+  merchantId?: number;
+  /** See `rolesById`. */
+  roleId?: number;
+  /** Store roles, keyed by store id. */
+  stores?: Record<string, unknown>;
+  [field: string]: unknown;
+}
+/** The logged-in user (`GET /user`). */
+interface User {
+  id: number;
+  firstName: string;
+  lastName: string;
+  email: string;
+  employee?: UserEmployee | null;
+  /** Documented in the API reference but not returned by the live API (Sep 2026). */
+  createdDate?: string;
+  /** Not returned by the live API (Sep 2026); use `fetchMerchant()`. */
+  merchant?: Merchant | null;
+  /** Other fields the API returns are kept as-is. */
+  [field: string]: unknown;
+}
+interface UserResponse {
+  user: User;
+  api: apiResponse;
+}
+/** Reads the logged-in user, or `null` when the API returns none. */
+declare function fetchUser(options?: RequestOptions): Promise<User | null>;
+//#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, 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, ParsedBasket, Product, ProductInstance, ProductResponse, Promotion, PromotionResponse, PromotionRuleSet, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RequestOptions, ResourceDefinition, ResourceKind, SHOPWAVE_ENTITIES, SHOPWAVE_IMAGE_BASE_URL, SHOPWAVE_RESOURCES, SHOPWAVE_UPLOAD, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UPLOAD_KINDS, UpdateMerchantOptions, UploadImageParams, UploadKind, UploadMerchantImageOptions, UploadedImage, 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, fetchProducts, fetchProductsMap, fetchPromotion, fetchPromotions, fetchReport, fetchSession, fetchStore, fetchStores, fetchUser, fitImageToSize, formatDateForQuery, getApiErrorMap, getApiErrors, getImageUrl, getMerchantImage, getMerchantImageUrl, imageFileName, isUploadKind, loginPath, logout, logoutPath, merchantLinksFromForm, merchantLinksToForm, normalizeMerchantLinks, parseBasketReportData, readImageSize, rolesById, saveCategory, saveEmployee, saveEntities, saveEntity, saveProduct, savePromotion, saveStore, setMerchantImage, submitEntity, toShopwaveApiError, toStoredImageIds, updateMerchant, uploadImage, uploadMerchantImage, validateMerchant, withToken };
 //# sourceMappingURL=index.d.ts.map