@attestry/sdk 0.6.0

package/dist/sse-parser.js

@@ -0,0 +1,271 @@
+// ─── Server-Sent Events parser ──────────────────────────────────────────────
+//
+// Generic SSE frame parser used by streaming resources (today: decisions.stream;
+// future: any other text/event-stream endpoint). Reads from a
+// `ReadableStreamDefaultReader<Uint8Array>` and yields parsed frames.
+//
+// Spec: https://html.spec.whatwg.org/multipage/server-sent-events.html
+// Subset implemented:
+//   - `id:`, `event:`, `data:` field lines (the three the kernel emits today)
+//   - Multi-`data:` line concatenation (joined with `\n` per spec)
+//   - Comment lines (`:` prefix) — silently dropped (heartbeat handling)
+//   - Frames separated by blank line (`\n\n`, `\r\n\r\n`, or `\r\r`)
+//   - UTF-8 decoded with `{stream: true}` so multibyte chars split across
+//     reads recombine correctly
+// Subset deliberately NOT implemented:
+//   - `retry:` field (would map to a reconnect-delay hint; we don't
+//     auto-reconnect today — caller manages reconnection by passing the
+//     last seen event id back as `lastEventId`)
+//   - `BOM` stripping at the very first byte (the kernel's text/event-stream
+//     never emits a BOM; defensive at the parser level would be over-spec)
+//
+// The parser is INTENTIONALLY lax about the optional space after the colon:
+// `data:foo` and `data: foo` both yield `foo`. The W3C spec (§ 9.2.6) says
+// "If value starts with a U+0020 SPACE character, remove it." — implemented.
+import { AttestryError } from "./errors.js";
+/**
+ * Maximum buffer size before the parser bails. Defense against a server
+ * that emits an unbounded frame (no `\n\n` boundary) — without a cap, the
+ * parser would buffer until the consumer's process runs out of memory.
+ * 1 MiB is generous: the kernel's frame payload is ~500 bytes today, so
+ * 1 MiB is ~2000× headroom. A real-world SSE event larger than this is
+ * either a server bug or a hostile peer.
+ *
+ * Configurable via `parseSSE`'s `maxBufferBytes` option for callers
+ * with legitimate large-frame use cases (none today). Hostile-review H3.
+ */
+const DEFAULT_MAX_BUFFER_BYTES = 1024 * 1024;
+/**
+ * Async generator: reads from a stream of UTF-8-encoded SSE bytes and
+ * yields each complete frame. Ends when the underlying reader signals
+ * `done`. Defensive: a caller that breaks early out of the for-await
+ * loop leaves the reader open — call `reader.cancel()` from your finally
+ * block (or use the `parseSSEResponse` wrapper below which handles it).
+ *
+ * @throws AttestryError if a frame line is malformed past recovery (no
+ *         such case in the kernel's emitter today; future-proofing); OR
+ *         if the buffer exceeds `maxBufferBytes` (defense against
+ *         unbounded-frame DoS — hostile-review H3).
+ */
+export async function* parseSSE(reader, options = {}) {
+    const maxBufferBytes = options.maxBufferBytes ?? DEFAULT_MAX_BUFFER_BYTES;
+    const decoder = new TextDecoder("utf-8");
+    let buffer = "";
+    let bomStripped = false;
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done) {
+            // Flush any final bytes (no-op if value was always complete).
+            buffer += decoder.decode();
+            // A final unterminated frame is dropped per SSE spec § 9.2.4
+            // ("If the end of the file is reached, then dispatch the event and
+            // proceed."). Be permissive and emit the trailing block if it has
+            // content — an HTTP/1.1 connection-close mid-frame is the most
+            // common failure mode and dropping the partial event silently is
+            // worse than emitting an under-defined one.
+            if (buffer.length > 0) {
+                const frame = parseFrameBlock(buffer);
+                if (frame !== null)
+                    yield frame;
+            }
+            return;
+        }
+        if (value === undefined)
+            continue;
+        // `{stream: true}` carries multi-byte boundaries across chunks.
+        buffer += decoder.decode(value, { stream: true });
+        // Strip a leading BOM (U+FEFF) if present. Kernel doesn't emit BOM
+        // today, but a misconfigured proxy / character-set transcoder
+        // could prepend one. Without this strip, the first frame's first
+        // field would be e.g. `"id"` instead of `"id"` and silently
+        // drop. Hostile-review H4. One-shot — only at the very first
+        // decoded codepoint of the stream.
+        //
+        // Hostile-review fix (parallel to ndjson-parser): `bomStripped` is
+        // only flipped once we've actually decoded at least one character.
+        // Otherwise an empty / partial-multibyte first read would set the
+        // flag prematurely; if the BOM bytes arrived in a later read, the
+        // strip-attempt would be skipped. Defense-in-depth — String.prototype.trim
+        // and TextDecoder("utf-8")'s default stream-start BOM handling
+        // mask the consumer-visible bug today, but a future TextDecoder
+        // change (e.g. `ignoreBOM: true`) would unmask it.
+        if (!bomStripped && buffer.length > 0) {
+            bomStripped = true;
+            // Defense-in-depth dead path: same rationale as
+            // ndjson-parser.ts — TextDecoder strips stream-start BOM
+            // internally, so the slice below is unreachable in Node 18+.
+            // Marked for v8 coverage to make the intentional defense visible;
+            // a future `{ignoreBOM: true}` decoder OR a buffer path that
+            // bypasses TextDecoder would unmask it.
+            /* v8 ignore next 3 */
+            if (buffer.charCodeAt(0) === 0xfeff) {
+                buffer = buffer.slice(1);
+            }
+        }
+        // Defense in depth: if the buffer grew past the cap WITHOUT
+        // a frame boundary, abort rather than spin until OOM. Hostile-
+        // review H3.
+        if (buffer.length > maxBufferBytes) {
+            throw new AttestryError(`SSE frame exceeded maximum buffer size (${maxBufferBytes} bytes) — server emitted an unbounded frame or omitted the boundary delimiter`);
+        }
+        // Find frame boundaries. Spec allows `\r\n\r\n`, `\n\n`, or `\r\r`
+        // as the separator. Scan with a regex that accepts any.
+        while (true) {
+            const match = FRAME_BOUNDARY.exec(buffer);
+            if (match === null)
+                break;
+            const block = buffer.slice(0, match.index);
+            buffer = buffer.slice(match.index + match[0].length);
+            if (block.length === 0)
+                continue; // back-to-back blank lines
+            const frame = parseFrameBlock(block);
+            if (frame !== null)
+                yield frame;
+        }
+    }
+}
+/**
+ * Convenience wrapper around `parseSSE` that accepts a `Response`,
+ * derives the reader, and ALWAYS calls `reader.cancel()` in a `finally`
+ * block — including when a caller breaks out of the for-await loop
+ * early. Without this, an early `break` leaks the underlying connection.
+ *
+ * Resources should call this rather than `parseSSE` directly.
+ */
+export async function* parseSSEResponse(response, options = {}) {
+    if (response.body === null) {
+        // 204 No Content / empty body — iterator ends with zero frames.
+        // Consumer's for-await loop runs zero times. (Throwing here would
+        // be over-strict; the server may legitimately close before any data.)
+        return;
+    }
+    const reader = response.body.getReader();
+    try {
+        yield* parseSSE(reader, options);
+    }
+    finally {
+        // Release the lock + signal cancellation upstream. Wrapped in
+        // try/catch because cancel() on an already-closed reader rejects.
+        try {
+            await reader.cancel();
+        }
+        catch {
+            // Already canceled / closed — nothing to do.
+        }
+    }
+}
+// ─── Internals ──────────────────────────────────────────────────────────────
+/**
+ * One block of SSE text (delimited by blank line) → a parsed frame, or
+ * `null` if the block was nothing but comments / whitespace.
+ *
+ * Per spec:
+ *   - Lines beginning with `:` are comments, ignored.
+ *   - Otherwise split on first `:` into `field` + `value`.
+ *   - If `value` starts with U+0020 SPACE, remove ONE leading space.
+ *   - Multiple `data:` lines accumulate, joined by `\n`.
+ *   - Field names other than `id`, `event`, `data`, `retry` are ignored.
+ */
+function parseFrameBlock(block) {
+    let id;
+    let eventType;
+    let dataLines = null;
+    let sawNonComment = false;
+    // Split on any of `\r\n`, `\n`, or `\r` per spec. Use a character
+    // class regex so we don't hit the trailing-empty-string edge case
+    // that String.split with a multi-char separator can produce.
+    for (const line of block.split(/\r\n|\n|\r/)) {
+        if (line.length === 0)
+            continue;
+        if (line[0] === ":")
+            continue; // comment
+        sawNonComment = true;
+        const colonIdx = line.indexOf(":");
+        let field;
+        let value;
+        if (colonIdx === -1) {
+            // Per spec: "If line contains no U+003A COLON character, set field to
+            // line and value to the empty string." — we don't recognize any
+            // value-less fields today, so silently drop these.
+            field = line;
+            value = "";
+        }
+        else {
+            field = line.slice(0, colonIdx);
+            value = line.slice(colonIdx + 1);
+            if (value.length > 0 && value[0] === " ")
+                value = value.slice(1);
+        }
+        switch (field) {
+            case "id":
+                // Per spec: "If the field value does not contain U+0000 NULL,
+                // then set the last event ID buffer to the field value."
+                if (!value.includes(""))
+                    id = value;
+                break;
+            case "event":
+                eventType = value;
+                break;
+            case "data":
+                if (dataLines === null)
+                    dataLines = [];
+                dataLines.push(value);
+                break;
+            case "retry":
+                // Reconnect-delay hint. Not implemented — see file header.
+                break;
+            default:
+                // Unknown field — silently ignored per spec. Don't throw; future
+                // server-side fields shouldn't break consumers.
+                break;
+        }
+    }
+    if (!sawNonComment)
+        return null;
+    // Defense in depth: if EVERY non-comment line was an unrecognized
+    // field, we still produced no data. Emitting an empty-data event is
+    // confusing — drop. Consumer never has to handle a frame with no
+    // content. (SSE spec strictly says emit anyway, but our wire shape
+    // always carries data.)
+    if (dataLines === null) {
+        if (id === undefined && eventType === undefined)
+            return null;
+        // id-only or event-only is unusual but valid — the kernel doesn't
+        // emit these today, but defensively pass them through with empty data
+        // rather than swallowing the metadata entirely.
+        return { id, event: eventType, data: "" };
+    }
+    return {
+        id,
+        event: eventType,
+        data: dataLines.join("\n"),
+    };
+}
+/**
+ * Frame-boundary regex — matches `\r\n\r\n`, `\n\n`, or `\r\r` per spec.
+ * Exported only for tests.
+ */
+const FRAME_BOUNDARY = /\r\n\r\n|\n\n|\r\r/g;
+/**
+ * Parse a `data:` payload as JSON. Throws `AttestryError` (with the
+ * underlying error as `cause`) if the payload isn't valid JSON. Resources
+ * call this when the wire shape is documented as JSON-encoded.
+ */
+export function parseSSEData(data) {
+    try {
+        return JSON.parse(data);
+    }
+    catch (err) {
+        throw new AttestryError(`SSE frame data was not valid JSON: ${
+        // JSON.parse always throws SyntaxError (an Error subclass), so
+        // the String(err) branch is unreachable. Defense-in-depth.
+        /* v8 ignore next */
+        err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
+// Test-only handles for direct pinning of internals.
+export const __test__ = {
+    FRAME_BOUNDARY,
+    parseFrameBlock,
+};
+//# sourceMappingURL=sse-parser.js.map

package/dist/sse-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-parser.js","sourceRoot":"","sources":["../src/sse-parser.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,142 @@
+import { type RetryOptions } from "./retry.js";
+import type { AttestryClientOptions, FetchLike, RequestOptions } from "./types.js";
+interface ResolvedClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    fetchImpl: FetchLike;
+    timeoutMs: number;
+    retry: Partial<RetryOptions> | undefined;
+}
+/**
+ * Validates options at construction time. Surfaces every misconfiguration
+ * as `AttestryError` BEFORE any request is made — fail-fast beats failing
+ * deep in the resource methods. Used by `AttestryClient` constructor.
+ */
+export declare function resolveClientConfig(options: AttestryClientOptions): ResolvedClientConfig;
+/**
+ * Internal — exported for tests. Composes a URL safely from baseUrl + path.
+ * Caller-supplied `path` may or may not start with `/`; either way works.
+ */
+export declare function composeUrl(baseUrl: string, path: string): string;
+interface InternalRequestArgs {
+    config: ResolvedClientConfig;
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    path: string;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    options?: RequestOptions;
+    /**
+     * P3 hardening: expected response Content-Type for the 2xx success
+     * path. Defaults to `"application/json"`. The transport's success
+     * path checks the response's Content-Type header against this value
+     * (MIME-type prefix only, parameter-tolerant for `; charset=utf-8`)
+     * and throws `AttestryAPIError` on mismatch — fail-fast against a
+     * misbehaving proxy / load balancer that returns 200 OK with an
+     * HTML error page or text/plain body. Pre-P3 the SDK silently
+     * resolved with `null` (or whatever JSON.parse returned) for
+     * wrong-content-type responses; consumers crashed downstream with
+     * a confusing TypeError. Now consumers receive a clear
+     * AttestryAPIError naming the expected and actual content-type.
+     *
+     * Skipped for 204 No Content and 304 Not Modified (no body to
+     * validate). Error path (non-2xx) is unchanged — the existing
+     * error-body parser still falls back to raw text for non-JSON
+     * error bodies (see hostile-review H1 pin in transport.test.ts).
+     *
+     * Symmetric with `streamRequestOnce`'s `expectedContentType` param
+     * (which defaults to `text/event-stream` for SSE). Both use the
+     * same MIME-type-extraction algorithm to defend against superset /
+     * parameter-injection / structured-suffix attacks.
+     */
+    expectedContentType?: string;
+}
+/**
+ * Public request runner. Wraps the single-attempt `requestOnce` with the
+ * retry loop. Resources should NOT import this directly — they go
+ * through `AttestryClient._request`.
+ *
+ * Retry behavior: on 429 only (today). The retry loop honors the caller's
+ * abort signal — `signal.abort()` during the backoff sleep rejects with
+ * `AttestryError("request aborted by caller")` rather than completing
+ * the wait.
+ */
+export declare function request<T>(args: InternalRequestArgs): Promise<T>;
+/**
+ * Internal single-attempt request runner. Exposed under `__test__` for
+ * unit pinning.
+ */
+export declare function requestOnce<T>(args: InternalRequestArgs): Promise<T>;
+/**
+ * Streaming-response request — used for any long-lived streaming endpoint
+ * (SSE, NDJSON). Mirrors `request` for header / signal / URL composition
+ * but:
+ *
+ *   - Hardcodes `method: "GET"` (streaming endpoints today are read-only).
+ *   - Sends `Accept: <expectedContentType>` (default `text/event-stream`
+ *     for SSE backward-compat; NDJSON callers pass
+ *     `application/x-ndjson`).
+ *   - Does NOT arm an internal timeout — streams are long-lived; the
+ *     30s default would kill them after half a minute. Caller controls
+ *     duration via `options.signal`. (`decisions.export` runs up to
+ *     5 minutes server-side.)
+ *   - Returns the un-consumed `Response` so the resource can read
+ *     `response.body` as a stream of bytes (for an SSE / NDJSON parser).
+ *   - On non-2xx, drains the body and throws `AttestryAPIError` exactly
+ *     like the JSON path so consumers see the same error shape.
+ *   - On a 2xx with the WRONG content-type, throws with a clear message —
+ *     defensive against a misconfigured proxy returning `text/html` (LB
+ *     error page) or `text/plain`. The kernel always sets the right
+ *     content-type for each route, so this is a fail-fast guard. The
+ *     `expectedContentType` parameter (default `text/event-stream`)
+ *     drives both the `Accept:` request header AND this guard, so SSE
+ *     callers reject NDJSON responses and vice versa — a single source
+ *     of truth.
+ *
+ * Retry semantics: the INITIAL fetch goes through the retry wrapper
+ * (same 429 logic as `request<T>`). Once the response is open,
+ * mid-iteration errors do NOT retry — events would be lost or
+ * duplicated without per-event idempotency. Caller manages reconnection
+ * by passing the last seen cursor back (e.g., SSE `lastEventId`,
+ * NDJSON: re-issue with adjusted filters).
+ */
+export declare function streamRequest(args: {
+    config: ResolvedClientConfig;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    headers?: Record<string, string>;
+    options?: RequestOptions;
+    /**
+     * Substring (case-insensitive) the response's `Content-Type` header
+     * must contain to pass the fail-fast guard. ALSO drives the request's
+     * `Accept:` header. Defaults to `"text/event-stream"` for SSE
+     * backward-compat. NDJSON callers (`decisions.export`) pass
+     * `"application/x-ndjson"`. Single source of truth — same value
+     * everywhere keeps SSE callers from accidentally accepting NDJSON
+     * responses and vice versa.
+     */
+    expectedContentType?: string;
+}): Promise<Response>;
+declare function encodeQuery(q: Record<string, string | number | boolean | undefined | null> | undefined): string;
+/**
+ * Reads the response body and tries to parse as JSON. Returns BOTH the
+ * parsed value (or null on parse failure / empty body) AND the raw text.
+ * Callers on the success path use only `parsed`; callers on the error
+ * path fall back to `raw` when `parsed` is null so non-JSON error bodies
+ * (LB 502 HTML, plain-text proxy errors) are surfaced as
+ * `AttestryAPIError.details` rather than silently lost. (Hostile-review
+ * H1.)
+ */
+declare function readBody(response: Response): Promise<{
+    parsed: unknown;
+    raw: string;
+}>;
+declare function extractMessage(detail: unknown): string | null;
+export declare const __test__: {
+    DEFAULT_BASE_URL: string;
+    DEFAULT_TIMEOUT_MS: number;
+    encodeQuery: typeof encodeQuery;
+    readBody: typeof readBody;
+    extractMessage: typeof extractMessage;
+};
+export {};
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AA6BA,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,qBAAqB,EACrB,SAAS,EACT,cAAc,EACf,MAAM,YAAY,CAAC;AAKpB,UAAU,oBAAoB;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,SAAS,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CAwCtB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhE;AAED,UAAU,mBAAmB;IAC3B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBtE;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CA8I1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyBpB;AA+HD,iBAAS,WAAW,CAClB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,SAAS,GAC1E,MAAM,CAQR;AAED;;;;;;;;GAQG;AACH,iBAAe,QAAQ,CACrB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAS3C;AAED,iBAAS,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CActD;AAcD,eAAO,MAAM,QAAQ;;;;;;CAMpB,CAAC"}