@bitbitpress/client 0.1.8 → 0.1.10

package/README.md

@@ -411,147 +411,137 @@ console.log('Signal 2 recorded:', response2.recorded);
 
 #### synthesizeItem
 
-Synthesize a single item (batched). Items are automatically batched and sent together after the configured timeout. Returns a promise that resolves with the `data` field from the event (excluding 'connected' and 'complete' events).
+Synthesize a single item (batched). Items are automatically batched and sent together after the configured timeout. Returns a promise that resolves with the final data event for that item's index. Optionally receive streaming data via `onStreamingData` when stream events have `complete: false`.
 
 ```typescript
-client.user.synthesizeItem(item: SynthesizeRequest['items'][number]): Promise<unknown>
+client.user.synthesizeItem(
+  item: SynthesizeItem,
+  onStreamingData?: SynthesizeOnStreamingData
+): Promise<SynthesizeItemResponse>
 ```
 
 ##### Parameters
 
-- `item` (required): A single synthesize item (same format as items in `synthesize`)
+- `item` (required): A single synthesize item (same shape as items in `synthesize`): `inputs`, `output` (schema as JSON string or Zod 4 schema, optional `staleAfter`), optional `configurationKeyName`
+- `onStreamingData` (optional): Callback invoked with streaming data whenever a stream event has `complete: false` for this item. Type: `(data: unknown) => void`.
 
 ##### Returns
 
-- `Promise<unknown>`: A promise that resolves with the `data` field from the event for this specific item. The data will be:
-  - For `DAILY_SUMMARY`: `{ summary: string | null }`
-  - For `CUSTOM`: An object following your schema input, where `fieldNames` are keys
+- `Promise<SynthesizeItemResponse>`: Resolves with the final data event for this item — `data` is the synthesized object (keys match your output schema) when present; `error` is set on failure
 
 ##### Behavior
 
-- Items added within the batch timeout window (default: 250ms) are grouped together and sent in a single request
-- Each item's promise resolves immediately when its data event arrives (based on the `index` field)
-- The batching happens in the background - promises resolve as soon as the batch request is sent
-- Only data events (DAILY_SUMMARY or CUSTOM) resolve the promise - 'connected' and 'complete' events are ignored
-- The batch timeout can be configured when creating the client via `synthesizeBatchTimeout`
+- Items added within the batch timeout window (default: 250ms) are grouped and sent in one request
+- Each item's promise resolves when its final data event arrives (by `index`, with `complete: true` or `error`)
+- If provided, `onStreamingData` is called for each streaming data update (`complete: false`) for this item's index
+- The batch timeout is configurable via `synthesizeBatchTimeout` when creating the client
 
 ##### Example
 
 ```typescript
-// Items are automatically batched and sent together after the timeout
-// Each promise resolves with the data field from the event
-const dailySummaryData = await client.user.synthesizeItem({
-  type: 'DAILY_SUMMARY',
+const result1 = await client.user.synthesizeItem({
+  inputs: [{ type: 'externalId', value: 'article-123' }],
+  output: {
+    schema: JSON.stringify({
+      type: 'object',
+      properties: { title: { type: 'string' }, summary: { type: 'string' } },
+    }),
+  },
 });
-// dailySummaryData will be: { summary: string | null }
-console.log('Daily summary:', dailySummaryData);
-
-const customData = await client.user.synthesizeItem({
-  type: 'CUSTOM',
-  schema: [
-    {
-      fieldName: 'title',
-      fieldDescription: 'The article title',
-      fieldCharacterLimitHint: 100,
-    },
-  ],
-  contentContext: {
-    contentId: 'article-123',
-    contentType: 'article',
-    expandOnContext: true,
+console.log('Synthesized:', result1);
+
+// Or pass a Zod 4 schema (converted to JSON schema string when sending)
+// meta variables include:
+// - description: formatting and purpose of the field
+// - characterLimitHint: rough amount of max characters the field should have, works as a hint
+import { z } from 'zod';
+const result2 = await client.user.synthesizeItem({
+  inputs: [{ type: 'text', value: 'Summarize this' }],
+  output: {
+    schema: z.object({ headline: z.string().meta({ description: 'headline, uppercase', characterLimitHint: 100 }) }),
+    staleAfter: '30m',
   },
 });
-// customData will be an object with keys matching your schema fieldNames
-console.log('Custom data:', customData);
-
-// Both items are sent together in a single batch request
-// Each promise resolves immediately when its data event arrives
 ```
 
 ---
 
 #### synthesize
 
