@vib-rato/ai 0.16.0

package/src/providers/aws-eventstream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `application/vnd.amazon.eventstream` decoder.
+ *
+ * Wire format (all integers big-endian):
+ *
+ *   [total length     u32]
+ *   [headers length   u32]
+ *   [prelude CRC32    u32]   <- CRC over the first 8 bytes
+ *   [headers          headers_length]
+ *   [payload          total_length - headers_length - 16]
+ *   [message CRC32    u32]   <- CRC over the entire message minus the trailing 4 bytes
+ *
+ * Headers: a sequence of `[name_len u8][name utf8][value_type u8][value …]`.
+ * We only need the typed values Bedrock emits (boolean true/false, byte, short,
+ * integer, long, byte-array, string, timestamp, uuid). All are surfaced as
+ * strings for ease of consumption — Bedrock only sets string-valued headers in
+ * practice (`:event-type`, `:message-type`, `:content-type`, `:exception-type`).
+ */
+export interface EventStreamMessage {
+    /** Lower-cased copy is *not* applied — Bedrock uses casing like `:event-type` verbatim. */
+    headers: Record<string, string>;
+    payload: Uint8Array;
+}
+export declare function crc32(bytes: Uint8Array, seed?: number): number;
+/**
+ * Decode a single, fully buffered eventstream message. Throws if the framing is
+ * malformed or either CRC mismatches. Used by both `decodeEventStream` (the
+ * streaming entry point) and the unit tests, which exercise it with hand-built
+ * frames.
+ */
+export declare function decodeMessage(frame: Uint8Array): EventStreamMessage;
+/**
+ * Async generator that consumes a `ReadableStream<Uint8Array>` (e.g. a fetch
+ * response body) and yields fully-framed messages. Handles arbitrary chunk
+ * boundaries: messages may span multiple chunks, and a single chunk may carry
+ * many messages.
+ */
+export declare function decodeEventStream(source: ReadableStream<Uint8Array>): AsyncGenerator<EventStreamMessage>;

package/src/providers/aws-eventstream.ts

