@oxy.so/core 4.5.0-oxy-one.1 → 4.6.0

package/src/api/accounts.ts

@@ -17,10 +17,22 @@
  * 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 { agentKeyOperationSchema, executeAgentKeyOperationSchema, agentKeyOperationChallengeSchema,
-  agentKeyOperationResultSchema, agentKeyListResponseSchema, type AgentKeyOperation, type AgentKeyOperationProof } from '@oxy.so/contracts';
+import {
+  agentKeyOperationSchema,
+  executeAgentKeyOperationSchema,
+  agentKeyOperationChallengeSchema,
+  agentKeyOperationResultSchema,
+  agentKeyListResponseSchema,
+  type AgentKeyOperation,
+  type AgentKeyOperationProof,
+} from '@oxy.so/contracts';
 import type { User } from '../models/interfaces';
-import type { AccountCategoryId, AccountKind, ChildAccountKind } from '@oxy.so/contracts';
+import type {
+  AccountCategoryId,
+  AccountKind,
+  AvatarCharacter,
+  ChildAccountKind,
+} from '@oxy.so/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyContext } from '../client/context';
 import { normalizeUserIdentity } from '../utils/userIdentity';
@@ -50,7 +62,7 @@ const enc = encodeURIComponent;
  *
  * Single source of truth is `@oxy.so/contracts`.
  */
