@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,885 @@
+/**
+ * The `/v0` surface as a Frontend sees it (components/05-interface-api.md
+ * §API, §Representation): the ARID is the only identifier that crosses the
+ * boundary. These types mirror what the Interface API serialises; they hold
+ * no Engine internals and pull in no Engine dependency.
+ */
+import type { RevealLevel } from "./reveal.js";
+import type { ContactOrigin, ContactState, DisclosableField } from "./contacts.js";
+import type { PortalOptions } from "./portal-options.js";
+import type { PassGate, PassKind, PassPresentation, PassState } from "./passes.js";
+import type { PortalThemeSpec } from "./theme.js";
+import type { EnrolmentState } from "./enrolment.js";
+import type { FieldRef, FillMode, LocatorRule } from "./fill.js";
+/** What an Entry is (ADR-014). The Engine's Definition schema checks the same list; a test there fails when they differ. */
+export declare const ENTRY_KINDS: readonly ["file", "folder"];
+export type EntryKind = (typeof ENTRY_KINDS)[number];
+/** What a Field's value is. The Engine's Definition schema checks the same list; a test there fails when they differ. */
+export declare const FIELD_VALUE_TYPES: readonly ["text", "password", "number", "boolean", "date", "datetime", "email", "phone", "url", "json", "attachment"];
+export type FieldValueType = (typeof FIELD_VALUE_TYPES)[number];
+export type Capability = "read" | "reveal" | "update" | "delete" | "share" | "transfer";
+export declare const CAPABILITIES: readonly Capability[];
+export type ResourceStatus = "active" | "deleted" | "transit" | "superseded" | string;
+export interface Page<T> {
+    items: T[];
+    next_cursor: string | null;
+}
+/** RFC 9457 body every error carries (`application/problem+json`). */
+export interface Problem {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    [key: string]: unknown;
+}
+export interface ResourceBase {
+    arid: string;
+    type: string;
+    version: number;
+    status: ResourceStatus;
+    created_at: string;
+    updated_at: string;
+}
+export interface DefinitionRef {
+    arid: string;
+    version: number;
+}
+export interface SessionCreated {
+    session: string;
+    expires_at: string;
+    customer: {
+        arid: string;
+        enrolled: boolean;
+    };
+    tenant: {
+        arid: string;
+        slug: string;
+        name: string;
+    };
+}
+export interface SessionCurrent {
+    session: string;
+    customer: string;
+    tenant: {
+        arid: string;
+        slug: string;
+    };
+    vault: string;
+    principal: string;
+    principals: string[];
+    created_at: string;
+    oidc_expires_at: string;
+    capabilities: {
+        owner_of_vault: boolean;
+    };
+    /** Step-ups recorded on this session (ADR-018): when each proven factor lapses. */
+    step_up?: {
+        password_until?: string;
+        mfa_until?: string;
+    };
+}
+export interface PlatformStatus {
+    status: "active" | "paused";
+    reason?: string;
+    since?: string;
+}
+/** `GET /v0/status/:arid`: a Tenant's state, its status message and whether it takes new Customers, with the platform's. No session. */
+export interface TenantStatusView {
+    arid: string;
+    state: "active" | "paused" | "frozen";
+    message: string;
+    message_since?: string;
+    /** `closed`: a first sign-in is refused with `403 enrolment-closed` (ADR-044); hide sign-up. Absent from an Interface API older than 2026-10-13: open. */
+    enrolment?: EnrolmentState;
+    platform: PlatformStatus & {
+        message: string;
+        message_since?: string;
+    };
+}
+/**
+ * `GET /v0/customer`: the Customer of this Tenant. The profile fields
+ * (`display_name`, `name`, `phone`, `email`, `email_verified`) belong to the
+ * person behind it and read the same on every Tenant (ADR-016); a Tenant
+ * never sees or addresses that grouping — it only ever holds the Customer.
+ */
+export interface Customer {
+    arid: string;
+    version: number;
+    tenant: string;
+    /** The person's platform-wide handle (ADR-024): what a Contact sees of them before anything is disclosed. */
+    handle?: string;
+    display_name?: string;
+    email?: string;
+    email_verified?: boolean;
+    phone?: string;
+    name?: string;
+    created_at: string;
+    updated_at: string;
+    principal: string;
+    redeemed_principals: string[];
+    vault: string;
+}
+export interface CustomerHeartbeat {
+    /** The tier in force (ADR-061). */
+    tier: string;
+    account_status: "active" | "suspended" | "deleted" | string;
+    sync: {
+        status: string;
+    };
+    updated_at: string;
+    updated_by: string;
+}
+export interface Vault extends ResourceBase {
+    name: string;
+    owner: string;
+    wallets: number;
+    tier: string;
+}
+export interface VaultTreeNode {
+    arid: string;
+    type: string;
+    name?: string;
+    children: VaultTreeNode[];
+}
+export interface VaultTree {
+    customer: string;
+    root: string;
+    generated_at: string;
+    tree: VaultTreeNode;
+}
+export interface WalletDefinitionSummary {
+    arid: string;
+    version: number;
+    name: string;
+    label?: string;
+    description?: string;
+    accepts: DefinitionRef[];
+    nestable: boolean;
+    immutable: boolean;
+    metering: "storage" | "events";
+    /** Whether the Customer's subscription level may create from it (Tenant scoping); never for a withdrawn one. */
+    available: boolean;
+    /** The Tenant took it out of its Definition set (ADR-029): existing Wallets keep it, nothing new is created from it. */
+    withdrawn?: boolean;
+}
+export interface WalletDefinitionDetail extends Omit<WalletDefinitionSummary, "available"> {
+    event_retention_days?: number;
+    default_policy?: Record<string, unknown>;
+    entries: {
+        arid: string;
+        version: number;
+        name?: string;
+        label?: string;
+        kind?: EntryKind;
+    }[];
+}
+export interface EntryDefinitionField {
+    definition: DefinitionRef;
+    required: boolean;
+    order?: number;
+    name?: string;
+    label?: string;
+    value_type?: FieldValueType;
+    secret?: boolean;
+    /** The reveal level in effect for a secret Field (ADR-018); absent on a plain Field. */
+    reveal?: RevealLevel;
+    searchable?: boolean;
+    /** A Customer may neither rename nor hide this field (ADR-028). */
+    locked?: boolean;
+    /** Written into an existing Entry without a value when it moves to this version (ADR-029). */
+    fill_in?: unknown;
+    /** The modes a Field of this field may use here: the FieldDefinition's, narrowed by this Entry type (ADR-046). Absent: all three. */
+    filled_by?: FillMode[];
+    /** The resource types an internal reference may point at (ADR-046). Absent: any. */
+    targets?: string[];
+    /** The Definitions a target must be of, by ARID (ADR-046). Absent: any. */
+    target_definitions?: string[];
+    /** The Tenant's rule for external locators (ADR-046). */
+    locator?: LocatorRule;
+}
+export interface EntryDefinitionDetail {
+    arid: string;
+    version: number;
+    name: string;
+    label?: string;
+    description?: string;
+    /** `file` or `folder` (ADR-014). Absent on Definitions written before kinds existed; treat as `file`. */
+    kind?: EntryKind;
+    fields: EntryDefinitionField[];
+    nestable: boolean;
+    /** Folders only: the entry types a folder of this type may hold; absent = everything the Wallet accepts. */
+    contains?: DefinitionRef[];
+    /** Whether a Wallet overlay may rename, arrange or extend this type (ADR-028): `false` only when the Tenant customises nothing or excludes this type. */
+    customizable: boolean;
+    /** The value types a custom field on this type may have; absent = every type. */
+    value_types?: FieldValueType[];
+    /** The lowest reveal level a secret custom field on this type may have; absent = `click`. */
+    secret_reveal_min?: RevealLevel;
+    /** The modes a custom field on this type may allow (ADR-046); absent = all three. */
+    custom_filled_by?: FillMode[];
+    withdrawn?: boolean;
+}
+export interface FieldDefinitionDetail {
+    arid: string;
+    version: number;
+    name: string;
+    label?: string;
+    description?: string;
+    value_type: FieldValueType;
+    validation?: {
+        pattern?: string;
+        min?: number;
+        max?: number;
+        min_length?: number;
+        max_length?: number;
+        enum?: (string | number | boolean)[];
+    };
+    secret: boolean;
+    reveal?: RevealLevel;
+    searchable: boolean;
+    required: boolean;
+    immutable: boolean;
+    locked?: boolean;
+    /** ADR-046: the modes a Field of this definition may use (absent: all three), what an internal reference may point at, the locator rule. */
+    filled_by?: FillMode[];
+    targets?: string[];
+    target_definitions?: string[];
+    locator?: LocatorRule;
+    withdrawn?: boolean;
+}
+/**
+ * The version a resource is pinned to, and the latest (ADR-029). A resource is
+ * `behind` until it moves: its owner's catch-up moves it when it already fits,
+ * otherwise its next write must bring it to the latest version.
+ */
+export interface DefinitionPin extends DefinitionRef {
+    latest_version: number;
+    /** The type's key and display label, from its latest version: enough to show the type without reading its Definition. Absent only for a type the Tenant no longer has. */
+    name?: string;
+    label?: string;
+}
+/** Why a behind Entry does not yet fit the latest version, per Field the caller can read. */
+export interface DefinitionIssue {
+    /** The FieldDefinition ARID. */
+    field: string;
+    problem: "missing" | "invalid" | "does_not_convert";
+    message: string;
+}
+export interface Wallet extends ResourceBase {
+    name: string;
+    description?: string;
+    definition: DefinitionPin;
+    behind: boolean;
+    parent: string | null;
+    nested_wallets: number;
+    entries: number;
+    portfolios: string[];
+}
+export interface Field extends ResourceBase {
+    /** The Tenant's FieldDefinition; `null` for a custom field (ADR-028). */
+    definition: DefinitionRef | null;
+    /** Set on a custom field: its key in the Wallet's overlay. */
+    custom: {
+        id: string;
+    } | null;
+    /** The Tenant's field name, or the `x_` id of a custom field. */
+    name: string;
+    /** The name to show: the overlay's rename or custom label, else the Tenant's label. */
+    label: string;
+    /** Position among the Entry's fields, after the overlay's layout. */
+    order: number;
+    /** The Wallet's overlay hides this field. Presentation only: the field is still returned and still shared. */
+    hidden: boolean;
+    value_type: FieldValueType;
+    secret: boolean;
+    searchable: boolean;
+    immutable: boolean;
+    entry: string;
+    /** The level in effect (ADR-018): the Tenant's for its fields, the overlay's for a custom one; `null` for a plain Field. */
+    reveal: RevealLevel | null;
+    /**
+     * Where the value comes from (ADR-046): `value` — the Field's own; `internal` — `ref` names an ARID, and `value` is
+     * a Field target's value when the reader may read it; `external` — `ref` holds a locator and `value` is `null`.
+     */
+    filled_by: FillMode;
+    /** The reference, for the two reference modes. */
+    ref?: FieldRef;
+    /** `null` while withheld; present after an explicit, audited reveal (or inline at level `visible`). */
+    value: unknown;
+    value_withheld: boolean;
+    /** The Entry's current version no longer declares this field (ADR-029): readable, shareable, deletable, never writable. */
+    retired: boolean;
+}
+/** A self-hosted captcha to answer before a `captcha`-level reveal (ADR-018). */
+export interface Captcha {
+    id: string;
+    /** A `data:image/svg+xml` URI. */
+    image: string;
+    expires_in: number;
+}
+/** What `POST /v0/sessions/current/step-up` answers: when each proven factor lapses. */
+export interface StepUpResult {
+    password_until?: string;
+    mfa_until?: string;
+    amr: string[];
+}
+/** One step of an Entry's location inside its Wallet: an ancestor folder (or nestable file) from the root down. */
+export interface EntryPathNode {
+    arid: string;
+    kind: EntryKind;
+    label: string | null;
+}
+export interface Entry extends ResourceBase {
+    definition: DefinitionPin;
+    /** Pinned to an older version than the latest (ADR-029). */
+    behind: boolean;
+    /** What keeps a behind Entry from the latest version; empty when it fits and only waits for its owner's catch-up. */
+    issues: DefinitionIssue[];
+    wallet: string;
+    /** The folder (or nestable file) the Entry sits in; `null` at the Wallet root. */
+    parent_entry: string | null;
+    /** `file` or `folder` (ADR-014). */
+    kind: EntryKind;
+    /** Ancestors inside the Wallet, root first; empty at the root. The trail a UI renders as breadcrumbs. */
+    path: EntryPathNode[];
+    label?: string;
+    fields: Field[];
+    attachments: string[];
+    /** Direct child Entries by kind. */
+    children: {
+        folders: number;
+        files: number;
+    };
+    /** `children.folders + children.files`. */
+    nested_entries: number;
+    /** `true` when Fields, Attachments or nested Entries were left out for the caller (ADR-027); always `false` for the owner. */
+    partial: boolean;
+}
+/** One node of a Wallet's folder tree (`GET /v0/wallets/{arid}/folders`): folders only, with the files each holds. */
+export interface FolderNode {
+    arid: string;
+    label: string | null;
+    definition: DefinitionRef;
+    files: number;
+    children: FolderNode[];
+}
+export interface WalletFolders {
+    wallet: string;
+    /** Files directly at the Wallet root. */
+    files: number;
+    folders: FolderNode[];
+}
+export interface Attachment extends ResourceBase {
+    filename: string;
+    content_type: string;
+    size: number;
+    bound_to: string;
+}
+/** One item of `GET /v0/trash`: something the vault's owner deleted and can still restore (ADR-036). */
+export interface TrashItem {
+    arid: string;
+    type: "wlt" | "ent" | "fld" | "att";
+    /** The Wallet's name, the Entry's label, the Attachment's file name, the Field's name; null when the item has none. */
+    name: string | null;
+    /** Where it goes back to: a Wallet, an Entry, a Field or the vault. */
+    parent: string;
+    deleted_at: string;
+    restorable_until: string;
+    /** The Principal that deleted it. */
+    deleted_by: string | null;
+    restorable: boolean;
+    /** Why it cannot go back yet: its parent is deleted (restore that first), gone, or blocked / in a Transfer. */
+    reason?: "parent_deleted" | "parent_gone" | "parent_locked";
+}
+/** The answer of `POST /v0/trash/{arid}/restore`. */
+export interface TrashRestoreResult {
+    arid: string;
+    type: TrashItem["type"];
+    parent: string;
+    /** Nodes brought back: the item and everything its deletion took under it. */
+    resources_restored: number;
+    /** Search entries written again for its Fields. */
+    reindexed: number;
+    /** Always false: Grants stay revoked; share again. */
+    grants_restored: false;
+}
+export interface Portfolio extends ResourceBase {
+    name: string;
+    order?: number;
+    description?: string;
+    wallets: string[];
+}
+/**
+ * A Principal as the caller may see it (ADR-024). The caller's own Principal
+ * and the external ones it registered come in full. Any other Customer's
+ * Principal carries only `arid`, `kind`, plus the `handle` and the profile
+ * fields that Customer disclosed through an active Contact — nothing says
+ * whether an e-mail has an account. A `bearer` Principal is the one a link
+ * for anyone opens as (ADR-040): no contact channel, never a Customer.
+ */
+export interface Principal {
+    arid: string;
+    version: number;
+    status: ResourceStatus;
+    kind: "customer" | "external" | "bearer";
+    display_name?: string;
+    contact: {
+        email?: string;
+        phone?: string;
+    };
+    /** Another Customer's handle, when the two are active Contacts. */
+    handle?: string;
+    created_at: string;
+}
+/**
+ * One side of a Contact (`GET /v0/contacts`, ADR-024). `state` is derived from
+ * both sides; `disclosed` is what the other person lets this one see, `handle`
+ * is there whenever the Contact is `active`; `my_disclose` is what this side
+ * lets the other see.
+ */
+export interface Contact extends ResourceBase {
+    principal: string;
+    /** The holder's own label, else the counterpart's handle, else `null`. */
+    label: string | null;
+    note?: string;
+    state: ContactState;
+    origin: ContactOrigin;
+    handle?: string;
+    disclosed: {
+        display_name?: string;
+        name?: string;
+        email?: string;
+        phone?: string;
+    };
+    my_disclose: DisclosableField[];
+    /**
+     * `customer`: another Customer's own Principal. `external`: a Principal for an address, registered by someone.
+     * Every response carries it since Tenant changeset 018; optional so objects built by hand still typecheck.
+     */
+    principal_kind?: "customer" | "external";
+    /**
+     * For an external Principal the caller registered: the name and channel it typed, as `GET /v0/principals/{arid}`
+     * returns them to the caller. `null` for anyone else's Principal, which shows only what it `disclosed`.
+     * Every response carries it since Tenant changeset 018.
+     */
+    registered?: {
+        display_name?: string;
+        email?: string;
+        phone?: string;
+    } | null;
+}
+/**
+ * A direct message as this side sees it (`GET /v0/messages`, ADR-024,
+ * ADR-025): its own sent copy, a message delivered into its vault, or one
+ * still in its mailbox (`read_at: null`). Opening a mailbox message accepts
+ * it into the vault; the sender is never told (no read receipts).
+ */
+export interface Message extends ResourceBase {
+    /** This side's Contact for the other party; `null` once that Contact is gone. */
+    contact: string | null;
+    box: "inbox" | "sent";
+    /** `null` in a listing while the message is still in the mailbox: `GET /v0/messages/:arid` opens it. */
+    body: string | null;
+    in_reply_to: string | null;
+    sent_at: string;
+    read_at: string | null;
+}
+export interface Group extends ResourceBase {
+    name: string;
+    description?: string;
+    owner: boolean;
+    members: string[];
+}
+export interface GrantCondition {
+    trigger?: string;
+    not_before?: string;
+    not_after?: string;
+}
+export interface Grant extends ResourceBase {
+    principal: string;
+    resource: string;
+    resource_type: string;
+    capabilities: Capability[];
+    effect: "allow" | "deny";
+    /** `false`: the Grant covers its own node only (ADR-027). */
+    inherit: boolean;
+    condition: GrantCondition | null;
+    /** The end date inherited from the same principal's Grants above this node, and the Grant it comes from (ADR-027). */
+    inherited: {
+        not_after: string;
+        from: string;
+    } | null;
+    /** The earlier of `condition.not_after` and `inherited.not_after`. */
+    effective_not_after: string | null;
+    state: "pending" | "active" | "expired" | "revoked" | string;
+    issued_by: string;
+    issued_at: string;
+    history: {
+        at: string;
+        by: string;
+        change: string;
+    }[];
+    /** The caller's Contact for the issuer, when one exists (ADR-024) — "shared by <label>" without a second lookup. */
+    issuer_contact?: string | null;
+}
+/** `POST /v0/grants` with `{ grants: [...] }` (ADR-027): the Grants in request order and one notification per recipient. */
+export interface GrantBatchResult {
+    items: Grant[];
+    notifications: {
+        principal: string;
+        notification: string;
+        merged: boolean;
+    }[];
+}
+/**
+ * A guest pass as its sharer sees it (`/v0/passes`, ADR-040): one in the
+ * caller's own vault. `state` is derived: `ended` once an e-mail pass's
+ * Principal signed in, `expired` past `not_after`, `exhausted` when `opens`
+ * reached `max_opens`.
+ */
+export interface Pass {
+    arid: string;
+    version: number;
+    kind: PassKind;
+    /** The caller made this pass (ADR-047). */
+    role: "sharer";
+    /** The Principal it opens as; Grants to it decide what a guest sees. */
+    principal: string;
+    label: string;
+    message: string | null;
+    not_after: string | null;
+    max_opens: number | null;
+    max_sessions: number | null;
+    gate: PassGate;
+    state: PassState;
+    opens: number;
+    last_opened_at: string | null;
+    /** Guest sessions open right now. */
+    live_sessions: number;
+    /** An e-mail pass: the address its code goes to (the sharer's own Principal record). */
+    address?: string;
+    created_at: string;
+    updated_at: string;
+}
+/** `POST /v0/passes`: the pass, its Grants, and — once, for a link for anyone — the token and the link. */
+export interface PassCreated extends Pass {
+    token?: string;
+    url?: string;
+    grants: Grant[];
+    notifications?: {
+        principal: string;
+        notification: string;
+        merged: boolean;
+    }[];
+}
+/** `GET /v0/passes/{arid}`: the pass with the Grants to its Principal that the sharer manages. */
+export interface PassDetail extends Pass {
+    grants: Grant[];
+}
+/**
+ * Someone else's pass that reaches the caller's items (ADR-047): another
+ * Customer holding `share` made it, and Grants to its Principal sit in the
+ * caller's vault. The facts only — never the sharer's label, the message to
+ * its guests or an e-mail pass's address (ADR-024).
+ */
+export interface PassOnYourItems {
+    arid: string;
+    version: number;
+    kind: PassKind;
+    /** The caller owns items the pass reaches. */
+    role: "owner";
+    /** The Principal it opens as: the `principal` of its Grants in your vault. */
+    principal: string;
+    /** Who made it: the Principal that issued its Grants on your items. */
+    issued_by: string;
+    /** Your Contact for that person, when one exists (ADR-024). */
+    issuer_contact: string | null;
+    not_after: string | null;
+    max_opens: number | null;
+    max_sessions: number | null;
+    gate: PassGate;
+    state: PassState;
+    opens: number;
+    last_opened_at: string | null;
+    live_sessions: number;
+    /** Grants to its Principal in your vault that are not revoked. */
+    grant_count: number;
+    created_at: string;
+    updated_at: string;
+}
+/** `GET /v0/passes/{arid}` for an owner: the facts and the Grants in your vault to its Principal. */
+export interface PassOnYourItemsDetail extends PassOnYourItems {
+    grants: Grant[];
+}
+/** One item of `GET /v0/passes`: tell them apart by `role`. */
+export type PassListItem = Pass | PassOnYourItems;
+/** `POST /v0/passes/open`: a guest session (send it as `X-Asturiu-Session`, to `/v0/guest` only). */
+export interface GuestOpened {
+    session: string;
+    kind: "guest";
+    expires_at: string;
+    idle_timeout_seconds: number;
+}
+/** `POST /v0/passes/handover`: the one-time code and where the portal sends the browser with it. */
+export interface PassHandover {
+    handover: string;
+    url: string;
+}
+/** One thing a pass shows: the node a Grant to its Principal names. */
+export interface GuestSharedItem {
+    arid: string;
+    type: string;
+    capabilities: Capability[];
+    /** `false`: this node only (ADR-027). */
+    inherit: boolean;
+    /** A Wallet's name or an Entry's label, when the guest may read it. */
+    name: string | null;
+}
+/** `GET /v0/guest`: what the pass shows and for how long. Nothing about the sharer beyond their message. */
+export interface GuestOverview {
+    message: string | null;
+    kind: PassKind;
+    expires_at: string;
+    items: GuestSharedItem[];
+}
+export type TriggerCondition = {
+    kind: "schedule";
+    at?: string;
+    every_seconds?: number;
+} | {
+    kind: "inactivity";
+    period_seconds: number;
+} | {
+    kind: "signal";
+};
+export type TriggerActionInput = {
+    kind: "activate_grant";
+    grant: string;
+} | {
+    kind: "activate_grants";
+    principal: string;
+    within: string;
+} | {
+    kind: "notify";
+    principal: string;
+    message?: string;
+} | {
+    kind: "mark_entry";
+    resource: string;
+    mark?: Record<string, unknown>;
+} | {
+    kind: "start_transfer";
+    resource: string;
+    principal: string;
+};
+export interface Trigger extends ResourceBase {
+    name?: string;
+    condition: TriggerCondition;
+    actions: (TriggerActionInput & Record<string, unknown>)[];
+    state: "armed" | "fired" | "disarmed" | string;
+    due_at: string | null;
+    last_signal_at: string | null;
+    /** Only on creation of a `signal` Trigger; never returned again. */
+    signal_token?: string;
+}
+export interface Event {
+    arid: string;
+    subject_type: "customer" | "resource" | "tenant" | string;
+    subject: string;
+    type: string;
+    actor: string;
+    at?: string;
+    created_at?: string;
+    detail?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface Notification extends ResourceBase {
+    title: string;
+    kind: string;
+    detail: Record<string, unknown>;
+    channel?: string;
+    state: "pending" | "delivered" | "acknowledged" | "failed" | string;
+    attempts: number;
+}
+export interface Transfer extends ResourceBase {
+    resource: string;
+    resource_type?: string;
+    principal: string;
+    state: "offered" | "accepted" | "declined" | "withdrawn" | "completed" | string;
+    offered_by?: string;
+    offered_at?: string;
+    /** What the sender keeps after completion (ADR-019); `null` when nothing. */
+    retain?: {
+        capabilities: string[];
+        not_after: string | null;
+        grants: string[];
+    } | null;
+    /** Grants other Principals hold on the subtree: carried to the recipient or revoked at completion. */
+    existing_grants?: "keep" | "revoke";
+    /** Set once completed: what happened to the Grants on the subtree. */
+    outcome?: {
+        retained: string[];
+        carried: number;
+        revoked: number;
+    } | null;
+    /** The recipient's Contact for the sender, when one exists (ADR-024). */
+    from_contact?: string | null;
+    [key: string]: unknown;
+}
+/** What a field search looks for (ADR-046, decision 10): a value (the default), a locator or an ARID. */
+export type SearchMatch = "value" | "locator" | "arid";
+export interface SearchResult {
+    index_type: string;
+    match?: SearchMatch;
+    items: ({
+        type: "prn";
+    } & Principal)[] | {
+        type: "fld";
+        arid: string;
+        entry: string;
+        name: string;
+    }[];
+}
+export interface Health {
+    status: "ready" | "degraded";
+    component: string;
+    dependencies: Record<string, string>;
+}
+/** `GET /v0/portal/presentation?host=` (ADR-020): which Tenant a portal host serves, and how to show and sign in to it. No session. */
+export interface PortalPresentation {
+    tenant: {
+        arid: string;
+        slug: string;
+        name: string;
+    };
+    state: "active" | "paused" | "frozen";
+    message: string;
+    /** Public branding only: `logo_url`, `logo_dark_url`, `favicon_url`, `primary_color`, `product_url`, `app_url`, `portal_url`, `billing_url`, `support_url`, `support_email`. Images are inline base64 only (ADR-038); one stored as a URL is left out. */
+    branding: Record<string, string>;
+    /** The Tenant's portal theme (ADR-033), as validated when it was written, with inline images only (ADR-038); `{}` when it has none. Read it through `resolvePortalTheme`. Absent from an Interface API older than 2026-10-07. */
+    theme?: PortalThemeSpec;
+    /**
+     * `backend` is `shared`, `isolated`, `source` or `direct` (ADR-021). Authentik backends carry `authentik_slug`; `direct` carries its `issuer`.
+     * `client_ids` lists every OIDC client of the Tenant's Application (the main one first); the portal's relay refuses any other on this host (ADR-032).
+     */
+    sign_in: {
+        backend: "shared" | "isolated" | "source" | "direct";
+        client_id: string | null;
+        client_ids: string[];
+        authentik_slug: string | null;
+        issuer: string | null;
+    };
+    /** Where the person manages the sign-in they may share with other services (ADR-022). */
+    security: {
+        mode: "neutral" | "brokered";
+    };
+    /** Who runs payments (ADR-067): the Tenant (`billing_url`), or the Engine on the Tenant's own account (`/v0/plans`, `/v0/customer/subscriptions`). */
+    billing: {
+        collection: "tenant" | "connected";
+        billing_url: string | null;
+    };
+    /** The day this Tenant closes, while its notice runs (ADR-064 §7). */
+    closing_at: string | null;
+    /**
+     * Portal options (ADR-037): the switches (`account_link`, `open_app`, `back_link`, `language_menu`, `appearance`) and where each page lives (`pages.<page>`: `portal`, `redirect` with a `url`, or `off`), defaults filled.
+     * Read it through `resolvePortalOptions`: an Interface API older than 2026-10-07 sends only `account_link`, or nothing.
+     */
+    portal?: Partial<PortalOptions>;
+    /** Guest passes (ADR-040): whether e-mail passes are on, where they open, and the Tenant app's pass page. Absent from an Interface API older than 2026-10-12: off. */
+    passes?: PassPresentation;
+    /** Whether the Tenant takes new Customers (ADR-044): `closed` hides sign-up and joining. Absent from an Interface API older than 2026-10-13: open. */
+    enrolment?: EnrolmentState;
+}
+/** One of the Customer's (or, on `/v0/me`, the User's) sessions, by opaque handle. */
+export interface SessionListItem {
+    handle: string;
+    current: boolean;
+    label: string;
+    created_at: string;
+    last_seen_at: string;
+    expires_at: string;
+    /** `/v0/me/sessions` only: which product the session is on, or `null` for the platform sign-in page. */
+    product?: string | null;
+}
+/** `DELETE /v0/customer` with the confirmation token. */
+export interface CustomerDeleted {
+    arid: string;
+    status: "deleted";
+    resources_deleted: number;
+    grants_revoked: number;
+    sessions_dropped: number;
+    user_deleted: boolean;
+    /** What happened to the sign-in (ADR-020): deactivated with the last Customer, or removed from this product only. */
+    account: "deactivated" | "left_tenant" | "none";
+    account_remove_after: string | null;
+    retention_days: number;
+}
+/** An enrolled second factor, by opaque handle. */
+export interface SignInFactor {
+    handle: string;
+    kind: string;
+    name: string;
+    created_at: string | null;
+    last_used_at: string | null;
+}
+/**
+ * `GET /v0/customer/sign-in` (ADR-022, `brokered` mode): the sign-in this
+ * Customer uses. `shared` says whether it also opens other services — never
+ * which ones or how many.
+ */
+export interface CustomerSignIn {
+    backend: "shared" | "isolated" | "source" | "direct";
+    shared: boolean;
+    username: string | null;
+    email: string | null;
+    factors: SignInFactor[];
+    /** Where to change the password (the Tenant's own flow); null when the Tenant's issuer owns it. */
+    password_change_url: string | null;
+    /** A policy this sign-in must keep because some service using it requires it; fixed text, no names. */
+    policy: {
+        require_2fa: boolean;
+    };
+}
+/** `GET /v0/me` (ADR-022): the person's own profile on the platform sign-in page. No ARIDs. */
+export interface MeProfile {
+    handle?: string;
+    display_name?: string;
+    name?: string;
+    email?: string;
+    email_verified?: boolean;
+    phone?: string;
+    username: string | null;
+}
+/** `GET /v0/me/products`: where this sign-in is used. Only here, only to the person. */
+export interface MeProduct {
+    name: string;
+    portal_url: string | null;
+    app_url: string | null;
+    /** Inline base64 only (ADR-038); null when the Tenant has none or still stores a URL. */
+    logo_url: string | null;
+    status: "active" | "suspended";
+}
+export interface MeSecurity {
+    username: string | null;
+    email: string | null;
+    factors: SignInFactor[];
+    password_change_url: string | null;
+    policy: {
+        require_2fa: boolean;
+    };
+}
+/** `GET /v0/attention` (ADR-029): what catch-up could not move to the latest version, for the vault's owner. */
+export interface AttentionItem {
+    arid: string;
+    type: "ent" | "wlt";
+    wallet: string | null;
+    definition: DefinitionPin;
+    issues: number;
+}
+export interface Attention {
+    /** The Definition revision the vault was last caught up to. */
+    revision: number;
+    items: AttentionItem[];
+}
+//# sourceMappingURL=types.d.ts.map