@vinaverse/server 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/{vinaverse-v1.d-DGSY4GsY.d.cts → vinaverse-v1.d-DT7a1T80.d.cts}

@@ -73,6 +73,30 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/conversations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * A person's past conversations with one agent, newest activity first
+         * @description v1-draft.21 (VIN-246): the conversations a history screen lists, for one subject and one agent, on one side of the app (`experience_mode`, and for a business `business_scope_id`, as the conversation was bound when it started). Newest activity first; ties by `id`.
+         *     **Access.** A service key only, never a client secret: the app asks the tenant's backend, which checks the person and calls this. The key needs `conversations:read` (a key without scopes has every scope) and sees its own tenant and environment only.
+         *     **What is listed.** Only what the tenant's `transcript_retention` still keeps: a conversation past it, a deleted one (`deleteConversation`) or an erased subject's is never listed, nor one where nothing was said (a session opened and left). A subject Vinaverse holds nothing for gets an empty page, the same as one with no conversations, so the answer never says whether a subject exists.
+         *     **The title** is deterministic and never the person's words: from the conversation's last search intent (`title_source: intent`, for example "Haircut · Los Angeles", in the subject's locale), else the date it started (`title_source: date`). There is no preview of the messages.
+         *     **Paging.** `next_cursor` is opaque and signed. It is bound to the filters, the key's tenant and environment, and expires after 24 hours: a cursor changed, used with other filters or expired is `400 invalid_request` at `/cursor`, and the caller starts again without it. An outage is `503 unavailable` (retryable), never an empty page: the app does not take it as "no conversations".
+         */
+        get: operations["listConversations"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/conversations/{conversation_id}": {
         parameters: {
             query?: never;
@@ -95,6 +119,42 @@ interface paths {
         get: operations["getConversation"];
         put?: never;
         post?: never;
+        /**
+         * Delete one of a person's conversations, everywhere
+         * @description v1-draft.21 (VIN-246): the person deletes a conversation from their history, through the tenant's backend. A service key with `conversations:write`, for its own tenant and environment; `subject_id` must be the conversation's subject.
+         *     **What it does, before it answers.** - Ends the conversation's open sessions: their sockets get `session.closed` with `reason: deleted` and
+         *       close with `4403` (a client that does not know `deleted` reads it as `revoked`). Their status ends as
+         *       `deleted`.
+         *     - Blanks every copy of the conversation's messages, cards, screening texts and state (and the guided flow's
+         *       answers), across both sides of the app, and leaves no title or count behind.
+         *     - Fences late writes: a turn still running, a webhook retry or a worker job that finishes after the delete
+         *       records nothing for it (a deletion barrier, kept as long as the longest session could run).
+         *     - Frees its `conversation_key`: a session with the same key afterwards starts a new conversation.
+         *     **Answers.** `200` with the number of sessions revoked. An unknown id, another tenant's, environment's or subject's, or one already deleted or erased: `404 not_found`, the same answer for each, so it never says whether the conversation exists. Deleting is not erasing the subject (`eraseSubject`): the person's other conversations and memory stay.
+         */
+        delete: operations["deleteConversation"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/conversations/{conversation_id}/messages": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * One past conversation, as one ordered timeline of messages and cards
+         * @description v1-draft.21 (VIN-246): what a history screen draws when the person opens a past conversation. A service key with `conversations:read`, for its own tenant and environment; `subject_id` must be the conversation's subject.
+         *     **The timeline.** One list of messages and the cards their turns drew, in the order they happened, each with an `id` that is stable and unique within the conversation. The first page is the newest; within a page, oldest first; `next_cursor` pages toward older items. A message carries `event_id`, the identifier its live event gave it (as `TranscriptItem.id`: an `assistant` message's `turn_id`, a `person` message's `client_event_id`, a `staff` message's `message_id`), so an app merges what it drew live, or a resumed `session.ready.transcript`, into the fetched history by `role` and `event_id` instead of replacing either. An input the runtime never recorded is not in it, as in the transcript.
+         *     **Cards from history are read-only.** An app draws their actions disabled: a past slot, price or availability is not checked again, so a tap would act on stale data. The person asks again in the conversation, and a fresh turn draws fresh cards.
+         *     **What is kept.** Only what the tenant's `transcript_retention` still keeps; a conversation past it is `410 conversation_expired`. An unknown id, another tenant's, environment's or subject's, or a deleted or erased one: `404 not_found`, the same answer for each. A cursor changed, used for another conversation or expired (24 hours) is `400 invalid_request` at `/cursor`. An outage is `503 unavailable`, never an empty timeline.
+         */
+        get: operations["listConversationMessages"];
+        put?: never;
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
@@ -144,7 +204,7 @@ interface paths {
         put?: never;
         /**
          * A fresh client secret for an open session
-         * @description A service key with the `sessions:write` scope gets a new connect secret for an open session, for an app that missed the connect window or connects from another device (whose connection then replaces the open one, with close code 4409). The previous secret no longer authenticates a new connection or an SSE turn. A socket already open stays open and keeps its session: refreshing never drops the person's live connection. To cut it off, revoke the session (`revokeSession`). An ended session is `409 session_closed`.
+         * @description A service key with the `sessions:write` scope gets a new connect secret for an open session, for an app that missed the connect window or connects from another device (whose connection then replaces the open one, with close code 4409). The previous secret no longer authenticates a new connection or an SSE turn. A socket already open stays open and keeps its session: refreshing never drops the person's live connection. To cut it off, revoke the session (`revokeSession`). An ended session is `409 session_closed`. With an optional `Idempotency-Key` (declared in v1-draft.22), a retry within 24 hours answers the secret first issued for that key instead of a newer one.
          */
         post: operations["refreshClientSecret"];
         delete?: never;
@@ -1484,10 +1544,10 @@ interface components {
             turns: number;
             handoff_ticket_ids?: string[];
             /**
-             * @description Why the session ended. `server_restart` is reserved and never appears here: it never ends a session (`docs/realtime-protocol.md` §2).
+             * @description Why the session ended. `server_restart` is reserved and never appears here: it never ends a session (`docs/realtime-protocol.md` §2). `deleted` (v1-draft.21): its conversation was deleted from history.
              * @enum {string}
              */
-            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left";
+            end_reason?: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "user_left" | "deleted";
             /** Format: date-time */
             created_at: string;
             /** Format: date-time */
@@ -1960,6 +2020,83 @@ interface components {
             /** Format: date-time */
             at: string;
         };
+        ConversationPage: {
+            data: components["schemas"]["ConversationSummary"][];
+            next_cursor: string | null;
+        };
+        /** @description v1-draft.21: one past conversation as a history screen lists it. No message text: the title is from the conversation's last search intent or its date, never the person's words. */
+        ConversationSummary: {
+            id: components["schemas"]["ConversationId"];
+            agent: string;
+            experience_mode: components["schemas"]["ExperienceMode"];
+            business_scope_id?: components["schemas"]["BusinessScopeId"];
+            title: string;
+            /**
+             * @description `intent`: the last search intent (service and place); `date`: the day it started
+             * @enum {string}
+             */
+            title_source: "intent" | "date";
+            /** Format: date-time */
+            started_at: string;
+            /** Format: date-time */
+            last_activity_at: string;
+            /** @description the messages its timeline holds (cards not counted) */
+            message_count: number;
+            /**
+             * @description `open`: a session can resume it; `ended`: it can only be read
+             * @enum {string}
+             */
+            state: "open" | "ended";
+        };
+        TimelinePage: {
+            data: components["schemas"]["TimelineItem"][];
+            /** @description the next older page; null at the conversation's start */
+            next_cursor: string | null;
+        };
+        /**
+         * @description v1-draft.21: one item of a past conversation, a message or a card its turn drew. `id` is stable and unique within the conversation; a message's `event_id` is its live event's identifier (`TranscriptItem.id`), the key an app merges live and resumed messages by, with `role`. A card is read-only in history.
+         *     Unlike `session.ready.transcript`, the history holds a guardrail's refusals: the person's message a guardrail refused and the fixed line said instead of an answer both carry `refusal: true`, so the app draws them as it drew them live (muted, never offered again). A `proposal` card carries `proposal_outcome`, what became of it.
+         */
+        TimelineItem: {
+            /** @constant */
+            type: "message";
+            id: string;
+            /**
+             * @description a client tolerates a role it does not know, as in `TranscriptItem`
+             * @enum {string}
+             */
+            role: "person" | "assistant" | "staff";
+            text: string;
+            /** Format: date-time */
+            at: string;
+            /** @description absent on a `person` message sent without a `client_event_id` */
+            event_id?: string;
+            turn_id?: string;
+            /** @description `assistant` only, present only when true: the reply stopped before it finished */
+            interrupted?: boolean;
+            /**
+             * @description Present only when true: a guardrail refused this turn. On a `person` message, the text it refused (as recorded, card-like digits masked); on an `assistant` message, the fixed line said instead of an answer.
+             * @constant
+             */
+            refusal?: true;
+        } | {
+            /** @constant */
+            type: "card";
+            id: string;
+            turn_id: string;
+            /** Format: date-time */
+            at: string;
+            card: components["schemas"]["Card"];
+            /**
+             * @description A `proposal` card only, always present on one: the outcome the app reported for it (`ui.action` `confirmed`, `declined`, `failed` or `expired`), or `pending` while none was reported. Draw it as settled; a past proposal is never confirmed from history.
+             * @enum {string}
+             */
+            proposal_outcome?: "pending" | "confirmed" | "declined" | "failed" | "expired";
+        };
+        ConversationDeleted: {
+            conversation_id: components["schemas"]["ConversationId"];
+            sessions_revoked: number;
+        };
         /** @description A time slot the person picked on a `time_slots` card (v1-draft.17, `docs/realtime-protocol.md` §6): the slot's `id`, and the `call_id` of the tool call the card came from (the card's `source.call_id`), so the runtime checks the pick against the evidence it holds for that call. Both are copied from the card; never built by the app. */
         SlotSelection: {
             id: string;
@@ -2256,10 +2393,10 @@ interface components {
             /** @constant */
             type: "session.closed";
             /**
-             * @description `replaced`: a newer session of the same conversation was created (close code `4409`)
+             * @description `replaced`: a newer session of the same conversation was created (close code `4409`). `deleted` (v1-draft.21): the person deleted the conversation from their history (`deleteConversation`, close code `4403`); drop it from the app's store and never resume it. A client that does not know `deleted` reads it as `revoked`, as any unknown reason.
              * @enum {string}
              */
-            reason: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "replaced";
+            reason: "expired" | "revoked" | "limit_reached" | "idle" | "server_restart" | "replaced" | "deleted";
         } | {
             /** @constant */
             type: "ui.answer.recorded";
@@ -2838,6 +2975,8 @@ interface components {
     };
     parameters: {
         IdempotencyKey: string;
+        /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+        OptionalIdempotencyKey: string;
         MediaJobId: string;
         ConversationId: components["schemas"]["ConversationId"];
         SessionId: string;
@@ -2913,6 +3052,39 @@ interface operations {
             503: components["responses"]["Problem"];
         };
     };
+    listConversations: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+                agent: string;
+                /** @description the side of the app; left out, the agent's template's */
+                experience_mode?: components["schemas"]["ExperienceMode"];
+                /** @description the business the person acts for; only with `experience_mode=business` */
+                business_scope_id?: components["schemas"]["BusinessScopeId"];
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Newest activity first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationPage"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
     getConversation: {
         parameters: {
             query?: never;
@@ -2939,6 +3111,66 @@ interface operations {
             410: components["responses"]["Problem"];
         };
     };
+    deleteConversation: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+            };
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Deleted. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ConversationDeleted"];
+                };
+            };
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
+    listConversationMessages: {
+        parameters: {
+            query: {
+                subject_id: components["schemas"]["SubjectId"];
+                limit?: number;
+                cursor?: string;
+            };
+            header?: never;
+            path: {
+                conversation_id: components["parameters"]["ConversationId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The newest page first; oldest first within a page. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TimelinePage"];
+                };
+            };
+            400: components["responses"]["Problem"];
+            401: components["responses"]["Problem"];
+            403: components["responses"]["Problem"];
+            404: components["responses"]["Problem"];
+            410: components["responses"]["Problem"];
+            503: components["responses"]["Problem"];
+        };
+    };
     getSession: {
         parameters: {
             query?: never;
@@ -2965,7 +3197,10 @@ interface operations {
     revokeSession: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+                "Idempotency-Key"?: components["parameters"]["OptionalIdempotencyKey"];
+            };
             path: {
                 session_id: components["parameters"]["SessionId"];
             };
@@ -2983,12 +3218,16 @@ interface operations {
                 };
             };
             404: components["responses"]["Problem"];
+            409: components["responses"]["Problem"];
         };
     };
     refreshClientSecret: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description Accepted, not required (declared in v1-draft.22). Scoped to the tenant and environment: the same key and request within 24 hours answers the first success again (`Idempotent-Replayed: true`); the same key with another request is `409 idempotency_conflict`. */
+                "Idempotency-Key"?: components["parameters"]["OptionalIdempotencyKey"];
+            };
             path: {
                 session_id: components["parameters"]["SessionId"];
             };