@patternzones/koine-sdk 2.0.4 → 2.2.0

package/README.md

@@ -76,6 +76,27 @@ Creates a client instance with the given configuration. The config is validated
 | `KoineError` | Error class with typed `code` property |
 | `KoineErrorCode` | Union type of all possible error codes |
 
+## Error Handling & Retries
+
+The SDK does not automatically retry failed requests. When the gateway returns `429 Too Many Requests` (concurrency limit exceeded), your application should implement retry logic:
+
+```typescript
+async function generateWithRetry(prompt: string, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await koine.generateText({ prompt });
+    } catch (error) {
+      if (error instanceof KoineError && error.code === 'CONCURRENCY_LIMIT_ERROR') {
+        await new Promise(r => setTimeout(r, 1000 * (i + 1))); // Exponential backoff
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error('Max retries exceeded');
+}
+```
+
 ## Documentation
 
 See the [SDK Guide](https://github.com/pattern-zones-co/koine/blob/main/docs/sdk-guide.md) for:

package/dist/client.d.ts

@@ -1,9 +1,10 @@
 import { type GenerateObjectOptions, type GenerateObjectResult, generateObject } from "./object.js";
+import { type StreamObjectOptions, streamObject } from "./stream-object.js";
 import { type StreamTextOptions, streamText } from "./stream/index.js";
 import { type GenerateTextOptions, type GenerateTextResult, generateText } from "./text.js";
-import type { KoineConfig, KoineStreamResult } from "./types.js";
-export { generateText, streamText, generateObject };
-export type { GenerateTextOptions, GenerateTextResult, StreamTextOptions, GenerateObjectOptions, GenerateObjectResult, };
+import type { KoineConfig, KoineStreamObjectResult, KoineStreamResult } from "./types.js";
+export { generateText, streamText, generateObject, streamObject };
+export type { GenerateTextOptions, GenerateTextResult, StreamTextOptions, GenerateObjectOptions, GenerateObjectResult, StreamObjectOptions, };
 /**
  * Koine client interface returned by createKoine.
  */
@@ -33,6 +34,15 @@ export interface KoineClient {
      * @throws {KoineError} With code 'VALIDATION_ERROR' if response doesn't match schema
      */
     generateObject<T>(options: GenerateObjectOptions<T>): Promise<GenerateObjectResult<T>>;
+    /**
+     * Streams structured JSON objects from Koine gateway service.
+     *
+     * @typeParam T - The type of the expected response object, inferred from schema
+     * @param options - Request options including Zod schema
+     * @returns KoineStreamObjectResult with partialObjectStream, object, sessionId, usage
+     * @throws {KoineError} When connection fails or stream encounters an error
+     */
+    streamObject<T>(options: StreamObjectOptions<T>): Promise<KoineStreamObjectResult<T>>;
 }
 /**
  * Creates a Koine client instance with the given configuration.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,cAAc,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,YAAY,EACZ,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGjE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,CAAC;AACpD,YAAY,EACX,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACpB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAExE;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEnE;;;;;;;OAOG;IACH,cAAc,CAAC,CAAC,EACf,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAU5D"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EACN,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,cAAc,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,mBAAmB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,KAAK,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,YAAY,EACZ,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EACX,WAAW,EACX,uBAAuB,EACvB,iBAAiB,EACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC;AAClE,YAAY,EACX,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,GACnB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAExE;;;;;;OAMG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEnE;;;;;;;OAOG;IACH,cAAc,CAAC,CAAC,EACf,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpC;;;;;;;OAOG;IACH,YAAY,CAAC,CAAC,EACb,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAY5D"}

package/dist/client.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateObject = exports.streamText = exports.generateText = void 0;
+exports.streamObject = exports.generateObject = exports.streamText = exports.generateText = void 0;
 exports.createKoine = createKoine;
 // Import and re-export functions from the new modules
 const http_js_1 = require("./http.js");
 const object_js_1 = require("./object.js");
 Object.defineProperty(exports, "generateObject", { enumerable: true, get: function () { return object_js_1.generateObject; } });
+const stream_object_js_1 = require("./stream-object.js");
+Object.defineProperty(exports, "streamObject", { enumerable: true, get: function () { return stream_object_js_1.streamObject; } });
 const index_js_1 = require("./stream/index.js");
 Object.defineProperty(exports, "streamText", { enumerable: true, get: function () { return index_js_1.streamText; } });
 const text_js_1 = require("./text.js");
@@ -41,6 +43,7 @@ function createKoine(config) {
         generateText: (options) => (0, text_js_1.generateText)(config, options),
         streamText: (options) => (0, index_js_1.streamText)(config, options),
         generateObject: (options) => (0, object_js_1.generateObject)(config, options),
+        streamObject: (options) => (0, stream_object_js_1.streamObject)(config, options),
     };
 }
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAoFA,kCAUC;AA9FD,sDAAsD;AACtD,uCAA2C;AAC3C,2CAIqB;AAUc,+FAXlC,0BAAc,OAWkC;AATjD,gDAAuE;AAShD,2FATU,qBAAU,OASV;AARjC,uCAImB;AAIV,6FALR,sBAAY,OAKQ;AA4CrB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,WAAW,CAAC,MAAmB;IAC9C,wCAAwC;IACxC,IAAA,wBAAc,EAAC,MAAM,CAAC,CAAC;IAEvB,OAAO;QACN,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAA,sBAAY,EAAC,MAAM,EAAE,OAAO,CAAC;QACxD,UAAU,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAA,qBAAU,EAAC,MAAM,EAAE,OAAO,CAAC;QACpD,cAAc,EAAE,CAAI,OAAiC,EAAE,EAAE,CACxD,IAAA,0BAAc,EAAC,MAAM,EAAE,OAAO,CAAC;KAChC,CAAC;AACH,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAsGA,kCAYC;AAlHD,sDAAsD;AACtD,uCAA2C;AAC3C,2CAIqB;AAec,+FAhBlC,0BAAc,OAgBkC;AAdjD,yDAA4E;AAczB,6FAdhB,+BAAY,OAcgB;AAb/D,gDAAuE;AAahD,2FAbU,qBAAU,OAaV;AAZjC,uCAImB;AAQV,6FATR,sBAAY,OASQ;AAyDrB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,WAAW,CAAC,MAAmB;IAC9C,wCAAwC;IACxC,IAAA,wBAAc,EAAC,MAAM,CAAC,CAAC;IAEvB,OAAO;QACN,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAA,sBAAY,EAAC,MAAM,EAAE,OAAO,CAAC;QACxD,UAAU,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAA,qBAAU,EAAC,MAAM,EAAE,OAAO,CAAC;QACpD,cAAc,EAAE,CAAI,OAAiC,EAAE,EAAE,CACxD,IAAA,0BAAc,EAAC,MAAM,EAAE,OAAO,CAAC;QAChC,YAAY,EAAE,CAAI,OAA+B,EAAE,EAAE,CACpD,IAAA,+BAAY,EAAC,MAAM,EAAE,OAAO,CAAC;KAC9B,CAAC;AACH,CAAC"}

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * Known error codes returned by the SDK and gateway.
  */
-export type KoineErrorCode = "HTTP_ERROR" | "INVALID_RESPONSE" | "INVALID_CONFIG" | "VALIDATION_ERROR" | "STREAM_ERROR" | "SSE_PARSE_ERROR" | "NO_SESSION" | "NO_USAGE" | "NO_RESPONSE_BODY" | "TIMEOUT" | "NETWORK_ERROR" | "INVALID_PARAMS" | "AUTH_ERROR" | "UNAUTHORIZED" | "SERVER_ERROR" | "SCHEMA_ERROR" | "RATE_LIMITED" | "CONTEXT_OVERFLOW";
+export type KoineErrorCode = "HTTP_ERROR" | "INVALID_RESPONSE" | "INVALID_CONFIG" | "VALIDATION_ERROR" | "STREAM_ERROR" | "SSE_PARSE_ERROR" | "NO_SESSION" | "NO_USAGE" | "NO_OBJECT" | "NO_RESPONSE_BODY" | "TIMEOUT" | "NETWORK_ERROR" | "INVALID_PARAMS" | "AUTH_ERROR" | "UNAUTHORIZED" | "SERVER_ERROR" | "SCHEMA_ERROR" | "RATE_LIMITED" | "CONTEXT_OVERFLOW";
 /**
  * Custom error class for Koine client errors.
  *

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GAEvB,YAAY,GACZ,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,YAAY,GACZ,UAAU,GACV,kBAAkB,GAClB,SAAS,GACT,eAAe,GAEf,gBAAgB,GAChB,YAAY,GACZ,cAAc,GACd,cAAc,GACd,cAAc,GACd,cAAc,GACd,kBAAkB,CAAC;AAEtB;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,MAAM;CAQnE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GAEvB,YAAY,GACZ,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,YAAY,GACZ,UAAU,GACV,WAAW,GACX,kBAAkB,GAClB,SAAS,GACT,eAAe,GAEf,gBAAgB,GAChB,YAAY,GACZ,cAAc,GACd,cAAc,GACd,cAAc,GACd,cAAc,GACd,kBAAkB,CAAC;AAEtB;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,MAAM;CAQnE"}

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAyBA;;;;;;;;;;;;;GAaG;AACH,MAAa,UAAW,SAAQ,KAAK;IAC3B,IAAI,CAAiB;IACrB,OAAO,CAAU;IAE1B,YAAY,OAAe,EAAE,IAAoB,EAAE,OAAgB;QAClE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,sEAAsE;QACtE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAZD,gCAYC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AA0BA;;;;;;;;;;;;;GAaG;AACH,MAAa,UAAW,SAAQ,KAAK;IAC3B,IAAI,CAAiB;IACrB,OAAO,CAAU;IAE1B,YAAY,OAAe,EAAE,IAAoB,EAAE,OAAgB;QAClE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,sEAAsE;QACtE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAZD,gCAYC"}

package/dist/index.d.ts

@@ -21,10 +21,10 @@
  * console.log(result.text);
  * ```
  */
-export type { KoineConfig, KoineUsage, KoineStreamResult } from "./types.js";
+export type { KoineConfig, KoineUsage, KoineStreamResult, KoineStreamObjectResult, } from "./types.js";
 export { KoineError } from "./errors.js";
 export type { KoineErrorCode } from "./errors.js";
 export { createKoine } from "./client.js";
-export type { KoineClient, GenerateTextOptions, GenerateTextResult, StreamTextOptions, GenerateObjectOptions, GenerateObjectResult, } from "./client.js";
-export { generateText, streamText, generateObject } from "./client.js";
+export type { KoineClient, GenerateTextOptions, GenerateTextResult, StreamTextOptions, GenerateObjectOptions, GenerateObjectResult, StreamObjectOptions, } from "./client.js";
+export { generateText, streamText, generateObject, streamObject, } from "./client.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACX,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,GACpB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,YAAY,EACX,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,uBAAuB,GACvB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,YAAY,EACX,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACN,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,GACZ,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -23,7 +23,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateObject = exports.streamText = exports.generateText = exports.createKoine = exports.KoineError = void 0;
+exports.streamObject = exports.generateObject = exports.streamText = exports.generateText = exports.createKoine = exports.KoineError = void 0;
 // Errors
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "KoineError", { enumerable: true, get: function () { return errors_js_1.KoineError; } });
@@ -35,4 +35,5 @@ var client_js_2 = require("./client.js");
 Object.defineProperty(exports, "generateText", { enumerable: true, get: function () { return client_js_2.generateText; } });
 Object.defineProperty(exports, "streamText", { enumerable: true, get: function () { return client_js_2.streamText; } });
 Object.defineProperty(exports, "generateObject", { enumerable: true, get: function () { return client_js_2.generateObject; } });
