@oxy.so/core 1.18.1 → 3.0.0

package/dist/types/api/accounts.d.ts

@@ -0,0 +1,415 @@
+/**
+ * `oxy.accounts` — the unified account graph (`/accounts`).
+ *
+ * An account is a relational, tree-structured principal (the `User` document
+ * generalised): a `personal` account is a human login at the root of its tree;
+ * `organization` / `project` / `bot` / `channel` accounts are non-login
+ * principals operated through membership. Accounts form a tree
+ * (`parentAccountId`) and expose a single membership model (`AccountMember`)
+ * with a unified role set and an explicit-but-inheritable cascade down the
+ * subtree. The applications an account owns are `oxy.apps`.
+ *
+ * Reference accounts by their `_id` (`accountId`, the underlying `User._id`)
+ * and members by their member `_id` — never by name, slug, or handle.
+ *
+ * SWITCHING INTO AN ACCOUNT: `accounts.actAs(accountId)` mints a REAL
+ * session for the target account and plants it as the active session — there is
+ * no per-request "acting-as" header. Identity is carried by the session/token,
+ * so a switch propagates through reload and cross-domain exactly like a login.
+ */
+import type { User } from '../models/interfaces';
+import type { AccountCategoryId, AccountKind, ChildAccountKind } from '@oxy.so/contracts';
+import type { SessionLoginResponse } from '../models/session';
+import type { OxyContext } from '../client/context';
+/**
+ * Account classification, orthogonal to the federation `type`
+ * (`local|federated|agent|automated`). `personal` accounts have a direct login;
+ * `organization` / `project` / `bot` / `channel` accounts are operated via
+ * `AccountMember` and have no direct login. Of those, only the first three may
+ * be acted AS by an application (`isDelegatedActAsEligibleKind`), and only the
+ * first two may be SWITCHED INTO by a person (`isOperatorSwitchTargetKind`).
+ *
+ * Single source of truth is `@oxy.so/contracts`.
+ */
+export type { AccountCategoryId, AccountKind } from '@oxy.so/contracts';
+export { ACCOUNT_CATEGORY_IDS, ACCOUNT_KINDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from '@oxy.so/contracts';
+/**
+ * The calling user's relationship to an account node, as resolved by the API:
+ * - `self` — the caller's own personal (root) account.
+ * - `owner` — an account the caller owns (e.g. an org/project/bot they created).
+ * - `member` — an account shared with the caller via membership (including
+ *   external organisations).
+ */
+export type AccountRelationship = 'self' | 'owner' | 'member';
+/** Role a member holds within an account. The unified account role set. */
+export type AccountRole = 'owner' | 'admin' | 'editor' | 'developer' | 'billing' | 'viewer';
+/** Membership lifecycle status. */
+export type AccountMemberStatus = 'active' | 'invited' | 'removed';
+/**
+ * Origin of a resolved membership. `direct` is a membership row on the account
+ * itself; `inherited` is resolved from the nearest ancestor account whose
+ * membership row has `inherit: true` (role inheritance cascades down the tree).
+ */
+export type AccountMemberSource = 'direct' | 'inherited';
+/**
+ * Client-facing AccountMember shape. `permissions` is the effective permission
+ * set (role baseline plus `permissionGrants` minus `permissionRevokes`).
+ */
+export interface AccountMember {
+    _id: string;
+    /** The account this membership grants access to (account `_id`). */
+    accountId: string;
+    /** The member's personal-account `User._id`. */
+    memberUserId: string;
+    role: AccountRole;
+    permissions: string[];
+    /** Permissions granted beyond the role baseline. */
+    permissionGrants?: string[];
+    /** Permissions revoked from the role baseline. */
+    permissionRevokes?: string[];
+    /**
+     * Whether this membership cascades to the account's subtree. `true` (default)
+     * lets descendants inherit this role unless a nearer row overrides it; `false`
+     * opts this row out of inheritance (it applies to this account only).
+     */
+    inherit: boolean;
+    status: AccountMemberStatus;
+    /**
+     * Where this membership COMES FROM relative to the account it is being
+     * reported for: `direct` when the row lives on that account, `inherited` when
+     * it lives on an ancestor whose `inherit` flag cascades it down.
+     *
+     * Present on every membership the API serialises — a resolved
+     * `callerMembership` and every entry of a member list alike. It is not
+     * decoration: an `inherited` entry's `accountId` is the ANCESTOR's, and the
+     * member-mutation endpoints are scoped to rows on the account named in the
+     * path, so `PATCH`/`DELETE .../members/<that row's _id>` against the
+     * descendant 404s. **Branch on `source === 'direct'` before offering to edit,
+     * remove or transfer to a member**, and count owners for a last-owner check
+     * over direct entries only.
+     */
+    source: AccountMemberSource;
+    invitedByUserId?: string | null;
+    joinedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * A node in the account graph as returned by the `/accounts` API. `account` is
+ * the underlying generalised `User` document; `relationship` and
+ * `callerMembership` describe the caller's access. On a flat list every node
+ * carries `parentAccountId`; with `tree:true`, `children` is populated and
+ * `childCount` reflects the number of direct children.
+ */
+export interface AccountNode {
+    /** The account's Mongo `_id` (the underlying `User._id`). */
+    accountId: string;
+    kind: AccountKind;
+    /** Parent account `_id`, or `null` for a root (personal) account. */
+    parentAccountId: string | null;
+    /** The generalised `User` document backing this account. */
+    account: User;
+    relationship: AccountRelationship;
+    /**
+     * The caller's effective membership in this account (direct or inherited), or
+     * `null` when the caller has no membership (e.g. their own `self` root, where
+     * ownership is implicit). Use `callerMembership.permissions` to gate UI.
+     */
+    callerMembership: AccountMember | null;
+    /** Number of direct child accounts (present when the API computes it). */
+    childCount?: number;
+    /** Direct children, populated when the list is requested with `tree:true`. */
+    children?: AccountNode[];
+}
+/** Options accepted by `accounts.list`. */
+export interface ListAccountsOptions {
+    /**
+     * When `true`, request the nested tree representation: each returned node has
+     * its `children` populated instead of a flat list keyed by `parentAccountId`.
+     */
+    tree?: boolean;
+}
+/** Input accepted by `accounts.create`. */
+export interface CreateAccountInput {
+    /**
+     * Classification of the new account. Every CHILD kind is creatable here with
+     * the caller's own bearer, `channel` included: a signed-in person has already
+     * proven who they are, and minting a child under their own tree is the same
+     * operation whichever kind it is.
+     *
+     * `channel` used to be excluded, on the reasoning that channels are
+     * service-provisioned only. What actually makes a channel safe does not depend
+     * on who creates it: `createChildAccount` writes no auth method, so it is born
+     * with no login, and `POST /accounts/:id/switch` refuses it via
+     * both act-as predicates, so no session can ever have a channel as its subject
+     * and therefore no bearer exists that could add one. `personal` is excluded
+     * because it is a human login, minted at signup.
+     */
+    kind: ChildAccountKind;
+    /**
+     * Parent account `_id` to nest the new account under. Omitted → the API roots
+     * it under the caller's personal account.
+     */
+    parentAccountId?: string;
+    /** Unique handle for the account (shares the `User.username` unique index). */
+    username: string;
+    /**
+     * A managed account (organization / project / bot / channel) has a TITLE, not
+     * a given-and-family name, so it sets `displayName` — the explicit
+     * `name_display` column — and leaves `first`/`last` unset. Splitting a title
+     * on whitespace into `first`/`last` is what this replaced.
+     */
+    name?: {
+        first?: string;
+        last?: string;
+        displayName?: string;
+    };
+    bio?: string;
+    avatar?: string;
+    /**
+     * Named color preset KEY — `'blue'`, `'mint'`, … — never a hex value. The
+     * account graph's half of `User.color`, which every account DTO already
+     * carries; this is how one gets WRITTEN for an account you administer.
+     *
+     * Set it HERE rather than after the fact. For a managed account the colour is
+     * a visual identity, and an account that is discoverable without one and
+     * acquires it on a second request is a face that changes by itself.
+     *
+     * Omitted is not "no colour": the platform assigns a random preset, exactly as
+     * it did before this field existed. A reserved preset is refused unless the
+     * account has a claim to it — the administrator's own entitlements are not the
+     * ones weighed.
+     */
+    color?: string;
+    /**
+     * What the account is about. ORDERED — the FIRST element is the primary
+     * category, so a picker must submit them in the order the user arranged them
+     * and must not sort. Stable ids, never labels: render each one through the
+     * `accounts.accountCategory.<id>` translation key.
+     *
+     * Offer `SELECTABLE_ACCOUNT_CATEGORY_IDS`, not `ACCOUNT_CATEGORY_IDS` — the
+     * latter still contains withdrawn ids so that accounts already carrying one
+     * keep working. At most `MAX_ACCOUNT_CATEGORIES`, no duplicates.
+     */
+    accountCategories?: AccountCategoryId[];
+    /**
+     * Create the account already opted OUT of discovery — kept out of people
+     * search, the follow-graph lists, `/similar` and the recommendation pools,
+     * with non-public media follower-gated.
+     *
+     * Pass `true` when the account is not something its owner has published yet:
+     * an agent, an unlaunched project, an organization for something unannounced.
+     * OMITTED IS NOT `false` IN MEANING, only in effect — saying nothing leaves
+     * the platform default, which is discoverable, and that default is not
+     * changed by this option existing.
+     *
+     * Setting it later is `PUT /users/:userId/privacy`, which needs the ACCOUNT's
+     * own bearer. Passing it here is the only way to have the account never be
+     * discoverable at all, rather than discoverable until a second call lands.
+     */
+    isPrivateAccount?: boolean;
+}
+/** Input accepted by `accounts.update`. Tree placement changes go through `/move`. */
+export interface UpdateAccountInput {
+    username?: string;
+    /**
+     * Same shape as `CreateAccountInput['name']`. On update, an EMPTY STRING in
+     * `displayName` clears the explicit name and falls back to the composed
+     * `first`/`last`; omitting the key leaves the stored value untouched. The two
+     * are not interchangeable.
+     */
+    name?: {
+        first?: string;
+        last?: string;
+        displayName?: string;
+    };
+    bio?: string | null;
+    avatar?: string | null;
+    /**
+     * Named color preset KEY, same vocabulary as `CreateAccountInput['color']`.
+     *
+     * NOT nullable, unlike `bio` and `avatar`: the column is `NOT NULL` with a
+     * default, so an account always HAS a colour and there is no "clear" to
+     * express. Sending the value the account already carries is always accepted,
+     * so a client may PATCH back the object it was served.
+     */
+    color?: string;
+    /**
+     * Replaces the WHOLE list, in the order given — there is no add/remove verb,
+     * because a partial edit cannot express a re-ordering and the order is what
+     * names the primary category. `[]` clears it.
+     *
+     * Not nullable, unlike `bio` and `avatar`: the empty case already has a
+     * spelling of its own, so a second one could only ever disagree with it.
+     *
+     * Rejected for a `personal` account, and rejected when it ADDS a withdrawn
+     * id the account did not already carry — keeping or re-ordering one it has is
+     * always allowed.
+     */
+    accountCategories?: AccountCategoryId[];
+}
+/** Input accepted by `accounts.members.invite`. The owner role cannot be invited. */
+export interface InviteAccountMemberInput {
+    /**
+     * The username or email of the user to invite. Resolved to a personal account
+     * server-side; an unknown value yields a 404 "User not found".
+     */
+    usernameOrEmail: string;
+    role: Exclude<AccountRole, 'owner'>;
+}
+/** Input accepted by `accounts.members.update`. The owner role cannot be assigned. */
+export interface UpdateAccountMemberInput {
+    role?: Exclude<AccountRole, 'owner'>;
+    inherit?: boolean;
+    permissionGrants?: string[];
+    permissionRevokes?: string[];
+}
+/** Input accepted by `accounts.transferOwnership`. */
+export interface TransferAccountOwnershipInput {
+    userId: string;
+}
+/** Result of an archive/remove/revoke/transfer/delete operation. */
+export interface AccountSuccessResult {
+    success: boolean;
+}
+/**
+ * Result of {@link AccountsApi.actAs} — the freshly
+ * minted session for the target account, in the SAME shape the canonical login
+ * / `claimSessionByToken` responses use (`SessionLoginResponse`).
+ *
+ * `accessToken` is the first access token for the new session (already planted
+ * as the active token by `actAs`). The switched session's survival
+ * across reload and cross-domain sync is device-first: the server registers
+ * it into the operator's `DeviceSession` set directly
+ * (`deviceSessionService.addAccount`, broadcast to the device room) — there is
+ * no client-side refresh-cookie slot to establish. `user` is the target
+ * account.
+ */
+export interface SwitchAccountResult extends SessionLoginResponse {
+    /**
+     * Legacy device-local refresh-cookie slot index. The current server switch
+     * response never sets this field (device-set registration replaced the
+     * cookie-slot model) — kept optional for backward type-compatibility with
+     * any caller still reading it, but always `undefined` in practice.
+     */
+    authuser?: number;
+}
+/** `oxy.accounts.members` — who can act on an account, and with what role. */
+export declare class AccountMembersApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /**
+     * List the members of an account: the membership rows ON it, plus the rows
+     * on its ancestors that cascade into it. Each entry carries `source`
+     * (`direct` | `inherited`) saying which it is.
+     *
+     * Inherited entries are members in every sense the server enforces — an
+     * ancestor row with `inherit: true` confers every account permission on the
+     * descendant, `account:act_as` included.
+     *
+     * An entry's `accountId` is the account its ROW lives on, so an inherited
+     * entry names an ancestor; and the member-mutation endpoints only accept rows
+     * on the account in the path, so gate any edit/remove/transfer affordance on
+     * `source === 'direct'`.
+     *
+     * To ask what the CALLER holds over an account, use `accounts.get`, whose
+     * `callerMembership` is the server's own resolution.
+     *
+     * @param accountId - The account's `_id`.
+     */
+    list(accountId: string): Promise<AccountMember[]>;
+    /**
+     * Add a member to an account.
+     * @param accountId - The account's `_id`.
+     * @param data - Target user's username or email and role (never `owner`).
+     *   The server resolves `usernameOrEmail` to a personal account; an unknown
+     *   value yields a 404 "User not found".
+     */
+    invite(accountId: string, data: InviteAccountMemberInput): Promise<AccountMember>;
+    /**
+     * Change a member's role or inheritance.
+     * @param accountId - The account's `_id`.
+     * @param memberId - The member's `_id`.
+     * @param data - New role (never `owner`), inheritance, permission overrides.
+     */
+    update(accountId: string, memberId: string, data: UpdateAccountMemberInput): Promise<AccountMember>;
+    /**
+     * Remove a member from an account.
+     * @param accountId - The account's `_id`.
+     * @param memberId - The member's `_id`.
+     */
+    remove(accountId: string, memberId: string): Promise<AccountSuccessResult>;
+}
+export declare class AccountsApi {
+    private readonly ctx;
+    /** Who can act on an account, and with what role. */
+    readonly members: AccountMembersApi;
+    constructor(ctx: OxyContext);
+    /**
+     * List the accounts the caller can access: their own personal (root)
+     * account, accounts they own, and accounts shared with them (including
+     * external organisations), plus the reachable subtree of each.
+     *
+     * @param opts - `{ tree: true }` requests the nested tree representation
+     *   (`children` populated) instead of a flat list. The flag is part of the
+     *   path (`?tree=true`), so the flat and tree variants never share a cache key.
+     */
+    list(opts?: ListAccountsOptions): Promise<AccountNode[]>;
+    /**
+     * Fetch a single account node by id.
+     * @param accountId - The account's `_id`.
+     */
+    get(accountId: string): Promise<AccountNode>;
+    /**
+     * Switch the active session INTO a managed account.
+     *
+     * `POST /accounts/:id/switch` with the signed-in operator's bearer. The
+     * server authorises the operator (must hold `account:act_as` over the
+     * target, directly or inherited — else 403; 404 if missing/archived; 403 if
+     * the target is a personal account), then mints a REAL session for the
+     * target account in the canonical login shape.
+     *
+     * The returned session IS the new identity: its `accessToken` is planted as
+     * the active token, so every subsequent request authenticates as the target
+     * account. The server registers the switched session into the operator's
+     * device set, so the switch survives a reload and syncs cross-domain like a
+     * normal login.
+     *
+     * The SDK's identity-scoped GET cache is then fully cleared so every cached
+     * read re-fetches as the new account (a same-user token refresh deliberately
+     * keeps the warm cache, so the sweep here is explicit).
+     *
+     * @param accountId - The target account's `_id`.
+     * @returns The minted session, already planted as the active session.
+     */
+    actAs(accountId: string): Promise<SwitchAccountResult>;
+    /**
+     * Create a new (non-personal) account. The caller becomes its `owner`.
+     * @param data - Account configuration: kind, optional parent, and profile.
+     */
+    create(data: CreateAccountInput): Promise<AccountNode>;
+    /**
+     * Update an account's mutable profile fields. Tree placement changes
+     * (reparenting) go through the dedicated move endpoint, not here.
+     *
+     * An account IS a user, so this write changes identity: every identity read
+     * of it (`GET /users/<id>`, `GET /profiles/username/<handle>`, …) is evicted
+     * too, not only the account-graph keys — see `evictOxyIdentityCache`.
+     *
+     * @param accountId - The account's `_id`.
+     * @param data - Subset of updatable profile fields.
+     */
+    update(accountId: string, data: UpdateAccountInput): Promise<AccountNode>;
+    /**
+     * Archive an account (soft delete). Not `users.deleteMe`, which is the GDPR
+     * self-deletion flow.
+     * @param accountId - The account's `_id`.
+     */
+    archive(accountId: string): Promise<AccountSuccessResult>;
+    /**
+     * Transfer ownership of an account to another member (owner only).
+     * @param accountId - The account's `_id`.
+     * @param data - Target user id.
+     */
+    transferOwnership(accountId: string, data: TransferAccountOwnershipInput): Promise<AccountSuccessResult>;
+}

package/dist/types/api/agency.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `oxy.agency` — native Alia and digital-agent authority.
+ *
+ * Oxy-owned delegation grants, account autonomy policy, execution
+ * authorizations and their audit trail. These use the signed-in account
+ * session: capability tickets and app service credentials stay on the server
+ * and are never exposed to Settings clients.
+ */
+import type { AppCapabilityCatalog, AuditEvent, AutonomyLevel, CapabilityCatalogBinding, CapabilityPackage, DelegationGrant, GrantLimit, ResourceRef, ToolGrantOverride } from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+export type DelegationCatalogBinding = CapabilityCatalogBinding;
+export type DelegationGrantView = DelegationGrant;
+export interface CreateDelegationGrantInput {
+    ownerAccountId: string;
+    actorAccountId: string;
+    resource: ResourceRef;
+    capabilityPackages: CapabilityPackage[];
+    capabilities: string[];
+    toolOverrides?: ToolGrantOverride[];
+    limits?: GrantLimit[];
+    maximumAutonomy: AutonomyLevel;
+    canRedelegate?: boolean;
+    expiresAt?: string | null;
+}
+export type UpdateDelegationGrantInput = Pick<CreateDelegationGrantInput, 'capabilityPackages' | 'capabilities' | 'toolOverrides' | 'limits' | 'maximumAutonomy' | 'canRedelegate' | 'expiresAt'>;
+export interface AvailableCapabilityCatalog {
+    id: string;
+    appId: string;
+    version: string;
+    digest: string;
+    audience: string;
+    catalog: AppCapabilityCatalog;
+}
+export interface AccountCapabilityPolicy {
+    id: string;
+    accountId: string;
+    appSlug: string;
+    maximumAutonomy: AutonomyLevel;
+    deniedCapabilities: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PutAccountCapabilityPolicyInput {
+    accountId: string;
+    maximumAutonomy: AutonomyLevel;
+    deniedCapabilities: string[];
+}
+export interface CapabilityExecutionAuthorization {
+    id: string;
+    kind: 'direct_request' | 'automation';
+    requesterAccountId: string;
+    ownerAccountId: string;
+    coordinatorApplicationId: string;
+    coordinatorCredentialId: string;
+    actorType: 'alia' | 'agent';
+    actorAccountId: string | null;
+    resourceApp: string;
+    effectiveAccountId: string;
+    resourceType: string;
+    resourceKey: string;
+    tool: string;
+    runId: string | null;
+    stepId: string | null;
+    automationId: string | null;
+    maximumAutonomy: AutonomyLevel;
+    limits: GrantLimit[];
+    expiresAt: string;
+    revokedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A present-requester assertion minted for a product backend (ADR 0025). */
+export interface RequesterAssertionGrant {
+    assertion: string;
+    expiresAt: string;
+    requesterAccountId: string;
+    agentId: string;
+}
+/** Oxy's live answer to the audience that consumed an assertion (ADR 0025). */
+export interface RequesterAssertionIntrospection {
+    active: boolean;
+    requesterAccountId?: string;
+    agentId?: string;
+    applicationId?: string;
+    credentialId?: string;
+    jti?: string;
+    expiresAt?: string;
+}
+/** `oxy.agency.grants` — what an owner account delegated to an actor. */
+export declare class DelegationGrantsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** The delegation grants an owner account issued. */
+    list(ownerAccountId: string): Promise<DelegationGrantView[]>;
+    /** Issue a delegation grant. */
+    create(input: CreateDelegationGrantInput): Promise<DelegationGrantView>;
+    /** Change a grant's capabilities, limits or autonomy. */
+    update(grantId: string, ownerAccountId: string, input: UpdateDelegationGrantInput): Promise<DelegationGrantView>;
+    /** Revoke a grant. */
+    revoke(grantId: string, ownerAccountId: string): Promise<void>;
+}
+/** `oxy.agency.policies` — an account's per-app autonomy policy. */
+export declare class CapabilityPoliciesApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** An account's capability policies, one per app. */
+    list(accountId: string): Promise<AccountCapabilityPolicy[]>;
+    /** Set an account's policy for one app. */
+    put(appId: string, input: PutAccountCapabilityPolicyInput): Promise<AccountCapabilityPolicy>;
+    /** Drop an account's policy for one app. */
+    delete(appId: string, accountId: string): Promise<void>;
+}
+/** `oxy.agency.authorizations` — live execution authorizations. */
+export declare class ExecutionAuthorizationsApi {
+    private readonly ctx;
+    constructor(ctx: OxyContext);
+    /** An owner account's execution authorizations. */
+    list(ownerAccountId: string): Promise<CapabilityExecutionAuthorization[]>;
+    /** Revoke an execution authorization. */
+    revoke(authorizationId: string, ownerAccountId: string): Promise<void>;
+}
+export declare class AgencyApi {
+    protected readonly ctx: OxyContext;
+    /** What an owner account delegated to an actor. */
+    readonly grants: DelegationGrantsApi;
+    /** An account's per-app autonomy policy. */
+    readonly policies: CapabilityPoliciesApi;
+    /** Live execution authorizations. */
+    readonly authorizations: ExecutionAuthorizationsApi;
+    constructor(ctx: OxyContext);
+    /** The capability catalogs available to an account. */
+    catalogs(accountId: string): Promise<AvailableCapabilityCatalog[]>;
+    /** An account's capability audit trail. */
+    auditEvents(accountId: string): Promise<AuditEvent[]>;
+}

package/dist/types/api/appData.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `oxy.appData` — a small per-user JSON key/value store (`/users/me/app-data`).
+ *
+ * For cross-device app state: course progress, "last viewed" markers,
+ * dismissed banners. Not for blobs or anything that needs querying.
+ *
+ * - `namespace` and `key` must match `[a-z0-9_-]{1,64}` (checked here first).
+ * - Values are capped at 64 KB; writes at 100/minute/user (server-enforced).
+ */
+import type { OxyContext } from '../client/context';
+/** Thrown when a namespace or key is not `[a-z0-9_-]{1,64}`. */
+export declare class OxyAppDataIdentifierError extends Error {
+    constructor(field: 'namespace' | 'key', value: string);
+}
+export declare class AppDataApi {
+    protected readonly ctx: OxyContext;
+    constructor(ctx: OxyContext);
+    /** The value under `(namespace, key)`, or `null` when nothing is stored. */
+    get<T = unknown>(namespace: string, key: string): Promise<T | null>;
+    /** Store `value` under `(namespace, key)`; returns what the server stored. */
+    set<T = unknown>(namespace: string, key: string, value: T): Promise<T>;
+    /** Delete `(namespace, key)`. Idempotent. */
+    delete(namespace: string, key: string): Promise<void>;
+    /** Every entry in `namespace` (an empty object when there are none). */
+    list<T = unknown>(namespace: string): Promise<Record<string, T>>;
+    private path;
+}