@catandbox/schrodinger-web-adapter

Framework-agnostic web adapter for Schrodinger — an AI-powered headless helpdesk built on Cloudflare Workers.

This package provides everything needed to embed a full customer-facing support portal into any web app, plus the server-side Shopify proxy and webhook utilities. No React dependency — the UI renders with Shopify Polaris Web Components.

Installation

npm install @catandbox/schrodinger-web-adapter

Package exports

| Entry point | Contents | |---|---| | @catandbox/schrodinger-web-adapter/client | Portal UI renderer + SupportApiClient | | @catandbox/schrodinger-web-adapter/server | Shopify proxy handler, webhook forwarders, auth utilities | | @catandbox/schrodinger-web-adapter/signer | HMAC request signing primitives |

Client — portal UI

Renders a complete support portal (ticket list → detail → new ticket form) into any HTMLElement. Requires Polaris Web Components to be loaded on the page.

import { renderSupportPortal } from "@catandbox/schrodinger-web-adapter/client";

const container = document.getElementById("support-root")!;

await renderSupportPortal(container, {
  basePath: "/support/api",     // path where the server proxy is mounted
  // headers: { "Authorization": "Bearer ..." },
  // getHeaders: async () => ({ "Authorization": `Bearer ${await getToken()}` }),
});

Individual renderers

You can also render each view independently:

import {
  renderTicketList,
  renderTicketDetail,
  renderNewTicketForm,
  EventEmitter,
} from "@catandbox/schrodinger-web-adapter/client";

const emitter = new EventEmitter();

await renderTicketList(container, client, emitter);
// emitter emits "ticket:select", "ticket:create"

await renderTicketDetail(container, client, ticketId, emitter);
// emitter emits "ticket:back", "ticket:closed", "ticket:reopened"

await renderNewTicketForm(container, client, categories, emitter);
// emitter emits "ticket:created", "ticket:cancel"

SupportApiClient

The API client is re-exported for convenience — see @catandbox/schrodinger-contracts for full documentation.

import { SupportApiClient } from "@catandbox/schrodinger-web-adapter/client";

const client = new SupportApiClient({ basePath: "/support/api" });
const { items } = await client.listTickets();

Server — Shopify proxy

The server module provides a ready-made HTTP proxy that sits between your Shopify app's frontend and the Schrodinger API. It verifies the Shopify session token on every request and signs outbound calls with HMAC credentials.

import { createShopifyProxyHandler } from "@catandbox/schrodinger-web-adapter/server";

const handler = createShopifyProxyHandler({
  schApiBaseUrl: "https://your-schrodinger-api.example.com",
  schAppId: env.SCH_APP_ID,
  schKeyId: env.SCH_KEY_ID,
  schSecret: env.SCH_SECRET,
  shopifyApiKey: env.SHOPIFY_API_KEY,
  shopifyApiSecret: env.SHOPIFY_API_SECRET,
  basePath: "/support/api",   // optional, default: "/support/api"
});

// Cloudflare Workers / any fetch-based runtime:
export default {
  async fetch(request: Request): Promise<Response> {
    return handler(request);
  },
};

GDPR webhook forwarding

import { createShopifyWebhookHandlers } from "@catandbox/schrodinger-web-adapter/server";

const webhooks = createShopifyWebhookHandlers({
  schApiBaseUrl: "https://your-schrodinger-api.example.com",
  schAdminApiToken: env.SCH_ADMIN_API_TOKEN,
  shopifyApiKey: env.SHOPIFY_API_KEY,
  shopifyApiSecret: env.SHOPIFY_API_SECRET,
  // called on app/uninstalled to revoke portal access:
  disablePortalAccess: async ({ shopDomain }) => { /* ... */ },
});

// Wire up to your router:
router.post("/webhooks/customers/data_request", webhooks.handleCustomersDataRequestWebhook);
router.post("/webhooks/customers/redact",        webhooks.handleCustomersRedactWebhook);
router.post("/webhooks/shop/redact",             webhooks.handleShopRedactWebhook);
router.post("/webhooks/app/uninstalled",         webhooks.handleAppUninstalledWebhook);

Auth utilities

import {
  createPrincipalContext,
  verifyShopifySessionToken,
  verifyShopifyWebhookHmac,
  ShopifyAuthError,
} from "@catandbox/schrodinger-web-adapter/server";

// Verify a Shopify session JWT and extract principal info
const principal = await createPrincipalContext(request, {
  shopifyApiKey: env.SHOPIFY_API_KEY,
  shopifyApiSecret: env.SHOPIFY_API_SECRET,
});
// principal.tenantExternalId — shop domain
// principal.principalExternalId — customer identifier

Signer — HMAC request signing

Low-level primitives for signing requests to the Schrodinger API with HMAC-SHA256. Useful when making server-to-server calls outside of the proxy handler.

import { signRequest, sha256Hex } from "@catandbox/schrodinger-web-adapter/signer";

const headers = await signRequest({
  appId: "my-app",
  keyId: "key-1",
  keySecret: "secret",
  timestamp: Math.floor(Date.now() / 1000),
  nonce: crypto.randomUUID(),
  method: "POST",
  path: "/v1/tickets",
  rawBody: JSON.stringify({ title: "Hello" }),
});

// headers["X-Sch-AppId"], ["X-Sch-KeyId"], ["X-Sch-Timestamp"],
//        ["X-Sch-Nonce"], ["Content-SHA256"], ["X-Sch-Signature"]

Requirements

• Runtime: any environment with fetch, crypto.subtle, and TextEncoder (Cloudflare Workers, modern browsers, Node.js ≥ 18)
• UI: Polaris Web Components must be loaded on the page before calling client renderers

License

MIT