@oxy.so/core 1.18.0 → 3.0.0

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

@@ -1,371 +0,0 @@
-import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant, BatchFileAccessResponse, ServiceAssetMetadata, ServiceAssetMetadataBySha, ServiceLinkedDownloadUrl } 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[]>;
-        /**
-         * Mint short-lived direct download URLs for files the calling application's
-         * own users attached to it, via `POST /assets/service/linked-url`.
-         *
-         * This is the ONLY path in this SDK by which a service token reaches file
-         * BYTES. {@link getServiceAssetMetadataByIds} is metadata-only, and every
-         * other download helper here — {@link getFileDownloadUrl},
-         * {@link getFileDownloadUrlAsync}, {@link getBatchFileAccess} — resolves a URL
-         * for the CURRENT USER through `makeRequest`, which is a different question: a
-         * relying service holds no user session, and the buyer whose entitlement it is
-         * enforcing is not a viewer Oxy knows anything about.
-         *
-         * **Service-token auth (required), plus the `files:linked:read` scope**, which
-         * is NOT implied by `files:read`. The calling client must be service-configured
-         * (`configureServiceAuth(apiKey, apiSecret)`); a user-session request is
-         * rejected by the route's service-auth guard.
-         *
-         * **What the server will and will not give you.** A URL comes back only for a
-         * file whose OWN OWNER linked it to this application (`file_links.created_by =
-         * files.owner_user_id`). Every other id is omitted: unknown, deleted,
-         * system-owned, linked by somebody else, or not linked here at all. So the
-         * result is routinely shorter than the input and must be mapped by `id`.
-         *
-         * ABSENCE IS A REFUSAL, NOT A FACT ABOUT THE FILE, and the caller is the only
-         * party that can tell the difference. The route deliberately cannot — it
-         * answers identically for "no such file" and "not yours" so it leaks nothing —
-         * which means a service must decide what to tell its user from its OWN
-         * entitlement record, never from this response. Do not surface "file not
-         * found" on the strength of an omission.
-         *
-         * FAILURE IS NOT ABSENCE EITHER, and here it cannot be opted out of: a failed
-         * chunk throws {@link ServiceLinkedDownloadUrlError} carrying its ids, with no
-         * `{ partial: true }` mode. Swallowing a 429 would tell a user who paid for a
-         * file that it is not there. An empty input resolves to `[]` with no network
-         * call.
-         *
-         * Never cached at the SDK layer, and that is a stronger statement than the
-         * sibling methods' "low hit rate": each entry is a live credential for the
-         * bytes, so caching one keeps it usable after the service has decided the
-         * caller's entitlement ended.
-         */
-        getServiceLinkedDownloadUrls(ids: string[]): Promise<ServiceLinkedDownloadUrl[]>;
-        /**
-         * 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;