-Synthesize user content (streaming). Returns a stream of events for all items.
+Synthesize content items personalized to the user (streaming SSE). Returns a stream of connection and data events. Data events may be sent multiple times per index as partial object updates; the final event for an index has `complete: true` and the validated object. Optionally pass `onStreamingData(index, data)` to receive streaming data per item index without consuming the stream.
 
 ```typescript
-client.user.synthesize(items: SynthesizeRequest['items']): Promise<AsyncIterable<SynthesizeEvent>>
+client.user.synthesize(
+  items: SynthesizeItems,
+  options?: { onStreamingData?: (index: number, data: unknown) => void }
+): Promise<AsyncIterable<SynthesizeEvent>>
 ```
 
 ##### Parameters
 
-- `items` (required): Array of items to synthesize. Each item can be:
-  - `{ type: "DAILY_SUMMARY" }`: Generate a daily summary
-  - `{ type: "CUSTOM", schema: Array<SchemaField>, contentContext: ContentContext }`: Custom synthesis with schema (contentContext is required for CUSTOM items)
-
-##### SchemaField
-
-- `fieldName` (required): Name of the field
-- `fieldDescription` (required): A prompt describing the value of the field
-- `fieldCharacterLimitHint` (optional): Optional hint for max number of characters that should be returned for this field. Not a guarantee.
-
-##### ContentContext (required for CUSTOM items)
-
-- `contentId` (optional): Your content ID
-- `contentType` (optional): The type of content to synthesize (currently only `"article"`)
-- `expandOnContext` (optional): If `true`, expands on the current context to provide more data to the synthesis. Determines if the synthesis should focus on the content provided, or if it should expand on it.
+- `items` (required): Array of items. Each item has:
+  - `inputs` (optional): Context for synthesis — array of `{ type: "externalId" | "text" | "excludeExternalIds", value: string }` (article ID, freeform text, or comma-separated external IDs to exclude)
+  - `output`: `{ schema: string | ZodType, staleAfter?: string }` — output schema as a JSON string or Zod 4 schema (top-level type must be `"object"`); optional staleness (e.g. `"1h"`, `"30m"`, `"1d"`)
+  - `configurationKeyName` (optional): Key name for configuration
+- `options` (optional): `{ onStreamingData?: (index: number, data: unknown) => void }` — if provided, `onStreamingData` is called for each data event with `complete: false`, with the item's index and streaming data
 
 ##### Returns
 
-- `Promise<AsyncIterable<SynthesizeEvent>>`: An async iterable stream of events
+- `Promise<AsyncIterable<SynthesizeEvent>>`: Async iterable of events
 
 ##### SynthesizeEvent
 
-Events in the stream can be:
-
 - `{ type: "connected" }`: Connection established
-- `{ type: "DAILY_SUMMARY", index: number, data: { summary: string | null } }`: Daily summary data
-- `{ type: "CUSTOM", index: number, data: {...} }`: Custom data following your schema
 - `{ type: "complete" }`: Stream complete
