@verentis/sdk 0.2.6 → 1.0.1

package/dist/index.d.ts

@@ -26,6 +26,304 @@ interface HeaderActionRegistration {
 type HeaderActionHandler = () => void | HeaderActionResult | Promise<void | HeaderActionResult>;
 declare function isHeaderAction(value: unknown): value is HeaderAction;
 
+/**
+ * Page commands an app exports to the workspace command registry (⌘K palette) while they are active.
+ *
+ * Unlike header actions, page commands have no placement and no count limit: an app with 100 actionable
+ * buttons registers all 100. Only display metadata crosses the bridge — never form data or handler code.
+ * Registration changes are sent incrementally (`upsert` / `remove`) in batches of at most
+ * {@link APP_COMMAND_BATCH_SIZE} entries per message, so large pages do not resend full snapshots.
+ */
+interface AppCommand {
+    /** Stable identifier, unique within the app session. */
+    id: string;
+    label: string;
+    description?: string;
+    /** Palette group heading; the host defaults to the current page. */
+    group?: string;
+    /** `lucide:<name>` icon. */
+    icon?: string;
+    /** Extra search terms. */
+    keywords?: string[];
+    variant?: 'default' | 'outline' | 'destructive';
+    enabled?: boolean;
+    busy?: boolean;
+    disabledReason?: string;
+}
+type AppCommandHandler = () => void | Promise<void>;
+interface AppCommandRegistration {
+    update(command: AppCommand): void;
+    dispose(): void;
+}
+/** Maximum entries (upserts + removals) in one `verentis:commands:update` message. Not a command-count cap. */
+declare const APP_COMMAND_BATCH_SIZE = 200;
+/** Host capability announced in `verentis:init` when it accepts page commands. */
+declare const APP_COMMANDS_CAPABILITY = "commands";
+declare const APP_COMMAND_ID_PATTERN: RegExp;
+declare function isAppCommand(value: unknown): value is AppCommand;
+
+/** A conversation participant. `agent` is reserved for future AI participants and rejected today. */
+interface ChatParticipant {
+    kind: 'user' | 'bot';
+    id: string;
+}
+type ConversationKind = 'direct' | 'group' | 'channel';
+type ConversationVisibility = 'private' | 'public';
+type HistoryPolicy = 'full' | 'fromJoin';
+type MemberRole = 'owner' | 'admin' | 'member';
+type AttentionLevel = 'all' | 'mentions' | 'none';
+/** A versioned message part. Unknown types are rejected on write; readers fall back to `fallbackText`. */
+type MessagePartInput = {
+    partId?: string;
+    type: 'text';
+    version?: 1;
+    data: {
+        markdown: string;
+    };
+    fallbackText?: string;
+} | {
+    partId?: string;
+    type: 'link';
+    version?: 1;
+    data: {
+        url: string;
+        title?: string;
+    };
+    fallbackText?: string;
+} | {
+    partId?: string;
+    type: 'mention';
+    version?: 1;
+    data: {
+        participant: ChatParticipant;
+        label?: string;
+    };
+    fallbackText?: string;
+} | {
+    partId?: string;
+    type: 'fileRef';
+    version?: 1;
+    data: {
+        nodeId: string;
+        versionId?: string;
+        name?: string;
+        mimeType?: string;
+        size?: number;
+    };
+    fallbackText?: string;
+};
+interface MessagePart {
+    partId: string;
+    type: string;
+    version: number;
+    data: Record<string, unknown>;
+    fallbackText: string;
+}
+interface Membership {
+    role: MemberRole;
+    active: boolean;
+    joinedSeq: number;
+    /** First sequence this member may see (the history boundary). */
+    historyFromSeq: number;
+}
+interface Conversation {
+    id: string;
+    kind: ConversationKind;
+    visibility: ConversationVisibility;
+    historyPolicy: HistoryPolicy;
+    title?: string;
+    topic?: string;
+    archived: boolean;
+    createdAt: string;
+    createdBy: ChatParticipant;
+    /** Sequence of the latest durable change. */
+    highWatermark: number;
+    membershipRevision: number;
+    memberCount: number;
+    lastActivityAt: string;
+    /** Null when previewing a public channel you have not joined. */
+    membership?: Membership;
+    directParticipants?: ChatParticipant[];
+}
+interface ConversationSummary {
+    id: string;
+    kind: ConversationKind;
+    visibility: ConversationVisibility;
+    title?: string;
+    directParticipants?: ChatParticipant[];
+    archived: boolean;
+    highWatermark: number;
+    readThroughSeq: number;
+    unreadCount: number;
+    unreadMentionCount: number;
+    muted: boolean;
+    attention: AttentionLevel;
+    lastMessageId?: string;
+    lastMessageAuthor?: ChatParticipant;
+    lastMessagePreview?: string;
+    lastActivityAt: string;
+}
+interface ReplyPreview {
+    messageId: string;
+    /** False when the original is outside your history boundary or gone. */
+    available: boolean;
+    deleted: boolean;
+    author?: ChatParticipant;
+    preview?: string;
+}
+interface ChatMessage {
+    id: string;
+    conversationId: string;
+    /** Creation sequence; never changes on edit. */
+    seq: number;
+    lastEventSeq: number;
+    revision: number;
+    author: ChatParticipant;
+    contentVersion: number;
+    /** Absent for deleted messages (tombstones). */
+    parts?: MessagePart[];
+    fallbackText?: string;
+    replyTo?: ReplyPreview;
+    createdAt: string;
+    editedAt?: string;
+    deleted: boolean;
+    deletedAt?: string;
+}
+interface MessagePage {
+    /** Oldest first. */
+    items: ChatMessage[];
+    /** Cursor for the next older page; absent at the history boundary. */
+    before?: string;
+    highWatermark: number;
+    historyFromSeq: number;
+}
+interface ConversationEvent {
+    seq: number;
+    kind: string;
+    at: string;
+    author?: ChatParticipant;
+    messageId?: string;
+    /** Current state of the message (content may have changed since the event). */
+    message?: ChatMessage;
+    participants?: ChatParticipant[];
+    role?: MemberRole;
+}
+interface EventPage {
+    items: ConversationEvent[];
+    /** Cursor to continue from. */
+    next: string;
+    highWatermark: number;
+    hasMore: boolean;
+    /** The cursor cannot be continued: discard local state and reload from `conversation` and history. */
+    resetRequired: boolean;
+    conversation?: Conversation;
+}
+interface ChatPage<T> {
+    items: T[];
+    cursor?: string;
+}
+interface Member {
+    participant: ChatParticipant;
+    role: MemberRole;
+    joinedSeq: number;
+    joinedAt: string;
+}
+interface ReadState {
+    conversationId: string;
+    readThroughSeq: number;
+    unreadCount: number;
+    unreadMentionCount: number;
+}
+interface ConversationPreferences {
+    conversationId: string;
+    muted: boolean;
+    attention: AttentionLevel;
+}
+interface PublicChannel {
+    id: string;
+    title?: string;
+    topic?: string;
+    memberCount: number;
+    lastActivityAt: string;
+}
+interface ChatPerson {
+    userId: string;
+    displayName: string;
+    /** Relative avatar URL on the workspace API. */
+    avatarUrl: string;
+}
+interface ChatBot {
+    id: string;
+    app: string;
+    key: string;
+    displayName: string;
+    description?: string;
+    directMessages: 'none' | 'workspace';
+}
+interface ChatCommandArgument {
+    name: string;
+    type: 'string' | 'number' | 'boolean';
+    required: boolean;
+    description?: string;
+}
+interface ChatCommand {
+    /** `{app}/{name}`. */
+    id: string;
+    app: string;
+    name: string;
+    description: string;
+    botId?: string;
+    arguments: ChatCommandArgument[];
+}
+/** The validated Execution request a command invocation returns; run it with the user's own token. */
+interface ChatCommandInvocation {
+    command: string;
+    eventSeq: number;
+    invocationKey: string;
+    workspaceId: string;
+    filePath: string;
+    branch: string;
+    /** JSON object text of the validated arguments. */
+    parameters: string;
+}
+interface CreateConversationOptions {
+    kind: ConversationKind;
+    participants?: ChatParticipant[];
+    title?: string;
+    topic?: string;
+    visibility?: ConversationVisibility;
+    historyPolicy?: HistoryPolicy;
+    /** Makes creation idempotent for this caller. */
+    idempotencyKey?: string;
+}
+interface SendMessageOptions {
+    replyTo?: string;
+    /** Makes the send idempotent: a retry with the same key and body returns the original message. */
+    idempotencyKey?: string;
+}
+interface BotPostOptions {
+    /** The bot's key when the app declares several. */
+    bot?: string;
+    conversationId?: string;
+    userId?: string;
+    parts: MessagePartInput[];
+    idempotencyKey?: string;
+}
+/** Identifier-only live hint; fetch content through the chat API. */
+interface ChatChangeHint {
+    conversationId: string;
+    highWatermark: number;
+    kinds: Array<'messages' | 'members' | 'conversation'>;
+}
+type ChatConnectionStatus = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected';
+interface ChatSubscriptionHandlers {
+    onChange: (hint: ChatChangeHint) => void;
+    /** Called with the host connection state; reconcile durable state after `connected` following a disconnect. */
+    onConnection?: (status: ChatConnectionStatus) => void;
+    /** The host refused the subscription (for example `chat.read` is not approved). */
+    onError?: (reason: string) => void;
+}
+
 type BridgeEventType = HostToAppMessage['type'];
 /** Handles a host message; the resolved value (structured-cloneable, ideally JSON) is the reply. */
 type HostMessageHandler = (payload: unknown) => unknown | Promise<unknown>;
@@ -50,6 +348,14 @@ declare class Bridge {
     private sessionId;
     private actions;
     private requests;
+    private commands;
+    private commandUpserts;
+    private commandRemovals;
+    private commandReset;
+    private commandFlushScheduled;
+    private commandRequests;
+    private _hostCapabilities;
+    private chatSubscribers;
     private hostMessageHandlers;
     private hostMessageRequests;
     private wopiRequests;
@@ -64,6 +370,13 @@ declare class Bridge {
     }>;
     /** Get the host origin (available after init) */
     get hostOrigin(): string | null;
+    /** Capabilities the host announced in `verentis:init`. */
+    get hostCapabilities(): readonly string[];
+    /**
+     * Whether the host exports page commands to its command registry. Older hosts ignore registrations;
+     * commands still run locally, they are just not discoverable in the workspace palette.
+     */
+    get supportsCommands(): boolean;
     /** Send a message to the host */
     postToHost(message: AppToHostMessage): void;
     /**
@@ -92,6 +405,16 @@ declare class Bridge {
     private requestWopi;
     requestNativeCollaboration(command: NativeCollaborationCommand): Promise<unknown>;
     registerAction(descriptor: HeaderAction, handler: HeaderActionHandler): HeaderActionRegistration;
+    /**
+     * Export a page command to the workspace command registry while it is active. There is no count limit;
+     * dispose the registration when the control unmounts. May be called before the init handshake.
+     */
+    registerCommand(descriptor: AppCommand, handler: AppCommandHandler): AppCommandRegistration;
+    private queueCommand;
+    private scheduleCommandFlush;
+    private commandSnapshot;
+    private flushCommands;
+    private invokeCommand;
     private publishActions;
     private invokeAction;
     /**
@@ -101,6 +424,12 @@ declare class Bridge {
      */
     onHostMessage(channel: string, handler: HostMessageHandler): () => void;
     private receiveHostMessage;
+    /**
+     * Subscribes to the host's chat live hints (see `ChatModule.subscribeChanges`). The first subscriber asks the host
+     * to relay; the last one to leave stops it. Messages from another session are ignored.
+     */
+    subscribeChat(handlers: ChatSubscriptionHandlers): () => void;
+    private receiveChat;
     /** Subscribe to a specific message type from the host */
     on(type: BridgeEventType, listener: BridgeListener): () => void;
     /** Clean up event listeners */
@@ -226,6 +555,8 @@ interface VerentisInitMessage extends VerentisMessage {
     context: AppContext;
     token: TokenInfo;
     sessionId?: string;
+    /** Optional host features, e.g. `commands` for page command registration. */
+    capabilities?: string[];
 }
 interface VerentisActionsSetMessage extends VerentisMessage {
     type: 'verentis:actions:set';
@@ -246,6 +577,27 @@ interface VerentisActionResultMessage extends VerentisMessage {
     result?: HeaderActionResult;
     error?: string;
 }
+/** Incremental page-command registration. `reset` replaces everything the host holds for the session. */
+interface VerentisCommandsUpdateMessage extends VerentisMessage {
+    type: 'verentis:commands:update';
+    sessionId: string;
+    reset?: boolean;
+    upsert: AppCommand[];
+    remove: string[];
+}
+interface VerentisCommandInvokeMessage extends VerentisMessage {
+    type: 'verentis:command:invoke';
+    sessionId: string;
+    requestId: string;
+    commandId: string;
+}
+interface VerentisCommandResultMessage extends VerentisMessage {
+    type: 'verentis:command:result';
+    sessionId: string;
+    requestId: string;
+    commandId: string;
+    error?: string;
+}
 /**
  * A message from the workspace (typically an agent acting for the user) on a channel the app declares in
  * its manifest `spec.messages`. Handled with `bridge.onHostMessage(channel, handler)`.
@@ -325,6 +677,36 @@ interface VerentisThemeMessage extends VerentisMessage {
     colorScheme: 'light' | 'dark';
     variables?: Record<string, string>;
 }
+/** Host → app chat live-hint relay messages (bound to the bridge session). */
+interface VerentisChatSubscribedMessage extends VerentisMessage {
+    type: 'verentis:chat:subscribed';
+    sessionId: string;
+    status: string;
+}
+interface VerentisChatChangedMessage extends VerentisMessage {
+    type: 'verentis:chat:changed';
+    sessionId: string;
+    hint: {
+        conversationId: string;
+        highWatermark: number;
+        kinds: string[];
+    };
+}
+interface VerentisChatConnectionMessage extends VerentisMessage {
+    type: 'verentis:chat:connection';
+    sessionId: string;
+    status: string;
+}
+interface VerentisChatErrorMessage extends VerentisMessage {
+    type: 'verentis:chat:error';
+    sessionId: string;
+    reason: string;
+}
+/** App → host chat relay subscription messages. */
+interface VerentisChatSubscriptionMessage extends VerentisMessage {
+    type: 'verentis:chat:subscribe' | 'verentis:chat:unsubscribe';
+    sessionId: string;
+}
 interface VerentisReadyMessage extends VerentisMessage {
     type: 'verentis:ready';
     capabilities?: string[];
@@ -352,8 +734,8 @@ interface VerentisDirtyMessage extends VerentisMessage {
     type: 'verentis:dirty';
     isDirty: boolean;
 }
-type HostToAppMessage = VerentisInitMessage | VerentisActionInvokeMessage | VerentisHostMessage | VerentisTokenRefreshedMessage | VerentisFileChangedMessage | VerentisThemeMessage | VerentisWopiResponse | NativeCollaborationResponse;
-type AppToHostMessage = VerentisReadyMessage | VerentisActionsSetMessage | VerentisActionResultMessage | VerentisHostReplyMessage | VerentisTokenRefreshMessage | VerentisNavigateMessage | VerentisResizeMessage | VerentisTitleMessage | VerentisDirtyMessage | VerentisWopiRequest | NativeCollaborationRequest;
+type HostToAppMessage = VerentisInitMessage | VerentisActionInvokeMessage | VerentisCommandInvokeMessage | VerentisHostMessage | VerentisTokenRefreshedMessage | VerentisFileChangedMessage | VerentisThemeMessage | VerentisWopiResponse | NativeCollaborationResponse | VerentisChatSubscribedMessage | VerentisChatChangedMessage | VerentisChatConnectionMessage | VerentisChatErrorMessage;
+type AppToHostMessage = VerentisReadyMessage | VerentisActionsSetMessage | VerentisActionResultMessage | VerentisCommandsUpdateMessage | VerentisCommandResultMessage | VerentisHostReplyMessage | VerentisTokenRefreshMessage | VerentisNavigateMessage | VerentisResizeMessage | VerentisTitleMessage | VerentisDirtyMessage | VerentisWopiRequest | NativeCollaborationRequest | VerentisChatSubscriptionMessage;
 type AppSurface = 'file' | 'workspace';
 interface AppContextBase {
     application?: AppApplicationContext;
@@ -366,6 +748,8 @@ interface AppContextBase {
         authorizationGeneration?: string;
         wopiEnabled?: boolean;
     };
+    /** In-app location the host asks the app to open (for example `/conversations/<id>` from a notification). */
+    location?: string;
 }
 interface AppApplicationContext {
     manifestPath: string;
@@ -739,8 +1123,10 @@ interface ApplicationManifest {
     spec: ApplicationSpec;
 }
 interface ManifestMetadata {
-    name: string;
-    displayName?: string;
+    /** Package identity (`metadata.id`). */
+    id: string;
+    /** Optional human-friendly label (`metadata.name`); displays fall back to {@link id}. */
+    name?: string;
     description?: string;
     icon?: string;
     version?: string;
@@ -823,7 +1209,7 @@ interface ApplicationSpec {
     scopes?: string[];
     /** Declarative install map: where packaged files land in the workspace VFS. */
     install?: InstallDirective[];
-    /** Where the app-record (manifest node) is anchored. Default `/applications/{name}`. */
+    /** Where the app-record (manifest node) is anchored. Default `/applications/{id}`. */
     installRoot?: string;
     /** Default display behavior inherited by entry points. */
     display?: ApplicationDisplayOptions;
@@ -834,7 +1220,7 @@ interface ApplicationSpec {
     launch?: ApplicationLaunchConfig;
     /**
      * Workspace settings and secrets this app requires. Declared settings are auto-registered
-     * in the workspace settings store under `{metadata.name}.{key}` and surfaced in the
+     * in the workspace settings store under `{metadata.id}.{key}` and surfaced in the
      * settings UI. Secret values never reach browser contexts.
      */
     settings?: SettingDeclaration[];
@@ -843,11 +1229,11 @@ interface ApplicationSpec {
 type SettingDeclarationType = 'string' | 'number' | 'boolean' | 'select' | 'file';
 /**
  * A workspace setting or secret an application/engine manifest requires. The platform
- * auto-creates a matching setting definition (namespaced `{manifest-name}.{key}`) so
+ * auto-creates a matching setting definition (namespaced `{metadata.id}.{key}`) so
  * workspace admins can provide the value; engines receive values at run time.
  */
 interface SettingDeclaration {
-    /** Short key; stored namespaced as `{metadata.name}.{key}` in the settings store. */
+    /** Short key; stored namespaced as `{metadata.id}.{key}` in the settings store. */
     key: string;
     /** Optional environment variable name injected into engine runs (e.g. `MY_API_KEY`). */
     env?: string;
@@ -931,6 +1317,62 @@ interface RunFileOptions {
     arguments?: string[];
     /** Structured parameters passed to the engine; serialized to JSON for the platform. */
     parameters?: Record<string, unknown>;
+    /** Idempotency key: requests with the same key from the same caller resolve to one execution. */
+    invocationKey?: string;
+}
+/** Value type of a declared script argument. */
+type ScriptArgumentType = 'string' | 'integer' | 'number' | 'boolean' | 'date';
+/** One declared script argument (an option such as `--customer-id`, or a positional). */
+interface ScriptArgumentDefinition {
+    /** Canonical name, e.g. `customer-id`. Structured parameters with this key become the option. */
+    name: string;
+    kind: 'option' | 'positional';
+    /** Option flags, e.g. `["--customer-id", "-c"]`. */
+    flags?: string[];
+    type: ScriptArgumentType;
+    required: boolean;
+    repeatable: boolean;
+    default?: unknown;
+    choices?: Array<string | number>;
+    minimum?: number;
+    maximum?: number;
+    help?: string;
+    label?: string;
+    metavar?: string;
+    /** Option may appear without a value. */
+    valueOptional?: boolean;
+    /** Flag that sets a boolean option to false, e.g. `--no-cache`. */
+    negation?: string;
+    /** Value a boolean flag stores when present. */
+    presentValue?: boolean;
+}
+/**
+ * A script's exported argument declaration (`<script>.arguments.json`, schema
+ * `verentis.io/script-arguments/v1`). The platform validates runs against it and the workspace prompts
+ * for missing required arguments.
+ */
+interface ScriptArgumentDescriptor {
+    schema: 'verentis.io/script-arguments/v1';
+    script?: string;
+    /** SHA-256 of the script the descriptor was exported from. */
+    sourceSha256?: string;
+    description?: string;
+    /** `options`: structured parameters named like an option are passed as that option. */
+    parameters?: 'options';
+    /** A parameter that selects a sibling script with its own descriptor. */
+    variants?: {
+        parameter: string;
+        scripts: Record<string, string>;
+    };
+    arguments: ScriptArgumentDefinition[];
+    exclusiveGroups?: Array<{
+        required: boolean;
+        arguments: string[];
+    }>;
+}
+/** Options for reading a script's argument declaration. */
+interface ScriptArgumentsOptions {
+    branch?: string;
 }
 /** Options for executing a specific engine (optionally against a file). */
 interface ExecuteEngineOptions {
@@ -1134,7 +1576,8 @@ declare class ApiError extends Error {
     readonly detail: string;
     readonly title?: string | undefined;
     readonly code?: string | undefined;
-    constructor(status: number, detail: string, title?: string | undefined, code?: string | undefined);
+    readonly retryAfterMs?: number | undefined;
+    constructor(status: number, detail: string, title?: string | undefined, code?: string | undefined, retryAfterMs?: number | undefined);
 }
 
 /**
@@ -1200,6 +1643,8 @@ declare class HttpTransport {
     private buildUrl;
 }
 
+/** Schema of exported script argument descriptors. */
+declare const SCRIPT_ARGUMENTS_SCHEMA = "verentis.io/script-arguments/v1";
 /** Returns true once an execution has reached a final state. */
 declare function isTerminalStatus(status: ExecutionStatus): boolean;
 /**
@@ -1221,6 +1666,11 @@ declare class ExecutionsModule {
      * (e.g. invoking an engine tool without a script).
      */
     execute(engineId: string, options?: ExecuteEngineOptions): Promise<Execution>;
+    /**
+     * Read the arguments a script declares (its exported `<script>.arguments.json`), e.g. to build a form
+     * before {@link run}. Returns `null` for scripts that declare none. Reading never runs the script.
+     */
+    getArguments(filePath: string, options?: ScriptArgumentsOptions): Promise<ScriptArgumentDescriptor | null>;
     /** Get an execution by id. */
     get(id: string, options?: ExecutionScopedOptions): Promise<Execution>;
     /** List workspace executions with optional engine, file, lifecycle, and time filters. */
@@ -1343,8 +1793,8 @@ declare class ResourcesModule {
  * over the Verentis settings API (`/v1/settings`).
  *
  * The app token must carry the matching scopes, declared in the manifest's `spec.permissions`:
- * `fabric.setting.read` (get), `fabric.setting.read-all` (list), `fabric.setting.update` (set)
- * and `fabric.setting.delete` (reset).
+ * `setting.read` (get, list), `setting.write` (set)
+ * and `setting.delete` (reset).
  *
  * Secret values are server-only: for browser callers the platform always returns `value: null`
  * for secrets while `hasValue` reports whether one is configured. Manifest-declared settings
@@ -1365,9 +1815,9 @@ declare class SettingsModule {
      * This never returns value content and also finds values retained after a definition is removed.
      */
     presence(keys: string[], options?: SettingsScopedOptions): Promise<SettingPresence[]>;
-    /** Upsert a setting value by its full key. Requires the `fabric.setting.update` scope. */
+    /** Upsert a setting value by its full key. Requires the `setting.write` scope. */
     set(key: string, value: unknown, options?: SettingsScopedOptions): Promise<void>;
-    /** Delete a stored value (reverting to the definition default). Requires `fabric.setting.delete`. */
+    /** Delete a stored value (reverting to the definition default). Requires `setting.delete`. */
     reset(key: string, options?: SettingsScopedOptions): Promise<void>;
     /**
      * A view of this module where every key is auto-prefixed with `{namespace}.` — the platform's
@@ -1390,126 +1840,36 @@ interface NamespacedSettings {
     reset(key: string, options?: SettingsScopedOptions): Promise<void>;
 }
 
-interface EmailScopedOptions {
+interface NotificationSendOptions {
     workspaceId?: string;
-    branch?: 'main';
-}
-interface EmailHistoryOptions extends EmailScopedOptions {
-    recordId?: string;
     installationId?: string;
-}
-interface EmailPurpose {
-    name: string;
-    templateId: string;
-    maximumRecipients: number;
-    maximumAttachmentBytes: number;
-    allowsOpenTracking: boolean;
-    allowsClickTracking: boolean;
-    senderRequirement: 'workspace-owned' | 'managed-or-workspace';
-}
-interface EmailSenderGrant {
-    purpose: string;
-    senderId: string;
-    senderIdentityDigest?: string;
-}
-interface EmailConsentPreview {
-    installationId: string;
-    workspaceId: string;
-    accountId: string;
-    packageId: string;
-    packageVersionId: string;
-    publisherId: string;
-    publisherName: string;
-    version: string;
-    treeDigest: string;
-    signingKeyId: string;
-    installPath: string;
-    branch: string;
-    candidateDigest: string;
-    declaration: {
-        purposes: EmailPurpose[];
-        maximumMessagesPerHour: number;
-        permissions: string[];
-        scopes: string[];
-        manifestDigest: string;
-    };
-}
-interface EmailConsent {
-    installationId: string;
-    candidateDigest: string;
-    enabled: boolean;
-    allowOpenTracking: boolean;
-    allowClickTracking: boolean;
-    approvedBy: string;
-    updatedAt: string;
-    senderGrants: EmailSenderGrant[] | null;
-}
-interface EmailConsentOptions {
-    senderGrants: EmailSenderGrant[];
-    allowOpenTracking?: boolean;
-    allowClickTracking?: boolean;
-}
-interface EmailSenderIdentity {
-    id: string;
-    mode: 'managed' | 'custom';
-    displayName: string;
-    address: string;
-}
-interface EmailArtifactOutcome {
-    artifactId: string;
-    sha256: string;
-    byteLength: number;
-    fileName: string;
-}
-interface EmailDispatchOptions extends EmailScopedOptions {
-    installationId: string;
-    recordId: string;
-    purpose: string;
-    templateId: string;
-    senderId: string;
-    recipients: string[];
-    artifactIds: string[];
+    typeKey: string;
     idempotencyKey: string;
-    replyTo?: string;
+    userIds?: string[];
+    audienceScope?: string;
+    emailAddresses?: string[];
+    parameters: Record<string, unknown>;
 }
-interface EmailDispatchOutcome {
+interface NotificationRequestOptions {
+    workspaceId?: string;
+    installationId?: string;
+}
+interface NotificationRequestStatus {
     id: string;
-    status: 'accepted' | 'delivered' | 'failed' | 'unknown';
+    status: string;
+    outcomeCode: string | null;
     createdAt: string;
-    failureCode?: string | null;
-    recordId: string;
-    installationId: string;
-    branch: 'main';
-    purpose: string;
-    templateId: string;
-    events: EmailDeliveryEvidence[];
-}
-interface EmailDeliveryEvidence {
-    type: 'processed' | 'deferred' | 'delivered' | 'failed' | 'complaint' | 'unsubscribe' | 'open' | 'click';
-    occurredAt: string;
+    updatedAt: string;
 }
 
-/** Signed-package transactional email. Dispatch never accepts HTML, From or a browser invoice snapshot. */
-declare class EmailModule {
+/** Send app notifications through the installed package's registered catalogue. */
+declare class NotificationsModule {
     private readonly http;
     private readonly workspaceId?;
     constructor(http: HttpTransport, workspaceId?: string | undefined);
-    preview(installationId: string, options?: EmailScopedOptions): Promise<EmailConsentPreview>;
-    consents(options?: EmailScopedOptions): Promise<EmailConsent[]>;
-    /** Approve exactly the reviewed signed candidate; tracking stays off unless explicitly opted in. */
-    consent(preview: EmailConsentPreview, approval: true, options: EmailConsentOptions): Promise<EmailConsent>;
-    revoke(consent: EmailConsent, options?: EmailScopedOptions): Promise<EmailConsent>;
-    senders(options?: EmailScopedOptions): Promise<EmailSenderIdentity[]>;
-    invoicePdf(recordId: string, installationId: string, options?: EmailScopedOptions): Promise<EmailArtifactOutcome>;
-    /** Authenticated immutable bytes; no public URL. The caller owns any local object URL it creates. */
-    artifactContent(artifactId: string, options?: EmailScopedOptions): Promise<Blob>;
-    /** A stable key binds this exact request. After a lost response inspect status; never automatically resend. */
-    dispatch(options: EmailDispatchOptions): Promise<EmailDispatchOutcome>;
-    outcome(id: string, options?: EmailScopedOptions): Promise<EmailDispatchOutcome>;
-    history(options?: EmailHistoryOptions): Promise<EmailDispatchOutcome[]>;
-    status(id: string, options?: EmailScopedOptions): Promise<EmailDispatchOutcome>;
-    private workspace;
-    private mainBranch;
+    send(options: NotificationSendOptions): Promise<NotificationRequestStatus>;
+    request(id: string, options?: NotificationRequestOptions): Promise<NotificationRequestStatus>;
+    private requireWorkspaceId;
 }
 
 type BusinessOperation = 'save-record' | 'archive-record' | 'delete-record' | 'restore-record' | 'close-period' | 'issue-invoice' | 'credit-invoice' | 'post-payment' | 'reverse-payment' | 'post-journal' | 'reverse-journal' | 'post-expense' | 'reverse-expense';
@@ -1643,6 +2003,111 @@ declare class BusinessModule {
     private headers;
 }
 
+/**
+ * Workspace chat (`/v1/chat`). Framework independent; the workspace and caller come from the token. In an installed
+ * app, {@link subscribeChanges} relays identifier-only live hints over the host's existing realtime connection
+ * (requires the approved `chat.read` permission); hints are best effort, so reconcile with {@link events} after
+ * reconnecting and on resume.
+ */
+declare class ChatModule {
+    private readonly http;
+    private readonly bridge;
+    private readonly executions?;
+    constructor(http: HttpTransport, bridge?: Bridge | null, executions?: ExecutionsModule | undefined);
+    listConversations(options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<ChatPage<ConversationSummary>>;
+    createConversation(options: CreateConversationOptions): Promise<Conversation>;
+    /** Opens (or returns the existing) direct conversation with one participant. */
+    openDirect(participant: ChatParticipant): Promise<Conversation>;
+    getConversation(conversationId: string): Promise<Conversation>;
+    updateConversation(conversationId: string, changes: {
+        title?: string;
+        topic?: string;
+        archived?: boolean;
+    }): Promise<Conversation>;
+    join(conversationId: string): Promise<Conversation>;
+    listPublicChannels(options?: {
+        query?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<ChatPage<PublicChannel>>;
+    listMembers(conversationId: string): Promise<ChatPage<Member>>;
+    addMembers(conversationId: string, participants: ChatParticipant[], role?: 'member' | 'admin'): Promise<Conversation>;
+    /** Removes a member; pass yourself to leave. */
+    removeMember(conversationId: string, participant: ChatParticipant): Promise<void>;
+    changeRole(conversationId: string, participant: ChatParticipant, role: MemberRole): Promise<ChatPage<Member>>;
+    listMessages(conversationId: string, options?: {
+        before?: string;
+        limit?: number;
+    }): Promise<MessagePage>;
+    getMessage(conversationId: string, messageId: string): Promise<ChatMessage>;
+    send(conversationId: string, parts: MessagePartInput[], options?: SendMessageOptions): Promise<ChatMessage>;
+    /** Sends Markdown text (rendered without raw HTML by every reader). */
+    sendText(conversationId: string, markdown: string, options?: SendMessageOptions): Promise<ChatMessage>;
+    /** Edits your own message; pass the revision you saw to reject a concurrent edit. */
+    edit(conversationId: string, messageId: string, parts: MessagePartInput[], options?: {
+        revision?: number;
+    }): Promise<ChatMessage>;
+    delete(conversationId: string, messageId: string): Promise<ChatMessage>;
+    /**
+     * Durable changes after a position: `afterSeq` is a snapshot's `highWatermark` (or the last sequence you applied);
+     * `after` is the `next` cursor of a previous page.
+     */
+    events(conversationId: string, options?: {
+        after?: string;
+        afterSeq?: number;
+        limit?: number;
+    }): Promise<EventPage>;
+    /** Marks messages read through a sequence; never moves back and never past what the server has. */
+    markRead(conversationId: string, readThroughSeq: number): Promise<ReadState>;
+    setPreferences(conversationId: string, preferences: {
+        muted?: boolean;
+        attention?: AttentionLevel;
+    }): Promise<ConversationPreferences>;
+    /** People in your workspace (name and avatar only). */
+    searchPeople(options?: {
+        query?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<ChatPage<ChatPerson>>;
+    listBots(): Promise<ChatPage<ChatBot>>;
+    /** Workspace managers (`chat.manage`) decide whether a bot may message people directly. */
+    updateBotSettings(botId: string, settings: {
+        directMessages: 'none' | 'workspace';
+    }): Promise<ChatBot>;
+    listCommands(): Promise<ChatPage<ChatCommand>>;
+    /** Validates and records a command invocation, returning the Execution request to run as you. */
+    invokeCommand(conversationId: string, command: string, args?: Record<string, unknown>, options?: {
+        idempotencyKey?: string;
+    }): Promise<ChatCommandInvocation>;
+    /**
+     * Invokes an installed app's command and runs its script with your own authorisation. Retrying with the same
+     * idempotency key reuses the invocation key, so Execution never runs it twice.
+     */
+    runCommand(conversationId: string, command: string, args?: Record<string, unknown>, options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        invocation: ChatCommandInvocation;
+        execution: Execution;
+    }>;
+    /**
+     * Posts as the installed app's bot from a running script. The bot is derived from the script's execution; the
+     * conversation must have added the bot (or, for `userId`, the workspace must allow it to message people).
+     * Retries briefly while Execution's start event is still on its way.
+     */
+    postAsBot(options: BotPostOptions): Promise<{
+        conversationId: string;
+        message: ChatMessage;
+    }>;
+    /**
+     * Subscribes to live change hints through the host (installed apps only). Returns an unsubscribe function.
+     * Hints carry ids only; duplicates and reordering are normal, and hints are lost while disconnected.
+     */
+    subscribeChanges(handlers: ChatSubscriptionHandlers): () => void;
+}
+
 /**
  * The main Verentis SDK client.
  * Provides access to file operations, workspace context, and (in iframe mode)
@@ -1655,8 +2120,9 @@ declare class VerentisClient {
     installations: InstallationsModule;
     resources: ResourcesModule;
     settings: SettingsModule;
-    email: EmailModule;
+    notifications: NotificationsModule;
     business: BusinessModule;
+    chat: ChatModule;
     readonly context: ContextModule;
     readonly bridge: Bridge | null;
     readonly collaboration: NativeCollaborationClient;
@@ -1811,4 +2277,5 @@ declare class BridgeAuth implements AuthStrategy {
  */
 declare function createVerentisClient(options?: VerentisClientOptions): VerentisClient;
 
-export { ApiError, ApiKeyAuth, type AppApplicationContext, type AppContext, type AppSurface, type AppToHostMessage, type ApplicationDisplayOptions, type ApplicationEntryPoint, type ApplicationFileType, type ApplicationLaunchConfig, type ApplicationManifest, type ApplicationSpec, type ArchiveFormat, type AuthOptions, type AuthStrategy, Bridge, BridgeAuth, type BusinessCommand, type BusinessCommitResult, type BusinessContext, type BusinessLedgerEntry, BusinessModule, type BusinessOperation, type BusinessOutcomeRequest, type BusinessParameters, type BusinessReceivable, type BusinessReceivableTotals, type BusinessReport, type BusinessReportLine, type BusinessReportName, type BusinessSnapshot, type CatalogImage, type CollaborationDocument, type CollaborationDocumentContext, ContextModule, type DeleteFileOptions, type EmailArtifactOutcome, type EmailConsent, type EmailConsentOptions, type EmailConsentPreview, type EmailDeliveryEvidence, type EmailDispatchOptions, type EmailDispatchOutcome, type EmailHistoryOptions, EmailModule, type EmailPurpose, type EmailScopedOptions, type EmailSenderGrant, type EmailSenderIdentity, type EngineFileType, type EngineRuntime, type EngineTool, EnginesModule, type EntryPointInfo, type ExecuteEngineOptions, type Execution, type ExecutionEngine, type ExecutionEngineListOptions, type ExecutionListOptions, type ExecutionLogs, type ExecutionMode, type ExecutionResult, type ExecutionScopedOptions, type ExecutionStatus, type ExecutionTrigger, ExecutionsModule, type ExtractUploadOptions, type FileAppContext, type FileEntry, type FileInfo, FilesModule, type GetFileOptions, HOST_MESSAGE_CHANNEL_PATTERN, type HeaderAction, type HeaderActionHandler, type HeaderActionRegistration, type HeaderActionResult, type HostMessageHandler, type HostToAppMessage, HttpTransport, type Installation, type InstallationDetail, type InstallationGraphOutcomeStatus, type InstallationGraphPackage, type InstallationGraphPreview, type InstallationGraphResult, type InstallationLifecycleResult, type InstallationListOptions, type InstallationMode, type InstallationScopedOptions, type InstallationStatus, InstallationsModule, type InstalledPackageDescriptor, type InstalledPackagePayload, type ManifestMetadata, type MimeTypeBinding, type MoveFileOptions, type NamespacedSettings, type NativeChangeSet, NativeCollaborationClient, type NativeCollaborationCommand, NativeCollaborationError, type NativeCollaborationRequest, type NativeCollaborationResponse, type NativeElement, type NativeFile, type NativeParticipant, type NativePointer, type NativeSaveReceipt, type NativeSaveResult, type NativeScene, type NativeSnapshot, type NavigateOptions, type NodeFileContent, type NodeFileMetadata, type NodeFileOptions, type OAuthConfig, type PackageDependency, type PagedResult, type PreviewInstallationOptions, type ReadArchiveOptions, type RequestOptions, type ResolveInstallationOptions, type ResourceMimeTypeBinding, type ResourceRegistration, type ResourceScopedOptions, ResourcesModule, type RunFileOptions, type SandboxOptions, type SettingDeclaration, type SettingDeclarationType, type SettingGroup, type SettingItem, type SettingOption, type SettingPresence, SettingsModule, type SettingsScopedOptions, TokenAuth, type TokenGrant, type TokenInfo, type UpdateInstallationOptions, type VerentisActionInvokeMessage, type VerentisActionResultMessage, type VerentisActionsSetMessage, VerentisClient, type VerentisClientOptions, type VerentisDirtyMessage, type VerentisFileChangedMessage, type VerentisHostMessage, type VerentisHostReplyMessage, type VerentisInitMessage, type VerentisMessage, type VerentisNavigateMessage, type VerentisReadyMessage, type VerentisResizeMessage, type VerentisThemeMessage, type VerentisTitleMessage, type VerentisTokenRefreshMessage, type VerentisTokenRefreshedMessage, type VerentisWopiRequest, type VerentisWopiResponse, type WaitOptions, type WopiContinuation, type WopiLaunch, type WopiSaveCheckpoint, type WopiSaveStatus, type WorkspaceAppContext, type WorkspaceInfo, type WriteFileOptions, type WriteNodeFileOptions, createVerentisClient, exactHttpsOrigin, findBestMatch, isDurableSaveConfirmed, isHeaderAction, isNativeSaveResult, isNativeSnapshot, isTerminalStatus, isTrustedMessage, matchMimeType, validateCollaborationDocument, validateNativeCommand };
+export { APP_COMMANDS_CAPABILITY, APP_COMMAND_BATCH_SIZE, APP_COMMAND_ID_PATTERN, ApiError, ApiKeyAuth, Bridge, BridgeAuth, BusinessModule, ChatModule, ContextModule, EnginesModule, ExecutionsModule, FilesModule, HOST_MESSAGE_CHANNEL_PATTERN, HttpTransport, InstallationsModule, NativeCollaborationClient, NativeCollaborationError, NotificationsModule, ResourcesModule, SCRIPT_ARGUMENTS_SCHEMA, SettingsModule, TokenAuth, VerentisClient, createVerentisClient, exactHttpsOrigin, findBestMatch, isAppCommand, isDurableSaveConfirmed, isHeaderAction, isNativeSaveResult, isNativeSnapshot, isTerminalStatus, isTrustedMessage, matchMimeType, validateCollaborationDocument, validateNativeCommand };
+export type { AppApplicationContext, AppCommand, AppCommandHandler, AppCommandRegistration, AppContext, AppSurface, AppToHostMessage, ApplicationDisplayOptions, ApplicationEntryPoint, ApplicationFileType, ApplicationLaunchConfig, ApplicationManifest, ApplicationSpec, ArchiveFormat, AttentionLevel, AuthOptions, AuthStrategy, BotPostOptions, BusinessCommand, BusinessCommitResult, BusinessContext, BusinessLedgerEntry, BusinessOperation, BusinessOutcomeRequest, BusinessParameters, BusinessReceivable, BusinessReceivableTotals, BusinessReport, BusinessReportLine, BusinessReportName, BusinessSnapshot, CatalogImage, ChatBot, ChatChangeHint, ChatCommand, ChatCommandArgument, ChatCommandInvocation, ChatConnectionStatus, ChatMessage, ChatPage, ChatParticipant, ChatPerson, ChatSubscriptionHandlers, CollaborationDocument, CollaborationDocumentContext, Conversation, ConversationEvent, ConversationKind, ConversationPreferences, ConversationSummary, ConversationVisibility, CreateConversationOptions, DeleteFileOptions, EngineFileType, EngineRuntime, EngineTool, EntryPointInfo, EventPage, ExecuteEngineOptions, Execution, ExecutionEngine, ExecutionEngineListOptions, ExecutionListOptions, ExecutionLogs, ExecutionMode, ExecutionResult, ExecutionScopedOptions, ExecutionStatus, ExecutionTrigger, ExtractUploadOptions, FileAppContext, FileEntry, FileInfo, GetFileOptions, HeaderAction, HeaderActionHandler, HeaderActionRegistration, HeaderActionResult, HistoryPolicy, HostMessageHandler, HostToAppMessage, Installation, InstallationDetail, InstallationGraphOutcomeStatus, InstallationGraphPackage, InstallationGraphPreview, InstallationGraphResult, InstallationLifecycleResult, InstallationListOptions, InstallationMode, InstallationScopedOptions, InstallationStatus, InstalledPackageDescriptor, InstalledPackagePayload, ManifestMetadata, Member, MemberRole, Membership, MessagePage, MessagePart, MessagePartInput, MimeTypeBinding, MoveFileOptions, NamespacedSettings, NativeChangeSet, NativeCollaborationCommand, NativeCollaborationRequest, NativeCollaborationResponse, NativeElement, NativeFile, NativeParticipant, NativePointer, NativeSaveReceipt, NativeSaveResult, NativeScene, NativeSnapshot, NavigateOptions, NodeFileContent, NodeFileMetadata, NodeFileOptions, NotificationRequestOptions, NotificationRequestStatus, NotificationSendOptions, OAuthConfig, PackageDependency, PagedResult, PreviewInstallationOptions, PublicChannel, ReadArchiveOptions, ReadState, ReplyPreview, RequestOptions, ResolveInstallationOptions, ResourceMimeTypeBinding, ResourceRegistration, ResourceScopedOptions, RunFileOptions, SandboxOptions, ScriptArgumentDefinition, ScriptArgumentDescriptor, ScriptArgumentType, ScriptArgumentsOptions, SendMessageOptions, SettingDeclaration, SettingDeclarationType, SettingGroup, SettingItem, SettingOption, SettingPresence, SettingsScopedOptions, TokenGrant, TokenInfo, UpdateInstallationOptions, VerentisActionInvokeMessage, VerentisActionResultMessage, VerentisActionsSetMessage, VerentisClientOptions, VerentisCommandInvokeMessage, VerentisCommandResultMessage, VerentisCommandsUpdateMessage, VerentisDirtyMessage, VerentisFileChangedMessage, VerentisHostMessage, VerentisHostReplyMessage, VerentisInitMessage, VerentisMessage, VerentisNavigateMessage, VerentisReadyMessage, VerentisResizeMessage, VerentisThemeMessage, VerentisTitleMessage, VerentisTokenRefreshMessage, VerentisTokenRefreshedMessage, VerentisWopiRequest, VerentisWopiResponse, WaitOptions, WopiContinuation, WopiLaunch, WopiSaveCheckpoint, WopiSaveStatus, WorkspaceAppContext, WorkspaceInfo, WriteFileOptions, WriteNodeFileOptions };