react-shopwave-connect 0.3.0 → 0.4.0

package/dist/hooks/index.d.cts

@@ -345,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.
@@ -451,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[];
@@ -471,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

package/dist/hooks/index.d.ts

@@ -345,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.
@@ -451,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[];
@@ -471,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.ts.map