@personize/sdk 0.6.2 → 0.6.5

package/dist/client.js

@@ -26,7 +26,11 @@ class Personize {
                 if (options?.excludeTags)
                     params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
                 const response = await this.client.get('/api/v1/guidelines', { params });
-                return response.data;
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeGuidelinesListResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * GET /api/v1/guidelines/:id/structure — Get guideline headings
@@ -100,13 +104,18 @@ class Personize {
                 if (options?.excludeTags)
                     params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
                 const response = await this.client.get('/api/v1/collections', { params });
-                return response.data;
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeCollectionsListResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/collections — Create a new property collection
              */
             create: async (payload) => {
-                const response = await this.client.post('/api/v1/collections', payload);
+                const normalizedPayload = await this.normalizeCollectionCreatePayload(payload);
+                const response = await this.client.post('/api/v1/collections', normalizedPayload);
                 return response.data;
             },
             /**
@@ -156,9 +165,38 @@ class Personize {
              * Use `memorize` to auto-save outputs and tool results to memory.
              */
             prompt: async (options) => {
-                const response = await this.client.post('/api/v1/prompt', options);
+                const normalizedOptions = this.normalizePromptOptions(options);
+                const response = await this.client.post('/api/v1/prompt', normalizedOptions);
                 return response.data;
             },
+            /**
+             * POST /api/v1/prompt (stream: true) — Stream prompt execution as Server-Sent Events.
+             *
+             * Returns an async generator that yields SSE events as they arrive:
+             * - `text`: plain text chunks from the LLM
+             * - `output`: a named output extracted when its </output> marker closes
+             * - `step_complete`: fired after each instruction step (multi-step mode)
+             * - `done`: final event with all outputs, evaluation, and metadata
+             * - `error`: non-fatal error during streaming
+             *
+             * @example
+             * ```ts
+             * for await (const event of personize.ai.promptStream({
+             *   prompt: 'Write a hero section',
+             *   outputs: [{ name: 'headline' }, { name: 'subtitle' }],
+             * })) {
+             *   if (event.type === 'output') console.log(event.name, event.data);
+             *   if (event.type === 'done') console.log('Finished:', event.metadata);
+             * }
+             * ```
+             */
+            promptStream: (options) => {
+                const normalizedOptions = this.normalizePromptOptions({ ...options, stream: true });
+                const baseURL = this.client.defaults.baseURL || 'https://agent.personize.ai';
+                const authHeader = this.client.defaults.headers?.['Authorization'];
+                const streamTimeout = options.streamTimeout ?? 120000;
+                return streamPromptSSE(baseURL, authHeader, normalizedOptions, streamTimeout, options.signal);
+            },
         };
         this.agents = {
             /**
@@ -201,7 +239,35 @@ class Personize {
              * Performs structured property extraction and free-form memory creation.
              */
             memorize: async (data) => {
-                const response = await this.client.post('/api/v1/memorize', data);
+                if (data.properties && Object.keys(data.properties).length > 0) {
+                    return this.memorizeBatchFromRecords({
+                        source: 'SDK memorize compatibility',
+                        enhanced: data.enhanced,
+                        records: [{
+                                content: data.content,
+                                email: data.email,
+                                website_url: data.website_url,
+                                record_id: data.record_id,
+                                type: data.type,
+                                customKeyName: data.customKeyName,
+                                customKeyValue: data.customKeyValue,
+                                collectionId: data.collectionIds?.[0],
+                                collectionName: data.collectionName,
+                                properties: data.properties,
+                                tags: data.tags,
+                                enhanced: data.enhanced,
+                                timestamp: data.timestamp,
+                                speaker: data.speaker,
+                            }],
+                        mapping: {
+                            entityType: data.type || 'Record',
+                            properties: {},
+                        },
+                        rows: [],
+                    });
+                }
+                const normalizedData = await this.normalizeMemorizeOptions(data);
+                const response = await this.client.post('/api/v1/memorize', normalizedData);
                 return response.data;
             },
             /**
@@ -209,23 +275,63 @@ class Personize {
              * Supports reflection loops for improved coverage, answer generation, and entity scoping.
              */
             smartRecall: async (data) => {
-                const response = await this.client.post('/api/v1/smart-recall', data);
-                return response.data;
+                const normalizedData = this.normalizeSmartRecallOptions(data);
+                const response = await this.client.post('/api/v1/smart-recall', normalizedData);
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeRecallResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/recall — Direct memory lookup (no reflection).
              */
             recall: async (data) => {
-                const response = await this.client.post('/api/v1/recall', data);
-                return response.data;
+                if (this.isLegacyRecallRequest(data)) {
+                    const compatPayload = this.normalizeLegacyRecallToSmartRecall(data);
+                    const response = await this.client.post('/api/v1/smart-recall', compatPayload);
+                    const responseData = response.data;
+                    if (responseData?.data) {
+                        responseData.data = this.normalizeRecallResponse(responseData.data);
+                    }
+                    return responseData;
+                }
+                const normalizedData = this.normalizeRecallOptions(data);
+                const response = await this.client.post('/api/v1/recall', normalizedData);
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeRecallResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/search — Filter and search records by property conditions.
              * Returns matching record IDs with optional property values and memories.
              */
             search: async (data) => {
-                const response = await this.client.post('/api/v1/search', data);
-                return response.data;
+                const normalizedRequest = await this.normalizeSearchRequest(data);
+                if (normalizedRequest.mode === 'smartRecall') {
+                    const response = await this.client.post('/api/v1/smart-recall', normalizedRequest.payload);
+                    const responseData = response.data;
+                    if (responseData?.data) {
+                        const recallData = this.normalizeRecallResponse(responseData.data);
+                        responseData.data = this.attachArrayMetadata([...(recallData || [])], {
+                            recordIds: [],
+                            totalMatched: recallData?.length || 0,
+                            page: 1,
+                            pageSize: recallData?.length || 0,
+                            totalPages: 1,
+                            results: recallData ? [...recallData] : [],
+                        });
+                    }
+                    return responseData;
+                }
+                const response = await this.client.post('/api/v1/search', normalizedRequest.payload);
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeSearchResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/batch-memorize — Unified batch sync with per-property extractMemories flag.
@@ -233,6 +339,9 @@ class Personize {
              * Properties without it (or false) are stored as structured data only.
              */
             memorizeBatch: async (data) => {
+                if (data.records?.length) {
+                    return this.memorizeBatchFromRecords(data);
+                }
                 const { organizationId, userId } = await this.resolveIdentity();
                 const response = await this.client.post('/api/v1/batch-memorize', {
                     ...data,
@@ -249,6 +358,98 @@ class Personize {
                 const response = await this.client.post('/api/v1/smart-memory-digest', data);
                 return response.data;
             },
+            /**
+             * POST /api/v1/memory/update — Update a single property or freeform memory.
+             *
+             * For property updates: pass `propertyName` + `propertyValue` (or array operations).
+             * For freeform edits: pass `memoryId` + `text`.
+             * Use `expectedVersion` for optimistic concurrency (409 on mismatch).
+             */
+            update: async (data) => {
+                const response = await this.client.post('/api/v1/memory/update', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/bulk-update — Update multiple properties on a record in one request.
+             * Use `expectedVersion` for optimistic concurrency (checked before any writes).
+             */
+            bulkUpdate: async (data) => {
+                const response = await this.client.post('/api/v1/memory/bulk-update', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/delete — Soft-delete memories (30-day recovery window).
+             * Deleted items are excluded from all reads. Use `cancelDeletion` to restore.
+             */
+            delete: async (data) => {
+                const response = await this.client.post('/api/v1/memory/delete', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/delete-record — Soft-delete all memories for a record (30-day recovery).
+             */
+            deleteRecord: async (data) => {
+                const response = await this.client.post('/api/v1/memory/delete-record', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/cancel-deletion — Cancel a pending soft-delete within the 30-day window.
+             * Returns 409 DELETION_FINALIZED if the window has expired.
+             */
+            cancelDeletion: async (data) => {
+                const response = await this.client.post('/api/v1/memory/cancel-deletion', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/property-history — Query property change history for a record.
+             * Supports filtering by property name, time range, and cursor-based pagination.
+             */
+            propertyHistory: async (data) => {
+                const response = await this.client.post('/api/v1/memory/property-history', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/query-properties — LLM-powered search across property values.
+             * Finds records where a property value matches a natural-language query.
+             */
+            queryProperties: async (data) => {
+                const response = await this.client.post('/api/v1/memory/query-properties', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/filter-by-property — Deterministic property filter (no LLM, no token cost).
+             * Finds records where property values match structured conditions.
+             *
+             * @example
+             * ```ts
+             * const result = await client.memory.filterByProperty({
+             *   conditions: [{ propertyName: 'deal_stage', operator: 'equals', value: 'closed_won' }],
+             *   type: 'Company',
+             *   limit: 100,
+             * });
+             * ```
+             */
+            filterByProperty: async (data) => {
+                const response = await this.client.post('/api/v1/memory/filter-by-property', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/properties — Get record properties with schema descriptions.
+             */
+            properties: async (data) => {
+                const response = await this.client.post('/api/v1/properties', {
+                    email: data.email,
+                    websiteUrl: data.websiteUrl || data.website_url,
+                    recordId: data.recordId || data.record_id,
+                    type: data.type,
+                    customKeyName: data.customKeyName,
+                    customKeyValue: data.customKeyValue,
+                    propertyNames: data.propertyNames,
+                    includeDescriptions: data.includeDescriptions,
+                    nonEmpty: data.nonEmpty,
+                });
+                return response.data;
+            },
         };
         this.evaluate = {
             /**
@@ -312,6 +513,387 @@ class Personize {
         const { organizationId } = await this.resolveIdentity();
         return organizationId;
     }
+    normalizePropertyOptions(options) {
+        if (!options)
+            return undefined;
+        return Array.isArray(options) ? options.join(',') : options;
+    }
+    inferEntityTypeFromKeys(input) {
+        if (input.primaryKeyField === 'email' || input.email)
+            return 'Contact';
+        if (input.primaryKeyField === 'website' || input.primaryKeyField === 'website_url' || input.website_url || input.websiteUrl) {
+            return 'Company';
+        }
+        return undefined;
+    }
+    async listAllCollections() {
+        const collections = [];
+        let nextToken;
+        do {
+            const response = await this.client.get('/api/v1/collections', {
+                params: {
+                    limit: 100,
+                    nextToken,
+                    summary: 'true',
+                },
+            });
+            const data = response.data?.data;
+            for (const action of data?.actions ?? []) {
+                const payload = action?.payload ?? {};
+                if (payload.collectionId && payload.collectionName) {
+                    collections.push({
+                        collectionId: String(payload.collectionId),
+                        collectionName: String(payload.collectionName),
+                    });
+                }
+            }
+            nextToken = data?.nextToken;
+        } while (nextToken);
+        return collections;
+    }
+    async resolveCollectionIdsByName(names) {
+        if (!names?.length)
+            return undefined;
+        const normalizedNames = names.map((name) => name.trim().toLowerCase()).filter(Boolean);
+        if (!normalizedNames.length)
+            return undefined;
+        const collections = await this.listAllCollections();
+        const ids = normalizedNames.map((target) => {
+            const match = collections.find((collection) => collection.collectionName.toLowerCase() === target);
+            return match?.collectionId;
+        }).filter((value) => Boolean(value));
+        return ids.length ? Array.from(new Set(ids)) : undefined;
+    }
+    async normalizeCollectionCreatePayload(payload) {
+        const normalizedProperties = payload.properties?.map((property) => ({
+            ...property,
+            options: this.normalizePropertyOptions(property.options),
+            update: property.update ?? (property.updateSemantics ? property.updateSemantics !== 'append' : undefined),
+        }));
+        return {
+            collectionName: payload.collectionName || payload.name || '',
+            collectionId: payload.collectionId || payload.slug,
+            definition: payload.definition || payload.description,
+            entityType: payload.entityType || this.inferEntityTypeFromKeys({ primaryKeyField: payload.primaryKeyField }),
+            properties: normalizedProperties,
+            status: payload.status,
+        };
+    }
+    attachArrayMetadata(items, metadata) {
+        return Object.assign(items, metadata);
+    }
+    normalizeGuidelinesListResponse(data) {
+        if (!data?.actions)
+            return data;
+        const items = data.actions.map((action) => ({
+            id: action.id,
+            type: action.type,
+            slug: typeof action.payload.name === 'string' ? action.payload.name : undefined,
+            ...action.payload,
+        }));
+        return this.attachArrayMetadata(items, data);
+    }
+    normalizeCollectionsListResponse(data) {
+        if (!data?.actions)
+            return data;
+        const items = data.actions.map((action) => ({
+            id: action.id,
+            type: action.type,
+            name: action.payload.collectionName,
+            slug: action.payload.collectionId,
+            ...action.payload,
+        }));
+        return this.attachArrayMetadata(items, data);
+    }
+    normalizePromptOptions(options) {
+        if (!options.evaluationCriteria || options.evaluate) {
+            const { evaluationCriteria: _ec, ...rest } = options;
+            return rest;
+        }
+        const { evaluationCriteria, ...rest } = options;
+        return {
+            ...rest,
+            evaluate: {
+                criteria: evaluationCriteria,
+                serverSide: true,
+            },
+        };
+    }
+    async normalizeMemorizeOptions(data) {
+        const { collectionName, collectionNames, properties, ...rest } = data;
+        const requestedCollectionNames = [
+            ...(collectionNames || []),
+            ...(collectionName ? [collectionName] : []),
+        ];
+        const collectionIds = rest.collectionIds?.length
+            ? rest.collectionIds
+            : await this.resolveCollectionIdsByName(requestedCollectionNames);
+        return {
+            ...rest,
+            collectionIds,
+            properties,
+        };
+    }
+    normalizeSmartRecallOptions(data) {
+        const { message, collectionName, ...rest } = data;
+        return {
+            ...rest,
+            query: data.query || message || '',
+            collectionNames: data.collectionNames || (collectionName ? [collectionName] : undefined),
+        };
+    }
+    isLegacyRecallRequest(data) {
+        return Boolean(data.message ||
+            data.limit != null ||
+            data.collectionName ||
+            data.collectionNames?.length ||
+            !data.type);
+    }
+    normalizeLegacyRecallToSmartRecall(data) {
+        return {
+            query: data.query || data.message || '',
+            limit: data.limit,
+            email: data.email,
+            website_url: data.website_url,
+            websiteUrl: data.websiteUrl,
+            record_id: data.record_id,
+            recordId: data.recordId,
+            type: data.type || this.inferEntityTypeFromKeys({
+                email: data.email,
+                website_url: data.website_url,
+                websiteUrl: data.websiteUrl,
+            }),
+            customKeyName: data.customKeyName,
+            customKeyValue: data.customKeyValue,
+            filters: data.filters,
+            collectionNames: data.collectionNames || (data.collectionName ? [data.collectionName] : undefined),
+        };
+    }
+    normalizeRecallOptions(data) {
+        const { message, limit: _limit, collectionName: _collectionName, collectionNames: _collectionNames, ...rest } = data;
+        return {
+            ...rest,
+            query: data.query || message || '',
+            type: data.type || this.inferEntityTypeFromKeys({
+                email: rest.email,
+                website_url: rest.website_url,
+                websiteUrl: rest.websiteUrl,
+            }),
+        };
+    }
+    buildSearchGroupsFromFilters(filters) {
+        if (!filters)
+            return undefined;
+        const conditions = Object.entries(filters)
+            .filter(([, value]) => value !== undefined)
+            .flatMap(([property, value]) => {
+            if (Array.isArray(value)) {
+                return value.map((item) => ({
+                    property,
+                    operator: 'contains',
+                    value: item,
+                }));
+            }
+            return [{
+                    property,
+                    operator: 'equals',
+                    value: value,
+                }];
+        });
+        return conditions.length ? [{ conditions }] : undefined;
+    }
+    async normalizeSearchRequest(data) {
+        const collectionNames = data.collectionNames || (data.collectionName ? [data.collectionName] : undefined);
+        if (data.query && !data.groups?.length) {
+            return {
+                mode: 'smartRecall',
+                payload: {
+                    query: data.query,
+                    limit: data.limit || data.pageSize,
+                    type: data.type,
+                    email: data.email,
+                    websiteUrl: data.websiteUrl,
+                    recordId: data.recordId,
+                    customKeyName: data.customKeyName,
+                    customKeyValue: data.customKeyValue,
+                    collectionNames,
+                    filters: data.filters,
+                },
+            };
+        }
+        const collectionIds = data.collectionIds?.length
+            ? data.collectionIds
+            : await this.resolveCollectionIdsByName(collectionNames);
+        return {
+            mode: 'search',
+            payload: {
+                type: data.type,
+                email: data.email,
+                websiteUrl: data.websiteUrl,
+                recordId: data.recordId,
+                customKeyName: data.customKeyName,
+                customKeyValue: data.customKeyValue,
+                collectionIds,
+                groups: data.groups || this.buildSearchGroupsFromFilters(data.filters),
+                pageSize: data.pageSize || data.limit,
+                page: data.page,
+                countOnly: data.countOnly,
+                returnRecords: data.returnRecords,
+                includeMemories: data.includeMemories,
+                dataSource: data.dataSource,
+            },
+        };
+    }
+    normalizeSearchResponse(data) {
+        if (!data)
+            return data;
+        const results = data.recordIds.map((recordId) => ({
+            recordId,
+            mainProperties: data.mainProperties?.[recordId],
+            record: data.records?.[recordId],
+            memories: data.memories?.[recordId],
+        }));
+        return this.attachArrayMetadata(results, {
+            ...data,
+            results: [...results],
+        });
+    }
+    normalizeRecallResponse(data) {
+        if (!data)
+            return undefined;
+        const source = Array.isArray(data) ? { results: data } : data;
+        const rawResults = Array.isArray(source.results)
+            ? source.results
+            : Array.isArray(source.memories)
+                ? source.memories
+                : [];
+        const results = rawResults.map((entry) => {
+            if (typeof entry !== 'object' || entry === null) {
+                return { content: String(entry), memory: String(entry) };
+            }
+            const record = entry;
+            const content = typeof record.content === 'string'
+                ? record.content
+                : typeof record.memory === 'string'
+                    ? record.memory
+                    : typeof record.text === 'string'
+                        ? record.text
+                        : undefined;
+            return {
+                ...record,
+                content,
+                memory: typeof record.memory === 'string' ? record.memory : content,
+            };
+        });
+        return this.attachArrayMetadata(results, {
+            ...(Array.isArray(data) ? {} : source),
+            results: [...results],
+        });
+    }
+    isBatchRecordProperty(value) {
+        return typeof value === 'object' && value !== null && 'value' in value;
+    }
+    async memorizeBatchFromRecords(data) {
+        const records = data.records || [];
+        if (!records.length) {
+            return { success: true, data: { memorized: 0 } };
+        }
+        const contentRecords = records.filter((record) => record.content);
+        for (const record of contentRecords) {
+            const normalizedMemorize = await this.normalizeMemorizeOptions({
+                content: String(record.content),
+                email: record.email,
+                website_url: record.website_url || record.websiteUrl,
+                record_id: record.record_id || record.recordId,
+                type: record.type,
+                customKeyName: record.customKeyName,
+                customKeyValue: record.customKeyValue,
+                tags: record.tags,
+                enhanced: record.enhanced ?? data.enhanced,
+                timestamp: record.timestamp,
+                speaker: record.speaker,
+                collectionNames: record.collectionName ? [record.collectionName] : undefined,
+                collectionIds: record.collectionId ? [record.collectionId] : undefined,
+            });
+            await this.memory.memorize(normalizedMemorize);
+        }
+        const structuredRecords = records.filter((record) => record.properties && Object.keys(record.properties).length > 0);
+        if (!structuredRecords.length) {
+            return { success: true, data: { memorized: contentRecords.length } };
+        }
+        const first = structuredRecords[0];
+        const entityType = first.type || this.inferEntityTypeFromKeys({
+            email: first.email,
+            website_url: first.website_url,
+            websiteUrl: first.websiteUrl,
+        }) || 'Record';
+        const mappingProperties = {};
+        const rows = structuredRecords.map((record) => {
+            const row = {};
+            if (record.email)
+                row.email = record.email;
+            if (record.website_url || record.websiteUrl)
+                row.website = record.website_url || record.websiteUrl;
+            if (record.record_id || record.recordId)
+                row.record_id = record.record_id || record.recordId;
+            if (record.customKeyValue)
+                row.custom_key = record.customKeyValue;
+            for (const [propertyName, rawProperty] of Object.entries(record.properties || {})) {
+                const property = this.isBatchRecordProperty(rawProperty)
+                    ? rawProperty
+                    : { value: rawProperty };
+                row[propertyName] = property.value;
+                if (!mappingProperties[propertyName]) {
+                    mappingProperties[propertyName] = {
+                        sourceField: propertyName,
+                        collectionId: property.collectionId || record.collectionId || '',
+                        collectionName: property.collectionName || record.collectionName || '',
+                        extractMemories: property.extractMemories,
+                    };
+                }
+            }
+            return row;
+        });
+        const unresolvedNames = Array.from(new Set(Object.values(mappingProperties)
+            .filter((property) => !property.collectionId && property.collectionName)
+            .map((property) => property.collectionName)));
+        const resolvedMap = new Map();
+        if (unresolvedNames.length) {
+            const collections = await this.listAllCollections();
+            for (const collection of collections) {
+                if (unresolvedNames.some((name) => name.toLowerCase() === collection.collectionName.toLowerCase())) {
+                    resolvedMap.set(collection.collectionName.toLowerCase(), collection.collectionId);
+                }
+            }
+        }
+        for (const property of Object.values(mappingProperties)) {
+            if (!property.collectionId && property.collectionName) {
+                property.collectionId = resolvedMap.get(property.collectionName.toLowerCase()) || '';
+            }
+            if (!property.collectionId || !property.collectionName) {
+                throw new Error('records shorthand requires collectionId/collectionName for each structured property');
+            }
+        }
+        const { organizationId, userId } = await this.resolveIdentity();
+        const response = await this.client.post('/api/v1/batch-memorize', {
+            source: data.source || 'SDK records shorthand',
+            tier: data.tier,
+            dryRun: data.dryRun,
+            chunkSize: data.chunkSize,
+            mapping: {
+                entityType,
+                email: rows.some((row) => row.email) ? 'email' : undefined,
+                website: rows.some((row) => row.website) ? 'website' : undefined,
+                customKeyName: first.customKeyName,
+                customKey: rows.some((row) => row.custom_key) ? 'custom_key' : undefined,
+                properties: mappingProperties,
+            },
+            rows,
+            orgId: organizationId,
+            userId,
+        });
+        return response.data;
+    }
     /**
      * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
      */
@@ -328,3 +910,124 @@ class Personize {
     }
 }
 exports.Personize = Personize;
+// ────────────────────────────── SSE Stream Parser ──────────────────────────────
+/**
+ * Initiates a streaming prompt request and yields SSE events.
+ * Extracted as a standalone function to avoid `this` binding issues with async generators.
+ */
+async function* streamPromptSSE(baseURL, authHeader, options, streamTimeout, signal) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), streamTimeout);
+    // Link external signal if provided
+    if (signal) {
+        if (signal.aborted) {
+            clearTimeout(timeoutId);
+            controller.abort();
+        }
+        else {
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+    }
+    let response;
+    try {
+        response = await fetch(`${baseURL}/api/v1/prompt`, {
+            method: 'POST',
+            headers: {
+                'Authorization': authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(options),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        throw new Error(`Prompt stream connection failed: ${err instanceof Error ? err.message : err}`);
+    }
+    if (!response.ok) {
+        clearTimeout(timeoutId);
+        const errorBody = await response.text().catch(() => '');
+        throw new Error(`Prompt stream failed (${response.status}): ${errorBody}`);
+    }
+    if (!response.body) {
+        clearTimeout(timeoutId);
+        throw new Error('Prompt stream: response body is null');
+    }
+    try {
+        yield* parseSSEStream(response.body);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Parses a ReadableStream of SSE bytes into typed PromptSSEEvent objects.
+ *
+ * Handles:
+ * - Partial chunks split across reads
+ * - Multi-line `data:` fields (accumulated per event)
+ * - Empty lines as event separators
+ * - Graceful end-of-stream
+ */
+async function* parseSSEStream(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Process complete events (separated by double newline)
+            const parts = buffer.split('\n\n');
+            // Last part may be incomplete — keep it in buffer
+            buffer = parts.pop() || '';
+            for (const part of parts) {
+                const dataLines = [];
+                for (const line of part.split('\n')) {
+                    if (line.startsWith('data: ')) {
+                        dataLines.push(line.slice(6));
+                    }
+                    else if (line.startsWith('data:')) {
+                        dataLines.push(line.slice(5));
+                    }
+                    // Ignore lines starting with ':' (comments/keepalive)
+                    // Ignore 'event:', 'id:', 'retry:' — we only use unnamed data events
+                }
+                if (dataLines.length === 0)
+                    continue;
+                const jsonStr = dataLines.join('\n');
+                try {
+                    const event = JSON.parse(jsonStr);
+                    yield event;
+                }
+                catch {
+                    // Non-JSON data line — skip (could be a keepalive or malformed chunk)
+                }
+            }
+        }
+        // Flush remaining buffer
+        if (buffer.trim()) {
+            const dataLines = [];
+            for (const line of buffer.split('\n')) {
+                if (line.startsWith('data: '))
+                    dataLines.push(line.slice(6));
+                else if (line.startsWith('data:'))
+                    dataLines.push(line.slice(5));
+            }
+            if (dataLines.length > 0) {
+                try {
+                    const event = JSON.parse(dataLines.join('\n'));
+                    yield event;
+                }
+                catch {
+                    // Ignore incomplete final chunk
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}