@oxy.so/core 1.0.0

package/dist/types/mixins/OxyServices.utility.d.ts

@@ -0,0 +1,393 @@
+import type { ApiError, User } from '../models/interfaces';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { type OxyServiceEnvironment } from '../utils/oxyServiceEnvironment';
+/**
+ * Result from the service-acting-as verification endpoint.
+ * Confirms that a given service app holds an active delegation grant for
+ * the supplied user, along with the explicit scope list the grant covers.
+ *
+ * The API side stores this as an ordinary `app_grants` row — the SAME revocable
+ * record the OAuth consent screen writes and the "Connected apps" UI lists and
+ * deletes — whose `scopes` name `acting-as:offline`. There is deliberately no
+ * separate delegation table: a second store would be a second revocation
+ * surface, and a user who disconnects an application in "Connected apps" means
+ * it, so one revoke has to end everything.
+ *
+ * `scopes` is what THAT USER consented to, not what the application may do in
+ * general. `requireScope` intersects it with the token's own app-wide scopes for
+ * a delegated request, and the intersection is the effective authority.
+ *
+ * The SDK never inspects the grant directly — it round-trips through
+ * `GET /internal/service-acting-as/verify?appId=...&userId=...` so the
+ * authoritative store stays server-side.
+ */
+export interface ServiceActingAsVerification {
+    authorized: boolean;
+    scopes: string[];
+}
+/**
+ * Service app metadata attached to requests authenticated with service tokens.
+ *
+ * Every field comes from the token's SIGNED payload and is populated only after
+ * the signature, `iss`/`aud`/`type` binding and expiry all pass — so a verifier
+ * holding this object can name the responsible principals without a lookup of
+ * its own. Together with `credentialId` and `ownerAccountId` it is the canonical
+ * attribution tuple of ADR 0007 minus the delegated user.
+ *
+ * `scopes` are the EFFECTIVE scopes: the credential's own scopes intersected
+ * with the owning application's grant at mint time (the API's `intersectScopes`
+ * is the single authority for that intersection — nothing re-intersects here).
+ * Route-level checks narrow further via `requireScope()`.
+ *
+ * A delegated end user is NOT a field of this type, and must never become one.
+ * It lives in `req.serviceActingAs` / `req.userId`, is authorised per request,
+ * and is attribution only.
+ */
+export interface ServiceApp {
+    appId: string;
+    appName: string;
+    scopes: string[];
+    /** The credentialId of the specific service credential that minted this token. */
+    credentialId: string;
+    /**
+     * The Oxy account that owns `appId` and is financially responsible for it.
+     * The BILLING principal — never a user id, and never the delegated
+     * `X-Oxy-User-Id` (ADR 0007).
+     */
+    ownerAccountId: string;
+    /** Test/live isolation (F2.0): which `ApplicationCredential.environment` minted this token. */
+    environment: OxyServiceEnvironment;
+}
+/**
+ * Options for oxyClient.auth() middleware
+ */
+interface AuthMiddlewareOptions {
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Custom error handler - receives error object, can return response */
+    onError?: (error: ApiError) => unknown;
+    /** Load full user profile from API (default: false for performance) */
+    loadUser?: boolean;
+    /** Optional auth - attach user if token present but don't block (default: false) */
+    optional?: boolean;
+    /**
+     * Public JWKS endpoint used for Ed25519 service-token verification. Defaults
+     * to `/.well-known/jwks.json` on this Oxy client's configured API origin.
+     */
+    serviceTokenJwksUrl?: string;
+    /**
+     * @deprecated Oxy-API-only transition for pre-cutover HS256 service tokens.
+     * External services omit this option and verify Ed25519 tokens through the
+     * public JWKS. Never distribute `ACCESS_TOKEN_SECRET`: a host holding it can
+     * mint user access tokens as well as verify legacy service tokens.
+     */
+    jwtSecret?: string;
+    /**
+     * Expected JWT issuer. Defaults to `'oxy-auth'`. Override only if you run
+     * a private fork of the Oxy auth server under a different `iss` claim.
+     */
+    expectedIssuer?: string;
+    /**
+     * Expected JWT audience. Defaults to `'oxy-api'`. Override only if your
+     * private fork mints tokens for a different audience.
+     */
+    expectedAudience?: string;
+}
+export declare function OxyServicesUtilityMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * In-memory cache for service-acting-as verification.
+         * Negative results are cached for 1min to avoid hammering the verify
+         * endpoint when a service is misconfigured; positive grants are cached
+         * for 5min to amortize the round-trip without holding stale grants too long.
+         * @internal
+         */
+        _serviceActingAsCache: Map<string, {
+            result: ServiceActingAsVerification | null;
+            expiresAt: number;
+        }>;
+        /** @internal Per-client public-key cache; never contains private material. */
+        _serviceTokenJwksCache: ServiceTokenJwksCache;
+        /**
+         * Verify that a service app holds an active delegation grant authorising
+         * it to act on behalf of `userId`. Returns the grant (with allowed scopes)
+         * on success or `null` if no valid grant exists. Negative answers are
+         * cached briefly to protect the verify endpoint from misconfigured callers.
+         *
+         * Implemented as a per-instance Map keyed by `appId:userId`. Cached
+         * positive grants live for 5 minutes (acceptable staleness window for an
+         * impersonation grant); revocations propagate within that window.
+         *
+         * @internal Used by the auth() middleware — not part of the public API
+         */
+        verifyServiceActingAs(appId: string, userId: string): Promise<ServiceActingAsVerification | null>;
+        /**
+         * Fetch link metadata
+         */
+        fetchLinkMetadata(url: string): Promise<{
+            url: string;
+            title: string;
+            description: string;
+            image?: string;
+        }>;
+        /**
+         * Express.js authentication middleware
+         *
+         * Validates JWT tokens against the Oxy API and attaches user data to requests.
+         * Uses server-side session validation for security (not just JWT decode).
+         *
+         * **Design note — jwtDecode vs jwt.verify:**
+         * This middleware uses `jwtDecode()` (decode-only, NO signature check) for
+         * user tokens, because third-party apps mounting `oxy.auth()` do not hold
+         * the Oxy signing secret. **Every claim in a user token is therefore
+         * attacker-controlled and proves nothing on its own.** The identity comes
+         * from somewhere else entirely:
+         * - A user token MUST carry a `sessionId`. That session is validated
+         *   server-side on every request via `validateSession()`, and the user id
+         *   is read off the VALIDATED SESSION — never off the token. A token whose
+         *   `userId` claim disagrees with the session is refused
+         *   (`SESSION_USER_MISMATCH`); a token with no `sessionId` at all is
+         *   refused outright (`SESSION_REQUIRED`). There is no local-claims path.
+         * - Service tokens (type: 'service') ARE stateless, so they use Ed25519
+         *   verification against Oxy's public JWKS and are additionally checked
+         *   for `aud`, `iss`, `type`, time, attribution and scope claims. The
+         *   `jwtSecret` path exists only for Oxy API's bounded HS256 transition.
+         * - The backend's own `authMiddleware` uses `jwt.verify()` because it has
+         *   direct access to `ACCESS_TOKEN_SECRET`.
+         *
+         * **Why session-less user tokens are refused rather than trusted:**
+         * every user access token the Oxy API issues carries a `sessionId` (see
+         * `packages/api/src/utils/sessionUtils.ts`, `generateSessionTokens` — the
+         * only mint site for user tokens, including the OAuth code exchange). So
+         * refusing session-less user tokens costs nothing legitimate, while
+         * accepting them let anyone authenticate as anyone by hand-rolling a JWT
+         * with a `userId` claim and a garbage signature.
+         *
+         * **Why the claimed user id is cross-checked against the session:**
+         * `GET /session/validate/:sessionId` is UNAUTHENTICATED and does not bind
+         * the bearer token — it returns whoever owns the session id it was handed.
+         * Trusting the token's `userId` claim after a successful validation would
+         * therefore let a caller holding ANY live session id (their own, for
+         * instance) pair it with a forged `userId` and be trusted as that user.
+         * `authSocket()` has always cross-checked this; the HTTP middleware now
+         * does too.
+         *
+         * **Service-token delegation (X-Oxy-User-Id):**
+         * When a service token is accompanied by `X-Oxy-User-Id`, the SDK calls
+         * `verifyServiceActingAs(appId, userId)` to confirm an explicit delegation
+         * grant exists before attaching `req.userId`. A missing/expired grant
+         * results in a 403 — there is no fail-open path.
+         *
+         * @example
+         * ```typescript
+         * import { OxyServices } from '@oxy.so/core';
+         *
+         * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+         *
+         * // Protect all routes under /protected
+         * app.use('/protected', oxy.auth());
+         *
+         * // Access user in route handler
+         * app.get('/protected/me', (req, res) => {
+         *   res.json({ userId: req.userId, user: req.user });
+         * });
+         *
+         * // Load full user profile from API
+         * app.use('/admin', oxy.auth({ loadUser: true }));
+         *
+         * // Optional auth - attach user if present, don't block if absent
+         * app.use('/public', oxy.auth({ optional: true }));
+         *
+         * // Require a specific scope on a service-token-protected route
+         * app.use('/internal/files', oxy.serviceAuth(), oxy.requireScope('files:write'));
+         * ```
+         *
+         * @param options Optional configuration
+         * @returns Express middleware function
+         */
+        auth(options?: AuthMiddlewareOptions): (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<unknown>;
+        /**
+         * Socket.IO authentication middleware factory
+         *
+         * Returns a middleware function for Socket.IO that validates JWT tokens
+         * from the handshake auth object and attaches user data to the socket.
+         *
+         * Uses `jwtDecode()` + API session validation (same rationale as `auth()`).
+         *
+         * @example
+         * ```typescript
+         * import { OxyServices } from '@oxy.so/core';
+         * import { Server } from 'socket.io';
+         *
+         * const oxy = new OxyServices({ baseURL: 'https://api.oxy.so' });
+         * const io = new Server(server);
+         *
+         * // Authenticate all socket connections
+         * io.use(oxy.authSocket());
+         *
+         * io.on('connection', (socket) => {
+         *   console.log('Authenticated user:', socket.data.userId);
+         * });
+         * ```
+         */
+        authSocket(options?: {
+            debug?: boolean;
+        }): (socket: SocketLike, next: (err?: Error) => void) => Promise<void>;
+        /**
+         * Express.js middleware that only allows service tokens.
+         * Use this for internal-only endpoints that should not be accessible
+         * to regular users or API key consumers.
+         *
+         * @example
+         * ```typescript
+         * // Protect internal endpoints
+         * app.use('/internal', oxy.serviceAuth());
+         *
+         * app.post('/internal/trigger', (req, res) => {
+         *   console.log('Service app:', req.serviceApp);
+         *   console.log('Acting on behalf of user:', req.userId);
+         * });
+         * ```
+         */
+        serviceAuth(options?: {
+            debug?: boolean;
+            /** @deprecated Oxy-API-only HS256 transition; external verifiers use JWKS. */
+            jwtSecret?: string;
+            serviceTokenJwksUrl?: string;
+            expectedIssuer?: string;
+            expectedAudience?: string;
+        }): (req: AuthReq, res: AuthRes, next: AuthNext) => Promise<void>;
+        /**
+         * Express.js middleware that enforces a specific service-token scope.
+         *
+         * Mount AFTER `auth()` / `serviceAuth()` — relies on `req.serviceApp` and
+         * (when delegation is in effect) `req.serviceActingAs.scopes`. App-only
+         * service requests require the app scope. Delegated user requests require
+         * BOTH the app scope and the per-user delegation scope.
+         *
+         * The intersection is the point, not a redundancy, because the two scope
+         * lists answer different questions and neither implies the other:
+         *
+         *   `serviceApp.scopes`      what the PLATFORM allows this application to do
+         *                            (credential ∩ application ceiling, at mint time)
+         *   `serviceActingAs.scopes` what THIS USER allowed it to do (`app_grants`)
+         *
+         * Requiring only the app scope would let an application do to a user
+         * something that user never consented to; requiring only the grant would let
+         * a user hand an application authority staff never gave it, so a revoked
+         * platform scope would keep working for every user who had already
+         * consented. Effective authority is the intersection, and this is where it
+         * is taken.
+         *
+         * Requests authenticated as a regular user (no service token) are rejected
+         * with 403 — scope-protected endpoints are service-to-service by design.
+         *
+         * @example
+         * ```typescript
+         * app.use(
+         *   '/internal/files',
+         *   oxy.serviceAuth(),
+         *   oxy.requireScope('files:write'),
+         * );
+         * ```
+         */
+        requireScope(scope: string): (req: AuthReq, res: AuthRes, next: AuthNext) => void;
+        httpService: import("../HttpService").HttpService;
+        cloudURL: string;
+        config: import("../OxyServices.base").OxyConfig;
+        __resetTokensForTests(): void;
+        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
+        getBaseURL(): string;
+        getClient(): import("../HttpService").HttpService;
+        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
+        getMetrics(): {
+            totalRequests: number;
+            successfulRequests: number;
+            failedRequests: number;
+            cacheHits: number;
+            cacheMisses: number;
+            averageResponseTime: number;
+        };
+        clearCache(): void;
+        clearCacheEntry(key: string): void;
+        clearCacheByPrefix(prefix: string): number;
+        getCacheStats(): {
+            size: number;
+            hits: number;
+            misses: number;
+            hitRate: number;
+        };
+        getCloudURL(): string;
+        setTokens(accessToken: string): void;
+        clearTokens(): void;
+        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
+        _cachedUserId: string | null | undefined;
+        _cachedAccessToken: string | null;
+        getCurrentUserId(): string | null;
+        hasValidToken(): boolean;
+        getAccessToken(): string | null;
+        getAccessTokenExpiry(): number | null;
+        waitForAuth(timeoutMs?: number): Promise<boolean>;
+        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
+            maxRetries?: number;
+            retryDelay?: number;
+            authTimeoutMs?: number;
+        }): Promise<T_1>;
+        validate(): Promise<boolean>;
+        handleError(error: unknown): Error;
+        healthCheck(): Promise<{
+            status: string;
+            users?: number;
+            timestamp?: string;
+            [key: string]: any;
+        }>;
+    };
+} & T;
+interface ServiceTokenPublicJwk {
+    readonly kty: 'OKP';
+    readonly crv: 'Ed25519';
+    readonly x: string;
+    readonly use: 'sig';
+    readonly alg: 'EdDSA';
+    readonly kid: string;
+}
+interface ServiceTokenJwksCache {
+    keys: Map<string, ServiceTokenPublicJwk>;
+    expiresAt: number;
+    lastAttemptAt: number;
+    pending?: Promise<void>;
+}
+interface AuthReq {
+    method?: string;
+    path?: string;
+    headers: Record<string, string | string[] | undefined>;
+    query?: Record<string, unknown>;
+    userId?: string | null;
+    user?: User | null;
+    accessToken?: string;
+    sessionId?: string | null;
+    serviceApp?: ServiceApp;
+    serviceActingAs?: {
+        userId: string;
+        scopes: string[];
+    };
+}
+interface AuthRes {
+    status(code: number): AuthRes;
+    json(body: unknown): unknown;
+}
+type AuthNext = (err?: unknown) => void;
+interface SocketLike {
+    handshake?: {
+        auth?: {
+            token?: string;
+        };
+    };
+    data?: Record<string, unknown>;
+    user?: {
+        id: string;
+        userId: string;
+        sessionId?: string | null;
+    };
+}
+export {};

