@bitbitpress/client 0.1.0 → 0.1.1

package/README.md

@@ -33,6 +33,477 @@ 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
+### API Reference
 
-See API.md for more details or reference your control room API docs: https://your-control-room.api.dev.bitbitpress.com/docs
+- [BitBitPressClient](#bitbitpressclient)
+- [Authentication](#authentication)
+- [User Methods](#user-methods)
+  - [authenticate](#authenticate)
+  - [token](#token)
+  - [recommendations](#recommendations)
+  - [signal](#signal)
+  - [synthesizeItem](#synthesizeitem)
+  - [synthesize](#synthesize)
+- [Types](#types)
+
+## BitBitPressClient
+
+Main client class for interacting with the BitBitPress API.
+
+### Constructor
+
+```typescript
+new BitBitPressClient(options: BitBitPressClientOptions)
+```
+
+#### 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)
+- `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`)
+
+#### Example
+
+```typescript
+const client = new BitBitPressClient({
+  baseUrl: 'https://your-control-room.api.dev.bitbitpress.com',
+  timeout: 30000,
+  synthesizeBatchTimeout: 250,
+});
+```
+
+### Methods
+
+#### `setBaseUrl(baseUrl: string): void`
+
+Update the base URL for API requests.
+
+#### `get user`
+
+Returns an object with user-related API methods. See [User Methods](#user-methods) below.
+
+## Authentication
+
+All user methods require authentication. You must call `client.user.authenticate()` before using other user methods.
+
+## User Methods
+
+### authenticate
+
+Exchanges an SSO token for an authentication token and automatically sets it for all subsequent user method calls.
+
+```typescript
+await client.user.authenticate(ssoToken: string): Promise<void>
+```
+
+#### Parameters
+
+- `ssoToken` (required): The SSO token from your authentication provider
+
+#### Returns
+
+- `Promise<void>`: Resolves when authentication is complete
+
+#### Example
+
+```typescript
+await client.user.authenticate('your-user-s-auth-sso-token');
+// Token is now automatically set for all user methods
+```
+
+#### Throws
+
+- `Error`: If token exchange fails or no access token is returned
+
+---
+
+### token
+
+Exchanges an SSO token for an authentication token without automatically setting it for user methods.
+
+```typescript
+client.user.token(ssoToken: string): Promise<TokenResponse>
+```
+
+#### Parameters
+
+- `ssoToken` (required): The SSO token from your authentication provider
+
+#### Returns
+
+- `Promise<TokenResponse>`: The token response containing:
+  - `idToken?: string`
+  - `accessToken?: string`
+  - `refreshToken?: string`
+  - `expiresIn?: number`
+
+#### Example
+
+```typescript
+const tokenResponse = await client.user.token('your-sso-token');
+console.log('Access token:', tokenResponse.accessToken);
+```
+
+---
+
+### recommendations
+
+Get recommended articles for the authenticated user.
+
+```typescript
+client.user.recommendations(options?: RecommendationsRequest): Promise<RecommendationsResponse>
+```
+
+#### Parameters
+
+- `options.limit` (optional): Maximum number of recommendations to return
+- `options.cursor` (optional): Cursor from previous response to fetch the next page
+
+#### Returns
+
+- `Promise<RecommendationsResponse>`: Response containing:
+  - `items?: Array<RecommendationItem>`: List of recommended articles
+  - `cursor?: string`: Cursor to request the next page, if any
+
+#### 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
+
+```typescript
+const recommendations = await client.user.recommendations({
+  limit: 10,
+  cursor: 'optional-cursor-from-previous-response',
+});
+
+console.log('Recommendations:', recommendations.items);
+console.log('Next cursor:', recommendations.cursor);
+```
+
+#### Throws
+
+- `Error`: If the request fails or no data is returned
+
+---
+
+### signal
+
+Record a user signal (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>
+```
+
+#### 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.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)
+  - `contentType` (required): The type of content (currently only `"article"`)
+
+#### Returns
+
+- `Promise<SignalResponse>`: Response containing:
+  - `recorded?: boolean`: Whether the signal was recorded (false if no app user or empty signal)
+
+#### Example
+
+```typescript
+// Active signal (explicit intent)
+await client.user.signal({
+  signal: 'clicked "Warriors intend to keep Jimmy Butler despite season-ending injury"',
+  type: 'active',
+  contentContext: {
+    contentId: 'article-123',
+    contentType: 'article',
+  },
+});
+
+// Passive signal (implicit intent)
+await client.user.signal({
+  signal: 'read article about NBA trades',
+  type: 'passive',
+  contentContext: {
+    contentId: 'article-456',
+    contentType: 'article',
+  },
+});
+
+// Negative signal (use sparingly)
+await client.user.signal({
+  signal: 'unfollowed topic "Politics"',
+  type: 'active',
+  negative: true,
+});
+```
+
+#### Throws
+
+- `Error`: If the request fails or no data is returned
+
+---
+
+### 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).
+
+```typescript
+client.user.synthesizeItem(item: SynthesizeRequest['items'][number]): Promise<unknown>
+```
+
+#### Parameters
+
+- `item` (required): A single synthesize item (same format as items in `synthesize`)
+
+#### 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
+
+- 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`
+
+#### 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',
+});
+// 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' }],
+  contentContext: {
+    contentId: 'article-123',
+    contentType: 'article',
+  },
+});
+// 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.
+
+```typescript
+client.user.synthesize(items: SynthesizeRequest['items']): 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
+
+#### ContentContext (required for CUSTOM items)
+
+- `contentId` (optional): Your content ID
+- `contentType` (optional): The type of content to synthesize (currently only `"article"`)
+
+#### Returns
+
+- `Promise<AsyncIterable<SynthesizeEvent>>`: An async iterable stream 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
+
+#### Example
+
+```typescript
+const stream = await client.user.synthesize([
+  {
+    type: 'DAILY_SUMMARY',
+  },
+  {
+    type: 'CUSTOM',
+    schema: [
+      { fieldName: 'title', fieldDescription: 'The article title' },
+      { fieldName: 'summary', fieldDescription: 'A brief summary' },
+    ],
+    contentContext: {
+      contentId: 'article-123',
+      contentType: 'article',
+    },
+  },
+]);
+
+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;
+  }
+}
+```
+
+---
+
+## Types
+
+### BitBitPressClientConfig
+
+```typescript
+interface BitBitPressClientConfig {
+  baseUrl: string;
+  fetch?: typeof fetch;
+  headers?: Record<string, string>;
+  timeout?: number;
+  synthesizeBatchTimeout?: number;
+}
+```
+
+### TokenRequest
+
+```typescript
+type TokenRequest = {
+  ssoToken: string;
+}
+```
+
+### TokenResponse
+
+```typescript
+type TokenResponse = {
+  idToken?: string;
+  accessToken?: string;
+  refreshToken?: string;
+  expiresIn?: number;
+}
+```
+
+### RecommendationsRequest
+
+```typescript
+type RecommendationsRequest = {
+  limit?: number;
+  cursor?: string;
+}
+```
+
+### RecommendationsResponse
+
+```typescript
+type RecommendationsResponse = {
+  items?: Array<{
+    id?: string;
+    assetId?: string;
+    title?: string;
+    summary?: string;
+    content?: string;
+    publishedAt?: string;
+    score?: number;
+  }>;
+  cursor?: string;
+}
+```
+
+### SignalRequest
+
+```typescript
+type SignalRequest = {
+  signal: string;
+  type: 'active' | 'passive';
+  negative?: boolean;
+  contentContext?: {
+    contentId: string;
+    contentType: 'article';
+  };
+}
+```
+
+### SignalResponse
+
+```typescript
+type SignalResponse = {
+  recorded?: boolean;
+}
+```
+
+### SynthesizeRequest
+
+```typescript
+type SynthesizeRequest = {
+  items: Array<
+    | { type: 'DAILY_SUMMARY' }
+    | {
+        type: 'CUSTOM';
+        schema: Array<{
+          fieldName: string;
+          fieldDescription: string;
+        }>;
+        contentContext: {
+          contentId?: string;
+          contentType?: 'article';
+        };
+      }
+  >;
+}
+```
+
+### SynthesizeEvent
+
+```typescript
+type SynthesizeEvent = {
+  type: 'DAILY_SUMMARY' | 'CUSTOM' | 'connected' | 'complete';
+  index?: number;
+  data?: unknown;
+}
+```
+
+For `DAILY_SUMMARY` events, `data` will be:
+```typescript
+{
+  summary: string | null;
+}
+```
+
+For `CUSTOM` events, `data` will be an object following your schema input, where `fieldNames` are keys.

package/package.json

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