react-shopwave-connect 0.1.2 → 0.3.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<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 apiDelete(path: string, options?: RequestOptions): Promise<void>;
+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[]`.
@@ -343,21 +409,45 @@ declare function fetchReport(query: ReportQueryMap, options?: RequestOptions): P
 //#endregion
 //#region src/core/session.d.ts
 /**
- * Ends the current server session.
+ * Login status returned by the app's `/api/session` route. It deliberately
+ * never contains tokens — those stay in the encrypted httpOnly cookie.
+ */
+interface SessionStatus {
+  loggedIn: boolean;
+  /** Access-token expiry (epoch ms), when known. */
+  expiresAt?: number;
+}
+/**
+ * Reads the current login status from `GET /api/session`.
+ *
+ * Works with the new `react-shopwave-connect/next` session route
+ * (`{ loggedIn }`) and with older routes that returned the raw session
+ * (`{ token: {...} }`) — in that case only a boolean is surfaced.
+ */
+declare function fetchSession(options?: RequestOptions): Promise<SessionStatus>;
+/**
+ * Path that starts a login and returns to `returnTo` afterwards.
+ * Navigate the browser to it (`window.location.href = loginPath(...)`).
+ */
+declare function loginPath(returnTo?: string, authPath?: string): string;
+/** Path that logs out of the app and the Shopwave auth server. */
+declare function logoutPath(authPath?: string): string;
+/**
+ * Ends the current server session (no redirect).
  *
- * This is the framework-agnostic half of the original `useLogout` hook. The
- * Next.js-specific redirect logic (router.push to the auth server logout URL,
- * built from server actions) is intentionally NOT included here because it is
- * tied to `next/navigation` and `'use server'` actions — see the README.
+ * Prefer navigating to {@link logoutPath} when using
+ * `react-shopwave-connect/next`: it also signs the user out of the auth server.
  */
 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}`.
@@ -376,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,
@@ -385,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;
@@ -488,10 +701,20 @@ declare function buildConsumerMap(consumers: Consumer[] | null | undefined): {
  * 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;
 }
 /**
@@ -503,6 +726,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
@@ -600,6 +825,17 @@ declare function useSubmit<R = any>(options?: RequestOptions): MutationState<R |
  */
 declare function useLogout(options?: RequestOptions): MutationState<void, []>;
 //#endregion
+//#region src/hooks/useSession.d.ts
+/**
+ * Current login status (`{ loggedIn, expiresAt }`) from `GET /api/session`.
+ * Tokens are never exposed to the browser.
+ *
+ * @example
+ * const { data: session, loading } = useSession();
+ * if (!loading && !session?.loggedIn) window.location.href = loginPath(location.pathname);
+ */
+declare function useSession(options?: RequestOptions): QueryState<SessionStatus>;
+//#endregion
 //#region src/hooks/useBasketReport.d.ts
 interface UseBasketReportReturn {
   rows: BasketReportRow[];
@@ -620,5 +856,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, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UseBasketReportReturn, apiDelete, apiGet, apiResponse, apiSend, buildBasketReportQuery, buildConsumerMap, collectConsumerIds, collectProductIds, combineBasketRows, computeBasketSummary, deleteEntity, fetchCategories, fetchConsumers, fetchEmployees, fetchProducts, fetchProductsMap, fetchPromotions, fetchReport, fetchStores, formatDateForQuery, getApiErrors, logout, parseBasketReportData, rolesById, submitEntity, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useProduct, usePromotion, useReport, useStore, useSubmit };
+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, MutationState, ParsedBasket, Product, ProductInstance, ProductResponse, Promotion, PromotionResponse, PromotionRuleSet, QueryState, ReportData, ReportKey, ReportQuery, ReportQueryMap, ReportResponse, RequestOptions, SHOPWAVE_ENTITIES, Saved, SessionStatus, ShopwaveApiError, ShopwaveErrorMap, Store, StoreResponse, SubmitEntityArgs, SubmitEntityResponse, SuccessMessage, UseBasketReportReturn, 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, useBasketReport, useCategory, useConsumer, useDelete, useEmployee, useLogout, useProduct, usePromotion, useReport, useSession, useStore, useSubmit, withToken };
 //# sourceMappingURL=index.d.cts.map