@catandbox/schrodinger-contracts 0.1.28 → 0.1.33

package/README.md

@@ -0,0 +1,117 @@
+# @catandbox/schrodinger-contracts
+
+TypeScript contracts and API client for [Schrodinger](https://github.com/yetone/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
+
+```bash
+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.
+
+```ts
+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
+
+```ts
+// 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
+
+```ts
+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

package/dist/src/client.d.ts

@@ -0,0 +1,120 @@
+import type { Alias, Message, RatingRequest, Ticket, TicketStatus } from "../generated/types";
+export interface ClientHeadersProvider {
+    (): Record<string, string> | Promise<Record<string, string>>;
+}
+export interface SupportClientOptions {
+    basePath?: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    headers?: Record<string, string>;
+    getHeaders?: ClientHeadersProvider;
+    /** BCP 47 locale tag (e.g. "en", "fr", "de"). Defaults to the browser locale. */
+    locale?: string;
+}
+export interface ListTicketsParams {
+    status?: TicketStatus;
+}
+export interface SupportCategory {
+    id: string;
+    integrationId?: string;
+    name: string;
+    isDeleted?: boolean;
+}
+export interface TicketDetailData {
+    ticket: Ticket;
+    messages: Message[];
+    events: Array<{
+        id: string;
+        eventType: string;
+        createdAt: number;
+        payloadJson?: string;
+    }>;
+}
+export interface UploadInputFile {
+    filename: string;
+    mime: string;
+    sizeBytes: number;
+    sha256: string;
+}
+export interface UploadInitResult {
+    uploads: Array<{
+        uploadId: string;
+        attachmentId: string;
+        filename: string;
+        putUrl: string;
+    }>;
+}
+export interface UploadCompleteInput {
+    ticketId: string;
+    uploads: Array<{
+        uploadId: string;
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    messageId?: string | null;
+}
+export declare class SupportApiError extends Error {
+    readonly code: string;
+    readonly requestId: string | null;
+    readonly status: number;
+    constructor(input: {
+        message: string;
+        status: number;
+        code?: string;
+        requestId?: string | null;
+    });
+}
+export declare class SupportApiClient {
+    private readonly basePath;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly staticHeaders;
+    private readonly getHeaders;
+    private readonly contractsClient;
+    constructor(options?: SupportClientOptions);
+    getCategories(): Promise<{
+        items: SupportCategory[];
+    }>;
+    getPortalConfig(): Promise<{
+        categories: Array<{
+            id: string;
+            name: string;
+        }>;
+        aliases: Alias[];
+    }>;
+    listTickets(params?: ListTicketsParams): Promise<{
+        items: Ticket[];
+    }>;
+    getTicket(ticketId: string): Promise<TicketDetailData>;
+    createTicket(input: {
+        categoryId?: string | null;
+        title: string;
+        body: string;
+        clientMessageId?: string | null;
+    }): Promise<Ticket>;
+    createReply(ticketId: string, input: {
+        body: string;
+        clientMessageId?: string | null;
+    }): Promise<Message>;
+    closeTicket(ticketId: string): Promise<Ticket>;
+    archiveTicket(ticketId: string): Promise<Ticket>;
+    reopenTicket(ticketId: string): Promise<Ticket>;
+    rateTicket(ticketId: string, input: Omit<RatingRequest, "tenantExternalId" | "principalExternalId">): Promise<{
+        ok: true;
+    }>;
+    rateMessage(messageId: string, input: Omit<RatingRequest, "tenantExternalId" | "principalExternalId">): Promise<{
+        ok: true;
+        aliasRated: boolean;
+    }>;
+    initUploads(input: {
+        ticketId: string;
+        files: UploadInputFile[];
+    }): Promise<UploadInitResult>;
+    completeUploads(input: UploadCompleteInput): Promise<{
+        completed: number;
+        scanStatus: "pending";
+    }>;
+    putUpload(putUrl: string, file: File, onProgress?: (loaded: number, total: number) => void): Promise<void>;
+    private requestJson;
+    private resolveHeaders;
+}

package/dist/src/client.js

@@ -0,0 +1,334 @@
+import { SchrodingerApiClient } from "../generated/client";
+export class SupportApiError extends Error {
+    code;
+    requestId;
+    status;
+    constructor(input) {
+        super(input.message);
+        this.name = "SupportApiError";
+        this.status = input.status;
+        this.code = input.code ?? "SUPPORT_API_ERROR";
+        this.requestId = input.requestId ?? null;
+    }
+}
+export class SupportApiClient {
+    basePath;
+    baseUrl;
+    fetchImpl;
+    staticHeaders;
+    getHeaders;
+    contractsClient;
+    constructor(options = {}) {
+        this.basePath = normalizeBasePath(options.basePath ?? "/support/api");
+        this.baseUrl = resolveBaseUrl(options.baseUrl, this.basePath);
+        this.fetchImpl = (options.fetchImpl ?? fetch).bind(globalThis);
+        this.staticHeaders = options.headers ?? {};
+        this.getHeaders = options.getHeaders ?? null;
+        this.contractsClient = new SchrodingerApiClient({
+            baseUrl: this.baseUrl,
+            fetchImpl: (input, init) => {
+                const requestUrl = new URL(typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url, this.baseUrl);
+                requestUrl.pathname = requestUrl.pathname.replace(new RegExp(`^${escapeRegExp(this.basePath)}/v1(?=/|$)`), // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp
+                this.basePath);
+                return this.fetchImpl(requestUrl.toString(), init);
+            }
+        });
+    }
+    async getCategories() {
+        return await this.requestJson("GET", "/categories");
+    }
+    async getPortalConfig() {
+        return await this.contractsClient.request("GET /v1/portal-config", undefined, {
+            headers: await this.resolveHeaders()
+        });
+    }
+    async listTickets(params = {}) {
+        return await this.contractsClient.request("GET /v1/tickets", undefined, {
+            headers: await this.resolveHeaders(),
+            query: {
+                status: params.status
+            }
+        });
+    }
+    async getTicket(ticketId) {
+        const [payload, historyPayload] = await Promise.all([
+            this.requestJson("GET", `/tickets/${encodeURIComponent(ticketId)}`),
+            this.requestJson("GET", `/tickets/${encodeURIComponent(ticketId)}/history`).catch(() => null)
+        ]);
+        const detail = normalizeTicketDetailPayload(payload);
+        if (historyPayload !== null) {
+            const historyEvents = asEventArrayFromHistory(historyPayload);
+            if (historyEvents.length > 0) {
+                detail.events = historyEvents;
+            }
+        }
+        return detail;
+    }
+    async createTicket(input) {
+        return await this.contractsClient.request("POST /v1/tickets", input, {
+            headers: await this.resolveHeaders()
+        });
+    }
+    async createReply(ticketId, input) {
+        return await this.contractsClient.request("POST /v1/tickets/{ticketId}/messages", input, {
+            headers: await this.resolveHeaders(),
+            pathParams: {
+                ticketId
+            }
+        });
+    }
+    async closeTicket(ticketId) {
+        return await this.requestJson("POST", `/tickets/${encodeURIComponent(ticketId)}/close`, {});
+    }
+    async archiveTicket(ticketId) {
+        return await this.requestJson("POST", `/tickets/${encodeURIComponent(ticketId)}/archive`, {});
+    }
+    async reopenTicket(ticketId) {
+        return await this.requestJson("POST", `/tickets/${encodeURIComponent(ticketId)}/reopen`, {});
+    }
+    async rateTicket(ticketId, input) {
+        return await this.contractsClient.request("POST /v1/tickets/{ticketId}/ratings", input, {
+            headers: await this.resolveHeaders(),
+            pathParams: {
+                ticketId
+            }
+        });
+    }
+    async rateMessage(messageId, input) {
+        return await this.contractsClient.request("POST /v1/messages/{messageId}/ratings", input, {
+            headers: await this.resolveHeaders(),
+            pathParams: {
+                messageId
+            }
+        });
+    }
+    async initUploads(input) {
+        return await this.contractsClient.request("POST /v1/uploads/init", input, {
+            headers: await this.resolveHeaders()
+        });
+    }
+    async completeUploads(input) {
+        return await this.contractsClient.request("POST /v1/uploads/complete", input, {
+            headers: await this.resolveHeaders()
+        });
+    }
+    async putUpload(putUrl, file, onProgress) {
+        if (onProgress) {
+            await uploadViaXmlHttpRequest({
+                url: putUrl,
+                file,
+                onProgress
+            });
+            return;
+        }
+        await uploadViaXmlHttpRequest({
+            url: putUrl,
+            file
+        });
+    }
+    async requestJson(method, path, body) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        const headers = await this.resolveHeaders();
+        const response = await this.fetchImpl(url.toString(), {
+            method,
+            headers: {
+                ...headers,
+                ...(body === undefined ? {} : { "content-type": "application/json" })
+            },
+            body: body === undefined ? null : JSON.stringify(body)
+        });
+        if (!response.ok) {
+            throw await toSupportApiError(response);
+        }
+        return (await response.json());
+    }
+    async resolveHeaders() {
+        const dynamic = this.getHeaders ? await this.getHeaders() : {};
+        return {
+            ...this.staticHeaders,
+            ...dynamic
+        };
+    }
+}
+async function uploadViaXmlHttpRequest(input) {
+    await new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        xhr.open("PUT", input.url);
+        xhr.setRequestHeader("content-type", input.file.type || "application/octet-stream");
+        xhr.upload.onprogress = (event) => {
+            if (event.lengthComputable) {
+                input.onProgress?.(event.loaded, event.total);
+            }
+        };
+        xhr.onerror = () => reject(new Error("Upload failed"));
+        xhr.onload = () => {
+            if (xhr.status >= 200 && xhr.status < 300) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Upload failed with status ${xhr.status}`));
+            }
+        };
+        xhr.send(input.file);
+    });
+}
+async function toSupportApiError(response) {
+    try {
+        const payload = (await response.json());
+        return new SupportApiError(payload.error
+            ? {
+                status: response.status,
+                message: payload.message ?? `Request failed with status ${response.status}`,
+                code: payload.error,
+                requestId: payload.requestId ?? response.headers.get("X-Request-Id")
+            }
+            : {
+                status: response.status,
+                message: payload.message ?? `Request failed with status ${response.status}`,
+                requestId: payload.requestId ?? response.headers.get("X-Request-Id")
+            });
+    }
+    catch {
+        return new SupportApiError({
+            status: response.status,
+            message: `Request failed with status ${response.status}`,
+            requestId: response.headers.get("X-Request-Id")
+        });
+    }
+}
+function resolveBaseUrl(baseUrl, basePath) {
+    if (baseUrl) {
+        return trimTrailingSlash(baseUrl);
+    }
+    if (typeof window !== "undefined" && window.location?.origin) {
+        return `${window.location.origin}${basePath}`;
+    }
+    return `http://localhost${basePath}`;
+}
+function normalizeBasePath(path) {
+    const withSlash = path.startsWith("/") ? path : `/${path}`;
+    return withSlash.replace(/\/+$/, "");
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function normalizeTicketDetailPayload(payload) {
+    if (isTicket(payload)) {
+        return {
+            ticket: payload,
+            messages: [],
+            events: []
+        };
+    }
+    if (isRecord(payload) && isTicket(payload.ticket)) {
+        const messages = asMessageArray(payload.messages);
+        const events = asEventArray(payload.events);
+        return {
+            ticket: payload.ticket,
+            messages,
+            events
+        };
+    }
+    throw new Error("Invalid ticket detail payload");
+}
+function asMessageArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(isMessage).sort((left, right) => left.createdAt - right.createdAt);
+}
+function asEventArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const events = [];
+    for (const entry of value) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        if (typeof entry.id !== "string" ||
+            typeof entry.eventType !== "string" ||
+            typeof entry.createdAt !== "number") {
+            continue;
+        }
+        if ("payloadJson" in entry &&
+            entry.payloadJson !== undefined &&
+            typeof entry.payloadJson !== "string") {
+            continue;
+        }
+        if (typeof entry.payloadJson === "string") {
+            events.push({
+                id: entry.id,
+                eventType: entry.eventType,
+                createdAt: entry.createdAt,
+                payloadJson: entry.payloadJson
+            });
+        }
+        else {
+            events.push({
+                id: entry.id,
+                eventType: entry.eventType,
+                createdAt: entry.createdAt
+            });
+        }
+    }
+    return events.sort((left, right) => left.createdAt - right.createdAt);
+}
+function isTicket(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.id === "string" &&
+        typeof value.tenantId === "string" &&
+        typeof value.principalId === "string" &&
+        (typeof value.categoryId === "string" || value.categoryId === null) &&
+        typeof value.status === "string" &&
+        typeof value.title === "string" &&
+        (typeof value.assignedAliasId === "string" || value.assignedAliasId === null) &&
+        typeof value.createdAt === "number" &&
+        typeof value.updatedAt === "number");
+}
+function isMessage(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    return (typeof value.id === "string" &&
+        typeof value.ticketId === "string" &&
+        typeof value.authorType === "string" &&
+        typeof value.isPublic === "boolean" &&
+        typeof value.bodyPlain === "string" &&
+        (typeof value.authorAliasId === "string" || value.authorAliasId === null) &&
+        typeof value.createdAt === "number");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function asEventArrayFromHistory(payload) {
+    const items = isRecord(payload) && Array.isArray(payload.items) ? payload.items : [];
+    const events = [];
+    for (const entry of items) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        if (typeof entry.id !== "string" ||
+            typeof entry.eventType !== "string" ||
+            typeof entry.createdAt !== "number") {
+            continue;
+        }
+        const payloadJson = typeof entry.payloadJson === "string"
+            ? entry.payloadJson
+            : isRecord(entry.payload)
+                ? JSON.stringify(entry.payload)
+                : undefined;
+        events.push({
+            id: entry.id,
+            eventType: entry.eventType,
+            createdAt: entry.createdAt,
+            ...(payloadJson !== undefined ? { payloadJson } : {})
+        });
+    }
+    return events.sort((left, right) => left.createdAt - right.createdAt);
+}

package/dist/src/index.d.ts

@@ -1,2 +1,3 @@
 export * from "../generated/types";
 export * from "../generated/client";
+export * from "./client";

package/dist/src/index.js

@@ -1,2 +1,3 @@
 export * from "../generated/types";
 export * from "../generated/client";
+export * from "./client";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catandbox/schrodinger-contracts",
-  "version": "0.1.28",
+  "version": "0.1.33",
   "private": false,
   "type": "module",
   "main": "./dist/src/index.js",