@oxy.so/core 1.0.0

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

@@ -0,0 +1,72 @@
+/**
+ * Analytics Methods Mixin
+ *
+ * Provides methods for analytics tracking and data retrieval
+ */
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesAnalyticsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Track an analytics event
+         * @param eventName - Name of the event to track
+         * @param properties - Optional event properties
+         */
+        trackEvent(eventName: string, properties?: Record<string, any>): Promise<void>;
+        /**
+         * Get analytics data for a date range
+         * @param startDate - Optional start date (ISO string)
+         * @param endDate - Optional end date (ISO string)
+         * @returns Analytics data
+         */
+        getAnalytics(startDate?: string, endDate?: string): Promise<any>;
+        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;

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

@@ -0,0 +1,108 @@
+/**
+ * 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';
+/** Thrown when a namespace or key fails the kebab/snake-case validator. */
+export declare class OxyAppDataIdentifierError extends Error {
+    constructor(field: 'namespace' | 'key', value: string);
+}
+export declare function OxyServicesAppDataMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: 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.
+         */
+        getAppData<TValue = unknown>(namespace: string, key: string): Promise<TValue | null>;
+        /**
+         * 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.
+         */
+        setAppData<TValue = unknown>(namespace: string, key: string, value: TValue): Promise<TValue>;
+        /**
+         * Delete the value stored under `(namespace, key)` for the current user.
+         *
+         * Idempotent — resolves successfully whether or not the entry existed.
+         */
+        deleteAppData(namespace: string, key: string): Promise<void>;
+        /**
+         * 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).
+         */
+        listAppData<TValue = unknown>(namespace: string): Promise<Record<string, TValue>>;
+        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;

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

