react-shopwave-connect 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -34,19 +34,24 @@ interface apiResponse {
 /**
  * Per-call configuration shared by every core API function.
  *
- * Nothing here is React-specific. By accepting these options per call, the
- * core layer works in the browser/Next (relative `/api/...` URLs, the default)
- * AND in Node / CLI / Vue / Angular by passing an absolute `baseUrl`, an auth
- * `token`, and/or a custom `fetch` implementation.
+ * Nothing here is React-specific. In the browser/Next leave `baseUrl` empty to
+ * call the app's own `/api/...` routes (which hold the session). From Node, a
+ * CLI or tests, pass an absolute `baseUrl` pointing at such an app plus a
+ * `token`.
  */
 interface RequestOptions {
   /**
    * Prefixed in front of every request path. Leave undefined in the browser to
-   * use relative URLs (e.g. `/api/products`). In Node/CLI pass something like
-   * `https://api.shopwave.com`.
+   * use relative URLs (e.g. `/api/products`). From Node pass the app origin,
+   * e.g. `http://localhost:3000`.
    */
   baseUrl?: string;
-  /** OAuth/session token forwarded in the `extras.token` header. */
+  /**
+   * Shopwave OAuth access token. Sent as `Authorization: OAuth <token>` on every
+   * request (GET, POST, PUT and DELETE alike). A value that already starts with
+   * a scheme (`OAuth …` / `Bearer …`) is sent as-is. Leave unset in the browser:
+   * the app's routes use the session cookie.
+   */
   token?: string;
   /**
    * Custom fetch implementation. Defaults to the global `fetch`. Useful for
@@ -58,24 +63,79 @@ interface RequestOptions {
 }
 /** The Shopwave API ships request metadata inside a single `extras` header. */
 type Extras = Record<string, unknown>;
+/** Options with `token` filled in from a legacy per-call `params.token`, unless `options.token` is set. */
+declare function withToken(options: RequestOptions, token: string | undefined): RequestOptions;
+/** `Authorization` header value for a token (`OAuth <token>` unless it already has a scheme). */
+declare function authorizationFor(token: string): string;
+/**
+ * Low-level request: resolves `{ status, body }` for 2xx responses and throws
+ * {@link ShopwaveApiError} otherwise. `init.headers` are merged over the
+ * standard ones (Accept + Authorization).
+ */
+declare function apiRequest(path: string, init: RequestInit, options?: RequestOptions): Promise<{
+  status: number;
+  body: unknown;
+}>;
 /**
  * Returns a JSON string of API errors if the response carries any, otherwise
- * `null`. Mirrors the original `!responseJson.api.message.errors` checks.
+ * `null`. Kept for backwards compatibility; prefer `ShopwaveApiError`.
  */
 declare function getApiErrors(api?: apiResponse): string | null;
 /**
- * GET helper. Sends request metadata via the `extras` header exactly like the
- * original hooks did, parses JSON, and returns the typed payload.
+ * GET helper. Sends request metadata via the `extras` header, parses JSON and
+ * returns the payload. Throws {@link ShopwaveApiError} for non-2xx responses.
  */
 declare function apiGet<T>(path: string, extras: Extras, options?: RequestOptions): Promise<T>;
 /**
- * JSON body helper for POST/PUT mutations.
+ * JSON body helper for POST/PUT mutations. Returns the parsed body (`null` for
+ * an empty one). Throws {@link ShopwaveApiError} for non-2xx responses.
  */
 declare function apiSend<T>(path: string, method: "POST" | "PUT", payload: unknown, options?: RequestOptions): Promise<T>;
 /**
- * DELETE helper.
+ * DELETE helper. Shopwave answers deletes with 205 and an empty body; if a body
+ * does come back and carries API errors, they are thrown. Returns the parsed
+ * body (`null` when empty).
  */
-declare function apiDelete(path: string, options?: RequestOptions): Promise<void>;
+declare function apiDelete(path: string, options?: RequestOptions): Promise<unknown>;
+//#endregion
+//#region src/core/errors.d.ts
+/** Map of Shopwave API errors as found in `api.message.errors`, keyed by error code. */
+type ShopwaveErrorMap = Record<string, Partial<ErrorMessage>>;
+/**
+ * Thrown by every `core` function when a request fails, either at the HTTP
+ * level (`status` is the HTTP status) or because the Shopwave response carried
+ * `api.message.errors` (then `status` is the HTTP status of that response,
+ * usually 200/201, and `errors` holds the API errors).
+ *
+ * Branch on `status` (e.g. `isUnauthorized` → send the user to log in) rather
+ * than parsing `message`.
+ */
+declare class ShopwaveApiError extends Error {
+  /** HTTP status of the response (0 when the request never got a response). */
+  readonly status: number;
+  /** Shopwave API errors, when the response carried any. */
+  readonly errors: ShopwaveErrorMap | null;
+  /** Parsed response body, when there was one. */
+  readonly body?: unknown;
+  constructor(status: number, message: string, details?: {
+    errors?: ShopwaveErrorMap | null;
+    body?: unknown;
+    cause?: unknown;
+  });
+  /** 401, or the Shopwave "token expired / invalid" error 908. */
+  get isUnauthorized(): boolean;
+  get isNotFound(): boolean;
+}
+/** The `api.message.errors` (or `api.message.error`) map of a Shopwave response, or `null` when there are none. */
+declare function getApiErrorMap(body: unknown): ShopwaveErrorMap | null;
+/**
+ * Builds a {@link ShopwaveApiError} for a response. Understands the Shopwave
+ * envelope (`api.message.errors`) and the `{ error, message }` bodies returned
+ * by the `react-shopwave-connect/next` routes.
+ */
+declare function toShopwaveApiError(status: number, body: unknown, fallback?: string): ShopwaveApiError;
+/** Throws a {@link ShopwaveApiError} when the response body carries API errors. */
+declare function assertNoApiErrors(body: unknown, status: number): void;
 //#endregion
 //#region src/core/category.d.ts
 interface Category {
@@ -96,7 +156,7 @@ interface FetchCategoriesParams {
   categoryIds?: Array<number>;
   /** Whether to include soft-deleted records. Defaults to `false`. */
   deleted?: boolean;
-  /** Token override (also accepted via `options.token`). */
+  /** @deprecated Pass `options.token` instead. Sent the same way (Authorization header). */
   token?: string;
 }
 /**
@@ -159,6 +219,8 @@ interface FetchEmployeesParams {
   employeeIds?: Array<number>;
   /** Whether to include soft-deleted records. Defaults to `false`. */
   deleted?: boolean;
+  /** @deprecated Pass `options.token` instead. Sent the same way (Authorization header). */
+  token?: string;
 }
 /**
  * Fetches employees. Returns the flattened `Employee[]`.
@@ -203,7 +265,7 @@ interface FetchProductsParams {
   storeId?: number;
   /** Whether to include soft-deleted records. Defaults to `false`. */
   deleted?: boolean;
-  /** Token override (also accepted via `options.token`). */
+  /** @deprecated Pass `options.token` instead. Sent the same way (Authorization header). */
   token?: string;
 }
 /**
@@ -265,7 +327,7 @@ interface FetchPromotionsParams {
   active?: boolean;
   /** Filter for expired promotions. */
   expired?: boolean;
-  /** Token override (also accepted via `options.token`). */
+  /** @deprecated Pass `options.token` instead. Sent the same way (Authorization header). */
   token?: string;
 }
 /**
@@ -297,8 +359,12 @@ interface StoreResponse {
   api: apiResponse;
 }
 interface FetchStoresParams {
+  /** Optional id filter. */
+  storeIds?: Array<number>;
   /** Whether to include soft-deleted records. Defaults to `false`. */
   deleted?: boolean;
