@poppykit/client 0.0.0-stage → 0.1.0

package/dist/network/transport.js

@@ -0,0 +1,305 @@
+import { request as httpsRequest, Agent } from 'node:https';
+import { connect, rootCertificates } from 'node:tls';
+import { lookup } from 'node:dns';
+import { BlockList, isIP } from 'node:net';
+export class TransportError extends Error {
+    code;
+    constructor(code) {
+        super(`Transport ${code}`);
+        this.code = code;
+        this.name = 'TransportError';
+    }
+}
+export function secureUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TransportError('invalid_url');
+    }
+    if (url.protocol !== 'https:' || url.username || url.password || url.hash)
+        throw new TransportError('invalid_url');
+    return url;
+}
+function normalizedAddress(value) { return value.replace(/^\[|\]$/g, '').toLowerCase(); }
+const blockedV4 = new BlockList();
+for (const [network, prefix] of [
+    ['0.0.0.0', 8], // "this" network
+    ['10.0.0.0', 8], // private
+    ['100.64.0.0', 10], // carrier-grade NAT
+    ['127.0.0.0', 8], // loopback
+    ['169.254.0.0', 16], // link-local
+    ['172.16.0.0', 12], // private
+    ['192.0.0.0', 24], // IETF protocol assignments
+    ['192.0.2.0', 24], // documentation
+    ['192.88.99.0', 24], // 6to4 relay anycast
+    ['192.168.0.0', 16], // private
+    ['198.18.0.0', 15], // benchmarking
+    ['198.51.100.0', 24], // documentation
+    ['203.0.113.0', 24], // documentation
+    ['224.0.0.0', 3], // multicast and reserved (224.0.0.0 to 255.255.255.255)
+])
+    blockedV4.addSubnet(network, prefix, 'ipv4');
+// IPv6 is allow-listed: only global unicast 2000::/3 minus special-purpose ranges.
+const blockedV6 = new BlockList();
+for (const [network, prefix] of [
+    ['2001::', 23], // IETF protocol assignments (Teredo etc.)
+    ['2001:db8::', 32], // documentation
+    ['2002::', 16], // 6to4
+    ['3fff::', 20], // documentation
+])
+    blockedV6.addSubnet(network, prefix, 'ipv6');
+const globalV6 = new BlockList();
+globalV6.addSubnet('2000::', 3, 'ipv6');
+export function isPublicAddress(value) {
+    const address = normalizedAddress(value);
+    if (isIP(address) === 4)
+        return !blockedV4.check(address, 'ipv4');
+    // Zoned addresses (fe80::1%eth0) fail closed.
+    if (isIP(address) !== 6 || address.includes('%'))
+        return false;
+    return globalV6.check(address, 'ipv6') && !blockedV6.check(address, 'ipv6');
+}
+export function createNodeTransport(options = {}) {
+    const limits = { timeoutMs: options.timeoutMs ?? 15000, maxResponseBytes: options.maxResponseBytes ?? 1048576, maxRequestBytes: options.maxRequestBytes ?? 1048576, maxRedirects: options.maxRedirects ?? 5, maxPools: options.maxPools ?? 8, maxSockets: options.maxSockets ?? 2, maxRequests: options.maxRequests ?? 32, maxStreamBytes: options.maxStreamBytes ?? 16777216, maxStreamMs: options.maxStreamMs ?? 300000 };
+    for (const [name, value] of Object.entries(limits))
+        if (!Number.isSafeInteger(value) || value < (name === 'maxRedirects' ? 0 : 1) || (name.endsWith('Ms') && value > 2147483647))
+            throw new TypeError('Invalid transport limit');
+    const pools = new Map();
+    let active = 0, closed = false;
+    const connecting = new Set();
+    const shutdown = new AbortController();
+    const allowed = (hostname, address) => isPublicAddress(address) || !!options.localExceptions?.some(entry => entry.hostname.toLowerCase() === hostname.toLowerCase() && entry.addresses.some(ip => normalizedAddress(ip) === normalizedAddress(address)));
+    async function execute(request, settings = {}, streaming = false) {
+        if (closed)
+            throw new TransportError('closed');
+        if (active >= limits.maxRequests)
+            throw new TransportError('overloaded');
+        const discovery = settings.mode === 'discovery';
+        const timeoutMs = streaming ? limits.maxStreamMs : (discovery ? Math.min(limits.timeoutMs, 5000) : limits.timeoutMs) + (settings.waitMs ?? 0);
+        if (!Number.isSafeInteger(settings.waitMs ?? 0) || (settings.waitMs ?? 0) < 0 || timeoutMs > 2147483647)
+            throw new TypeError('Invalid transport wait');
+        active++;
+        const controller = new AbortController(), signal = AbortSignal.any([request.signal, controller.signal, shutdown.signal]);
+        const timer = setTimeout(() => controller.abort(new TransportError('timeout')), timeoutMs);
+        let transferred = false, finished = false;
+        const finish = () => { if (!finished) {
+            finished = true;
+            active--;
+            clearTimeout(timer);
+        } };
+        try {
+            signal.throwIfAborted();
+            let body;
+            if (request.body) {
+                const reader = request.body.getReader(), chunks = [];
+                let length = 0;
+                const abort = () => { void reader.cancel(signal.reason); };
+                signal.addEventListener('abort', abort, { once: true });
+                try {
+                    for (;;) {
+                        signal.throwIfAborted();
+                        const item = await reader.read();
+                        if (item.done)
+                            break;
+                        length += item.value.length;
+                        if (length > limits.maxRequestBytes)
+                            throw new TransportError('body_limit');
+                        chunks.push(item.value);
+                    }
+                }
+                finally {
+                    signal.removeEventListener('abort', abort);
+                    await reader.cancel().catch(() => { });
+                    reader.releaseLock();
+                }
+                body = Buffer.concat(chunks);
+            }
+            let url = secureUrl(request.url);
+            if (request.headers.has('host') && request.headers.get('host') !== url.host)
+                throw new TransportError('invalid_url');
+            if (discovery && (request.method !== 'GET' || body || ['authorization', 'dpop', 'cookie', 'proxy-authorization', 'host'].some(key => request.headers.has(key))))
+                throw new TransportError('invalid_url');
+            for (let redirects = 0;; redirects++) {
+                signal.throwIfAborted();
+                const hostname = normalizedAddress(url.hostname);
+                const addresses = await new Promise((resolve, reject) => {
+                    const abort = () => reject(signal.reason);
+                    signal.addEventListener('abort', abort, { once: true });
+                    const done = (error, found) => { signal.removeEventListener('abort', abort); error ? reject(new TransportError('network_error')) : resolve(found); };
+                    if (isIP(hostname))
+                        done(null, [{ address: hostname, family: isIP(hostname) }]);
+                    else
+                        lookup(hostname, { all: true, verbatim: true }, done);
+                });
+                signal.throwIfAborted();
+                const approved = addresses.filter(item => allowed(hostname, item.address)).sort((a, b) => a.address.localeCompare(b.address));
+                if (!approved.length)
+                    throw new TransportError('blocked_address');
+                const mode = discovery ? 'discovery' : streaming ? 'stream' : 'endpoint';
+                const poolKey = JSON.stringify([url.origin, mode, approved, options.ca]);
+                // Recheck DNS/policy before every assignment, including free sockets. Retire incompatible pools.
+                for (const [key, pool] of pools)
+                    if (pool.origin === url.origin && pool.mode === mode && key !== poolKey) {
+                        pool.agent.destroy();
+                        pools.delete(key);
+                    }
+                let pool = pools.get(poolKey);
+                if (!pool) {
+                    if (pools.size >= limits.maxPools) {
+                        const idle = [...pools].find(([, value]) => value.active === 0);
+                        if (!idle)
+                            throw new TransportError('overloaded');
+                        idle[1].agent.destroy();
+                        pools.delete(idle[0]);
+                    }
+                    const agent = new Agent({ keepAlive: true, maxSockets: limits.maxSockets, maxTotalSockets: limits.maxSockets, maxFreeSockets: 1, timeout: limits.timeoutMs });
+                    agent.createConnection = ((connectionOptions, callback) => {
+                        const selected = approved[0];
+                        const socket = connect({ ...connectionOptions, host: selected.address, servername: isIP(hostname) ? undefined : hostname, rejectUnauthorized: true, minVersion: 'TLSv1.2', ca: options.ca ? [...rootCertificates, options.ca] : undefined });
+                        const connectSignal = connectionOptions.transportSignal;
+                        const abortConnect = () => settle(new TransportError('network_error'));
+                        connecting.add(socket);
+                        socket.setTimeout?.(limits.timeoutMs, () => socket.destroy(new TransportError('timeout')));
+                        let settled = false;
+                        const settle = (error) => { if (settled)
+                            return; settled = true; connectSignal?.removeEventListener('abort', abortConnect); connecting.delete(socket); socket.setTimeout?.(0); if (error) {
+                            socket.destroy();
+                            callback(error);
+                        }
+                        else
+                            callback(null, socket); };
+                        connectSignal?.addEventListener('abort', abortConnect, { once: true });
+                        if (connectSignal?.aborted)
+                            queueMicrotask(abortConnect);
+                        socket.once('error', error => settle(error instanceof TransportError ? error : new TransportError('network_error')));
+                        socket.once('secureConnect', () => settle(socket.remoteAddress && approved.some(item => normalizedAddress(item.address) === normalizedAddress(socket.remoteAddress)) && allowed(hostname, socket.remoteAddress) ? null : new TransportError('blocked_address')));
+                        return undefined;
+                    });
+                    agent.reuseSocket = (duplex, outgoing) => {
+                        const socket = duplex;
+                        if (!socket.remoteAddress || !approved.some(item => normalizedAddress(item.address) === normalizedAddress(socket.remoteAddress)) || !allowed(hostname, socket.remoteAddress)) {
+                            const error = new TransportError('blocked_address');
+                            socket.destroy(error);
+                            outgoing.destroy(error);
+                            return;
+                        }
+                        Agent.prototype.reuseSocket.call(agent, socket, outgoing);
+                    };
+                    pool = { agent, active: 0, origin: url.origin, mode };
+                    pools.set(poolKey, pool);
+                }
+                const selectedPool = pool;
+                // No hidden Agent queue: callers retry overload, after fresh DNS and policy validation.
+                if (selectedPool.active >= limits.maxSockets)
+                    throw new TransportError('overloaded');
+                selectedPool.active++;
+                let releaseCalled = false;
+                const release = () => { if (!releaseCalled) {
+                    releaseCalled = true;
+                    selectedPool.active--;
+                } };
+                const response = await new Promise((resolve, reject) => {
+                    const failed = (error) => {
+                        const retired = () => { release(); reject(error); }, socket = outgoing.socket;
+                        // A destroyed socket can still count against the Agent until its close event.
+                        if (socket && !socket.closed)
+                            socket.once('close', retired);
+                        else if (!outgoing.closed)
+                            outgoing.once('close', retired);
+                        else
+                            retired();
+                    };
+                    const outgoing = httpsRequest(url, { method: request.method, headers: Object.fromEntries(request.headers), agent: selectedPool.agent, signal, ...{ transportSignal: signal } }, incoming => {
+                        const headers = new Headers();
+                        for (let i = 0; i < incoming.rawHeaders.length; i += 2)
+                            headers.append(incoming.rawHeaders[i], incoming.rawHeaders[i + 1]);
+                        const status = incoming.statusCode ?? 502;
+                        if (status < 200 || status > 599) {
+                            incoming.destroy();
+                            reject(new TransportError('network_error'));
+                            return;
+                        }
+                        const noBody = [204, 205, 304].includes(status) || request.method === 'HEAD';
+                        if (streaming && !noBody) {
+                            incoming.pause();
+                            let bytes = 0;
+                            const iterator = incoming[Symbol.asyncIterator]();
+                            const retire = () => new Promise(done => { const socket = incoming.socket; if (socket && !socket.closed)
+                                socket.once('close', done);
+                            else
+                                done(); incoming.destroy(); });
+                            const ended = () => { const socket = incoming.socket, done = () => { release(); finish(); }; if (socket?.destroyed && !socket.closed)
+                                socket.once('close', done);
+                            else
+                                done(); };
+                            const stream = new ReadableStream({
+                                async pull(target) { try {
+                                    const item = await iterator.next();
+                                    if (item.done) {
+                                        target.close();
+                                        release();
+                                        finish();
+                                    }
+                                    else {
+                                        bytes += item.value.length;
+                                        if (bytes > limits.maxStreamBytes)
+                                            throw new TransportError('body_limit');
+                                        target.enqueue(item.value);
+                                    }
+                                }
+                                catch (error) {
+                                    await retire();
+                                    release();
+                                    finish();
+                                    target.error(error);
+                                } },
+                                async cancel() { await retire(); await iterator.return?.(); release(); finish(); },
+                            }, { highWaterMark: 0 });
+                            incoming.once('close', ended);
+                            transferred = true;
+                            const result = new Response(stream, { status, headers });
+                            Object.defineProperty(result, 'url', { value: url.href });
+                            resolve(result);
+                        }
+                        else {
+                            const chunks = [];
+                            let size = 0;
+                            incoming.on('data', (chunk) => { size += chunk.length; if (size > (discovery ? Math.min(limits.maxResponseBytes, 102400) : limits.maxResponseBytes))
+                                incoming.destroy(new TransportError('body_limit'));
+                            else
+                                chunks.push(chunk); });
+                            incoming.on('error', failed);
+                            incoming.on('end', () => { const result = new Response(noBody ? null : Buffer.concat(chunks), { status, headers }); Object.defineProperty(result, 'url', { value: url.href }); release(); resolve(result); });
+                        }
+                    });
+                    outgoing.on('error', failed);
+                    outgoing.end(body);
+                }).catch(error => { release(); throw error; });
+                if (!discovery || ![301, 302, 303, 307, 308].includes(response.status))
+                    return response;
+                if (redirects >= limits.maxRedirects)
+                    throw new TransportError('redirect_limit');
+                const location = response.headers.get('location');
+                if (!location)
+                    return response;
+                url = secureUrl(new URL(location, url).href);
+            }
+        }
+        catch (error) {
+            if (closed)
+                throw new TransportError('closed');
+            if (error instanceof TransportError)
+                throw error;
+            throw new TransportError(controller.signal.aborted ? 'timeout' : 'network_error');
+        }
+        finally {
+            if (!transferred)
+                finish();
+        }
+    }
+    return { fetch: (request, settings) => execute(request, settings), stream: request => execute(request, {}, true), close() { closed = true; shutdown.abort(new TransportError('closed')); for (const socket of connecting)
+            socket.destroy(); connecting.clear(); for (const pool of pools.values())
+            pool.agent.destroy(); pools.clear(); } };
+}

