chat-proxy

@evolve-storefront/chat-proxy · v1.0.0

A same-origin proxy for a chat backend, as a Next.js catch-all route.

Get started

1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

   pnpm add @evolve-storefront/chat-proxy next

   Requirements1

   next	>=16.2.11 <17

Then render it on a page:

// app/api/chat-proxy/[...path]/route.ts
import { createChatProxy } from "@evolve-storefront/chat-proxy";

export const { DELETE, GET, OPTIONS, POST } = createChatProxy({
  apiUrl: process.env.CHAT_API_URL,
});

Functions

createChatProxyA same-origin proxy for a chat backend.

import { createChatProxy } from "@evolve-storefront/chat-proxy";

The storefront and the chat backend are different origins, so the browser will not send its SameSite auth cookies to the backend directly. Routing chat traffic through a route on the storefront's own origin lets the Next server read those cookies — HttpOnly ones included, which client code cannot reach at all — and call the backend server to server. No chat subdomain, certificate or CORS policy.

Mount it at a catch-all route, which is where the path param comes from:

// app/api/chat-proxy/[...path]/route.ts
export const { DELETE, GET, OPTIONS, POST } = createChatProxy({
  apiUrl: process.env.CHAT_API_URL,
});

Returns 403 rather than 500 when apiUrl is unset: a storefront with no chat backend configured has not misconfigured the proxy, it has not enabled it.

function createChatProxy(
  options: ChatProxyOptions,
): {
  DELETE: Handler;
  GET: Handler;
  OPTIONS: Handler;
  POST: Handler;
}

Option	Type	Description
apiUrl	string | undefined	The chat backend's base URL. Server-side only — never NEXT_PUBLIC_*.
authCookies?	readonly string[]	Overrides DEFAULT_AUTH_COOKIES.
forwardHeaders?	readonly string[]	Overrides DEFAULT_FORWARD_HEADERS.

Returns { DELETE: Handler; GET: Handler; OPTIONS: Handler; POST: Handler; }

Constants

DEFAULT_AUTH_COOKIESCookies forwarded by default: the gateway's auth tokens, plus the JWTs a chat backend persists a conversation against.

import { DEFAULT_AUTH_COOKIES } from "@evolve-storefront/chat-proxy";

A default rather than a constant, because the names belong to whatever issues them. Nothing outside the list is forwarded — a blanket copy would hand the chat backend every cookie the storefront holds, including a session it has no business seeing.

const DEFAULT_AUTH_COOKIES: string[]

DEFAULT_FORWARD_HEADERSRequest headers forwarded by default: the store context a chat backend needs to answer in the right locale, currency and market, and the ids that scope a conversation.

import { DEFAULT_FORWARD_HEADERS } from "@evolve-storefront/chat-proxy";

const DEFAULT_FORWARD_HEADERS: string[]