react-shopwave-connect 0.2.0 → 0.4.0

package/dist/next/index.d.cts

@@ -84,6 +84,218 @@ interface ShopwaveOAuthClient {
   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/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>>;
+//#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;
+  /** 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;
+}
+//#endregion
 //#region src/core/session.d.ts
 /**
  * Login status returned by the app's `/api/session` route. It deliberately
@@ -192,6 +404,13 @@ interface ProtectOptions {
   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. */
@@ -250,6 +469,35 @@ interface ShopwaveAuth {
  * 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");
+ * // app/api/merchant/route.ts, app/api/user/route.ts
+ * export const { GET, PUT } = shopwave.resource("merchant");
+ * export const { GET } = shopwave.resource("user");
+ * // app/api/upload/route.ts
+ * export const { POST } = shopwave.upload();
+ * ```
+ */
+declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-export { AuthContext, ProtectOptions, type SessionStatus, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, authorizationHeader, createShopwaveAuth, isExpiredTokenResponse };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.cts.map

package/dist/next/index.d.ts

@@ -84,6 +84,218 @@ interface ShopwaveOAuthClient {
   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/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>>;
+//#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;
+  /** 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;
+}
+//#endregion
 //#region src/core/session.d.ts
 /**
  * Login status returned by the app's `/api/session` route. It deliberately
@@ -192,6 +404,13 @@ interface ProtectOptions {
   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. */
@@ -250,6 +469,35 @@ interface ShopwaveAuth {
  * 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");
+ * // app/api/merchant/route.ts, app/api/user/route.ts
+ * export const { GET, PUT } = shopwave.resource("merchant");
+ * export const { GET } = shopwave.resource("user");
+ * // app/api/upload/route.ts
+ * export const { POST } = shopwave.upload();
+ * ```
+ */
+declare function createShopwaveApi(config: ShopwaveNextApiConfig): ShopwaveApiHandlers;
 //#endregion
-export { AuthContext, ProtectOptions, type SessionStatus, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, authorizationHeader, createShopwaveAuth, isExpiredTokenResponse };
+export { AuthContext, type CollectionHandlers, type EntityDefinition, type EntityKind, type ForwardInit, type ItemHandlers, ProtectOptions, type ResourceHandlers, type ResourceKind, type RouteContext, type RouteHandler, SHOPWAVE_ENTITIES, SHOPWAVE_RESOURCES, type SessionStatus, type ShopwaveApiHandlers, ShopwaveAuth, ShopwaveAuthConfig, ShopwaveAuthError, ShopwaveNextApiConfig, ShopwaveSessionConfig, ShopwaveSessionData, type ShopwaveToken, UPLOAD_KINDS, type UploadHandlers, type UploadKind, type UploadOptions, authorizationHeader, createShopwaveApi, createShopwaveAuth, isExpiredTokenResponse, readRequestToken };
 //# sourceMappingURL=index.d.ts.map