@intelligo-dev/chat 1.0.0-beta.13

package/src/attachments.ts

@@ -0,0 +1,262 @@
+/**
+ * Stored attachments: the upload route and the route that serves them.
+ *
+ * Inline attachments (the default policy) travel inside the message as
+ * data URLs and need nothing here. A deployment that wants files
+ * outside the transcript — larger than a message should carry, kept
+ * after the conversation is shared, extracted to text for the model —
+ * sets `attachments.mode: "stored"`, binds a storage adapter from its
+ * composition root, and mounts these two handlers:
+ *
+ *     // app/api/chat/upload/route.ts
+ *     export const { POST } = createChatUploadHandler(chatServerConfig);
+ *     // app/api/chat/attachments/[id]/route.ts
+ *     export const { GET } = createChatAttachmentHandler(chatServerConfig);
+ *
+ * The upload answers `{ id, url, filename, mediaType, size }`; the
+ * composer puts `url` in the file part; the transport signs it for the
+ * model and persists the app URL, which this route redirects to a
+ * fresh signed URL for anyone in the workspace who can open the
+ * conversation. No signed URL is ever persisted or shared.
+ */
+
+import { requireWorkspace } from "@intelligo-dev/auth";
+import {
+  createAttachment,
+  getAttachment,
+  isAttachmentServiceError,
+  setExtractedText,
+} from "@intelligo-dev/core/attachments";
+import { createLogger } from "@intelligo-dev/core/logger";
+import {
+  attachmentStorageKey,
+  getStorageAdapter,
+  StorageUnavailableError,
+} from "@intelligo-dev/core/storage";
+
+import { ATTACHMENT_MAX_BYTES, attachmentUrl } from "./body";
+
+/** Room for the multipart boundaries and headers around the file. */
+const FORM_OVERHEAD_BYTES = 64 * 1024;
+import type { ChatActor, ChatServerConfig } from "./config";
+import { DEFAULT_CHAT_MESSAGES, refuse } from "./errors";
+
+const log = createLogger("Chat");
+
+const SIGNED_URL_SECONDS = 900;
+
+export type ChatUploadResult = {
+  id: string;
+  url: string;
+  filename: string;
+  mediaType: string;
+  size: number;
+};
+
+export type ChatUploadHandler = {
+  POST: (request: Request) => Promise<Response>;
+};
+
+export type ChatAttachmentHandler = {
+  GET: (
+    request: Request,
+    context: { params: { id: string } | Promise<{ id: string }> }
+  ) => Promise<Response>;
+};
+
+async function defaultAuthenticate(): Promise<ChatActor> {
+  const { workspace, user } = await requireWorkspace();
+  return { workspaceId: workspace.id, userId: user.id };
+}
+
+function safeFilename(name: string): string {
+  const base = name.split(/[\\/]/).pop() ?? "";
+  return base.replace(/[\x00-\x1f]/g, "").slice(0, 255) || "file";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * `POST multipart/form-data` with one `file` field → an attachment row
+ * and the URL the composer puts in the file part. Refuses a type the
+ * policy does not accept, a file over `maxBytes`, and anything without
+ * a session.
+ */
+export function createChatUploadHandler(
+  config: ChatServerConfig
+): ChatUploadHandler {
+  const authenticate = config.authenticate ?? defaultAuthenticate;
+  const policy = config.attachments;
+
+  async function messagesFor(request: Request) {
+    return config.messages ? config.messages(request) : DEFAULT_CHAT_MESSAGES;
+  }
+
+  async function POST(request: Request): Promise<Response> {
+    await config.onRequest?.();
+    const t = await messagesFor(request);
+
+    if (!policy || policy.mode !== "stored") {
+      return refuse("BAD_REQUEST", t("attachmentRejected"));
+    }
+
+    let actor: ChatActor;
+    try {
+      actor = await authenticate(request);
+    } catch {
+      return refuse("UNAUTHORIZED", t("unauthorized"));
+    }
+
+    // Refused before the body is read: `formData()` buffers all of it.
+    const maxBytes = policy.maxBytes ?? ATTACHMENT_MAX_BYTES;
+    const declared = Number(request.headers.get("content-length"));
+    if (
+      Number.isFinite(declared) &&
+      declared > maxBytes + FORM_OVERHEAD_BYTES
+    ) {
+      return refuse("BAD_REQUEST", t("attachmentRejected"));
+    }
+
+    let form: FormData;
+    try {
+      form = await request.formData();
+    } catch {
+      return refuse("BAD_REQUEST", t("invalidBody"));
+    }
+    const file = form.get("file");
+    if (!(file instanceof Blob)) {
+      return refuse("BAD_REQUEST", t("invalidBody"));
+    }
+    const mediaType = file.type || "application/octet-stream";
+    if (!policy.accept.includes(mediaType)) {
+      return refuse("BAD_REQUEST", t("attachmentRejected"));
+    }
+    if (file.size > maxBytes) {
+      return refuse("BAD_REQUEST", t("attachmentRejected"));
+    }
+
+    let storage;
+    try {
+      storage = getStorageAdapter();
+    } catch (error) {
+      if (error instanceof StorageUnavailableError) {
+        log.error("Attachment upload with no storage adapter bound");
+        return refuse("INTERNAL", t("internalError"));
+      }
+      throw error;
+    }
+
+    const id = crypto.randomUUID();
+    const filename = safeFilename(
+      typeof (file as File).name === "string" ? (file as File).name : "file"
+    );
+    const key = attachmentStorageKey(actor.workspaceId, id);
+
+    try {
+      await storage.put({
+        key,
+        body: file,
+        contentType: mediaType,
+        contentLength: file.size,
+      });
+      await createAttachment(actor, {
+        id,
+        storageKey: key,
+        filename,
+        mediaType,
+        sizeBytes: file.size,
+      });
+    } catch (error) {
+      log.error("Attachment upload failed", { error: errorMessage(error) });
+      return refuse("INTERNAL", t("internalError"));
+    }
+
+    // Text extraction is best effort: a PDF that will not parse still
+    // uploads, and the model gets the file part alone.
+    if (policy.extractText && !mediaType.startsWith("image/")) {
+      try {
+        const text = await policy.extractText({
+          id,
+          filename,
+          mediaType,
+          bytes: async () => new Uint8Array(await file.arrayBuffer()),
+        });
+        if (text) await setExtractedText(actor, { id, text });
+      } catch (error) {
+        log.warn("Attachment text extraction failed", {
+          attachmentId: id,
+          error: errorMessage(error),
+        });
+      }
+    }
+
+    const result: ChatUploadResult = {
+      id,
+      url: attachmentUrl(policy, id),
+      filename,
+      mediaType,
+      size: file.size,
+    };
+    return Response.json(result, { status: 201 });
+  }
+
+  return { POST };
+}
+
+/**
+ * `GET /api/chat/attachments/[id]` → a redirect to a short-lived signed
+ * URL, for anyone signed in to the attachment's workspace. The app URL
+ * is what the transcript persists, so it must keep working after the
+ * signed one expires.
+ */
+export function createChatAttachmentHandler(
+  config: ChatServerConfig
+): ChatAttachmentHandler {
+  const authenticate = config.authenticate ?? defaultAuthenticate;
+
+  async function messagesFor(request: Request) {
+    return config.messages ? config.messages(request) : DEFAULT_CHAT_MESSAGES;
+  }
+
+  async function GET(
+    request: Request,
+    context: { params: { id: string } | Promise<{ id: string }> }
+  ): Promise<Response> {
+    await config.onRequest?.();
+    const t = await messagesFor(request);
+    const { id } = await context.params;
+
+    let actor: ChatActor;
+    try {
+      actor = await authenticate(request);
+    } catch {
+      return refuse("UNAUTHORIZED", t("unauthorized"));
+    }
+
+    try {
+      const row = await getAttachment(actor, id);
+      const url = await getStorageAdapter().getSignedUrl(row.storageKey, {
+        expiresInSeconds: SIGNED_URL_SECONDS,
+        disposition: "inline",
+        filename: row.filename,
+      });
+      return new Response(null, {
+        status: 302,
+        headers: { location: url, "cache-control": "private, no-store" },
+      });
+    } catch (error) {
+      if (isAttachmentServiceError(error) && error.code === "not_found") {
+        return refuse("NOT_FOUND", t("notFound"));
+      }
+      log.error("Attachment read failed", {
+        attachmentId: id,
+        error: errorMessage(error),
+      });
+      return refuse("INTERNAL", t("internalError"));
+    }
+  }
+
+  return { GET };
+}

package/src/body.ts

@@ -0,0 +1,236 @@
+/**
+ * The request body, validated by hand.
+ *
+ * Not zod: a schema library in a package's public surface would have
+ * to be a peer (its `instanceof` fails across copies), and the body
+ * has four fields. The shape is the AI SDK's `DefaultChatTransport`
+ * one — `id`, `messages`, `trigger`, `messageId` — plus whatever the
+ * application's transport added, which is handed back untouched as
+ * `extra` for `resolveAgent` to read (an `agentId`, a model choice).
+ */
+
+import type { UIMessage } from "ai";
+
+import { extractText } from "./windowing";
+
+export type ChatAttachmentPolicy = {
+  /** Media types a file part may carry, e.g. `["image/jpeg", "image/png"]`. */
+  accept: readonly string[];
+  /** Largest payload accepted, in bytes. `ATTACHMENT_MAX_BYTES` when omitted. */
+  maxBytes?: number;
+  /**
+   * `inline` (default): the file travels in the message as a data URL
+   * and is persisted with it. `stored`: the file was uploaded first
+   * through the upload route and the part carries the app URL the
+   * attachment route serves; the transport signs it for the model.
+   */
+  mode?: "inline" | "stored";
+  /** The app URL of a stored attachment. Default `/api/chat/attachments/<id>`. */
+  urlFor?: (id: string) => string;
+  /**
+   * Turns a stored, non-image file into text for the model — a PDF, a
+   * spreadsheet. Runs once, at upload; the text is kept on the row and
+   * appended to the message the model sees. Unset: the file part is
+   * passed through as-is and the provider decides what to do with it.
+   */
+  extractText?: (file: {
+    id: string;
+    filename: string;
+    mediaType: string;
+    bytes: () => Promise<Uint8Array>;
+  }) => Promise<string | null>;
+};
+
+export type ChatBody = {
+  id: string;
+  messages: UIMessage[];
+  trigger: "submit-message" | "regenerate-message" | undefined;
+  messageId: string | undefined;
+  /** Fields the application's transport added beyond the SDK's own. */
+  extra: Record<string, unknown>;
+};
+
+export type ChatBodyRejection = {
+  key: "invalidBody" | "messageTooLong" | "attachmentRejected";
+  params?: Record<string, string | number>;
+};
+
+export type ParsedChatBody =
+  { ok: true; body: ChatBody } | { ok: false; rejection: ChatBodyRejection };
+
+/** 10 MB: the limit a policy that names none gets. */
+export const ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024;
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * No `system`: the system prompt is the server's. A client that could
+ * send one could rewrite the agent's instructions.
+ */
+const ROLES = new Set(["user", "assistant"]);
+const SDK_FIELDS = new Set(["id", "messages", "trigger", "messageId"]);
+const ID_PLACEHOLDER = "__ATTACHMENT_ID__";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isUIMessage(value: unknown): value is UIMessage {
+  if (!isRecord(value)) return false;
+  if (typeof value.id !== "string" || !value.id) return false;
+  if (typeof value.role !== "string" || !ROLES.has(value.role)) return false;
+  if (!Array.isArray(value.parts)) return false;
+  return value.parts.every(
+    (part) => isRecord(part) && typeof part.type === "string"
+  );
+}
+
+function dataUrlBytes(url: string): number | null {
+  if (!url.startsWith("data:")) return null;
+  const comma = url.indexOf(",");
+  if (comma === -1) return null;
+  const payload = url.slice(comma + 1);
+  return url.slice(0, comma).endsWith(";base64")
+    ? Math.floor((payload.length * 3) / 4)
+    : payload.length;
+}
+
+/** The app URL of a stored attachment under this policy. */
+export function attachmentUrl(
+  policy: Pick<ChatAttachmentPolicy, "urlFor">,
+  id: string
+): string {
+  return policy.urlFor ? policy.urlFor(id) : `/api/chat/attachments/${id}`;
+}
+
+/**
+ * The attachment id a stored file part's URL names, or null when the
+ * URL is not one this policy hands out. Absolute and relative forms
+ * of the same path both match.
+ */
+export function attachmentIdFromUrl(
+  policy: Pick<ChatAttachmentPolicy, "urlFor">,
+  url: string
+): string | null {
+  const template = attachmentUrl(policy, ID_PLACEHOLDER);
+  const at = template.indexOf(ID_PLACEHOLDER);
+  if (at === -1) return null;
+  const prefix = template.slice(0, at);
+  const suffix = template.slice(at + ID_PLACEHOLDER.length);
+
+  let path = url;
+  if (/^https?:\/\//i.test(url)) {
+    try {
+      const parsed = new URL(url);
+      path = parsed.pathname + parsed.search;
+    } catch {
+      return null;
+    }
+  }
+  if (!path.startsWith(prefix) || !path.endsWith(suffix)) return null;
+  const id = path.slice(prefix.length, path.length - suffix.length);
+  return id && !id.includes("/") ? id : null;
+}
+
+function rejectedAttachment(
+  message: UIMessage,
+  policy: ChatAttachmentPolicy | false
+): boolean {
+  for (const part of message.parts) {
+    if (part.type !== "file") continue;
+    if (policy === false) return true;
+    const file = part as { mediaType?: unknown; url?: unknown };
+    if (
+      typeof file.mediaType !== "string" ||
+      !policy.accept.includes(file.mediaType)
+    ) {
+      return true;
+    }
+    if (typeof file.url !== "string") return true;
+    if (policy.mode === "stored") {
+      // A stored part names an upload; the row is checked by the
+      // handler, which knows the tenant. A data URL here bypassed the
+      // upload route and its limits, so it is refused.
+      if (attachmentIdFromUrl(policy, file.url) === null) return true;
+      continue;
+    }
+    const bytes = dataUrlBytes(file.url);
+    if (bytes !== null && bytes > (policy.maxBytes ?? ATTACHMENT_MAX_BYTES)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function parseChatBody(
+  json: unknown,
+  options: {
+    maxMessageLength: number;
+    attachments: ChatAttachmentPolicy | false;
+  }
+): ParsedChatBody {
+  const invalid: ParsedChatBody = {
+    ok: false,
+    rejection: { key: "invalidBody" },
+  };
+  if (!isRecord(json)) return invalid;
+  if (typeof json.id !== "string" || !UUID.test(json.id)) return invalid;
+  if (!Array.isArray(json.messages) || json.messages.length === 0)
+    return invalid;
+  if (!json.messages.every(isUIMessage)) return invalid;
+  if (
+    json.trigger !== undefined &&
+    json.trigger !== "submit-message" &&
+    json.trigger !== "regenerate-message"
+  ) {
+    return invalid;
+  }
+  if (json.messageId !== undefined && typeof json.messageId !== "string") {
+    return invalid;
+  }
+
+  const messages = json.messages as UIMessage[];
+  // Every user message, not only the new one: the history is the
+  // client's too, and a turn is billed for all of it.
+  for (const message of messages) {
+    if (message.role !== "user") continue;
+    const length = extractText(message.parts).length;
+    if (length > options.maxMessageLength) {
+      return {
+        ok: false,
+        rejection: {
+          key: "messageTooLong",
+          params: { max: options.maxMessageLength },
+        },
+      };
+    }
+    if (rejectedAttachment(message, options.attachments)) {
+      return { ok: false, rejection: { key: "attachmentRejected" } };
+    }
+  }
+
+  const last = messages[messages.length - 1]!;
+  if (last.role === "assistant") {
+    // A turn that continues the assistant's own message — tool results
+    // or approval answers added client-side — names that message. The
+    // SDK sends exactly this; anything else is a hand-made body that
+    // would make the reply a fresh message with the tool loop lost.
+    if (json.trigger === "regenerate-message") return invalid;
+    if (json.messageId !== last.id) return invalid;
+  }
+
+  const extra: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(json)) {
+    if (!SDK_FIELDS.has(key)) extra[key] = value;
+  }
+
+  return {
+    ok: true,
+    body: {
+      id: json.id,
+      messages,
+      trigger: json.trigger as ChatBody["trigger"],
+      messageId: json.messageId as string | undefined,
+      extra,
+    },
+  };
+}

package/src/client.ts

@@ -0,0 +1,133 @@
+/**
+ * What a chat client needs to know about the transport. Imports nothing at
+ * runtime (`./parts` is types and one type guard), so the UI never pulls
+ * the server handler, or Drizzle, Stripe and the auth server behind it,
+ * into the browser.
+ */
+
+/** Stable codes the transport answers with. The status is fixed per code. */
+export const CHAT_ERROR_CODES = [
+  "BAD_REQUEST",
+  "UNAUTHORIZED",
+  "QUOTA_EXCEEDED",
+  "FEATURE_GATED",
+  "NOT_FOUND",
+  "RATE_LIMITED",
+  "INTERNAL",
+  "BILLING_NOT_CONFIGURED",
+  "MODEL_UNAVAILABLE",
+] as const;
+
+export type ChatErrorCode = (typeof CHAT_ERROR_CODES)[number];
+
+/** The JSON body of every non-2xx answer from the chat transport. */
+export type ChatErrorBody = {
+  /** Human-readable, in the caller's locale when the app bound a translator. */
+  error: string;
+  code: ChatErrorCode;
+  /**
+   * The entitlement port's own refusal code (`insufficient_credits`,
+   * `allowance_depleted`, …) when `code` is `QUOTA_EXCEEDED`,
+   * `BILLING_NOT_CONFIGURED` or `MODEL_UNAVAILABLE` (`unknown_model`).
+   */
+  reasonCode?: string;
+  /** Set on `RATE_LIMITED`. */
+  retryAfterSeconds?: number;
+};
+
+/**
+ * What the chat page opened with: a server-rendered estimate of the
+ * caller's credit, so the page can say "you are out" before a message
+ * is spent on finding out. Amounts are micros of the billing currency.
+ */
+export type ChatQuotaState = {
+  /** False when the next turn would be refused. */
+  allowed: boolean;
+  /** Why, when the engine refused. */
+  reason: string | null;
+  /** Typed refusal, for a UI that wants to distinguish them. */
+  code: string | null;
+  /** Balance left across every pool. */
+  remaining: number;
+  /** Worst-case cost of one turn. */
+  estimated: number;
+  /** Where "upgrade" and "top up" should go. */
+  upgradeHref: string;
+};
+
+/**
+ * A model the composer may offer. `id` is a registered model id; the
+ * transport refuses any other. `featureKey` gates it by plan.
+ */
+export type ChatModelOption = {
+  id: string;
+  label: string;
+  description?: string;
+  /** Plan feature the workspace needs for this model; unset means every plan. */
+  featureKey?: string;
+};
+
+export type {
+  ChatAgentData,
+  ChatArtifactData,
+  ChatAuthorizationData,
+  ChatCompactionData,
+  ChatDataChunk,
+  ChatDataPart,
+  ChatDataPartName,
+  ChatDataParts,
+  ChatMessageMetadata,
+  ChatQuestionData,
+  ChatQuestionOption,
+  ChatStatusData,
+  ChatTaskData,
+  ChatTaskItem,
+  ChatTaskStatus,
+  ChatUIMessage,
+  ChatUIMessageChunk,
+} from "./parts";
+export { isChatDataPart } from "./parts";
+
+const CODES: ReadonlySet<string> = new Set(CHAT_ERROR_CODES);
+
+/**
+ * The transport's error body, from the error `useChat` surfaces.
+ *
+ * The AI SDK's transport throws an `Error` whose message is the
+ * response text, so a JSON refusal arrives as a string. Anything that
+ * is not one of ours — a network failure, a proxy's HTML page — is
+ * null, and belongs in a generic error strip rather than a banner.
+ */
+export function parseChatError(error: unknown): ChatErrorBody | null {
+  const text =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : null;
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text) as Partial<ChatErrorBody>;
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      typeof parsed.error !== "string" ||
+      typeof parsed.code !== "string" ||
+      !CODES.has(parsed.code)
+    ) {
+      return null;
+    }
+    return {
+      error: parsed.error,
+      code: parsed.code as ChatErrorCode,
+      ...(typeof parsed.reasonCode === "string"
+        ? { reasonCode: parsed.reasonCode }
+        : {}),
+      ...(typeof parsed.retryAfterSeconds === "number"
+        ? { retryAfterSeconds: parsed.retryAfterSeconds }
+        : {}),
+    };
+  } catch {
+    return null;
+  }
+}