@oxy.so/core 4.6.0 → 4.9.0

package/dist/types/i18n/locales/es-ES.d.ts

@@ -1,4 +1,65 @@
 declare const dict: {
+    organizationDirectory: {
+        invalidName: string;
+        review: {
+            title: string;
+            forbidden: string;
+            empty: string;
+            hint: string;
+            independent: string;
+            evidence: string;
+            approved: string;
+            rejected: string;
+            conflict: string;
+            failed: string;
+        };
+        title: string;
+        search: string;
+        searchHint: string;
+        empty: string;
+        retry: string;
+        loadMore: string;
+        failed: string;
+        unclaimed: string;
+        claimed: string;
+        inactive: string;
+        newAccount: string;
+        newAccountHint: string;
+        addDirectory: string;
+        directoryHint: string;
+        added: string;
+        back: string;
+        type: string;
+        types: {
+            business: string;
+            nonprofit: string;
+            public_body: string;
+            community: string;
+            other: string;
+        };
+        name: string;
+        legalName: string;
+        website: string;
+        country: string;
+        save: string;
+        saved: string;
+        invalid: string;
+        saveFailed: string;
+        claim: string;
+        claimHint: string;
+        evidence: string;
+        evidenceHint: string;
+        claimSent: string;
+        claimFailed: string;
+        claimedHint: string;
+        requests: string;
+        pending: string;
+        approved: string;
+        rejected: string;
+        requestError: string;
+        view: string;
+        readonly: string;
+    };
     signin: {
         title: string;
         subtitle: string;
@@ -1364,6 +1425,13 @@ declare const dict: {
         };
     };
     preferences: {
+        displayCurrency: {
+            label: string;
+            saveFailed: string;
+            unavailable: string;
+            approximate: string;
+            estimate: string;
+        };
         title: string;
         subtitle: string;
         sections: {

package/dist/types/index.d.ts

@@ -99,3 +99,6 @@ export { AUTH_WEB_ORIGIN, CENTRAL_IDP_APEX } from './utils/authWebUrl';
 export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams, OxyAuthScreen } from './utils/oauthPkce';
 export { packageInfo } from './constants/version';
+export type { Organization, OrganizationType, CreateOrganization, UpdateOrganization, OrganizationSearch, OrganizationClaim, } from '@oxy.so/contracts';
+export type { ProfileAccessInput, ProfileAccessDecision } from '@oxy.so/contracts';
+export type { AccountInvitation, AccountInvitationPreview } from './api/accounts';

package/dist/types/models/interfaces.d.ts

@@ -242,6 +242,8 @@ export interface NotificationPreferences {
  * Persisted on the User document.
  */
 export interface UserPreferences {
+    /** Preferred display units only; never changes a payment's denomination. */
+    displayCurrency?: 'USD' | 'EUR' | 'FAIR';
     /** BCP-47 language tag, e.g. "en-US", "es-ES". Empty string = follow device. */
     language?: string;
     /** Theme mode preference. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "4.6.0",
+  "version": "4.9.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -176,11 +176,11 @@
     }
   },
   "dependencies": {
-    "@oxy.so/telemetry": "^1.2.0",
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxy.so/contracts": "4.13.0",
+    "@oxy.so/contracts": "4.15.0",
     "@oxy.so/protocol": "^1.2.2",
+    "@oxy.so/telemetry": "^1.2.0",
     "@scure/bip39": "^1.6.0",
     "buffer": "^6.0.3",
     "express-rate-limit": "^8.6.0",

package/src/OxyServices.ts

@@ -1,3 +1,4 @@
+import { SafetyApi } from './api/safety';
 /**
  * `OxyServices` — the Oxy API client.
  *
@@ -32,6 +33,7 @@ import { PrivacyApi } from './api/privacy';
 import { NotificationsApi } from './api/notifications';
 import { AssetsApi } from './api/assets';
 import { IdentityApi } from './api/identity';
+import { OrganizationsApi } from './api/organizations';
 import { AccountsApi } from './api/accounts';
 import { AppsApi } from './api/apps';
 import { LinkedAccountsApi } from './api/linkedAccounts';
@@ -191,6 +193,8 @@ export class OxyServices {
   private _assets?: AssetsApi;
   private _identity?: IdentityApi;
   private _accounts?: AccountsApi;
+  private _organizations?: OrganizationsApi;
+  private _safety?: SafetyApi;
   private _apps?: AppsApi;
   private _linkedAccounts?: LinkedAccountsApi;
   private _agency?: AgencyApi;
@@ -245,6 +249,16 @@ export class OxyServices {
     return this._identity;
   }
   /** The account graph: accounts and their members. */
+  get safety(): SafetyApi {
+    if (!this._safety) this._safety = new SafetyApi(this.context);
+    return this._safety;
+  }
+
+  get organizations(): OrganizationsApi {
+    if (!this._organizations) this._organizations = new OrganizationsApi(this.context);
+    return this._organizations;
+  }
+
   get accounts(): AccountsApi {
     if (!this._accounts) this._accounts = new AccountsApi(this.context);
     return this._accounts;

package/src/api/accounts.ts

@@ -1,3 +1,4 @@
+import type { OrganizationType } from '@oxy.so/contracts';
 /**
  * `oxy.accounts` — the unified account graph (`/accounts`).
  *
@@ -236,6 +237,7 @@ export interface CreateAccountInput {
    * keep working. At most `MAX_ACCOUNT_CATEGORIES`, no duplicates.
    */
   accountCategories?: AccountCategoryId[];
+  organizationType?: OrganizationType;
   /**
    * Create the account already opted OUT of discovery — kept out of people
    * search, the follow-graph lists, `/similar` and the recommendation pools,
@@ -301,6 +303,7 @@ export interface UpdateAccountInput {
    * every other field here (`account:update`).
    */
   character?: AvatarCharacter;
+  organizationType?: OrganizationType;
 }
 
 /** Input accepted by `accounts.members.invite`. The owner role cannot be invited. */
@@ -388,7 +391,8 @@ export class AccountMembersApi {
   }
 
   /**
-   * Add a member to an account.
+   * @deprecated The API returns 410. Use accounts.invitations.create with an email.
+   * Access is granted only after recipient confirmation.
    * @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
@@ -473,13 +477,93 @@ export class AccountAgentKeysApi {
   }
 }
 
+export interface AccountInvitation {
+  id: string;
+  accountId: string;
+  email: string;
+  role: Exclude<AccountRole, 'owner'>;
+  status: 'pending' | 'expired' | 'accepted' | 'cancelled';
+  expiresAt: string;
+  createdAt: string;
+}
+export interface AccountInvitationPreview {
+  invitation: AccountInvitation;
+  account: { id: string; username: string | null; displayName: string | null };
+}
+
+/** Consent-based invitations; never cached or queued as offline mutations. */
+export class AccountInvitationsApi {
+  constructor(private readonly ctx: OxyContext) {}
+  async list(accountId: string): Promise<AccountInvitation[]> {
+    return (
+      await this.ctx.request<{ invitations: AccountInvitation[] }>(
+        'GET',
+        `/accounts/${enc(accountId)}/invitations`,
+        undefined,
+        { cache: false },
+      )
+    ).invitations;
+  }
+  async create(
+    accountId: string,
+    data: { email: string; role: Exclude<AccountRole, 'owner'>; inherit?: boolean },
+  ): Promise<AccountInvitation> {
+    return (
+      await this.ctx.request<{ invitation: AccountInvitation }>(
+        'POST',
+        `/accounts/${enc(accountId)}/invitations`,
+        data,
+        { cache: false },
+      )
+    ).invitation;
+  }
+  async resend(accountId: string, id: string): Promise<AccountInvitation> {
+    return (
+      await this.ctx.request<{ invitation: AccountInvitation }>(
+        'POST',
+        `/accounts/${enc(accountId)}/invitations/${enc(id)}/resend`,
+        undefined,
+        { cache: false },
+      )
+    ).invitation;
+  }
+  async cancel(accountId: string, id: string): Promise<AccountSuccessResult> {
+    return this.ctx.request(
+      'DELETE',
+      `/accounts/${enc(accountId)}/invitations/${enc(id)}`,
+      undefined,
+      { cache: false },
+    );
+  }
+  async preview(token: string): Promise<AccountInvitationPreview> {
+    return this.ctx.request('POST', '/accounts/invitations/preview', { token }, { cache: false });
+  }
+  /** selectedUserId must equal the currently authenticated personal account. */
+  async accept(
+    token: string,
+    selectedUserId: string,
+  ): Promise<AccountSuccessResult & { accountId: string }> {
+    const result = await this.ctx.request<AccountSuccessResult & { accountId: string }>(
+      'POST',
+      '/accounts/invitations/accept',
+      { token, selectedUserId, confirmed: true },
+      { cache: false },
+    );
+    invalidateAccountMembership(this.ctx, result.accountId);
+    evictOxyAccountForestCache(this.ctx.http);
+    return result;
+  }
+}
+
 export class AccountsApi {
   /** Who can act on an account, and with what role. */
   readonly members: AccountMembersApi;
+  readonly invitations: AccountInvitationsApi;
   readonly agentKeys: AccountAgentKeysApi;
 
   constructor(private readonly ctx: OxyContext) {
     this.members = new AccountMembersApi(ctx);
+    this.invitations = new AccountInvitationsApi(ctx);
     this.agentKeys = new AccountAgentKeysApi(ctx);
   }
 

package/src/api/billing.ts

@@ -1,5 +1,11 @@
 import {
   personalPlanCheckoutRequestSchema,
+  productPlanCheckoutRequestSchema,
+  productSubscriptionRenewalRequestSchema,
+  type ProductSubscriptionRenewalRequest,
+  productPlanCatalogueSchema,
+  type ProductPlanCheckoutRequest,
+  type ProductPlanCatalogue,
   personalPlanCheckoutResultSchema,
   type PersonalPlanCheckoutRequest,
   type PersonalPlanCheckoutResult,
@@ -127,6 +133,43 @@ export interface WalletTransactionsPage {
 export class BillingApi {
   constructor(protected readonly ctx: OxyContext) {}
 
+  async renewProductSubscription(
+    request: ProductSubscriptionRenewalRequest,
+  ): Promise<PersonalPlanCheckoutResult> {
+    return personalPlanCheckoutResultSchema.parse(
+      await this.ctx.request<unknown>(
+        'POST',
+        '/billing/product-subscriptions/renew',
+        productSubscriptionRenewalRequestSchema.parse(request),
+        { cache: false },
+      ),
+    );
+  }
+
+  async startProductPlanCheckout(
+    request: ProductPlanCheckoutRequest,
+  ): Promise<PersonalPlanCheckoutResult> {
+    return personalPlanCheckoutResultSchema.parse(
+      await this.ctx.request<unknown>(
+        'POST',
+        '/billing/checkout/product-plan',
+        productPlanCheckoutRequestSchema.parse(request),
+        { cache: false },
+      ),
+    );
+  }
+
+  async productPlans(productId: string): Promise<ProductPlanCatalogue> {
+    return productPlanCatalogueSchema.parse(
+      await this.ctx.request<unknown>(
+        'GET',
+        `/billing/product-plans/${encodeURIComponent(productId)}`,
+        undefined,
+        { cache: false },
+      ),
+    );
+  }
+
   async startPersonalPlanCheckout(
     request: PersonalPlanCheckoutRequest,
   ): Promise<PersonalPlanCheckoutResult> {

package/src/api/organizations.ts

@@ -0,0 +1,180 @@
+import {
+  organizationSchema,
+  organizationListSchema,
+  organizationBatchSchema,
+  organizationClaimSchema,
+  organizationExternalSchema,
+  organizationExternalResolutionSchema,
+  organizationImportBatchResultSchema,
+  organizationCurationResultSchema,
+  type OrganizationCuration,
+  type OrganizationImportBatch,
+  organizationClaimListSchema,
+  organizationClaimDetailSchema,
+  type OrganizationClaimListQuery,
+  type CreateOrganization,
+  type OrganizationSearch,
+  type UpdateOrganization,
+  type OrganizationClaimInput,
+  type OrganizationClaimReview,
+  type OrganizationExternalInput,
+  type OrganizationMerge,
+} from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
+
+/** The public canonical organization directory. Claiming changes authority, never identity. */
+export class OrganizationsApi {
+  constructor(private readonly ctx: OxyContext) {}
+  async search(input: OrganizationSearch) {
+    return organizationListSchema.parse(
+      await this.ctx.request('GET', '/organizations', input, { cache: false, skipAuth: true }),
+    );
+  }
+  async get(accountId: string) {
+    return organizationSchema.parse(
+      await this.ctx.request('GET', `/organizations/${encodeURIComponent(accountId)}`, undefined, {
+        cache: false,
+        skipAuth: true,
+      }),
+    );
+  }
+  async batch(input: { ids: string[] }) {
+    return organizationBatchSchema.parse(
+      await this.ctx.request('POST', '/organizations/batch', input, {
+        cache: false,
+        skipAuth: true,
+      }),
+    );
+  }
+  async create(input: CreateOrganization) {
+    return organizationSchema.parse(
+      await this.ctx.request('POST', '/organizations', input, { cache: false }),
+    );
+  }
+  async update(accountId: string, input: UpdateOrganization) {
+    const result = organizationSchema.parse(
+      await this.ctx.request('PATCH', `/organizations/${encodeURIComponent(accountId)}`, input, {
+        cache: false,
+      }),
+    );
+
+    evictOxyIdentityCache(this.ctx.http, accountId);
+    return result;
+  }
+  async claim(accountId: string, input: OrganizationClaimInput) {
+    return organizationClaimSchema.parse(
+      await this.ctx.request(
+        'POST',
+        `/organizations/${encodeURIComponent(accountId)}/claims`,
+        input,
+        { cache: false },
+      ),
+    );
+  }
+  async myClaims(input: OrganizationClaimListQuery = {}) {
+    return organizationClaimListSchema.parse(
+      await this.ctx.request('GET', '/organizations/claims/mine', input, { cache: false }),
+    );
+  }
+  async myClaim(claimId: string) {
+    return organizationClaimDetailSchema.parse(
+      await this.ctx.request(
+        'GET',
+        `/organizations/claims/mine/${encodeURIComponent(claimId)}`,
+        undefined,
+        { cache: false },
+      ),
+    );
+  }
+  async reviewClaims(input: OrganizationClaimListQuery = {}) {
+    return organizationClaimListSchema.parse(
+      await this.ctx.request('GET', '/organizations/claims/review', input, { cache: false }),
+    );
+  }
+  async reviewClaimDetail(claimId: string) {
+    return organizationClaimDetailSchema.parse(
+      await this.ctx.request(
+        'GET',
+        `/organizations/claims/review/${encodeURIComponent(claimId)}`,
+        undefined,
+        { cache: false },
+      ),
+    );
+  }
+  async reviewClaim(claimId: string, input: OrganizationClaimReview) {
+    const result = organizationClaimSchema.parse(
+      await this.ctx.request(
+        'POST',
+        `/organizations/claims/${encodeURIComponent(claimId)}/review`,
+        input,
+        { cache: false },
+      ),
+    );
+
+    evictOxyIdentityCache(this.ctx.http, result.accountId);
+    return result;
+  }
+  async importBatch(input: OrganizationImportBatch) {
+    if (!this.ctx.service?.available)
+      throw new Error('Organization batch import requires an OxyServer service identity');
+    return organizationImportBatchResultSchema.parse(
+      await this.ctx.service.request('POST', '/organizations/external/batch', input, {
+        cache: false,
+      }),
+    );
+  }
+  async importExternal(input: OrganizationExternalInput) {
+    return organizationExternalSchema.parse(
+      await this.ctx.request('POST', '/organizations/external', input, { cache: false }),
+    );
+  }
+  async resolveExternal(input: { namespace: string; externalId: string }) {
+    return organizationExternalResolutionSchema.parse(
+      await this.ctx.request(
+        'GET',
+        `/organizations/external/${encodeURIComponent(input.namespace)}/${encodeURIComponent(input.externalId)}`,
+        undefined,
+        { cache: false },
+      ),
+    );
+  }
+  async curate(accountId: string, input: OrganizationCuration) {
+    const result = organizationCurationResultSchema.parse(
+      await this.ctx.request(
+        'POST',
+        `/organizations/${encodeURIComponent(accountId)}/curation`,
+        input,
+        { cache: false },
+      ),
+    );
+
+    evictOxyIdentityCache(this.ctx.http, accountId);
+    return result;
+  }
+  async merge(accountId: string, input: OrganizationMerge) {
+    const result = organizationSchema.parse(
+      await this.ctx.request(
+        'POST',
+        `/organizations/${encodeURIComponent(accountId)}/merge`,
+        input,
+        { cache: false },
+      ),
+    );
+
+    evictOxyIdentityCache(this.ctx.http, accountId);
+    evictOxyIdentityCache(this.ctx.http, result.accountId);
+    return result;
+  }
+  async *iterate(input: OrganizationSearch) {
+    let cursor = input.cursor;
+    const seen = new Set<string>();
+    do {
+      const page = await this.search({ ...input, cursor });
+      yield* page.items;
+      cursor = page.nextCursor ?? undefined;
+      if (cursor && seen.has(cursor)) throw new Error('Organization directory repeated a cursor');
+      if (cursor) seen.add(cursor);
+    } while (cursor);
+  }
+}

package/src/api/safety.ts

@@ -0,0 +1,33 @@
+import {
+  profileAccessInputSchema,
+  profileAccessDecisionSchema,
+  type ProfileAccessInput,
+} from '@oxy.so/contracts';
+import type { OxyContext } from '../client/context';
+
+export class SafetyApi {
+  constructor(private readonly ctx: OxyContext) {}
+  /** Server callers must explicitly supply the incoming user bearer or null for anonymous access. */
+  async profileAccess(input: ProfileAccessInput, options?: { accessToken: string | null }) {
+    if (this.ctx.service && options === undefined)
+      throw new Error('Server profile access requires an explicit requester bearer or null');
+    return profileAccessDecisionSchema.parse(
+      await this.ctx.request(
+        'GET',
+        '/safety/profile-access',
+        profileAccessInputSchema.parse(input),
+        {
+          cache: false,
+          ...(options
+            ? {
+                skipAuth: true,
+                headers: options.accessToken
+                  ? { Authorization: `Bearer ${options.accessToken}` }
+                  : {},
+              }
+            : {}),
+        },
+      ),
+    );
+  }
+}

package/src/i18n/locales/en-US.ts

@@ -1,4 +1,72 @@
 const dict = {
+  organizationDirectory: {
+    invalidName: 'Use a plain-text organization name (up to 300 characters).',
+    review: {
+      title: 'Review organization access requests',
+      forbidden: 'This action requires current staff authorization.',
+      empty: 'No requests are waiting for review.',
+      hint: 'Review the supporting evidence independently. Approval grants management access to the existing organization account.',
+      independent: 'Another reviewer must decide your own request.',
+      evidence: 'Review evidence reference',
+      approved: 'Approve access',
+      rejected: 'Reject request',
+      conflict:
+        'This request or organization changed. Refresh the queue before making another decision.',
+      failed: 'The review could not be saved. Your decision has not been confirmed.',
+    },
+    title: 'Organization directory',
+    search: 'Find your organization',
+    searchHint:
+      'Find an existing organization before creating an account. Its identity is shared across Oxy apps.',
+    empty: 'No organizations found.',
+    retry: 'Try again',
+    loadMore: 'Show more',
+    failed: 'Could not load the organization directory.',
+    unclaimed: 'Unclaimed',
+    claimed: 'Managed organization',
+    inactive: 'Inactive',
+    newAccount: 'Create a new organization account',
+    newAccountHint:
+      'Create and manage a new organization. Choose an existing entry if your organization is already listed.',
+    addDirectory: 'Add to directory',
+    directoryHint:
+      'This creates a shared, unclaimed entry. It does not give you access to manage the organization.',
+    added: 'Organization added to the directory',
+    back: 'Back to search',
+    type: 'Organization type',
+    types: {
+      business: 'Business',
+      nonprofit: 'Nonprofit',
+      public_body: 'Public body',
+      community: 'Community',
+      other: 'Other',
+    },
+    name: 'Organization name',
+    legalName: 'Legal name',
+    website: 'Website',
+    country: 'Country code',
+    save: 'Save organization',
+    saved: 'Organization updated',
+    invalid:
+      'Check the organization details. Use a complete website URL and a two-letter country code.',
+    saveFailed: 'Could not save the organization. Try again.',
+    claim: 'Request management access',
+    claimHint:
+      'Oxy reviews evidence of your authority. A request does not grant access or verify your role.',
+    evidence: 'Supporting evidence reference',
+    evidenceHint:
+      'Provide a reference to your private verification case or supporting records. Only you and reviewers can read it.',
+    claimSent: 'Request submitted for review',
+    claimFailed: 'Could not submit your request. Try again.',
+    claimedHint: 'This organization already has managers. Contact a manager to request access.',
+    requests: 'Organization access requests',
+    pending: 'Pending review',
+    approved: 'Approved',
+    rejected: 'Rejected',
+    requestError: 'Could not load your access requests.',
+    view: 'Organization details',
+    readonly: 'You do not have permission to edit this organization.',
+  },
   signin: {
     title: 'Sign in',
     subtitle: 'Use your Oxy account',
@@ -1397,6 +1465,14 @@ const dict = {
     },
   },
   preferences: {
+    displayCurrency: {
+      label: 'Display currency',
+      saveFailed: 'Could not save display currency. Please try again.',
+      unavailable: 'Equivalent in {{currency}} unavailable',
+      approximate: 'Approx. {{amount}}',
+      estimate: 'Display estimate. The final payable amount is quoted in FAIR at checkout.',
+    },
+
     title: 'Preferences',
     subtitle: 'Theme, motion, and regional settings',
     sections: {