@catandbox/schrodinger-contracts

TypeScript contracts and API client for Schrodinger — an AI-powered headless helpdesk built on Cloudflare Workers.

This package contains:

• Generated TypeScript types from the OpenAPI spec
• SchrodingerApiClient — low-level generated HTTP client
• SupportApiClient — high-level fetch-based client for the customer-facing portal API
• All shared interfaces used by the web adapter and any custom integrations

Installation

npm install @catandbox/schrodinger-contracts

Usage

SupportApiClient

The primary client for interacting with the Schrodinger support portal API from a browser or edge runtime. No framework dependencies — works anywhere fetch is available.

import { SupportApiClient } from "@catandbox/schrodinger-contracts";

const client = new SupportApiClient({
  basePath: "/support/api",       // path prefix where the proxy is mounted
  // baseUrl: "https://...",      // explicit base URL (optional)
  // headers: { "X-My-Header": "value" }, // static headers
  // getHeaders: async () => ({ ... }),   // dynamic headers (e.g. auth tokens)
});

// List tickets
const { items } = await client.listTickets({ status: "Active" });

// Get a single ticket with its messages
const { ticket, messages, events } = await client.getTicket(ticketId);

// Create a new ticket
const ticket = await client.createTicket({
  title: "Something isn't working",
  body: "Here are the details...",
  categoryId: "cat_123",       // optional
});

// Reply to a ticket
const message = await client.createReply(ticketId, { body: "Thank you!" });

// Close / reopen
await client.closeTicket(ticketId);
await client.reopenTicket(ticketId);

// Rate a ticket or a message
await client.rateTicket(ticketId, { stars: 5, comment: "Great support!" });
await client.rateMessage(messageId, { stars: 4 });

File uploads

// 1. Initialise uploads
const { uploads } = await client.initUploads({
  ticketId,
  files: [{ filename: "screenshot.png", mime: "image/png", sizeBytes: 12345, sha256: "..." }],
});

// 2. PUT each file to its pre-signed URL
await client.putUpload(uploads[0].putUrl, file, (loaded, total) => {
  console.log(`${Math.round((loaded / total) * 100)}%`);
});

// 3. Confirm completion
await client.completeUploads({
  ticketId,
  uploads: [{ uploadId: uploads[0].uploadId, sizeBytes: file.size, sha256: "..." }],
  messageId,  // optional — attach to an existing message
});

SupportApiError

import { SupportApiClient, SupportApiError } from "@catandbox/schrodinger-contracts";

try {
  await client.createTicket({ title: "...", body: "..." });
} catch (err) {
  if (err instanceof SupportApiError) {
    console.error(err.status, err.code, err.message, err.requestId);
  }
}

Types

All types are exported from the package root:

| Type | Description | |---|---| | SupportClientOptions | Constructor options for SupportApiClient | | ClientHeadersProvider | Async function returning dynamic request headers | | ListTicketsParams | Parameters for listTickets() | | SupportCategory | A support category | | TicketDetailData | Return type of getTicket() — ticket + messages + events | | UploadInputFile | File descriptor for initUploads() | | UploadInitResult | Return type of initUploads() | | UploadCompleteInput | Input for completeUploads() | | Ticket, Message, Alias | Core domain types (generated from OpenAPI) | | TicketStatus | "Active" \| "InProgress" \| "AwaitingResponse" \| "Closed" \| "Archived" |

OpenAPI spec

The raw OpenAPI specification is included in the package at openapi/schrodinger.openapi.yaml and can be used to generate clients in other languages.

License

MIT