@oxy.so/core 1.18.0 → 3.0.0

package/dist/esm/OxyServices.js

@@ -1,66 +1,271 @@
-import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors.js';
-// Import mixin composition helper
-import { composeOxyServices } from './mixins/index.js';
 /**
- * OxyServices - Unified client library for interacting with the Oxy API
+ * `OxyServices` — the Oxy API client.
  *
- * This class provides all API functionality in one simple, easy-to-use interface.
+ * ```ts
+ * import { OxyServices } from '@oxy.so/core';
  *
- * ## Architecture
- * - **HttpService**: Unified HTTP service handling authentication, caching, deduplication, queuing, and retry
- * - **OxyServices**: Provides high-level API methods
+ * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
  *
- * ## Mixin Composition
- * The class is composed using TypeScript mixins for better code organization:
- * - **Base**: Core infrastructure (HTTP client, request management, error handling)
- * - **Auth**: Authentication and session management
- * - **User**: User profiles, follow, notifications
- * - **Privacy**: Blocked and restricted users
- * - **Language**: Language detection and metadata
- * - **Payment**: Payment processing
- * - **Reputation**: Reputation system (Oxy Trust)
- * - **Assets**: File upload and asset management
- * - **Accounts**: Unified account graph (tree, members, roles, bot credentials)
- *   and the applications owned within it (Application = OAuth client)
- * - **Connected apps**: OAuth-consent surface (public app identity, grants)
- * - **Location**: Location-based features
- * - **Analytics**: Analytics tracking
- * - **Devices**: Device management
- * - **Utility**: Utility methods and Express middleware
- *
- * @example
- * ```typescript
- * const oxy = new OxyServices({
- *   baseURL: 'https://api.oxy.so',
- *   cloudURL: 'https://cloud.oxy.so'
- * });
+ * const me = await oxy.users.me();
+ * const people = await oxy.users.getMany(ids);
+ * const { id } = await oxy.assets.upload(file);
+ * await oxy.follows.follow(userId);
  * ```
+ *
+ * The client itself is small — the transport (`request`, `http`), the response
+ * cache, and `createLinkedClient` for an app's own backend. Everything else is a
+ * namespace (`oxy.users`, `oxy.assets`, …), created on first access and kept for
+ * the client's life.
+ *
+ * Servers use `OxyServer` from `@oxy.so/core/server`: the same client plus the
+ * service-token lane and the Express / Socket.IO middleware.
  */
