phenoml 17.7.0 → 17.9.0

package/dist/esm/core/stream/Stream.mjs

@@ -36,8 +36,14 @@ import { fromJson } from "../json.mjs";
 import { RUNTIME } from "../runtime/index.mjs";
 const DATA_PREFIX = "data:";
 const EVENT_PREFIX = "event:";
+const ID_PREFIX = "id:";
+const RETRY_PREFIX = "retry:";
+const DEFAULT_MAX_RECONNECTION_ATTEMPTS = 5;
+const DEFAULT_RECONNECT_DELAY_MS = 1000;
+const MAX_RECONNECT_DELAY_MS = 30000;
 export class Stream {
-    constructor({ stream, parse, eventShape, signal }) {
+    constructor({ stream, parse, eventShape, signal, reconnectionEnabled, maxReconnectionAttempts, reconnect, }) {
+        var _a;
         this.controller = new AbortController();
         this.stream = stream;
         this.parse = parse;
@@ -46,11 +52,20 @@ export class Stream {
             this.messageTerminator = "\n";
             this.streamTerminator = eventShape.streamTerminator;
             this.eventDiscriminator = eventShape.eventDiscriminator;
+            this.resumable = (_a = eventShape.resumable) !== null && _a !== void 0 ? _a : false;
         }
         else {
             this.messageTerminator = eventShape.messageTerminator;
+            this.resumable = false;
+        }
+        this.reconnectionEnabled = reconnectionEnabled !== null && reconnectionEnabled !== void 0 ? reconnectionEnabled : true;
+        this.maxReconnectionAttempts = maxReconnectionAttempts !== null && maxReconnectionAttempts !== void 0 ? maxReconnectionAttempts : DEFAULT_MAX_RECONNECTION_ATTEMPTS;
+        this.reconnect = reconnect;
+        if (signal != null) {
+            this.externalSignal = signal;
+            this.onExternalAbort = () => this.controller.abort();
+            signal.addEventListener("abort", this.onExternalAbort, { once: true });
         }
-        signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", () => this.controller.abort());
         // Initialize shared TextDecoder
         if (typeof TextDecoder !== "undefined") {
             this.decoder = new TextDecoder("utf-8");
@@ -69,98 +84,227 @@ export class Stream {
     iterDataMessages() {
         return __asyncGenerator(this, arguments, function* iterDataMessages_1() {
             var _a, e_1, _b, _c;
-            const stream = readableStreamAsyncIterable(this.stream);
-            let buf = "";
-            let prefixSeen = false;
-            try {
-                for (var _d = true, stream_1 = __asyncValues(stream), stream_1_1; stream_1_1 = yield __await(stream_1.next()), _a = stream_1_1.done, !_a; _d = true) {
-                    _c = stream_1_1.value;
-                    _d = false;
-                    const chunk = _c;
-                    buf += this.decodeChunk(chunk);
-                    let terminatorIndex;
-                    while ((terminatorIndex = buf.indexOf(this.messageTerminator)) >= 0) {
-                        let line = buf.slice(0, terminatorIndex);
-                        buf = buf.slice(terminatorIndex + this.messageTerminator.length);
-                        if (!line.trim()) {
-                            continue;
-                        }
-                        if (!prefixSeen && this.prefix != null) {
-                            const prefixIndex = line.indexOf(this.prefix);
-                            if (prefixIndex === -1) {
+            let reconnectAttempts = 0;
+            let currentStream = this.stream;
+            let lastId;
+            // The id of the most recently *dispatched* event. Per the WHATWG
+            // EventSource spec, the "last event ID" is only committed when an event
+            // is dispatched, not when the `id:` line is parsed. Reconnecting with a
+            // parsed-but-undispatched id would skip an event that was never yielded
+            // (e.g. if the connection drops after `id:` but before the event's
+            // terminating blank line), so reconnection uses lastDispatchedId.
+            let lastDispatchedId;
+            let lastRetry;
+            while (true) {
+                const stream = readableStreamAsyncIterable(currentStream);
+                let buf = "";
+                let dataValue;
+                try {
+                    for (var _d = true, stream_1 = (e_1 = void 0, __asyncValues(stream)), stream_1_1; stream_1_1 = yield __await(stream_1.next()), _a = stream_1_1.done, !_a; _d = true) {
+                        _c = stream_1_1.value;
+                        _d = false;
+                        const chunk = _c;
+                        buf += this.decodeChunk(chunk);
+                        let terminatorIndex;
+                        while ((terminatorIndex = buf.indexOf(this.messageTerminator)) >= 0) {
+                            const line = buf.slice(0, terminatorIndex);
+                            buf = buf.slice(terminatorIndex + this.messageTerminator.length);
+                            if (!line.trim()) {
+                                if (this.prefix != null && dataValue != null) {
+                                    if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+                                        return yield __await(void 0);
+                                    }
+                                    const data = yield __await(this.parse(fromJson(dataValue)));
+                                    yield yield __await({ data, id: lastId, retry: lastRetry, event: undefined });
+                                    lastDispatchedId = lastId;
+                                    reconnectAttempts = 0;
+                                    dataValue = undefined;
+                                }
                                 continue;
                             }
-                            prefixSeen = true;
-                            line = line.slice(prefixIndex + this.prefix.length);
-                        }
-                        if (this.streamTerminator != null && line.includes(this.streamTerminator)) {
-                            return yield __await(void 0);
+                            if (line.startsWith(ID_PREFIX)) {
+                                const idValue = line.slice(ID_PREFIX.length).trim();
+                                if (!idValue.includes("\0")) {
+                                    lastId = idValue;
+                                }
+                                continue;
+                            }
+                            if (line.startsWith(RETRY_PREFIX)) {
+                                const retryValue = line.slice(RETRY_PREFIX.length).trim();
+                                const parsed = parseInt(retryValue, 10);
+                                if (!Number.isNaN(parsed) && String(parsed) === retryValue) {
+                                    lastRetry = parsed;
+                                }
+                                continue;
+                            }
+                            if (this.prefix != null) {
+                                const prefixIndex = line.indexOf(this.prefix);
+                                if (prefixIndex === -1) {
+                                    continue;
+                                }
+                                const val = line.slice(prefixIndex + this.prefix.length).trim();
+                                dataValue = dataValue != null ? `${dataValue}\n${val}` : val;
+                            }
+                            else {
+                                if (this.streamTerminator != null && line.includes(this.streamTerminator)) {
+                                    return yield __await(void 0);
+                                }
+                                const data = yield __await(this.parse(fromJson(line)));
+                                yield yield __await({ data, id: lastId, retry: lastRetry, event: undefined });
+                                lastDispatchedId = lastId;
+                                reconnectAttempts = 0;
+                            }
                         }
-                        const message = yield __await(this.parse(fromJson(line)));
-                        yield yield __await(message);
-                        prefixSeen = false;
                     }
                 }
-            }
-            catch (e_1_1) { e_1 = { error: e_1_1 }; }
-            finally {
+                catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
+                    }
+                    finally { if (e_1) throw e_1.error; }
+                }
+                if (this.prefix != null && dataValue != null) {
+                    if (this.streamTerminator != null && dataValue.includes(this.streamTerminator)) {
+                        return yield __await(void 0);
+                    }
+                    const data = yield __await(this.parse(fromJson(dataValue)));
+                    yield yield __await({ data, id: lastId, retry: lastRetry, event: undefined });
+                    lastDispatchedId = lastId;
+                    reconnectAttempts = 0;
+                }
+                if (!this.shouldReconnect(lastDispatchedId, reconnectAttempts)) {
+                    return yield __await(void 0);
+                }
+                reconnectAttempts++;
+                yield __await(this.delayReconnect(lastRetry));
+                if (this.controller.signal.aborted) {
+                    return yield __await(void 0);
+                }
+                // Re-check after async delay; needed for TypeScript narrowing.
+                const reconnectFn = this.reconnect;
+                if (reconnectFn == null || lastDispatchedId == null) {
+                    return yield __await(void 0);
+                }
                 try {
-                    if (!_d && !_a && (_b = stream_1.return)) yield __await(_b.call(stream_1));
+                    const reconnected = yield __await(reconnectFn(lastDispatchedId));
+                    if (reconnected == null) {
+                        currentStream = this.createEmptyStream();
+                        continue;
+                    }
+                    currentStream = reconnected;
+                }
+                catch (_e) {
+                    // Failed reconnect (e.g. HTTP error); assign an empty stream
+                    // so the next iteration is a safe no-op before shouldReconnect.
+                    currentStream = this.createEmptyStream();
                 }
-                finally { if (e_1) throw e_1.error; }
             }
         });
     }
     iterSseEvents() {
         return __asyncGenerator(this, arguments, function* iterSseEvents_1() {
             var _a, e_2, _b, _c;
-            const stream = readableStreamAsyncIterable(this.stream);
-            let buf = "";
-            let eventType;
-            let dataValue;
-            try {
-                for (var _d = true, stream_2 = __asyncValues(stream), stream_2_1; stream_2_1 = yield __await(stream_2.next()), _a = stream_2_1.done, !_a; _d = true) {
-                    _c = stream_2_1.value;
-                    _d = false;
-                    const chunk = _c;
-                    buf += this.decodeChunk(chunk);
-                    let terminatorIndex;
-                    while ((terminatorIndex = buf.indexOf("\n")) >= 0) {
-                        const line = buf.slice(0, terminatorIndex).replace(/\r$/, "");
-                        buf = buf.slice(terminatorIndex + 1);
-                        if (!line.trim()) {
-                            if (dataValue != null) {
-                                const message = yield __await(this.dispatchSseEvent(dataValue, eventType));
-                                if (message == null) {
-                                    return yield __await(void 0);
+            let reconnectAttempts = 0;
+            let currentStream = this.stream;
+            let lastId;
+            // See iterDataMessages: reconnection uses the last *dispatched* id (per
+            // the EventSource spec), not the last *parsed* id, to avoid skipping an
+            // event that was never yielded when a drop lands mid-event.
+            let lastDispatchedId;
+            let lastRetry;
+            while (true) {
+                const stream = readableStreamAsyncIterable(currentStream);
+                let buf = "";
+                let eventType;
+                let dataValue;
+                try {
+                    for (var _d = true, stream_2 = (e_2 = void 0, __asyncValues(stream)), stream_2_1; stream_2_1 = yield __await(stream_2.next()), _a = stream_2_1.done, !_a; _d = true) {
+                        _c = stream_2_1.value;
+                        _d = false;
+                        const chunk = _c;
+                        buf += this.decodeChunk(chunk);
+                        let terminatorIndex;
+                        while ((terminatorIndex = buf.indexOf("\n")) >= 0) {
+                            const line = buf.slice(0, terminatorIndex).replace(/\r$/, "");
+                            buf = buf.slice(terminatorIndex + 1);
+                            if (!line.trim()) {
+                                if (dataValue != null) {
+                                    const data = yield __await(this.dispatchSseEvent(dataValue, eventType));
+                                    if (data == null) {
+                                        return yield __await(void 0);
+                                    }
+                                    yield yield __await({ data, id: lastId, retry: lastRetry, event: eventType });
+                                    lastDispatchedId = lastId;
+                                    reconnectAttempts = 0;
+                                }
+                                eventType = undefined;
+                                dataValue = undefined;
+                                continue;
+                            }
+                            if (line.startsWith(EVENT_PREFIX)) {
+                                eventType = line.slice(EVENT_PREFIX.length).trim();
+                            }
+                            else if (line.startsWith(DATA_PREFIX)) {
+                                const val = line.slice(DATA_PREFIX.length).trim();
+                                dataValue = dataValue != null ? `${dataValue}\n${val}` : val;
+                            }
+                            else if (line.startsWith(ID_PREFIX)) {
+                                const idValue = line.slice(ID_PREFIX.length).trim();
+                                if (!idValue.includes("\0")) {
+                                    lastId = idValue;
+                                }
+                            }
+                            else if (line.startsWith(RETRY_PREFIX)) {
+                                const retryValue = line.slice(RETRY_PREFIX.length).trim();
+                                const parsed = parseInt(retryValue, 10);
+                                if (!Number.isNaN(parsed) && String(parsed) === retryValue) {
+                                    lastRetry = parsed;
                                 }
-                                yield yield __await(message);
                             }
-                            eventType = undefined;
-                            dataValue = undefined;
-                            continue;
-                        }
-                        if (line.startsWith(EVENT_PREFIX)) {
-                            eventType = line.slice(EVENT_PREFIX.length).trim();
-                        }
-                        else if (line.startsWith(DATA_PREFIX)) {
-                            const val = line.slice(DATA_PREFIX.length).trim();
-                            dataValue = dataValue != null ? `${dataValue}\n${val}` : val;
                         }
                     }
                 }
-            }
-            catch (e_2_1) { e_2 = { error: e_2_1 }; }
-            finally {
+                catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                finally {
+                    try {
+                        if (!_d && !_a && (_b = stream_2.return)) yield __await(_b.call(stream_2));
+                    }
+                    finally { if (e_2) throw e_2.error; }
+                }
+                if (dataValue != null) {
+                    const data = yield __await(this.dispatchSseEvent(dataValue, eventType));
+                    if (data != null) {
+                        yield yield __await({ data, id: lastId, retry: lastRetry, event: eventType });
+                        lastDispatchedId = lastId;
+                        reconnectAttempts = 0;
+                    }
+                }
+                if (!this.shouldReconnect(lastDispatchedId, reconnectAttempts)) {
+                    return yield __await(void 0);
+                }
+                reconnectAttempts++;
+                yield __await(this.delayReconnect(lastRetry));
+                if (this.controller.signal.aborted) {
+                    return yield __await(void 0);
+                }
+                // Re-check after async delay; needed for TypeScript narrowing.
+                const reconnectFn = this.reconnect;
+                if (reconnectFn == null || lastDispatchedId == null) {
+                    return yield __await(void 0);
+                }
                 try {
-                    if (!_d && !_a && (_b = stream_2.return)) yield __await(_b.call(stream_2));
+                    const reconnected = yield __await(reconnectFn(lastDispatchedId));
+                    if (reconnected == null) {
+                        currentStream = this.createEmptyStream();
+                        continue;
+                    }
+                    currentStream = reconnected;
                 }
-                finally { if (e_2) throw e_2.error; }
-            }
-            if (dataValue != null) {
-                const message = yield __await(this.dispatchSseEvent(dataValue, eventType));
-                if (message != null) {
-                    yield yield __await(message);
+                catch (_e) {
+                    // Failed reconnect (e.g. HTTP error); assign an empty stream
+                    // so the next iteration is a safe no-op before shouldReconnect.
+                    currentStream = this.createEmptyStream();
                 }
             }
         });
@@ -176,6 +320,96 @@ export class Stream {
             return this.parse(this.injectDiscriminator(fromJson(dataValue), eventType));
         });
     }
+    /**
+     * Determines whether a reconnection attempt should be made.
+     */
+    shouldReconnect(lastId, reconnectAttempts) {
+        if (!this.resumable) {
+            return false;
+        }
+        if (this.streamTerminator == null) {
+            // Without a terminator the client cannot distinguish a completed
+            // stream from a dropped connection, so reconnection is disabled.
+            return false;
+        }
+        // NOTE: When a terminator IS configured but the server never sends it
+        // (e.g. it drops the connection after emitting events every time),
+        // maxReconnectionAttempts is a per-consecutive-failure cap — each
+        // yielded event resets the counter. This matches EventSource semantics
+        // but means such a server can cause unbounded reconnections. Callers
+        // concerned about this should impose a wall-clock budget externally.
+        if (!this.reconnectionEnabled) {
+            return false;
+        }
+        if (this.reconnect == null) {
+            return false;
+        }
+        if (lastId == null || lastId === "") {
+            return false;
+        }
+        if (reconnectAttempts >= this.maxReconnectionAttempts) {
+            return false;
+        }
+        if (this.controller.signal.aborted) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Delays before reconnecting, using a server-sent retry directive if provided
+     * (clamped to MAX_RECONNECT_DELAY_MS), otherwise falling back to
+     * DEFAULT_RECONNECT_DELAY_MS. The delay is abortable: if the stream's abort
+     * signal fires during the wait, the promise resolves immediately.
+     */
+    delayReconnect(lastRetry) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const base = lastRetry != null && lastRetry > 0 ? lastRetry : DEFAULT_RECONNECT_DELAY_MS;
+            const delay = Math.min(base, MAX_RECONNECT_DELAY_MS);
+            const signal = this.controller.signal;
+            if (signal.aborted) {
+                return;
+            }
+            yield new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    signal.removeEventListener("abort", onAbort);
+                    resolve();
+                }, delay);
+                const onAbort = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+                signal.addEventListener("abort", onAbort, { once: true });
+            });
+        });
+    }
+    createEmptyStream() {
+        return new ReadableStream({
+            start(controller) {
+                controller.close();
+            },
+        });
+    }
+    removeAbortListener() {
+        if (this.externalSignal != null && this.onExternalAbort != null) {
+            this.externalSignal.removeEventListener("abort", this.onExternalAbort);
+            this.onExternalAbort = undefined;
+        }
+    }
+    withMetadata() {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return __asyncGenerator(this, arguments, function* _a() {
+                    try {
+                        yield __await(yield* __asyncDelegator(__asyncValues(self.iterMessages())));
+                    }
+                    finally {
+                        self.removeAbortListener();
+                    }
+                });
+            },
+        };
+    }
     injectDiscriminator(parsed, eventType) {
         if (this.eventDiscriminator == null || eventType == null) {
             return parsed;
@@ -193,19 +427,24 @@ export class Stream {
         return __asyncGenerator(this, arguments, function* _a() {
             var _b, e_3, _c, _d;
             try {
-                for (var _e = true, _f = __asyncValues(this.iterMessages()), _g; _g = yield __await(_f.next()), _b = _g.done, !_b; _e = true) {
-                    _d = _g.value;
-                    _e = false;
-                    const message = _d;
-                    yield yield __await(message);
+                try {
+                    for (var _e = true, _f = __asyncValues(this.iterMessages()), _g; _g = yield __await(_f.next()), _b = _g.done, !_b; _e = true) {
+                        _d = _g.value;
+                        _e = false;
+                        const event = _d;
+                        yield yield __await(event.data);
+                    }
+                }
+                catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                finally {
+                    try {
+                        if (!_e && !_b && (_c = _f.return)) yield __await(_c.call(_f));
+                    }
+                    finally { if (e_3) throw e_3.error; }
                 }
             }
-            catch (e_3_1) { e_3 = { error: e_3_1 }; }
             finally {
-                try {
-                    if (!_e && !_b && (_c = _f.return)) yield __await(_c.call(_f));
-                }
-                finally { if (e_3) throw e_3.error; }
+                this.removeAbortListener();
             }
         });
     }

package/dist/esm/core/stream/index.d.mts

@@ -1 +1,2 @@
+export type { ServerSentEvent } from "./Stream.mjs";
 export { Stream } from "./Stream.mjs";

package/dist/esm/core/url/qs.mjs

@@ -16,7 +16,7 @@ function stringifyObject(obj, prefix = "", options) {
     const parts = [];
     for (const [key, value] of Object.entries(obj)) {
         const fullKey = prefix ? `${prefix}[${key}]` : key;
-        if (value === undefined) {
+        if (value == null) {
             continue;
         }
         if (Array.isArray(value)) {
@@ -36,7 +36,7 @@ function stringifyObject(obj, prefix = "", options) {
             else {
                 for (let i = 0; i < value.length; i++) {
                     const item = value[i];
-                    if (item === undefined) {
+                    if (item == null) {
                         continue;
                     }
                     if (typeof item === "object" && !Array.isArray(item) && item !== null) {

package/dist/esm/errors/phenomlError.d.mts

@@ -11,4 +11,5 @@ export declare class phenomlError extends Error {
         rawResponse?: core.RawResponse;
         cause?: unknown;
     });
+    get requestId(): string | undefined;
 }

package/dist/esm/errors/phenomlError.mjs

@@ -7,7 +7,7 @@ export class phenomlError extends Error {
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, this.constructor);
         }
-        this.name = this.constructor.name;
+        this.name = "phenomlError";
         this.statusCode = statusCode;
         this.body = body;
         this.rawResponse = rawResponse;
@@ -15,6 +15,10 @@ export class phenomlError extends Error {
             this.cause = cause;
         }
     }
+    get requestId() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.rawResponse) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b.get("x-request-id")) !== null && _c !== void 0 ? _c : undefined;
+    }
 }
 function buildMessage({ message, statusCode, body, }) {
     const lines = [];

package/dist/esm/errors/phenomlTimeoutError.d.mts

@@ -1,5 +1,5 @@
-export declare class phenomlTimeoutError extends Error {
-    readonly cause?: unknown;
+import * as errors from "./index.mjs";
+export declare class phenomlTimeoutError extends errors.phenomlError {
     constructor(message: string, opts?: {
         cause?: unknown;
     });

package/dist/esm/errors/phenomlTimeoutError.mjs

@@ -1,14 +1,15 @@
 // This file was auto-generated by Fern from our API Definition.
-export class phenomlTimeoutError extends Error {
+import * as errors from "./index.mjs";
+export class phenomlTimeoutError extends errors.phenomlError {
     constructor(message, opts) {
-        super(message);
+        super({
+            message: message,
+            cause: opts === null || opts === void 0 ? void 0 : opts.cause,
+        });
         Object.setPrototypeOf(this, new.target.prototype);
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, this.constructor);
         }
-        this.name = this.constructor.name;
-        if ((opts === null || opts === void 0 ? void 0 : opts.cause) != null) {
-            this.cause = opts.cause;
-        }
+        this.name = "phenomlTimeoutError";
     }
 }

package/dist/esm/version.d.mts

@@ -1 +1 @@
-export declare const SDK_VERSION = "17.7.0";
+export declare const SDK_VERSION = "17.9.0";

package/dist/esm/version.mjs

@@ -1 +1 @@
-export const SDK_VERSION = "17.7.0";
+export const SDK_VERSION = "17.9.0";