@djangocfg/widget-assistant 0.0.0-stage → 0.1.1

package/src/wire/parseSSE.ts

@@ -0,0 +1,76 @@
+/** The stream ended because nothing arrived for the idle limit, or the connection broke mid-stream. The stored message is the truth: reconcile. */
+export class StreamLostError extends Error {
+  readonly reason: 'idle' | 'network';
+
+  constructor(reason: 'idle' | 'network') {
+    super(`stream lost (${reason})`);
+    this.reason = reason;
+  }
+}
+
+/** One block (lines up to a blank line) to its JSON payload: `:` comment lines are skipped, `data:` lines are joined, malformed JSON is dropped. */
+function payloadOf(block: string): unknown {
+  const data: string[] = [];
+  for (const line of block.split('\n')) {
+    if (line.startsWith(':')) continue;
+    if (line.startsWith('data:')) data.push(line.slice(line.charAt(5) === ' ' ? 6 : 5));
+  }
+  if (data.length === 0) return undefined;
+  try {
+    return JSON.parse(data.join('\n'));
+  } catch {
+    return undefined;
+  }
+}
+
+const withIdle = <T,>(read: Promise<T>, idleMs: number): Promise<T> =>
+  new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new StreamLostError('idle')), idleMs);
+    read.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error: unknown) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+
+/**
+ * JSON payloads of a Server-Sent Events body, in order. Blocks end at a blank line (`\n\n`, `\r\n\r\n`); a trailing partial block is flushed at the end;
+ * a multi-byte character split across chunks is decoded whole. Throws `StreamLostError` on the idle limit or a read failure; an abort by the caller ends quietly.
+ */
+export async function* parseSSE(body: ReadableStream<Uint8Array>, options: { idleMs: number; signal?: AbortSignal }): AsyncGenerator<unknown> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  try {
+    for (;;) {
+      let chunk: ReadableStreamReadResult<Uint8Array>;
+      try {
+        chunk = await withIdle(reader.read(), options.idleMs);
+      } catch (error) {
+        if (options.signal?.aborted) return;
+        throw error instanceof StreamLostError ? error : new StreamLostError('network');
+      }
+      if (chunk.done) break;
+      buffer += decoder.decode(chunk.value, { stream: true }).replace(/\r\n?/g, '\n');
+      let cut = buffer.indexOf('\n\n');
+      while (cut !== -1) {
+        const payload = payloadOf(buffer.slice(0, cut));
+        buffer = buffer.slice(cut + 2);
+        if (payload !== undefined) yield payload;
+        cut = buffer.indexOf('\n\n');
+      }
+    }
+    buffer += decoder.decode().replace(/\r\n?/g, '\n');
+    if (buffer.trim()) {
+      const payload = payloadOf(buffer);
+      if (payload !== undefined) yield payload;
+    }
+  } finally {
+    reader.cancel().catch(() => undefined);
+  }
+}

package/src/wire/stored.ts

@@ -0,0 +1,24 @@
+/** A stored message as `GET /apix/chat/v1/conversation` returns it (CONTRACT.md `Message`). Replace with the generated type once `make gen-ts` carries group `chat`. */
+export type StoredStatus = 'done' | 'running' | 'error' | 'cancelled';
+
+export interface StoredWidget {
+  kind: string;
+  ids: string[];
+  caption: string | null;
+}
+
+export interface StoredMessage {
+  id: string;
+  seq: number;
+  role: 'user' | 'assistant';
+  text: string;
+  widgets: StoredWidget[];
+  status: StoredStatus;
+  error_code: string | null;
+  created_at: string;
+}
+
+export interface StoredConversation {
+  id: string | null;
+  messages: StoredMessage[];
+}

package/src/wire/transport.ts

@@ -0,0 +1,94 @@
+import { decodeFrame, IDLE_MS, type ChatContext, type Frame } from './frames.ts';
+import { parseSSE, StreamLostError } from './parseSSE.ts';
+
+/** Problem codes the API answers before a stream starts (CONTRACT.md "Auth and errors"). */
+export type RejectCode = 'unauthorized' | 'busy' | 'invalid' | 'rate_limited' | 'unavailable' | 'failed';
+
+/** The request was refused before any frame: nothing ran, so a retry with the same `client_id` is safe. */
+export class ChatHttpError extends Error {
+  readonly status: number;
+  readonly code: RejectCode;
+  /** Seconds from `Retry-After`, for 429. */
+  readonly retryAfter?: number;
+
+  constructor(status: number, code: RejectCode, retryAfter?: number) {
+    super(`chat ${status} ${code}`);
+    this.status = status;
+    this.code = code;
+    this.retryAfter = retryAfter;
+  }
+}
+
+/** No answer at all (offline, DNS, reset before the response): nothing is known to have run. */
+export class ChatNetworkError extends Error {
+  constructor() {
+    super('chat network error');
+  }
+}
+
+export interface SendInput {
+  text: string;
+  clientId: string;
+  context?: ChatContext;
+  signal: AbortSignal;
+}
+
+/** Opens one run and yields its frames. The adapter owns the meaning; tests and stories supply a scripted one. */
+export interface ChatTransport {
+  open(input: SendInput): AsyncGenerator<Frame>;
+}
+
+export interface TransportConfig {
+  /** API origin, no trailing slash. The stream is called directly, never through a Next rewrite. */
+  baseUrl: string;
+  /** The bearer token, read per request; the header only, never the query string. */
+  getToken: () => string | null | undefined;
+  idleMs?: number;
+  fetch?: typeof fetch;
+}
+
+const CODES: readonly string[] = ['unauthorized', 'busy', 'invalid', 'rate_limited', 'unavailable'];
+
+function rejectCode(status: number, body: unknown): RejectCode {
+  const code = typeof body === 'object' && body !== null ? (body as { code?: unknown }).code : undefined;
+  if (typeof code === 'string' && CODES.includes(code)) return code as RejectCode;
+  if (status === 401) return 'unauthorized';
+  if (status === 409) return 'busy';
+  if (status === 422) return 'invalid';
+  if (status === 429) return 'rate_limited';
+  if (status === 503) return 'unavailable';
+  return 'failed';
+}
+
+export function createTransport(config: TransportConfig): ChatTransport {
+  const call = config.fetch ?? fetch;
+  return {
+    async *open({ text, clientId, context, signal }) {
+      const token = config.getToken();
+      let response: Response;
+      try {
+        response = await call(`${config.baseUrl}/apix/chat/v1/stream`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+          body: JSON.stringify({ text, client_id: clientId, ...(context ? { context } : {}) }),
+          signal,
+        });
+      } catch {
+        if (signal.aborted) return;
+        throw new ChatNetworkError();
+      }
+      if (!response.ok) {
+        const body: unknown = await response.json().catch(() => null);
+        const wait = Number(response.headers.get('retry-after'));
+        throw new ChatHttpError(response.status, rejectCode(response.status, body), Number.isFinite(wait) && wait > 0 ? Math.ceil(wait) : undefined);
+      }
+      if (!response.body || !(response.headers.get('content-type') ?? '').includes('text/event-stream')) throw new ChatHttpError(response.status, 'failed');
+      for await (const raw of parseSSE(response.body, { idleMs: config.idleMs ?? IDLE_MS, signal })) {
+        const frame = decodeFrame(raw);
+        if (frame) yield frame;
+      }
+    },
+  };
+}
+
+export { StreamLostError };