package/dist/protocol/sse.d.ts

@@ -0,0 +1,15 @@
+import type { ConversationEvent } from './wire.js';
+export type StreamFrame = {
+    kind: 'event';
+    event: ConversationEvent;
+} | {
+    kind: 'delta';
+    messageId: string;
+    text: string;
+};
+/** One bounded frame at a time. The caller controls reads by advancing the iterator. */
+export declare function parseEventStream(body: ReadableStream<Uint8Array>, options?: {
+    maxFrameBytes?: number;
+    maxStreamBytes?: number;
+    signal?: AbortSignal;
+}): AsyncGenerator<StreamFrame>;

package/dist/protocol/sse.js

@@ -0,0 +1,90 @@
+import { id, object, parseEvent, parseJson, string, ValidationError } from './wire.js';
+/** One bounded frame at a time. The caller controls reads by advancing the iterator. */
+export async function* parseEventStream(body, options = {}) {
+    const maxFrame = options.maxFrameBytes ?? 1048576, maxStream = options.maxStreamBytes ?? 16777216;
+    if (![maxFrame, maxStream].every(value => Number.isSafeInteger(value) && value > 0))
+        throw new TypeError('Invalid stream budget');
+    const reader = body.getReader(), decoder = new TextDecoder('utf-8', { fatal: true });
+    let buffer = '', bytes = 0, frameBytes = 0, data = [], eventType = '', eventId;
+    const abort = () => { void reader.cancel(options.signal?.reason); };
+    options.signal?.addEventListener('abort', abort, { once: true });
+    function frame() {
+        if (!data.length)
+            return;
+        const value = parseJson(data.join('\n'));
+        if (eventType === 'text-delta') {
+            if (eventId !== undefined)
+                throw new ValidationError('sse.delta.id');
+            const delta = object(value);
+            return { kind: 'delta', messageId: id(delta.message_id, 'message_id'), text: string(delta.text, 'text', false) };
+        }
+        const event = parseEvent(value);
+        if (eventId !== event.id)
+            throw new ValidationError('sse.id');
+        return { kind: 'event', event };
+    }
+    try {
+        for (;;) {
+            options.signal?.throwIfAborted();
+            const item = await reader.read();
+            options.signal?.throwIfAborted();
+            if (item.done) {
+                buffer += decoder.decode();
+                if (buffer.endsWith('\r'))
+                    buffer += '\n';
+                else
+                    break;
+            } // Discard an unterminated frame, but CR alone is a valid line ending.
+            bytes += item.value?.byteLength ?? 0;
+            if (bytes > maxStream)
+                throw new ValidationError('sse.stream.size');
+            if (!item.done)
+                buffer += decoder.decode(item.value, { stream: true });
+            for (;;) {
+                const end = buffer.search(/[\r\n]/);
+                if (end < 0)
+                    break;
+                if (buffer[end] === '\r' && end === buffer.length - 1)
+                    break;
+                const line = buffer.slice(0, end), width = buffer[end] === '\r' && buffer[end + 1] === '\n' ? 2 : 1;
+                buffer = buffer.slice(end + width);
+                frameBytes += Buffer.byteLength(line) + width;
+                if (frameBytes > maxFrame)
+                    throw new ValidationError('sse.frame.size');
+                if (!line) {
+                    const result = frame();
+                    data = [];
+                    eventType = '';
+                    eventId = undefined;
+                    frameBytes = 0;
+                    if (result)
+                        yield result;
+                }
+                else if (!line.startsWith(':')) {
+                    const colon = line.indexOf(':'), field = colon < 0 ? line : line.slice(0, colon);
+                    let value = colon < 0 ? '' : line.slice(colon + 1);
+                    if (value.startsWith(' '))
+                        value = value.slice(1);
+                    if (field === 'data')
+                        data.push(value);
+                    else if (field === 'event')
+                        eventType = value;
+                    else if (field === 'id') {
+                        if (value.includes('\0'))
+                            throw new ValidationError('sse.id');
+                        eventId = value;
+                    }
+                }
+            }
+            if (frameBytes + Buffer.byteLength(buffer) > maxFrame)
+                throw new ValidationError('sse.frame.size');
+            if (item.done)
+                break;
+        }
+    }
+    finally {
+        options.signal?.removeEventListener('abort', abort);
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}

package/dist/protocol/wire.d.ts

@@ -0,0 +1,128 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type JsonObject = {
+    [key: string]: Json;
+};
+export type Sender = 'agent' | 'human';
+export type Status = 'working' | 'idle' | 'queued' | 'closed';
+export interface Message {
+    id: string;
+    sender: Sender;
+    text?: string;
+    data?: JsonObject;
+    context?: JsonObject;
+    [key: string]: unknown;
+}
+export interface RecordedMessage extends Message {
+    role: 'user' | 'company';
+}
+export interface ConversationRequest {
+    message: Message;
+    parent_conversation_id?: string;
+    [key: string]: unknown;
+}
+export interface ConversationState {
+    conversation_id: string;
+    status: Status;
+    responder: Sender;
+    [key: string]: unknown;
+}
+export interface ConversationEvent {
+    id: string;
+    type: string;
+    created_at: string;
+    [key: string]: unknown;
+}
+export type KnownEvent = (ConversationEvent & {
+    type: 'message';
+    message: RecordedMessage;
+}) | (ConversationEvent & {
+    type: 'state';
+    status: Status;
+    responder: Sender;
+}) | (ConversationEvent & {
+    type: 'authorization';
+    error: 'sign_in_required';
+    scope?: string;
+}) | (ConversationEvent & {
+    type: 'authorization';
+    error: 'insufficient_scope';
+    scope: string;
+}) | (ConversationEvent & {
+    type: 'user_requested';
+    reason: string;
+}) | (ConversationEvent & {
+    type: 'direct_opened' | 'direct_closed';
+    conversation_id: string;
+});
+export interface EventPage extends ConversationState {
+    events: ConversationEvent[];
+    cursor: string | null;
+    has_more: boolean;
+}
+export interface TokenResponse {
+    access_token: string;
+    token_type: 'DPoP' | 'Bearer';
+    expires_in: number;
+    scope: string;
+    session_id: string;
+    signed_in: boolean;
+    refresh_token?: string;
+    refresh_token_expires_in?: number;
+    [key: string]: unknown;
+}
+export interface ProtocolErrorBody {
+    error: string;
+    error_description?: string;
+    error_uri?: string;
+    extension?: string;
+    conversation_id?: string;
+    [key: string]: unknown;
+}
+export declare class ValidationError extends Error {
+    readonly field: string;
+    constructor(field: string);
+}
+export declare function validateJson(value: unknown): void;
+export declare function object(value: unknown, field?: string): Record<string, unknown>;
+export declare function string(value: unknown, field: string, nonempty?: boolean): string;
+export declare function member(value: unknown, values: readonly unknown[], field: string): void;
+export declare function id(value: unknown, field: string): string;
+export declare function parseMessage(value: unknown, options?: {
+    recorded?: boolean;
+    company?: boolean;
+}): Message | RecordedMessage;
+export declare function parseConversationRequest(value: unknown): ConversationRequest;
+export declare function parseConversationState(value: unknown): ConversationState;
+export declare function parseEvent(value: unknown): ConversationEvent;
+export declare function parseEventPage(value: unknown, requestCursor?: string): EventPage;
+export declare function parseTokenResponse(value: unknown): TokenResponse;
+export declare function parseProtocolError(value: unknown): ProtocolErrorBody;
+export declare function parseReadOptions(url: URL, maxWaitSeconds: number): {
+    cursor?: string;
+    waitSeconds: number;
+};
+export declare function retryAfterMilliseconds(value: string | null, nowMs: number): number | undefined;
+export interface AssertionClaims {
+    iss: string;
+    sub: string;
+    aud: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    [key: string]: unknown;
+}
+export interface DpopClaims {
+    jti: string;
+    htm: string;
+    htu: string;
+    iat: number;
+    ath?: string;
+    nonce?: string;
+    [key: string]: unknown;
+}
+export declare function parseAssertionClaims(value: unknown): AssertionClaims;
+export declare function parseDpopClaims(value: unknown): DpopClaims;
+export declare function canonical(value: unknown): string;
+export declare function parseJson(text: string): unknown;