react-shopwave-connect 0.2.0 → 0.4.0

package/dist/server/index.d.ts

@@ -173,5 +173,262 @@ declare class ShopwaveAuthError extends Error {
   get isInvalidGrant(): boolean;
 }
 //#endregion
-export { SHOPWAVE_TOKEN_EXPIRED_ERROR_ID, ShopwaveAuthError, type ShopwaveAuthErrorCode, type ShopwaveOAuthClient, type ShopwaveOAuthConfig, type ShopwaveToken, type ShopwaveTokenResponse, assertOAuthConfig, authorizationHeader, createShopwaveOAuth, createState, isExpiredTokenResponse, isTokenExpired, normalizeStoredToken, safeEqual, sanitizeReturnTo, tokenFromResponse };
+//#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>>;
+//#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";
+}>;
+//#endregion
+//#region src/server/api.d.ts
+/**
+ * The OAuth token a caller sent with the request, without its scheme, or `null`.
+ *
+ * Reads, in order: `Authorization: OAuth|Bearer <token>` (what the SDK sends
+ * from 0.3), the `token` header (SDK ≤ 0.2 writes), and `extras.token`
+ * (SDK ≤ 0.2 reads).
+ */
+declare function readRequestToken(request: Request): string | null;
+/**
+ * `extras` keys that are never forwarded upstream (case-insensitive).
+ * `Content-Type` is allowed (SDK clients have always sent `application/json`
+ * on reads) but is replaced by the form content type on writes.
+ */
+declare const BLOCKED_EXTRAS: ReadonlySet<string>;
+/**
+ * Parses the `extras` request header into upstream headers.
+ * Returns `null` when the header isn't a JSON object.
+ */
+declare function parseExtras(raw: string | null, blocked?: ReadonlySet<string>): Record<string, string> | null;
+declare class RequestBodyError extends Error {}
+/**
+ * Normalises a write request body into the Shopwave envelope
+ * `{ <collection>: { <ref>: entity, … } }`.
+ *
+ * Accepts:
+ *  - the SDK ≥ 0.3 shape `{ <collection>: { "0": {...}, "1": {...} } }` (refs kept),
+ *  - the older AdminUI shapes `{ <collection>: { new: {...} } }` / `{ updated: {...} }`,
+ *  - a bare entity object `{ title: … }`.
+ *
+ * With `forcedId` (item routes) exactly one entity is allowed and its `id` is
+ * set from the URL.
+ */
+declare function normalizeWriteBody(def: Pick<EntityDefinition, "collection">, body: unknown, forcedId?: string): Record<string, Record<string, Record<string, unknown>>>;
+interface ShopwaveApiConfig {
+  /** Shopwave API base URL, e.g. `process.env.SHOPWAVE_API_SERVER_URL`. */
+  apiUrl: string;
+  /**
+   * `Authorization` header value for the logged-in user (`"OAuth <token>"`),
+   * or `null` when logged out. Called again with `forceRefresh: true` when the
+   * API reports the token expired.
+   */
+  getAuthorization?: (options?: {
+    forceRefresh?: boolean;
+  }) => Promise<string | null>;
+  /**
+   * Accept a token sent by the caller (`Authorization: OAuth <token>`, or the
+   * legacy `token` header / `extras.token`) instead of the session. The token
+   * is only forwarded to the Shopwave API, which validates it. Defaults to `true`
+   * (SDK integration tests, scripts and server-to-server calls rely on it).
+   */
+  allowRequestToken?: boolean;
+  /** `x-accept-version` sent upstream. Defaults to `"2.0"`. */
+  apiVersion?: string;
+  /** Custom fetch for the upstream call. */
+  fetch?: typeof fetch;
+  /** Override how an entity is addressed (e.g. a different id header). */
+  entities?: Partial<Record<EntityKind, Partial<EntityDefinition>>>;
+  /** Extra `extras` keys to drop, on top of {@link BLOCKED_EXTRAS}. */
+  blockedExtras?: string[];
+  /**
+   * Called when the upstream call throws (network error). Defaults to a
+   * `console.error` with the method and path only — never headers or tokens.
+   */
+  onError?: (error: unknown, context: {
+    method: string;
+    path: string;
+  }) => void;
+}
+interface ForwardInit {
+  /** HTTP method sent upstream. Defaults to `GET`. */
+  method?: string;
+  /** Shopwave API path, e.g. `"product"`. */
+  path: string;
+  /** Extra upstream headers; they win over `extras`. */
+  headers?: Record<string, string>;
+  /** Sent as the form field `postBody=<JSON>`. */
+  postBody?: unknown;
+  /** Sent as a multipart body (e.g. uploads). Ignored when `postBody` is set. */
+  formData?: FormData;
+  /** Forward the caller's `extras` header as upstream headers. Defaults to `true`. */
+  forwardExtras?: boolean;
+}
+/** Second argument Next.js (and similar) pass to dynamic route handlers. */
+interface RouteContext {
+  params?: Promise<Record<string, string | string[] | undefined>> | Record<string, string | string[] | undefined>;
+}
+type RouteHandler = (request: Request, context?: RouteContext) => Promise<Response>;
+interface CollectionHandlers {
+  /** List/filter via `extras` (e.g. `productIds`, `deleted`). */
+  GET: RouteHandler;
+  /** Create or update (Shopwave upserts: an `id` means update). */
+  POST: RouteHandler;
+  /** Same as POST (kept for older clients). */
+  PUT: RouteHandler;
+}
+interface ItemHandlers {
+  /** Read one record by the `[id]` route param. */
+  GET: RouteHandler;
+  /** Update the record at `[id]` (the id in the URL wins). */
+  PUT: RouteHandler;
+  /** Delete the record at `[id]`. Shopwave answers 205 with an empty body. */
+  DELETE: RouteHandler;
+}
+interface ResourceHandlers {
+  /** Read the resource (`GET {apiUrl}/<upstream>`). */
+  GET: RouteHandler;
+  /**
+   * Update it: body `{ <key>: { id, … } }` or the bare object. The `id` is
+   * required (without one Shopwave would create a new record). 405 for
+   * read-only resources.
+   */
+  PUT: RouteHandler;
+  /** Same as PUT. */
+  POST: RouteHandler;
+}
+interface UploadOptions {
+  /** Largest accepted file, in bytes. Defaults to 10 MB. */
+  maxBytes?: number;
+  /**
+   * Accepted MIME types. An entry ending in `/` is a prefix (`"image/"`).
+   * Defaults to `["image/"]`.
+   */
+  accept?: string[];
+}
+interface UploadHandlers {
+  /**
+   * Multipart `file` + `kind` (see `UploadKind`) → `PUT {apiUrl}/uploader`.
+   * Answers with Shopwave's reply (201 `{ fileName, path, api }`); 400 for a
+   * missing file or unknown kind, 413 when too large, 415 for other types.
+   */
+  POST: RouteHandler;
+}
+interface ShopwaveApiHandlers {
+  /** Calls the Shopwave API for this request (token, extras, refresh-retry) and returns its answer. */
+  forward(request: Request, init: ForwardInit): Promise<Response>;
+  /** Handlers for `app/api/<route>/route.ts`. */
+  collection(kind: EntityKind): CollectionHandlers;
+  /** Handlers for `app/api/<route>/[id]/route.ts`. */
+  item(kind: EntityKind, options?: {
+    param?: string;
+  }): ItemHandlers;
+  /** GET-only proxy for a Shopwave path (e.g. `"report"`). */
+  passthrough(path: string): {
+    GET: RouteHandler;
+  };
+  /** Handlers for a singleton resource: `app/api/merchant/route.ts`, `app/api/user/route.ts`. */
+  resource(kind: ResourceKind): ResourceHandlers;
+  /** Handler for `app/api/upload/route.ts`. */
+  upload(options?: UploadOptions): UploadHandlers;
+  /** The entity table in use (defaults merged with `config.entities`). */
+  entity(kind: EntityKind): EntityDefinition;
+}
+/** `YYYY-MM-DD HH:mm:ss` in UTC, the datetime format Shopwave writes use (e.g. promotions). */
+declare function shopwaveDateTime(date?: Date): string;
+declare function createShopwaveApiHandlers(config: ShopwaveApiConfig): ShopwaveApiHandlers;
+//#endregion
+export { BLOCKED_EXTRAS, type CollectionHandlers, type DeletableEntityKind, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, RequestBodyError, type ResourceDefinition, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, SHOPWAVE_TOKEN_EXPIRED_ERROR_ID, SHOPWAVE_UPLOAD, type ShopwaveApiConfig, type ShopwaveApiHandlers, ShopwaveAuthError, type ShopwaveAuthErrorCode, type ShopwaveOAuthClient, type ShopwaveOAuthConfig, type ShopwaveToken, type ShopwaveTokenResponse, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, type WritableEntityKind, assertOAuthConfig, authorizationHeader, createShopwaveApiHandlers, createShopwaveOAuth, createState, isExpiredTokenResponse, isTokenExpired, normalizeStoredToken, normalizeWriteBody, parseExtras, readRequestToken, safeEqual, sanitizeReturnTo, shopwaveDateTime, tokenFromResponse };
 //# sourceMappingURL=index.d.ts.map