@bitbitpress/client 0.1.4 → 0.1.5

package/README.md

@@ -47,6 +47,7 @@ More details can also be found in your control room's API docs @ https://your-co
   - [recommendations](#recommendations)
   - [report](#report)
   - [signal](#signal)
+  - [signalItem](#signalitem)
   - [synthesizeItem](#synthesizeitem)
   - [synthesize](#synthesize)
 - [Types](#types)
@@ -68,6 +69,7 @@ new BitBitPressClient(options: BitBitPressClientOptions)
 - `options.headers` (optional): Additional headers to include in all requests
 - `options.timeout` (optional): Request timeout in milliseconds (default: `30000`)
 - `options.synthesizeBatchTimeout` (optional): Batch timeout for `synthesizeItem` in milliseconds (default: `250`)
+- `options.signalBatchTimeout` (optional): Batch timeout for `signalItem` in milliseconds (default: `250`)
 
 ##### Example
 
@@ -76,6 +78,7 @@ const client = new BitBitPressClient({
   baseUrl: 'https://your-control-room.api.dev.bitbitpress.com',
   timeout: 30000,
   synthesizeBatchTimeout: 250,
+  signalBatchTimeout: 250,
 });
 ```
 
@@ -191,6 +194,7 @@ client.user.recommendations(options?: RecommendationsRequest): Promise<Recommend
 
 - `options.limit` (optional): Maximum number of recommendations to return
 - `options.cursor` (optional): Cursor from previous response to fetch the next page
+- `options.fields` (optional): Asset fields to return (dot or bracket notation, e.g. `tags[0]`, `images[1].src`). Allowed: `title`, `tags`, `images`, `videos`, `publishedAt`, `externalId` (your content id), `externalData` and subfields. Returned as JSON string in `fields`.
 
 ##### Returns
 
@@ -200,12 +204,23 @@ client.user.recommendations(options?: RecommendationsRequest): Promise<Recommend
 
 ##### RecommendationItem
 
-- `id?: string`: Your article ID
 - `assetId?: string`: BitBitPress's ID
-- `title?: string`: Article title
-- `content?: string`: Article content
-- `publishedAt?: string`: Publication date (e.g., "2021-01-01")
 - `score?: number`: Recommendation score (e.g., 0.95)
+- `fields?: string`: JSON string of requested asset fields (when `fields` provided in request)
+
+##### Available Fields
+
+Use dot or bracket notation (e.g. `tags[0]`, `images[1].src`). Requested values are returned as a JSON string in each item's `fields` property.
+
+| Field | Type | Structure |
+|-------|------|-----------|
+| `title` | string | Title |
+| `tags` | string[] | Array of strings (auto-extracted or manual tags) |
+| `images` | array | Each item: `{ src, externalId, alt, width, height, credit }` |
+| `videos` | array | Each item: `{ sources: [{ mimeType, src }], externalId, alt, credit, posterUrl, caption, width, height }` |
+| `publishedAt` | string | ISO date when the article was originally published |
+| `externalId` | string | unique identifier from source (your content id) |
+| `externalData` | any | data unique to your content (you must extract subfields that you need from your article data type) |
 
 ##### Example
 
@@ -213,10 +228,22 @@ client.user.recommendations(options?: RecommendationsRequest): Promise<Recommend
 const recommendations = await client.user.recommendations({
   limit: 10,
   cursor: 'optional-cursor-from-previous-response',
+  fields: ['title', 'tags', 'images[0].src', 'publishedAt'],
 });
 
 console.log('Recommendations:', recommendations.items);
 console.log('Next cursor:', recommendations.cursor);
+
+// Access requested fields from the fields JSON string
+if (recommendations.items) {
+  for (const item of recommendations.items) {
+    if (item.fields) {
+      const fields = JSON.parse(item.fields);
+      console.log('Title:', fields.title);
+      console.log('Tags:', fields.tags);
+    }
+  }
+}
 ```
 
 ##### Throws
@@ -259,7 +286,7 @@ await client.user.report({
 
 #### signal
 
-Record a user signal (e.g., clicked topic, read article) to inform profile interests. Signals are used to power a user's recommendations.
+Record user signals (e.g., clicked topic, read article) to inform profile interests. Signals are used to power a user's recommendations.
 
 ```typescript
 client.user.signal(options: SignalRequest): Promise<SignalResponse>
@@ -267,25 +294,88 @@ client.user.signal(options: SignalRequest): Promise<SignalResponse>
 
 ##### Parameters
 
-- `options.signal` (required): User action with the text associated with the interaction (e.g., `'searched for \"best restaurants\"'`)
-- `options.type` (required): Signal type - `"active"` or `"passive"`
-  - `"active"`: Explicit intent (click, search, subscribe)
-  - `"passive"`: Implicit intent (read, scroll, dwell)
-- `options.negative` (optional): When `true`, indicates the signal is negative (e.g., dislike, unfollow). Defaults to `false`. Use sparingly.
-- `options.contentContext` (optional): Context about the content that triggered this signal
-  - `contentId` (required): The ID of the content (e.g., your article ID)
-  - `contentType` (required): The type of content (currently only `"article"`)
+- `options.signals` (required): Array of signals to record. Each signal object contains:
+  - `signal` (required): User action with the text associated with the interaction (e.g., `'searched for \"best restaurants\"'`)
+  - `type` (required): Signal type - `"active"` or `"passive"`
+    - `"active"`: Explicit intent (click, search, subscribe)
+    - `"passive"`: Implicit intent (read, scroll, dwell)
+  - `negative` (optional): When `true`, indicates the signal is negative (e.g., dislike, unfollow). Defaults to `false`. Use sparingly.
+  - `contentContext` (optional): Context about the content that triggered this signal
+    - `contentId` (required): The ID of the content (e.g., your article ID)
+    - `contentType` (required): The type of content (currently only `"article"`)
 
 ##### Returns
 
 - `Promise<SignalResponse>`: Response containing:
-  - `recorded?: boolean`: Whether the signal was recorded (false if no user or empty signal)
+  - `recorded?: boolean`: Whether the signals were recorded (false if no user or no valid signals)
 
 ##### Example
 
 ```typescript
-// Active signal (explicit intent)
+// Record multiple signals at once
 await client.user.signal({
+  signals: [
+    {
+      signal: 'searched "best restaurants"',
+      type: 'active',
+      contentContext: {
+        contentId: 'article-123',
+        contentType: 'article',
+      },
+    },
+    {
+      signal: 'read article about NBA trades',
+      type: 'passive',
+      contentContext: {
+        contentId: 'article-456',
+        contentType: 'article',
+      },
+    },
+    {
+      signal: 'unfollowed topic "Politics"',
+      type: 'active',
+      negative: true,
+    },
+  ],
+});
+```
+
+##### Throws
+
+- `Error`: If the request fails or no data is returned
+
+---
+
+#### signalItem
+
+Record a single signal (batched). Signals are automatically batched and sent together after the configured timeout.
+
+```typescript
+client.user.signalItem(signal: Signal): Promise<SignalResponse>
+```
+
+##### Parameters
+
+- `signal` (required): A single signal object (same format as items in the `signals` array for `signal`)
+
+##### Returns
+
+- `Promise<SignalResponse>`: Response containing:
+  - `recorded?: boolean`: Whether the signal was recorded (false if no user or no valid signals)
+
+##### Behavior
+
+- Signals added within the batch timeout window (default: 250ms) are grouped together and sent in a single request
+- Each signal's promise resolves with the batch response when the request completes
+- The batching happens in the background - promises resolve as soon as the batch request completes
+- The batch timeout can be configured when creating the client via `signalBatchTimeout`
+
+##### Example
+
+```typescript
+// Signals are automatically batched and sent together after the timeout
+// Each promise resolves with the batch response
+const response1 = await client.user.signalItem({
   signal: 'searched "best restaurants"',
   type: 'active',
   contentContext: {
@@ -294,8 +384,7 @@ await client.user.signal({
   },
 });
 
-// Passive signal (implicit intent)
-await client.user.signal({
+const response2 = await client.user.signalItem({
   signal: 'read article about NBA trades',
   type: 'passive',
   contentContext: {
@@ -304,12 +393,10 @@ await client.user.signal({
   },
 });
 
-// Negative signal (use sparingly)
-await client.user.signal({
-  signal: 'unfollowed topic "Politics"',
-  type: 'active',
-  negative: true,
-});
+// Both signals are sent together in a single batch request
+// Each promise resolves when the batch request completes
+console.log('Signal 1 recorded:', response1.recorded);
+console.log('Signal 2 recorded:', response2.recorded);
 ```
 
 ##### Throws
@@ -390,6 +477,7 @@ client.user.synthesize(items: SynthesizeRequest['items']): Promise<AsyncIterable
 
 - `fieldName` (required): Name of the field
 - `fieldDescription` (required): A prompt describing the value of the field
+- `fieldCharacterLimit` (optional): The maximum number of characters that can be returned for this field
 
 ##### ContentContext (required for CUSTOM items)
 
@@ -460,6 +548,7 @@ interface BitBitPressClientConfig {
   headers?: Record<string, string>;
   timeout?: number;
   synthesizeBatchTimeout?: number;
+  signalBatchTimeout?: number;
 }
 ```
 
@@ -488,6 +577,7 @@ type TokenResponse = {
 type RecommendationsRequest = {
   limit?: number;
   cursor?: string;
+  fields?: string[];
 }
 ```
 
@@ -504,13 +594,9 @@ type ProfileResponse = {
 ```typescript
 type RecommendationsResponse = {
   items?: Array<{
-    id?: string;
     assetId?: string;
-    title?: string;
-    summary?: string;
-    content?: string;
-    publishedAt?: string;
     score?: number;
+    fields?: string; // JSON string of requested asset fields
   }>;
   cursor?: string;
 }
@@ -535,6 +621,22 @@ type ReportResponse = unknown;
 
 ```typescript
 type SignalRequest = {
+  signals: Array<{
+    signal: string;
+    type: 'active' | 'passive';
+    negative?: boolean;
+    contentContext?: {
+      contentId: string;
+      contentType: 'article';
+    };
+  }>;
+}
+```
+
+#### Signal
+
+```typescript
+type Signal = {
   signal: string;
   type: 'active' | 'passive';
   negative?: boolean;

package/dist/client.d.ts

@@ -26,6 +26,12 @@ export interface BitBitPressClientConfig {
      * @default 250
      */
     synthesizeBatchTimeout?: number;
+    /**
+     * Batch timeout for signalItem in milliseconds
+     * Signals will be batched and sent after this delay
+     * @default 250
+     */
+    signalBatchTimeout?: number;
 }
 /**
  * Options for creating a BitBitPress client instance
@@ -54,6 +60,10 @@ export declare class BitBitPressClient {
      * Get synthesize batch timeout configuration
      */
     private getSynthesizeBatchTimeout;
+    /**
+     * Get signal batch timeout configuration
+     */
+    private getSignalBatchTimeout;
     /**
      * User-related API methods
      * Provides type-safe access to user endpoints like signal, recommendations, synthesize, etc.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;CAAG;AAE5E;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CACkE;IAChF,OAAO,CAAC,mBAAmB,CAAC,CAAc;gBAE9B,OAAO,EAAE,wBAAwB;IAqB7C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMjC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;;OAGG;IACH,IAAI,IAAI,IAAI,WAAW,CAQtB;CACF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,uBAAuB;CAAG;AAE5E;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CACyF;IACvG,OAAO,CAAC,mBAAmB,CAAC,CAAc;gBAE9B,OAAO,EAAE,wBAAwB;IAsB7C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAMjC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAI7B;;;OAGG;IACH,IAAI,IAAI,IAAI,WAAW,CAStB;CACF"}

package/dist/client.js

@@ -19,6 +19,7 @@ class BitBitPressClient {
             baseUrl: options.baseUrl,
             timeout: options.timeout ?? 30000,
             synthesizeBatchTimeout: options.synthesizeBatchTimeout,
+            signalBatchTimeout: options.signalBatchTimeout,
             fetch: options.fetch ?? (typeof globalThis !== 'undefined' ? globalThis.fetch : undefined),
             headers: options.headers,
         };
@@ -52,13 +53,19 @@ class BitBitPressClient {
     getSynthesizeBatchTimeout() {
         return this.config.synthesizeBatchTimeout;
     }
+    /**
+     * Get signal batch timeout configuration
+     */
+    getSignalBatchTimeout() {
+        return this.config.signalBatchTimeout;
+    }
     /**
      * User-related API methods
      * Provides type-safe access to user endpoints like signal, recommendations, synthesize, etc.
      */
     get user() {
         if (!this.userMethodsInstance) {
-            this.userMethodsInstance = (0, index_js_1.createUserMethods)(this.getRequestConfig(), this.getSynthesizeBatchTimeout());
+            this.userMethodsInstance = (0, index_js_1.createUserMethods)(this.getRequestConfig(), this.getSynthesizeBatchTimeout(), this.getSignalBatchTimeout());
         }
         return this.userMethodsInstance;
     }

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AACA,8CAAsE;AAwCtE;;;;;GAKG;AACH,MAAa,iBAAiB;IACpB,MAAM,CACkE;IACxE,mBAAmB,CAAe;IAE1C,YAAY,OAAiC;QAC3C,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;YACjC,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;YACtD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,UAAU,KAAK,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1F,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC;QAEF,8BAA8B;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,iIAAiI,CAClI,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;QAC9B,gFAAgF;QAChF,IAAI,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACvC,CAAC;IAED;;OAEG;IACK,gBAAgB;QACtB,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAM;YACzB,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;SAC7B,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,yBAAyB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,IAAI,IAAI;QACN,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,IAAI,CAAC,mBAAmB,GAAG,IAAA,4BAAiB,EAC1C,IAAI,CAAC,gBAAgB,EAAE,EACvB,IAAI,CAAC,yBAAyB,EAAE,CACjC,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,mBAAmB,CAAC;IAClC,CAAC;CACF;AAnED,8CAmEC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AACA,8CAAsE;AA+CtE;;;;;GAKG;AACH,MAAa,iBAAiB;IACpB,MAAM,CACyF;IAC/F,mBAAmB,CAAe;IAE1C,YAAY,OAAiC;QAC3C,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC3F,CAAC;QAED,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;YACjC,sBAAsB,EAAE,OAAO,CAAC,sBAAsB;YACtD,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,UAAU,KAAK,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;YAC1F,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC;QAEF,8BAA8B;QAC9B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,iIAAiI,CAClI,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,OAAe;QACxB,IAAI,CAAC,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC;QAC9B,gFAAgF;QAChF,IAAI,CAAC,mBAAmB,GAAG,SAAS,CAAC;IACvC,CAAC;IAED;;OAEG;IACK,gBAAgB;QACtB,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;YAC5B,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAM;YACzB,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;SAC7B,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,yBAAyB;QAC/B,OAAO,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAAC;IAC5C,CAAC;IAED;;OAEG;IACK,qBAAqB;QAC3B,OAAO,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC;IACxC,CAAC;IAED;;;OAGG;IACH,IAAI,IAAI;QACN,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,IAAI,CAAC,mBAAmB,GAAG,IAAA,4BAAiB,EAC1C,IAAI,CAAC,gBAAgB,EAAE,EACvB,IAAI,CAAC,yBAAyB,EAAE,EAChC,IAAI,CAAC,qBAAqB,EAAE,CAC7B,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,mBAAmB,CAAC;IAClC,CAAC;CACF;AA5ED,8CA4EC"}

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

@@ -7,5 +7,6 @@ declare function basicExample(): Promise<void>;
 declare function streamingExample(): Promise<void>;
 declare function batchedSynthesisExample(): Promise<void>;
 declare function signalExample(): Promise<void>;
-export { basicExample, streamingExample, batchedSynthesisExample, signalExample };
+declare function batchedSignalExample(): Promise<void>;
+export { basicExample, streamingExample, batchedSynthesisExample, signalExample, batchedSignalExample };
 //# sourceMappingURL=basic-usage.d.ts.map

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,kBAwB1B;AAGD,iBAAe,gBAAgB,kBAyC9B;AAGD,iBAAe,uBAAuB,kBA4BrC;AAGD,iBAAe,aAAa,kBAkC3B;AAED,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,aAAa,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,kBAyC9B;AAGD,iBAAe,uBAAuB,kBA4BrC;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

@@ -16,14 +16,18 @@ async function basicExample() {
         limit: 10,
     });
     console.log('Recommendations:', recommendations.items);
-    // Record a user signal (e.g., user clicked on an article)
+    // Record user signals (e.g., user clicked on an article)
     const signalResult = await client.user.signal({
-        signal: 'clicked "Warriors intend to keep Jimmy Butler despite season-ending injury"',
-        type: 'active',
-        contentContext: {
-            contentId: 'article-123',
-            contentType: 'article',
-        },
+        signals: [
+            {
+                signal: 'searched "best restaurants"',
+                type: 'active',
+                contentContext: {
+                    contentId: 'article-123',
+                    contentType: 'article',
+                },
+            },
+        ],
     });
     console.log('Signal recorded:', signalResult.recorded);
 }
@@ -100,8 +104,47 @@ async function signalExample() {
     });
     // Authenticate first
     await client.user.authenticate("your-user's-auth-sso-token");
-    // Record an active signal (explicit intent like click, search, subscribe)
+    // Record multiple signals at once
     await client.user.signal({
+        signals: [
+            // Active signal (explicit intent like click, search, subscribe)
+            {
+                signal: 'clicked "Warriors intend to keep Jimmy Butler despite season-ending injury"',
+                type: 'active',
+                contentContext: {
+                    contentId: 'article-123',
+                    contentType: 'article',
+                },
+            },
+            // Passive signal (implicit like read, scroll, dwell)
+            {
+                signal: 'read about NBA trades',
+                type: 'passive',
+                contentContext: {
+                    contentId: 'article-456',
+                    contentType: 'article',
+                },
+            },
+            // Negative signal (e.g., dislike, unfollow) - use sparingly
+            {
+                signal: 'unfollowed topic "Politics"',
+                type: 'active',
+                negative: true,
+            },
+        ],
+    });
+}
+// Example 5: Batched signals with signalItem
+async function batchedSignalExample() {
+    const client = new BitBitPressClient({
+        baseUrl: 'https://your-control-room.api.dev.bitbitpress.com',
+        signalBatchTimeout: 250, // Optional: customize batch timeout
+    });
+    // Authenticate first
+    await client.user.authenticate("your-user's-auth-sso-token");
+    // Signals are automatically batched and sent together after the timeout
+    // Each promise resolves with the batch response
+    const response1 = await client.user.signalItem({
         signal: 'clicked "Warriors intend to keep Jimmy Butler despite season-ending injury"',
         type: 'active',
         contentContext: {
@@ -109,8 +152,7 @@ async function signalExample() {
             contentType: 'article',
         },
     });
-    // Record a passive signal (implicit like read, scroll, dwell)
-    await client.user.signal({
+    const response2 = await client.user.signalItem({
         signal: 'read about NBA trades',
         type: 'passive',
         contentContext: {
@@ -118,12 +160,10 @@ async function signalExample() {
             contentType: 'article',
         },
     });
-    // Record a negative signal (e.g., dislike, unfollow) - use sparingly
-    await client.user.signal({
-        signal: 'unfollowed topic "Politics"',
-        type: 'active',
-        negative: true,
-    });
+    // Both signals are sent together in a single batch request
+    // Each promise resolves when the batch request completes
+    console.log('Signal 1 recorded:', response1.recorded);
+    console.log('Signal 2 recorded:', response2.recorded);
 }
-export { basicExample, streamingExample, batchedSynthesisExample, signalExample };
+export { basicExample, streamingExample, batchedSynthesisExample, signalExample, batchedSignalExample };
 //# sourceMappingURL=basic-usage.js.map

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":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,6CAA6C;AAC7C,KAAK,UAAU,YAAY;IACzB,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;QACnC,OAAO,EAAE,mDAAmD;KAC7D,CAAC,CAAC;IAEH,gFAAgF;IAChF,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,4BAA4B,CAAC,CAAC;IAE7D,sBAAsB;IACtB,MAAM,eAAe,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC;QACxD,KAAK,EAAE,EAAE;KACV,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAEvD,yDAAyD;IACzD,MAAM,YAAY,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QAC5C,OAAO,EAAE;YACP;gBACE,MAAM,EAAE,6BAA6B;gBACrC,IAAI,EAAE,QAAQ;gBACd,cAAc,EAAE;oBACd,SAAS,EAAE,aAAa;oBACxB,WAAW,EAAE,SAAS;iBACvB;aACF;SACF;KACF,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;AACzD,CAAC;AAED,iCAAiC;AACjC,KAAK,UAAU,gBAAgB;IAC7B,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;QACnC,OAAO,EAAE,mDAAmD;KAC7D,CAAC,CAAC;IAEH,qBAAqB;IACrB,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,4BAA4B,CAAC,CAAC;IAE7D,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;QAC1C;YACE,IAAI,EAAE,eAAe;SACtB;QACD;YACE,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE;gBACN,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE;gBAC7D,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,iBAAiB,EAAE;aAC9D;YACD,cAAc,EAAE;gBACd,SAAS,EAAE,aAAa;gBACxB,WAAW,EAAE,SAAS;aACvB;SACF;KACF,CAAC,CAAC;IAEH,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QACjC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,WAAW;gBACd,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;gBAChC,MAAM;YACR,KAAK,eAAe;gBAClB,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC1C,MAAM;YACR,KAAK,QAAQ;gBACX,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;gBACxC,MAAM;YACR,KAAK,UAAU;gBACb,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;gBAC/B,MAAM;QACV,CAAC;IACH,CAAC;AACH,CAAC;AAED,mDAAmD;AACnD,KAAK,UAAU,uBAAuB;IACpC,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;QACnC,OAAO,EAAE,mDAAmD;QAC5D,sBAAsB,EAAE,GAAG,EAAE,oCAAoC;KAClE,CAAC,CAAC;IAEH,qBAAqB;IACrB,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,4BAA4B,CAAC,CAAC;IAE7D,sEAAsE;IACtE,2DAA2D;IAC3D,MAAM,gBAAgB,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC;QACxD,IAAI,EAAE,eAAe;KACtB,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC;IAEhD,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC;QAClD,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,CAAC;QACvE,cAAc,EAAE;YACd,SAAS,EAAE,aAAa;YACxB,WAAW,EAAE,SAAS;SACvB;KACF,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;IAExC,yDAAyD;IACzD,gEAAgE;AAClE,CAAC;AAED,oCAAoC;AACpC,KAAK,UAAU,aAAa;IAC1B,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;QACnC,OAAO,EAAE,mDAAmD;KAC7D,CAAC,CAAC;IAEH,qBAAqB;IACrB,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,4BAA4B,CAAC,CAAC;IAE7D,kCAAkC;IAClC,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;QACvB,OAAO,EAAE;YACP,gEAAgE;YAChE;gBACE,MAAM,EAAE,6EAA6E;gBACrF,IAAI,EAAE,QAAQ;gBACd,cAAc,EAAE;oBACd,SAAS,EAAE,aAAa;oBACxB,WAAW,EAAE,SAAS;iBACvB;aACF;YACD,qDAAqD;YACrD;gBACE,MAAM,EAAE,uBAAuB;gBAC/B,IAAI,EAAE,SAAS;gBACf,cAAc,EAAE;oBACd,SAAS,EAAE,aAAa;oBACxB,WAAW,EAAE,SAAS;iBACvB;aACF;YACD,4DAA4D;YAC5D;gBACE,MAAM,EAAE,6BAA6B;gBACrC,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;aACf;SACF;KACF,CAAC,CAAC;AACL,CAAC;AAED,6CAA6C;AAC7C,KAAK,UAAU,oBAAoB;IACjC,MAAM,MAAM,GAAG,IAAI,iBAAiB,CAAC;QACnC,OAAO,EAAE,mDAAmD;QAC5D,kBAAkB,EAAE,GAAG,EAAE,oCAAoC;KAC9D,CAAC,CAAC;IAEH,qBAAqB;IACrB,MAAM,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,4BAA4B,CAAC,CAAC;IAE7D,wEAAwE;IACxE,gDAAgD;IAChD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;QAC7C,MAAM,EAAE,6EAA6E;QACrF,IAAI,EAAE,QAAQ;QACd,cAAc,EAAE;YACd,SAAS,EAAE,aAAa;YACxB,WAAW,EAAE,SAAS;SACvB;KACF,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;QAC7C,MAAM,EAAE,uBAAuB;QAC/B,IAAI,EAAE,SAAS;QACf,cAAc,EAAE;YACd,SAAS,EAAE,aAAa;YACxB,WAAW,EAAE,SAAS;SACvB;KACF,CAAC,CAAC;IAEH,2DAA2D;IAC3D,yDAAyD;IACzD,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;AACxD,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,aAAa,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/generated/openapi.d.ts

@@ -225,6 +225,20 @@ export interface paths {
         /**
          * Retrieve User Recommendations
          * @description **POST** `/v1/user/recommendations` Returns recommended articles for the authenticated user based on their interests.
+         *
+         *     #### Available fields (`fields` in request body)
+         *
+         *     Use dot or bracket notation (e.g. `tags[0]`, `images[1].src`). Requested values are returned as a JSON string in each item's `fields` property.
+         *
+         *     | Field | Type | Structure |
+         *     |-------|------|-----------|
+         *     | `title` | string | Title |
+         *     | `tags` | string[] | Array of strings (auto-extracted or manual tags) |
+         *     | `images` | array | Each item: `{ src, externalId, alt, width, height, credit }` |
+         *     | `videos` | array | Each item: `{ sources: [{ mimeType, src }], externalId, alt, credit, posterUrl, caption, width, height }` |
+         *     | `publishedAt` | string | ISO date when the article was originally published |
+         *     | `externalId` | string | unique identifier from source (your content id) |
+         *     | `externalData` | any | data unique to your content (you must extract subfields that you need from your article data type) |
          */
         post: {
             parameters: {
@@ -243,6 +257,8 @@ export interface paths {
                         limit?: number;
                         /** @description Cursor from previous response to fetch the next page of recommendations */
                         cursor?: string;
+                        /** @description Asset fields to return (dot or bracket notation, e.g. tags[0], images[1].src). Allowed: title, tags, images, videos, publishedAt, externalId (your content id), externalData, and subfields. Returned as JSON string in `fields`. */
+                        fields?: string[];
                     };
                 };
             };
@@ -260,18 +276,12 @@ export interface paths {
                             data?: {
                                 /** @description List of recommended articles */
                                 items?: {
-                                    /** @example Your article id */
-                                    id?: string;
                                     /** @example BitBitPress's id */
                                     assetId?: string;
-                                    /** @example Title */
-                                    title?: string;
-                                    /** @example Content */
-                                    content?: string;
-                                    /** @example 2021-01-01 */
-                                    publishedAt?: string;
                                     /** @example 0.95 */
                                     score?: number;
+                                    /** @description JSON string of requested asset fields (when `fields` provided in request) */
+                                    fields?: string;
                                 }[];
                                 /** @description Cursor to request the next page, if any */
                                 cursor?: string;
@@ -434,8 +444,8 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Record User Signal
-         * @description **POST** `/v1/user/signal` Records a user signal (e.g. clicked topic, read article) to inform profile interests. Signals are used power a user's recommendations.
+         * Record User Signals
+         * @description **POST** `/v1/user/signal` Records user signals (e.g. clicked topic, read article) to inform profile interests. Signals power the user's recommendations.
          */
         post: {
             parameters: {
@@ -450,30 +460,33 @@ export interface paths {
             requestBody: {
                 content: {
                     "application/json": {
-                        /** @description User action with the text associated with the interaction. (e.g. liked "Warriors intend to keep Jimmy Butler despite season-ending injury") */
-                        signal: string;
-                        /**
-                         * @description `active` = explicit intent (click, search, subscribe). `passive` = implicit (read, scroll, dwell).
-                         * @enum {string}
-                         */
-                        type: "active" | "passive";
-                        /** @description When true, indicates the signal is negative (e.g. dislike, unfollow). Use sparingly. Optional; defaults to false. */
-                        negative?: boolean;
-                        /** @description Optional context about the content that triggered this signal. */
-                        contentContext?: {
-                            /** @description The ID of the content (e.g. article ID). */
-                            contentId: string;
+                        /** @description Array of signals to record. */
+                        signals: {
+                            /** @description User action with the text associated with the interaction. (e.g. liked "Warriors intend to keep Jimmy Butler despite season-ending injury") */
+                            signal: string;
                             /**
-                             * @description The type of content.
+                             * @description `active` = explicit intent (click, search, subscribe). `passive` = implicit (read, scroll, dwell).
                              * @enum {string}
                              */
-                            contentType: "article";
-                        };
+                            type: "active" | "passive";
+                            /** @description When true, indicates the signal is negative (e.g. dislike, unfollow). Use sparingly. Optional; defaults to false. */
+                            negative?: boolean;
+                            /** @description Optional context about the content that triggered this signal. */
+                            contentContext?: {
+                                /** @description The ID of the content (e.g. article ID). */
+                                contentId: string;
+                                /**
+                                 * @description The type of content.
+                                 * @enum {string}
+                                 */
+                                contentType: "article";
+                            };
+                        }[];
                     };
                 };
             };
             responses: {
-                /** @description Signal recorded */
+                /** @description Signals recorded */
                 200: {
                     headers: {
                         [name: string]: unknown;
@@ -488,7 +501,7 @@ export interface paths {
                             /** @description Response payload */
                             data?: {
                                 /**
-                                 * @description Whether the signal was recorded (false if no app user or empty signal)
+                                 * @description Whether the signals were recorded (false if no app user or no valid signals)
                                  * @example true
                                  */
                                 recorded?: boolean;
@@ -592,6 +605,8 @@ export interface paths {
                                 fieldName: string;
                                 /** @description A prompt describing the value of the field */
                                 fieldDescription: string;
+                                /** @description Optional max number of characters that can be returned for this field */
+                                fieldCharacterLimit?: number;
                             }[];
                             /** @description Context data to provide to the prompt. */
                             contentContext: {

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type { BitBitPressClientConfig, BitBitPressClientOptions } from './client
 export { BitBitPressClient } from './client.js';
 export type * from './generated/openapi.js';
 export type { UserMethods } from './user/index.js';
-export type { SignalRequest, SignalResponse } from './user/signal.js';
+export type { Signal, SignalRequest, SignalResponse } from './user/signal.js';
 export type { RecommendationsRequest, RecommendationsResponse } from './user/recommendations.js';
 export type { ProfileResponse } from './user/profile.js';
 export type { ReportRequest, ReportResponse } from './user/report.js';

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;AAGhD,mBAAmB,wBAAwB,CAAC;AAG5C,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACtE,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;AAGhD,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"}

package/dist/user/index.d.ts

@@ -2,7 +2,7 @@ import type { RequestConfig } from '../request.js';
 import { type RecommendationsRequest, type RecommendationsResponse } from './recommendations.js';
 import { type ProfileResponse } from './profile.js';
 import { type ReportRequest, type ReportResponse } from './report.js';
-import { type SignalRequest, type SignalResponse } from './signal.js';
+import { type Signal, type SignalRequest, type SignalResponse } from './signal.js';
 import { type SynthesizeEvent } from './synthesize.js';
 import { type TokenRequest, type TokenResponse } from './token.js';
 import type { SynthesizeRequest } from './typeDefs.js';
@@ -47,12 +47,20 @@ export interface UserMethods {
      */
     report(options: ReportRequest): Promise<NonNullable<ReportResponse>>;
     /**
-     * Record a user signal (e.g. clicked topic, read article) to inform profile interests
+     * Record user signals (e.g. clicked topic, read article) to inform profile interests
      *
-     * @param options - Signal request parameters
+     * @param options - Signal request parameters containing an array of signals
      * @returns Promise that resolves with the signal response
      */
     signal(options: SignalRequest): Promise<NonNullable<SignalResponse>>;
+    /**
+     * Record a single signal (batched)
+     * Signals are batched and sent together after the configured timeout
+     *
+     * @param signal - Single signal to record
+     * @returns Promise that resolves with the signal response
+     */
+    signalItem(signal: Signal): Promise<NonNullable<SignalResponse>>;
     /**
      * Synthesize user content (streaming)
      *
@@ -72,5 +80,5 @@ export interface UserMethods {
 /**
  * User-related API methods
  */
-export declare function createUserMethods(config: RequestConfig, synthesizeBatchTimeout?: number): UserMethods;
+export declare function createUserMethods(config: RequestConfig, synthesizeBatchTimeout?: number, signalBatchTimeout?: number): UserMethods;
 //# sourceMappingURL=index.d.ts.map

package/dist/user/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/user/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAa,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAElE;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAEjG;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IAErE;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IAErE;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IAEvF;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,EAAE,sBAAsB,GAAE,MAAY,GAAG,WAAW,CAyC1G"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/user/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAa,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEjG,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,EAAiB,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAElE;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC,CAAC;IAEjG;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IAErE;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IAErE;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;IAEvF;;;;;;OAMG;IACH,cAAc,CAAC,IAAI,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,sBAAsB,GAAE,MAAY,EACpC,kBAAkB,GAAE,MAAY,GAC/B,WAAW,CA8Cb"}

package/dist/user/index.js

@@ -6,12 +6,13 @@ const recommendations_js_1 = require("./recommendations.js");
 const profile_js_1 = require("./profile.js");
 const report_js_1 = require("./report.js");
 const signal_js_1 = require("./signal.js");
+const signal_batch_manager_js_1 = require("./signal-batch-manager.js");
 const synthesize_js_1 = require("./synthesize.js");
 const token_js_1 = require("./token.js");
 /**
  * User-related API methods
  */
-function createUserMethods(config, synthesizeBatchTimeout = 250) {
+function createUserMethods(config, synthesizeBatchTimeout = 250, signalBatchTimeout = 250) {
     // Store token in closure - will be set by authenticate method
     let userToken;
     // Create a config getter that includes the user token
@@ -19,15 +20,17 @@ function createUserMethods(config, synthesizeBatchTimeout = 250) {
         ...config,
         token: userToken,
     });
-    const batchManager = new batch_manager_js_1.SynthesizeBatchManager(getConfigWithToken(), synthesizeBatchTimeout);
+    const synthesizeBatchManager = new batch_manager_js_1.SynthesizeBatchManager(getConfigWithToken(), synthesizeBatchTimeout);
+    const signalBatchManager = new signal_batch_manager_js_1.SignalBatchManager(getConfigWithToken(), signalBatchTimeout);
     return {
         async authenticate(ssoToken) {
             const tokenResponse = await (0, token_js_1.exchangeToken)(config, ssoToken);
             const accessToken = tokenResponse?.idToken || tokenResponse?.accessToken;
             if (accessToken) {
                 userToken = accessToken;
-                // Update batch manager config with new token
-                batchManager.updateConfig(getConfigWithToken());
+                // Update batch manager configs with new token
+                synthesizeBatchManager.updateConfig(getConfigWithToken());
+                signalBatchManager.updateConfig(getConfigWithToken());
             }
             else {
                 throw new Error('Token exchange failed: no access token in response');
@@ -38,8 +41,9 @@ function createUserMethods(config, synthesizeBatchTimeout = 250) {
         recommendations: (options) => (0, recommendations_js_1.getRecommendations)(getConfigWithToken(), options),
         report: (options) => (0, report_js_1.reportBit)(getConfigWithToken(), options),
         signal: (options) => (0, signal_js_1.recordSignal)(getConfigWithToken(), options),
+        signalItem: (signal) => signalBatchManager.addSignal(signal),
         synthesize: (items) => (0, synthesize_js_1.synthesize)(getConfigWithToken(), items),
-        synthesizeItem: (item) => batchManager.addItem(item),
+        synthesizeItem: (item) => synthesizeBatchManager.addItem(item),
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/user/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/user/index.ts"],"names":[],"mappings":";;AAwFA,8CAyCC;AAhID,yDAA4D;AAC5D,6DAI8B;AAC9B,6CAAgE;AAChE,2CAAiF;AACjF,2CAAoF;AACpF,mDAAmE;AACnE,yCAAkF;AA0ElF;;GAEG;AACH,SAAgB,iBAAiB,CAAC,MAAqB,EAAE,yBAAiC,GAAG;IAC3F,8DAA8D;IAC9D,IAAI,SAA6B,CAAC;IAElC,sDAAsD;IACtD,MAAM,kBAAkB,GAAG,GAAkB,EAAE,CAAC,CAAC;QAC/C,GAAG,MAAM;QACT,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,IAAI,yCAAsB,CAAC,kBAAkB,EAAE,EAAE,sBAAsB,CAAC,CAAC;IAE9F,OAAO;QACL,KAAK,CAAC,YAAY,CAAC,QAAgB;YACjC,MAAM,aAAa,GAAG,MAAM,IAAA,wBAAa,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC5D,MAAM,WAAW,GAAG,aAAa,EAAE,OAAO,IAAI,aAAa,EAAE,WAAW,CAAC;YACzE,IAAI,WAAW,EAAE,CAAC;gBAChB,SAAS,GAAG,WAAW,CAAC;gBACxB,6CAA6C;gBAC7C,YAAY,CAAC,YAAY,CAAC,kBAAkB,EAAE,CAAC,CAAC;YAClD,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACxE,CAAC;QACH,CAAC;QAED,KAAK,EAAE,CAAC,QAAkC,EAAE,EAAE,CAAC,IAAA,wBAAa,EAAC,MAAM,EAAE,QAAQ,CAAC;QAE9E,OAAO,EAAE,GAAG,EAAE,CAAC,IAAA,uBAAU,EAAC,kBAAkB,EAAE,CAAC;QAE/C,eAAe,EAAE,CAAC,OAAgC,EAAE,EAAE,CACpD,IAAA,uCAAkB,EAAC,kBAAkB,EAAE,EAAE,OAAO,CAAC;QAEnD,MAAM,EAAE,CAAC,OAAsB,EAAE,EAAE,CAAC,IAAA,qBAAS,EAAC,kBAAkB,EAAE,EAAE,OAAO,CAAC;QAE5E,MAAM,EAAE,CAAC,OAAsB,EAAE,EAAE,CAAC,IAAA,wBAAY,EAAC,kBAAkB,EAAE,EAAE,OAAO,CAAC;QAE/E,UAAU,EAAE,CAAC,KAAiC,EAAE,EAAE,CAAC,IAAA,0BAAU,EAAC,kBAAkB,EAAE,EAAE,KAAK,CAAC;QAE1F,cAAc,EAAE,CAAC,IAAwC,EAAoB,EAAE,CAC7E,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC;KAC7B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/user/index.ts"],"names":[],"mappings":";;AAkGA,8CAkDC;AAnJD,yDAA4D;AAC5D,6DAI8B;AAC9B,6CAAgE;AAChE,2CAAiF;AACjF,2CAAiG;AACjG,uEAA+D;AAC/D,mDAAmE;AACnE,yCAAkF;AAmFlF;;GAEG;AACH,SAAgB,iBAAiB,CAC/B,MAAqB,EACrB,yBAAiC,GAAG,EACpC,qBAA6B,GAAG;IAEhC,8DAA8D;IAC9D,IAAI,SAA6B,CAAC;IAElC,sDAAsD;IACtD,MAAM,kBAAkB,GAAG,GAAkB,EAAE,CAAC,CAAC;QAC/C,GAAG,MAAM;QACT,KAAK,EAAE,SAAS;KACjB,CAAC,CAAC;IAEH,MAAM,sBAAsB,GAAG,IAAI,yCAAsB,CAAC,kBAAkB,EAAE,EAAE,sBAAsB,CAAC,CAAC;IACxG,MAAM,kBAAkB,GAAG,IAAI,4CAAkB,CAAC,kBAAkB,EAAE,EAAE,kBAAkB,CAAC,CAAC;IAE5F,OAAO;QACL,KAAK,CAAC,YAAY,CAAC,QAAgB;YACjC,MAAM,aAAa,GAAG,MAAM,IAAA,wBAAa,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC5D,MAAM,WAAW,GAAG,aAAa,EAAE,OAAO,IAAI,aAAa,EAAE,WAAW,CAAC;YACzE,IAAI,WAAW,EAAE,CAAC;gBAChB,SAAS,GAAG,WAAW,CAAC;gBACxB,8CAA8C;gBAC9C,sBAAsB,CAAC,YAAY,CAAC,kBAAkB,EAAE,CAAC,CAAC;gBAC1D,kBAAkB,CAAC,YAAY,CAAC,kBAAkB,EAAE,CAAC,CAAC;YACxD,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACxE,CAAC;QACH,CAAC;QAED,KAAK,EAAE,CAAC,QAAkC,EAAE,EAAE,CAAC,IAAA,wBAAa,EAAC,MAAM,EAAE,QAAQ,CAAC;QAE9E,OAAO,EAAE,GAAG,EAAE,CAAC,IAAA,uBAAU,EAAC,kBAAkB,EAAE,CAAC;QAE/C,eAAe,EAAE,CAAC,OAAgC,EAAE,EAAE,CACpD,IAAA,uCAAkB,EAAC,kBAAkB,EAAE,EAAE,OAAO,CAAC;QAEnD,MAAM,EAAE,CAAC,OAAsB,EAAE,EAAE,CAAC,IAAA,qBAAS,EAAC,kBAAkB,EAAE,EAAE,OAAO,CAAC;QAE5E,MAAM,EAAE,CAAC,OAAsB,EAAE,EAAE,CAAC,IAAA,wBAAY,EAAC,kBAAkB,EAAE,EAAE,OAAO,CAAC;QAE/E,UAAU,EAAE,CAAC,MAAc,EAAwC,EAAE,CACnE,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAC;QAEtC,UAAU,EAAE,CAAC,KAAiC,EAAE,EAAE,CAAC,IAAA,0BAAU,EAAC,kBAAkB,EAAE,EAAE,KAAK,CAAC;QAE1F,cAAc,EAAE,CAAC,IAAwC,EAAoB,EAAE,CAC7E,sBAAsB,CAAC,OAAO,CAAC,IAAI,CAAC;KACvC,CAAC;AACJ,CAAC"}

package/dist/user/signal-batch-manager.d.ts

@@ -0,0 +1,22 @@
+import type { RequestConfig } from '../request.js';
+import { type Signal } from './signal.js';
+/**
+ * Batch manager for signalItem
+ * Batches individual signals and sends them together after the timeout
+ */
+export declare class SignalBatchManager {
+    private queue;
+    private timer;
+    private config;
+    private batchTimeout;
+    constructor(config: RequestConfig, batchTimeout: number);
+    /**
+     * Update the request configuration (e.g., when token changes)
+     */
+    updateConfig(config: RequestConfig): void;
+    addSignal(signal: Signal): Promise<{
+        recorded?: boolean;
+    }>;
+    private flush;
+}
+//# sourceMappingURL=signal-batch-manager.d.ts.map

package/dist/user/signal-batch-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-batch-manager.d.ts","sourceRoot":"","sources":["../../src/user/signal-batch-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAkBxD;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAIL;IACR,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM;IAKvD;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIzC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;YAe5C,KAAK;CA6BpB"}

package/dist/user/signal-batch-manager.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignalBatchManager = void 0;
+const signal_js_1 = require("./signal.js");
+// Timer functions for cross-platform compatibility
+function getSetTimeout() {
+    return setTimeout;
+}
+function getClearTimeout() {
+    return clearTimeout;
+}
+const setTimer = getSetTimeout();
+const clearTimer = getClearTimeout();
+/**
+ * Batch manager for signalItem
+ * Batches individual signals and sends them together after the timeout
+ */
+class SignalBatchManager {
+    queue = [];
+    timer = null;
+    config;
+    batchTimeout;
+    constructor(config, batchTimeout) {
+        this.config = config;
+        this.batchTimeout = batchTimeout;
+    }
+    /**
+     * Update the request configuration (e.g., when token changes)
+     */
+    updateConfig(config) {
+        this.config = config;
+    }
+    addSignal(signal) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ signal, resolve, reject });
+            // Reset timer
+            if (this.timer) {
+                clearTimer(this.timer);
+            }
+            this.timer = setTimer(() => {
+                this.flush();
+            }, this.batchTimeout);
+        });
+    }
+    async flush() {
+        if (this.queue.length === 0) {
+            return;
+        }
+        const batch = [...this.queue];
+        // Clear queue and reset state
+        this.queue = [];
+        this.timer = null;
+        try {
+            // Send batch request
+            const signals = batch.map((b) => b.signal);
+            const response = await (0, signal_js_1.recordSignal)(this.config, { signals });
+            // Resolve all promises with the same response
+            // The API returns a single response for the batch
+            for (const { resolve } of batch) {
+                resolve(response);
+            }
+        }
+        catch (error) {
+            // Reject all pending promises
+            const err = error instanceof Error ? error : new Error(String(error));
+            for (const { reject } of batch) {
+                reject(err);
+            }
+        }
+    }
+}
+exports.SignalBatchManager = SignalBatchManager;
+//# sourceMappingURL=signal-batch-manager.js.map

package/dist/user/signal-batch-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-batch-manager.js","sourceRoot":"","sources":["../../src/user/signal-batch-manager.ts"],"names":[],"mappings":";;;AACA,2CAAwD;AAExD,mDAAmD;AACnD,SAAS,aAAa;IACpB,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,eAAe;IACtB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAC;AACjC,MAAM,UAAU,GAAG,eAAe,EAAE,CAAC;AAMrC;;;GAGG;AACH,MAAa,kBAAkB;IACrB,KAAK,GAIR,EAAE,CAAC;IACA,KAAK,GAAiB,IAAI,CAAC;IAC3B,MAAM,CAAgB;IACtB,YAAY,CAAS;IAE7B,YAAY,MAAqB,EAAE,YAAoB;QACrD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,MAAqB;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,SAAS,CAAC,MAAc;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAE7C,cAAc;YACd,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;YAED,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE;gBACzB,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACxB,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAE9B,8BAA8B;QAC9B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAElB,IAAI,CAAC;YACH,qBAAqB;YACrB,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC3C,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAY,EAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;YAE9D,8CAA8C;YAC9C,kDAAkD;YAClD,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,KAAK,EAAE,CAAC;gBAChC,OAAO,CAAC,QAAQ,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,8BAA8B;YAC9B,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACtE,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;gBAC/B,MAAM,CAAC,GAAG,CAAC,CAAC;YACd,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAlED,gDAkEC"}

package/dist/user/signal.d.ts

@@ -2,11 +2,12 @@ import type { paths } from '../generated/openapi.js';
 import type { RequestConfig } from '../request.js';
 export type SignalRequest = paths['/v1/user/signal']['post']['requestBody']['content']['application/json'];
 export type SignalResponse = paths['/v1/user/signal']['post']['responses'][200]['content']['application/json']['data'];
+export type Signal = SignalRequest['signals'][number];
 /**
- * Record a user signal (e.g. clicked topic, read article) to inform profile interests
+ * Record user signals (e.g. clicked topic, read article) to inform profile interests
  *
  * @param config - Request configuration with base URL, timeout, fetch, and optional token
- * @param options - Signal request parameters (type: SignalRequest)
+ * @param options - Signal request parameters (type: SignalRequest) containing an array of signals
  * @returns Promise that resolves with the signal response data
  */
 export declare function recordSignal(config: RequestConfig, options: SignalRequest): Promise<NonNullable<SignalResponse>>;

package/dist/user/signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/user/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,MAAM,aAAa,GACvB,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AACjF,MAAM,MAAM,cAAc,GACxB,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5F;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CActC"}
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/user/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAInD,MAAM,MAAM,aAAa,GACvB,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AACjF,MAAM,MAAM,cAAc,GACxB,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAG5F,MAAM,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,WAAW,CAAC,cAAc,CAAC,CAAC,CActC"}

package/dist/user/signal.js

@@ -3,10 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordSignal = recordSignal;
 const request_js_1 = require("../request.js");
 /**
- * Record a user signal (e.g. clicked topic, read article) to inform profile interests
+ * Record user signals (e.g. clicked topic, read article) to inform profile interests
  *
  * @param config - Request configuration with base URL, timeout, fetch, and optional token
- * @param options - Signal request parameters (type: SignalRequest)
+ * @param options - Signal request parameters (type: SignalRequest) containing an array of signals
  * @returns Promise that resolves with the signal response data
  */
 async function recordSignal(config, options) {

package/dist/user/signal.js.map

@@ -1 +1 @@
-{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/user/signal.ts"],"names":[],"mappings":";;AAiBA,oCAiBC;AAhCD,8CAA4C;AAQ5C;;;;;;GAMG;AACI,KAAK,UAAU,YAAY,CAChC,MAAqB,EACrB,OAAsB;IAEtB,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAW,EAEhC,MAAM,EAAE;QACR,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,iBAAiB;QACvB,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"signal.js","sourceRoot":"","sources":["../../src/user/signal.ts"],"names":[],"mappings":";;AAoBA,oCAiBC;AAnCD,8CAA4C;AAW5C;;;;;;GAMG;AACI,KAAK,UAAU,YAAY,CAChC,MAAqB,EACrB,OAAsB;IAEtB,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAW,EAEhC,MAAM,EAAE;QACR,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,iBAAiB;QACvB,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;IAEH,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbitpress/client",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "BitBitPress TypeScript client library",
   "type": "module",
   "main": "./dist/index.js",