@blendification/results 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1
+
+- `TrackedConversation`, the type of what `conversations()` yields, now has the fields the server sends: `conversationId`, `respondentName` and `respondentEmail`. 0.1.0 declared `id`, `name` and `email`, which were always undefined. The type also gains `abandoned`, `templateId` and the conversation's dates. It drops the catch-all index signature, so a misspelt field no longer compiles.
+- `conversationPage()` returns a typed `ConversationPage`, and `status` accepts one status or a list.
+- The README named the same wrong fields; it now names the real ones.
+
 ## 0.1.0
 
 First release.

package/README.md

@@ -78,7 +78,7 @@ const results = createResultsClient({
 | Call | What it returns |
 | --- | --- |
 | `progress({ templateId?, inviteGroupName?, since? })` | Status counts, completion rate, and splits by invite group or template, read to the end and added up |
-| `conversations({ templateId?, inviteGroupName?, status?, since? })` | An async iterator over every conversation: id, status, name, email, invite group, link |
+| `conversations({ templateId?, inviteGroupName?, status?, since? })` | An async iterator over every conversation: `conversationId`, `status`, `abandoned`, `respondentName`, `respondentEmail`, `inviteGroup`, `link`, and its dates (`startedAt`, `completedAt`) |
 | `transcript(conversationId, { resultsGroupId })` | Every message, oldest first |
 | `summary(resultsGroupId)` | A results group's name, counts, topics and reports |
 | `exportGroup(resultsGroupId, { format: 'csv' })` | Starts an export, waits for it, and returns download links plus the first page |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blendification/results",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Read Blendification results (survey progress, conversations, transcripts, exports) from your own page or server, signed in with Blendification's OAuth, and verify the webhooks it sends.",
   "license": "MIT",
   "author": "Blendification",

package/types/index.d.ts

@@ -106,14 +106,44 @@ export interface ScopeArgs {
   since?: string;
 }
 
+export type ConversationStatus = 'not started' | 'started' | 'complete';
+
+/**
+ * One conversation, as conversations() yields it and conversationPage() lists
+ * it (the list_template_conversations tool). A drift test in
+ * services/analysis-engine pins these names to the rows the server builds.
+ */
 export interface TrackedConversation {
-  id: string;
-  status: string;
-  name?: string | null;
-  email?: string | null;
-  inviteGroup?: string | null;
-  link?: string | null;
-  [key: string]: unknown;
+  conversationId: string;
+  /** 'not started', 'started' or 'complete'. */
+  status: string | null;
+  /** Started, then left without completing. */
+  abandoned: boolean;
+  /** Null for an anonymous conversation. */
+  respondentName: string | null;
+  /** Lower-cased. Null for an anonymous conversation. */
+  respondentEmail: string | null;
+  inviteGroup: string | null;
+  templateId: string | null;
+  interviewDate: string | null;
+  createdAt: string | null;
+  startedAt: string | null;
+  completedAt: string | null;
+  /** The participant's link: the template's hosted page when it names one, else the app's page. */
+  link: string | null;
+}
+
+/** One page of list_template_conversations. */
+export interface ConversationPage {
+  templateId: string | null;
+  templateName: string | null;
+  inviteGroupName: string | null;
+  status: ConversationStatus[] | null;
+  since: string | null;
+  returned: number;
+  conversations: TrackedConversation[];
+  nextToken: string | null;
+  message: string;
 }
 
 export interface ResultsClient {
@@ -122,8 +152,8 @@ export interface ResultsClient {
   call<T = any>(tool: string, args?: Record<string, unknown>): Promise<T>;
   listTools(): Promise<Array<{ name: string; description: string; inputSchema: object }>>;
   progress(args: ScopeArgs): Promise<Progress>;
-  conversationPage(args: ScopeArgs & { status?: string[]; limit?: number; nextToken?: string }): Promise<any>;
-  conversations(args: ScopeArgs & { status?: string[]; limit?: number }): AsyncGenerator<TrackedConversation>;
+  conversationPage(args: ScopeArgs & { status?: ConversationStatus | ConversationStatus[]; limit?: number; nextToken?: string }): Promise<ConversationPage>;
+  conversations(args: ScopeArgs & { status?: ConversationStatus | ConversationStatus[]; limit?: number }): AsyncGenerator<TrackedConversation>;
   transcript(conversationId: string, opts: { resultsGroupId: string; limit?: number }): Promise<{ conversationId: string; messages: any[]; complete: boolean }>;
   waitForJob(jobId: string, opts?: { intervalMs?: number; timeoutMs?: number; onUpdate?: (status: any) => void }): Promise<any>;
   exportGroup(resultsGroupId: string, opts?: { format?: 'json' | 'csv'; conversationIds?: string[]; includeMessages?: boolean; includeFeatures?: boolean; waitMs?: number }): Promise<any>;