@schift-io/chat-widget-contract

Shared contract for a hosted chat widget API.

This package is deliberately separate from the browser widget package. The widget package owns browser rendering. This package owns the public request shape, publishable siteKey rules, origin checks, and response/error types that edge ingress services and product APIs can share.

Production Boundary

The production path should stay split:

1. Customer website loads the browser widget package with a publishable siteKey.
2. Browser sends POST /v1/widget/chat to a widget ingress service.
3. Widget ingress validates JSON, siteKey, allowed origin, rate limit, and widget status using this contract.
4. Widget ingress enqueues a widget.chat.received job or calls an internal product API with a server-side secret.
5. Worker/product APIs store conversations, run retrieval/answering, and return customer-safe status or answer data.
6. Customer console reads widget settings, install snippet, and inbox through authenticated operator APIs.

The widget ingress can be a Cloudflare Worker, Pages Function, or small service. It should not be implemented as a hard dependency of auth, billing, or core dashboard routes. If widget traffic spikes or fails, the authenticated product must continue to work.

Key Model

• siteKey: publishable identifier placed in HTML or bundled JavaScript.
• Secret API key: server-only credential used by widget ingress or customer backends. Never expose it through the browser SDK.

Minimal Ingress Sketch

import { createWidgetIngressHandler } from "@schift-io/chat-widget-ingress";

export const handleWidgetChat = createWidgetIngressHandler({
  loadSite: (siteKey) => loadWidgetSite(siteKey),
  enqueue: (job) => enqueueWidgetJob(job),
});

The contract remains useful for custom ingress implementations, but hosted widget paths should prefer the isolated ingress package so widget traffic can fail or scale independently from auth, billing, and dashboard routes.