+- `{ index: number, data?: unknown, complete: boolean, error?: string }`: Data event for that item. Multiple events may be sent per index as partial updates; the final event has `complete: true` and the validated object. When `complete` is false, `data` is streaming data (partial object). `error` is set on failure.
 
 ##### Example
 
 ```typescript
+import { z } from 'zod';
+
 const stream = await client.user.synthesize([
   {
-    type: 'DAILY_SUMMARY',
+    inputs: [{ type: 'externalId', value: 'article-123' }],
+    output: {
+      schema: JSON.stringify({
+        type: 'object',
+        properties: { title: { type: 'string' }, summary: { type: 'string' } },
+      }),
+    },
   },
-    {
-      type: 'CUSTOM',
-      schema: [
-        {
-          fieldName: 'title',
-          fieldDescription: 'The article title',
-          fieldCharacterLimitHint: 100,
-        },
-        {
-          fieldName: 'summary',
-          fieldDescription: 'A brief summary',
-          fieldCharacterLimitHint: 200,
-        },
-      ],
-      contentContext: {
-        contentId: 'article-123',
-        contentType: 'article',
-        expandOnContext: true,
-      },
+  {
+    inputs: [{ type: 'text', value: 'Summarize recent tech news' }],
+    output: {
+      schema: z.object({ headline: z.string() }),
+      staleAfter: '1h',
+    },
+  },
+  // Richer Zod schema: array of objects with description and characterLimitHint
+  {
+    inputs: [{ type: 'text', value: 'Summarize key points by topic' }],
+    output: {
+      schema: z.object({
+        summaries: z.array(
+          z.object({
+            summary: z.string().meta({
+              description: 'a single sentence summary of a specific topic or facts',
+              characterLimitHint: 100,
+            }),
+          }),
+        ),
+      }),
     },
+  ],
 ]);
 
 for await (const event of stream) {
-  switch (event.type) {
-    case 'connected':
-      console.log('Stream connected');
-      break;
-    case 'DAILY_SUMMARY':
-      console.log('Daily summary:', event.data);
-      break;
-    case 'CUSTOM':
-      console.log('Custom data:', event.data);
-      break;
-    case 'complete':
-      console.log('Stream complete');
-      break;
+  if ('type' in event) {
+    if (event.type === 'connected') console.log('Stream connected');
+    else if (event.type === 'complete') console.log('Stream complete');
+  } else if ('index' in event) {
+    if (event.error) console.error(`Item ${event.index}:`, event.error);
+    else console.log(`Item ${event.index}:`, event.data);
   }
 }
 ```
