react-shopwave-connect 0.1.2 → 0.3.0

package/dist/next/index.d.ts

@@ -0,0 +1,423 @@
+import { IronSession } from "iron-session";
+
+//#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;
+}
+/** `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>;
+}
+//#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";
+/**
+ * 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;
+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;
+}
+//#endregion
+//#region src/core/session.d.ts
+/**
+ * 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;
+}
+//#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/next/index.d.ts
+interface ShopwaveSessionConfig {
+  /**
+   * Encrypts the session cookie. At least 32 characters. Pass a map such as
+   * `{ 2: newPassword, 1: oldPassword }` to rotate without logging users out.
+   */
+  password: string | Record<string, string>;
+  /** Defaults to `"shopwave_session"`. Use a different name per app on a shared domain. */
+  cookieName?: string;
+  /** Session lifetime in seconds. Defaults to iron-session's 14 days. */
+  ttl?: number;
+  /** Defaults to `true` in production, `false` otherwise (so http://localhost works). */
+  secure?: boolean;
+  /** Defaults to `"lax"`, which the OAuth redirect back to your app needs. */
+  sameSite?: "lax" | "strict" | "none";
+  domain?: string;
+}
+interface ShopwaveAuthConfig extends ShopwaveOAuthConfig {
+  session: ShopwaveSessionConfig;
+  /**
+   * Path where `handlers.auth` is mounted. It starts the login AND receives the
+   * callback, so it should be the path of `redirectUri`. Defaults to `"/auth"`.
+   */
+  authPath?: string;
+  /** Path where `handlers.logout` is mounted. Defaults to `${authPath}/logout`. */
+  logoutPath?: string;
+  /**
+   * Path where `handlers.session` is mounted. Always public, because it is how
+   * the browser finds out it is logged out. Defaults to `"/api/session"`.
+   */
+  sessionPath?: string;
+  /** Where users land after login when no `returnTo` was given. Defaults to `"/"`. */
+  defaultReturnTo?: string;
+  /**
+   * Reject callbacks whose `state` doesn't match the one we sent (login-CSRF
+   * protection). Defaults to `true`. Only turn off if the auth server does not
+   * echo `state` back.
+   */
+  requireState?: boolean;
+  /**
+   * Refresh this many seconds before expiry. Defaults to `0`, because the
+   * Shopwave server only issues a new access token once the old one expired.
+   */
+  refreshSkewSeconds?: number;
+  /** How long a started login stays valid, in seconds. Defaults to 600. */
+  loginTimeoutSeconds?: number;
+}
+/** What we keep in the encrypted cookie. Tokens never leave the server. */
+interface ShopwaveSessionData {
+  token?: ShopwaveToken | Record<string, unknown>;
+  pendingLogin?: {
+    state: string;
+    returnTo: string;
+    createdAt: number;
+  };
+}
+interface AuthContext {
+  accessToken: string;
+  /** Ready-to-use `Authorization` header value, e.g. `OAuth 111ad…`. */
+  authorization: string;
+  token: ShopwaveToken;
+}
+interface ProtectOptions {
+  /**
+   * Paths that don't need a login. A path matches itself and everything below
+   * it (`"/tools/tag-joiner"` covers `/tools/tag-joiner/x`). `"/"` matches only
+   * the root. The auth, logout and session paths are always public.
+   */
+  publicPaths?: string[];
+  /** Paths that get a 401 JSON response instead of a login redirect. Defaults to `["/api"]`. */
+  apiPaths?: string[];
+  /**
+   * Let API requests that carry their own token (`Authorization: OAuth <token>`,
+   * or the legacy `token` header / `extras.token`) through without a session
+   * cookie. The route handlers from {@link createShopwaveApi} forward that token
+   * to the Shopwave API, which validates it. Defaults to `false`.
+   */
+  allowRequestToken?: boolean;
+}
+interface ShopwaveAuth {
+  /** The underlying framework-agnostic OAuth client. */
+  readonly oauth: ShopwaveOAuthClient;
+  /** Route handlers to export from your app. */
+  readonly handlers: {
+    /** Mount at the redirect-URI path (e.g. `app/auth/route.ts`): `export const GET = auth.handlers.auth`. */
+    auth: (request: Request) => Promise<Response>;
+    /** Mount at `app/auth/logout/route.ts`: `export const GET = auth.handlers.logout`. */
+    logout: (request: Request) => Promise<Response>;
+    /** Mount at `app/api/session/route.ts`: `export const { GET, DELETE } = auth.handlers.session`. */
+    session: {
+      GET: (request?: Request) => Promise<Response>;
+      DELETE: (request?: Request) => Promise<Response>;
+    };
+  };
+  /** Login status for the current request. Never includes tokens. */
+  getStatus(): Promise<SessionStatus>;
+  /**
+   * A valid access token for the current user, refreshing it when expired
+   * (and saving the new one in the cookie when called from a route handler,
+   * server action or proxy). `null` when logged out or the refresh token was
+   * rejected. Pass `forceRefresh` after the API answered 401 / error 908.
+   */
+  getAccessToken(options?: {
+    forceRefresh?: boolean;
+  }): Promise<string | null>;
+  /** Same as `getAccessToken` but returns the whole token object. */
+  getToken(options?: {
+    forceRefresh?: boolean;
+  }): Promise<ShopwaveToken | null>;
+  /** `Authorization` header value (`"OAuth <token>"`), or `null` when logged out. */
+  getAuthorizationHeader(options?: {
+    forceRefresh?: boolean;
+  }): Promise<string | null>;
+  /** Wraps a route handler; responds 401 JSON when there's no valid session. */
+  withAuth<C = unknown>(handler: (request: Request, context: C, auth: AuthContext) => Response | Promise<Response>): (request: Request, context: C) => Promise<Response>;
+  /**
+   * For `proxy.ts` / `middleware.ts`. Returns a redirect (pages) or 401
+   * (API paths) when the request has no session, or `undefined` to continue.
+   * Only reads the cookie — it never calls the auth server.
+   */
+  protect(request: Request, options?: ProtectOptions): Promise<Response | undefined>;
+  /** Cookie-only check usable anywhere you have the Request. */
+  isAuthenticated(request: Request): Promise<boolean>;
+  /** Link that starts the login and comes back to `returnTo`. */
+  loginPath(returnTo?: string): string;
+  /** Link that logs the user out of the app and the auth server. */
+  readonly logoutPath: string;
+  /** Raw iron-session for advanced use (e.g. storing app data alongside the token). */
+  getSession(): Promise<IronSession<ShopwaveSessionData>>;
+}
+/**
+ * Creates the Shopwave auth instance for one Next.js app. Call once at module
+ * scope (e.g. `lib/auth.ts`) and reuse. Config is validated on first use, so
+ * a missing env var doesn't fail `next build`.
+ */
+declare function createShopwaveAuth(config: ShopwaveAuthConfig): ShopwaveAuth;
+interface ShopwaveNextApiConfig extends Omit<ShopwaveApiConfig, "getAuthorization"> {
+  /** The app's auth instance: supplies (and refreshes) the logged-in user's token. */
+  auth: Pick<ShopwaveAuth, "getAuthorizationHeader">;
+}
+/**
+ * Ready-made Next.js route handlers for the SDK's `/api/*` contract, using the
+ * session from `createShopwaveAuth`. Create once (e.g. `lib/shopwave.ts`):
+ *
+ * ```ts
+ * export const shopwave = createShopwaveApi({ auth, apiUrl: process.env.SHOPWAVE_API_SERVER_URL! });
+ * ```
+ *
+ * then each route file is one line:
+ *
+ * ```ts
+ * // app/api/products/route.ts
+ * export const { GET, POST, PUT } = shopwave.collection("product");
+ * // app/api/products/[id]/route.ts
+ * export const { GET, PUT, DELETE } = shopwave.item("product");
+ * // app/api/report/route.ts
+ * export const { GET } = shopwave.passthrough("report");
+ * ```
+ */
+declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
+//#endregion
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, ProtectOptions, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
+//# sourceMappingURL=index.d.ts.map