@oxy.so/core 1.18.0 → 3.0.0

package/src/mixins/OxyServices.agency.ts

@@ -1,353 +0,0 @@
-/**
- * Native Alia and digital-agent authority.
- *
- * These methods manage Oxy-owned delegation grants, account autonomy policy,
- * execution authorizations and their audit trail. They deliberately 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 { OxyServicesBase } from '../OxyServices.base';
-import { CACHE_TIMES } from './mixinHelpers';
-
-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;
-}
-
-function query(path: string, key: string, value: string): string {
-  return `${path}?${key}=${encodeURIComponent(value)}`;
-}
-
-export function OxyServicesAgencyMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    async listAvailableCapabilityCatalogs(accountId: string): Promise<AvailableCapabilityCatalog[]> {
-      try {
-        const response = await this.makeRequest<{ catalogs: AvailableCapabilityCatalog[] }>(
-          'GET',
-          query('/capabilities/catalogs/available', 'accountId', accountId),
-          undefined,
-          { cache: true, cacheTTL: CACHE_TIMES.MEDIUM },
-        );
-        return response.catalogs;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async listDelegationGrants(ownerAccountId: string): Promise<DelegationGrantView[]> {
-      try {
-        const response = await this.makeRequest<{ grants: DelegationGrantView[] }>(
-          'GET',
-          query('/capabilities/grants', 'ownerAccountId', ownerAccountId),
-          undefined,
-          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
-        );
-        return response.grants;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async createDelegationGrant(input: CreateDelegationGrantInput): Promise<DelegationGrantView> {
-      try {
-        const response = await this.makeRequest<{ grant: DelegationGrantView }>(
-          'POST',
-          '/capabilities/grants',
-          input,
-          { cache: false },
-        );
-        this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(input.ownerAccountId)}`);
-        return response.grant;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async revokeDelegationGrant(grantId: string, ownerAccountId: string): Promise<void> {
-      try {
-        await this.makeRequest<void>(
-          'DELETE',
-          `/capabilities/grants/${encodeURIComponent(grantId)}`,
-          undefined,
-          { cache: false },
-        );
-        this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(ownerAccountId)}`);
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async updateDelegationGrant(
-      grantId: string,
-      ownerAccountId: string,
-      input: UpdateDelegationGrantInput,
-    ): Promise<DelegationGrantView> {
-      try {
-        const response = await this.makeRequest<{ grant: DelegationGrantView }>(
-          'PUT',
-          `/capabilities/grants/${encodeURIComponent(grantId)}`,
-          input,
-          { cache: false },
-        );
-        this.clearCacheEntry(`GET:/capabilities/grants?ownerAccountId=${encodeURIComponent(ownerAccountId)}`);
-        return response.grant;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async listAccountCapabilityPolicies(accountId: string): Promise<AccountCapabilityPolicy[]> {
-      try {
-        const response = await this.makeRequest<{ policies: AccountCapabilityPolicy[] }>(
-          'GET',
-          query('/capabilities/account-policies', 'accountId', accountId),
-          undefined,
-          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
-        );
-        return response.policies;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async putAccountCapabilityPolicy(
-      appId: string,
-      input: PutAccountCapabilityPolicyInput,
-    ): Promise<AccountCapabilityPolicy> {
-      try {
-        const response = await this.makeRequest<{ policy: AccountCapabilityPolicy }>(
-          'PUT',
-          `/capabilities/account-policies/${encodeURIComponent(appId)}`,
-          input,
-          { cache: false },
-        );
-        this.clearCacheEntry(`GET:/capabilities/account-policies?accountId=${encodeURIComponent(input.accountId)}`);
-        return response.policy;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async deleteAccountCapabilityPolicy(appId: string, accountId: string): Promise<void> {
-      try {
-        await this.makeRequest<void>(
-          'DELETE',
-          `/capabilities/account-policies/${encodeURIComponent(appId)}?accountId=${encodeURIComponent(accountId)}`,
-          undefined,
-          { cache: false },
-        );
-        this.clearCacheEntry(`GET:/capabilities/account-policies?accountId=${encodeURIComponent(accountId)}`);
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async listCapabilityExecutionAuthorizations(
-      ownerAccountId: string,
-    ): Promise<CapabilityExecutionAuthorization[]> {
-      try {
-        const response = await this.makeRequest<{ authorizations: CapabilityExecutionAuthorization[] }>(
-          'GET',
-          query('/capabilities/execution-authorizations', 'ownerAccountId', ownerAccountId),
-          undefined,
-          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
-        );
-        return response.authorizations;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async revokeCapabilityExecutionAuthorization(
-      authorizationId: string,
-      ownerAccountId: string,
-    ): Promise<void> {
-      try {
-        await this.makeRequest<void>(
-          'DELETE',
-          `/capabilities/execution-authorizations/${encodeURIComponent(authorizationId)}`,
-          undefined,
-          { cache: false },
-        );
-        this.clearCacheEntry(
-          `GET:/capabilities/execution-authorizations?ownerAccountId=${encodeURIComponent(ownerAccountId)}`,
-        );
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    async listCapabilityAuditEvents(accountId: string): Promise<AuditEvent[]> {
-      try {
-        const response = await this.makeRequest<{ events: AuditEvent[] }>(
-          'GET',
-          query('/capabilities/audit', 'accountId', accountId),
-          undefined,
-          { cache: true, cacheTTL: CACHE_TIMES.SHORT },
-        );
-        return response.events;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Product backend → Oxy: trade the signed-in requester's access token for a
-     * one-use assertion naming `agentId` (ADR 0025). Authenticated with THIS
-     * instance's service credential (`configureServiceAuth`). `subjectToken` is
-     * sent to Oxy only, in the body; never forward it anywhere else.
-     *
-     * Not retried: a refusal is an answer, and the caller mints per turn.
-     */
-    async mintRequesterAssertion(input: {
-      agentId: string;
-      subjectToken: string;
-    }): Promise<RequesterAssertionGrant> {
-      try {
-        const serviceToken = await (this as unknown as { getServiceToken(): Promise<string> }).getServiceToken();
-        return await this.makeRequest<RequesterAssertionGrant>(
-          'POST',
-          '/internal/native-agents/requester-assertions',
-          { agentId: input.agentId, subjectToken: input.subjectToken },
-          {
-            cache: false,
-            retry: false,
-            timeout: 5000,
-            headers: { Authorization: `Bearer ${serviceToken}` },
-          },
-        );
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Audience → Oxy: verify, live-revalidate and CONSUME an assertion. A second
-     * call with the same assertion answers `active: false`. Authenticated with
-     * the audience's own service credential.
-     */
-    async introspectRequesterAssertion(input: {
-      assertion: string;
-      presenter: { applicationId: string; credentialId: string };
-    }): Promise<RequesterAssertionIntrospection> {
-      try {
-        const serviceToken = await (this as unknown as { getServiceToken(): Promise<string> }).getServiceToken();
-        return await this.makeRequest<RequesterAssertionIntrospection>(
-          'POST',
-          '/internal/native-agents/requester-assertions/introspect',
-          { assertion: input.assertion, presenter: input.presenter },
-          {
-            cache: false,
-            retry: false,
-            timeout: 5000,
-            headers: { Authorization: `Bearer ${serviceToken}` },
-          },
-        );
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-  };
-}

package/src/mixins/OxyServices.analytics.ts

@@ -1,53 +0,0 @@
-/**
- * Analytics Methods Mixin
- * 
- * Provides methods for analytics tracking and data retrieval
- */
-import type { OxyServicesBase } from '../OxyServices.base';
-import { CACHE_TIMES } from './mixinHelpers';
-
-export function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
-    /**
-     * Track an analytics event
-     * @param eventName - Name of the event to track
-     * @param properties - Optional event properties
-     */
-    async trackEvent(eventName: string, properties?: Record<string, any>): Promise<void> {
-      try {
-        await this.makeRequest('POST', '/analytics/events', {
-          event: eventName,
-          properties
-        }, { cache: false, retry: false }); // Don't retry analytics events
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /**
-     * Get analytics data for a date range
-     * @param startDate - Optional start date (ISO string)
-     * @param endDate - Optional end date (ISO string)
-     * @returns Analytics data
-     */
-    async getAnalytics(startDate?: string, endDate?: string): Promise<any> {
-      try {
-        const params: any = {};
-        if (startDate) params.startDate = startDate;
-        if (endDate) params.endDate = endDate;
-        
-        return await this.makeRequest('GET', '/analytics', params, {
-          cache: true,
-          cacheTTL: CACHE_TIMES.LONG,
-        });
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-  };
-}
-

package/src/mixins/OxyServices.appData.ts

@@ -1,158 +0,0 @@
-/**
- * Per-user App-Data Mixin
- *
- * Thin client around `/users/me/app-data/...` — a generic per-user JSON KV
- * store on the API. Authenticated callers can read, write, list, and delete
- * entries scoped to their own user account.
- *
- * Identifier rules (must match the API):
- *   - Both `namespace` and `key` must match `/^[a-z0-9_-]{1,64}$/u`.
- *
- * Limits (enforced by the API):
- *   - Serialized JSON values are capped at 64 KB.
- *   - Writes are rate-limited to 100 / minute / user.
- *
- * Intended use cases are small bits of cross-device app state — e.g. Academy
- * course progress, "last viewed" markers, dismissed banner flags. Do not use
- * this for large blobs or anything that needs server-side querying; it's a
- * write-it-and-read-it-back store.
- */
-
-import type { OxyServicesBase } from '../OxyServices.base';
-
-/**
- * Identifier validator — mirror of the API regex. Validating client-side
- * gives consumers a clean throw before the request even leaves the device.
- */
-const APP_DATA_IDENTIFIER_PATTERN = /^[a-z0-9_-]{1,64}$/u;
-
-/** Thrown when a namespace or key fails the kebab/snake-case validator. */
-export class OxyAppDataIdentifierError extends Error {
-  constructor(field: 'namespace' | 'key', value: string) {
-    super(
-      `Invalid app-data ${field} "${value}": must match [a-z0-9_-]{1,64} (lowercase letters, digits, dashes, underscores).`,
-    );
-    this.name = 'OxyAppDataIdentifierError';
-  }
-}
-
-function assertIdentifier(field: 'namespace' | 'key', value: string): void {
-  if (!APP_DATA_IDENTIFIER_PATTERN.test(value)) {
-    throw new OxyAppDataIdentifierError(field, value);
-  }
-}
-
-/** Wire shape of `GET /users/me/app-data/:namespace/:key`. */
-interface AppDataValueResponse<T> {
-  value: T | null;
-}
-
-/** Wire shape of `GET /users/me/app-data/:namespace`. */
-interface AppDataNamespaceResponse<T> {
-  entries: Record<string, T>;
-}
-
-export function OxyServicesAppDataMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
-    /**
-     * Read the value stored under `(namespace, key)` for the current user.
-     *
-     * @returns The previously-stored value, or `null` if nothing has been
-     *   stored yet. Never throws on "not found" — a missing entry is
-     *   semantically a `null` value.
-     */
-    async getAppData<TValue = unknown>(
-      namespace: string,
-      key: string,
-    ): Promise<TValue | null> {
-      assertIdentifier('namespace', namespace);
-      assertIdentifier('key', key);
-
-      return this.withAuthRetry(async () => {
-        const response = await this.makeRequest<AppDataValueResponse<TValue>>(
-          'GET',
-          `/users/me/app-data/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
-          undefined,
-          { cache: false },
-        );
-        return response?.value ?? null;
-      }, 'getAppData');
-    }
-
-    /**
-     * Upsert the value under `(namespace, key)` for the current user.
-     *
-     * Returns the value the server confirmed it stored — typically the same
-     * value the caller passed in, but consumers should prefer the returned
-     * value (the API is the source of truth).
-     *
-     * @throws OxyAppDataIdentifierError when namespace or key is malformed.
-     */
-    async setAppData<TValue = unknown>(
-      namespace: string,
-      key: string,
-      value: TValue,
-    ): Promise<TValue> {
-      assertIdentifier('namespace', namespace);
-      assertIdentifier('key', key);
-
-      return this.withAuthRetry(async () => {
-        const response = await this.makeRequest<AppDataValueResponse<TValue>>(
-          'PUT',
-          `/users/me/app-data/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
-          { value },
-          { cache: false },
-        );
-        // The server echoes the stored value back; fall back to the caller's
-        // input only if the server somehow omitted it (defensive — the route
-        // always sets it).
-        return (response?.value ?? value) as TValue;
-      }, 'setAppData');
-    }
-
-    /**
-     * Delete the value stored under `(namespace, key)` for the current user.
-     *
-     * Idempotent — resolves successfully whether or not the entry existed.
-     */
-    async deleteAppData(namespace: string, key: string): Promise<void> {
-      assertIdentifier('namespace', namespace);
-      assertIdentifier('key', key);
-
-      await this.withAuthRetry(async () => {
-        await this.makeRequest<void>(
-          'DELETE',
-          `/users/me/app-data/${encodeURIComponent(namespace)}/${encodeURIComponent(key)}`,
-          undefined,
-          { cache: false },
-        );
-      }, 'deleteAppData');
-    }
-
-    /**
-     * List every entry stored under `namespace` for the current user.
-     *
-     * Returns an empty object when the namespace contains no entries (the
-     * endpoint never 404s on an empty namespace).
-     */
-    async listAppData<TValue = unknown>(
-      namespace: string,
-    ): Promise<Record<string, TValue>> {
-      assertIdentifier('namespace', namespace);
-
-      return this.withAuthRetry(async () => {
-        const response = await this.makeRequest<AppDataNamespaceResponse<TValue>>(
-          'GET',
-          `/users/me/app-data/${encodeURIComponent(namespace)}`,
-          undefined,
-          { cache: false },
-        );
-        return response?.entries ?? {};
-      }, 'listAppData');
-    }
-  };
-}