@bitbitpress/client 1.1.0-alpha.1 → 1.1.1

package/README.md

@@ -49,6 +49,9 @@ More details can also be found in your control room's API docs @ https://your-co
   - [report](#report)
   - [createSubmission](#createsubmission)
   - [submissions](#submissions)
+  - [submit](#submit)
+  - [submissionState](#submissionstate)
+  - [submissionFeed](#submissionfeed)
   - [signal](#signal)
   - [signalItem](#signalitem)
   - [synthesizeItem](#synthesizeitem)
@@ -428,6 +431,74 @@ console.log('Next cursor:', result.cursor);
 
 ---
 
+#### submit
+
+Submit content (a poll vote or a contest entry) tied to a synthesis output. One submission per user per piece — re-submitting overwrites the prior one. Get `synthesisOutputId` from the synthesize response (`result.synthesisOutputId`).
+
+```typescript
+client.user.submit(options: SubmitRequest): Promise<SubmitResponse>
+```
+
+##### Parameters
+
+- `options.synthesisOutputId` (required): The output the submission attaches to
+- `options.data` (required): Structured submission data (e.g. `{ response: 'yes' }` for a poll)
+- `options.synthesisOutputContentKey` (optional): Defaults to `''` (one piece per output)
+- `options.files` (optional): File descriptors for presigned uploads
+
+##### Example
+
+```typescript
+const { synthesisOutputId } = await client.user.synthesizeItem(pollItem);
+await client.user.submit({ synthesisOutputId, data: { response: 'yes' } });
+```
+
+---
+
+#### submissionState
+
+Read one submittable piece: the public aggregate and this user's own submission (`null` if none). For a poll: results plus whether the user has voted.
+
+```typescript
+client.user.submissionState(options: {
+  synthesisOutputId: string;
+  synthesisOutputContentKey?: string;
+}): Promise<SubmissionState>
+```
+
+##### Returns
+
+- `aggregate`: `{ total, submissionCounts?, byState? }` — `submissionCounts` is keyed by the config's `aggregateField` value (e.g. a poll option)
+- `ownSubmission`: this user's submission, or `null`
+
+##### Example
+
+```typescript
+const { aggregate, ownSubmission } = await client.user.submissionState({ synthesisOutputId });
+const hasVoted = ownSubmission != null;
+const counts = aggregate.submissionCounts; // { yes: 12, no: 3 }
+```
+
+---
+
+#### submissionFeed
+
+List the public feed of LIVE submissions for a synthesis output (e.g. all contest entries), paginated.
+
+```typescript
+client.user.submissionFeed(options: {
+  synthesisOutputId: string;
+  first?: number;
+  after?: string;
+}): Promise<SubmissionFeed>
+```
+
+##### Returns
+
+- `SubmissionFeed`: `{ cursor, items }` — each item is `{ id, data, files, createdAt }`
+
+---
+
 #### signal
 
 Record user signals (e.g., clicked topic, read article) to inform profile interests. Signals are used to power a user's recommendations.
@@ -554,12 +625,12 @@ client.user.synthesizeItem(
 
 ##### Parameters
 
-- `item` (required): A single synthesize item (same shape as items in `synthesize`): `inputs`, `output` (schema as JSON string or Zod 4 schema), optional `configurationKeyName`, optional `limit` (number of results to return; defaults to `1`), optional `searchOptionsOverrides` (e.g. `{ lookbackMinutes: 1440 }` for 24-hour lookback)
+- `item` (required): A single synthesize item (same shape as items in `synthesize`): `inputs`, `output` (schema as JSON string or Zod 4 schema), optional `configurationKeyName`, optional `synthesisHistoryLimit` (how many recent stored outputs to expose in `synthesisHistory`; defaults to `0` — no history emitted), optional `searchOptionsOverrides` (e.g. `{ lookbackMinutes: 1440 }` for 24-hour lookback)
 - `onStreamingData` (optional): Callback invoked with streaming data whenever a stream event has `complete: false` for this item. Type: `(data: unknown) => void`.
 
 ##### Returns
 
-- `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
+- `Promise<SynthesizeItemResponse>`: Resolves with the final data event for this item — `data` is the synthesized object (keys match your output schema) when present; `synthesisHistory` is an array of recent stored `data` payloads when `synthesisHistoryLimit > 0` (most-recent first; the first entry is the current synthesis itself); `error` is set on failure
 
 ##### Behavior
 
@@ -614,7 +685,7 @@ client.user.synthesize(
   - `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 }` — output schema as a JSON string or Zod 4 schema (top-level type must be `"object"`; supports object, string, number, boolean, array, and enum)
   - `configurationKeyName` (optional): Key name for configuration
-  - `limit` (optional): Number of results to return. Defaults to `1`.
+  - `synthesisHistoryLimit` (optional): How many recent stored synthesis outputs to expose in the final data event's `synthesisHistory` field. Defaults to `0` (no history emitted). When `> 0`, the final event includes a `synthesisHistory` array of up to N `data` payloads (most-recent first; first entry is the current synthesis itself).
   - `searchOptionsOverrides` (optional): Per-request overrides, e.g. `{ lookbackMinutes: 1440 }` for 24-hour lookback.
 - `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
 
@@ -626,7 +697,7 @@ client.user.synthesize(
 
 - `{ type: "connected" }`: Connection established
 - `{ type: "complete" }`: Stream complete
-- `{ index, data?, complete, error? }`: 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.
+- `{ index, data?, synthesisHistory?, complete, error? }`: 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). `synthesisHistory` (only on the final event, only when `synthesisHistoryLimit > 0`) is an array of recent stored `data` payloads, most-recent first. `error` is set on failure.
 
 ##### Example
 
@@ -995,13 +1066,13 @@ type SignalResponse = {
 
 #### SynthesizeRequest
 
-Request body for POST `/v1/user/synthesize` (from OpenAPI). Each item has `inputs`, `output`, optional `configurationKeyName`, optional `limit` (defaults to `1`), and optional `searchOptionsOverrides`.
+Request body for POST `/v1/user/synthesize` (from OpenAPI). Each item has `inputs`, `output`, optional `configurationKeyName`, optional `synthesisHistoryLimit` (defaults to `0`), and optional `searchOptionsOverrides`.
 
 ```typescript
 type SynthesizeRequest = {
   items: Array<{
     configurationKeyName?: string;
-    limit?: number; // number of results to return; defaults to 1
+    synthesisHistoryLimit?: number; // how many recent stored outputs to include in synthesisHistory; defaults to 0 (no history emitted)
     searchOptionsOverrides?: { lookbackMinutes?: number };
     inputs?: Array<{ type: 'externalId' | 'text' | 'excludeExternalIds'; value: string }>;
     output: {
@@ -1027,10 +1098,10 @@ Stream events (SSE). Connection events use `type`; data events use `index`, opti
 type SynthesizeEvent =
   | { type: 'connected' }
   | { type: 'complete' }
-  | { index: number; data?: unknown; complete: boolean; error?: string };
+  | { index: number; data?: unknown; synthesisHistory?: 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.
+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). When the request set `synthesisHistoryLimit > 0`, the final event also includes `synthesisHistory`: an array of recent stored `data` payloads (most-recent first; first entry is the current synthesis itself — identical to `data` unless user reranking is configured server-side). `error` is set on failure.
 
 #### SynthesizeItemResponse
 
@@ -1038,8 +1109,9 @@ Return type of `synthesizeItem`. Same shape as a data event payload (without `in
 
 ```typescript
 type SynthesizeItemResponse = {
-  data?: unknown;   // synthesized object when present
-  error?: string;   // set on failure
+  data?: unknown;              // synthesized object when present
+  synthesisHistory?: unknown[]; // recent stored outputs when synthesisHistoryLimit > 0; most-recent first
+  error?: string;               // set on failure
 };
 ```