package/dist/types/mixins/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Centralized mixin exports and composition helper
+ *
+ * This module provides a clean way to compose all mixins
+ * and ensures consistent ordering for better maintainability
+ */
+import { OxyServicesBase } from '../OxyServices.base';
+import { OxyServicesAuthMixin } from './OxyServices.auth';
+import { OxyServicesUserMixin } from './OxyServices.user';
+import { OxyServicesIdentityMixin } from './OxyServices.identity';
+import { OxyServicesIdentityBackupMixin } from './OxyServices.identityBackup';
+import { OxyServicesPrivacyMixin } from './OxyServices.privacy';
+import { OxyServicesLanguageMixin } from './OxyServices.language';
+import { OxyServicesPaymentMixin } from './OxyServices.payment';
+import { OxyServicesReputationMixin } from './OxyServices.reputation';
+import { OxyServicesAssetsMixin } from './OxyServices.assets';
+import { OxyServicesAccountsMixin } from './OxyServices.accounts';
+import { OxyServicesConnectedAppsMixin } from './OxyServices.connectedApps';
+import { OxyServicesStoreMixin } from './OxyServices.store';
+import { OxyServicesLocationMixin } from './OxyServices.location';
+import { OxyServicesAnalyticsMixin } from './OxyServices.analytics';
+import { OxyServicesDevicesMixin } from './OxyServices.devices';
+import { OxyServicesSecurityMixin } from './OxyServices.security';
+import { OxyServicesUtilityMixin } from './OxyServices.utility';
+import { OxyServicesFeaturesMixin } from './OxyServices.features';
+import { OxyServicesTopicsMixin } from './OxyServices.topics';
+import { OxyServicesContactsMixin } from './OxyServices.contacts';
+import { OxyServicesNotificationsMixin } from './OxyServices.notifications';
+import { OxyServicesAppDataMixin } from './OxyServices.appData';
+import { OxyServicesCivicMixin } from './OxyServices.civic';
+import { OxyServicesChainsMixin } from './OxyServices.chains';
+import { OxyServicesNodesMixin } from './OxyServices.nodes';
+import { OxyServicesLinksMixin } from './OxyServices.links';
+import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
+import { OxyServicesInferenceMixin } from './OxyServices.inference';
+import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
+/**
+ * Instance shape of every mixin in the pipeline, intersected. The runtime
+ * `composeOxyServices()` produces a class whose instances expose all of
+ * these methods; we surface that to TypeScript via this intersection so the
+ * `extends` site in `OxyServices.ts` can avoid an `as any` cast.
+ *
+ * If you add a new mixin to `MIXIN_PIPELINE`, add it here too so its methods
+ * are visible without a cast.
+ */
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityBackupMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPrivacyMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLanguageMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesPaymentMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesReputationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAssetsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesConnectedAppsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesStoreMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLocationMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAnalyticsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDevicesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSecurityMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFeaturesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesTopicsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNotificationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesChainsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesInferenceMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+/**
+ * Constructor type for the fully composed mixin pipeline. Each mixin returns
+ * a new constructor that augments its input; reducing across the pipeline
+ * yields an instance with every mixin's methods.
+ */
+export type ComposedOxyServicesConstructor = new (config: import('../OxyServices.base').OxyConfig) => AllMixinInstances;
+/**
+ * A mixin function: takes a constructor and returns an augmented constructor.
+ * Each individual mixin uses a `<T extends typeof OxyServicesBase>` generic
+ * to preserve its specific augmentations, but those refinements are
+ * intentionally collapsed across the `reduce` call below.
+ */
+type MixinFunction = (Base: new (...args: unknown[]) => OxyServicesBase) => new (...args: unknown[]) => OxyServicesBase;
+/**
+ * Mixin pipeline - applied in order from first to last.
+ *
+ * Order matters for dependencies:
+ * 1. Base auth mixin first (required by all others)
+ * 2. User mixin (requires auth)
+ * 3. Feature mixins (can depend on user)
+ * 4. Utility mixin last (augments all)
+ *
+ * To add a new mixin: insert it at the appropriate position in this array.
+ */
+declare const MIXIN_PIPELINE: MixinFunction[];
+/**
+ * Composes all OxyServices mixins using a pipeline pattern.
+ *
+ * This is equivalent to the nested calls but more readable and maintainable.
+ * Adding a new mixin: add it to MIXIN_PIPELINE at the appropriate position
+ * AND extend `AllMixinInstances` so its methods are visible to consumers.
+ *
+ * The cast through `unknown` carries the runtime augmentation chain into the
+ * static type system. `Array.reduce` cannot track each mixin's generic
+ * refinement, so we assert the final shape exposed by all mixins together.
+ *
+ * @returns The fully composed OxyServices constructor with all mixins applied
+ */
+export declare function composeOxyServices(): ComposedOxyServicesConstructor;
+export { MIXIN_PIPELINE };

