@verentis/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1112 @@
+interface VerentisMessage {
+    type: `verentis:${string}`;
+    version: 1;
+    requestId?: string;
+}
+interface VerentisInitMessage extends VerentisMessage {
+    type: 'verentis:init';
+    context: AppContext;
+    token: TokenInfo;
+}
+interface VerentisTokenRefreshedMessage extends VerentisMessage {
+    type: 'verentis:token:refreshed';
+    requestId: string;
+    token: TokenInfo;
+}
+interface VerentisFileChangedMessage extends VerentisMessage {
+    type: 'verentis:file:changed';
+    path: string;
+    fileVersion?: string;
+}
+interface VerentisThemeMessage extends VerentisMessage {
+    type: 'verentis:theme';
+    colorScheme: 'light' | 'dark';
+    variables?: Record<string, string>;
+}
+interface VerentisReadyMessage extends VerentisMessage {
+    type: 'verentis:ready';
+    capabilities?: string[];
+}
+interface VerentisTokenRefreshMessage extends VerentisMessage {
+    type: 'verentis:token:refresh';
+    requestId: string;
+}
+interface VerentisNavigateMessage extends VerentisMessage {
+    type: 'verentis:navigate';
+    /** Target of the navigation: a workspace file path or an absolute http(s) URL. */
+    path: string;
+    /** When true, the host opens the target in a new browser tab instead of the current one. */
+    newTab?: boolean;
+}
+interface VerentisResizeMessage extends VerentisMessage {
+    type: 'verentis:resize';
+    height: number;
+}
+interface VerentisTitleMessage extends VerentisMessage {
+    type: 'verentis:title';
+    title: string;
+}
+interface VerentisDirtyMessage extends VerentisMessage {
+    type: 'verentis:dirty';
+    isDirty: boolean;
+}
+type HostToAppMessage = VerentisInitMessage | VerentisTokenRefreshedMessage | VerentisFileChangedMessage | VerentisThemeMessage;
+type AppToHostMessage = VerentisReadyMessage | VerentisTokenRefreshMessage | VerentisNavigateMessage | VerentisResizeMessage | VerentisTitleMessage | VerentisDirtyMessage;
+type AppSurface = 'file' | 'workspace';
+interface AppContextBase {
+    workspace: WorkspaceInfo;
+    entryPoint?: EntryPointInfo;
+    apiUrl: string;
+}
+/** Context for an application opened against a workspace file. */
+interface FileAppContext extends AppContextBase {
+    surface: 'file';
+    file: FileInfo;
+}
+/** Context for an application opened as a standalone workspace experience. */
+interface WorkspaceAppContext extends AppContextBase {
+    surface: 'workspace';
+    file?: never;
+}
+/**
+ * Legacy file-hosted contexts did not include a surface discriminator. They
+ * remain accepted and are treated as `file` surfaces by the SDK.
+ */
+interface LegacyFileAppContext extends AppContextBase {
+    surface?: undefined;
+    file: FileInfo;
+}
+/**
+ * Application context supplied by the workspace host.
+ *
+ * New hosts explicitly identify `file` or `workspace` surfaces. The legacy
+ * file shape without `surface` remains supported for backwards compatibility.
+ */
+type AppContext = FileAppContext | WorkspaceAppContext | LegacyFileAppContext;
+interface WorkspaceInfo {
+    id: string;
+    slug: string;
+    name: string;
+}
+interface FileInfo {
+    path: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    version?: string;
+    etag?: string;
+}
+interface EntryPointInfo {
+    id: string;
+    displayName: string;
+    description?: string;
+    icon?: string;
+    route: string;
+    mode: 'view' | 'edit';
+    matchedPattern: string;
+    priority: number;
+}
+interface TokenInfo {
+    accessToken: string;
+    expiresAt: string;
+    scopes: string[];
+}
+interface VerentisClientOptions {
+    /** Base URL of the Verentis API gateway (e.g. 'https://api.verentis.com') */
+    apiUrl?: string;
+    /** API version prefix (defaults to 'v1') */
+    apiVersion?: string;
+    /** Authentication configuration */
+    auth?: AuthOptions;
+    /** Workspace ID for standalone mode */
+    workspaceId?: string;
+}
+type AuthOptions = {
+    apiKey: string;
+} | {
+    token: string;
+    expiresAt?: string;
+    refreshToken?: () => Promise<TokenInfo>;
+};
+/**
+ * Options for {@link VerentisNavigateMessage}-based navigation requests.
+ */
+interface NavigateOptions {
+    /**
+     * When true, the host opens the target in a new browser tab instead of
+     * navigating the current tab. Defaults to false.
+     *
+     * The target may be a workspace file path or an absolute http(s) URL.
+     * Opening an external URL requires the app to declare the
+     * `navigation:external` capability in its manifest.
+     */
+    newTab?: boolean;
+}
+interface FileEntry {
+    path: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    version?: string;
+    etag?: string;
+    children?: FileEntry[];
+}
+interface GetFileOptions {
+    branch?: string;
+    pageNo?: number;
+    pageSize?: number;
+    orderBy?: string;
+}
+interface WriteFileOptions {
+    content: Blob | string | ArrayBuffer;
+    contentType?: string;
+    filename?: string;
+    branch?: string;
+}
+interface MoveFileOptions {
+    from: string;
+    to: string;
+    branch?: string;
+}
+interface DeleteFileOptions {
+    path: string;
+    branch?: string;
+}
+type ArchiveFormat = 'zip' | 'tgz';
+interface ReadArchiveOptions {
+    /** Archive format. Defaults to 'zip'. */
+    format?: ArchiveFormat;
+    /** Target branch. Defaults to 'main'. */
+    branch?: string;
+}
+interface ExtractUploadOptions {
+    /** Original filename of the archive (for format detection). */
+    filename?: string;
+    /** Target branch. Defaults to 'main'. */
+    branch?: string;
+}
+interface InstalledPackagePayload {
+    sourcePath: string;
+    destinationPath: string;
+    mode: string;
+    phase: number;
+    mimeType?: string | null;
+}
+interface InstalledPackageDescriptor {
+    packageIdentity: string;
+    publisher?: string | null;
+    name: string;
+    version: string;
+    kind: string;
+    manifestYaml: string;
+    installMode: string;
+    sealed: boolean;
+    mimeType: string;
+    payloads: InstalledPackagePayload[];
+}
+type InstallationMode = 'Extracted' | 'Sealed';
+type InstallationStatus = 'Pending' | 'Installing' | 'Installed' | 'Updating' | 'Uninstalling' | 'Failed' | 'Uninstalled';
+interface Installation {
+    id: string;
+    accountId: string;
+    workspaceId: string;
+    packageId: string;
+    packageVersionId: string;
+    packageName: string;
+    publisherName: string;
+    version: string;
+    installPath: string;
+    branch: string;
+    installMode: InstallationMode;
+    status: InstallationStatus;
+    installedBy: string;
+    errorMessage?: string | null;
+    createdAt: string;
+    updatedAt?: string | null;
+    securityFlagged: boolean;
+    securityFlagReason?: string | null;
+    isSystem: boolean;
+    systemKey?: string | null;
+    protectionReason?: string | null;
+}
+interface CatalogImage {
+    assetId: string;
+    url: string;
+    alt: string;
+    caption?: string | null;
+    mediaType: string;
+}
+interface InstallationDetail {
+    installation: Installation;
+    installedVersionStatus: string;
+    installedReadmeMarkdown?: string | null;
+    installedChangelogMarkdown?: string | null;
+    installedDisplayName?: string | null;
+    installedDescription?: string | null;
+    installedLogoUrl?: string | null;
+    installedHeroUrl?: string | null;
+    installedImages: CatalogImage[];
+    installedBadges: string[];
+    installedIsDeprecated: boolean;
+    installedDeprecationMessage?: string | null;
+    installedIsMalicious: boolean;
+    installedIsDelisted: boolean;
+    publisherId: string;
+    publisherName: string;
+    publisherDisplayName: string;
+    publisherLogoUrl?: string | null;
+    publisherIsVerified: boolean;
+    publisherBadges: string[];
+    publisherIsMalicious: boolean;
+    packageBadges: string[];
+    packageIsMalicious: boolean;
+    packageIsDeprecated: boolean;
+    packageDeprecationMessage?: string | null;
+    latestVersion?: string | null;
+    latestVersionId?: string | null;
+    updateAvailable: boolean;
+    canUpdate: boolean;
+    canRetry: boolean;
+    canDelete: boolean;
+    allowedActions: string[];
+}
+interface InstallationLifecycleResult {
+    installationId: string;
+    status: InstallationStatus;
+    succeeded: boolean;
+    error?: string | null;
+}
+interface InstallationScopedOptions {
+    workspaceId?: string;
+}
+interface InstallationListOptions extends InstallationScopedOptions {
+    pageNo?: number;
+    pageSize?: number;
+    orderBy?: string;
+    packageId?: string;
+    branch?: string;
+    installPath?: string;
+    status?: InstallationStatus;
+    isSystem?: boolean;
+}
+interface ResolveInstallationOptions extends InstallationScopedOptions {
+    branch?: string;
+}
+interface UpdateInstallationOptions extends InstallationScopedOptions {
+    packageVersion?: string;
+    installMode?: InstallationMode;
+}
+interface AuthStrategy {
+    getAuthHeader(): Promise<string | null>;
+    destroy?(): void;
+}
+interface MimeTypeBinding {
+    pattern: string;
+    mode: 'view' | 'edit';
+    priority: number;
+    icon?: string;
+}
+interface ApplicationFileType {
+    pattern: string;
+    extensions: string[];
+    priority: number;
+    icon?: string;
+}
+interface ApplicationManifest {
+    apiVersion: string;
+    kind: 'Application';
+    metadata: ManifestMetadata;
+    spec: ApplicationSpec;
+}
+interface ManifestMetadata {
+    name: string;
+    displayName?: string;
+    description?: string;
+    icon?: string;
+    version?: string;
+    author?: string;
+    labels?: Record<string, string>;
+    annotations?: Record<string, string>;
+}
+type InstallMode = 'seed' | 'managed';
+interface InstallDirective {
+    /** Source path/glob relative to the package payload root. Must match at least one file. */
+    from: string;
+    /**
+     * Destination workspace-absolute VFS path. A trailing `/` denotes a directory (the source's
+     * basename / relative subpath is preserved beneath it); otherwise an exact file path.
+     */
+    to: string;
+    /**
+     * `seed` = install once, never overwrite an existing/user-edited file (never removed on upgrade);
+     * `managed` = app-owned, created and replaced on upgrade, removed on uninstall. Default `managed`.
+     */
+    mode?: InstallMode;
+    /** Optional explicit MIME for placed nodes; else inferred / resolved by json-schema. */
+    mime?: string;
+    /** Optional sequential install phase; omitted directives remain in the legacy single phase. */
+    phase?: number;
+}
+interface ApplicationLaunchConfig {
+    /**
+     * Enables standalone launch from the workspace. Defaults to `false`.
+     *
+     * When enabled, the platform requires `entryPoint` or `spec.entry` to
+     * resolve an iframe entry.
+     */
+    enabled?: boolean;
+    /**
+     * Optional entry-point ID to use as the standalone home. When omitted, the
+     * platform falls back to `spec.entry`.
+     */
+    entryPoint?: string;
+    /**
+     * Whether users may pin the launch surface. Defaults to `false` and does not
+     * pin it automatically.
+     */
+    pinnable?: boolean;
+}
+interface ApplicationDisplayOptions {
+    fullscreen?: boolean;
+}
+interface ApplicationEntryPoint {
+    id: string;
+    displayName?: string;
+    description?: string;
+    icon?: string;
+    route?: string;
+    /** Optional per-entry-point iframe URL override. */
+    entry?: string;
+    /** Optional splash URL override. Relative values resolve against this entry point's iframe URL. */
+    splash?: string;
+    order?: number;
+    mimeTypes?: MimeTypeBinding[];
+    display?: ApplicationDisplayOptions;
+}
+interface ApplicationSpec {
+    /** 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. */
+    splash?: string;
+    /** Named iframe surfaces; `launch.entryPoint` references one of these ids. */
+    entryPoints?: ApplicationEntryPoint[];
+    scope?: string;
+    mimeTypes?: MimeTypeBinding[];
+    fileTypes?: ApplicationFileType[];
+    capabilities?: string[];
+    permissions?: string[];
+    sandbox?: SandboxOptions;
+    oauth?: OAuthConfig;
+    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}`. */
+    installRoot?: string;
+    /** Default display behavior inherited by entry points. */
+    display?: ApplicationDisplayOptions;
+    /**
+     * Opt-in standalone workspace launch configuration. The platform defaults
+     * `enabled` and `pinnable` to `false` when omitted.
+     */
+    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
+     * settings UI. Secret values never reach browser contexts.
+     */
+    settings?: SettingDeclaration[];
+}
+/** Data type of a declared setting value. */
+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
+ * 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. */
+    key: string;
+    /** Optional environment variable name injected into engine runs (e.g. `MY_API_KEY`). */
+    env?: string;
+    /**
+     * Secret values are server-only: delivered to Docker engine runs, never to browser
+     * contexts (wasm runs, iframe apps). Defaults to `false`.
+     */
+    secret?: boolean;
+    /**
+     * Required settings prompt during marketplace install and fail an execution fast when
+     * no value is configured. Defaults to `false`.
+     */
+    required?: boolean;
+    displayName?: string;
+    description?: string;
+    /**
+     * Value input type. `file` prompts the installer to select a local file and stores its
+     * bytes as a base64 string. Defaults to `string`.
+     */
+    type?: SettingDeclarationType;
+    /** Default value. Not allowed for secrets. */
+    default?: string | number | boolean;
+    /** Allowed values when `type` is `select`. */
+    options?: string[];
+}
+interface OAuthConfig {
+    clientType: string;
+    redirectUris?: string[];
+}
+interface SandboxOptions {
+    allowScripts?: boolean;
+    allowSameOrigin?: boolean;
+    allowPopups?: boolean;
+    allowForms?: boolean;
+}
+/** Lifecycle status of an execution. Mirrors the platform `ExecutionStatus` enum. */
+type ExecutionStatus = 'Pending' | 'Queued' | 'Running' | 'Completed' | 'Failed' | 'Cancelled' | 'TimedOut' | 'AwaitingClient';
+/** How an execution is run. Mirrors the platform `ExecutionMode` enum. */
+type ExecutionMode = 'RequestResponse' | 'LongRunning' | 'Scheduled' | 'EventDriven';
+/** What triggered an execution. Mirrors the platform `ExecutionTrigger` enum. */
+type ExecutionTrigger = 'User' | 'Api' | 'Schedule' | 'Event';
+/** The structured outcome of an execution. */
+interface ExecutionResult {
+    exitCode: number;
+    stdout?: string | null;
+    stderr?: string | null;
+    /** Raw JSON payload the engine reported in `result.json`, as a string. */
+    data?: string | null;
+    artifacts: string[];
+    durationMs: number;
+    error?: string | null;
+}
+/** A single execution record. */
+interface Execution {
+    id: string;
+    workspaceId: string;
+    engineId: string;
+    engineName: string;
+    filePath?: string | null;
+    mode: ExecutionMode;
+    trigger: ExecutionTrigger;
+    tool?: string | null;
+    status: ExecutionStatus;
+    requestedAt: string;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    result?: ExecutionResult | null;
+}
+/** Captured stdout/stderr of an execution. */
+interface ExecutionLogs {
+    stdout?: string | null;
+    stderr?: string | null;
+}
+/** Options for running a file (engine resolved by the file's type). */
+interface RunFileOptions {
+    /** Workspace to run in. Defaults to the client's workspace. */
+    workspaceId?: string;
+    branch?: string;
+    tool?: string;
+    mode?: string;
+    arguments?: string[];
+    /** Structured parameters passed to the engine; serialized to JSON for the platform. */
+    parameters?: Record<string, unknown>;
+}
+/** Options for executing a specific engine (optionally against a file). */
+interface ExecuteEngineOptions {
+    workspaceId?: string;
+    filePath?: string;
+    branch?: string;
+    tool?: string;
+    mode?: string;
+    arguments?: string[];
+    parameters?: Record<string, unknown>;
+}
+/** Options that only need to scope a request to a workspace. */
+interface ExecutionScopedOptions {
+    workspaceId?: string;
+}
+interface ExecutionListOptions extends ExecutionScopedOptions {
+    filePath?: string;
+    engineIds?: string[];
+    filePaths?: string[];
+    status?: ExecutionStatus;
+    trigger?: ExecutionTrigger;
+    activeOnly?: boolean;
+    requestedAfter?: string;
+    requestedBefore?: string;
+    pageNo?: number;
+    pageSize?: number;
+    orderBy?: string;
+}
+interface PagedResult<T> {
+    totalCount: number;
+    pageCount: number;
+    pageSize: number;
+    pageNumber: number;
+    data: T[];
+}
+interface EngineRuntime {
+    kind: 'Docker' | 'Wasm';
+    image?: string | null;
+    pullPolicy?: string | null;
+    moduleUrl?: string | null;
+    runtimeHint?: string | null;
+    serverCompatible: boolean;
+    clientCompatible: boolean;
+    adapterUrl?: string | null;
+}
+interface EngineFileType {
+    pattern: string;
+    extensions: string[];
+    priority: number;
+    icon?: string;
+}
+interface EngineTool {
+    name: string;
+    description?: string | null;
+    inputSchema?: string | null;
+    outputSchema?: string | null;
+}
+interface ExecutionEngine {
+    id: string;
+    workspaceId: string;
+    name: string;
+    displayName: string;
+    description?: string | null;
+    icon?: string | null;
+    version: string;
+    author?: string | null;
+    category?: string | null;
+    tier?: string | null;
+    sourcePath: string;
+    priority: number;
+    enabled: boolean;
+    capabilities: string[];
+    permissions: string[];
+    supportedModes: string[];
+    runtimes: EngineRuntime[];
+    fileTypes: EngineFileType[];
+    tools: EngineTool[];
+    resources?: {
+        cpu?: string | null;
+        memory?: string | null;
+        timeoutSeconds: number;
+        maxConcurrent: number;
+        storage?: string | null;
+    } | null;
+    sandbox?: {
+        network: string;
+        allowedHosts: string[];
+        readOnlyRoot: boolean;
+        noNewPrivileges: boolean;
+    } | null;
+    firstParty: boolean;
+}
+interface ExecutionEngineListOptions extends ExecutionScopedOptions {
+    pageNo?: number;
+    pageSize?: number;
+    orderBy?: string;
+}
+/** Options for polling an execution to completion. */
+interface WaitOptions extends ExecutionScopedOptions {
+    /** Poll interval in milliseconds (default 1000). */
+    intervalMs?: number;
+    /** Maximum time to wait in milliseconds before throwing. */
+    timeoutMs?: number;
+    /** Abort signal to cancel waiting. */
+    signal?: AbortSignal;
+}
+/** An allowed value for a `select` setting. */
+interface SettingOption {
+    value: string;
+    label: string;
+}
+/**
+ * A single workspace setting merged from its definition and any stored value.
+ * Secret values are always `null` for browser callers; `hasValue` still reports
+ * whether a value (or default) is configured.
+ */
+interface SettingItem {
+    key: string;
+    group: string;
+    label: string;
+    description?: string | null;
+    dataType: string;
+    isSecret: boolean;
+    options?: SettingOption[] | null;
+    defaultValue?: unknown;
+    value?: unknown;
+    hasValue: boolean;
+}
+/** A labeled group of settings (e.g. one group per application). */
+interface SettingGroup {
+    key: string;
+    label: string;
+    items: SettingItem[];
+}
+/** Options that scope a settings request to a workspace. */
+interface SettingsScopedOptions {
+    workspaceId?: string;
+}
+/** Presence-only result. Stored secret and non-secret values are never included. */
+interface SettingPresence {
+    key: string;
+    hasStoredValue: boolean;
+    hasEffectiveValue: boolean;
+}
+interface ResourceMimeTypeBinding {
+    id: string;
+    pattern: string;
+    mode: string;
+    priority: number;
+}
+interface ResourceRegistration {
+    id: string;
+    accountId: string;
+    workspaceId: string;
+    name: string;
+    displayName?: string | null;
+    description?: string | null;
+    icon?: string | null;
+    version?: string | null;
+    author?: string | null;
+    entryUrl?: string | null;
+    kind: string;
+    scope: string;
+    manifestPath: string;
+    manifestNodeId: string;
+    manifestHash: string;
+    branch: string;
+    spec?: string | null;
+    labels?: string | null;
+    capabilities?: string | null;
+    permissions?: string | null;
+    sandboxConfig?: string | null;
+    createdAt: string;
+    updatedAt?: string | null;
+    mimeTypeBindings: ResourceMimeTypeBinding[];
+    entryPointId?: string | null;
+    entryPointDisplayName?: string | null;
+    entryPointDescription?: string | null;
+    entryPointIcon?: string | null;
+    entryPointRoute?: string | null;
+    entryPointEntryUrl?: string | null;
+    entryPointMode?: string | null;
+    entryPointMatchedPattern?: string | null;
+    entryPointPriority?: number | null;
+    entryPointFullscreen?: boolean | null;
+    entryPointSplashUrl?: string | null;
+    launchEnabled: boolean;
+    launchEntryPointId?: string | null;
+    launchPinnable: boolean;
+}
+interface ResourceScopedOptions {
+    workspaceId?: string;
+}
+interface RequestOptions {
+    headers?: Record<string, string>;
+    body?: BodyInit | null;
+    params?: Record<string, string | number | boolean | readonly (string | number)[] | undefined>;
+}
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly detail: string;
+    readonly title?: string | undefined;
+    constructor(status: number, detail: string, title?: string | undefined);
+}
+
+/**
+ * Provides access to the current workspace and launch context.
+ * In iframe mode, this is populated from the host's `verentis:init` message.
+ * In standalone mode, the developer provides values via options.
+ */
+declare class ContextModule {
+    private _workspace;
+    private _surface;
+    private _file;
+    private _entryPoint;
+    private _apiUrl;
+    /** The current workspace */
+    get workspace(): WorkspaceInfo;
+    /** The host surface that launched the app */
+    get surface(): AppSurface;
+    /** The file that triggered the app to open on a file surface */
+    get file(): FileInfo;
+    /** The API URL */
+    get apiUrl(): string;
+    /** Whether a file context is available */
+    get hasFile(): boolean;
+    /** The application entry point that matched the opened file */
+    get entryPoint(): EntryPointInfo | null;
+    /** Whether an entry point context is available */
+    get hasEntryPoint(): boolean;
+    /** Update context from the host's init message */
+    setFromAppContext(ctx: AppContext): void;
+    /** Set workspace info directly (standalone mode) */
+    setWorkspace(workspace: Partial<WorkspaceInfo> & {
+        id: string;
+    }): void;
+    /** Set API URL directly */
+    setApiUrl(url: string): void;
+}
+
+/**
+ * HTTP client for making direct API calls to the Verentis gateway.
+ * Used in both standalone and iframe modes — the auth strategy determines
+ * how the Authorization header is obtained.
+ */
+declare class HttpTransport {
+    private readonly baseUrl;
+    private readonly auth;
+    private readonly apiVersion;
+    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>;
+    private buildUrl;
+}
+
+/** Returns true once an execution has reached a final state. */
+declare function isTerminalStatus(status: ExecutionStatus): boolean;
+/**
+ * Execution operations module. Triggers engine executions against files or a specific engine,
+ * reads their status/result/logs, cancels them, and polls them to completion — all over the
+ * Verentis execution API (`/v1/executions`).
+ */
+declare class ExecutionsModule {
+    private readonly http;
+    private readonly workspaceId?;
+    constructor(http: HttpTransport, workspaceId?: string | undefined);
+    /**
+     * Run a file in the virtual file system. The platform resolves the appropriate engine from the
+     * file's type (e.g. a `.py` file runs on the Python engine).
+     */
+    run(filePath: string, options?: RunFileOptions): Promise<Execution>;
+    /**
+     * Execute a specific engine by id, optionally against a file and/or with structured parameters
+     * (e.g. invoking an engine tool without a script).
+     */
+    execute(engineId: string, options?: ExecuteEngineOptions): Promise<Execution>;
+    /** Get an execution by id. */
+    get(id: string, options?: ExecutionScopedOptions): Promise<Execution>;
+    /** List workspace executions with optional engine, file, lifecycle, and time filters. */
+    list(options?: ExecutionListOptions): Promise<PagedResult<Execution>>;
+    /** Get the captured stdout/stderr of an execution. */
+    logs(id: string, options?: ExecutionScopedOptions): Promise<ExecutionLogs>;
+    /** Cancel a pending or running execution. */
+    cancel(id: string, options?: ExecutionScopedOptions): Promise<Execution>;
+    /**
+     * Poll an execution until it reaches a terminal status. Returns immediately if it is already
+     * terminal. Throws if `timeoutMs` elapses or the supplied signal aborts.
+     */
+    wait(id: string, options?: WaitOptions): Promise<Execution>;
+    /**
+     * Run a file and resolve once it has completed. For synchronous (request-response) executions the
+     * initial response is already terminal; otherwise it polls via {@link wait}.
+     */
+    runAndWait(filePath: string, options?: RunFileOptions & WaitOptions): Promise<Execution>;
+    private requireWorkspaceId;
+}
+
+/** Read-only access to execution engines registered in a workspace. */
+declare class EnginesModule {
+    private readonly http;
+    private readonly workspaceId?;
+    constructor(http: HttpTransport, workspaceId?: string | undefined);
+    list(options?: ExecutionEngineListOptions): Promise<PagedResult<ExecutionEngine>>;
+    get(id: string, options?: ExecutionScopedOptions): Promise<ExecutionEngine>;
+    private requireWorkspaceId;
+}
+
+/**
+ * File operations module. Provides read, write, list, move, and delete
+ * against the Verentis Node file API.
+ */
+declare class FilesModule {
+    private readonly http;
+    private readonly workspaceId?;
+    constructor(http: HttpTransport, workspaceId?: string | undefined);
+    /**
+     * Get file metadata or directory listing.
+     * For files: returns metadata (path, name, mimeType, size, etc.).
+     * For directories: returns metadata with children array populated.
+     */
+    get(path: string, options?: GetFileOptions): Promise<FileEntry>;
+    /**
+     * Read the raw content of a file as a Blob.
+     */
+    readContent(path: string, branch?: string): Promise<Blob>;
+    /** Read UTF-8 text content from a workspace file. */
+    readText(path: string, branch?: string): Promise<string>;
+    /** Inspect an extracted or sealed package node without exposing sealed payload content. */
+    getPackageDescriptor(path: string, branch?: string): Promise<InstalledPackageDescriptor>;
+    /**
+     * Download a file or directory as an archive (zip or tgz).
+     * Only applicable when the target has children or you want a packaged download.
+     */
+    readArchive(path: string, options?: ReadArchiveOptions): Promise<Blob>;
+    /**
+     * Upload an archive (zip or tgz) and auto-extract its contents as individual nodes.
+     * If the archive contains a `.verentis-manifest.json`, the original metadata
+     * (display names, mime types, parent-content relationships) will be honoured.
+     */
+    extractUpload(path: string, file: Blob, options?: ExtractUploadOptions): Promise<void>;
+    /**
+     * Upload or create a file.
+     */
+    write(path: string, options: WriteFileOptions): Promise<void>;
+    /**
+     * Move or rename a file.
+     */
+    move(options: MoveFileOptions): Promise<void>;
+    /**
+     * Delete a file.
+     */
+    remove(options: DeleteFileOptions): Promise<void>;
+    private workspaceHeaders;
+}
+
+/** Manage Marketplace installation ledger records for the current workspace. */
+declare class InstallationsModule {
+    private readonly http;
+    private readonly workspaceId?;
+    constructor(http: HttpTransport, workspaceId?: string | undefined);
+    list(options?: InstallationListOptions): Promise<PagedResult<Installation>>;
+    resolve(installPath: string, options?: ResolveInstallationOptions): Promise<InstallationDetail>;
+    update(id: string, options?: UpdateInstallationOptions): Promise<InstallationLifecycleResult>;
+    uninstall(id: string, options?: InstallationScopedOptions): Promise<void>;
+    private requireWorkspaceId;
+}
+
+/** Read-only access to workspace Resource registrations and resolved application handlers. */
+declare class ResourcesModule {
+    private readonly http;
+    private readonly workspaceId?;
+    constructor(http: HttpTransport, workspaceId?: string | undefined);
+    list(options?: ResourceScopedOptions): Promise<ResourceRegistration[]>;
+    get(id: string, options?: ResourceScopedOptions): Promise<ResourceRegistration>;
+    private requireWorkspaceId;
+}
+
+/**
+ * Workspace settings module. Reads (and where permitted, writes) workspace-scoped settings
+ * 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).
+ *
+ * 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
+ * are stored namespaced as `{manifest-name}.{key}` — see {@link SettingsModule.namespaced}.
+ */
+declare class SettingsModule {
+    private readonly http;
+    private readonly workspaceId?;
+    constructor(http: HttpTransport, workspaceId?: string | undefined);
+    /** List every setting group visible to the workspace (definitions merged with values). */
+    list(options?: SettingsScopedOptions): Promise<SettingGroup[]>;
+    /** Get a single setting by its full key (e.g. `graphite.api-key`). */
+    get(key: string, options?: SettingsScopedOptions): Promise<SettingItem>;
+    /** Get a setting's value by its full key, or `defaultValue` when unset. */
+    getValue<T = unknown>(key: string, defaultValue?: T, options?: SettingsScopedOptions): Promise<T | undefined>;
+    /**
+     * Check exact setting keys for retained stored values and effective defaults.
+     * 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. */
+    set(key: string, value: unknown, options?: SettingsScopedOptions): Promise<void>;
+    /** Delete a stored value (reverting to the definition default). Requires `fabric.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
+     * manifest namespacing convention. An app named `graphite` declaring `key: api-key` reads it as:
+     *
+     * ```ts
+     * const settings = client.settings.namespaced('graphite')
+     * const apiKey = await settings.getValue<string>('api-key')
+     * ```
+     */
+    namespaced(namespace: string): NamespacedSettings;
+    private scopeParams;
+    private requireWorkspaceId;
+}
+/** Key-prefixed settings accessor returned by {@link SettingsModule.namespaced}. */
+interface NamespacedSettings {
+    get(key: string, options?: SettingsScopedOptions): Promise<SettingItem>;
+    getValue<T = unknown>(key: string, defaultValue?: T, options?: SettingsScopedOptions): Promise<T | undefined>;
+    set(key: string, value: unknown, options?: SettingsScopedOptions): Promise<void>;
+    reset(key: string, options?: SettingsScopedOptions): Promise<void>;
+}
+
+type BridgeEventType = HostToAppMessage['type'];
+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 listeners;
+    private _initResolve;
+    private _initPromise;
+    private _hostOrigin;
+    private _messageHandler;
+    private _destroyed;
+    constructor();
+    /** 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;
+    /** Subscribe to a specific message type from the host */
+    on(type: BridgeEventType, listener: BridgeListener): () => void;
+    /** Clean up event listeners */
+    destroy(): void;
+    private handleMessage;
+}
+
+/**
+ * The main Verentis SDK client.
+ * Provides access to file operations, workspace context, and (in iframe mode)
+ * the host communication bridge.
+ */
+declare class VerentisClient {
+    files: FilesModule;
+    executions: ExecutionsModule;
+    engines: EnginesModule;
+    installations: InstallationsModule;
+    resources: ResourcesModule;
+    settings: SettingsModule;
+    readonly context: ContextModule;
+    readonly bridge: Bridge | null;
+    private readonly _auth;
+    private _http;
+    private _ready;
+    constructor(options?: VerentisClientOptions);
+    /**
+     * Returns a promise that resolves when the client is fully initialized.
+     * In standalone mode this resolves immediately.
+     * In iframe mode this resolves after the host sends `verentis:init`.
+     */
+    whenReady(): Promise<void>;
+    /** Clean up resources (timers, event listeners) */
+    destroy(): void;
+    private initFromBridge;
+}
+
+/**
+ * Tests whether a MIME type matches a pattern.
+ * Supports wildcards: `image/*` matches `image/png`, `*​/*` matches everything.
+ * Comparison is case-insensitive and ignores parameters (e.g. `; charset=utf-8`).
+ */
+declare function matchMimeType(pattern: string, mimeType: string): boolean;
+/**
+ * Finds the best matching binding for a given MIME type.
+ * Exact matches beat wildcard matches at the same priority level.
+ * Higher priority values are preferred.
+ */
+declare function findBestMatch(mimeType: string, bindings: MimeTypeBinding[]): MimeTypeBinding | null;
+
+/**
+ * Authenticates with a Verentis API key (`vrt_` prefix).
+ * The backend detects the `vrt_` prefix in the Bearer token and resolves it
+ * as an API key rather than a JWT.
+ */
+declare class ApiKeyAuth implements AuthStrategy {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    getAuthHeader(): Promise<string>;
+}
+
+/**
+ * Authenticates with a pre-existing bearer token.
+ * Tracks expiry and invokes an optional refresh callback before the token expires.
+ */
+declare class TokenAuth implements AuthStrategy {
+    private _token;
+    private _expiresAt;
+    private _refreshTimer;
+    private _refreshFn?;
+    constructor(token: string, expiresAt?: string, refreshFn?: () => Promise<TokenInfo>);
+    getAuthHeader(): Promise<string>;
+    /** Update the token (e.g. after a refresh) */
+    update(info: TokenInfo): void;
+    destroy(): void;
+    private isExpired;
+    private refresh;
+    private scheduleRefresh;
+}
+
+/**
+ * Authenticates via the PostMessage bridge in iframe mode.
+ * The token is received from the host during initialization and refreshed
+ * by requesting a new token from the host when nearing expiry.
+ */
+declare class BridgeAuth implements AuthStrategy {
+    private readonly hostOrigin;
+    private _token;
+    private _expiresAt;
+    private _refreshTimer;
+    private _pendingRefresh;
+    private _messageHandler;
+    constructor(hostOrigin: string);
+    /** Set the initial token received from the host's `verentis:init` message */
+    setToken(info: TokenInfo): void;
+    getAuthHeader(): Promise<string | null>;
+    destroy(): void;
+    private isExpired;
+    private _refreshResolve;
+    private requestRefresh;
+    private handleMessage;
+    private scheduleRefresh;
+}
+
+/**
+ * Create a new Verentis SDK client.
+ *
+ * @example Standalone mode (local development)
+ * ```ts
+ * const client = createVerentisClient({
+ *   apiUrl: 'https://api.verentis.com',
+ *   auth: { apiKey: 'vrt_abc123_...' },
+ *   workspaceId: 'workspace-uuid',
+ * })
+ *
+ * const file = await client.files.get('/documents/report.json')
+ * ```
+ *
+ * @example iframe mode (auto-detected at runtime)
+ * ```ts
+ * const client = createVerentisClient()
+ * await client.whenReady()
+ *
+ * const { surface, workspace } = client.context
+ * if (surface === 'file') {
+ *   const content = await client.files.readContent(client.context.file.path)
+ * }
+ * ```
+ */
+declare function createVerentisClient(options?: VerentisClientOptions): VerentisClient;
+
+export { ApiError, ApiKeyAuth, 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 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, 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, isTerminalStatus, matchMimeType };