@spekoai/sdk 0.3.0 → 0.4.0

package/dist/lib/resources/knowledge-bases.d.ts

@@ -0,0 +1,60 @@
+import type { HttpClient } from '../http.js';
+import type { KnowledgeBaseCreateParams, KnowledgeBaseDocumentCreateParams, KnowledgeBaseDocumentCreateResult, KnowledgeBaseDocumentPollOptions, KnowledgeBaseDocumentRow, KnowledgeBaseDocumentUploadParams, KnowledgeBaseListParams, KnowledgeBaseRow } from '../types/index.js';
+/**
+ * Per-agent knowledge bases. Each KB owns documents that get embedded
+ * into a Chroma collection so the agent can retrieve relevant chunks
+ * during a call. Every agent created via {@link Agents.create}
+ * auto-provisions a `Default` KB; additional KBs can be created
+ * explicitly with {@link KnowledgeBases.create}.
+ *
+ * @example
+ * ```ts
+ * const kb = await speko.knowledgeBases.create({
+ *   agentId: agent.id,
+ *   name: 'Product FAQ',
+ * });
+ *
+ * const doc = await speko.knowledgeBases.uploadDocument(kb.id, {
+ *   filename: 'faq.md',
+ *   contentType: 'text/markdown',
+ *   data: await Bun.file('faq.md').arrayBuffer(),
+ * });
+ *
+ * const ready = await speko.knowledgeBases.pollDocumentReady(kb.id, doc.id);
+ * ```
+ */
+export declare class KnowledgeBases {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(params: KnowledgeBaseCreateParams): Promise<KnowledgeBaseRow>;
+    list(params?: KnowledgeBaseListParams): Promise<KnowledgeBaseRow[]>;
+    get(kbId: string): Promise<KnowledgeBaseRow>;
+    delete(kbId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listDocuments(kbId: string): Promise<KnowledgeBaseDocumentRow[]>;
+    getDocument(kbId: string, docId: string): Promise<KnowledgeBaseDocumentRow>;
+    createDocument(kbId: string, params: KnowledgeBaseDocumentCreateParams): Promise<KnowledgeBaseDocumentCreateResult>;
+    finalizeDocument(kbId: string, docId: string): Promise<KnowledgeBaseDocumentRow>;
+    deleteDocument(kbId: string, docId: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Convenience wrapper: register a document, upload its bytes to the
+     * signed PUT URL the server mints, then call finalize. Returns the
+     * document with status flipped to `processing`. Call
+     * {@link pollDocumentReady} to wait for ingest completion.
+     *
+     * The server's signed upload URL expires 600 seconds after issuance,
+     * so do not hold the result of {@link createDocument} for long before
+     * uploading. This wrapper performs all three steps back-to-back.
+     */
+    uploadDocument(kbId: string, params: KnowledgeBaseDocumentUploadParams): Promise<KnowledgeBaseDocumentRow>;
+    /**
+     * Poll a document until it reaches `ready` or `failed` status, or the
+     * timeout elapses. Throws {@link SpekoApiError} on `failed` (with the
+     * server's `errorMessage`) or on timeout.
+     */
+    pollDocumentReady(kbId: string, docId: string, opts?: KnowledgeBaseDocumentPollOptions): Promise<KnowledgeBaseDocumentRow>;
+}
+//# sourceMappingURL=knowledge-bases.d.ts.map

package/dist/lib/resources/knowledge-bases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-bases.d.ts","sourceRoot":"","sources":["../../../src/lib/resources/knowledge-bases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EACV,yBAAyB,EACzB,iCAAiC,EACjC,iCAAiC,EACjC,gCAAgC,EAChC,wBAAwB,EACxB,iCAAiC,EACjC,uBAAuB,EACvB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,MAAM,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIpE,IAAI,CAAC,MAAM,GAAE,uBAA4B,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IASvE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAMnD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,EAAE,CAAC;IAMhE,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,wBAAwB,CAAC;IAMpC,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iCAAiC,GACxC,OAAO,CAAC,iCAAiC,CAAC;IAO7C,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,wBAAwB,CAAC;IAOpC,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAMhC;;;;;;;;;OASG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,iCAAiC,GACxC,OAAO,CAAC,wBAAwB,CAAC;IA4BpC;;;;OAIG;IACG,iBAAiB,CACrB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,gCAAqC,GAC1C,OAAO,CAAC,wBAAwB,CAAC;CAwBrC"}

package/dist/lib/resources/knowledge-bases.js

@@ -0,0 +1,138 @@
+import { SpekoApiError } from '../errors.js';
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_POLL_TIMEOUT_MS = 120_000;
+/**
+ * Per-agent knowledge bases. Each KB owns documents that get embedded
+ * into a Chroma collection so the agent can retrieve relevant chunks
+ * during a call. Every agent created via {@link Agents.create}
+ * auto-provisions a `Default` KB; additional KBs can be created
+ * explicitly with {@link KnowledgeBases.create}.
+ *
+ * @example
+ * ```ts
+ * const kb = await speko.knowledgeBases.create({
+ *   agentId: agent.id,
+ *   name: 'Product FAQ',
+ * });
+ *
+ * const doc = await speko.knowledgeBases.uploadDocument(kb.id, {
+ *   filename: 'faq.md',
+ *   contentType: 'text/markdown',
+ *   data: await Bun.file('faq.md').arrayBuffer(),
+ * });
+ *
+ * const ready = await speko.knowledgeBases.pollDocumentReady(kb.id, doc.id);
+ * ```
+ */
+export class KnowledgeBases {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    create(params) {
+        return this.http.post('/v1/knowledge-bases', params);
+    }
+    list(params = {}) {
+        const query = new URLSearchParams();
+        if (params.agentId)
+            query.set('agentId', params.agentId);
+        const qs = query.toString();
+        return this.http.get(`/v1/knowledge-bases${qs ? `?${qs}` : ''}`);
+    }
+    get(kbId) {
+        return this.http.get(`/v1/knowledge-bases/${encodeURIComponent(kbId)}`);
+    }
+    delete(kbId) {
+        return this.http.delete(`/v1/knowledge-bases/${encodeURIComponent(kbId)}`);
+    }
+    listDocuments(kbId) {
+        return this.http.get(`/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents`);
+    }
+    getDocument(kbId, docId) {
+        return this.http.get(`/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}`);
+    }
+    createDocument(kbId, params) {
+        return this.http.post(`/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents`, params);
+    }
+    finalizeDocument(kbId, docId) {
+        return this.http.post(`/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}/finalize`, {});
+    }
+    deleteDocument(kbId, docId) {
+        return this.http.delete(`/v1/knowledge-bases/${encodeURIComponent(kbId)}/documents/${encodeURIComponent(docId)}`);
+    }
+    /**
+     * Convenience wrapper: register a document, upload its bytes to the
+     * signed PUT URL the server mints, then call finalize. Returns the
+     * document with status flipped to `processing`. Call
+     * {@link pollDocumentReady} to wait for ingest completion.
+     *
+     * The server's signed upload URL expires 600 seconds after issuance,
+     * so do not hold the result of {@link createDocument} for long before
+     * uploading. This wrapper performs all three steps back-to-back.
+     */
+    async uploadDocument(kbId, params) {
+        const sizeBytes = byteLengthOf(params.data);
+        const { document, upload } = await this.createDocument(kbId, {
+            filename: params.filename,
+            contentType: params.contentType,
+            sizeBytes,
+            metadata: params.metadata,
+        });
+        const putResponse = await fetch(upload.url, {
+            method: upload.method,
+            headers: upload.headers,
+            body: toBodyInit(params.data),
+        });
+        if (!putResponse.ok) {
+            const text = await safeReadText(putResponse);
+            throw new SpekoApiError(`Document upload failed: ${putResponse.status} ${text || putResponse.statusText}`, putResponse.status, 'DOCUMENT_UPLOAD_FAILED');
+        }
+        return this.finalizeDocument(kbId, document.id);
+    }
+    /**
+     * Poll a document until it reaches `ready` or `failed` status, or the
+     * timeout elapses. Throws {@link SpekoApiError} on `failed` (with the
+     * server's `errorMessage`) or on timeout.
+     */
+    async pollDocumentReady(kbId, docId, opts = {}) {
+        const intervalMs = opts.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        const timeoutMs = opts.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const doc = await this.getDocument(kbId, docId);
+            if (doc.status === 'ready')
+                return doc;
+            if (doc.status === 'failed') {
+                throw new SpekoApiError(doc.errorMessage ?? 'Document ingest failed', 500, 'DOCUMENT_INGEST_FAILED');
+            }
+            await delay(intervalMs);
+        }
+        throw new SpekoApiError(`Document ingest timed out after ${timeoutMs}ms`, 408, 'DOCUMENT_INGEST_TIMEOUT');
+    }
+}
+function byteLengthOf(data) {
+    if (data instanceof Blob)
+        return data.size;
+    if (data instanceof Uint8Array)
+        return data.byteLength;
+    return data.byteLength;
+}
+function toBodyInit(data) {
+    if (data instanceof Blob)
+        return data;
+    if (data instanceof Uint8Array) {
+        return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength);
+    }
+    return data;
+}
+async function safeReadText(r) {
+    try {
+        return await r.text();
+    }
+    catch {
+        return '';
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/lib/resources/synthesize.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../http.js';
-import type { SynthesizeOptions, SynthesizeResult } from '../types/index.js';
+import type { SynthesizeOptions, SynthesizeResult, SynthesizeStreamResult } from '../types/index.js';
 export declare class Synthesize {
     private readonly http;
     constructor(http: HttpClient);
@@ -20,5 +20,6 @@ export declare class Synthesize {
      * ```
      */
     call(text: string, options: SynthesizeOptions, abortSignal?: AbortSignal): Promise<SynthesizeResult>;
+    stream(text: string, options: SynthesizeOptions, abortSignal?: AbortSignal): Promise<SynthesizeStreamResult>;
 }
 //# sourceMappingURL=synthesize.d.ts.map

package/dist/lib/resources/synthesize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"synthesize.d.ts","sourceRoot":"","sources":["../../../src/lib/resources/synthesize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,gBAAgB,CAAC;CA4B7B"}
+{"version":3,"file":"synthesize.d.ts","sourceRoot":"","sources":["../../../src/lib/resources/synthesize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;;;;;;;;;;;;OAeG;IACG,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,gBAAgB,CAAC;IAiBtB,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,sBAAsB,CAAC;CAgCnC"}

package/dist/lib/resources/synthesize.js

@@ -20,6 +20,21 @@ export class Synthesize {
      * ```
      */
     async call(text, options, abortSignal) {
+        const streamed = await this.stream(text, options, abortSignal);
+        const chunks = [];
+        for await (const chunk of streamed) {
+            chunks.push(chunk);
+        }
+        return {
+            audio: concatChunks(chunks),
+            contentType: streamed.contentType,
+            provider: streamed.provider,
+            model: streamed.model,
+            failoverCount: streamed.failoverCount,
+            scoresRunId: streamed.scoresRunId,
+        };
+    }
+    async stream(text, options, abortSignal) {
         const intent = {
             language: options.language,
             ...(options.region !== undefined && { region: options.region }),
@@ -32,14 +47,27 @@ export class Synthesize {
             body['speed'] = options.speed;
         if (options.constraints !== undefined)
             body['constraints'] = options.constraints;
-        const { bytes, headers } = await this.http.requestBinary('POST', '/v1/synthesize', body, abortSignal);
-        return {
-            audio: bytes,
+        const { chunks, headers } = await this.http.requestBinaryStream('POST', '/v1/synthesize', body, abortSignal);
+        const result = {
             contentType: headers['content-type'] ?? 'application/octet-stream',
             provider: headers['x-speko-provider'] ?? 'unknown',
             model: headers['x-speko-model'] ?? 'unknown',
             failoverCount: parseInt(headers['x-speko-failover-count'] ?? '0', 10),
             scoresRunId: headers['x-speko-scores-run-id'] || null,
+            [Symbol.asyncIterator]() {
+                return chunks;
+            },
         };
+        return result;
+    }
+}
+function concatChunks(chunks) {
+    const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
     }
+    return out;
 }

package/dist/lib/resources/transcribe.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../http.js';
-import type { TranscribeOptions, TranscribeResult } from '../types/index.js';
+import type { TranscribeOptions, TranscribeResult, TranscribeStreamEvent } from '../types/index.js';
 export declare class Transcribe {
     private readonly http;
     constructor(http: HttpClient);
@@ -16,5 +16,6 @@ export declare class Transcribe {
      * ```
      */
     call(audio: Uint8Array, options: TranscribeOptions, abortSignal?: AbortSignal): Promise<TranscribeResult>;
+    stream(audio: Uint8Array, options: TranscribeOptions, abortSignal?: AbortSignal): AsyncIterableIterator<TranscribeStreamEvent>;
 }
 //# sourceMappingURL=transcribe.d.ts.map

package/dist/lib/resources/transcribe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../../../src/lib/resources/transcribe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,mBAAmB,CAAC;AAE3B,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;;;;;;;;OAWG;IACG,IAAI,CACR,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,gBAAgB,CAAC;CAuB7B"}
+{"version":3,"file":"transcribe.d.ts","sourceRoot":"","sources":["../../../src/lib/resources/transcribe.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,mBAAmB,CAAC;AAG3B,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;;;;;;;;OAWG;IACG,IAAI,CACR,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,gBAAgB,CAAC;IAsBrB,MAAM,CACX,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,iBAAiB,EAC1B,WAAW,CAAC,EAAE,WAAW,GACxB,qBAAqB,CAAC,qBAAqB,CAAC;CA+BhD"}

package/dist/lib/resources/transcribe.js

@@ -1,3 +1,4 @@
+import { SpekoApiError } from '../errors.js';
 export class Transcribe {
     http;
     constructor(http) {
@@ -16,6 +17,28 @@ export class Transcribe {
      * ```
      */
     async call(audio, options, abortSignal) {
+        let done;
+        for await (const event of this.stream(audio, options, abortSignal)) {
+            if (event.type === 'done') {
+                done = {
+                    text: event.text,
+                    provider: event.provider,
+                    model: event.model,
+                    confidence: event.confidence,
+                    failoverCount: event.failoverCount,
+                    scoresRunId: event.scoresRunId,
+                };
+            }
+            else if (event.type === 'error') {
+                throw new SpekoApiError(event.error, 200, event.code);
+            }
+        }
+        if (!done) {
+            throw new SpekoApiError('Transcribe stream ended without a done event', 200, 'STREAM_ENDED');
+        }
+        return done;
+    }
+    async *stream(audio, options, abortSignal) {
         const intent = {
             language: options.language,
             ...(options.region !== undefined && { region: options.region }),
@@ -28,6 +51,14 @@ export class Transcribe {
         if (options.constraints) {
             headers['X-Speko-Constraints'] = JSON.stringify(options.constraints);
         }
-        return this.http.requestRaw('POST', '/v1/transcribe', audio, headers, abortSignal);
+        if (options.keywords && options.keywords.length > 0) {
+            headers['X-Speko-Stt-Options'] = JSON.stringify({
+                keywords: [...options.keywords],
+            });
+        }
+        const stream = await this.http.requestRawSse('POST', '/v1/transcribe', audio, headers, abortSignal);
+        for await (const event of stream) {
+            yield { ...event.data, type: event.event };
+        }
     }
 }