-export type { AccountCategoryId, AccountKind } from '@oxy.so/contracts';
+export type { AccountCategoryId, AccountKind, AvatarCharacter } from '@oxy.so/contracts';
 export {
   ACCOUNT_CATEGORY_IDS,
   ACCOUNT_KINDS,
@@ -136,7 +148,7 @@ export interface AccountMember {
  * `childCount` reflects the number of direct children.
  */
 export interface AccountNode {
-  /** The account's Mongo `_id` (the underlying `User._id`). */
+  /** The account's user id. */
   accountId: string;
   kind: AccountKind;
   /** Parent account `_id`, or `null` for a root (personal) account. */
@@ -240,6 +252,13 @@ export interface CreateAccountInput {
    * discoverable at all, rather than discoverable until a second call lands.
    */
   isPrivateAccount?: boolean;
+  /**
+   * The 3D avatar character, for `kind: 'bot'` ONLY (any other kind is a 400).
+   * Optional: a bot created without one is given a look seeded from its
+   * handle, so every bot has a character from birth and its owner changes it
+   * afterwards with `accounts.update`.
+   */
+  character?: AvatarCharacter;
 }
 
 /** Input accepted by `accounts.update`. Tree placement changes go through `/move`. */
@@ -276,6 +295,12 @@ export interface UpdateAccountInput {
    * always allowed.
    */
   accountCategories?: AccountCategoryId[];
+  /**
+   * Replaces the WHOLE character of a `bot` account. Rejected (400) for any
+   * other kind, and not nullable: a bot always has one. Same authorization as
+   * every other field here (`account:update`).
+   */
+  character?: AvatarCharacter;
 }
 
 /** Input accepted by `accounts.members.invite`. The owner role cannot be invited. */
@@ -329,7 +354,6 @@ export interface SwitchAccountResult extends SessionLoginResponse {
   authuser?: number;
 }
 
-
 /** `oxy.accounts.members` — who can act on an account, and with what role. */
 export class AccountMembersApi {
   constructor(private readonly ctx: OxyContext) {}
@@ -387,7 +411,11 @@ export class AccountMembersApi {
    * @param memberId - The member's `_id`.
    * @param data - New role (never `owner`), inheritance, permission overrides.
    */
-  async update(accountId: string, memberId: string, data: UpdateAccountMemberInput): Promise<AccountMember> {
+  async update(
+    accountId: string,
+    memberId: string,
+    data: UpdateAccountMemberInput,
+  ): Promise<AccountMember> {
     const res = await this.ctx.request<{ member: AccountMember }>(
       'PATCH',
       `/accounts/${enc(accountId)}/members/${enc(memberId)}`,
@@ -419,16 +447,28 @@ export class AccountMembersApi {
 export class AccountAgentKeysApi {
   constructor(private readonly ctx: OxyContext) {}
   async list(accountId: string) {
-    return agentKeyListResponseSchema.parse(await this.ctx.request<unknown>('GET', `/accounts/${enc(accountId)}/agent-keys`, undefined, { cache: false }));
+    return agentKeyListResponseSchema.parse(
+      await this.ctx.request<unknown>('GET', `/accounts/${enc(accountId)}/agent-keys`, undefined, {
+        cache: false,
+      }),
+    );
   }
   async requestChallenge(accountId: string, operation: AgentKeyOperation) {
-    const response = await this.ctx.request<unknown>('POST', `/accounts/${enc(accountId)}/agent-keys/challenge`,
-      agentKeyOperationSchema.parse(operation), { cache: false });
+    const response = await this.ctx.request<unknown>(
+      'POST',
+      `/accounts/${enc(accountId)}/agent-keys/challenge`,
+      agentKeyOperationSchema.parse(operation),
+      { cache: false },
+    );
     return agentKeyOperationChallengeSchema.parse(response);
   }
   async execute(accountId: string, operation: AgentKeyOperation, proof: AgentKeyOperationProof) {
-    const response = await this.ctx.request<unknown>('POST', `/accounts/${enc(accountId)}/agent-keys/execute`,
-      executeAgentKeyOperationSchema.parse({ operation, proof }), { cache: false });
+    const response = await this.ctx.request<unknown>(
+      'POST',
+      `/accounts/${enc(accountId)}/agent-keys/execute`,
+      executeAgentKeyOperationSchema.parse({ operation, proof }),
+      { cache: false },
+    );
     return agentKeyOperationResultSchema.parse(response);
   }
 }
@@ -466,10 +506,15 @@ export class AccountsApi {
    * @param accountId - The account's `_id`.
    */
   async get(accountId: string): Promise<AccountNode> {
-    const res = await this.ctx.request<{ account: AccountNode }>('GET', `/accounts/${enc(accountId)}`, undefined, {
-      cache: true,
-      cacheTTL: LONG_TTL,
-    });
+    const res = await this.ctx.request<{ account: AccountNode }>(
+      'GET',
+      `/accounts/${enc(accountId)}`,
+      undefined,
+      {
+        cache: true,
+        cacheTTL: LONG_TTL,
+      },
+    );
     return res.account;
   }
 
@@ -496,9 +541,14 @@ export class AccountsApi {
    * @returns The minted session, already planted as the active session.
    */
   async actAs(accountId: string): Promise<SwitchAccountResult> {
-    const res = await this.ctx.request<SwitchAccountResult>('POST', `/accounts/${enc(accountId)}/switch`, undefined, {
-      cache: false,
-    });
+    const res = await this.ctx.request<SwitchAccountResult>(
+      'POST',
+      `/accounts/${enc(accountId)}/switch`,
+      undefined,
+      {
+        cache: false,
+      },
+    );
     if (res?.accessToken) {
       this.ctx.oxy.session.setAccessToken(res.accessToken);
     }
@@ -518,7 +568,9 @@ export class AccountsApi {
    * @param data - Account configuration: kind, optional parent, and profile.
    */
   async create(data: CreateAccountInput): Promise<AccountNode> {
-    const res = await this.ctx.request<{ account: AccountNode }>('POST', '/accounts', data, { cache: false });
+    const res = await this.ctx.request<{ account: AccountNode }>('POST', '/accounts', data, {
+      cache: false,
+    });
     // A new account changes the accessible forest — bust every cached list.
     evictOxyAccountForestCache(this.ctx.http);
     return res.account;
@@ -536,9 +588,14 @@ export class AccountsApi {
    * @param data - Subset of updatable profile fields.
    */
   async update(accountId: string, data: UpdateAccountInput): Promise<AccountNode> {
-    const res = await this.ctx.request<{ account: AccountNode }>('PATCH', `/accounts/${enc(accountId)}`, data, {
-      cache: false,
-    });
+    const res = await this.ctx.request<{ account: AccountNode }>(
+      '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.
@@ -556,11 +613,19 @@ export class AccountsApi {
    * @param accountId - The account's `_id`.
    */
   async archive(accountId: string): Promise<AccountSuccessResult> {
-    const result = await this.ctx.request<AccountSuccessResult>('DELETE', `/accounts/${enc(accountId)}`, undefined, {
-      cache: false,
-    });
+    const result = await this.ctx.request<AccountSuccessResult>(
+      'DELETE',
+      `/accounts/${enc(accountId)}`,
+      undefined,
+      {
+        cache: false,
+      },
+    );
     this.ctx.http.invalidateCache({
-      keys: [`GET:/accounts/${enc(accountId)}/members`, `GET:/accounts/${enc(accountId)}/credentials`],
+      keys: [
+        `GET:/accounts/${enc(accountId)}/members`,
+        `GET:/accounts/${enc(accountId)}/credentials`,
+      ],
     });
     evictOxyAccountForestCache(this.ctx.http, accountId);
     return result;
@@ -571,7 +636,10 @@ export class AccountsApi {
    * @param accountId - The account's `_id`.
    * @param data - Target user id.
    */
-  async transferOwnership(accountId: string, data: TransferAccountOwnershipInput): Promise<AccountSuccessResult> {
+  async transferOwnership(
+    accountId: string,
+    data: TransferAccountOwnershipInput,
+  ): Promise<AccountSuccessResult> {
     const result = await this.ctx.request<AccountSuccessResult>(
       'POST',
       `/accounts/${enc(accountId)}/transfer-ownership`,

package/src/api/agency.ts

@@ -122,13 +122,14 @@ export interface RequesterAssertionIntrospection {
   expiresAt?: string;
 }
 
-
 function query(path: string, key: string, value: string): string {
   return `${path}?${key}=${enc(value)}`;
 }
 
-const grantsKey = (ownerAccountId: string): string => `GET:${query('/capabilities/grants', 'ownerAccountId', ownerAccountId)}`;
-const policiesKey = (accountId: string): string => `GET:${query('/capabilities/account-policies', 'accountId', accountId)}`;
+const grantsKey = (ownerAccountId: string): string =>
+  `GET:${query('/capabilities/grants', 'ownerAccountId', ownerAccountId)}`;
+const policiesKey = (accountId: string): string =>
+  `GET:${query('/capabilities/account-policies', 'accountId', accountId)}`;
 const authorizationsKey = (ownerAccountId: string): string =>
   `GET:${query('/capabilities/execution-authorizations', 'ownerAccountId', ownerAccountId)}`;
 
@@ -149,15 +150,24 @@ export class DelegationGrantsApi {
 
   /** Issue a delegation grant. */
   async create(input: CreateDelegationGrantInput): Promise<DelegationGrantView> {
-    const res = await this.ctx.request<{ grant: DelegationGrantView }>('POST', '/capabilities/grants', input, {
-      cache: false,
-    });
+    const res = await this.ctx.request<{ grant: DelegationGrantView }>(
+      '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: string, ownerAccountId: string, input: UpdateDelegationGrantInput): Promise<DelegationGrantView> {
+  async update(
+    grantId: string,
+    ownerAccountId: string,
+    input: UpdateDelegationGrantInput,
+  ): Promise<DelegationGrantView> {
     const res = await this.ctx.request<{ grant: DelegationGrantView }>(
       'PUT',
       `/capabilities/grants/${enc(grantId)}`,
@@ -170,7 +180,9 @@ export class DelegationGrantsApi {
 
   /** Revoke a grant. */
   async revoke(grantId: string, ownerAccountId: string): Promise<void> {
-    await this.ctx.request<void>('DELETE', `/capabilities/grants/${enc(grantId)}`, undefined, { cache: false });
+    await this.ctx.request<void>('DELETE', `/capabilities/grants/${enc(grantId)}`, undefined, {
+      cache: false,
+    });
     this.ctx.oxy.cache.delete(grantsKey(ownerAccountId));
   }
 }
@@ -191,7 +203,10 @@ export class CapabilityPoliciesApi {
   }
 
   /** Set an account's policy for one app. */
-  async put(appId: string, input: PutAccountCapabilityPolicyInput): Promise<AccountCapabilityPolicy> {
+  async put(
+    appId: string,
+    input: PutAccountCapabilityPolicyInput,
+  ): Promise<AccountCapabilityPolicy> {
     const res = await this.ctx.request<{ policy: AccountCapabilityPolicy }>(
       'PUT',
       `/capabilities/account-policies/${enc(appId)}`,

package/src/api/appData.ts

@@ -31,13 +31,23 @@ export class AppDataApi {
 
   /** The value under `(namespace, key)`, or `null` when nothing is stored. */
   async get<T = unknown>(namespace: string, key: string): Promise<T | null> {
-    const res = await this.ctx.request<{ value: T | null }>('GET', this.path(namespace, key), undefined, { cache: false });
+    const res = await this.ctx.request<{ value: T | null }>(
+      'GET',
+      this.path(namespace, key),
+      undefined,
+      { cache: false },
+    );
     return res?.value ?? null;
   }
 
   /** Store `value` under `(namespace, key)`; returns what the server stored. */
   async set<T = unknown>(namespace: string, key: string, value: T): Promise<T> {
-    const res = await this.ctx.request<{ value: T | null }>('PUT', this.path(namespace, key), { value }, { cache: false });
+    const res = await this.ctx.request<{ value: T | null }>(
+      'PUT',
+      this.path(namespace, key),
+      { value },
+      { cache: false },
+    );
     return (res?.value ?? value) as T;
   }
 

package/src/api/apps.ts

@@ -273,7 +273,6 @@ export interface ApplicationUsageStats {
   byEndpoint: ApplicationUsageByEndpoint[];
 }
 
-
 // ---------------------------------------------------------------------------
 // OAuth consent (connected apps) types
 // ---------------------------------------------------------------------------
@@ -289,7 +288,7 @@ export interface ApplicationUsageStats {
  * `_id` as a string.
  */
 export interface PublicApplication {
-  /** The application's Mongo `_id` as a string. */
+  /** The application's id as a string. */
   id: string;
   /** Human-readable application name shown to the user. */
   name: string;
@@ -320,14 +319,14 @@ export interface PublicApplication {
  * view: an application the user has granted access to via the consent flow.
  *
  * Returned by `GET /auth/grants` and rendered in the user-facing "Connected
- * apps" management surface. Keyed by `applicationId` (the application's Mongo
- * `_id`) rather than a credential/client id, so the grant — and a subsequent
+ * apps" management surface. Keyed by `applicationId` (the application's own
+ * id) rather than a credential/client id, so the grant — and a subsequent
  * `apps.connected.revoke` — survive credential
  * rotation. This is a display shape: it carries the application's name/logo and
  * the granted scopes, never any membership or credential material.
  */
 export interface ConnectedApp {
-  /** The connected application's Mongo `_id`. Use this to revoke the grant. */
+  /** The connected application's id. Use this to revoke the grant. */
   applicationId: string;
   /** Human-readable application name shown to the user. */
   name: string;
@@ -353,7 +352,6 @@ export interface ConnectedMcpClient {
   lastUsedAt: string;
 }
 
-
 /** `oxy.apps.credentials` — an application's OAuth client credentials. */
 export class AppCredentialsApi {
   constructor(private readonly ctx: OxyContext) {}
@@ -379,10 +377,18 @@ export class AppCredentialsApi {
    * @param applicationId - The application's `_id`.
    * @param data - Credential configuration.
    */
-  async create(applicationId: string, data: CreateApplicationCredentialInput): Promise<ApplicationCredentialWithSecret> {
-    const result = await this.ctx.request<ApplicationCredentialWithSecret>('POST', credentialsPath(applicationId), data, {
-      cache: false,
-    });
+  async create(
+    applicationId: string,
+    data: CreateApplicationCredentialInput,
+  ): Promise<ApplicationCredentialWithSecret> {
+    const result = await this.ctx.request<ApplicationCredentialWithSecret>(
+      'POST',
+      credentialsPath(applicationId),
+      data,
+      {
+        cache: false,
+      },
+    );
     this.ctx.oxy.cache.delete(`GET:${credentialsPath(applicationId)}`);
     return result;
   }
@@ -441,7 +447,10 @@ export class ConnectedAppsApi {
    * `GET /auth/grants`, briefly cached; `revoke` busts it.
    */
   async list(): Promise<ConnectedApp[]> {
-    return this.ctx.request<ConnectedApp[]>('GET', '/auth/grants', undefined, { cache: true, cacheTTL: SHORT_TTL });
+    return this.ctx.request<ConnectedApp[]>('GET', '/auth/grants', undefined, {
+      cache: true,
+      cacheTTL: SHORT_TTL,
+    });
   }
 
   /**
@@ -451,22 +460,34 @@ export class ConnectedAppsApi {
    *   `ConnectedApp.applicationId`, NOT a credential/client id).
    */
   async revoke(applicationId: string): Promise<void> {
-    await this.ctx.request<{ revoked: boolean }>('DELETE', `/auth/grants/${applicationId}`, undefined, { cache: false });
+    await this.ctx.request<{ revoked: boolean }>(
+      'DELETE',
+      `/auth/grants/${applicationId}`,
+      undefined,
+      { cache: false },
+    );
     this.ctx.oxy.cache.delete('GET:/auth/grants');
   }
 
   /** Resource-bound external MCP connections for the active Oxy account. */
   async mcpClients(): Promise<ConnectedMcpClient[]> {
-    const res = await this.ctx.request<{ grants: ConnectedMcpClient[] }>('GET', '/auth/mcp/oauth/grants', undefined, {
-      cache: true,
-      cacheTTL: SHORT_TTL,
-    });
+    const res = await this.ctx.request<{ grants: ConnectedMcpClient[] }>(
+      'GET',
+      '/auth/mcp/oauth/grants',
+      undefined,
+      {
+        cache: true,
+        cacheTTL: SHORT_TTL,
+      },
+    );
     return res.grants;
   }
 
   /** Revoke one external MCP connection and every token in its family. */
   async revokeMcpClient(grantId: string): Promise<void> {
-    await this.ctx.request<void>('DELETE', `/auth/mcp/oauth/grants/${enc(grantId)}`, undefined, { cache: false });
+    await this.ctx.request<void>('DELETE', `/auth/mcp/oauth/grants/${enc(grantId)}`, undefined, {
+      cache: false,
+    });
     this.ctx.oxy.cache.delete('GET:/auth/mcp/oauth/grants');
   }
 }
@@ -501,10 +522,15 @@ export class AppsApi {
    * @param applicationId - The application's `_id`.
    */
   async get(applicationId: string): Promise<Application> {
-    const res = await this.ctx.request<{ application: Application }>('GET', appPath(applicationId), undefined, {
-      cache: true,
-      cacheTTL: LONG_TTL,
-    });
+    const res = await this.ctx.request<{ application: Application }>(
+      'GET',
+      appPath(applicationId),
+      undefined,
+      {
+        cache: true,
+        cacheTTL: LONG_TTL,
+      },
+    );
     return res.application;
   }
 
@@ -514,7 +540,12 @@ export class AppsApi {
    *   caller's personal account when omitted. Staff-only fields are ignored.
    */
   async create(data: CreateApplicationInput): Promise<Application> {
-    const res = await this.ctx.request<{ application: Application }>('POST', '/applications', data, { cache: false });
+    const res = await this.ctx.request<{ application: Application }>(
+      'POST',
+      '/applications',
+      data,
+      { cache: false },
+    );
     this.invalidateLists();
     return res.application;
   }
@@ -525,9 +556,14 @@ export class AppsApi {
    * @param data - Subset of updatable fields. Staff-only fields are ignored.
    */
   async update(applicationId: string, data: UpdateApplicationInput): Promise<Application> {
-    const res = await this.ctx.request<{ application: Application }>('PATCH', appPath(applicationId), data, {
-      cache: false,
-    });
+    const res = await this.ctx.request<{ application: Application }>(
+      'PATCH',
+      appPath(applicationId),
+      data,
+      {
+        cache: false,
+      },
+    );
     this.invalidateLists([`GET:${appPath(applicationId)}`]);
     return res.application;
   }
@@ -537,10 +573,18 @@ export class AppsApi {
    * @param applicationId - The application's `_id`.
    */
   async delete(applicationId: string): Promise<AccountSuccessResult> {
-    const result = await this.ctx.request<AccountSuccessResult>('DELETE', appPath(applicationId), undefined, {
-      cache: false,
-    });
-    this.invalidateLists([`GET:${appPath(applicationId)}`, `GET:${credentialsPath(applicationId)}`]);
+    const result = await this.ctx.request<AccountSuccessResult>(
+      'DELETE',
+      appPath(applicationId),
+      undefined,
+      {
+        cache: false,
+      },
+    );
+    this.invalidateLists([
+      `GET:${appPath(applicationId)}`,
+      `GET:${credentialsPath(applicationId)}`,
+    ]);
     return result;
   }
 
@@ -549,7 +593,10 @@ export class AppsApi {
    * @param applicationId - The application's `_id`.
    * @param period - Time window (defaults to the server default).
    */
-  async usage(applicationId: string, period?: ApplicationUsagePeriod): Promise<ApplicationUsageStats> {
+  async usage(
+    applicationId: string,
+    period?: ApplicationUsagePeriod,
+  ): Promise<ApplicationUsageStats> {
     return this.ctx.request<ApplicationUsageStats>(
       'GET',
       `${appPath(applicationId)}/usage`,
@@ -583,7 +630,10 @@ export class AppsApi {
    * `GET:/applications/<id>…` detail keys.
    */
   private invalidateLists(extraKeys: string[] = []): void {
-    this.ctx.http.invalidateCache({ keys: ['GET:/applications', ...extraKeys], prefixes: ['GET:/applications?'] });
+    this.ctx.http.invalidateCache({
+      keys: ['GET:/applications', ...extraKeys],
+      prefixes: ['GET:/applications?'],
+    });
   }
 }