react-shopwave-connect 0.1.2 → 0.3.0

package/dist/server/index.d.ts

@@ -0,0 +1,346 @@
+//#region src/server/token.d.ts
+/**
+ * Token model + helpers shared by every server-side integration.
+ *
+ * The Shopwave auth server returns (snake_case):
+ *   { access_token, refresh_token, token_type: "OAuth", expires_in: 43200 }
+ *
+ * We store a normalised, camelCase shape with an absolute expiry so any
+ * request can decide whether the token is still usable without extra state.
+ */
+interface ShopwaveToken {
+  accessToken: string;
+  /** Long-lived; the Shopwave server does not rotate it on refresh. */
+  refreshToken?: string;
+  /** Scheme used in the Authorization header. Shopwave uses "OAuth". */
+  tokenType: string;
+  /** Absolute expiry, epoch milliseconds. Undefined if the server didn't say. */
+  expiresAt?: number;
+}
+/** Raw token response from `POST {authServer}/oauth/token`. */
+interface ShopwaveTokenResponse {
+  access_token?: string;
+  refresh_token?: string;
+  token_type?: string;
+  expires_in?: number | string;
+  [key: string]: unknown;
+}
+/** Shopwave API error id meaning "access token expired / invalid". */
+declare const SHOPWAVE_TOKEN_EXPIRED_ERROR_ID = 908;
+/**
+ * Converts a token-endpoint response into a {@link ShopwaveToken}.
+ * Returns `null` when the response has no access token.
+ *
+ * @param previous  the token being refreshed; its refresh token is kept when
+ *                  the server doesn't send a new one.
+ */
+declare function tokenFromResponse(response: ShopwaveTokenResponse, previous?: ShopwaveToken, now?: number): ShopwaveToken | null;
+/**
+ * Reads a token from session storage. Accepts both the current shape and the
+ * legacy raw response that older apps (e.g. AdminUI ≤ 0.1) stored directly in
+ * the session, so existing sessions survive an upgrade.
+ */
+declare function normalizeStoredToken(raw: unknown): ShopwaveToken | null;
+/**
+ * True when the token has passed its expiry (minus `skewSeconds`).
+ * Tokens without a known expiry are treated as valid.
+ *
+ * Shopwave only issues a new access token once the old one has actually
+ * expired, so the default skew is 0 — refreshing early just returns the same
+ * token.
+ */
+declare function isTokenExpired(token: ShopwaveToken, {
+  skewSeconds,
+  now
+}?: {
+  skewSeconds?: number;
+  now?: number;
+}): boolean;
+/** `Authorization` header value, e.g. `OAuth 111ad…`. */
+declare function authorizationHeader(token: ShopwaveToken): string;
+/**
+ * True when a Shopwave API response means "your access token is no longer
+ * valid": HTTP 401, or the API error 908 in the response envelope.
+ * Use it to trigger a forced refresh + a single retry.
+ */
+declare function isExpiredTokenResponse(status: number, body?: unknown): boolean;
+//#endregion
+//#region src/server/oauth.d.ts
+/**
+ * Per-app OAuth settings. Everything that differs between Shopwave apps lives
+ * here; the flow itself is identical for all of them.
+ */
+interface ShopwaveOAuthConfig {
+  /** e.g. `https://secure.merchantstack.com` (no trailing slash needed). */
+  authServerUrl: string;
+  clientId: string;
+  /** Server-side only. Never expose it to the browser. */
+  clientSecret: string;
+  /**
+   * The callback URL registered for this client on the auth server, e.g.
+   * `https://admin.example.com/auth`. Must match exactly.
+   */
+  redirectUri: string;
+  /** Where the auth server sends the user after logout. Defaults to `redirectUri`. */
+  postLogoutRedirectUri?: string;
+  /** Defaults to `"application"`. */
+  scope?: string;
+  /** Defaults to `"online"`. */
+  accessType?: string;
+  /**
+   * Body encoding for `POST /oauth/token`. Defaults to standard
+   * `application/x-www-form-urlencoded`; `"multipart"` sends `FormData`.
+   */
+  tokenRequestFormat?: "urlencoded" | "multipart";
+  /** Auth-server paths. Defaults match Shopwave: `/login`, `/oauth/token`, `/logout`. */
+  endpoints?: {
+    login?: string;
+    token?: string;
+    logout?: string;
+  };
+  /** Custom fetch (tests, proxies). Defaults to global `fetch`. */
+  fetch?: typeof fetch;
+}
+interface ShopwaveOAuthClient {
+  readonly config: Readonly<ShopwaveOAuthConfig>;
+  /** URL to send the browser to so the user can sign in. */
+  buildLoginUrl(params?: {
+    state?: string;
+  }): string;
+  /** URL to send the browser to so the auth server ends its own session. */
+  buildLogoutUrl(params?: {
+    redirectUri?: string;
+  }): string;
+  /** Exchanges the `?code=` from the callback for tokens (server-to-server). */
+  exchangeCode(code: string): Promise<ShopwaveToken>;
+  /**
+   * Gets a fresh access token. Shopwave keeps the same refresh token, so the
+   * returned token carries the previous refresh token when none is sent back.
+   */
+  refreshToken(token: ShopwaveToken | string): Promise<ShopwaveToken>;
+}
+/** Throws a readable error when required settings are missing. */
+declare function assertOAuthConfig(config: Partial<ShopwaveOAuthConfig>): asserts config is ShopwaveOAuthConfig;
+/**
+ * Creates a framework-agnostic Shopwave OAuth client (authorization-code flow
+ * with a client secret — the Shopwave auth server does not support PKCE, so
+ * this must run on a server).
+ *
+ * Config is validated lazily on first use, so creating the client at module
+ * scope doesn't break builds where env vars aren't present.
+ */
+declare function createShopwaveOAuth(config: ShopwaveOAuthConfig): ShopwaveOAuthClient;
+//#endregion
+//#region src/server/returnTo.d.ts
+/**
+ * Helpers for the round trip through the auth server.
+ */
+/**
+ * Only allows same-origin relative paths ("/products?tab=1"). Anything that
+ * could send the user to another site after login — absolute URLs,
+ * protocol-relative "//evil.com", backslash tricks, control characters —
+ * falls back to `fallback`.
+ */
+declare function sanitizeReturnTo(value: unknown, fallback?: string): string;
+/** Random, URL-safe value for the OAuth `state` parameter (128 bits, hex). */
+declare function createState(): string;
+/** Constant-time string comparison for state values. */
+declare function safeEqual(a: string, b: string): boolean;
+//#endregion
+//#region src/server/errors.d.ts
+/**
+ * Error thrown by the server-side auth helpers.
+ *
+ * `code` is stable and safe to branch on; `status` is the HTTP status returned
+ * by the Shopwave auth server when there was one.
+ */
+type ShopwaveAuthErrorCode = "config_invalid" | "token_exchange_failed" | "token_refresh_failed" | "token_response_invalid" | "network_error";
+declare class ShopwaveAuthError extends Error {
+  readonly code: ShopwaveAuthErrorCode;
+  readonly status?: number;
+  /** Raw response body from the auth server, if any. Never contains our secret. */
+  readonly body?: string;
+  constructor(code: ShopwaveAuthErrorCode, message: string, details?: {
+    status?: number;
+    body?: string;
+    cause?: unknown;
+  });
+  /**
+   * True when the auth server rejected the grant itself (bad/expired code or
+   * refresh token) rather than failing for a transient reason. Callers should
+   * treat the user as logged out.
+   */
+  get isInvalidGrant(): boolean;
+}
+//#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>>;
+//#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