@@ -0,0 +1,329 @@
+import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha } from '../models/interfaces';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Service-token request, implemented by the auth mixin earlier in the
+         * composition pipeline (see `mixins/index.ts`). The assets mixin is typed
+         * against `OxyServicesBase`, which does not carry the auth mixin's methods,
+         * so this `declare` surfaces the inherited runtime method to TypeScript
+         * without re-implementing it. Used by
+         * {@link getServiceAssetMetadataByIds} to authenticate the server-to-server
+         * `/assets/service/by-ids` bulk fetch with a bearer service token.
+         */
+        makeServiceRequest: <R = unknown>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: unknown, userId?: string) => Promise<R>;
+        /**
+         * Delete file
+         */
+        deleteFile(fileId: string): Promise<any>;
+        /**
+         * Build a synchronous, `<img src>`-ready URL for a **PUBLIC** Oxy asset.
+         *
+         * ## Contract — read before calling
+         *
+         * This is a pure string builder. It performs no network call and therefore
+         * has **no knowledge of the asset's visibility**. It always produces the
+         * public form: `${cloudURL}/<id>[?variant=…]`, which the CDN serves from
+         * the public media origin only.
+         *
+         * Consequently:
+         *  - Call it ONLY when the asset is known to be `public` — e.g. avatars and
+         *    profile banners, which {@link uploadAvatar} / {@link uploadProfileBanner}
+         *    upload with `visibility: 'public'`.
+         *  - For an asset that may be `private` or `unlisted` — anything uploaded
+         *    through the generic {@link assetUpload} path, whose server-side default
+         *    is private — this URL resolves to a hard **404**. Use
+         *    {@link getFileDownloadUrlAsync}, which asks the API for a URL scoped to
+         *    the current caller.
+         *  - It must never guess visibility, and must never embed the caller's
+         *    bearer token: the returned string is rendered into DOM attributes,
+         *    browser network panels, HTTP caches, and logs.
+         *
+         * Passing `expiresIn` switches to the API-origin stream form
+         * (`${baseURL}/assets/<id>/stream?…`) WITHOUT any credential. That form
+         * still only serves what an unauthenticated request may see — it is not a
+         * synchronous private-asset path, and none exists: authorization for a
+         * private asset requires the round-trip in {@link getFileDownloadUrlAsync}.
+         */
+        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string;
+        /**
+         * Resolve an asset id to a URL that is valid for the CURRENT caller,
+         * whatever the asset's visibility.
+         *
+         * Asks the API (`GET /assets/:id/url`) rather than guessing: a `public`
+         * asset resolves to the CDN form, while a `private`/`unlisted` asset the
+         * caller may read resolves to an API-origin stream URL carrying a scoped,
+         * short-lived media token. The returned URL is passed through **unchanged**
+         * — the SDK never rewrites, re-signs, or strips it.
+         *
+         * ## Failure behaviour — no CDN fallback
+         *
+         * Throws {@link AssetUrlResolutionError} when the API returns no URL or the
+         * request fails (including 401/403/404). It deliberately does NOT fall back
+         * to {@link getFileDownloadUrl}: that builder only produces the public CDN
+         * form, so falling back would hand the caller a URL that renders as a hard
+         * 404 for every private asset and would silently swallow the real failure.
+         * A caller that knows an asset is public should call the synchronous
+         * builder directly instead of relying on a fallback here.
+         *
+         * The resolved URL is cached per identity for well under the media token's
+         * lifetime — see {@link getAssetUrlCacheTTL}.
+         */
+        getFileDownloadUrlAsync(fileId: string, variant?: string, expiresIn?: number): Promise<string>;
+        /**
+         * List user files
+         */
+        listUserFiles(limit?: number, offset?: number): Promise<{
+            files: any[];
+            total: number;
+            hasMore: boolean;
+        }>;
+        /**
+         * Get account storage usage (server-side usage aggregated from assets)
+         */
+        getAccountStorageUsage(): Promise<AccountStorageUsageResponse>;
+        /**
+         * Get file content as text
+         */
+        getFileContentAsText(fileId: string, variant?: string): Promise<string>;
+        /**
+         * Get file content as blob
+         */
+        getFileContentAsBlob(fileId: string, variant?: string): Promise<Blob>;
+        /**
+         * Resolve access + a caller-scoped URL for many assets — each with its OWN
+         * requested variant — in ONE round trip via `POST /assets/batch-access`.
+         *
+         * `requests` is a per-file `{ fileId, variant? }` list (a `variant` of
+         * `undefined` asks for the original). `options.expiresIn` sets the requested
+         * media-token / signed-URL lifetime (seconds); `options.context` is the
+         * server-side access-check context. Entries with a blank `fileId` are
+         * dropped and exact `(fileId, variant)` duplicates are collapsed before the
+         * request; an empty effective list performs no network call.
+         *
+         * The server caps the batch at 100 entries — callers that page beyond that
+         * must chunk. Returns the raw per-file envelope (see
+         * {@link BatchFileAccessResponse}); most callers want {@link getFileDownloadUrls},
+         * which flattens it to just the usable URLs.
+         */
+        getBatchFileAccess(requests: Array<{
+            fileId: string;
+            variant?: string;
+        }>, options?: {
+            expiresIn?: number;
+            context?: string;
+        }): Promise<BatchFileAccessResponse>;
+        /**
+         * Resolve many assets — each with its OWN variant — to caller-scoped,
+         * `<img src>`-ready URLs in one round trip. The batch counterpart of
+         * {@link getFileDownloadUrlAsync}, built to resolve a whole grid page at once.
+         *
+         * `requests` is a per-file `{ fileId, variant? }` list (e.g. `poster` for a
+         * video, `thumb` for an image); the per-file variant RULE lives in the
+         * caller — core just forwards what it is given. `options.expiresIn` /
+         * `options.context` are passed through to the endpoint.
+         *
+         * Each returned URL is the API's own scoped form, passed through unchanged:
+         * the public CDN URL for a public asset, or an API-origin
+         * `/assets/:id/stream?…&mt=<media token>` URL for a private asset the caller
+         * may read. Ids the caller cannot access (or that do not exist) are simply
+         * OMITTED from the returned map — there is NO public-CDN fallback, so a grid
+         * never renders a known-404 URL. Callers detect a miss by the absent key
+         * (the map never contains an empty-string value). Keyed by `fileId`.
+         */
+        getFileDownloadUrls(requests: Array<{
+            fileId: string;
+            variant?: string;
+        }>, options?: {
+            expiresIn?: number;
+            context?: string;
+        }): Promise<Record<string, string>>;
+        /**
+         * Resolve many Oxy asset ids to their content-addressed metadata in one
+         * round-trip per chunk via `POST /assets/service/by-ids` (body `{ ids }`).
+         *
+         * Returns each asset's `sha256`, `mime`, byte `size`, and `status` — built
+         * for server-to-server callers (e.g. Mention's MTN Protocol blob-ref
+         * resolution) that need the content hash for an asset id. Ids are
+         * deduplicated and validated (empty/blank ids dropped) before being split
+         * into chunks of {@link SERVICE_ASSET_METADATA_CHUNK_SIZE} (the server-side
+         * cap). The server omits unknown/deleted ids from each chunk's `data`, so
+         * the merged result may be shorter than the requested id list and the caller
+         * is expected to map by `id`.
+         *
+         * **Service-token auth (required).** `/assets/service/by-ids` is guarded by
+         * `serviceAuthMiddleware` + the `files:read` scope and is called via
+         * `makeServiceRequest`, which attaches `Authorization: Bearer <serviceToken>`
+         * (the same client that calls `POST /assets/service/cache`). The calling
+         * client MUST be service-configured (`configureServiceAuth(apiKey,
+         * apiSecret)`) before invoking this method; otherwise `getServiceToken()`
+         * throws because no credentials are available. A plain user-session request
+         * is rejected by the route's service-auth guard.
+         *
+         * FAILURE IS NOT ABSENCE. The server legitimately omits unknown/deleted ids,
+         * so a short result is normal — which means a chunk that FAILED (a 429, a
+         * timeout, a 5xx) is indistinguishable from "those assets don't exist" if it
+         * simply contributes nothing. This method used to swallow a failed chunk and
+         * return the rest, so every caller silently read a throttled request as "no
+         * metadata": a backfill counted the asset as needing no update, and the
+         * signed-record builder embedded a media item with no hash. Both reported
+         * success while writing nothing, and the MTN chain's records are immutable.
+         *
+         * So a failed chunk THROWS {@link ServiceAssetMetadataError} by default,
+         * carrying the ids it could not resolve. A caller that genuinely wants
+         * best-effort opts in with `{ partial: true }` and gets the old behaviour
+         * explicitly. An empty/whitespace-only input resolves immediately with `[]`
+         * and performs no network call.
+         *
+         * Not cached at the SDK layer: it's a POST keyed on a multi-id body (low hit
+         * rate), mirroring the sibling service/POST methods which never cache.
+         */
+        getServiceAssetMetadataByIds(ids: string[], options?: {
+            partial?: boolean;
+        }): Promise<ServiceAssetMetadata[]>;
+        /**
+         * Reverse content-address lookup: resolve many content `sha256` digests to
+         * the servable Oxy asset holding each, in one round-trip per chunk via
+         * `POST /assets/service/by-sha256` (body `{ sha256s }`).
+         *
+         * This is the INVERSE of {@link getServiceAssetMetadataByIds}: given a
+         * record's `blob.sha256`, it returns the asset's `id`, `mime`, byte `size`,
+         * `status`, and — for active, public, CDN-reachable assets only — a public
+         * `url` (`cloud.oxy.so`). Built for server-to-server callers (e.g. Mention's
+         * MTN materializer / node-blob sync) that hold a content hash and need to
+         * map it back to a servable asset. Hashes are lowercased, validated against
+         * a 64-char hex pattern (malformed entries dropped client-side), and
+         * deduplicated before being split into chunks of
+         * {@link SERVICE_ASSET_METADATA_BY_SHA_CHUNK_SIZE} (the server-side cap). The
+         * server omits unknown/deleted hashes from each chunk's `data`, so the
+         * merged result may be shorter than the requested list and the caller is
+         * expected to map by `sha256`.
+         *
+         * **Service-token auth (required).** `/assets/service/by-sha256` is guarded
+         * by `serviceAuthMiddleware` + the `files:read` scope and is called via
+         * `makeServiceRequest` (`Authorization: Bearer <serviceToken>`, `cache:false`).
+         * The calling client MUST be service-configured (`configureServiceAuth`)
+         * before invoking; a plain user-session request is rejected by the route's
+         * service-auth guard.
+         *
+         * Resilience: chunks are independent. A failed chunk is logged and skipped —
+         * every entry that resolved is still returned. An empty input (or one whose
+         * every value is malformed) resolves immediately with `[]` and performs no
+         * network call.
+         *
+         * Not cached at the SDK layer: it's a POST keyed on a multi-hash body (low
+         * hit rate), mirroring the sibling service/POST methods which never cache.
+         */
+        getServiceAssetMetadataBySha256(sha256s: string[]): Promise<ServiceAssetMetadataBySha[]>;
+        /**
+         * Upload raw file data
+         */
+        uploadRawFile(file: AssetUploadInput, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>): Promise<any>;
+        /**
+         * Upload file using Central Asset Service.
+         *
+         * Accepts either a web File/Blob or a React Native file descriptor
+         * ({uri, type, name, size}). RN descriptors are passed directly to
+         * FormData.append, which handles them natively.
+         */
+        assetUpload(file: AssetUploadInput, visibility?: "private" | "public" | "unlisted", metadata?: Record<string, any>, onProgress?: (progress: number) => void): Promise<any>;
+        /**
+         * Link asset to an entity
+         */
+        assetLink(fileId: string, app: string, entityType: string, entityId: string, visibility?: "private" | "public" | "unlisted", webhookUrl?: string): Promise<any>;
+        /**
+         * Unlink asset from an entity
+         */
+        assetUnlink(fileId: string, app: string, entityType: string, entityId: string): Promise<any>;
+        /**
+         * Get asset metadata
+         */
+        assetGet(fileId: string): Promise<any>;
+        /**
+         * Get asset URL (CDN or signed URL)
+         */
+        assetGetUrl(fileId: string, variant?: string, expiresIn?: number): Promise<AssetUrlResponse>;
+        /**
+         * Restore asset from trash
+         */
+        assetRestore(fileId: string): Promise<any>;
+        /**
+         * Delete asset with optional force
+         */
+        assetDelete(fileId: string, force?: boolean): Promise<any>;
+        /**
+         * Get list of available variants for an asset
+         */
+        assetGetVariants(fileId: string): Promise<AssetVariant[]>;
+        /**
+         * Update asset visibility
+         */
+        assetUpdateVisibility(fileId: string, visibility: "private" | "public" | "unlisted"): Promise<any>;
+        uploadAvatar(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
+        uploadProfileBanner(file: AssetUploadInput, userId: string, app?: string): Promise<any>;
+        /**
+         * How long a resolved asset URL may stay in the SDK's GET cache, in ms.
+         *
+         * A resolved private-asset URL dies the instant its scoped media token
+         * expires (~{@link ASSET_MEDIA_TOKEN_TTL_MS}). Caching it for its full
+         * nominal lifetime would leave a window where the cache serves an
+         * already-dead URL (clock skew, render-pipeline latency, an image request
+         * queued behind others). So the TTL is (a) never longer than the token's
+         * lifetime and (b) discounted to {@link ASSET_URL_CACHE_LIFETIME_FRACTION}
+         * of that bound — comfortably below the token TTL by construction.
+         */
+        getAssetUrlCacheTTL(expiresIn?: number): number;
+        fetchAssetDownloadUrl(fileId: string, variant?: string, cacheTTL?: number, expiresIn?: number): Promise<string | null>;
+        fetchAssetContent(url: string, type: "text"): Promise<string>;
+        fetchAssetContent(url: string, type: "blob"): Promise<Blob>;
+        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;