@oxy.so/core 1.18.1 → 3.0.0

package/dist/types/OxyServices.d.ts

@@ -1,142 +1,171 @@
 /**
- * OxyServices - Unified client for Oxy API and Oxy Cloud
+ * `OxyServices` — the Oxy API client.
  *
- * # Usage Examples
+ * ```ts
+ * import { OxyServices } from '@oxy.so/core';
  *
- * ## Browser (ESM/TypeScript)
+ * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
  *
- * ```typescript
- * import { OxyServices } from './core/OxyServices';
- *
- * const oxy = new OxyServices({
- *   baseURL: 'https://api.oxy.so',
- *   cloudURL: 'https://cloud.oxy.so',
- * });
- *
- * // Authenticate and fetch user
- * await oxy.setTokens('ACCESS_TOKEN');
- * const user = await oxy.getCurrentUser();
- *
- * // Upload a file (browser File API)
- * const fileInput = document.querySelector('input[type=file]');
- * const file = fileInput.files[0];
- * await oxy.uploadRawFile(file);
- *
- * // Get a file download URL for <img src>
- * const url = oxy.getFileDownloadUrl('fileId', 'thumb');
+ * 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);
  * ```
  *
- * ## Node.js (CommonJS/TypeScript)
- *
- * ```typescript
- * import { OxyServices } from './core/OxyServices';
- * import fs from 'fs';
- *
- * const oxy = new OxyServices({
- *   baseURL: 'https://api.oxy.so',
- *   cloudURL: 'https://cloud.oxy.so',
- * });
- *
- * // Authenticate and fetch user
- * await oxy.setTokens('ACCESS_TOKEN');
- * const user = await oxy.getCurrentUser();
- *
- * // Upload a file (Node.js Buffer)
- * const buffer = fs.readFileSync('myfile.png');
- * const blob = new Blob([buffer]);
- * await oxy.uploadRawFile(blob, { filename: 'myfile.png' });
+ * 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.
  *
- * // Get a file download URL
- * const url = oxy.getFileDownloadUrl('fileId');
- * ```
- *
- * ## Configuration
- * - `baseURL`: Oxy API endpoint (e.g., https://api.oxy.so)
- * - `cloudURL`: Oxy Cloud/CDN endpoint (e.g., https://cloud.oxy.so)
- *
- * See method JSDoc for more details and options.
+ * Servers use `OxyServer` from `@oxy.so/core/server`: the same client plus the
+ * service-token lane and the Express / Socket.IO middleware.
  */