+  /** @deprecated Pass `options.token` instead. Sent the same way (Authorization header). */
+  token?: string;
 }
 /**
  * Fetches stores. Returns the flattened `Store[]`.
@@ -376,10 +442,12 @@ declare function logout(options?: RequestOptions): Promise<void>;
 //#endregion
 //#region src/core/entity.d.ts
 /**
- * Generic CRUD-style mutations extracted from `useHandleDelete` /
- * `useHandleSubmit`. The original hooks also surfaced notistack snackbars; that
- * UI concern is deliberately left to the hooks/host layer so core stays
- * dependency-free.
+ * Low-level, untyped mutations: the caller supplies the route and payload.
+ *
+ * Prefer the typed functions in `./entities` (`saveProduct`, `deleteCategory`,
+ * …): they know each route, build the request envelope, check the response and
+ * return the saved entity with its id. Keep these for routes that have no typed
+ * function yet (e.g. `/api/merchant`).
  */
 /**
  * Deletes `/api/{resourcePath}/{entityId}`.
@@ -398,8 +466,9 @@ interface SubmitEntityResponse<R = any> {
   [key: string]: unknown;
 }
 /**
- * Sends a create/update mutation and returns the parsed `result` field
- * (matching the original `result.result` access).
+ * Sends a create/update mutation. Returns the response's `result` field when it
+ * has one (older app routes wrapped their answer that way), otherwise the whole
+ * parsed response body. Throws `ShopwaveApiError` on HTTP or API errors.
  */
 declare function submitEntity<R = any>({
   endpoint,
@@ -407,6 +476,128 @@ declare function submitEntity<R = any>({
   payload
 }: SubmitEntityArgs, options?: RequestOptions): Promise<R | undefined>;
 //#endregion
+//#region src/core/entities.d.ts
+/**
+ * How each Shopwave entity is addressed, shared by the client functions below
+ * and the server route handlers in `react-shopwave-connect/next`, so the two
+ * halves of the contract can't drift apart.
+ */
+interface EntityDefinition {
+  /** App route segment: `/api/<route>` and `/api/<route>/<id>`. */
+  route: string;
+  /** Key of the entity map in requests and responses (`{ products: { … } }`). */
+  collection: string;
+  /** Shopwave API path (`GET/POST/DELETE {apiUrl}/<upstream>`). */
+  upstream: string;
+  /** Header that filters reads by id (`productIds: 1,2`). */
+  idsHeader: string;
+  /** Header that names the record to delete (`productId: 1`). */
+  idHeader: string;
+  /** False for read-only entities (the API has no POST for them). */
+  writable: boolean;
+  /**
+   * How a delete is done upstream:
+   * - `"delete"`: `DELETE {apiUrl}/<upstream>` with the `idHeader` (205, empty body)
+   * - `"retire"`: the API has no DELETE; the record is retired by POSTing
+   *   `{ id, [retireField]: <now> }` (employees: `exitDate`, promotions: `endDate`)
+   * - `"none"`: can't be deleted
+   */
+  deleteMode: "delete" | "retire" | "none";
+  /** Date field set to "now" when `deleteMode` is `"retire"`. */
+  retireField?: string;
+}
+type EntityKind = "product" | "category" | "store" | "promotion" | "employee" | "consumer";
+/** Entities that can be created/updated through the API. */
+type WritableEntityKind = Exclude<EntityKind, "consumer">;
+/** Entities that can be deleted (or retired) through the API. */
+type DeletableEntityKind = Exclude<EntityKind, "consumer">;
+/**
+ * Addressing per entity, following the Shopwave API reference
+ * (https://developer.merchantstack.com/api-reference.html) and checked against
+ * the live API where noted:
+ * - category/product/store: GET filtered by `<x>Ids`, POST upsert, DELETE with `<x>Id` → 205.
+ * - promotion: no DELETE; "deleting" a promotion ends it by setting `endDate` to now.
+ * - employee: POST updates `roleId`, `joinedDate`, `exitDate` (names can't be
+ *   changed); no DELETE (live API: "Cannot DELETE /employee") → retired via `exitDate`.
+ * - consumer: read-only (`GET` with `ids`, comma-separated); live POST → 404.
+ */
+declare const SHOPWAVE_ENTITIES: Readonly<Record<EntityKind, EntityDefinition>>;
+interface EntityTypes {
+  product: Product;
+  category: Category;
+  store: Store;
+  promotion: Promotion;
+  employee: Employee;
+  consumer: Consumer;
+}
+/**
+ * What a save accepts: any subset of the entity's fields (plus extra API
+ * fields the type doesn't list). Include `id` to update; leave it out to create.
+ */
+type EntityInput<T> = Partial<T> & {
+  [field: string]: unknown;
+};
+/** A saved entity: always has its `id`. */
+type Saved<T> = T & {
+  id: number;
+};
+type EntityId = number | string;
+/**
+ * Creates or updates several entities of one kind in a single request and
+ * returns them as saved (with their ids), in the order given.
+ *
+ * The request is `{ <collection>: { "0": item0, "1": item1, … } }`. Shopwave
+ * answers 201 and echoes every entity under the ref it was sent with, so each
+ * result is matched back by ref. Throws {@link ShopwaveApiError} when the
+ * response carries `api.message.errors` or any ref is missing from it.
+ *
+ * The API's partial-success semantics for multi-entity saves haven't been
+ * confirmed yet; single saves (`saveProduct` etc.) are the tested path.
+ */
+declare function saveEntities<K extends WritableEntityKind>(kind: K, items: ReadonlyArray<EntityInput<EntityTypes[K]>>, options?: RequestOptions): Promise<Array<Saved<EntityTypes[K]>>>;
+/** Creates (no `id`) or updates (with `id`) one entity and returns it with its id. */
+declare function saveEntity<K extends WritableEntityKind>(kind: K, item: EntityInput<EntityTypes[K]>, options?: RequestOptions): Promise<Saved<EntityTypes[K]>>;
+/**
+ * Deletes one entity (a soft delete: it stays readable with `deleted: true`).
+ * Employees and promotions can't be deleted in Shopwave; for them the route
+ * sets `exitDate` / `endDate` to now instead (see `SHOPWAVE_ENTITIES`).
+ *
+ * Shopwave answers 205 with an empty body — also for ids that don't exist — so
+ * a resolved promise means "the API accepted the request", not "a record was
+ * deleted".
+ */
+declare function deleteEntityById(kind: DeletableEntityKind, id: EntityId, options?: RequestOptions): Promise<void>;
+interface FetchByIdParams {
+  /** Also return the record when it has been deleted. Defaults to `false`. */
+  deleted?: boolean;
+}
+/** Reads one entity by id, or `null` when there's no such (non-deleted) record. */
+declare function fetchEntityById<K extends EntityKind>(kind: K, id: EntityId, params?: FetchByIdParams, options?: RequestOptions): Promise<EntityTypes[K] | null>;
+declare const saveProduct: (product: EntityInput<Product>, options?: RequestOptions) => Promise<Saved<Product>>;
+declare const deleteProduct: (id: EntityId, options?: RequestOptions) => Promise<void>;
+declare const fetchProduct: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Product | null>;
+declare const saveCategory: (category: EntityInput<Category>, options?: RequestOptions) => Promise<Saved<Category>>;
+declare const deleteCategory: (id: EntityId, options?: RequestOptions) => Promise<void>;
+declare const fetchCategory: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Category | null>;
+declare const saveStore: (store: EntityInput<Store>, options?: RequestOptions) => Promise<Saved<Store>>;
+declare const deleteStore: (id: EntityId, options?: RequestOptions) => Promise<void>;
+declare const fetchStore: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Store | null>;
+declare const savePromotion: (promotion: EntityInput<Promotion>, options?: RequestOptions) => Promise<Saved<Promotion>>;
+/** Ends a promotion: Shopwave has no promotion DELETE, so this sets `endDate` to now. */
+declare const deletePromotion: (id: EntityId, options?: RequestOptions) => Promise<void>;
+declare const fetchPromotion: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Promotion | null>;
+/**
+ * Creates an employee, or updates one (with `id`). On update Shopwave only
+ * applies `roleId`, `joinedDate` and `exitDate` (and store roles); names and
+ * email can't be changed, and the echo only carries the updated fields — re-read
+ * with `fetchEmployee` if you need the stored record.
+ */
+declare const saveEmployee: (employee: EntityInput<Employee>, options?: RequestOptions) => Promise<Saved<Employee>>;
+/** Retires an employee: Shopwave has no employee DELETE, so this sets `exitDate` to now. */
+declare const deleteEmployee: (id: EntityId, options?: RequestOptions) => Promise<void>;
+declare const fetchEmployee: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Employee | null>;
+declare const fetchConsumer: (id: EntityId, params?: FetchByIdParams, options?: RequestOptions) => Promise<Consumer | null>;
+//#endregion
 //#region src/core/basket.d.ts
 interface BasketItem {
   productId: number;
@@ -505,15 +696,415 @@ declare function buildConsumerMap(consumers: Consumer[] | null | undefined): {
   [id: number]: Consumer;
 };
 //#endregion
+//#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
 //#region src/hooks/shared.d.ts
 /**
  * Consistent return shape for every auto-fetching ("query") hook.
  */
 interface QueryState<T> {
+  /**
+   * The latest data for the current params. Kept while a `refetch()` is in
+   * flight (and after a failed refetch), so lists don't blank out and flash a
+   * skeleton after every save. Reset to `null` when the params change.
+   */
   data: T | null;
+  /** True while there's no data to show yet (first load, or params changed). */
   loading: boolean;
+  /** True whenever a request is in flight, including background refetches. */
+  fetching: boolean;
   error: string | null;
-  /** Re-runs the underlying fetch. */
+  /** HTTP status of the last error (0 = no response), or `null`. */
+  errorStatus: number | null;
+  /** Re-runs the underlying fetch, keeping the current data visible meanwhile. */
   refetch: () => void;
 }
 /**
@@ -525,6 +1116,8 @@ interface MutationState<TData, TArgs extends any[]> {
   data: TData | null;
   loading: boolean;
   error: string | null;
+  /** HTTP status of the last error (0 = no response), or `null`. */
+  errorStatus: number | null;
 }
 //#endregion
 //#region src/hooks/useCategory.d.ts
@@ -633,6 +1226,59 @@ declare function useLogout(options?: RequestOptions): MutationState<void, []>;
  */
 declare function useSession(options?: RequestOptions): QueryState<SessionStatus>;
 //#endregion
+//#region src/hooks/useMerchant.d.ts
+/**
+ * The logged-in user's merchant, fetched on mount. `data` is `null` while
+ * loading or when the API has no merchant.
+ *
+ * @example
+ * const { data: merchant, loading, refetch } = useMerchant();
+ */
+declare function useMerchant(options?: RequestOptions): QueryState<Merchant | null>;
+/**
+ * Manually-triggered merchant update (see `updateMerchant`: the patch is merged
+ * over the current merchant by default). Resolves to the saved merchant, or
+ * `null` on error (then `error` / `errorStatus` are set).
+ *
+ * @example
+ * const { mutate: saveMerchant, loading: saving } = useUpdateMerchant();
+ * const saved = await saveMerchant({ vatNumber: "GB123" });
+ */
+declare function useUpdateMerchant(options?: UpdateMerchantOptions): MutationState<Merchant, [MerchantPatch]>;
+//#endregion
+//#region src/hooks/useUser.d.ts
+/**
+ * The logged-in user, fetched on mount. `errorStatus` is 401 when logged out.
+ *
+ * @example
+ * const { data: user } = useUser();
+ */
+declare function useUser(options?: RequestOptions & {
+  enabled?: boolean;
+}): QueryState<User | null>;
+//#endregion
+//#region src/hooks/useUploadImage.d.ts
+/**
+ * Manually-triggered image upload. Resolves to `{ id, url }`, or `null` on
+ * error (then `error` / `errorStatus` are set).
+ *
+ * @example
+ * const { mutate: upload, loading: uploading } = useUploadImage();
+ * const image = await upload(file, { kind: "merchant" });
+ */
+declare function useUploadImage(options?: RequestOptions): MutationState<UploadedImage, [Blob, UploadImageParams]>;
+/**
+ * Manually-triggered upload for a merchant image slot (`receipt`, `square`,
+ * `featured`): fits the image to the slot's exact size, uploads it with the
+ * slot's kind, and resolves to `{ id, url }`. Put `id` into `imageIds` with
+ * `setMerchantImage`.
+ *
+ * @example
+ * const { mutate: upload } = useUploadMerchantImage();
+ * const image = await upload(file, "square");
+ */
+declare function useUploadMerchantImage(options?: UploadMerchantImageOptions): MutationState<UploadedImage, [Blob, MerchantImageSlot]>;
+//#endregion
 //#region src/hooks/useBasketReport.d.ts
 interface UseBasketReportReturn {
   rows: BasketReportRow[];
@@ -653,5 +1299,5 @@ interface UseBasketReportReturn {
  */
 declare function useBasketReport(options?: RequestOptions): UseBasketReportReturn;
 //#endregion
-export { Basket, BasketFilters, BasketItem, BasketPagination, BasketReportRow, BasketSummary, Category, CategoryResponse, CombineBasketRowsParams, Consumer, ConsumerResponse, DEFAULT_BASKET_FILTERS, DEFAULT_PAGINATION, Employee, EmployeeResponse, ErrorMessage, Extras, FetchCategoriesParams, FetchEmployeesParams, FetchProductsParams, FetchPromotionsParams, FetchStoresParams, MessageInfo, MutationState, ParsedBasket, Product, ProductInstance, ProductResponse, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RequestOptions, SessionStatus, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UseBasketReportReturn, apiDelete, apiGet, apiResponse, apiSend, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, deleteEntity, fetchCategories, fetchConsumers, fetchEmployees, fetchProducts, fetchProductsMap, fetchPromotions, fetchReport, fetchSession, fetchStores, formatDateForQuery, getApiErrors, loginPath, logout, logoutPath, parseBasketReportData, rolesById, submitEntity, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useProduct, usePromotion, useReport, useSession, useStore, useSubmit };
+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, MutationState, ParsedBasket, Product, ProductInstance, ProductResponse, Promotion, PromotionResponse, PromotionRuleSet, QueryState, 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, 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, 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, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser, validateMerchant, withToken };
 //# sourceMappingURL=index.d.cts.map