@lumavox/client 0.11.1 → 0.14.0

package/README.md

@@ -57,7 +57,7 @@ for a 402, 403 or 429. `clearToken()` at sign-out.
 | Resource | Methods |
 |---|---|
 | `sessions` | `create`, `list` (every one), `page`, `get`, `history` (the whole transcript, newest first), `delete`, `compact`, `extract` |
-| `facts` | `list`, `page`, `delete`, `deleteAll` |
+| `facts` | `list`, `page` (`{ include_replaced: true }` after the options lists the replaced ones too), `create` (tell the agents something; `created` says whether it was new), `update` (correct one's words), `delete`, `deleteAll` |
 | `relations` | `list`, `page` |
 
 Bodies and answers are the API's own JSON, as the API reference shows them;

package/dist/client.d.ts

@@ -22,7 +22,7 @@
  *   and later, browsers, React Native.
  */
 import { type ConnectOptions, Conversation, type ConversationHandlers } from "./conversation.js";
-import type { CompactionInfo, CompactRequest, FactInfo, FactPage, FactsDeleted, MessageInfo, RelationInfo, RelationPage, SessionCreateRequest, SessionDetail, SessionInfo, SessionPage } from "./gen/index.js";
+import type { CompactionInfo, CompactRequest, FactCreateRequest, FactInfo, FactPage, FactsDeleted, FactUpdateRequest, MessageInfo, RelationInfo, RelationPage, SessionCreateRequest, SessionDetail, SessionInfo, SessionPage } from "./gen/index.js";
 import type { WebSocketConstructor } from "./socket.js";
 import { type GetToken } from "./token.js";
 import { type Fetch, type RequestOptions } from "./transport.js";
@@ -77,14 +77,31 @@ export interface Sessions {
     /** Compact it and extract facts, in one model call. */
     extract(id: string, options?: RequestOptions): Promise<CompactionInfo>;
 }
+export interface FactListParams {
+    /**
+     * Also the facts a later conversation replaced or removed, each with
+     * `replaced_at`, until they are deleted 30 days later.
+     */
+    include_replaced?: boolean;
+}
 export interface Facts {
     /** Everything remembered about the person, oldest first, 200 a page. */
-    list(options?: RequestOptions): AsyncGenerator<FactInfo, void, undefined>;
+    list(options?: RequestOptions, params?: FactListParams): AsyncGenerator<FactInfo, void, undefined>;
     /**
      * One page of them, 100 by default; `cursor` is the `next_cursor` of the
      * page before.
      */
-    page(options?: RequestOptions, cursor?: string): Promise<FactPage>;
+    page(options?: RequestOptions, cursor?: string, params?: FactListParams): Promise<FactPage>;
+    /**
+     * Tell the agents something about the person: yours (`source`
+     * `customer`), never replaced by a conversation. `created` is `false`
+     * when a fact already said it.
+     */
+    create(body: FactCreateRequest, options?: RequestOptions): Promise<FactInfo & {
+        created: boolean;
+    }>;
+    /** Correct one fact's words; the old ones are kept as forgotten. */
+    update(id: string, body: FactUpdateRequest, options?: RequestOptions): Promise<FactInfo>;
     /** Forget one: `true`, or `false` when it is already gone. */
     delete(id: string, options?: RequestOptions): Promise<boolean>;
     /** Forget everything about the person: how many facts went. Their conversations stay. */

package/dist/client.js

@@ -55,11 +55,10 @@ export function createClient(options) {
     });
     const tokens = new Tokens(options.getToken);
     /** A call with the key, and with a new one once if it is refused. */
-    async function send(call, request) {
+    async function answered(call, request) {
         const key = await tokens.current();
         try {
-            return (await transport.request({ ...call, token: key }, request))
-                .data;
+            return await transport.request({ ...call, token: key }, request);
         }
         catch (error) {
             if (!(error instanceof AuthenticationError))
@@ -68,15 +67,16 @@ export function createClient(options) {
                 status: 401,
                 code: error.code,
             });
-            return (await transport.request({ ...call, token: fresh }, request))
-                .data;
+            return await transport.request({ ...call, token: fresh }, request);
         }
     }
+    /** `answered`'s body. */
+    const send = async (call, request) => (await answered(call, request)).data;
     const sessionPath = (id, rest = "") => `/v1/agent/sessions/${segment(id)}${rest}`;
     /** One page of the list at `path`. */
     const read = (path, params = {}, request) => send({ method: "GET", path, query: { ...params } }, request);
     const page = (params = {}, request) => read("/v1/agent/sessions", params, request);
-    const factPage = (request, cursor, limit) => read("/v1/agent/facts", { limit, cursor }, request);
+    const factPage = (request, cursor, params = {}) => read("/v1/agent/facts", { ...params, cursor }, request);
     const relationPage = (params = {}, request) => read("/v1/agent/relations", params, request);
     const get = (id, params = {}, request) => send({ method: "GET", path: sessionPath(id), query: { ...params } }, request);
     return {
@@ -102,10 +102,15 @@ export function createClient(options) {
             extract: (id, request) => send({ method: "POST", path: sessionPath(id, "/extract") }, request),
         },
         facts: {
-            list: (request) => pages((cursor) => factPage(request, cursor, PAGE)),
-            page: factPage,
+            list: (request, params = {}) => pages((cursor) => factPage(request, cursor, { ...params, limit: PAGE })),
+            page: (request, cursor, params = {}) => factPage(request, cursor, params),
             delete: (id, request) => done(send({ method: "DELETE", path: `/v1/agent/facts/${segment(id)}` }, request)),
             deleteAll: (request) => send({ method: "DELETE", path: "/v1/agent/facts" }, request),
+            create: async (body, request) => {
+                const answer = await answered({ method: "POST", path: "/v1/agent/facts", body }, request);
+                return { ...answer.data, created: answer.status === 201 };
+            },
+            update: (id, body, request) => send({ method: "PATCH", path: `/v1/agent/facts/${segment(id)}`, body }, request),
         },
         relations: {
             list: (params = {}, request) => pages((cursor) => relationPage({ limit: PAGE, ...params, cursor }, request)),

package/dist/gen/index.d.ts

@@ -1 +1 @@
-export type { ClientOptions, CompactionInfo, CompactRequest, CompactSessionData, CompactSessionError, CompactSessionErrors, CompactSessionResponse, CompactSessionResponses, CreateSessionData, CreateSessionError, CreateSessionErrors, CreateSessionResponse, CreateSessionResponses, DeleteAllFactsData, DeleteAllFactsError, DeleteAllFactsErrors, DeleteAllFactsResponse, DeleteAllFactsResponses, DeleteFactData, DeleteFactError, DeleteFactErrors, DeleteFactResponse, DeleteFactResponses, DeleteSessionData, DeleteSessionError, DeleteSessionErrors, DeleteSessionResponse, DeleteSessionResponses, ErrorCode, ErrorInfo, ErrorResponse, ExtractSessionFactsData, ExtractSessionFactsError, ExtractSessionFactsErrors, ExtractSessionFactsResponse, ExtractSessionFactsResponses, FactInfo, FactPage, FactsDeleted, GetSessionData, GetSessionError, GetSessionErrors, GetSessionResponse, GetSessionResponses, KnowledgeCitation, KnowledgeLookupInfo, ListFactsData, ListFactsError, ListFactsErrors, ListFactsResponse, ListFactsResponses, ListRelationsData, ListRelationsError, ListRelationsErrors, ListRelationsResponse, ListRelationsResponses, ListSessionsData, ListSessionsError, ListSessionsErrors, ListSessionsResponse, ListSessionsResponses, MessageInfo, MessageKnowledge, MessagePage, MessageSource, MessageToolCall, RelationInfo, RelationPage, SessionCreateRequest, SessionDetail, SessionInfo, SessionPage, ValidationIssue } from './types.gen.js';
+export type { ClientOptions, CompactionInfo, CompactRequest, CompactSessionData, CompactSessionError, CompactSessionErrors, CompactSessionResponse, CompactSessionResponses, CreateFactData, CreateFactError, CreateFactErrors, CreateFactResponse, CreateFactResponses, CreateSessionData, CreateSessionError, CreateSessionErrors, CreateSessionResponse, CreateSessionResponses, DeleteAllFactsData, DeleteAllFactsError, DeleteAllFactsErrors, DeleteAllFactsResponse, DeleteAllFactsResponses, DeleteFactData, DeleteFactError, DeleteFactErrors, DeleteFactResponse, DeleteFactResponses, DeleteSessionData, DeleteSessionError, DeleteSessionErrors, DeleteSessionResponse, DeleteSessionResponses, ErrorCode, ErrorInfo, ErrorResponse, ExtractSessionFactsData, ExtractSessionFactsError, ExtractSessionFactsErrors, ExtractSessionFactsResponse, ExtractSessionFactsResponses, FactCreateRequest, FactInfo, FactPage, FactsDeleted, FactUpdateRequest, GetSessionData, GetSessionError, GetSessionErrors, GetSessionResponse, GetSessionResponses, KnowledgeCitation, KnowledgeLookupInfo, ListFactsData, ListFactsError, ListFactsErrors, ListFactsResponse, ListFactsResponses, ListRelationsData, ListRelationsError, ListRelationsErrors, ListRelationsResponse, ListRelationsResponses, ListSessionsData, ListSessionsError, ListSessionsErrors, ListSessionsResponse, ListSessionsResponses, MessageInfo, MessageKnowledge, MessagePage, MessageSource, MessageToolCall, RelationInfo, RelationPage, SessionCreateRequest, SessionDetail, SessionInfo, SessionPage, UpdateFactData, UpdateFactError, UpdateFactErrors, UpdateFactResponse, UpdateFactResponses, ValidationIssue } from './types.gen.js';

package/dist/gen/types.gen.d.ts

@@ -313,14 +313,50 @@ export type FactInfo = {
      * Which agent was being talked to when this was learned.
      */
     agent_id: string | null;
+    /**
+     * When a conversation last said it again; `null` for never. The agents see the most recently confirmed first when not every fact fits.
+     */
+    confirmed_at: string | null;
     created_at: string;
     id: string;
+    /**
+     * When a later conversation replaced or removed it; `null` while it stands. Listed only with `include_replaced=true`.
+     */
+    replaced_at: string | null;
+    /**
+     * The fact that replaced it — moved city, changed job — or `null` when it was removed with nothing in its place, or stands.
+     */
+    replaced_by: string | null;
+    /**
+     * `person`: recalled by every agent of yours that shares its facts. `agent`: kept to one agent (`agent_id`), which alone recalls it — learnt by an agent whose `facts_scope` is `agent`, or added for that agent.
+     */
+    scope: 'person' | 'agent';
+    /**
+     * `conversation`: a reading learnt it. `customer`: you added or corrected it — a later conversation never replaces or removes it.
+     */
+    source: 'conversation' | 'customer';
     text: string;
     /**
-     * A fact is never edited, only learned or forgotten: the same as `created_at`.
+     * When it last changed: its `replaced_at` once replaced, else when you last corrected it, else its `created_at`.
      */
     updated_at: string;
 };
+export type FactCreateRequest = {
+    /**
+     * What to remember about the person, as one plain statement: "Prefers to be called Sam." At most 500 characters. Never a secret — a password, a code, a card, account or identity number, or a key is refused, since facts are sent to the model on every turn.
+     */
+    text: string;
+    /**
+     * Keep it to one agent: only that agent recalls it. Unset or `null`: every agent of yours that shares its facts — and the ones that keep their own, too.
+     */
+    agent_id?: string | null;
+};
+export type FactUpdateRequest = {
+    /**
+     * What to remember about the person, as one plain statement: "Prefers to be called Sam." At most 500 characters. Never a secret — a password, a code, a card, account or identity number, or a key is refused, since facts are sent to the model on every turn.
+     */
+    text: string;
+};
 export type FactsDeleted = {
     /**
      * How many stored facts were deleted.
@@ -649,6 +685,10 @@ export type ListFactsData = {
          * Optional, and only ever the key's own end user — their `eu_...` id or your own id for them. Anybody else is a 403.
          */
         end_user_id?: string;
+        /**
+         * Also list the facts a later conversation replaced or removed, until they are deleted 30 days later.
+         */
+        include_replaced?: boolean;
         /**
          * How many to answer, 1 to 200.
          */
@@ -686,6 +726,46 @@ export type ListFactsResponses = {
     200: FactPage;
 };
 export type ListFactsResponse = ListFactsResponses[keyof ListFactsResponses];
+export type CreateFactData = {
+    body: FactCreateRequest;
+    path?: never;
+    query?: never;
+    url: '/v1/agent/facts';
+};
+export type CreateFactErrors = {
+    /**
+     * The request could not be read: malformed JSON
+     */
+    400: ErrorResponse;
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key's scopes do not cover this, or it is pinned to agents and `agent_id` names another
+     */
+    403: ErrorResponse;
+    /**
+     * No text, or text that looks like a secret — a password, a code, a card, account or identity number, or a key — which no fact may hold
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type CreateFactError = CreateFactErrors[keyof CreateFactErrors];
+export type CreateFactResponses = {
+    /**
+     * The fact that already said it, now yours
+     */
+    200: FactInfo;
+    /**
+     * The fact, remembered
+     */
+    201: FactInfo;
+};
+export type CreateFactResponse = CreateFactResponses[keyof CreateFactResponses];
 export type DeleteFactData = {
     body?: never;
     path: {
@@ -724,6 +804,52 @@ export type DeleteFactResponses = {
     204: void;
 };
 export type DeleteFactResponse = DeleteFactResponses[keyof DeleteFactResponses];
+export type UpdateFactData = {
+    body: FactUpdateRequest;
+    path: {
+        fact_id: string;
+    };
+    query?: never;
+    url: '/v1/agent/facts/{fact_id}';
+};
+export type UpdateFactErrors = {
+    /**
+     * The request could not be read: malformed JSON
+     */
+    400: ErrorResponse;
+    /**
+     * Missing or invalid credentials
+     */
+    401: ErrorResponse;
+    /**
+     * The key is valid but its scopes do not cover this capability
+     */
+    403: ErrorResponse;
+    /**
+     * Unknown fact id
+     */
+    404: ErrorResponse;
+    /**
+     * Replaced by a later conversation, or another fact already says that
+     */
+    409: ErrorResponse;
+    /**
+     * No text, or text that looks like a secret — a password, a code, a card, account or identity number, or a key — which no fact may hold
+     */
+    422: ErrorResponse;
+    /**
+     * Rate limit exceeded
+     */
+    429: ErrorResponse;
+};
+export type UpdateFactError = UpdateFactErrors[keyof UpdateFactErrors];
+export type UpdateFactResponses = {
+    /**
+     * The fact, corrected
+     */
+    200: FactInfo;
+};
+export type UpdateFactResponse = UpdateFactResponses[keyof UpdateFactResponses];
 export type ListRelationsData = {
     body?: never;
     path?: never;

package/dist/index.d.ts

@@ -8,7 +8,7 @@
  * own options go last.
  */
 export type { AgentAudio } from "./audio.js";
-export { type Client, type ClientOptions, createClient, DEFAULT_BASE_URL, type Facts, type RelationListParams, type Relations, type SessionGetParams, type SessionListParams, type Sessions, } from "./client.js";
+export { type Client, type ClientOptions, createClient, DEFAULT_BASE_URL, type FactListParams, type Facts, type RelationListParams, type Relations, type SessionGetParams, type SessionListParams, type Sessions, } from "./client.js";
 export { type CloseInfo, type ConnectOptions, Conversation, type ConversationHandlers, type ConversationState, type Disconnect, type Dropped, READY_DEADLINE_MS, type Snapshot, type StartAudioOptions, type ToolHandler, type TranscriptOutcome, type TurnOptions, type TurnOutcome, type TurnSnapshot, } from "./conversation.js";
 export { AuthenticationError, ConflictError, ConnectionError, InsufficientCreditsError, NotFoundError, PermissionError, PlatformError, type PlatformErrorInit, RateLimitError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
 export type * from "./events.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumavox/client",
-  "version": "0.11.1",
+  "version": "0.14.0",
   "description": "Talk to Lumavox agents from a browser, a React Native app or Node, with an end user's ephemeral key: conversations on the agent's socket, sessions, memory and relations. Zero dependencies.",
   "license": "MIT",
   "type": "module",