react-shopwave-connect 0.2.0 → 0.4.0

package/dist/hooks/index.d.cts

@@ -3,10 +3,20 @@
  * 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;
 }
 /**
@@ -18,6 +28,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/core/types.d.ts
@@ -56,19 +68,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
@@ -92,7 +109,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;
 }
 //#endregion
@@ -126,6 +143,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;
 }
 //#endregion
 //#region src/core/product.d.ts
@@ -160,7 +179,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;
 }
 //#endregion
@@ -203,7 +222,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;
 }
 //#endregion
@@ -225,8 +244,12 @@ interface Store {
   sandbox: boolean | null;
 }
 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;
 }
 //#endregion
 //#region src/core/report.d.ts
@@ -322,6 +345,181 @@ interface BasketPagination {
   total: number;
 }
 //#endregion
+//#region src/core/resources.d.ts
+/**
+ * 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";
+//#endregion
+//#region src/core/imageFit.d.ts
+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;
+}
+//#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;
+}
+//#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 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;
+}
+//#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;
+}
+/**
+ * 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;
+}
+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;
+}
+/** What `updateMerchant` accepts: any subset of the merchant's fields. */
+type MerchantPatch = Partial<Merchant> & {
+  [field: string]: unknown;
+};
+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;
+}
+//#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;
+}
+//#endregion
 //#region src/hooks/useCategory.d.ts
 /**
  * Auto-fetches categories on mount and whenever the params change.
@@ -428,6 +626,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[];
@@ -448,5 +699,5 @@ interface UseBasketReportReturn {
  */
 declare function useBasketReport(options?: RequestOptions): UseBasketReportReturn;
 //#endregion
-export { type MutationState, type QueryState, type UseBasketReportReturn, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useProduct, usePromotion, useReport, useSession, useStore, useSubmit };
+export { type MutationState, type QueryState, type UseBasketReportReturn, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useMerchant, useProduct, usePromotion, useReport, useSession, useStore, useSubmit, useUpdateMerchant, useUploadImage, useUploadMerchantImage, useUser };
 //# sourceMappingURL=index.d.cts.map