@bitbitpress/client 1.1.0 → 1.1.2

package/README.md

@@ -49,12 +49,15 @@ 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)
   - [synthesize](#synthesize)
-  - [interactions](#interactions)
-  - [respondToInteraction](#respondtointeraction)
+  - [interactions (deprecated)](#interactions)
+  - [respondToInteraction (deprecated)](#respondtointeraction)
 - [Data Methods](#data-methods)
   - [assets](#assets)
 - [Types](#types)
@@ -428,6 +431,75 @@ 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);
+if (!synthesisOutputId) throw new Error('Poll output is missing synthesisOutputId');
+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 +626,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 `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)
+- `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 `synthesisHistoryEntries`; 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; `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
+- `Promise<SynthesizeItemResponse>`: Resolves with the final data event for this item — `data` is the synthesized object (keys match your output schema) when present; `synthesisOutputId` identifies the current output for submissions; `synthesisHistoryEntries` is an array of recent stored `{ synthesisOutputId, data }` entries when `synthesisHistoryLimit > 0` (most-recent first; the first entry is the current synthesis itself); deprecated `synthesisHistory` may also be present as bare payloads; `error` is set on failure
 
 ##### Behavior
 
@@ -614,7 +686,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
-  - `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).
+  - `synthesisHistoryLimit` (optional): How many recent stored synthesis outputs to expose in the final data event's `synthesisHistoryEntries` field. Defaults to `0` (no history emitted). When `> 0`, the final event includes a `synthesisHistoryEntries` array of up to N `{ synthesisOutputId, data }` entries (most-recent first; first entry is the current synthesis itself). A deprecated `synthesisHistory` array of bare payloads may also be present for retrocompatibility.
   - `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 +698,7 @@ client.user.synthesize(
 
 - `{ type: "connected" }`: Connection established
 - `{ type: "complete" }`: Stream complete
-- `{ 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.
+- `{ index, data?, synthesisOutputId?, synthesisHistoryEntries?, 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). `synthesisHistoryEntries` (only on the final event, only when `synthesisHistoryLimit > 0`) is an array of recent stored `{ synthesisOutputId, data }` entries, most-recent first. `synthesisHistory` is deprecated and contains the same entries as bare payloads. `error` is set on failure.
 
 ##### Example
 
@@ -682,6 +754,8 @@ for await (const event of stream) {
 
 #### interactions
 
+**Deprecated:** use `client.user.submissionState({ synthesisOutputId })`, keyed by the poll's synthesis output. This legacy method is kept for retrocompatibility.
+
 Batch-resolve interaction state for items from a synthesis output. Returns aggregates and whether the current user has already responded to each.
 
 ```typescript
@@ -732,6 +806,8 @@ for (const item of interactions) {
 
 #### respondToInteraction
 
+**Deprecated:** use `client.user.submit({ synthesisOutputId, data })`, keyed by the poll's synthesis output. This legacy method is kept for retrocompatibility.
+
 Submit or update a response to an interaction (e.g. a poll answer). Returns updated aggregates.
 
 ```typescript
@@ -778,7 +854,7 @@ Data methods require authentication. Call `client.user.authenticate()` before us
 
 #### assets
 
-Fetch assets by IDs and return requested fields.
+Fetch assets by internal IDs or external IDs, and return requested fields.
 
 ```typescript
 client.data.assets(options: AssetsRequest): Promise<AssetsResponse>
@@ -786,7 +862,8 @@ client.data.assets(options: AssetsRequest): Promise<AssetsResponse>
 
 ##### Parameters
 
-- `options.assetIds` (required): List of asset IDs to fetch
+- `options.assetIds` (required unless `externalIds` is provided): List of BitBitPress asset IDs to fetch
+- `options.externalIds` (required unless `assetIds` is provided): List of source-system external IDs to fetch
 - `options.assetFields` (required): Asset fields to return (dot or bracket notation, e.g. `tags[0]`, `images[1].src`). Allowed: `assetId`, `title`, `tags`, `images`, `videos`, `audios`, `publishedAt`, `externalId`, `externalData`, `assetType`, `sourceUrl`, `dataSource.name`, and subfields. Empty array returns objects with only `assetId`.
 
 ##### Returns
@@ -1001,7 +1078,7 @@ Request body for POST `/v1/user/synthesize` (from OpenAPI). Each item has `input
 type SynthesizeRequest = {
   items: Array<{
     configurationKeyName?: string;
-    synthesisHistoryLimit?: number; // how many recent stored outputs to include in synthesisHistory; defaults to 0 (no history emitted)
+    synthesisHistoryLimit?: number; // how many recent stored outputs to include in synthesisHistoryEntries; defaults to 0 (no history emitted)
     searchOptionsOverrides?: { lookbackMinutes?: number };
     inputs?: Array<{ type: 'externalId' | 'text' | 'excludeExternalIds'; value: string }>;
     output: {
@@ -1021,16 +1098,24 @@ Same shape as the request items above, but `output.schema` may be a **string or
 
 #### SynthesizeEvent
 
-Stream events (SSE). Connection events use `type`; data events use `index`, optional `data`, required `complete`, and optional `error`. Multiple data events may be sent per index as partial object updates; the final event for an index has `complete: true` and the validated object.
+Stream events (SSE). Connection events use `type`; data events use `index`, optional `data`, optional `synthesisOutputId`, optional history fields, required `complete`, and optional `error`. Multiple data events may be sent per index as partial object updates; the final event for an index has `complete: true` and the validated object.
 
 ```typescript
 type SynthesizeEvent =
   | { type: 'connected' }
   | { type: 'complete' }
-  | { index: number; data?: unknown; synthesisHistory?: unknown[]; complete: boolean; error?: string };
+  | {
+      index: number;
+      data?: unknown;
+      synthesisOutputId?: string;
+      synthesisHistoryEntries?: Array<{ synthesisOutputId: string; data: unknown }>;
+      synthesisHistory?: unknown[]; // deprecated bare-payload history
+      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). 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.
+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). `synthesisOutputId` identifies the current output and can be passed to `submit`, `submissionState`, or `submissionFeed`. When the request set `synthesisHistoryLimit > 0`, the final event also includes `synthesisHistoryEntries`: an array of recent stored `{ synthesisOutputId, data }` entries (most-recent first; first entry is the current synthesis itself). Deprecated `synthesisHistory` may also be present as index-aligned bare payloads. `error` is set on failure.
 
 #### SynthesizeItemResponse
 
@@ -1038,9 +1123,11 @@ Return type of `synthesizeItem`. Same shape as a data event payload (without `in
 
 ```typescript
 type SynthesizeItemResponse = {
-  data?: unknown;              // synthesized object when present
-  synthesisHistory?: unknown[]; // recent stored outputs when synthesisHistoryLimit > 0; most-recent first
-  error?: string;               // set on failure
+  data?: unknown; // synthesized object when present
+  synthesisOutputId?: string; // current output id for submissions
+  synthesisHistoryEntries?: Array<{ synthesisOutputId: string; data: unknown }>; // preferred history with output ids
+  synthesisHistory?: unknown[]; // deprecated bare-payload history
+  error?: string; // set on failure
 };
 ```
 
@@ -1050,9 +1137,13 @@ Request body for POST `/v1/data/assets`.
 
 ```typescript
 type AssetsRequest = {
-  assetIds: string[];
+  assetIds?: string[];
+  externalIds?: string[];
   assetFields: string[];
-}
+} & (
+  | { assetIds: string[]; externalIds?: string[] }
+  | { assetIds?: string[]; externalIds: string[] }
+);
 ```
 
 #### AssetsResponse
@@ -1085,7 +1176,7 @@ interface SynthesizeOptions {
 
 #### InteractionsRequest
 
-Request body for POST `/v1/user/interactions`.
+Deprecated request body for POST `/v1/user/interactions`. Prefer `submissionState({ synthesisOutputId })`.
 
 ```typescript
 type InteractionsRequest = {
@@ -1121,7 +1212,7 @@ type InteractionsResponse = InteractionItem[];
 
 #### InteractionResponseRequest
 
-Request body for POST `/v1/user/interactions/:interactionId/responses`.
+Deprecated request body for POST `/v1/user/interactions/:interactionId/responses`. Prefer `submit({ synthesisOutputId, data })`.
 
 ```typescript
 type InteractionResponseRequest = {

package/dist/data/assets.d.ts

@@ -1,13 +1,21 @@
 import type { paths } from '../generated/openapi.js';
 import type { RequestConfig } from '../request.js';
-export type AssetsRequest = paths['/v1/data/assets']['post']['requestBody']['content']['application/json'];
+type OpenApiAssetsRequest = paths['/v1/data/assets']['post']['requestBody']['content']['application/json'];
+export type AssetsRequest = OpenApiAssetsRequest & ({
+    assetIds: string[];
+    externalIds?: string[];
+} | {
+    assetIds?: string[];
+    externalIds: string[];
+});
 export type AssetsResponse = paths['/v1/data/assets']['post']['responses'][200]['content']['application/json']['data'];
 /**
- * Fetch assets by IDs and return requested fields.
+ * Fetch assets by internal and/or external IDs and return requested fields.
  *
  * @param config - Request configuration with base URL, timeout, fetch, and token
- * @param options - assetIds (required) and assetFields (required)
+ * @param options - assetFields and at least one of assetIds or externalIds
  * @returns Promise that resolves with assets array
  */
 export declare function assets(config: RequestConfig, options: AssetsRequest): Promise<AssetsResponse>;
+export {};
 //# sourceMappingURL=assets.d.ts.map

package/dist/data/assets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/data/assets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,MAAM,MAAM,aAAa,GACvB,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAEjF,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,MAAM,CAC1B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,cAAc,CAAC,CAYzB"}
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../src/data/assets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGnD,KAAK,oBAAoB,GACvB,KAAK,CAAC,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAEjF,MAAM,MAAM,aAAa,GAAG,oBAAoB,GAC9C,CAAC;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAAC;AAEpG,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,MAAM,CAC1B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,cAAc,CAAC,CAYzB"}

package/dist/data/assets.js

@@ -3,10 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.assets = assets;
 const request_js_1 = require("../request.js");
 /**
- * Fetch assets by IDs and return requested fields.
+ * Fetch assets by internal and/or external IDs and return requested fields.
  *
  * @param config - Request configuration with base URL, timeout, fetch, and token
- * @param options - assetIds (required) and assetFields (required)
+ * @param options - assetFields and at least one of assetIds or externalIds
  * @returns Promise that resolves with assets array
  */
 async function assets(config, options) {

package/dist/data/assets.js.map

@@ -1 +1 @@
-{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../src/data/assets.ts"],"names":[],"mappings":";;AAiBA,wBAeC;AA9BD,8CAA4C;AAQ5C;;;;;;GAMG;AACI,KAAK,UAAU,MAAM,CAC1B,MAAqB,EACrB,OAAsB;IAEtB,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAW,EAAiB,MAAM,EAAE;QACzD,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,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../src/data/assets.ts"],"names":[],"mappings":";;AAoBA,wBAeC;AAjCD,8CAA4C;AAW5C;;;;;;GAMG;AACI,KAAK,UAAU,MAAM,CAC1B,MAAqB,EACrB,OAAsB;IAEtB,MAAM,QAAQ,GAAG,MAAM,IAAA,wBAAW,EAAiB,MAAM,EAAE;QACzD,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,6CAA6C,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/data/index.d.ts

@@ -5,9 +5,9 @@ import { type AssetsRequest, type AssetsResponse } from './assets.js';
  */
 export interface DataMethods {
     /**
-     * Fetch assets by IDs and return requested fields.
+     * Fetch assets by internal and/or external IDs and return requested fields.
      *
-     * @param options - assetIds (required) and assetFields (required)
+     * @param options - assetFields and at least one of assetIds or externalIds
      * @returns Promise that resolves with assets array
      */
     assets(options: AssetsRequest): Promise<AssetsResponse>;