+Object.defineProperty(exports, "streamObject", { enumerable: true, get: function () { return client_js_2.streamObject; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAKH,SAAS;AACT,yCAAyC;AAAhC,uGAAA,UAAU,OAAA;AAGnB,mCAAmC;AACnC,yCAA0C;AAAjC,wGAAA,WAAW,OAAA;AAUpB,sDAAsD;AACtD,yCAAuE;AAA9D,yGAAA,YAAY,OAAA;AAAE,uGAAA,UAAU,OAAA;AAAE,2GAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAUH,SAAS;AACT,yCAAyC;AAAhC,uGAAA,UAAU,OAAA;AAGnB,mCAAmC;AACnC,yCAA0C;AAAjC,wGAAA,WAAW,OAAA;AAWpB,sDAAsD;AACtD,yCAKqB;AAJpB,yGAAA,YAAY,OAAA;AACZ,uGAAA,UAAU,OAAA;AACV,2GAAA,cAAc,OAAA;AACd,yGAAA,YAAY,OAAA"}

package/dist/stream-object.d.ts

@@ -0,0 +1,39 @@
+import type { z } from "zod";
+import type { KoineConfig, KoineStreamObjectResult } from "./types.js";
+/**
+ * Streams structured JSON objects from Koine gateway service.
+ *
+ * @typeParam T - The type of the expected response object, inferred from schema
+ * @param config - Client configuration including baseUrl, authKey, and timeout
+ * @param options - Request options
+ * @param options.prompt - The user prompt describing what to extract
+ * @param options.schema - Zod schema defining the expected response structure
+ * @param options.system - Optional system prompt for context
+ * @param options.sessionId - Optional session ID to continue a conversation
+ * @param options.signal - Optional AbortSignal for cancellation
+ * @returns KoineStreamObjectResult containing:
+ *   - partialObjectStream: ReadableStream of partial objects (async iterable)
+ *   - object: Promise that resolves to final validated object
+ *   - sessionId: Promise that resolves early when session event arrives
+ *   - usage: Promise that resolves when stream completes
+ * @throws {KoineError} When connection fails or stream encounters an error
+ * @throws {KoineError} With code 'VALIDATION_ERROR' if final object fails schema validation
+ * @throws {KoineError} With code 'NO_OBJECT' if stream ends without receiving final object
+ */
+export declare function streamObject<T>(config: KoineConfig, options: StreamObjectOptions<T>): Promise<KoineStreamObjectResult<T>>;
+/**
+ * Request options for streaming object generation.
+ */
+export interface StreamObjectOptions<T> {
+    /** The user prompt describing what to extract */
+    prompt: string;
+    /** Zod schema defining the expected response structure */
+    schema: z.ZodSchema<T>;
+    /** Optional system prompt for context */
+    system?: string;
+    /** Optional session ID to continue a conversation */
+    sessionId?: string;
+    /** Optional AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=stream-object.d.ts.map

package/dist/stream-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-object.d.ts","sourceRoot":"","sources":["../src/stream-object.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAW7B,OAAO,KAAK,EAEX,WAAW,EACX,uBAAuB,EAMvB,MAAM,YAAY,CAAC;AAWpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EACnC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAiPrC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACrC,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACvB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB"}

package/dist/stream-object.js

@@ -0,0 +1,229 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.streamObject = streamObject;
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const errors_js_1 = require("./errors.js");
+const http_js_1 = require("./http.js");
+const sse_js_1 = require("./stream/sse.js");
+/** Events where parse errors must propagate (vs partial-object which can log and continue) */
+const CRITICAL_EVENTS = new Set([
+    "session",
+    "result",
+    "error",
+    "done",
+    "object",
+]);
+/**
+ * Streams structured JSON objects from Koine gateway service.
+ *
+ * @typeParam T - The type of the expected response object, inferred from schema
+ * @param config - Client configuration including baseUrl, authKey, and timeout
+ * @param options - Request options
+ * @param options.prompt - The user prompt describing what to extract
+ * @param options.schema - Zod schema defining the expected response structure
+ * @param options.system - Optional system prompt for context
+ * @param options.sessionId - Optional session ID to continue a conversation
+ * @param options.signal - Optional AbortSignal for cancellation
+ * @returns KoineStreamObjectResult containing:
+ *   - partialObjectStream: ReadableStream of partial objects (async iterable)
+ *   - object: Promise that resolves to final validated object
+ *   - sessionId: Promise that resolves early when session event arrives
+ *   - usage: Promise that resolves when stream completes
+ * @throws {KoineError} When connection fails or stream encounters an error
+ * @throws {KoineError} With code 'VALIDATION_ERROR' if final object fails schema validation
+ * @throws {KoineError} With code 'NO_OBJECT' if stream ends without receiving final object
+ */
+async function streamObject(config, options) {
+    (0, http_js_1.validateConfig)(config);
+    // Convert Zod schema to JSON Schema for the gateway service
+    const jsonSchema = (0, zod_to_json_schema_1.zodToJsonSchema)(options.schema, {
+        $refStrategy: "none",
+        target: "jsonSchema7",
+    });
+    const response = await (0, http_js_1.safeFetch)(`${config.baseUrl}/stream-object`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.authKey}`,
+        },
+        body: JSON.stringify({
+            system: options.system,
+            prompt: options.prompt,
+            schema: jsonSchema,
+            sessionId: options.sessionId,
+            model: config.model,
+        }),
+        signal: (0, http_js_1.createAbortSignal)(config.timeout, options.signal),
+    }, config.timeout);
+    if (!response.ok) {
+        const errorBody = await (0, http_js_1.safeJsonParse)(response);
+        throw new errors_js_1.KoineError(errorBody?.error || `HTTP ${response.status} ${response.statusText}`, (0, http_js_1.toErrorCode)(errorBody?.code, "HTTP_ERROR"), errorBody?.rawText);
+    }
+    if (!response.body) {
+        throw new errors_js_1.KoineError("No response body from Koine gateway", "NO_RESPONSE_BODY");
+    }
+    // Set up promises for session, usage, and final object
+    let resolveSessionId;
+    let rejectSessionId;
+    const sessionIdPromise = new Promise((resolve, reject) => {
+        resolveSessionId = resolve;
+        rejectSessionId = reject;
+    });
+    let resolveUsage;
+    let rejectUsage;
+    const usagePromise = new Promise((resolve, reject) => {
+        resolveUsage = resolve;
+        rejectUsage = reject;
+    });
+    let resolveObject;
+    let rejectObject;
+    const objectPromise = new Promise((resolve, reject) => {
+        resolveObject = resolve;
+        rejectObject = reject;
+    });
+    let sessionIdReceived = false;
+    let usageReceived = false;
+    let objectReceived = false;
+    // Transform SSE events into partial objects
+    const partialObjectStream = response.body
+        .pipeThrough((0, sse_js_1.createSSEParser)())
+        .pipeThrough(new TransformStream({
+        transform(sseEvent, controller) {
+            const isCriticalEvent = CRITICAL_EVENTS.has(sseEvent.event);
+            try {
+                switch (sseEvent.event) {
+                    case "session": {
+                        const parsed = JSON.parse(sseEvent.data);
+                        if (!sessionIdReceived) {
+                            sessionIdReceived = true;
+                            resolveSessionId(parsed.sessionId);
+                        }
+                        break;
+                    }
+                    case "partial-object": {
+                        const parsed = JSON.parse(sseEvent.data);
+                        // Skip null/non-object partials (can happen during early JSON parsing)
+                        if (parsed.parsed === null ||
+                            typeof parsed.parsed !== "object") {
+                            break;
+                        }
+                        // Try to validate partial object with Zod (warn on failure, don't stop)
+                        const partialResult = options.schema.safeParse(parsed.parsed);
+                        if (partialResult.success) {
+                            controller.enqueue(partialResult.data);
+                        }
+                        else {
+                            // Partial objects may not fully validate during streaming - expected.
+                            // Enqueue raw parsed data for consumers to handle incrementally.
+                            controller.enqueue(parsed.parsed);
+                        }
+                        break;
+                    }
+                    case "object": {
+                        const parsed = JSON.parse(sseEvent.data);
+                        // Validate final object strictly with Zod
+                        const finalResult = options.schema.safeParse(parsed.object);
+                        if (finalResult.success) {
+                            objectReceived = true;
+                            resolveObject(finalResult.data);
+                        }
+                        else {
+                            const error = new errors_js_1.KoineError(`Response validation failed: ${finalResult.error.message}`, "VALIDATION_ERROR", JSON.stringify(parsed.object));
+                            objectReceived = true;
+                            rejectObject(error);
+                        }
+                        break;
+                    }
+                    case "result": {
+                        const parsed = JSON.parse(sseEvent.data);
+                        usageReceived = true;
+                        resolveUsage(parsed.usage);
+                        if (!sessionIdReceived) {
+                            sessionIdReceived = true;
+                            resolveSessionId(parsed.sessionId);
+                        }
+                        break;
+                    }
+                    case "error": {
+                        const parsed = JSON.parse(sseEvent.data);
+                        const error = new errors_js_1.KoineError(parsed.error, (0, http_js_1.toErrorCode)(parsed.code, "STREAM_ERROR"));
+                        usageReceived = true;
+                        rejectUsage(error);
+                        if (!objectReceived) {
+                            objectReceived = true;
+                            rejectObject(error);
+                        }
+                        if (!sessionIdReceived) {
+                            rejectSessionId(error);
+                        }
+                        controller.error(error);
+                        break;
+                    }
+                    case "done": {
+                        break;
+                    }
+                }
+            }
+            catch (parseError) {
+                const parseErrorMessage = parseError instanceof Error
+                    ? parseError.message
+                    : String(parseError);
+                if (isCriticalEvent) {
+                    const error = new errors_js_1.KoineError(`Failed to parse critical SSE event '${sseEvent.event}': ${parseErrorMessage}`, "SSE_PARSE_ERROR", sseEvent.data);
+                    if (!usageReceived) {
+                        usageReceived = true;
+                        rejectUsage(error);
+                    }
+                    if (!objectReceived) {
+                        objectReceived = true;
+                        rejectObject(error);
+                    }
+                    if (!sessionIdReceived) {
+                        rejectSessionId(error);
+                    }
+                    controller.error(error);
+                }
+                else {
+                    // Non-critical event (partial-object) - log warning but continue
+                    console.warn(`[Koine SDK] Failed to parse SSE partial-object event: ${parseErrorMessage}. Raw data: ${sseEvent.data?.substring(0, 100)}`);
+                }
+            }
+        },
+        flush() {
+            // Handle promises that were never resolved/rejected
+            if (!sessionIdReceived) {
+                rejectSessionId(new errors_js_1.KoineError("Stream ended without session ID", "NO_SESSION"));
+            }
+            if (!usageReceived) {
+                rejectUsage(new errors_js_1.KoineError("Stream ended without usage information", "NO_USAGE"));
+            }
+            if (!objectReceived) {
+                rejectObject(new errors_js_1.KoineError("Stream ended without final object", "NO_OBJECT"));
+            }
+        },
+    }));
+    // Augment the stream with Symbol.asyncIterator for ergonomic for-await-of usage
+    const iterablePartialObjectStream = Object.assign(partialObjectStream, {
+        async *[Symbol.asyncIterator]() {
+            const reader = partialObjectStream.getReader();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        return;
+                    yield value;
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        },
+    });
+    return {
+        partialObjectStream: iterablePartialObjectStream,
+        object: objectPromise,
+        sessionId: sessionIdPromise,
+        usage: usagePromise,
+    };
+}
+//# sourceMappingURL=stream-object.js.map

package/dist/stream-object.js.map

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

package/dist/types.d.ts

@@ -71,4 +71,27 @@ export interface SSEErrorEvent {
     readonly error: string;
     readonly code?: string;
 }
+/**
+ * SSE event types from Koine gateway /stream-object endpoint (internal).
+ */
+export interface SSEPartialObjectEvent {
+    readonly partial: string;
+    readonly parsed: unknown;
+}
+export interface SSEObjectEvent {
+    readonly object: unknown;
+}
+/**
+ * Result from streaming object generation.
+ */
+export interface KoineStreamObjectResult<T> {
+    /** Stream of partial objects as they arrive. Supports both ReadableStream methods and async iteration. */
+    readonly partialObjectStream: ReadableStream<T> & AsyncIterable<T>;
+    /** Final validated object (resolves when stream completes via object event, rejects with KoineError if validation fails) */
+    readonly object: Promise<T>;
+    /** Session ID for conversation continuity (resolves early in stream, after session event) */
+    readonly sessionId: Promise<string>;
+    /** Usage stats (resolves when stream completes via result event) */
+    readonly usage: Promise<KoineUsage>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,sGAAsG;IACtG,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACpE,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,sGAAsG;IACtG,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACpE,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACpC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACzC,0GAA0G;IAC1G,QAAQ,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;IACnE,4HAA4H;IAC5H,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;CACpC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@patternzones/koine-sdk",
-	"version": "2.0.4",
+	"version": "2.2.0",
 	"description": "TypeScript SDK for Koine gateway",
 	"repository": {
 		"type": "git",
@@ -26,6 +26,7 @@
 		"lint": "biome check .",
 		"example:hello": "bun --env-file=../../../.env run examples/hello.ts",
 		"example:stream": "bun --env-file=../../../.env run examples/stream.ts",
+		"example:stream-object": "bun --env-file=../../../.env run examples/stream-object.ts",
 		"example:recipe": "bun --env-file=../../../.env run examples/extract-recipe.ts",
 		"example:conversation": "bun --env-file=../../../.env run examples/conversation.ts"
 	},