package/dist/types/mixins/mixinHelpers.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Helper utilities for mixin classes
+ * Provides common patterns to reduce code duplication
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+/**
+ * Wraps an async method with standard error handling
+ * Reduces boilerplate in mixin methods
+ */
+export declare function withErrorHandling<T>(operation: () => Promise<T>, handleError: (error: any) => Error): Promise<T>;
+/**
+ * Creates a standard API request method with error handling
+ * Reduces duplication across mixin methods
+ */
+export declare function createApiMethod<T>(makeRequest: OxyServicesBase['makeRequest'], handleError: OxyServicesBase['handleError'], method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', url: string | ((...args: any[]) => string), options?: {
+    cache?: boolean;
+    cacheTTL?: number;
+    retry?: boolean;
+    transformData?: (data: any) => any;
+    transformResponse?: (response: any) => T;
+}): (...args: any[]) => Promise<T>;
+/**
+ * Cache time constants (in milliseconds)
+ */
+export declare const CACHE_TIMES: {
+    readonly SHORT: number;
+    readonly MEDIUM: number;
+    readonly LONG: number;
+    readonly VERY_LONG: number;
+    readonly EXTRA_LONG: number;
+};

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

@@ -0,0 +1,42 @@
+export declare enum TopicType {
+    CATEGORY = "category",
+    TOPIC = "topic",
+    ENTITY = "entity"
+}
+export declare enum TopicSource {
+    SEED = "seed",
+    AI = "ai",
+    MANUAL = "manual",
+    SYSTEM = "system"
+}
+export interface TopicTranslation {
+    displayName: string;
+    description?: string;
+}
+export interface TopicData {
+    _id: string;
+    name: string;
+    slug: string;
+    displayName: string;
+    description: string;
+    type: TopicType;
+    source: TopicSource;
+    aliases: string[];
+    parentTopicId?: string;
+    icon?: string;
+    image?: string;
+    isActive: boolean;
+    translations?: Record<string, TopicTranslation>;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Paginated result of {@link OxyServices.listTopics}. Mirrors the `GET /topics`
+ * envelope so callers keep access to `total`/`offset` for pagination.
+ */
+export interface TopicListResult {
+    topics: TopicData[];
+    total: number;
+    limit: number;
+    offset: number;
+}