-import { type LinkedHttpClient, type OxyConfig } from './OxyServices.base';
-import { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError } from './OxyServices.errors';
-import { composeOxyServices } from './mixins';
-import type { OxyAuthRefusal } from './mixins/OxyServices.utility';
-/**
- * OxyServices - Unified client library for interacting with the Oxy API
- *
- * This class provides all API functionality in one simple, easy-to-use interface.
- *
- * ## Architecture
- * - **HttpService**: Unified HTTP service handling authentication, caching, deduplication, queuing, and retry
- * - **OxyServices**: Provides high-level API methods
- *
- * ## 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'
- * });
- * ```
- */
-declare const OxyServicesComposed: import("./mixins").ComposedOxyServicesConstructor;
-export declare class OxyServices extends OxyServicesComposed {
-    constructor(config: OxyConfig);
+import { HttpService, type RequestOptions } from './HttpService';
+import type { OxyConfig as OxyConfigBase } from './models/interfaces';
+import type { HttpMethod, OxyContext } from './client/context';
+import { SessionApi } from './api/session';
+import { AuthApi } from './api/auth';
+import { UsersApi } from './api/users';
+import { FollowsApi } from './api/follows';
+import { PrivacyApi } from './api/privacy';
+import { NotificationsApi } from './api/notifications';
+import { AssetsApi } from './api/assets';
+import { IdentityApi } from './api/identity';
+import { AccountsApi } from './api/accounts';
+import { AppsApi } from './api/apps';
+import { LinkedAccountsApi } from './api/linkedAccounts';
+import { AgencyApi } from './api/agency';
+import { StoreApi } from './api/store';
+import { BillingApi } from './api/billing';
+import { ReputationApi } from './api/reputation';
+import { CivicApi } from './api/civic';
+import { NodesApi } from './api/nodes';
+import { DevicesApi } from './api/devices';
+import { TopicsApi } from './api/topics';
+import { AppDataApi } from './api/appData';
+import { ContactsApi } from './api/contacts';
+export interface OxyConfig extends OxyConfigBase {
+    /** Oxy Cloud (file CDN) origin. Default `https://cloud.oxy.so`. */
+    cloudURL?: string;
 }
-export interface OxyServices extends InstanceType<ReturnType<typeof composeOxyServices>> {
-    createLinkedClient(config: OxyConfig): LinkedHttpClient;
-    auth(options?: {
-        debug?: boolean;
-        onError?: (error: unknown) => unknown;
-        loadUser?: boolean;
-        optional?: boolean;
-        onRefusal?: (refusal: OxyAuthRefusal) => void;
-        serviceTokenJwksUrl?: string;
-        jwtSecret?: string;
-        expectedIssuer?: string;
-        expectedAudience?: string;
-    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
-    authSocket(options?: {
-        debug?: boolean;
-    }): (socket: unknown, next: (err?: Error) => void) => Promise<void>;
-    serviceAuth(options?: {
-        debug?: boolean;
-        onRefusal?: (refusal: OxyAuthRefusal) => void;
-        serviceTokenJwksUrl?: string;
-        jwtSecret?: string;
-        expectedIssuer?: string;
-        expectedAudience?: string;
-    }): (req: unknown, res: unknown, next: (err?: unknown) => void) => Promise<void>;
-    requireScope(scope: string): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
-    assetUpdateVisibility(fileId: string, visibility: 'private' | 'public' | 'unlisted'): Promise<unknown>;
+/** An HTTP client for an app's own backend, bound to this client's session. */
+export interface LinkedHttpClient {
+    client: HttpService;
+    dispose(): void;
 }
-export { AssetUrlResolutionError, OxyAuthenticationError, OxyAuthenticationTimeoutError, ServiceAssetMetadataError };
-/**
- * Default Oxy Cloud URL — used when no `cloudURL` is provided to OxyServices.
- */
+/** Default Oxy Cloud URL — used when no `cloudURL` is given. */
 export declare const OXY_CLOUD_URL = "https://cloud.oxy.so";
-/**
- * Export the default Oxy API URL (for documentation)
- */
-export declare const OXY_API_URL: string;
-/**
- * Pre-configured client instance for easy import
- * Uses OXY_API_URL as baseURL and OXY_CLOUD_URL as cloudURL
- */
-export declare const oxyClient: OxyServices;
+/** Default Oxy API URL. */
+export declare const OXY_API_URL = "https://api.oxy.so";
+export declare class OxyServices {
+    /** The transport. Every namespace call goes through it. */
+    readonly http: HttpService;
+    readonly config: Readonly<OxyConfig>;
+    /** Oxy Cloud (file CDN) origin. */
+    readonly cloudURL: string;
+    /** Shared with every namespace; see `client/context.ts`. */
+    protected readonly context: OxyContext;
+    constructor(config: OxyConfig);
+    /** The Oxy API origin this client talks to. */
+    get baseURL(): string;
+    /**
+     * 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`.
+     */
+    request<T>(method: HttpMethod, url: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    /** `GET /health`. */
+    health(): Promise<{
+        status: string;
+        timestamp?: string;
+        [key: string]: unknown;
+    }>;
+    /** The response cache (GETs only, identity-scoped). */
+    readonly cache: {
+        /** Drop every cached response. */
+        clear: () => void;
+        /** Drop one cached response by key (`GET:/path`), every identity's variant. */
+        delete: (key: string) => void;
+        /** Drop every cached response whose key starts with `prefix`; returns how many. */
+        deletePrefix: (prefix: string) => number;
+        stats: () => {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+    };
+    /**
+     * 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: OxyConfig): LinkedHttpClient;
+    /** Release this client: its cache stops being swept and its session ends. */
+    dispose(): void;
+    private _session?;
+    private _auth?;
+    private _users?;
+    private _follows?;
+    private _privacy?;
+    private _notifications?;
+    private _assets?;
+    private _identity?;
+    private _accounts?;
+    private _apps?;
+    private _linkedAccounts?;
+    private _agency?;
+    private _store?;
+    private _billing?;
+    private _reputation?;
+    private _civic?;
+    private _nodes?;
+    private _devices?;
+    private _topics?;
+    private _appData?;
+    private _contacts?;
+    /** This client's auth state (token, user id) and its server session. */
+    get session(): SessionApi;
+    /** Signing in, signing up, and the account's credentials. */
+    get auth(): AuthApi;
+    /** People and their profiles. */
+    get users(): UsersApi;
+    /** The follow graph: people and every other followable target. */
+    get follows(): FollowsApi;
+    /** Privacy settings, blocks and restrictions. */
+    get privacy(): PrivacyApi;
+    /** The in-app inbox and push tokens. */
+    get notifications(): NotificationsApi;
+    /** Files: upload, link, URLs, content. */
+    get assets(): AssetsApi;
+    /** DID, keys, identity links, domains, backup and the signed export. */
+    get identity(): IdentityApi;
+    /** The account graph: accounts and their members. */
+    get accounts(): AccountsApi;
+    /** Applications an account owns, and the ones this user granted access. */
+    get apps(): AppsApi;
+    /** External accounts (Mastodon, Bluesky) linked by OAuth. */
+    get linkedAccounts(): LinkedAccountsApi;
+    /** Delegated capabilities for agents. */
+    get agency(): AgencyApi;
+    /** The app store: storefront, reviews, and a publisher's listing. */
+    get store(): StoreApi;
+    /** Subscription, wallet and payments. */
+    get billing(): BillingApi;
+    /** Oxy Trust reputation (read-only for people; apps award it). */
+    get reputation(): ReputationApi;
+    /** Oxy ID: cards, attestations, vouching, personhood, credentials. */
+    get civic(): CivicApi;
+    /** The user's personal data node. */
+    get nodes(): NodesApi;
+    /** This user's devices, their sessions, and device sign-in. */
+    get devices(): DevicesApi;
+    get topics(): TopicsApi;
+    /** Per-app key/value data stored on the user's account. */
+    get appData(): AppDataApi;
+    get contacts(): ContactsApi;
+}

package/dist/types/OxyServices.errors.d.ts

@@ -106,3 +106,45 @@ export declare class ServiceLinkedDownloadUrlError extends Error {
 export declare class OxyAuthenticationTimeoutError extends OxyAuthenticationError {
     constructor(operationName: string, timeoutMs: number);
 }
+/**
+ * The one error every `OxyServices` call rejects with.
+ *
+ * `status` is the HTTP status (0 when no response arrived: a network failure,
+ * a timeout or a cancellation), `code` the API's machine code when it sent one
+ * (else a transport code such as `TIMEOUT`, `NETWORK_ERROR`, `CANCELLED`), and
+ * `details` the API's structured detail. The original error is `cause`.
+ */
+export declare class OxyApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    /** The raw response, when one arrived. */
+    readonly response?: {
+        status: number;
+        statusText: string;
+        data?: unknown;
+    };
+    /** True when the caller cancelled the request (never a failure). */
+    readonly cancelled: boolean;
+    /** True when the request timed out. */
+    readonly timeout: boolean;
+    constructor(message: string, init: {
+        status: number;
+        code: string;
+        details?: Record<string, unknown>;
+        response?: {
+            status: number;
+            statusText: string;
+            data?: unknown;
+        };
+        cancelled?: boolean;
+        timeout?: boolean;
+        cause?: unknown;
+    });
+}
+/**
+ * Normalise anything a request rejected with into an `OxyApiError`. An error
+ * that already is one (or a typed SDK error such as `OxyAuthenticationError`)
+ * passes through unchanged.
+ */
+export declare function toOxyApiError(error: unknown): Error;