@verentis/sdk 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -26,6 +26,195 @@ interface HeaderActionRegistration {
 type HeaderActionHandler = () => void | HeaderActionResult | Promise<void | HeaderActionResult>;
 declare function isHeaderAction(value: unknown): value is HeaderAction;
 
+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>;
+/** Channel names declared in the manifest `spec.messages`. */
+declare const HOST_MESSAGE_CHANNEL_PATTERN: RegExp;
+type BridgeListener = (data: HostToAppMessage) => void;
+/**
+ * PostMessage bridge for communication between an app (iframe) and the
+ * workspace host. Handles the initialization handshake, token lifecycle,
+ * and app-to-host events (navigate, resize, dirty, etc.).
+ */
+declare class Bridge {
+    private readonly expectedHostOrigin?;
+    private listeners;
+    private _initResolve;
+    private _initReject;
+    private _initTimer;
+    private _initPromise;
+    private _hostOrigin;
+    private _messageHandler;
+    private _destroyed;
+    private sessionId;
+    private actions;
+    private requests;
+    private hostMessageHandlers;
+    private hostMessageRequests;
+    private wopiRequests;
+    private collaborationRequests;
+    constructor(expectedHostOrigin?: string | undefined);
+    /** Post `verentis:ready` to the host to start the handshake */
+    sendReady(capabilities?: string[]): void;
+    /** Wait for the host to send `verentis:init` with context and token */
+    waitForInit(): Promise<{
+        context: AppContext;
+        token: TokenInfo;
+    }>;
+    /** Get the host origin (available after init) */
+    get hostOrigin(): string | null;
+    /** Send a message to the host */
+    postToHost(message: AppToHostMessage): void;
+    /**
+     * Navigate to another location in the workspace.
+     *
+     * @param path A workspace file path (e.g. `/reports/q1.json`) or an absolute
+     *   http(s) URL. External URLs require the app to declare the
+     *   `navigation:external` capability in its manifest.
+     * @param options Navigation options. Set `newTab: true` to open the target in
+     *   a new browser tab instead of the current one.
+     */
+    navigate(path: string, options?: NavigateOptions): void;
+    /** Request iframe resize */
+    resize(height: number): void;
+    /** Update the title displayed by the host */
+    setTitle(title: string): void;
+    /** Signal unsaved changes to the host */
+    setDirty(isDirty: boolean): void;
+    /** The trusted parent selects the approved installation, document and action. */
+    requestWopiLaunch(): Promise<WopiLaunch>;
+    /** Recover only the target selected by a completed server-owned derived operation. */
+    requestWopiContinuation(): Promise<WopiContinuation>;
+    getWopiStatus(): Promise<WopiSaveStatus>;
+    requestWopiSave(generation: number): Promise<WopiSaveCheckpoint>;
+    closeWopiSession(): Promise<void>;
+    private requestWopi;
+    requestNativeCollaboration(command: NativeCollaborationCommand): Promise<unknown>;
+    registerAction(descriptor: HeaderAction, handler: HeaderActionHandler): HeaderActionRegistration;
+    private publishActions;
+    private invokeAction;
+    /**
+     * Handle messages the workspace sends on a channel declared in the manifest `spec.messages` — for
+     * example an agent asking the open app to select a record. The handler's return value is the reply;
+     * a thrown error is reported back as the failure. May be called before the init handshake.
+     */
+    onHostMessage(channel: string, handler: HostMessageHandler): () => void;
+    private receiveHostMessage;
+    /** Subscribe to a specific message type from the host */
+    on(type: BridgeEventType, listener: BridgeListener): () => void;
+    /** Clean up event listeners */
+    destroy(): void;
+    private handleMessage;
+}
+
+interface NativeElement {
+    id: string;
+    version: number;
+    versionNonce?: number;
+    isDeleted?: boolean;
+    [key: string]: unknown;
+}
+interface NativeFile {
+    id: string;
+    dataURL: string;
+    mimeType: string;
+    created: number;
+    lastRetrieved?: number;
+}
+interface NativeScene {
+    elements: NativeElement[];
+    files: Record<string, NativeFile>;
+    appState: Record<string, unknown>;
+}
+interface NativePointer {
+    x: number;
+    y: number;
+}
+interface NativeParticipant {
+    id: string;
+    name: string;
+    readOnly: boolean;
+    pointer: NativePointer | null;
+    /** `agent` marks an agent acting on behalf of a user (same principal, separate connection). */
+    kind?: 'user' | 'agent';
+}
+interface NativeSnapshot {
+    sequence: number;
+    savedSequence: number;
+    revision: string;
+    readOnly: boolean;
+    scene: NativeScene;
+    participants: NativeParticipant[];
+}
+interface NativeSaveReceipt {
+    generation: number;
+    correlation: string;
+    revision: string;
+}
+interface NativeSaveResult extends NativeSnapshot {
+    receipt: NativeSaveReceipt;
+}
+interface NativeChangeSet {
+    operationId: string;
+    changes: Array<{
+        id: string;
+        expectedVersion: number | null;
+        element: NativeElement | null;
+    }>;
+    files?: Record<string, NativeFile>;
+    appState?: Record<string, unknown>;
+    appStateExpectedSequence?: number;
+}
+type NativeCollaborationCommand = {
+    operation: 'join' | 'snapshot' | 'close';
+} | {
+    operation: 'apply';
+    changes: NativeChangeSet;
+} | {
+    operation: 'presence';
+    pointer: NativePointer | null;
+} | {
+    operation: 'save';
+    generation: number;
+    correlation: string;
+};
+interface NativeCollaborationRequest {
+    type: 'verentis:collaboration:request';
+    version: 1;
+    sessionId: string;
+    requestId: string;
+    command: NativeCollaborationCommand;
+}
+interface NativeCollaborationResponse {
+    type: 'verentis:collaboration:response';
+    version: 1;
+    sessionId: string;
+    requestId: string;
+    result?: NativeSnapshot | NativeSaveResult | null;
+    error?: string;
+    code?: string;
+}
+declare class NativeCollaborationError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+declare function isNativeSnapshot(value: unknown): value is NativeSnapshot;
+declare function isNativeSaveResult(value: unknown): value is NativeSaveResult;
+declare function validateNativeCommand(command: NativeCollaborationCommand): void;
+/** Native authority is always selected by the installed workspace host, never by the iframe. */
+declare class NativeCollaborationClient {
+    private readonly bridge;
+    constructor(bridge: Bridge | null);
+    private snapshotRequest;
+    join(): Promise<NativeSnapshot>;
+    snapshot(): Promise<NativeSnapshot>;
+    apply(changes: NativeChangeSet): Promise<NativeSnapshot>;
+    presence(value: NativePointer | null): Promise<NativeSnapshot>;
+    save(generation: number, correlation: string): Promise<NativeSaveResult>;
+    close(): Promise<void>;
+}
+
 interface VerentisMessage {
     type: `verentis:${string}`;
     version: 1;
@@ -57,28 +246,73 @@ interface VerentisActionResultMessage extends VerentisMessage {
     result?: HeaderActionResult;
     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)`.
+ */
+interface VerentisHostMessage extends VerentisMessage {
+    type: 'verentis:host:message';
+    sessionId: string;
+    requestId: string;
+    channel: string;
+    payload?: unknown;
+}
+interface VerentisHostReplyMessage extends VerentisMessage {
+    type: 'verentis:host:reply';
+    sessionId: string;
+    requestId: string;
+    channel: string;
+    result?: unknown;
+    error?: string;
+}
 interface VerentisTokenRefreshedMessage extends VerentisMessage {
     type: 'verentis:token:refreshed';
     requestId: string;
     token: TokenInfo;
 }
-/** Single-use credential for the installation's independently registered backend. */
-interface AppBackendCredential {
-    delegationId: string;
-    backendClientId: string;
-    launchCredential: string;
-    expiresAt: string;
+/** Nonsecret active-document metadata. CODE already holds its own scoped credential. */
+interface WopiContinuation {
+    sessionId: string;
+    workspaceId: string;
+    branch: string;
+    nodeId: string;
+    accessTokenTtl: number;
+    fileId: string;
+    format: string;
+    readOnly: boolean;
+    name: string;
 }
-interface VerentisBackendCredentialRequest extends VerentisMessage {
-    type: 'verentis:backend:request';
+/** Initial document-scoped collaboration authority, never a platform OAuth credential. */
+interface WopiLaunch extends WopiContinuation {
+    action: string;
+    accessToken: string;
+    editorOrigin: string;
+    wopiSource: string;
+}
+interface WopiSaveCheckpoint {
+    generation: number;
+    correlation: string;
+    revision?: string | null;
+}
+interface WopiSaveStatus {
+    state: string;
+    revision: string;
+    readOnly: boolean;
+    receipt: WopiSaveCheckpoint | null;
+    continuationAvailable?: boolean;
+}
+interface VerentisWopiRequest extends VerentisMessage {
+    type: 'verentis:wopi:request';
     requestId: string;
     sessionId: string;
+    operation: 'launch' | 'status' | 'save' | 'close' | 'continue';
+    generation?: number;
 }
-interface VerentisBackendCredentialResponse extends VerentisMessage {
-    type: 'verentis:backend:response';
+interface VerentisWopiResponse extends VerentisMessage {
+    type: 'verentis:wopi:response';
     requestId: string;
     sessionId: string;
-    credential?: AppBackendCredential;
+    result?: WopiLaunch | WopiContinuation | WopiSaveCheckpoint | WopiSaveStatus | null;
     error?: string;
 }
 interface VerentisFileChangedMessage extends VerentisMessage {
@@ -118,19 +352,26 @@ interface VerentisDirtyMessage extends VerentisMessage {
     type: 'verentis:dirty';
     isDirty: boolean;
 }
-type HostToAppMessage = VerentisInitMessage | VerentisActionInvokeMessage | VerentisTokenRefreshedMessage | VerentisFileChangedMessage | VerentisThemeMessage | VerentisBackendCredentialResponse;
-type AppToHostMessage = VerentisReadyMessage | VerentisActionsSetMessage | VerentisActionResultMessage | VerentisTokenRefreshMessage | VerentisNavigateMessage | VerentisResizeMessage | VerentisTitleMessage | VerentisDirtyMessage | VerentisBackendCredentialRequest;
+type HostToAppMessage = VerentisInitMessage | VerentisActionInvokeMessage | VerentisHostMessage | VerentisTokenRefreshedMessage | VerentisFileChangedMessage | VerentisThemeMessage | VerentisWopiResponse | NativeCollaborationResponse;
+type AppToHostMessage = VerentisReadyMessage | VerentisActionsSetMessage | VerentisActionResultMessage | VerentisHostReplyMessage | VerentisTokenRefreshMessage | VerentisNavigateMessage | VerentisResizeMessage | VerentisTitleMessage | VerentisDirtyMessage | VerentisWopiRequest | NativeCollaborationRequest;
 type AppSurface = 'file' | 'workspace';
 interface AppContextBase {
+    application?: AppApplicationContext;
     workspace: WorkspaceInfo;
     entryPoint?: EntryPointInfo;
     apiUrl: string;
     installation?: {
         id: string;
-        backendClientId: string;
-        authorizationGeneration: string;
+        backendClientId?: string;
+        authorizationGeneration?: string;
+        wopiEnabled?: boolean;
     };
 }
+interface AppApplicationContext {
+    manifestPath: string;
+    manifestNodeId: string;
+    branch: string;
+}
 /** Context for an application opened against a workspace file. */
 interface FileAppContext extends AppContextBase {
     surface: 'file';
@@ -225,6 +466,33 @@ interface FileEntry {
     version?: string;
     etag?: string;
     children?: FileEntry[];
+    /** Stable node identity, when supplied by the path metadata API. */
+    nodeId?: string;
+}
+interface NodeFileMetadata {
+    nodeId: string;
+    path: string;
+    name: string;
+    mimeType: string;
+    size?: number | null;
+    /** Unquoted opaque content revision; distinct from a path delete head stamp. */
+    etag: string;
+    version: string;
+    children?: PagedResult<FileEntry>;
+}
+interface NodeFileOptions {
+    branch: string;
+}
+interface NodeFileContent {
+    content: Blob;
+    /** Strong quoted ETag returned by the node-content API. */
+    revision: string;
+}
+interface WriteNodeFileOptions extends NodeFileOptions {
+    content: Blob | string | ArrayBuffer;
+    /** Strong quoted revision, or the unquoted etag returned by getNode. */
+    revision: string;
+    idempotencyKey: string;
 }
 interface GetFileOptions {
     branch?: string;
@@ -237,6 +505,8 @@ interface WriteFileOptions {
     contentType?: string;
     filename?: string;
     branch?: string;
+    /** Atomically require no live file at this path; conflicts return HTTP 412. */
+    createOnly?: boolean;
 }
 interface MoveFileOptions {
     from: string;
@@ -246,6 +516,10 @@ interface MoveFileOptions {
 interface DeleteFileOptions {
     path: string;
     branch?: string;
+    /** Path-binding head stamp, not a node-content revision. */
+    headStamp?: string;
+    idempotencyKey?: string;
+    mode?: 'shallow' | 'deep';
 }
 type ArchiveFormat = 'zip' | 'tgz';
 interface ReadArchiveOptions {
@@ -280,6 +554,64 @@ interface InstalledPackageDescriptor {
     payloads: InstalledPackagePayload[];
 }
 type InstallationMode = 'Extracted' | 'Sealed';
+/** Required dependencies use immutable exact SemVer pins; optional packages are never implicit installs. */
+interface PackageDependency {
+    package: string;
+    version: string;
+    installPath?: string | null;
+    optional?: boolean;
+}
+interface InstallationGraphPackage {
+    packageId: string;
+    packageVersionId: string;
+    publisherId: string;
+    identity: string;
+    publisher: string;
+    version: string;
+    treeDigest: string;
+    artifactFingerprint: string;
+    manifestYaml: string;
+    verifiedSigningKeyKid?: string | null;
+    branch: string;
+    installPath: string;
+    installMode: InstallationMode;
+    reuseInstallationId?: string | null;
+    /** Only a previously Failed exact target can be recovered, after a fresh explicit preview. */
+    retryInstallationId?: string | null;
+    permissions: string[];
+    dependencies: PackageDependency[];
+    /** Conservative destination reservations, including external install-map/seed roots. */
+    installPaths: string[];
+}
+interface InstallationGraphPreview {
+    operationId: string;
+    workspaceId: string;
+    expiresAt: string;
+    fingerprint: string;
+    /** Topological installation order: required dependencies before their dependents. */
+    packages: InstallationGraphPackage[];
+}
+type InstallationGraphOutcomeStatus = 'Pending' | 'Installing' | 'Reused' | 'Installed' | 'InstalledWithError' | 'Failed' | 'NotAttempted';
+interface InstallationGraphResult {
+    operationId: string;
+    status: 'Preview' | 'Accepted' | 'Completed' | 'Rejected' | 'Failed';
+    succeeded: boolean;
+    /** The exact durable preview baseline, also available after a lost preview/install response. */
+    packages: InstallationGraphPackage[];
+    outcomes: {
+        identity: string;
+        status: InstallationGraphOutcomeStatus;
+        installationId?: string | null;
+        error?: string | null;
+    }[];
+    error?: string | null;
+}
+interface PreviewInstallationOptions extends InstallationScopedOptions {
+    packageVersion?: string;
+    installPath?: string;
+    branch?: string;
+    installMode?: InstallationMode;
+}
 type InstallationStatus = 'Pending' | 'Installing' | 'Installed' | 'Updating' | 'Uninstalling' | 'Failed' | 'Uninstalled';
 interface Installation {
     id: string;
@@ -459,6 +791,9 @@ interface ApplicationEntryPoint {
     display?: ApplicationDisplayOptions;
 }
 interface ApplicationSpec {
+    dependencies?: PackageDependency[];
+    /** Publisher-qualified required engine dependency for script-bearing packages. */
+    engine?: string;
     /** Optional iframe UI surface URL. Omit for a headless / file-collection app. */
     entry?: string;
     /** Optional application splash URL. Relative values resolve against the selected iframe entry URL. */
@@ -785,7 +1120,8 @@ declare class ApiError extends Error {
     readonly status: number;
     readonly detail: string;
     readonly title?: string | undefined;
-    constructor(status: number, detail: string, title?: string | undefined);
+    readonly code?: string | undefined;
+    constructor(status: number, detail: string, title?: string | undefined, code?: string | undefined);
 }
 
 /**
@@ -799,6 +1135,8 @@ declare class ContextModule {
     private _file;
     private _entryPoint;
     private _apiUrl;
+    private _application;
+    private _installation;
     /** The current workspace */
     get workspace(): WorkspaceInfo;
     /** The host surface that launched the app */
@@ -813,6 +1151,8 @@ declare class ContextModule {
     get entryPoint(): EntryPointInfo | null;
     /** Whether an entry point context is available */
     get hasEntryPoint(): boolean;
+    get application(): AppApplicationContext | null;
+    get installation(): AppContext['installation'] | null;
     /** Update context from the host's init message */
     setFromAppContext(ctx: AppContext): void;
     /** Set workspace info directly (standalone mode) */
@@ -835,6 +1175,7 @@ declare class HttpTransport {
     constructor(baseUrl: string, auth: AuthStrategy, apiVersion?: string);
     request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
     requestRaw(method: string, path: string, options?: RequestOptions): Promise<Response>;
+    ensureSuccess(response: Response): Promise<void>;
     private buildUrl;
 }
 
@@ -904,6 +1245,12 @@ declare class FilesModule {
      * For directories: returns metadata with children array populated.
      */
     get(path: string, options?: GetFileOptions): Promise<FileEntry>;
+    /** Read metadata by stable node identity on an explicit branch. */
+    getNode(nodeId: string, options: NodeFileOptions): Promise<NodeFileMetadata>;
+    /** Read bytes and their matching content revision in the same response. */
+    readNodeContent(nodeId: string, options: NodeFileOptions): Promise<NodeFileContent>;
+    /** Replace existing node bytes conditionally; never creates or changes path/MIME. */
+    writeNodeContent(nodeId: string, options: WriteNodeFileOptions): Promise<NodeFileMetadata>;
     /**
      * Read the raw content of a file as a Blob.
      */
@@ -927,6 +1274,8 @@ declare class FilesModule {
      * Upload or create a file.
      */
     write(path: string, options: WriteFileOptions): Promise<void>;
+    /** Create without a read-before-write race or overwrite of an existing live file. */
+    create(path: string, options: WriteFileOptions): Promise<void>;
     /**
      * Move or rename a file.
      */
@@ -943,6 +1292,14 @@ declare class InstallationsModule {
     private readonly http;
     private readonly workspaceId?;
     constructor(http: HttpTransport, workspaceId?: string | undefined);
+    /** Resolve canonical publisher/package identity, never the installation's runtime display name. */
+    resolvePackageId(identity: string, options?: InstallationScopedOptions): Promise<string>;
+    /** Resolves the complete required graph without installing anything or granting capabilities. */
+    preview(packageId: string, options?: PreviewInstallationOptions): Promise<InstallationGraphPreview>;
+    /** Explicit, single-use consent to a displayed preview. Never automatically retries accepted installs. */
+    install(preview: InstallationGraphPreview, consent: true): Promise<InstallationGraphResult>;
+    /** Inspect durable outcomes after a failure or lost response instead of resubmitting consent. */
+    graphResult(operationId: string, options?: InstallationScopedOptions): Promise<InstallationGraphResult>;
     list(options?: InstallationListOptions): Promise<PagedResult<Installation>>;
     resolve(installPath: string, options?: ResolveInstallationOptions): Promise<InstallationDetail>;
     update(id: string, options?: UpdateInstallationOptions): Promise<InstallationLifecycleResult>;
@@ -1012,65 +1369,257 @@ interface NamespacedSettings {
     reset(key: string, options?: SettingsScopedOptions): Promise<void>;
 }
 
-type BridgeEventType = HostToAppMessage['type'];
-type BridgeListener = (data: HostToAppMessage) => void;
+interface EmailScopedOptions {
+    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[];
+    idempotencyKey: string;
+    replyTo?: string;
+}
+interface EmailDispatchOutcome {
+    id: string;
+    status: 'accepted' | 'delivered' | 'failed' | 'unknown';
+    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;
+}
+
+/** Signed-package transactional email. Dispatch never accepts HTML, From or a browser invoice snapshot. */
+declare class EmailModule {
+    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;
+}
+
+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';
+interface BusinessParameters {
+    periodId?: string;
+    receivableAccountId?: string;
+    incomeAccountId?: string;
+    taxAccountId?: string;
+    date?: string;
+    reason?: string;
+}
+interface BusinessCommand {
+    operation: BusinessOperation;
+    idempotencyKey: string;
+    /** Omit only when creating; the server derives a stable ID from this operation key. */
+    recordId?: string;
+    /** Canonical kind, e.g. crm/company. Required for metadata-free creation. */
+    kind?: string;
+    expectedCatalogueRevision?: string;
+    /** Exact strong, quoted canonical revision; omit only for a new record. */
+    expectedRevision?: string;
+    record?: Record<string, unknown>;
+    parameters?: BusinessParameters;
+}
+interface BusinessSnapshot {
+    id: string;
+    kind: string;
+    json: string;
+    revision: string;
+}
+interface BusinessContext {
+    workspaceId: string;
+    branch: string;
+    catalogueRevision: string | null;
+    settings: BusinessSnapshot[];
+}
+interface BusinessCommitResult {
+    operationId: string;
+    committedAt: string;
+    records: BusinessSnapshot[];
+}
+interface BusinessOutcomeRequest {
+    operation: BusinessOperation;
+    idempotencyKey: string;
+    requestHash?: string;
+    command?: BusinessCommand;
+}
+type BusinessReportName = 'trial-balance' | 'general-ledger' | 'profit-and-loss' | 'balance-sheet' | 'receivables';
+interface BusinessReportLine {
+    accountId: string;
+    code: string;
+    name: string;
+    accountType: 'asset' | 'liability' | 'equity' | 'income' | 'expense';
+    debitMinor: string;
+    creditMinor: string;
+    balanceMinor: string;
+}
+interface BusinessReport {
+    report: BusinessReportName;
+    from: string | null;
+    to: string | null;
+    lines: BusinessReportLine[];
+    entries: BusinessLedgerEntry[];
+    /** Coherent catalogue revision and overdue evaluation date for receivables. */
+    revision?: string;
+    asOf?: string;
+    currency?: string;
+    minorDigits?: number;
+    receivables?: BusinessReceivable[];
+    totals?: BusinessReceivableTotals;
+}
+interface BusinessReceivable {
+    invoiceId: string;
+    revision: string;
+    invoiceNumber: string;
+    issueDate: string;
+    dueDate: string;
+    currency: string;
+    minorDigits: number;
+    customer: Record<string, unknown>;
+    customerReference?: Record<string, unknown>;
+    grossAmountMinor: string;
+    creditedAmountMinor: string;
+    paidAmountMinor: string;
+    outstandingAmountMinor: string;
+    overdueAmountMinor: string;
+    isOverdue: boolean;
+    daysOverdue: number;
+}
+interface BusinessReceivableTotals {
+    grossAmountMinor: string;
+    creditedAmountMinor: string;
+    paidAmountMinor: string;
+    outstandingAmountMinor: string;
+    overdueAmountMinor: string;
+}
+interface BusinessLedgerEntry {
+    journalId: string;
+    date: string;
+    description: string;
+    accountId: string;
+    direction: 'debit' | 'credit';
+    amountMinor: string;
+    runningBalanceMinor: string;
+}
+
 /**
- * PostMessage bridge for communication between an app (iframe) and the
- * workspace host. Handles the initialization handshake, token lifecycle,
- * and app-to-host events (navigate, resize, dirty, etc.).
+ * Trusted workspace business records, independent of app scripts or generic file writes.
+ * Never automatically retries a command: resolve a lost response with outcome() or
+ * resubmit the exact same command/key to obtain the original durable result.
  */
-declare class Bridge {
-    private readonly expectedHostOrigin?;
-    private listeners;
-    private _initResolve;
-    private _initReject;
-    private _initTimer;
-    private _initPromise;
-    private _hostOrigin;
-    private _messageHandler;
-    private _destroyed;
-    private sessionId;
-    private actions;
-    private requests;
-    private backendRequests;
-    constructor(expectedHostOrigin?: string | undefined);
-    /** Post `verentis:ready` to the host to start the handshake */
-    sendReady(capabilities?: string[]): void;
-    /** Wait for the host to send `verentis:init` with context and token */
-    waitForInit(): Promise<{
-        context: AppContext;
-        token: TokenInfo;
-    }>;
-    /** Get the host origin (available after init) */
-    get hostOrigin(): string | null;
-    /** Send a message to the host */
-    postToHost(message: AppToHostMessage): void;
-    /**
-     * Navigate to another location in the workspace.
-     *
-     * @param path A workspace file path (e.g. `/reports/q1.json`) or an absolute
-     *   http(s) URL. External URLs require the app to declare the
-     *   `navigation:external` capability in its manifest.
-     * @param options Navigation options. Set `newTab: true` to open the target in
-     *   a new browser tab instead of the current one.
-     */
-    navigate(path: string, options?: NavigateOptions): void;
-    /** Request iframe resize */
-    resize(height: number): void;
-    /** Update the title displayed by the host */
-    setTitle(title: string): void;
-    /** Signal unsaved changes to the host */
-    setDirty(isDirty: boolean): void;
-    /** The host, not the app, selects the installation, file, branch and permission ceiling. */
-    requestBackendCredential(): Promise<AppBackendCredential>;
-    registerAction(descriptor: HeaderAction, handler: HeaderActionHandler): HeaderActionRegistration;
-    private publishActions;
-    private invokeAction;
-    /** Subscribe to a specific message type from the host */
-    on(type: BridgeEventType, listener: BridgeListener): () => void;
-    /** Clean up event listeners */
-    destroy(): void;
-    private handleMessage;
+declare class BusinessModule {
+    private readonly http;
+    private readonly branch;
+    constructor(http: HttpTransport, branch?: string);
+    withBranch(branch: string): BusinessModule;
+    context(): Promise<BusinessContext>;
+    command(command: BusinessCommand): Promise<BusinessCommitResult>;
+    read(id: string): Promise<BusinessSnapshot | null>;
+    list(kind?: string): Promise<BusinessSnapshot[]>;
+    /** null means unresolved, not success; do not invent a new operation key. */
+    outcome(request: BusinessOutcomeRequest): Promise<BusinessCommitResult | null>;
+    /** Recover using the exact original command, without reproducing server fingerprint encoding. */
+    outcomeFor(command: BusinessCommand): Promise<BusinessCommitResult | null>;
+    report(report: BusinessReportName, range?: {
+        from?: string;
+        to?: string;
+    }): Promise<BusinessReport>;
+    /** Retained historical expense receipt bytes, even after the original native file is removed. */
+    receipt(nodeId: string, revision: string): Promise<Blob>;
+    private headers;
 }
 
 /**
@@ -1085,8 +1634,11 @@ declare class VerentisClient {
     installations: InstallationsModule;
     resources: ResourcesModule;
     settings: SettingsModule;
+    email: EmailModule;
+    business: BusinessModule;
     readonly context: ContextModule;
     readonly bridge: Bridge | null;
+    readonly collaboration: NativeCollaborationClient;
     private readonly _auth;
     private _http;
     private _ready;
@@ -1097,6 +1649,12 @@ declare class VerentisClient {
      * In iframe mode this resolves after the host sends `verentis:init`.
      */
     whenReady(): Promise<void>;
+    /**
+     * The current `Authorization` header value, refreshed when near expiry.
+     * Forward it to the app's own backend, which exchanges it at Security's
+     * `/connect/token` (RFC 8693) as the installation's confidential client.
+     */
+    getAuthorizationHeader(): Promise<string | null>;
     /** Clean up resources (timers, event listeners) */
     destroy(): void;
     private initFromBridge;
@@ -1115,6 +1673,36 @@ declare function matchMimeType(pattern: string, mimeType: string): boolean;
  */
 declare function findBestMatch(mimeType: string, bindings: MimeTypeBinding[]): MimeTypeBinding | null;
 
+interface CollaborationDocumentContext {
+    workspace?: {
+        id?: string;
+    };
+    file?: {
+        nodeId?: string;
+        branch?: string;
+    };
+}
+interface CollaborationDocument {
+    sessionId: string;
+    workspaceId: string;
+    branch: string;
+    nodeId: string;
+    fileId: string;
+    name: string;
+    readOnly: boolean;
+    accessTokenTtl: number;
+}
+/** An exact origin, not a URL pattern or an authority grant. */
+declare function exactHttpsOrigin(value: unknown): string;
+declare function isTrustedMessage(event: {
+    source: unknown;
+    origin: string;
+}, source: unknown, origin: string): boolean;
+/** Checks nonsecret launch metadata against the document selected by the trusted host. */
+declare function validateCollaborationDocument(value: unknown, context: CollaborationDocumentContext, now?: number): CollaborationDocument;
+/** An editor acknowledgement alone never proves a document was durably saved. */
+declare function isDurableSaveConfirmed(result: unknown, request: unknown, currentGeneration: number, editorModified: boolean): boolean;
+
 /**
  * Authenticates with a Verentis API key (`vrt_` prefix).
  * The backend detects the `vrt_` prefix in the Bearer token and resolves it
@@ -1202,4 +1790,4 @@ declare class BridgeAuth implements AuthStrategy {
  */
 declare function createVerentisClient(options?: VerentisClientOptions): VerentisClient;
 
-export { ApiError, ApiKeyAuth, type AppBackendCredential, 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 CatalogImage, ContextModule, type DeleteFileOptions, 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, type HeaderAction, type HeaderActionHandler, type HeaderActionRegistration, type HeaderActionResult, type HostToAppMessage, HttpTransport, type Installation, type InstallationDetail, type InstallationLifecycleResult, type InstallationListOptions, type InstallationMode, type InstallationScopedOptions, type InstallationStatus, InstallationsModule, type InstalledPackageDescriptor, type InstalledPackagePayload, type ManifestMetadata, type MimeTypeBinding, type MoveFileOptions, type NamespacedSettings, type NavigateOptions, type OAuthConfig, type PagedResult, 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 TokenInfo, type UpdateInstallationOptions, type VerentisActionInvokeMessage, type VerentisActionResultMessage, type VerentisActionsSetMessage, type VerentisBackendCredentialRequest, type VerentisBackendCredentialResponse, VerentisClient, type VerentisClientOptions, type VerentisDirtyMessage, type VerentisFileChangedMessage, type VerentisInitMessage, type VerentisMessage, type VerentisNavigateMessage, type VerentisReadyMessage, type VerentisResizeMessage, type VerentisThemeMessage, type VerentisTitleMessage, type VerentisTokenRefreshMessage, type VerentisTokenRefreshedMessage, type WaitOptions, type WorkspaceAppContext, type WorkspaceInfo, type WriteFileOptions, createVerentisClient, findBestMatch, isHeaderAction, isTerminalStatus, matchMimeType };
+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 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 };