@bitbitpress/client 0.1.1 → 0.1.3

package/README.md

@@ -33,7 +33,10 @@ await client.user.authenticate('your-user\'s-auth-sso-token');
 
 **Note:** You must call `authenticate()` before using any other user methods (recommendations, synthesize, etc.).
 
-### API Reference
+
+## API Reference
+
+More details can also be found in your control room's API docs @ https://your-control-room.api.dev.bitbitpress.com/docs.
 
 - [BitBitPressClient](#bitbitpressclient)
 - [Authentication](#authentication)
@@ -46,17 +49,17 @@ await client.user.authenticate('your-user\'s-auth-sso-token');
   - [synthesize](#synthesize)
 - [Types](#types)
 
-## BitBitPressClient
+### BitBitPressClient
 
 Main client class for interacting with the BitBitPress API.
 
-### Constructor
+#### Constructor
 
 ```typescript
 new BitBitPressClient(options: BitBitPressClientOptions)
 ```
 
-#### Parameters
+##### Parameters
 
 - `options.baseUrl` (required): Base URL of the API server (your custom Control Room API Url)
 - `options.fetch` (optional): Custom fetch implementation (useful for React Native or Node.js polyfills)
@@ -64,7 +67,7 @@ new BitBitPressClient(options: BitBitPressClientOptions)
 - `options.timeout` (optional): Request timeout in milliseconds (default: `30000`)
 - `options.synthesizeBatchTimeout` (optional): Batch timeout for `synthesizeItem` in milliseconds (default: `250`)
 
-#### Example
+##### Example
 
 ```typescript
 const client = new BitBitPressClient({
@@ -74,23 +77,23 @@ const client = new BitBitPressClient({
 });
 ```
 
-### Methods
+##### Methods
 
-#### `setBaseUrl(baseUrl: string): void`
+##### `setBaseUrl(baseUrl: string): void`
 
 Update the base URL for API requests.
 
-#### `get user`
+##### `get user`
 
 Returns an object with user-related API methods. See [User Methods](#user-methods) below.
 
-## Authentication
+### Authentication
 
 All user methods require authentication. You must call `client.user.authenticate()` before using other user methods.
 
-## User Methods
+### User Methods
 
-### authenticate
+#### authenticate
 
 Exchanges an SSO token for an authentication token and automatically sets it for all subsequent user method calls.
 
@@ -98,28 +101,28 @@ Exchanges an SSO token for an authentication token and automatically sets it for
 await client.user.authenticate(ssoToken: string): Promise<void>
 ```
 
-#### Parameters
+##### Parameters
 
 - `ssoToken` (required): The SSO token from your authentication provider
 
-#### Returns
+##### Returns
 
 - `Promise<void>`: Resolves when authentication is complete
 
-#### Example
+##### Example
 
 ```typescript
 await client.user.authenticate('your-user-s-auth-sso-token');
 // Token is now automatically set for all user methods
 ```
 
-#### Throws
+##### Throws
 
 - `Error`: If token exchange fails or no access token is returned
 
 ---
 
-### token
+#### token
 
 Exchanges an SSO token for an authentication token without automatically setting it for user methods.
 
@@ -127,11 +130,11 @@ Exchanges an SSO token for an authentication token without automatically setting
 client.user.token(ssoToken: string): Promise<TokenResponse>
 ```
 
-#### Parameters
+##### Parameters
 
 - `ssoToken` (required): The SSO token from your authentication provider
 
-#### Returns
+##### Returns
 
 - `Promise<TokenResponse>`: The token response containing:
   - `idToken?: string`
@@ -139,7 +142,7 @@ client.user.token(ssoToken: string): Promise<TokenResponse>
   - `refreshToken?: string`
   - `expiresIn?: number`
 
-#### Example
+##### Example
 
 ```typescript
 const tokenResponse = await client.user.token('your-sso-token');
@@ -148,7 +151,7 @@ console.log('Access token:', tokenResponse.accessToken);
 
 ---
 
-### recommendations
+#### recommendations
 
 Get recommended articles for the authenticated user.
 
@@ -156,28 +159,27 @@ Get recommended articles for the authenticated user.
 client.user.recommendations(options?: RecommendationsRequest): Promise<RecommendationsResponse>
 ```
 
-#### Parameters
+##### Parameters
 
 - `options.limit` (optional): Maximum number of recommendations to return
 - `options.cursor` (optional): Cursor from previous response to fetch the next page
 
-#### Returns
+##### Returns
 
 - `Promise<RecommendationsResponse>`: Response containing:
   - `items?: Array<RecommendationItem>`: List of recommended articles
   - `cursor?: string`: Cursor to request the next page, if any
 
-#### RecommendationItem
+##### RecommendationItem
 
 - `id?: string`: Your article ID
 - `assetId?: string`: BitBitPress's ID
 - `title?: string`: Article title
-- `summary?: string`: Generated summary
 - `content?: string`: Article content
 - `publishedAt?: string`: Publication date (e.g., "2021-01-01")
 - `score?: number`: Recommendation score (e.g., 0.95)
 
-#### Example
+##### Example
 
 ```typescript
 const recommendations = await client.user.recommendations({
@@ -189,13 +191,13 @@ console.log('Recommendations:', recommendations.items);
 console.log('Next cursor:', recommendations.cursor);
 ```
 
-#### Throws
+##### Throws
 
 - `Error`: If the request fails or no data is returned
 
 ---
 
-### signal
+#### signal
 
 Record a user signal (e.g., clicked topic, read article) to inform profile interests. Signals are used to power a user's recommendations.
 
@@ -203,28 +205,28 @@ Record a user signal (e.g., clicked topic, read article) to inform profile inter
 client.user.signal(options: SignalRequest): Promise<SignalResponse>
 ```
 
-#### Parameters
+##### Parameters
 
-- `options.signal` (required): User action with the text associated with the interaction (e.g., `'clicked "Warriors intend to keep Jimmy Butler despite season-ending injury"'`)
+- `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., article ID)
+  - `contentId` (required): The ID of the content (e.g., your article ID)
   - `contentType` (required): The type of content (currently only `"article"`)
 
-#### Returns
+##### Returns
 
 - `Promise<SignalResponse>`: Response containing:
-  - `recorded?: boolean`: Whether the signal was recorded (false if no app user or empty signal)
+  - `recorded?: boolean`: Whether the signal was recorded (false if no user or empty signal)
 
-#### Example
+##### Example
 
 ```typescript
 // Active signal (explicit intent)
 await client.user.signal({
-  signal: 'clicked "Warriors intend to keep Jimmy Butler despite season-ending injury"',
+  signal: 'searched "best restaurants"',
   type: 'active',
   contentContext: {
     contentId: 'article-123',
@@ -250,13 +252,13 @@ await client.user.signal({
 });
 ```
 
-#### Throws
+##### Throws
 
 - `Error`: If the request fails or no data is returned
 
 ---
 
-### synthesizeItem
+#### 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).
 
@@ -264,17 +266,17 @@ Synthesize a single item (batched). Items are automatically batched and sent tog
 client.user.synthesizeItem(item: SynthesizeRequest['items'][number]): Promise<unknown>
 ```
 
-#### Parameters
+##### Parameters
 
 - `item` (required): A single synthesize item (same format as items in `synthesize`)
 
-#### Returns
+##### 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
 
-#### Behavior
+##### 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)
@@ -282,7 +284,7 @@ client.user.synthesizeItem(item: SynthesizeRequest['items'][number]): Promise<un
 - 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`
 
-#### Example
+##### Example
 
 ```typescript
 // Items are automatically batched and sent together after the timeout
@@ -310,7 +312,7 @@ console.log('Custom data:', customData);
 
 ---
 
-### synthesize
+#### synthesize
 
 Synthesize user content (streaming). Returns a stream of events for all items.
 
@@ -318,27 +320,27 @@ Synthesize user content (streaming). Returns a stream of events for all items.
 client.user.synthesize(items: SynthesizeRequest['items']): Promise<AsyncIterable<SynthesizeEvent>>
 ```
 
-#### Parameters
+##### 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
+##### SchemaField
 
 - `fieldName` (required): Name of the field
 - `fieldDescription` (required): A prompt describing the value of the field
 
-#### ContentContext (required for CUSTOM items)
+##### ContentContext (required for CUSTOM items)
 
 - `contentId` (optional): Your content ID
 - `contentType` (optional): The type of content to synthesize (currently only `"article"`)
 
-#### Returns
+##### Returns
 
 - `Promise<AsyncIterable<SynthesizeEvent>>`: An async iterable stream of events
 
-#### SynthesizeEvent
+##### SynthesizeEvent
 
 Events in the stream can be:
 
@@ -347,7 +349,7 @@ Events in the stream can be:
 - `{ type: "CUSTOM", index: number, data: {...} }`: Custom data following your schema
 - `{ type: "complete" }`: Stream complete
 
-#### Example
+##### Example
 
 ```typescript
 const stream = await client.user.synthesize([
@@ -387,9 +389,9 @@ for await (const event of stream) {
 
 ---
 
-## Types
+### Types
 
-### BitBitPressClientConfig
+#### BitBitPressClientConfig
 
 ```typescript
 interface BitBitPressClientConfig {
@@ -401,7 +403,7 @@ interface BitBitPressClientConfig {
 }
 ```
 
-### TokenRequest
+#### TokenRequest
 
 ```typescript
 type TokenRequest = {
@@ -409,7 +411,7 @@ type TokenRequest = {
 }
 ```
 
-### TokenResponse
+#### TokenResponse
 
 ```typescript
 type TokenResponse = {
@@ -420,7 +422,7 @@ type TokenResponse = {
 }
 ```
 
-### RecommendationsRequest
+#### RecommendationsRequest
 
 ```typescript
 type RecommendationsRequest = {
@@ -429,7 +431,7 @@ type RecommendationsRequest = {
 }
 ```
 
-### RecommendationsResponse
+#### RecommendationsResponse
 
 ```typescript
 type RecommendationsResponse = {
@@ -446,7 +448,7 @@ type RecommendationsResponse = {
 }
 ```
 
-### SignalRequest
+#### SignalRequest
 
 ```typescript
 type SignalRequest = {
@@ -460,7 +462,7 @@ type SignalRequest = {
 }
 ```
 
-### SignalResponse
+#### SignalResponse
 
 ```typescript
 type SignalResponse = {
@@ -468,7 +470,7 @@ type SignalResponse = {
 }
 ```
 
-### SynthesizeRequest
+#### SynthesizeRequest
 
 ```typescript
 type SynthesizeRequest = {
@@ -489,7 +491,7 @@ type SynthesizeRequest = {
 }
 ```
 
-### SynthesizeEvent
+#### SynthesizeEvent
 
 ```typescript
 type SynthesizeEvent = {

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { type UserMethods } from './user/index.js';
 /**
  * Configuration for the BitBitPress client
  */
@@ -39,6 +40,7 @@ export interface BitBitPressClientOptions extends BitBitPressClientConfig {
  */
 export declare class BitBitPressClient {
     private config;
+    private userMethodsInstance?;
     constructor(options: BitBitPressClientOptions);
     /**
      * Update the base URL
@@ -54,32 +56,8 @@ export declare class BitBitPressClient {
     private getSynthesizeBatchTimeout;
     /**
      * User-related API methods
+     * Provides type-safe access to user endpoints like signal, recommendations, synthesize, etc.
      */
-    get user(): {
-        authenticate(ssoToken: string): Promise<void>;
-        token: (ssoToken: import("./user/token.js").TokenRequest["ssoToken"]) => Promise<{
-            idToken?: string;
-            accessToken?: string;
-            refreshToken?: string;
-            expiresIn?: number;
-        }>;
-        recommendations: (options?: import("./user/recommendations.js").RecommendationsRequest) => Promise<{
-            items?: {
-                id?: string;
-                assetId?: string;
-                title?: string;
-                summary?: string;
-                content?: string;
-                publishedAt?: string;
-                score?: number;
-            }[];
-            cursor?: string;
-        }>;
-        signal: (options: import("./user/signal.js").SignalRequest) => Promise<{
-            recorded?: boolean;
-        }>;
-        synthesize: (items: import("./user/typeDefs.js").SynthesizeRequest["items"]) => Promise<AsyncIterable<import("./user/synthesize.js").SynthesizeEvent>>;
-        synthesizeItem: (item: import("./user/typeDefs.js").SynthesizeRequest["items"][number]) => Promise<unknown>;
-    };
+    get user(): UserMethods;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA;;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;gBAEpE,OAAO,EAAE,wBAAwB;IAqB7C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIjC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAIjC;;OAEG;IACH,IAAI,IAAI;;;;;;;;;;kBAIq4G,CAAC;uBAA0H,CAAC;qBAA6G,CAAC;uBAA2H,CAAC;uBAAiH,CAAC;2BAAwH,CAAC;qBAA4G,CAAC;;;;;;;;+BANnkI,uDAET;MAEE;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;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"}

package/dist/client.js

@@ -10,6 +10,7 @@ const index_js_1 = require("./user/index.js");
  */
 class BitBitPressClient {
     config;
+    userMethodsInstance;
     constructor(options) {
         if (!options.baseUrl) {
             throw new Error('baseUrl is required. Please provide your custom Control Room API Url.');
@@ -31,6 +32,8 @@ class BitBitPressClient {
      */
     setBaseUrl(baseUrl) {
         this.config.baseUrl = baseUrl;
+        // Invalidate cached user methods instance so it gets recreated with new baseUrl
+        this.userMethodsInstance = undefined;
     }
     /**
      * Get request configuration for making API calls
@@ -51,9 +54,13 @@ class BitBitPressClient {
     }
     /**
      * User-related API methods
+     * Provides type-safe access to user endpoints like signal, recommendations, synthesize, etc.
      */
     get user() {
-        return (0, index_js_1.createUserMethods)(this.getRequestConfig(), this.getSynthesizeBatchTimeout());
+        if (!this.userMethodsInstance) {
+            this.userMethodsInstance = (0, index_js_1.createUserMethods)(this.getRequestConfig(), this.getSynthesizeBatchTimeout());
+        }
+        return this.userMethodsInstance;
     }
 }
 exports.BitBitPressClient = BitBitPressClient;

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AACA,8CAAoD;AAwCpD;;;;;GAKG;AACH,MAAa,iBAAiB;IACpB,MAAM,CACkE;IAEhF,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;IAChC,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;IACH,IAAI,IAAI;QACN,OAAO,IAAA,4BAAiB,EAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,IAAI,CAAC,yBAAyB,EAAE,CAAC,CAAC;IACtF,CAAC;CACF;AAzDD,8CAyDC"}
+{"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"}