@@ -0,0 +1,185 @@
+/**
+ * `application/vnd.amazon.eventstream` decoder.
+ *
+ * Wire format (all integers big-endian):
+ *
+ *   [total length     u32]
+ *   [headers length   u32]
+ *   [prelude CRC32    u32]   <- CRC over the first 8 bytes
+ *   [headers          headers_length]
+ *   [payload          total_length - headers_length - 16]
+ *   [message CRC32    u32]   <- CRC over the entire message minus the trailing 4 bytes
+ *
+ * Headers: a sequence of `[name_len u8][name utf8][value_type u8][value …]`.
+ * We only need the typed values Bedrock emits (boolean true/false, byte, short,
+ * integer, long, byte-array, string, timestamp, uuid). All are surfaced as
+ * strings for ease of consumption — Bedrock only sets string-valued headers in
+ * practice (`:event-type`, `:message-type`, `:content-type`, `:exception-type`).
+ */
+
+const PRELUDE_LEN = 8;
+const PRELUDE_CRC_LEN = 4;
+const MESSAGE_CRC_LEN = 4;
+const HEADER_BLOCK_OFFSET = PRELUDE_LEN + PRELUDE_CRC_LEN;
+const MIN_MESSAGE_LEN = HEADER_BLOCK_OFFSET + MESSAGE_CRC_LEN;
+
+export interface EventStreamMessage {
+	/** Lower-cased copy is *not* applied — Bedrock uses casing like `:event-type` verbatim. */
+	headers: Record<string, string>;
+	payload: Uint8Array;
+}
+
+/** CRC32 (IEEE / zlib polynomial 0xEDB88320), matches `@aws-crypto/crc32`. */
+const CRC_TABLE = (() => {
+	const t = new Uint32Array(256);
+	for (let i = 0; i < 256; i++) {
+		let c = i;
+		for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+		t[i] = c >>> 0;
+	}
+	return t;
+})();
+
+export function crc32(bytes: Uint8Array, seed = 0): number {
+	let c = (seed ^ 0xffffffff) >>> 0;
+	for (let i = 0; i < bytes.length; i++) c = (CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8)) >>> 0;
+	return (c ^ 0xffffffff) >>> 0;
+}
+
+/**
+ * Decode a single, fully buffered eventstream message. Throws if the framing is
+ * malformed or either CRC mismatches. Used by both `decodeEventStream` (the
+ * streaming entry point) and the unit tests, which exercise it with hand-built
+ * frames.
+ */
+export function decodeMessage(frame: Uint8Array): EventStreamMessage {
+	if (frame.length < MIN_MESSAGE_LEN) throw new Error("eventstream: frame too short");
+	const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength);
+	const total = view.getUint32(0, false);
+	if (total !== frame.length) throw new Error(`eventstream: framed length ${total} != buffer ${frame.length}`);
+	const headersLen = view.getUint32(4, false);
+	const preludeCrc = view.getUint32(8, false);
+	const computedPreludeCrc = crc32(frame.subarray(0, PRELUDE_LEN));
+	if (computedPreludeCrc !== preludeCrc) throw new Error("eventstream: prelude CRC mismatch");
+	const msgCrc = view.getUint32(total - MESSAGE_CRC_LEN, false);
+	const computedMsgCrc = crc32(frame.subarray(0, total - MESSAGE_CRC_LEN));
+	if (computedMsgCrc !== msgCrc) throw new Error("eventstream: message CRC mismatch");
+
+	const headersBytes = frame.subarray(HEADER_BLOCK_OFFSET, HEADER_BLOCK_OFFSET + headersLen);
+	const payload = frame.subarray(HEADER_BLOCK_OFFSET + headersLen, total - MESSAGE_CRC_LEN);
+	return { headers: parseHeaders(headersBytes), payload };
+}
+
+function parseHeaders(buf: Uint8Array): Record<string, string> {
+	const out: Record<string, string> = {};
+	const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+	const decoder = new TextDecoder();
+	let p = 0;
+	while (p < buf.length) {
+		const nameLen = view.getUint8(p);
+		p += 1;
+		const name = decoder.decode(buf.subarray(p, p + nameLen));
+		p += nameLen;
+		const type = view.getUint8(p);
+		p += 1;
+		switch (type) {
+			case 0: // bool true
+				out[name] = "true";
+				break;
+			case 1: // bool false
+				out[name] = "false";
+				break;
+			case 2: // byte
+				out[name] = String(view.getInt8(p));
+				p += 1;
+				break;
+			case 3: // short
+				out[name] = String(view.getInt16(p, false));
+				p += 2;
+				break;
+			case 4: // integer
+				out[name] = String(view.getInt32(p, false));
+				p += 4;
+				break;
+			case 5: // long — surface as decimal string to avoid precision loss
+				out[name] = bigIntFromBytes(buf.subarray(p, p + 8)).toString();
+				p += 8;
+				break;
+			case 6: {
+				// byte array — base64 for safe transport
+				const len = view.getUint16(p, false);
+				p += 2;
+				out[name] = Buffer.from(buf.buffer, buf.byteOffset + p, len).toString("base64");
+				p += len;
+				break;
+			}
+			case 7: {
+				// string
+				const len = view.getUint16(p, false);
+				p += 2;
+				out[name] = decoder.decode(buf.subarray(p, p + len));
+				p += len;
+				break;
+			}
+			case 8: // timestamp (ms since epoch as i64)
+				out[name] = new Date(Number(bigIntFromBytes(buf.subarray(p, p + 8)))).toISOString();
+				p += 8;
+				break;
+			case 9: {
+				// uuid
+				const u = buf.subarray(p, p + 16);
+				const hex: string[] = [];
+				for (let i = 0; i < 16; i++) hex.push(u[i].toString(16).padStart(2, "0"));
+				out[name] =
+					`${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+				p += 16;
+				break;
+			}
+			default:
+				throw new Error(`eventstream: unknown header value type ${type}`);
+		}
+	}
+	return out;
+}
+
+function bigIntFromBytes(b: Uint8Array): bigint {
+	let v = 0n;
+	for (let i = 0; i < b.length; i++) v = (v << 8n) | BigInt(b[i]);
+	// sign-extend (two's complement)
+	if (b.length === 8 && b[0] & 0x80) v -= 1n << 64n;
+	return v;
+}
+
+/**
+ * Async generator that consumes a `ReadableStream<Uint8Array>` (e.g. a fetch
+ * response body) and yields fully-framed messages. Handles arbitrary chunk
+ * boundaries: messages may span multiple chunks, and a single chunk may carry
+ * many messages.
+ */
+export async function* decodeEventStream(source: ReadableStream<Uint8Array>): AsyncGenerator<EventStreamMessage> {
+	const reader = source.getReader();
+	// Single growable buffer; we slide a read cursor along it and compact when a
+	// complete prefix has been consumed. Avoids per-message Uint8Array copies.
+	let buf: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+	try {
+		while (true) {
+			const { value, done } = await reader.read();
+			if (value && value.length > 0) buf = buf.length === 0 ? value : Buffer.concat([buf, value]);
+			let offset = 0;
+			while (buf.length - offset >= 4) {
+				const dv = new DataView(buf.buffer, buf.byteOffset + offset, buf.length - offset);
+				const total = dv.getUint32(0, false);
+				if (total < MIN_MESSAGE_LEN) throw new Error(`eventstream: total length ${total} below minimum`);
+				if (buf.length - offset < total) break;
+				const frame = buf.subarray(offset, offset + total);
+				yield decodeMessage(frame);
+				offset += total;
+			}
+			if (offset > 0) buf = buf.slice(offset);
+			if (done) break;
+		}
+		if (buf.length > 0) throw new Error("eventstream: truncated message at end of stream");
+	} finally {
+		reader.releaseLock();
+	}
+}

package/src/providers/aws-sigv4.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AWS Signature V4 signing for HTTP requests. WebCrypto-only — no node:crypto.
+ *
+ * Matches `@smithy/signature-v4` for our usage: header-based signing with a
+ * full SHA-256 payload hash (Bedrock requires `applyChecksum: true`).
+ *
+ * Returns the set of headers to attach to the request:
+ *  - `host`
+ *  - `x-amz-date`
+ *  - `x-amz-content-sha256`
+ *  - `x-amz-security-token` (only when credentials carry a sessionToken)
+ *  - `authorization`
+ */
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface SignParams {
+    method: string;
+    /** Hostname only — used to build the `host` header and the canonical request. */
+    host: string;
+    /** URI path component, e.g. `/model/anthropic.Anthropic model/converse-stream`. */
+    path: string;
+    /** Optional pre-built query string (without leading `?`). */
+    query?: string;
+    /** Extra headers to sign in addition to `host`/`x-amz-*`. Names are case-insensitive. */
+    headers?: Record<string, string>;
+    body: Uint8Array;
+    region: string;
+    service: string;
+    credentials: AwsCredentials;
+    /** Override clock for deterministic tests. */
+    date?: Date;
+}
+export declare function toHex(bytes: Uint8Array): string;
+export declare function sha256(data: Uint8Array | string): Promise<Uint8Array>;
+export declare function sha256Hex(data: Uint8Array | string): Promise<string>;
+/**
+ * Derive a signing key: HMAC chain `kSecret → kDate → kRegion → kService → kSigning`.
+ */
+export declare function getSigningKey(secretAccessKey: string, shortDate: string, region: string, service: string): Promise<Uint8Array>;
+/** `YYYYMMDDTHHMMSSZ` + 8-char `YYYYMMDD`. */
+export declare function formatAmzDate(d: Date): {
+    longDate: string;
+    shortDate: string;
+};
+export interface SignedHeaders {
+    host: string;
+    "x-amz-date": string;
+    "x-amz-content-sha256": string;
+    authorization: string;
+    "x-amz-security-token"?: string;
+}
+export declare function signRequest(params: SignParams): Promise<SignedHeaders>;

package/src/providers/aws-sigv4.ts

@@ -0,0 +1,218 @@
+/**
+ * AWS Signature V4 signing for HTTP requests. WebCrypto-only — no node:crypto.
+ *
+ * Matches `@smithy/signature-v4` for our usage: header-based signing with a
+ * full SHA-256 payload hash (Bedrock requires `applyChecksum: true`).
+ *
+ * Returns the set of headers to attach to the request:
+ *  - `host`
+ *  - `x-amz-date`
+ *  - `x-amz-content-sha256`
+ *  - `x-amz-security-token` (only when credentials carry a sessionToken)
+ *  - `authorization`
+ */
+
+export interface AwsCredentials {
+	accessKeyId: string;
+	secretAccessKey: string;
+	sessionToken?: string;
+}
+
+export interface SignParams {
+	method: string;
+	/** Hostname only — used to build the `host` header and the canonical request. */
+	host: string;
+	/** URI path component, e.g. `/model/anthropic.Anthropic model/converse-stream`. */
+	path: string;
+	/** Optional pre-built query string (without leading `?`). */
+	query?: string;
+	/** Extra headers to sign in addition to `host`/`x-amz-*`. Names are case-insensitive. */
+	headers?: Record<string, string>;
+	body: Uint8Array;
+	region: string;
+	service: string;
+	credentials: AwsCredentials;
+	/** Override clock for deterministic tests. */
+	date?: Date;
+}
+
+const ALGORITHM = "AWS4-HMAC-SHA256";
+const KEY_TYPE = "aws4_request";
+// Headers the SDK never includes in the signature. Lowercased.
+const UNSIGNABLE: Record<string, true> = {
+	authorization: true,
+	"cache-control": true,
+	connection: true,
+	expect: true,
+	from: true,
+	"keep-alive": true,
+	"max-forwards": true,
+	pragma: true,
+	referer: true,
+	te: true,
+	trailer: true,
+	"transfer-encoding": true,
+	upgrade: true,
+	"user-agent": true,
+	"x-amzn-trace-id": true,
+};
+
+/** Coerce a possibly-ArrayBufferLike-backed `Uint8Array` into one over a fresh
+ * `ArrayBuffer`, which is what `crypto.subtle.{digest,sign,importKey}` requires
+ * under the strict TS DOM typings. No-op when already strict.
+ */
+function asStrict(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+	if (bytes.buffer instanceof ArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+		return bytes as Uint8Array<ArrayBuffer>;
+	}
+	const copy = new Uint8Array(bytes.byteLength);
+	copy.set(bytes);
+	return copy;
+}
+const subtle = globalThis.crypto.subtle;
+
+const HEX = "0123456789abcdef";
+export function toHex(bytes: Uint8Array): string {
+	let out = "";
+	for (let i = 0; i < bytes.length; i++) {
+		const b = bytes[i];
+		out += HEX[b >> 4] + HEX[b & 15];
+	}
+	return out;
+}
+
+export async function sha256(data: Uint8Array | string): Promise<Uint8Array> {
+	const bytes = typeof data === "string" ? new TextEncoder().encode(data) : asStrict(data);
+	const digest = await subtle.digest("SHA-256", bytes);
+	return new Uint8Array(digest);
+}
+
+export async function sha256Hex(data: Uint8Array | string): Promise<string> {
+	return toHex(await sha256(data));
+}
+
+async function hmac(key: Uint8Array, data: string | Uint8Array): Promise<Uint8Array> {
+	const cryptoKey = await subtle.importKey("raw", asStrict(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+	const bytes = typeof data === "string" ? new TextEncoder().encode(data) : asStrict(data);
+	const sig = await subtle.sign("HMAC", cryptoKey, bytes);
+	return new Uint8Array(sig);
+}
+
+/**
+ * Derive a signing key: HMAC chain `kSecret → kDate → kRegion → kService → kSigning`.
+ */
+export async function getSigningKey(
+	secretAccessKey: string,
+	shortDate: string,
+	region: string,
+	service: string,
+): Promise<Uint8Array> {
+	const kDate = await hmac(new TextEncoder().encode(`AWS4${secretAccessKey}`), shortDate);
+	const kRegion = await hmac(kDate, region);
+	const kService = await hmac(kRegion, service);
+	return hmac(kService, KEY_TYPE);
+}
+
+/** `YYYYMMDDTHHMMSSZ` + 8-char `YYYYMMDD`. */
+export function formatAmzDate(d: Date): { longDate: string; shortDate: string } {
+	const iso = d.toISOString();
+	// `2025-05-17T12:34:56.789Z` -> `20250517T123456Z`
+	const longDate = `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}T${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}Z`;
+	return { longDate, shortDate: longDate.slice(0, 8) };
+}
+
+/**
+ * Canonicalize a request path per RFC 3986: each segment is %-encoded but `/`
+ * stays literal. Matches the smithy default (`uriEscapePath: true`, then revert
+ * the double-encoding of `/`). Bedrock paths use no reserved characters in
+ * practice, but model IDs can include `:` and `.`.
+ */
+function canonicalPath(path: string): string {
+	const segments = path.split("/");
+	const escaped = segments.map(seg => (seg.length === 0 ? "" : encodeRfc3986(seg)));
+	return escaped.join("/");
+}
+
+function encodeRfc3986(str: string): string {
+	return encodeURIComponent(str).replace(/[!'()*]/g, c => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function canonicalQuery(query: string | undefined): string {
+	if (!query) return "";
+	const pairs: Array<[string, string]> = [];
+	for (const part of query.split("&")) {
+		if (!part) continue;
+		const eq = part.indexOf("=");
+		const k = eq === -1 ? part : part.slice(0, eq);
+		const v = eq === -1 ? "" : part.slice(eq + 1);
+		pairs.push([decodeURIComponent(k), decodeURIComponent(v)]);
+	}
+	pairs.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+	return pairs.map(([k, v]) => `${encodeRfc3986(k)}=${encodeRfc3986(v)}`).join("&");
+}
+
+export interface SignedHeaders {
+	host: string;
+	"x-amz-date": string;
+	"x-amz-content-sha256": string;
+	authorization: string;
+	"x-amz-security-token"?: string;
+}
+
+export async function signRequest(params: SignParams): Promise<SignedHeaders> {
+	const { method, host, path, query, body, region, service, credentials } = params;
+	const date = params.date ?? new Date();
+	const { longDate, shortDate } = formatAmzDate(date);
+	const payloadHash = await sha256Hex(body);
+
+	// Assemble the headers that will be signed. Always include host, x-amz-date,
+	// x-amz-content-sha256, plus x-amz-security-token when present, plus
+	// caller-provided signable headers (e.g. content-type, accept).
+	const signed: Record<string, string> = {
+		host,
+		"x-amz-date": longDate,
+		"x-amz-content-sha256": payloadHash,
+	};
+	if (credentials.sessionToken) signed["x-amz-security-token"] = credentials.sessionToken;
+	const extraHeaders = params.headers;
+	if (extraHeaders) {
+		for (const k in extraHeaders) {
+			const lk = k.toLowerCase();
+			if (UNSIGNABLE[lk]) continue;
+			if (lk.startsWith("proxy-") || lk.startsWith("sec-")) continue;
+			signed[lk] = extraHeaders[k].trim().replace(/\s+/g, " ");
+		}
+	}
+
+	const sortedNames = Object.keys(signed).sort();
+	const canonicalHeaders = `${sortedNames.map(n => `${n}:${signed[n]}`).join("\n")}\n`;
+	const signedHeadersStr = sortedNames.join(";");
+
+	const canonicalRequest = [
+		method.toUpperCase(),
+		canonicalPath(path),
+		canonicalQuery(query),
+		canonicalHeaders,
+		signedHeadersStr,
+		payloadHash,
+	].join("\n");
+
+	const scope = `${shortDate}/${region}/${service}/${KEY_TYPE}`;
+	const stringToSign = [ALGORITHM, longDate, scope, await sha256Hex(canonicalRequest)].join("\n");
+
+	const signingKey = await getSigningKey(credentials.secretAccessKey, shortDate, region, service);
+	const signature = toHex(await hmac(signingKey, stringToSign));
+
+	const authorization =
+		`${ALGORITHM} Credential=${credentials.accessKeyId}/${scope}, ` +
+		`SignedHeaders=${signedHeadersStr}, Signature=${signature}`;
+
+	const out: SignedHeaders = {
+		host,
+		"x-amz-date": longDate,
+		"x-amz-content-sha256": payloadHash,
+		authorization,
+	};
+	if (credentials.sessionToken) out["x-amz-security-token"] = credentials.sessionToken;
+	return out;
+}

package/src/providers/azure-openai-responses.d.ts

@@ -0,0 +1,22 @@
+import type { Model, ServiceTier, StreamFunction, StreamOptions, ToolChoice } from "../types";
+export interface AzureOpenAIResponsesOptions extends StreamOptions {
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    reasoningSummary?: "auto" | "detailed" | "concise" | null;
+    azureApiVersion?: string;
+    azureResourceName?: string;
+    azureBaseUrl?: string;
+    azureDeploymentName?: string;
+    toolChoice?: ToolChoice;
+    serviceTier?: ServiceTier;
+}
+/**
+ * Generate function for Azure OpenAI Responses API
+ */
+export declare const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses">;
+/** Test seam: the Azure endpoint config as resolved from trusted env. */
+export declare function resolveAzureConfigForTest(model: Model<"azure-openai-responses">, options?: AzureOpenAIResponsesOptions): {
+    baseUrl: string;
+    apiVersion: string;
+};
+/** Test seam: the client API key as resolved from a caller value plus trusted env. */
+export declare function resolveAzureClientApiKeyForTest(apiKey: string): string | undefined;