-// Compose all mixins into the final OxyServices class. The composed runtime
-// class augments OxyServicesBase with every mixin's methods (see mixins/index.ts).
-// Statically, TypeScript sees this as a constructor producing OxyServicesBase;
-// the additional methods are exposed via interface merging on `OxyServices` below.
-const OxyServicesComposed = composeOxyServices();
-// Export as a named class to avoid TypeScript issues with anonymous class types.
-// We extend the composed constructor directly — its public surface is broadened
-// to the full mixin set via the interface declaration that follows.
-export class OxyServices extends OxyServicesComposed {
+import { HttpService } from './HttpService.js';
+import { toOxyApiError } from './OxyServices.errors.js';
+import { SessionApi } from './api/session.js';
+import { AuthApi } from './api/auth.js';
+import { UsersApi } from './api/users.js';
+import { FollowsApi } from './api/follows.js';
+import { PrivacyApi } from './api/privacy.js';
+import { NotificationsApi } from './api/notifications.js';
+import { AssetsApi } from './api/assets.js';
+import { IdentityApi } from './api/identity.js';
+import { AccountsApi } from './api/accounts.js';
+import { AppsApi } from './api/apps.js';
+import { LinkedAccountsApi } from './api/linkedAccounts.js';
+import { AgencyApi } from './api/agency.js';
+import { StoreApi } from './api/store.js';
+import { BillingApi } from './api/billing.js';
+import { ReputationApi } from './api/reputation.js';
+import { CivicApi } from './api/civic.js';
+import { NodesApi } from './api/nodes.js';
+import { DevicesApi } from './api/devices.js';
+import { TopicsApi } from './api/topics.js';
+import { AppDataApi } from './api/appData.js';
+import { ContactsApi } from './api/contacts.js';
+/** Default Oxy Cloud URL — used when no `cloudURL` is given. */
+export const OXY_CLOUD_URL = 'https://cloud.oxy.so';
+/** Default Oxy API URL. */
+export const OXY_API_URL = 'https://api.oxy.so';
+export class OxyServices {
     constructor(config) {
-        super(config);
+        /** The response cache (GETs only, identity-scoped). */
+        this.cache = {
+            /** Drop every cached response. */
+            clear: () => this.http.clearCache(),
+            /** Drop one cached response by key (`GET:/path`), every identity's variant. */
+            delete: (key) => this.http.clearCacheEntry(key),
+            /** Drop every cached response whose key starts with `prefix`; returns how many. */
+            deletePrefix: (prefix) => this.http.clearCacheByPrefix(prefix),
+            stats: () => this.http.getCacheStats(),
+        };
+        if (!config || typeof config !== 'object') {
+            throw new Error('OxyConfig is required');
+        }
+        this.config = config;
+        this.cloudURL = config.cloudURL || OXY_CLOUD_URL;
+        this.http = new HttpService(config);
+        this.context = {
+            oxy: this,
+            http: this.http,
+            request: (method, url, data, options) => this.request(method, url, data, options),
+            service: null,
+        };
+    }
+    /** The Oxy API origin this client talks to. */
+    get baseURL() {
+        return this.http.getBaseURL();
+    }
+    /**
+     * One authenticated request to the Oxy API — the primitive every namespace is
+     * built on, for the routes no namespace covers yet. GET sends `data` as the
+     * query string, every other method as the body. Rejects with `OxyApiError`.
+     */
+    async request(method, url, data, options = {}) {
+        try {
+            return await this.http.request({
+                method,
+                url,
+                data: method !== 'GET' ? data : undefined,
+                params: method === 'GET' ? data : undefined,
+                ...options,
+            });
+        }
+        catch (error) {
+            throw toOxyApiError(error);
+        }
+    }
+    /** `GET /health`. */
+    async health() {
+        return this.request('GET', '/health', undefined, { cache: false, retry: false, timeout: 5000 });
+    }
+    /**
+     * An HTTP client for an app's own backend (e.g. `https://api.syra.fm`) that
+     * shares this client's session: its bearer follows this session's token and
+     * its 401 refresh delegates here.
+     *
+     * GET caching is OFF by default: the SDK cannot invalidate another backend's
+     * resources, so caching there belongs to the consumer's own layer (React
+     * Query). Pass `enableCache: true` to opt in.
+     */
+    createLinkedClient(config) {
+        const client = new HttpService({ ...config, enableCache: config.enableCache ?? false });
+        const syncToken = (accessToken) => {
+            const current = client.getAccessToken();
+            if (accessToken) {
+                if (current !== accessToken)
+                    client.setTokens(accessToken);
+                return;
+            }
+            if (current)
+                client.clearTokens();
+        };
+        syncToken(this.http.getAccessToken());
+        const unsubscribe = this.http.addTokenChangeListener(syncToken);
+        client.setAccessTokenProvider(() => this.http.getAccessToken());
+        client.setAuthRefreshHandler(async (reason) => {
+            const refreshed = await this.http.refreshAccessToken(reason);
+            if (!refreshed)
+                return null;
+            syncToken(refreshed);
+            return refreshed;
+        });
+        return {
+            client,
+            dispose: () => {
+                unsubscribe();
+                client.setAuthRefreshHandler(null);
+                client.setAccessTokenProvider(null);
+                client.clearTokens();
+            },
+        };
+    }
+    /** Release this client: its cache stops being swept and its session ends. */
+    dispose() {
+        this.http.dispose();
+    }
+    /** This client's auth state (token, user id) and its server session. */
+    get session() {
+        if (!this._session)
+            this._session = new SessionApi(this.context);
+        return this._session;
+    }
+    /** Signing in, signing up, and the account's credentials. */
+    get auth() {
+        if (!this._auth)
+            this._auth = new AuthApi(this.context);
+        return this._auth;
+    }
+    /** People and their profiles. */
+    get users() {
+        if (!this._users)
+            this._users = new UsersApi(this.context);
+        return this._users;
+    }
+    /** The follow graph: people and every other followable target. */
+    get follows() {
+        if (!this._follows)
+            this._follows = new FollowsApi(this.context);
+        return this._follows;
+    }
+    /** Privacy settings, blocks and restrictions. */
+    get privacy() {
+        if (!this._privacy)
+            this._privacy = new PrivacyApi(this.context);
+        return this._privacy;
+    }
+    /** The in-app inbox and push tokens. */
+    get notifications() {
+        if (!this._notifications)
+            this._notifications = new NotificationsApi(this.context);
+        return this._notifications;
+    }
+    /** Files: upload, link, URLs, content. */
+    get assets() {
+        if (!this._assets)
+            this._assets = new AssetsApi(this.context);
+        return this._assets;
+    }
+    /** DID, keys, identity links, domains, backup and the signed export. */
+    get identity() {
+        if (!this._identity)
+            this._identity = new IdentityApi(this.context);
+        return this._identity;
+    }
+    /** The account graph: accounts and their members. */
+    get accounts() {
+        if (!this._accounts)
+            this._accounts = new AccountsApi(this.context);
+        return this._accounts;
+    }
+    /** Applications an account owns, and the ones this user granted access. */
+    get apps() {
+        if (!this._apps)
+            this._apps = new AppsApi(this.context);
+        return this._apps;
+    }
+    /** External accounts (Mastodon, Bluesky) linked by OAuth. */
+    get linkedAccounts() {
+        if (!this._linkedAccounts)
+            this._linkedAccounts = new LinkedAccountsApi(this.context);
+        return this._linkedAccounts;
+    }
+    /** Delegated capabilities for agents. */
+    get agency() {
+        if (!this._agency)
+            this._agency = new AgencyApi(this.context);
+        return this._agency;
+    }
+    /** The app store: storefront, reviews, and a publisher's listing. */
+    get store() {
+        if (!this._store)
+            this._store = new StoreApi(this.context);
+        return this._store;
+    }
+    /** Subscription, wallet and payments. */
+    get billing() {
+        if (!this._billing)
+            this._billing = new BillingApi(this.context);
+        return this._billing;
+    }
+    /** Oxy Trust reputation (read-only for people; apps award it). */
+    get reputation() {
+        if (!this._reputation)
+            this._reputation = new ReputationApi(this.context);
+        return this._reputation;
+    }
+    /** Oxy ID: cards, attestations, vouching, personhood, credentials. */
+    get civic() {
+        if (!this._civic)
+            this._civic = new CivicApi(this.context);
+        return this._civic;
+    }
+    /** The user's personal data node. */
+    get nodes() {
+        if (!this._nodes)
+            this._nodes = new NodesApi(this.context);
+        return this._nodes;
+    }
+    /** This user's devices, their sessions, and device sign-in. */
+    get devices() {
+        if (!this._devices)
+            this._devices = new DevicesApi(this.context);
+        return this._devices;
+    }
+    get topics() {
+        if (!this._topics)
+            this._topics = new TopicsApi(this.context);
+        return this._topics;
+    }
+    /** Per-app key/value data stored on the user's account. */
+    get appData() {
+        if (!this._appData)
+            this._appData = new AppDataApi(this.context);
+        return this._appData;
+    }
+    get contacts() {
+        if (!this._contacts)
+            this._contacts = new ContactsApi(this.context);
+        return this._contacts;
     }
 }
-// Re-export error classes for convenience
-export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
-/**
- * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
- */
-export const OXY_CLOUD_URL = 'https://cloud.oxy.so';
-/**
- * Export the default Oxy API URL (for documentation)
- */
-export const OXY_API_URL = (typeof process !== 'undefined' && process.env && process.env.OXY_API_URL) || 'https://api.oxy.so';
-/**
- * Pre-configured client instance for easy import
- * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL
- */
-export const oxyClient = new OxyServices({ baseURL: OXY_API_URL, cloudURL: OXY_CLOUD_URL });

package/dist/esm/api/accounts.js

@@ -0,0 +1,218 @@
+import { normalizeUserIdentity } from '../utils/userIdentity.js';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep.js';
+import { evictOxyAccountForestCache, oxyAccountDetailCacheKey, OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX, } from '../utils/accountCacheSweep.js';
+const MEDIUM_TTL = 2 * 60 * 1000;
+const LONG_TTL = 5 * 60 * 1000;
+const enc = encodeURIComponent;
+export { ACCOUNT_CATEGORY_IDS, ACCOUNT_KINDS, MAX_ACCOUNT_CATEGORIES, SELECTABLE_ACCOUNT_CATEGORY_IDS, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, isSelectableAccountCategoryId, kindAcceptsAccountCategories, } from '@oxy.so/contracts';
+/** `oxy.accounts.members` — who can act on an account, and with what role. */
+export class AccountMembersApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * 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`.
+     */
+    async list(accountId) {
+        const res = await this.ctx.request('GET', `/accounts/${enc(accountId)}/members`, undefined, { cache: true, cacheTTL: MEDIUM_TTL });
+        return res.members ?? [];
+    }
+    /**
+     * 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".
+     */
+    async invite(accountId, data) {
+        const res = await this.ctx.request('POST', `/accounts/${enc(accountId)}/members`, data, { cache: false });
+        invalidateAccountMembership(this.ctx, accountId);
+        return res.member;
+    }
+    /**
+     * 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.
+     */
+    async update(accountId, memberId, data) {
+        const res = await this.ctx.request('PATCH', `/accounts/${enc(accountId)}/members/${enc(memberId)}`, data, { cache: false });
+        invalidateAccountMembership(this.ctx, accountId);
+        return res.member;
+    }
+    /**
+     * Remove a member from an account.
+     * @param accountId - The account's `_id`.
+     * @param memberId - The member's `_id`.
+     */
+    async remove(accountId, memberId) {
+        const result = await this.ctx.request('DELETE', `/accounts/${enc(accountId)}/members/${enc(memberId)}`, undefined, { cache: false });
+        invalidateAccountMembership(this.ctx, accountId);
+        return result;
+    }
+}
+export class AccountsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.members = new AccountMembersApi(ctx);
+    }
+    /**
+     * 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.
+     */
+    async list(opts) {
+        const path = opts?.tree ? '/accounts?tree=true' : '/accounts';
+        const res = await this.ctx.request('GET', path, undefined, {
+            cache: true,
+            cacheTTL: MEDIUM_TTL,
+        });
+        return res.accounts ?? [];
+    }
+    /**
+     * Fetch a single account node by id.
+     * @param accountId - The account's `_id`.
+     */
+    async get(accountId) {
+        const res = await this.ctx.request('GET', `/accounts/${enc(accountId)}`, undefined, {
+            cache: true,
+            cacheTTL: LONG_TTL,
+        });
+        return res.account;
+    }
+    /**
+     * 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.
+     */
+    async actAs(accountId) {
+        const res = await this.ctx.request('POST', `/accounts/${enc(accountId)}/switch`, undefined, {
+            cache: false,
+        });
+        if (res?.accessToken) {
+            this.ctx.oxy.session.setAccessToken(res.accessToken);
+        }
+        const authuser = res?.authuser;
+        // Identity changed → drop the entire GET response cache so no entry
+        // personalised for the previous identity is reused.
+        this.ctx.oxy.cache.clear();
+        return {
+            ...res,
+            ...(typeof authuser === 'number' ? { authuser } : {}),
+            user: normalizeUserIdentity(res.user),
+        };
+    }
+    /**
+     * Create a new (non-personal) account. The caller becomes its `owner`.
+     * @param data - Account configuration: kind, optional parent, and profile.
+     */
+    async create(data) {
+        const res = await this.ctx.request('POST', '/accounts', data, { cache: false });
+        // A new account changes the accessible forest — bust every cached list.
+        evictOxyAccountForestCache(this.ctx.http);
+        return res.account;
+    }
+    /**
+     * 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.
+     */
+    async update(accountId, data) {
+        const res = await this.ctx.request('PATCH', `/accounts/${enc(accountId)}`, data, {
+            cache: false,
+        });
+        evictOxyAccountForestCache(this.ctx.http, accountId);
+        // The parent's children list embeds this account's profile and is keyed by
+        // the PARENT id, so it is reachable only from the response node.
+        const parentAccountId = res.account?.parentAccountId;
+        if (parentAccountId) {
+            this.ctx.oxy.cache.delete(`GET:/accounts/${enc(parentAccountId)}/children`);
+        }
+        evictOxyIdentityCache(this.ctx.http, accountId);
+        return res.account;
+    }
+    /**
+     * Archive an account (soft delete). Not `users.deleteMe`, which is the GDPR
+     * self-deletion flow.
+     * @param accountId - The account's `_id`.
+     */
+    async archive(accountId) {
+        const result = await this.ctx.request('DELETE', `/accounts/${enc(accountId)}`, undefined, {
+            cache: false,
+        });
+        this.ctx.http.invalidateCache({
+            keys: [`GET:/accounts/${enc(accountId)}/members`, `GET:/accounts/${enc(accountId)}/credentials`],
+        });
+        evictOxyAccountForestCache(this.ctx.http, accountId);
+        return result;
+    }
+    /**
+     * Transfer ownership of an account to another member (owner only).
+     * @param accountId - The account's `_id`.
+     * @param data - Target user id.
+     */
+    async transferOwnership(accountId, data) {
+        const result = await this.ctx.request('POST', `/accounts/${enc(accountId)}/transfer-ownership`, data, { cache: false });
+        // Ownership changes roles in the member list AND the detail, and which
+        // accounts the caller "owns" in the list view.
+        invalidateAccountMembership(this.ctx, accountId);
+        evictOxyAccountForestCache(this.ctx.http);
+        return result;
+    }
+}
+/**
+ * Bust the cached member list and detail after a membership mutation. Inherited
+ * rows on descendant rosters derive from this account's membership, so every
+ * per-account sub-resource key (`GET:/accounts/<id>…`) goes, in one pass; the
+ * forest list keys (`GET:/accounts`, `GET:/accounts?…`) are excluded by the
+ * trailing slash on the prefix.
+ */
+function invalidateAccountMembership(ctx, accountId) {
+    ctx.http.invalidateCache({
+        keys: [`GET:/accounts/${enc(accountId)}/members`, oxyAccountDetailCacheKey(accountId)],
+        prefixes: [OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX],
+    });
+}

package/dist/esm/api/agency.js

@@ -0,0 +1,95 @@
+const SHORT_TTL = 60 * 1000;
+const MEDIUM_TTL = 2 * 60 * 1000;
+const enc = encodeURIComponent;
+function query(path, key, value) {
+    return `${path}?${key}=${enc(value)}`;
+}
+const grantsKey = (ownerAccountId) => `GET:${query('/capabilities/grants', 'ownerAccountId', ownerAccountId)}`;
+const policiesKey = (accountId) => `GET:${query('/capabilities/account-policies', 'accountId', accountId)}`;
+const authorizationsKey = (ownerAccountId) => `GET:${query('/capabilities/execution-authorizations', 'ownerAccountId', ownerAccountId)}`;
+/** `oxy.agency.grants` — what an owner account delegated to an actor. */
+export class DelegationGrantsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The delegation grants an owner account issued. */
+    async list(ownerAccountId) {
+        const res = await this.ctx.request('GET', query('/capabilities/grants', 'ownerAccountId', ownerAccountId), undefined, { cache: true, cacheTTL: SHORT_TTL });
+        return res.grants;
+    }
+    /** Issue a delegation grant. */
+    async create(input) {
+        const res = await this.ctx.request('POST', '/capabilities/grants', input, {
+            cache: false,
+        });
+        this.ctx.oxy.cache.delete(grantsKey(input.ownerAccountId));
+        return res.grant;
+    }
+    /** Change a grant's capabilities, limits or autonomy. */
+    async update(grantId, ownerAccountId, input) {
+        const res = await this.ctx.request('PUT', `/capabilities/grants/${enc(grantId)}`, input, { cache: false });
+        this.ctx.oxy.cache.delete(grantsKey(ownerAccountId));
+        return res.grant;
+    }
+    /** Revoke a grant. */
+    async revoke(grantId, ownerAccountId) {
+        await this.ctx.request('DELETE', `/capabilities/grants/${enc(grantId)}`, undefined, { cache: false });
+        this.ctx.oxy.cache.delete(grantsKey(ownerAccountId));
+    }
+}
+/** `oxy.agency.policies` — an account's per-app autonomy policy. */
+export class CapabilityPoliciesApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** An account's capability policies, one per app. */
+    async list(accountId) {
+        const res = await this.ctx.request('GET', query('/capabilities/account-policies', 'accountId', accountId), undefined, { cache: true, cacheTTL: SHORT_TTL });
+        return res.policies;
+    }
+    /** Set an account's policy for one app. */
+    async put(appId, input) {
+        const res = await this.ctx.request('PUT', `/capabilities/account-policies/${enc(appId)}`, input, { cache: false });
+        this.ctx.oxy.cache.delete(policiesKey(input.accountId));
+        return res.policy;
+    }
+    /** Drop an account's policy for one app. */
+    async delete(appId, accountId) {
+        await this.ctx.request('DELETE', `/capabilities/account-policies/${enc(appId)}?accountId=${enc(accountId)}`, undefined, { cache: false });
+        this.ctx.oxy.cache.delete(policiesKey(accountId));
+    }
+}
+/** `oxy.agency.authorizations` — live execution authorizations. */
+export class ExecutionAuthorizationsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** An owner account's execution authorizations. */
+    async list(ownerAccountId) {
+        const res = await this.ctx.request('GET', query('/capabilities/execution-authorizations', 'ownerAccountId', ownerAccountId), undefined, { cache: true, cacheTTL: SHORT_TTL });
+        return res.authorizations;
+    }
+    /** Revoke an execution authorization. */
+    async revoke(authorizationId, ownerAccountId) {
+        await this.ctx.request('DELETE', `/capabilities/execution-authorizations/${enc(authorizationId)}`, undefined, { cache: false });
+        this.ctx.oxy.cache.delete(authorizationsKey(ownerAccountId));
+    }
+}
+export class AgencyApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.grants = new DelegationGrantsApi(ctx);
+        this.policies = new CapabilityPoliciesApi(ctx);
+        this.authorizations = new ExecutionAuthorizationsApi(ctx);
+    }
+    /** The capability catalogs available to an account. */
+    async catalogs(accountId) {
+        const res = await this.ctx.request('GET', query('/capabilities/catalogs/available', 'accountId', accountId), undefined, { cache: true, cacheTTL: MEDIUM_TTL });
+        return res.catalogs;
+    }
+    /** An account's capability audit trail. */
+    async auditEvents(accountId) {
+        const res = await this.ctx.request('GET', query('/capabilities/audit', 'accountId', accountId), undefined, { cache: true, cacheTTL: SHORT_TTL });
+        return res.events;
+    }
+}

package/dist/esm/api/appData.js

@@ -0,0 +1,40 @@
+const IDENTIFIER = /^[a-z0-9_-]{1,64}$/u;
+/** Thrown when a namespace or key is not `[a-z0-9_-]{1,64}`. */
+export class OxyAppDataIdentifierError extends Error {
+    constructor(field, value) {
+        super(`Invalid app-data ${field} "${value}": must match [a-z0-9_-]{1,64} (lowercase letters, digits, dashes, underscores).`);
+        this.name = 'OxyAppDataIdentifierError';
+    }
+}
+function check(field, value) {
+    if (!IDENTIFIER.test(value))
+        throw new OxyAppDataIdentifierError(field, value);
+    return encodeURIComponent(value);
+}
+export class AppDataApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /** The value under `(namespace, key)`, or `null` when nothing is stored. */
+    async get(namespace, key) {
+        const res = await this.ctx.request('GET', this.path(namespace, key), undefined, { cache: false });
+        return res?.value ?? null;
+    }
+    /** Store `value` under `(namespace, key)`; returns what the server stored. */
+    async set(namespace, key, value) {
+        const res = await this.ctx.request('PUT', this.path(namespace, key), { value }, { cache: false });
+        return (res?.value ?? value);
+    }
+    /** Delete `(namespace, key)`. Idempotent. */
+    async delete(namespace, key) {
+        await this.ctx.request('DELETE', this.path(namespace, key), undefined, { cache: false });
+    }
+    /** Every entry in `namespace` (an empty object when there are none). */
+    async list(namespace) {
+        const res = await this.ctx.request('GET', `/users/me/app-data/${check('namespace', namespace)}`, undefined, { cache: false });
+        return res?.entries ?? {};
+    }
+    path(namespace, key) {
+        return `/users/me/app-data/${check('namespace', namespace)}/${check('key', key)}`;
+    }
+}