react-shopwave-connect 0.2.0 → 0.3.0

package/dist/server/index.d.cts

@@ -173,5 +173,174 @@ 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/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;
+  /** 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 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"`, `"user"`, `"merchant"`). */
+  passthrough(path: string): {
+    GET: RouteHandler;
+  };
+  /** 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 RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_TOKEN_EXPIRED_ERROR_ID, type ShopwaveApiConfig, type ShopwaveApiHandlers, ShopwaveAuthError, type ShopwaveAuthErrorCode, type ShopwaveOAuthClient, type ShopwaveOAuthConfig, type ShopwaveToken, type ShopwaveTokenResponse, type WritableEntityKind, assertOAuthConfig, authorizationHeader, createShopwaveApiHandlers, createShopwaveOAuth, createState, isExpiredTokenResponse, isTokenExpired, normalizeStoredToken, normalizeWriteBody, parseExtras, readRequestToken, safeEqual, sanitizeReturnTo, shopwaveDateTime, tokenFromResponse };
 //# sourceMappingURL=index.d.cts.map

package/dist/server/index.d.ts

@@ -173,5 +173,174 @@ 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/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;
+  /** 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 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"`, `"user"`, `"merchant"`). */
+  passthrough(path: string): {
+    GET: RouteHandler;
+  };
+  /** 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 RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_TOKEN_EXPIRED_ERROR_ID, type ShopwaveApiConfig, type ShopwaveApiHandlers, ShopwaveAuthError, type ShopwaveAuthErrorCode, type ShopwaveOAuthClient, type ShopwaveOAuthConfig, type ShopwaveToken, type ShopwaveTokenResponse, type WritableEntityKind, assertOAuthConfig, authorizationHeader, createShopwaveApiHandlers, createShopwaveOAuth, createState, isExpiredTokenResponse, isTokenExpired, normalizeStoredToken, normalizeWriteBody, parseExtras, readRequestToken, safeEqual, sanitizeReturnTo, shopwaveDateTime, tokenFromResponse };
 //# sourceMappingURL=index.d.ts.map