react-shopwave-connect 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,618 @@
+//#region src/core/types.d.ts
+/**
+ * Shared API envelope types.
+ *
+ * Preserved exactly from the original `model/message.ts` so existing
+ * response handling keeps working.
+ */
+interface ErrorMessage {
+  id: number;
+  title: string;
+  details: string;
+  moreInfo: string;
+}
+interface SuccessMessage {
+  id: number;
+  title: string;
+  details: string;
+}
+interface MessageInfo {
+  errors: {
+    [key: number]: ErrorMessage;
+  };
+  success: {
+    [key: number]: SuccessMessage;
+  };
+}
+interface apiResponse {
+  message: MessageInfo;
+  codeBaseVersion: number;
+  executionTime_milliSeconds: number;
+}
+//#endregion
+//#region src/core/request.d.ts
+/**
+ * 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.
+ */
+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`.
+   */
+  baseUrl?: string;
+  /** OAuth/session token forwarded in the `extras.token` header. */
+  token?: string;
+  /**
+   * Custom fetch implementation. Defaults to the global `fetch`. Useful for
+   * Node < 18, testing, or injecting interceptors.
+   */
+  fetch?: typeof fetch;
+  /** Optional abort signal for cancellation (used by the hooks layer). */
+  signal?: AbortSignal;
+}
+/** The Shopwave API ships request metadata inside a single `extras` header. */
+type Extras = Record<string, unknown>;
+/**
+ * Returns a JSON string of API errors if the response carries any, otherwise
+ * `null`. Mirrors the original `!responseJson.api.message.errors` checks.
+ */
+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.
+ */
+declare function apiGet<T>(path: string, extras: Extras, options?: RequestOptions): Promise<T>;
+/**
+ * JSON body helper for POST/PUT mutations.
+ */
+declare function apiSend<T>(path: string, method: "POST" | "PUT", payload: unknown, options?: RequestOptions): Promise<T>;
+/**
+ * DELETE helper.
+ */
+declare function apiDelete(path: string, options?: RequestOptions): Promise<void>;
+//#endregion
+//#region src/core/category.d.ts
+interface Category {
+  id: number;
+  title: string;
+  parentId: number | null;
+  deleteDate: string;
+  activeDate: string;
+  type: number;
+}
+interface CategoryResponse {
+  categories: {
+    [key: number]: Category;
+  };
+  api: apiResponse;
+}
+interface FetchCategoriesParams {
+  categoryIds?: Array<number>;
+  /** Whether to include soft-deleted records. Defaults to `false`. */
+  deleted?: boolean;
+  /** Token override (also accepted via `options.token`). */
+  token?: string;
+}
+/**
+ * Fetches categories. Framework-agnostic: returns the flattened `Category[]`
+ * or throws on API errors.
+ */
+declare function fetchCategories(params?: FetchCategoriesParams, options?: RequestOptions): Promise<Category[]>;
+//#endregion
+//#region src/core/consumer.d.ts
+interface Consumer {
+  id: number;
+  activeCount: number;
+  firstName: string;
+  lastName: string;
+  email: string;
+}
+interface ConsumerResponse {
+  consumers: {
+    [key: number]: Consumer;
+  };
+  api: apiResponse;
+}
+/**
+ * Fetches consumers by id. Returns an empty array when no ids are supplied
+ * (the original hook short-circuited in that case).
+ */
+declare function fetchConsumers(consumerIds: number[] | null | undefined, options?: RequestOptions): Promise<Consumer[]>;
+//#endregion
+//#region src/core/employee.d.ts
+declare const rolesById: {
+  readonly "1": "Owner";
+  readonly "2": "Manager";
+  readonly "3": "Assistant";
+  readonly "4": "Guest";
+  readonly "5": "Assistant Manager";
+};
+interface Employee {
+  id: number;
+  firstName: string;
+  lastName: string;
+  email: string;
+  roleId: number;
+  joinedDate: string;
+  exitDate: string;
+  stores: {
+    [key: number]: {
+      id: number;
+      roleId: number;
+    };
+  };
+}
+interface EmployeeResponse {
+  employees: {
+    [key: number]: Employee;
+  };
+  api: apiResponse;
+}
+interface FetchEmployeesParams {
+  /** Optional id filter. Forwarded when provided. */
+  employeeIds?: Array<number>;
+  /** Whether to include soft-deleted records. Defaults to `false`. */
+  deleted?: boolean;
+}
+/**
+ * Fetches employees. Returns the flattened `Employee[]`.
+ */
+declare function fetchEmployees(params?: FetchEmployeesParams, options?: RequestOptions): Promise<Employee[]>;
+//#endregion
+//#region src/core/product.d.ts
+interface ProductInstance {
+  id: number;
+  price: string;
+  taxPercentage: string;
+  timestamp: string;
+  size: string;
+  name: string;
+  activeDate: string;
+  tags: string;
+}
+interface Product {
+  id: number;
+  barcode: string;
+  name: string;
+  details: string;
+  tags: string;
+  unit: number;
+  timestamp: string;
+  activeDate: string;
+  deleteDate: string;
+  images: Array<string>;
+  categories: Array<number>;
+  instances: {
+    [key: number]: ProductInstance;
+  };
+}
+interface ProductResponse {
+  products: {
+    [key: number]: Product;
+  };
+  api: apiResponse;
+}
+interface FetchProductsParams {
+  productIds?: Array<number>;
+  storeId?: number;
+  /** Whether to include soft-deleted records. Defaults to `false`. */
+  deleted?: boolean;
+  /** Token override (also accepted via `options.token`). */
+  token?: string;
+}
+/**
+ * Fetches products. Returns the flattened `Product[]`.
+ */
+declare function fetchProducts(params?: FetchProductsParams, options?: RequestOptions): Promise<Product[]>;
+/**
+ * Fetches products by id and returns them keyed by id, transparently batching
+ * the request (default 200 ids per call) to stay within API limits. Extracted
+ * from the original `useBasketReport` inline batching loop so it can be reused
+ * outside React.
+ */
+declare function fetchProductsMap(productIds: number[] | null | undefined, options?: RequestOptions, batchSize?: number): Promise<{
+  [id: number]: Product;
+}>;
+//#endregion
+//#region src/core/promotion.d.ts
+/** Promotion rule identifiers as stored by the Shopwave API. */
+declare enum PromotionRuleSet {
+  Percentage = "|%^/",
+  Combo = "&%</",
+  MealDeal = "&=^/",
+}
+interface Promotion {
+  id: number;
+  merchantId: number;
+  storeIds: number[];
+  categoryIds: {
+    [key: string]: number;
+  };
+  productIds: {
+    [key: string]: any;
+  };
+  title: string;
+  details: string | null;
+  terms: string | null;
+  startDate: string;
+  endDate: string;
+  daysAvailable: number[];
+  automatic: number;
+  rule: PromotionRuleSet;
+  x: number;
+  y: number | null;
+}
+interface PromotionResponse {
+  promotions: {
+    [key: number]: Promotion;
+  };
+  api: apiResponse;
+}
+interface FetchPromotionsParams {
+  /** Optional id filter. Forwarded when provided. */
+  promotionIds?: Array<number>;
+  /** Whether to include soft-deleted records. Defaults to `false`. */
+  deleted?: boolean;
+  /** Token override (also accepted via `options.token`). */
+  token?: string;
+}
+/**
+ * Fetches promotions. Returns the flattened `Promotion[]`.
+ */
+declare function fetchPromotions(params?: FetchPromotionsParams, options?: RequestOptions): Promise<Promotion[]>;
+//#endregion
+//#region src/core/store.d.ts
+interface Store {
+  id: number;
+  lat: number;
+  lng: number;
+  addressLine1: string;
+  addressLine2: string | null;
+  addressLine3: string;
+  phoneNumber: string;
+  city: string;
+  postcode: string;
+  countryId: number | null;
+  timezoneId: number | null;
+  storeDeleteDate: string | null;
+  email: string | null;
+  sandbox: boolean | null;
+}
+interface StoreResponse {
+  stores: {
+    [key: number]: Store;
+  };
+  api: apiResponse;
+}
+interface FetchStoresParams {
+  /** Whether to include soft-deleted records. Defaults to `false`. */
+  deleted?: boolean;
+}
+/**
+ * Fetches stores. Returns the flattened `Store[]`.
+ */
+declare function fetchStores(params?: FetchStoresParams, options?: RequestOptions): Promise<Store[]>;
+//#endregion
+//#region src/core/report.d.ts
+interface ReportKey {
+  name: string;
+  type: string;
+  item?: ReportKey[];
+}
+interface ReportData {
+  keys: ReportKey[];
+  data: any[][];
+}
+interface ReportResponse {
+  reports: {
+    [key: string]: ReportData;
+  };
+  api: apiResponse;
+}
+interface ReportQuery {
+  FROM: string;
+  WHERE?: {
+    AND?: string[];
+    OR?: string[];
+  };
+  SELECT?: string[];
+  LIMIT?: number;
+  OFFSET?: number;
+}
+interface ReportQueryMap {
+  [key: string]: ReportQuery;
+}
+/**
+ * Runs one or more report queries and returns the `reports` map keyed by query
+ * name. The query is JSON-encoded into the `extras.query` header, matching the
+ * original endpoint contract.
+ */
+declare function fetchReport(query: ReportQueryMap, options?: RequestOptions): Promise<ReportResponse["reports"]>;
+//#endregion
+//#region src/core/session.d.ts
+/**
+ * Ends the current server session.
+ *
+ * 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.
+ */
+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.
+ */
+/**
+ * Deletes `/api/{resourcePath}/{entityId}`.
+ */
+declare function deleteEntity(resourcePath: string, entityId: number | string, options?: RequestOptions): Promise<void>;
+interface SubmitEntityArgs {
+  /** Fully-resolved endpoint, e.g. `/api/products` or `/api/products/42`. */
+  endpoint: string;
+  /** Defaults to PUT when an `entityId` exists, otherwise POST. */
+  method?: "POST" | "PUT";
+  /** The request payload (already transformed by the caller). */
+  payload: unknown;
+}
+interface SubmitEntityResponse<R = any> {
+  result?: R;
+  [key: string]: unknown;
+}
+/**
+ * Sends a create/update mutation and returns the parsed `result` field
+ * (matching the original `result.result` access).
+ */
+declare function submitEntity<R = any>({
+  endpoint,
+  method,
+  payload
+}: SubmitEntityArgs, options?: RequestOptions): Promise<R | undefined>;
+//#endregion
+//#region src/core/basket.d.ts
+interface BasketItem {
+  productId: number;
+  productName: string;
+  quantity: number;
+  price: number;
+  tax: number;
+}
+interface Basket {
+  id: number;
+  name: string;
+  consumerId: number;
+  products: BasketItem[];
+  total: number;
+  taxTotal: number;
+  status: "pending" | "completed" | "cancelled";
+  completeDate: string;
+}
+interface BasketReportRow {
+  id: number;
+  basketId: number;
+  basketName: string;
+  consumerId: number;
+  consumerName: string;
+  consumerEmail: string;
+  products: BasketItem[];
+  basketTotal: number;
+  tax: number;
+  dateTime: string;
+  status: string;
+}
+interface BasketSummary {
+  totalBaskets: number;
+  totalRevenue: number;
+  totalTax: number;
+  uniqueConsumers: number;
+}
+interface BasketFilters {
+  search: string;
+  dateRange: {
+    start: Date | null;
+    end: Date | null;
+  };
+  consumerId: number | null;
+  status: "all" | "pending" | "completed" | "cancelled";
+}
+interface BasketPagination {
+  page: number;
+  pageSize: number;
+  total: number;
+}
+declare const DEFAULT_BASKET_FILTERS: BasketFilters;
+declare const DEFAULT_PAGINATION: BasketPagination;
+/** Intermediate shape produced by {@link parseBasketReportData}. */
+interface ParsedBasket {
+  id: number;
+  name: string;
+  consumerId: number;
+  products: BasketItem[];
+  total: number;
+  taxTotal: number;
+  status: "completed";
+  completeDate: string;
+}
+/** Formats a date as `YYYY-MM-DD HH:mm:ss` for the report query. */
+declare function formatDateForQuery(date: Date, isEndOfDay?: boolean): string;
+/** Builds the `Basket` report query from a set of filters. */
+declare function buildBasketReportQuery(filters: BasketFilters): ReportQueryMap;
+/** Flattens the raw report rows/keys into structured baskets. */
+declare function parseBasketReportData(reports: ReportResponse["reports"] | null | undefined): ParsedBasket[];
+/** Unique non-null consumer ids referenced by a set of baskets. */
+declare function collectConsumerIds(baskets: ParsedBasket[]): number[] | null;
+/** Unique product ids referenced by a set of baskets. */
+declare function collectProductIds(baskets: ParsedBasket[]): number[] | null;
+interface CombineBasketRowsParams {
+  baskets: ParsedBasket[];
+  consumerMap: {
+    [id: number]: Consumer;
+  };
+  productMap: {
+    [id: number]: Product;
+  };
+  search?: string;
+}
+/** Joins baskets with consumer + product lookups, applies search, sorts. */
+declare function combineBasketRows({
+  baskets,
+  consumerMap,
+  productMap,
+  search
+}: CombineBasketRowsParams): BasketReportRow[];
+/** Aggregate totals for a set of report rows. */
+declare function computeBasketSummary(rows: BasketReportRow[]): BasketSummary;
+/** Builds a consumer id → consumer lookup. */
+declare function buildConsumerMap(consumers: Consumer[] | null | undefined): {
+  [id: number]: Consumer;
+};
+//#endregion
+//#region src/hooks/shared.d.ts
+/**
+ * Consistent return shape for every auto-fetching ("query") hook.
+ */
+interface QueryState<T> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  /** Re-runs the underlying fetch. */
+  refetch: () => void;
+}
+/**
+ * Consistent return shape for manually-triggered ("mutation") hooks.
+ */
+interface MutationState<TData, TArgs extends any[]> {
+  /** Triggers the request. Resolves to the result, or `null` on error. */
+  mutate: (...args: TArgs) => Promise<TData | null>;
+  data: TData | null;
+  loading: boolean;
+  error: string | null;
+}
+//#endregion
+//#region src/hooks/useCategory.d.ts
+/**
+ * Auto-fetches categories on mount and whenever the params change.
+ * Manual reloads are available via `refetch` (replaces the old `reloadFlag`).
+ */
+declare function useCategory(params?: FetchCategoriesParams, options?: RequestOptions): QueryState<Category[]>;
+//#endregion
+//#region src/hooks/useConsumer.d.ts
+/**
+ * Auto-fetches consumers by id. Disabled (no request) until at least one id is
+ * supplied, mirroring the original early-return behaviour.
+ */
+declare function useConsumer(consumerIds: number[] | null, options?: RequestOptions): QueryState<Consumer[]>;
+//#endregion
+//#region src/hooks/useEmployee.d.ts
+/**
+ * Auto-fetches employees on mount and whenever the params change.
+ */
+declare function useEmployee(params?: FetchEmployeesParams, options?: RequestOptions): QueryState<Employee[]>;
+//#endregion
+//#region src/hooks/useProduct.d.ts
+/**
+ * Auto-fetches products on mount and whenever the params change.
+ */
+declare function useProduct(params?: FetchProductsParams, options?: RequestOptions): QueryState<Product[]>;
+//#endregion
+//#region src/hooks/usePromotion.d.ts
+/**
+ * Auto-fetches promotions on mount and whenever the params change.
+ * Manual reloads are available via `refetch`.
+ */
+declare function usePromotion(params?: FetchPromotionsParams, options?: RequestOptions): QueryState<Promotion[]>;
+//#endregion
+//#region src/hooks/useStore.d.ts
+/**
+ * Auto-fetches stores on mount. Manual reloads via `refetch`
+ * (replaces the old `reloadFlag` argument).
+ */
+declare function useStore(params?: FetchStoresParams, options?: RequestOptions): QueryState<Store[]>;
+//#endregion
+//#region src/hooks/useReport.d.ts
+/**
+ * Auto-fetches one or more reports. Disabled (no request) until a non-null
+ * query is supplied, mirroring the original early-return behaviour.
+ */
+declare function useReport(query: ReportQueryMap | null, options?: RequestOptions): QueryState<ReportResponse["reports"]>;
+//#endregion
+//#region src/hooks/useDelete.d.ts
+/**
+ * Manually-triggered delete. Returns `{ mutate, loading, error, data }`.
+ *
+ * Note: the original `useHandleDelete` surfaced notistack toasts. That UI
+ * concern is left to the host app — handle success/error from the returned
+ * state or the promise resolved by `mutate`.
+ *
+ * @example
+ * const { mutate, loading } = useDelete();
+ * await mutate("products", 42);
+ */
+declare function useDelete(options?: RequestOptions): MutationState<void, [resourcePath: string, entityId: number | string]>;
+//#endregion
+//#region src/hooks/useSubmit.d.ts
+/**
+ * Manually-triggered create/update. Returns `{ mutate, loading, error, data }`,
+ * where `data` is the API `result` payload.
+ *
+ * The original `useHandleSubmit` bundled validation, payload transformation and
+ * notistack toasts. Those are app concerns: resolve the endpoint/method/payload
+ * in your component and pass them in, then react to the returned state.
+ *
+ * @example
+ * const { mutate, loading } = useSubmit<Product>();
+ * const saved = await mutate({
+ *   endpoint: id ? `/api/products/${id}` : "/api/products",
+ *   method: id ? "PUT" : "POST",
+ *   payload,
+ * });
+ */
+declare function useSubmit<R = any>(options?: RequestOptions): MutationState<R | undefined, [args: SubmitEntityArgs]>;
+//#endregion
+//#region src/hooks/useLogout.d.ts
+/**
+ * Manually-triggered logout (ends the server session).
+ *
+ * This is framework-agnostic and does NOT redirect. The original `useLogout`
+ * also pushed the browser to the auth-server logout URL via `next/navigation`
+ * and `'use server'` actions; that part is Next-specific and stays in your app.
+ *
+ * @example
+ * const { mutate: doLogout } = useLogout();
+ * await doLogout();
+ * router.push(logoutUrl); // app-specific redirect
+ */
+declare function useLogout(options?: RequestOptions): MutationState<void, []>;
+//#endregion
+//#region src/hooks/useBasketReport.d.ts
+interface UseBasketReportReturn {
+  rows: BasketReportRow[];
+  summary: BasketSummary;
+  loading: boolean;
+  error: string | null;
+  filters: BasketFilters;
+  setFilters: (filters: Partial<BasketFilters>) => void;
+  pagination: BasketPagination;
+  setPagination: (page: number, pageSize: number) => void;
+  refresh: () => void;
+}
+/**
+ * Composite hook that orchestrates the report → consumers → products pipeline
+ * for the basket report screen. All the data-shaping logic now lives in the
+ * framework-agnostic `core/basket` helpers; this hook is the thin React glue
+ * (state, memoisation, effects) on top of them.
+ */
+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 };
+//# sourceMappingURL=index.d.cts.map