palbase 0.19.2 → 0.21.0

package/types/internal/src/modules/messaging.d.ts

@@ -798,6 +798,10 @@ export type MessagePage = {
      * The messages.
      */
     data: Message[];
+    /**
+     * The cursor to read on toward the newest (after); absent when the page reaches it. Only a page opened at a message (around), or read forward (after), has one.
+     */
+    newer_cursor?: string;
     /**
      * The next page's cursor; absent on the last page.
      */
@@ -1234,6 +1238,62 @@ export type ScheduledPage = {
      */
     next_cursor?: string;
 };
+/**
+ * A message a search found, and where it says what was asked — or, found by its meaning, how near the question it is.
+ */
+export type SearchHit = {
+    /**
+     * Where it says a word of the search, in the order said; none for a message found by its meaning.
+     */
+    matches: SearchMatch[];
+    message: Message;
+    /**
+     * Found by its meaning (by=meaning): how near the question it is, the cosine of their vectors (higher: nearer; what is found is at least 0.3).
+     */
+    score?: number;
+};
+/**
+ * Where a message found says a word of the search: in its text, or a file's name. offset and length are in UTF-16 code units, as mentions are.
+ */
+export type SearchMatch = {
+    /**
+     * The file whose name it is (attachment_name).
+     */
+    attachment_id?: string;
+    /**
+     * Where: `text`, or `attachment_name` (a file's name).
+     */
+    field: "text" | "attachment_name";
+    /**
+     * How long what was asked is (the word's beginning that matched), in UTF-16 code units.
+     */
+    length: number;
+    /**
+     * Where the word starts, in UTF-16 code units.
+     */
+    offset: number;
+};
+/**
+ * A page of what a search found, the newest first, with the conversations it is in and the people it shows — its writers, and the other person of a direct conversation — each once.
+ */
+export type SearchPage = {
+    /**
+     * The conversations of the messages found, each once, as the reader's list shows them.
+     */
+    conversations: Conversation[];
+    /**
+     * The messages found.
+     */
+    data: SearchHit[];
+    /**
+     * The next page's cursor; absent on the last page. A page may hold fewer than limit — even none — while there is more to read: read on while next_cursor is there.
+     */
+    next_cursor?: string;
+    /**
+     * The people the page shows, each once: who wrote what was found, and the other person of a direct conversation. Someone with no profile is not here.
+     */
+    profiles: Profile[];
+};
 /**
  * A message to send.
  */
@@ -1304,6 +1364,10 @@ export type Settings = {
      * Messages older are removed; null: kept for good.
      */
     retention_days: number | null;
+    /**
+     * Messages are found by what they mean too (GET /messaging/search?by=meaning): each message's text — not a system message's, nor one seen a limited number of times, nor one of vanish mode — is embedded by the project's embedding model, through the AI module, billed to the project as its AI use (Palbase's provider: kept by it up to 30 days for abuse monitoring, never trained on). Off (the default): no message goes to a model.
+     */
+    search_by_meaning: boolean;
 };
 /**
  * Changes how the project runs its conversations; what it names changes.
@@ -1325,6 +1389,10 @@ export type SettingsRequest = {
      * 1 to 36,500; null: for good.
      */
     retention_days?: number | null;
+    /**
+     * Turned on, the messages written before are embedded too (a walk, in the background), and each one written from then on; turned off, nothing more is embedded and the vectors are removed.
+     */
+    search_by_meaning?: boolean;
 };
 /**
  * What changed for the reader since their cursor.
@@ -2048,7 +2116,7 @@ export declare function client(t: Transport): {
     /**
      * A conversation's messages
      *
-     * The conversation's own timeline as the reader sees it, the newest first, a page at a time; a message removed is there, said removed.
+     * The conversation's own timeline as the reader sees it, the newest first, a page at a time; a message removed is there, said removed. Paged back from the newest (cursor: next_cursor), or opened at a message (around: the page holds it, with what came before and after it) and paged forward from there (after: newer_cursor) — a search's find shown where it was said. cursor, after and around are one at a time.
      */
     listMessages(input: {
         path: {
@@ -2056,7 +2124,9 @@ export declare function client(t: Transport): {
         };
         query?: {
             limit?: number; /** The cursor a page handed out (next_cursor). */
-            cursor?: string;
+            cursor?: string; /** Open the timeline at this message: the page holds it, about half the page before it and half after (next_cursor pages back, newer_cursor forward). A thread's answer is read in its thread (`in_thread`). */
+            around?: string; /** The cursor a page handed out to read on toward the newest (newer_cursor). */
+            after?: string;
         }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, MessagePage>>;
@@ -2328,6 +2398,16 @@ export declare function client(t: Transport): {
         body: UpdateScheduled; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
         signal?: AbortSignal;
     }): Promise<Reply<200, ScheduledMessage>>;
+    searchMessages(input: {
+        query: {
+            q: string; /** words (the default): the messages that say every word of q. meaning: those nearest what q means (the project's search_by_meaning on): one page, the nearest first; cursor is not taken. */
+            by?: "words" | "meaning"; /** Search one conversation of the reader's only. */
+            conversation_id?: string; /** How many (1 to 50; 20 when absent). */
+            limit?: number; /** The cursor a page handed out (next_cursor). */
+            cursor?: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, SearchPage>>;
     /**
      * How the project runs its conversations
      *

package/types/web/src/index.d.ts

@@ -10,7 +10,7 @@ export { connectVoice, type StartedVoice, type VoiceConnection, type VoiceOption
 export { Purchases, redemptionToken, type CheckoutSource, type CustomerInfo, type CustomerInfoListener, type GrantInfo, type MergeGrant, type OfferView, type Offerings, type Redeemed, type RedemptionLink, } from './purchases.js';
 export { Notify, WebPush, type PushPermission, type PushSubscribeOptions } from './notify.js';
 export { Flags, type FlagSource, type FlagsListener } from './flags.js';
-export { ConversationList, ConversationView, DeletedGroupList, indexedDBKeyValue, Messaging, ScheduledList, ThreadView, type Conversation, type ConversationViewState, type ConversationListState, type DeletedGroup, type DeletedGroupListState, type Entry, type Member, type Message, type MessagingOptions, type MyProfile, type Observed, type OpenedFile, type OutboxItem, type OutgoingFile, type Profile, type ScheduledMessage, type SendOptions, type ThreadState, type ThreadViewState, } from './messaging.js';
+export { ConversationList, ConversationView, DeletedGroupList, indexedDBKeyValue, Messaging, ScheduledList, ThreadView, type Conversation, type ConversationMatch, type ConversationViewState, type ConversationListState, type DeletedGroup, type DeletedGroupListState, type Entry, type Hit, type Member, type Message, type MessagingOptions, type MyProfile, type Observed, type OpenedFile, type OutboxItem, type OutgoingFile, type Profile, type ScheduledMessage, type SearchHit, type SearchMatch, type SearchOptions, type SearchResults, type SendOptions, type ThreadState, type ThreadViewState, } from './messaging.js';
 export { Inbox, type InboxItem, type InboxListOptions, type InboxPage, type InboxView, type InboxViewOptions } from './inbox.js';
 export { InApp, SESSION_START, type InAppOptions } from './inapp.js';
 export type { Paywall, PaywallRenderOptions } from './paywall/placement.js';

package/types/web/src/messaging.d.ts

@@ -1,5 +1,5 @@
 import { messaging as api } from '../../internal/src/modules/index.js';
-import { Engine, type DeletedGroup, type Entry, type KeyValue, type OutboxItem, type Touched } from '../../internal/src/messaging/index.js';
+import { Engine, type DeletedGroup, type Entry, type Hit, type KeyValue, type OutboxItem, type Touched } from '../../internal/src/messaging/index.js';
 import { type Fetch, type Transport } from '../../internal/src/transport.js';
 import { type SessionManager } from './session.js';
 import type { RealtimeSocket } from './socket.js';
@@ -10,7 +10,8 @@ export type MyProfile = api.MyProfile;
 export type Profile = api.Profile;
 export type ScheduledMessage = api.ScheduledMessage;
 export type ThreadState = api.ThreadState;
-export type { DeletedGroup, Entry, OutboxItem } from '../../internal/src/messaging/index.js';
+export type SearchMatch = api.SearchMatch;
+export type { DeletedGroup, Entry, Hit, OutboxItem } from '../../internal/src/messaging/index.js';
 export interface MessagingOptions {
     /**
      * What the device keeps of a person's conversations when they sign out:
@@ -80,18 +81,92 @@ export interface DeletedGroupListState {
 }
 export interface ConversationViewState {
     conversation: Conversation | null;
-    /** Its timeline: its messages, the oldest first, then what is on its way. */
+    /**
+     * Its timeline: its messages, the oldest first, then what is on its way. Opened at a message away from the newest
+     * (conversation(id, { at })), the stretch around it — what is on its way shows once it reaches the newest; nothing
+     * while the stretch is read (it is read once the view is subscribed), never the newest in the message's place.
+     */
     entries: Entry[];
     members: Member[];
     /** Who is typing now, by user id. */
     typing: string[];
     /** Older messages are there to read (loadEarlier). */
     hasEarlier: boolean;
+    /** Newer messages are there to read before the newest (loadLater): opened at a message away from it. */
+    hasLater: boolean;
+    /** The message it was opened at — what the app scrolls to and marks; null when opened at the newest. */
+    focus: string | null;
 }
 export interface ThreadViewState {
     root: Message | null;
     entries: Entry[];
     thread: ThreadState | null;
+    /** The answer it was opened at (thread(…, { at })); null otherwise. */
+    focus: string | null;
+}
+export interface SearchOptions {
+    /**
+     * How messages are found: by their words (the default) — every word asked, each a word's beginning — or by what
+     * they mean ('meaning'): those nearest the question, sharing none of its words perhaps ("flight time" finds "THY
+     * leaves at 14:30"), the nearest first, each with its score; one page, no conversations found by their name. By
+     * meaning, the project's setting search_by_meaning is on — or the search is refused, a PalbaseError whose code says
+     * why: 'search_by_meaning_off' (409), 'ai_payment_required' (402: the project's AI use is spent for the month;
+     * search by words meanwhile), 'too_many_searches' (429: a person asks 30 questions at once and one more a minute;
+     * retryAfter says when), 'busy' or 'embedding_unavailable' (503, retryAfter).
+     */
+    by?: 'words' | 'meaning';
+    /** Search one conversation of the person's only. */
+    conversationId?: string;
+    /** How many messages a page holds (1 to 50; 20 when absent). */
+    limit?: number;
+    /** The page after the one that handed out this cursor (nextCursor): a search by words alone. */
+    cursor?: string;
+}
+/** A message a search found, with what the app draws it with and where it opens. */
+export interface SearchHit {
+    message: Message;
+    /** The conversation it is in. */
+    conversation: Conversation;
+    /** The conversation's name: a group's title, the other person's name (null when they have none). */
+    title: string | null;
+    /** A group's photo, the other person's image. */
+    photo: string | null;
+    /** Who wrote it (null: the project's server, or someone with no profile). */
+    sender: Profile | null;
+    /** The other person of a direct conversation. */
+    peer: Profile | null;
+    /** Where it says what was asked: its text, or a file's name (UTF-16 code units); none when found by its meaning. */
+    matches: SearchMatch[];
+    /**
+     * Found by its meaning (by: 'meaning'): how near the question it is — the cosine of their vectors, from 0.3 (what
+     * is found is at least that) to 1, higher nearer; null when found by its words.
+     */
+    score: number | null;
+    /**
+     * The thread it answers in, when its conversation's timeline does not show it: open it with
+     * thread(conversation.id, threadRootId, { at: message.id }); null — open conversation(conversation.id, { at: message.id }).
+     */
+    threadRootId: string | null;
+}
+/** A conversation of the person's whose name says what was asked. */
+export interface ConversationMatch {
+    conversation: Conversation;
+    title: string | null;
+    photo: string | null;
+    peer: Profile | null;
+    /** Where its title says what was asked (UTF-16 code units). */
+    matches: Hit[];
+}
+export interface SearchResults {
+    /**
+     * The person's conversations whose name says every word asked, the latest first — on the first page alone of a
+     * search by words; none by meaning.
+     */
+    conversations: ConversationMatch[];
+    /** The messages found, the newest first — by meaning, the nearest first. */
+    messages: SearchHit[];
+    /** The next page's cursor (search(query, { cursor })); null on the last, and by meaning (one page). */
+    nextCursor: string | null;
 }
 /** Where a browser keeps it: IndexedDB, one object store of each person's state. */
 export declare function indexedDBKeyValue(name?: string): KeyValue | null;
@@ -125,6 +200,9 @@ export declare class Messaging {
     private saving;
     private readonly reopeners;
     private readonly incoming;
+    private readonly windows;
+    /** People's profiles read for a search (a direct conversation's name is the other person's), and when. */
+    private readonly people;
     private readonly session;
     private readonly socket;
     private readonly ref;
@@ -154,6 +232,12 @@ export declare class Messaging {
     private heardLive;
     /** Applies what changed to the person's conversations — to e's alone: what came for one who is gone goes nowhere. */
     private changed;
+    /** What changed, applied to the stretches read around a message too. */
+    private toWindows;
+    /** Messages put in a stretch: each goes when its time is up, as the timeline's do. */
+    private putWindow;
+    /** Runs take on each stretch of a conversation; answers whether any changed. */
+    private fromWindows;
     /** What follows a change: timers to take messages away, deliveries told, the device's copy saved. */
     private after;
     /** A message whose time is up goes from the device at once: the server says so too, a moment after. */
@@ -181,8 +265,14 @@ export declare class Messaging {
      * the word came (on the deleter's own device, now and then, the group the person deleted).
      */
     deletedGroups(): DeletedGroupList;
-    /** A conversation of the person's, kept up to date: its timeline, its members, who is typing. */
-    conversation(conversationId: string): ConversationView;
+    /**
+     * A conversation of the person's, kept up to date: its timeline, its members, who is typing. Opened at a message
+     * (at — a search's find), its timeline is the stretch around it, focus the message: loadEarlier and loadLater read
+     * on from there, and once it reaches the newest it is the conversation's timeline again.
+     */
+    conversation(conversationId: string, opts?: {
+        at?: string;
+    }): ConversationView;
     /** The direct conversation with someone — the one there is, or a new one. */
     direct(userId: string): Promise<ConversationView>;
     /** A new group, the person its owner. */
@@ -196,8 +286,23 @@ export declare class Messaging {
         conversation: ConversationView;
         notAdded: api.NotAdded[];
     }>;
-    /** A thread: a message's answers, kept up to date. */
-    thread(conversationId: string, rootId: string): ThreadView;
+    /** A thread: a message's answers, kept up to date — opened at an answer (at, a search's find), read on until it is there. */
+    thread(conversationId: string, rootId: string, opts?: {
+        at?: string;
+    }): ThreadView;
+    /**
+     * Finds the person's messages by their words — every word asked, each a word's beginning, as they type it
+     * ("cafe" finds "Café's", capitals and the Turkish i's alike) — in what they say or their files' names, the newest
+     * first, a page at a time: in all their conversations, or one (conversationId). Each comes with its conversation, its name and picture, who wrote
+     * it and where it says what was asked. On the first page, the conversations whose name says it too (a group's
+     * title, the other person's name), from the person's own list. A query with no word finds nothing.
+     *
+     * By meaning (by: 'meaning'; the project's setting search_by_meaning on), the messages nearest what the query
+     * means instead, the nearest first, each with its score: one page, no conversations by name. Opened as any find is.
+     */
+    search(query: string, opts?: SearchOptions): Promise<SearchResults>;
+    /** The person's conversations whose name says every word asked: a group's title, the other person's name. */
+    private named;
     /** The person's messages scheduled for later, kept up to date. */
     scheduled(): ScheduledList;
     /** The threads the person follows, the latest answered first. */
@@ -246,6 +351,11 @@ export declare class Messaging {
      * reportableUntil, naming no message: the last 30 messages the person saw in it go with the report.
      */
     report(input: api.ReportRequest): Promise<api.ReportCreated>;
+    /**
+     * A stretch that reaches the newest becomes the timeline's: both run to the newest, so together they are one —
+     * read back from the older of their ends.
+     */
+    private merge;
 }
 declare abstract class View<S> implements Observed<S> {
     protected listeners: Set<Listener>;
@@ -258,6 +368,7 @@ declare abstract class View<S> implements Observed<S> {
     get state(): S;
     subscribe(listener: Listener): () => void;
     protected opened(): void;
+    protected closed(): void;
     protected abstract touches(t: Touched): boolean;
     protected abstract read(): S;
 }
@@ -271,14 +382,32 @@ export declare class DeletedGroupList extends View<DeletedGroupListState> {
 }
 export declare class ConversationView extends View<ConversationViewState> {
     readonly id: string;
-    constructor(m: Messaging, id: string);
+    /** The message it was opened at (conversation(id, { at })). */
+    readonly focus: string | null;
+    private window;
+    /** Opening it at its message: read, or failed (it opens at the newest then). */
+    private opening;
+    /** Opened at its message: until then nothing is drawn — not the newest in the message's place. */
+    private settled;
+    constructor(m: Messaging, id: string, focus?: string | null);
     protected opened(): void;
+    protected closed(): void;
     protected touches(t: Touched): boolean;
+    /** The stretch around the message it was opened at, while it is apart from the timeline. */
+    private stretch;
     protected read(): ConversationViewState;
     /** Reads the conversation's newest page now (opening it does). */
     refresh(): Promise<boolean>;
     /** Reads the page of messages before the oldest one drawn; answers whether there are more. */
     loadEarlier(): Promise<boolean>;
+    /**
+     * Reads the page of messages after the newest one drawn, opened at a message away from the newest; answers whether
+     * there are more. Once it reaches the newest, the timeline is the conversation's again — what comes live, what is on
+     * its way.
+     */
+    loadLater(): Promise<boolean>;
+    /** Puts aside the stretch it was opened at: its timeline is the conversation's newest again (focus stays). */
+    showLatest(): void;
     send(input: string | SendOptions): Promise<OutboxItem>;
     markRead(seq?: number): Promise<void>;
     typing(): Promise<void>;
@@ -287,7 +416,9 @@ export declare class ConversationView extends View<ConversationViewState> {
 export declare class ThreadView extends View<ThreadViewState> {
     readonly conversationId: string;
     readonly rootId: string;
-    constructor(m: Messaging, conversationId: string, rootId: string);
+    /** The answer it was opened at (thread(…, { at })). */
+    readonly focus: string | null;
+    constructor(m: Messaging, conversationId: string, rootId: string, focus?: string | null);
     protected opened(): void;
     protected touches(t: Touched): boolean;
     protected read(): ThreadViewState;