@@ -682,42 +672,67 @@ type SignalResponse = {
 
 #### SynthesizeRequest
 
+Request body for POST `/v1/user/synthesize` (from OpenAPI). Each item has `inputs`, `output`, and optional `configurationKeyName`.
+
 ```typescript
 type SynthesizeRequest = {
-  items: Array<
-    | { type: 'DAILY_SUMMARY' }
-    | {
-        type: 'CUSTOM';
-        schema: Array<{
-          fieldName: string;
-          fieldDescription: string;
-          fieldCharacterLimitHint?: number;
-        }>;
-        contentContext: {
-          contentId?: string;
-          contentType?: 'article';
-          expandOnContext?: boolean;
-        };
-      }
-  >;
+  items: Array<{
+    configurationKeyName?: string;
+    inputs?: Array<{ type: 'externalId' | 'text' | 'excludeExternalIds'; value: string }>;
+    output: {
+      schema: string; // JSON schema string; top-level type must be "object"
+      staleAfter?: string;
+    };
+  }>;
 }
 ```
 
+#### SynthesizeItem / SynthesizeItems
+
+Same shape as the request items above, but `output.schema` may be a **string or a Zod 4 schema**; Zod schemas are converted to the expected JSON schema string when sending.
+
+- `SynthesizeItem`: Single item (for `synthesizeItem`).
+- `SynthesizeItems`: Array of items (for `synthesize`).
+- `SynthesizeOutputSchema`: `string | ZodType` (exported for typing `output.schema`).
+
 #### SynthesizeEvent
 
+Stream events (SSE). Connection events use `type`; data events use `index`, optional `data`, required `complete` (true or false), and optional `error`. Multiple data events may be sent per index as partial object updates; the final event for an index has `complete: true` and the validated object.
+
 ```typescript
-type SynthesizeEvent = {
-  type: 'DAILY_SUMMARY' | 'CUSTOM' | 'connected' | 'complete';
-  index?: number;
-  data?: unknown;
-}
+type SynthesizeEvent =
+  | { type: 'connected' }
+  | { type: 'complete' }
+  | { index: number; data?: unknown; complete: boolean; error?: string };
+```
+
+When `complete` is true, `data` is the full synthesized object (keys match your output schema). When `complete` is false, `data` is streaming data (partial update). `error` is set on failure.
+
+#### SynthesizeItemResponse
+
+Return type of `synthesizeItem`. Same shape as a data event payload (without `index`).
+
+```typescript
+type SynthesizeItemResponse = {
+  data?: unknown;   // synthesized object when present
+  error?: string;   // set on failure
+};
+```
+
+#### SynthesizeOnStreamingData
+
+Callback type for receiving streaming data on a single item. Used as the second parameter to `synthesizeItem`. Invoked whenever a stream data event has `complete: false` for that item's index.
+
+```typescript
+type SynthesizeOnStreamingData = (data: unknown) => void;
 ```
 
-For `DAILY_SUMMARY` events, `data` will be:
+#### SynthesizeOptions
+
+Options for `synthesize`. Used to receive streaming data per item index without consuming the stream.
+
 ```typescript
-{
-  summary: string | null;
+interface SynthesizeOptions {
+  onStreamingData?: (index: number, data: unknown) => void;
 }
 ```
-
-For `CUSTOM` events, `data` will be an object following your schema input, where `fieldNames` are keys.

package/dist/examples/basic-usage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"basic-usage.d.ts","sourceRoot":"","sources":["../../src/examples/basic-usage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,iBAAe,YAAY,kBA4B1B;AAGD,iBAAe,gBAAgB,kBAkD9B;AAGD,iBAAe,uBAAuB,kBAmCrC;AAGD,iBAAe,aAAa,kBAqC3B;AAGD,iBAAe,oBAAoB,kBAiClC;AAED,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,aAAa,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"basic-usage.d.ts","sourceRoot":"","sources":["../../src/examples/basic-usage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,iBAAe,YAAY,kBA4B1B;AAGD,iBAAe,gBAAgB,kBAwC9B;AAGD,iBAAe,uBAAuB,kBAiCrC;AAGD,iBAAe,aAAa,kBAqC3B;AAGD,iBAAe,oBAAoB,kBAiClC;AAED,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,aAAa,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/examples/basic-usage.js

@@ -40,43 +40,39 @@ async function streamingExample() {
     await client.user.authenticate("your-user's-auth-sso-token");
     const stream = await client.user.synthesize([
         {
-            type: 'DAILY_SUMMARY',
+            inputs: [{ type: 'externalId', value: 'article-123' }],
+            output: {
+                schema: JSON.stringify({
+                    type: 'object',
+                    properties: { title: { type: 'string' }, summary: { type: 'string' } },
+                }),
+            },
         },
         {
-            type: 'CUSTOM',
-            schema: [
-                {
-                    fieldName: 'title',
-                    fieldDescription: 'The article title',
-                    fieldCharacterLimitHint: 100,
-                },
-                {
-                    fieldName: 'summary',
-                    fieldDescription: 'A brief summary',
-                    fieldCharacterLimitHint: 200,
-                },
-            ],
-            contentContext: {
-                contentId: 'article-123',
-                contentType: 'article',
-                expandOnContext: true,
+            inputs: [{ type: 'text', value: 'Summarize recent tech news' }],
+            output: {
+                schema: JSON.stringify({
+                    type: 'object',
+                    properties: { headline: { type: 'string' } },
+                }),
+                staleAfter: '1h',
             },
         },
     ]);
     for await (const event of stream) {
-        switch (event.type) {
-            case 'connected':
+        if ('type' in event) {
+            if (event.type === 'connected')
                 console.log('Stream connected');
-                break;
-            case 'DAILY_SUMMARY':
-                console.log('Daily summary:', event.data);
-                break;
-            case 'CUSTOM':
-                console.log('Custom data:', event.data);
-                break;
-            case 'complete':
+            else if (event.type === 'complete')
                 console.log('Stream complete');
-                break;
+        }
+        else if ('index' in event) {
+            if (event.error)
+                console.error(`Item ${event.index}:`, event.error);
+            else if (event.complete)
+                console.log(`Item ${event.index}:`, event.data);
+            else
+                console.log(`Item ${event.index} (streaming):`, event.data);
         }
     }
 }
@@ -89,27 +85,25 @@ async function batchedSynthesisExample() {
     // Authenticate first
     await client.user.authenticate("your-user's-auth-sso-token");
     // Items are automatically batched and sent together after the timeout
-    // Each promise resolves with the data field from the event
-    const dailySummaryData = await client.user.synthesizeItem({
-        type: 'DAILY_SUMMARY',
+    // Each promise resolves with the synthesized data for that item's index
+    const result1 = await client.user.synthesizeItem({
+        inputs: [{ type: 'externalId', value: 'article-123' }],
+        output: {
+            schema: JSON.stringify({
+                type: 'object',
+                properties: { title: { type: 'string' }, summary: { type: 'string' } },
+            }),
+        },
     });
-    console.log('Daily summary:', dailySummaryData);
-    const customData = await client.user.synthesizeItem({
-        type: 'CUSTOM',
-        schema: [
-            {
-                fieldName: 'title',
-                fieldDescription: 'The article title',
-                fieldCharacterLimitHint: 100,
-            },
-        ],
-        contentContext: {
-            contentId: 'article-123',
-            contentType: 'article',
-            expandOnContext: true,
+    console.log('Synthesized:', result1);
+    const result2 = await client.user.synthesizeItem({
+        inputs: [{ type: 'text', value: 'Summarize this' }],
+        output: {
+            schema: JSON.stringify({ type: 'object', properties: { headline: { type: 'string' } } }),
+            staleAfter: '30m',
         },
     });
-    console.log('Custom data:', customData);
+    console.log('Synthesized:', result2);
     // Both items are sent together in a single batch request
     // Each promise resolves immediately when its data event arrives
 }

package/dist/examples/basic-usage.js.map

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

package/dist/generated/openapi.d.ts

@@ -573,7 +573,7 @@ export interface paths {
          * Synthesize User Content
          * @description **POST** `/v1/user/synthesize`
          *
-         *     Synthesize content items personalized to the user. Each item specifies a type to inform the type of synthesis to perform.
+         *     Synthesize content items personalized to the user.
          */
         post: {
             parameters: {
@@ -588,70 +588,58 @@ export interface paths {
             requestBody: {
                 content: {
                     "application/json": {
-                        /** @description Array of items to synthesize */
-                        items: ({
-                            /**
-                             * @description Type of synthesis item.
-                             * @enum {string}
-                             */
-                            type: "DAILY_SUMMARY" | "CUSTOM";
-                        } | {
-                            /** @enum {unknown} */
-                            type?: "DAILY_SUMMARY";
-                        } | {
-                            /** @enum {unknown} */
-                            type?: "CUSTOM";
-                            /** @description Schema describing the output format. */
-                            schema: {
-                                /** @description Name of the field */
-                                fieldName: string;
-                                /** @description A prompt describing the value of the field */
-                                fieldDescription: string;
-                                /** @description Optional hint for max number of characters that should be returned for this field. Not a guarantee. */
-                                fieldCharacterLimitHint?: number;
-                            }[];
-                            /** @description Context data to provide to the prompt. */
-                            contentContext: {
-                                /** @description Your content id */
-                                contentId?: string;
+                        /** @description Array of items to synthesize. Each item has inputs and output; optional configurationKeyName to use a named config (omit for default). */
+                        items: {
+                            /** @description Optional configuration key name. Loads an existing synthesis config by this name; omit for default configuration. */
+                            configurationKeyName?: string;
+                            /** @description Inputs used as context for the synthesis: externalId (article ID), or text (freeform text). */
+                            inputs?: {
                                 /**
-                                 * @description The type of content to synthesize
+                                 * @description Type of input: externalId (article) or text (freeform).
                                  * @enum {string}
                                  */
-                                contentType?: "article";
-                                /** @description If true, expands on the current context to provide more data to the synthesis. Determines if the synthesis should focus on the content provided, or if it should expand on it. */
-                                expandOnContext?: boolean;
+                                type: "externalId" | "text" | "excludeExternalIds";
+                                /** @description External ID (e.g. article) for externalId, freeform text for text, or comma-separated list of external IDs to exclude */
+                                value: string;
+                            }[];
+                            /** @description Output definition: schema and optional staleness. */
+                            output: {
+                                /** @description Output schema as a JSON string. Top-level type must be "object". Example: {"type":"object","properties":{"title":{"type":"string","description":"title"}}} */
+                                schema: string;
+                                /** @description Time after which the result is considered stale and will be regenerated again. Examples: "1h", "30m", "1d", "3600" (seconds). */
+                                staleAfter?: string;
                             };
-                        })[];
+                        }[];
                     };
                 };
             };
             responses: {
                 /**
-                 * @description Streaming response (Server-Sent Events). Each event is a JSON object sent as `data: {JSON}\n\n`. Event types:
+                 * @description Streaming response (Server-Sent Events). Each event is a JSON object sent as `data: {JSON}\n\n`.
                  *
                  *     **Connection Events:**
                  *     ```json
                  *     {"type":"connected" | "complete"}
                  *     ```
                  *
-                 *     **Data Events:**
+                 *     **Data Events (success):**
                  *     ```json
                  *     {
-                 *       "type": "DAILY_SUMMARY" | "CUSTOM",
                  *       "index": number,
-                 *       "data": {...}
+                 *       "data": {...},
+                 *       "complete": false | true
                  *     }
                  *     ```
+                 *     `data` is the synthesized object (keys match your output schema). `complete` is `false` for partial streaming updates and `true` for the final validated object for that index.
                  *
-                 *     For `DAILY_SUMMARY` type, `data` will be:
+                 *     **Data Events (error):**
                  *     ```json
                  *     {
-                 *       "summary": string | null
+                 *       "index": number,
+                 *       "error": "error message"
                  *     }
                  *     ```
-                 *
-                 *     For `CUSTOM` type, `data` will be an object following your schema input, where `fieldNames` are keys.
+                 *     Sent when synthesis fails for that item (e.g. resolve failure, exception).
                  */
                 200: {
                     headers: {

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export type { RecommendationsRequest, RecommendationsResponse } from './user/rec
 export type { ProfileResponse } from './user/profile.js';
 export type { ReportRequest, ReportResponse } from './user/report.js';
 export type { TokenRequest, TokenResponse } from './user/token.js';
-export type { SynthesizeRequest } from './user/typeDefs.js';
-export type { SynthesizeEvent } from './user/synthesize.js';
+export type { BitBitPressSynthesizeRequest, RecommendationsRequestBody, SynthesizeInput, SynthesizeItem, SynthesizeItems, SynthesizeOutputSchema, SynthesizeRequest, } from './user/typeDefs.js';
+export type { SynthesizeEvent, SynthesizeItemResponse, SynthesizeOptions } from './user/synthesize.js';
+export type { SynthesizeOnStreamingData } from './user/synthesize-batch-manager.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;;;;;GAKG;AAEH,YAAY,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,WAAW,EACX,QAAQ,GACT,MAAM,cAAc,CAAC;AAGtB,mBAAmB,wBAAwB,CAAC;AAG5C,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACjG,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,yBAAyB,EACzB,WAAW,EACX,QAAQ,GACT,MAAM,cAAc,CAAC;AAGtB,mBAAmB,wBAAwB,CAAC;AAG5C,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC9E,YAAY,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACjG,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,YAAY,EACV,4BAA4B,EAC5B,0BAA0B,EAC1B,eAAe,EACf,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,eAAe,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACvG,YAAY,EAAE,yBAAyB,EAAE,MAAM,oCAAoC,CAAC"}