@oxy.so/core 1.18.1 → 3.0.0

package/dist/esm/api/apps.js

@@ -0,0 +1,191 @@
+const SHORT_TTL = 60 * 1000;
+const MEDIUM_TTL = 2 * 60 * 1000;
+const LONG_TTL = 5 * 60 * 1000;
+const enc = encodeURIComponent;
+/** `oxy.apps.credentials` — an application's OAuth client credentials. */
+export class AppCredentialsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * List an application's OAuth credentials. The response NEVER includes
+     * secrets.
+     * @param applicationId - The application's `_id`.
+     */
+    async list(applicationId) {
+        const res = await this.ctx.request('GET', credentialsPath(applicationId), undefined, { cache: true, cacheTTL: MEDIUM_TTL });
+        return res.credentials ?? [];
+    }
+    /**
+     * Create an application credential. The plaintext `secret` is returned
+     * exactly ONCE; the server stores only a hash and will never return it again.
+     * @param applicationId - The application's `_id`.
+     * @param data - Credential configuration.
+     */
+    async create(applicationId, data) {
+        const result = await this.ctx.request('POST', credentialsPath(applicationId), data, {
+            cache: false,
+        });
+        this.ctx.oxy.cache.delete(`GET:${credentialsPath(applicationId)}`);
+        return result;
+    }
+    /**
+     * Rotate an application credential's secret. The new plaintext `secret` is
+     * returned exactly ONCE, along with audit fields: `rotatedFrom` (the previous
+     * credentialId) and `graceExpiresAt` (the end of the window during which the
+     * old credential is still honoured).
+     * @param applicationId - The application's `_id`.
+     * @param credentialId - The credential's `_id`.
+     * @param options - `graceSeconds` keeps a superseded `machine` token working
+     *   for that long. Omitted, the previous token dies the moment the
+     *   replacement is minted.
+     */
+    async rotate(applicationId, credentialId, options) {
+        const result = await this.ctx.request('POST', `${credentialsPath(applicationId)}/${enc(credentialId)}/rotate`, options, { cache: false });
+        this.ctx.oxy.cache.delete(`GET:${credentialsPath(applicationId)}`);
+        return result;
+    }
+    /**
+     * Revoke an application credential (`status='revoked'`). Revoked credentials
+     * can no longer authenticate.
+     * @param applicationId - The application's `_id`.
+     * @param credentialId - The credential's `_id`.
+     */
+    async revoke(applicationId, credentialId) {
+        const result = await this.ctx.request('DELETE', `${credentialsPath(applicationId)}/${enc(credentialId)}`, undefined, { cache: false });
+        this.ctx.oxy.cache.delete(`GET:${credentialsPath(applicationId)}`);
+        return result;
+    }
+}
+/** `oxy.apps.connected` — third-party apps (and MCP clients) this user authorized. */
+export class ConnectedAppsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * The applications this user granted access to through the consent flow,
+     * with the granted scopes and when the grant was first made and last used.
+     * `GET /auth/grants`, briefly cached; `revoke` busts it.
+     */
+    async list() {
+        return this.ctx.request('GET', '/auth/grants', undefined, { cache: true, cacheTTL: SHORT_TTL });
+    }
+    /**
+     * Revoke this user's grant for a connected application. After this the
+     * application can no longer act on the user's behalf until re-authorized.
+     * @param applicationId - The connected application's `_id` (a
+     *   `ConnectedApp.applicationId`, NOT a credential/client id).
+     */
+    async revoke(applicationId) {
+        await this.ctx.request('DELETE', `/auth/grants/${applicationId}`, undefined, { cache: false });
+        this.ctx.oxy.cache.delete('GET:/auth/grants');
+    }
+    /** Resource-bound external MCP connections for the active Oxy account. */
+    async mcpClients() {
+        const res = await this.ctx.request('GET', '/auth/mcp/oauth/grants', undefined, {
+            cache: true,
+            cacheTTL: SHORT_TTL,
+        });
+        return res.grants;
+    }
+    /** Revoke one external MCP connection and every token in its family. */
+    async revokeMcpClient(grantId) {
+        await this.ctx.request('DELETE', `/auth/mcp/oauth/grants/${enc(grantId)}`, undefined, { cache: false });
+        this.ctx.oxy.cache.delete('GET:/auth/mcp/oauth/grants');
+    }
+}
+export class AppsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.credentials = new AppCredentialsApi(ctx);
+        this.connected = new ConnectedAppsApi(ctx);
+    }
+    /**
+     * The applications an account owns. `GET /applications?ownerAccountId=<id>`.
+     * @param accountId - The owning account's `_id`.
+     */
+    async list(accountId) {
+        const res = await this.ctx.request('GET', `/applications?ownerAccountId=${enc(accountId)}`, undefined, { cache: true, cacheTTL: MEDIUM_TTL });
+        return res.applications ?? [];
+    }
+    /**
+     * Fetch a single application by id.
+     * @param applicationId - The application's `_id`.
+     */
+    async get(applicationId) {
+        const res = await this.ctx.request('GET', appPath(applicationId), undefined, {
+            cache: true,
+            cacheTTL: LONG_TTL,
+        });
+        return res.application;
+    }
+    /**
+     * Create an application owned by an account.
+     * @param data - Application configuration. `ownerAccountId` defaults to the
+     *   caller's personal account when omitted. Staff-only fields are ignored.
+     */
+    async create(data) {
+        const res = await this.ctx.request('POST', '/applications', data, { cache: false });
+        this.invalidateLists();
+        return res.application;
+    }
+    /**
+     * Update an application's mutable fields.
+     * @param applicationId - The application's `_id`.
+     * @param data - Subset of updatable fields. Staff-only fields are ignored.
+     */
+    async update(applicationId, data) {
+        const res = await this.ctx.request('PATCH', appPath(applicationId), data, {
+            cache: false,
+        });
+        this.invalidateLists([`GET:${appPath(applicationId)}`]);
+        return res.application;
+    }
+    /**
+     * Soft-delete an application.
+     * @param applicationId - The application's `_id`.
+     */
+    async delete(applicationId) {
+        const result = await this.ctx.request('DELETE', appPath(applicationId), undefined, {
+            cache: false,
+        });
+        this.invalidateLists([`GET:${appPath(applicationId)}`, `GET:${credentialsPath(applicationId)}`]);
+        return result;
+    }
+    /**
+     * Usage statistics for an application.
+     * @param applicationId - The application's `_id`.
+     * @param period - Time window (defaults to the server default).
+     */
+    async usage(applicationId, period) {
+        return this.ctx.request('GET', `${appPath(applicationId)}/usage`, period ? { period } : undefined, { cache: true, cacheTTL: SHORT_TTL });
+    }
+    /**
+     * Resolve an OAuth `client_id` (an active credential's public key) to the
+     * owning application's PUBLIC identity. No authentication required — only
+     * sanitized, display-safe metadata; use it to render the requesting app in
+     * consent, authorize, and device-flow approval screens before any session
+     * exists.
+     */
+    async getPublic(clientId) {
+        const res = await this.ctx.request('GET', `/auth/oauth/client/${enc(clientId)}`, undefined, 
+        // Public client metadata (pre-session consent UI) — skip the bearer preflight.
+        { cache: true, cacheTTL: MEDIUM_TTL, skipAuth: true });
+        return res.application;
+    }
+    /**
+     * Bust every cached application list — the unscoped entry and every
+     * owner-scoped `GET:/applications?ownerAccountId=<id>` variant — plus any
+     * extra keys, in one pass. The `?` prefix never matches the
+     * `GET:/applications/<id>…` detail keys.
+     */
+    invalidateLists(extraKeys = []) {
+        this.ctx.http.invalidateCache({ keys: ['GET:/applications', ...extraKeys], prefixes: ['GET:/applications?'] });
+    }
+}
+function appPath(applicationId) {
+    return `/applications/${enc(applicationId)}`;
+}
+function credentialsPath(applicationId) {
+    return `${appPath(applicationId)}/credentials`;
+}

package/dist/esm/api/assets.js

@@ -0,0 +1,324 @@
+/**
+ * `oxy.assets` — files: upload, link to entities, resolve URLs, read content.
+ *
+ * ## Which URL to use
+ *
+ * - {@link AssetsApi.url} — asks the API for a URL valid for the CURRENT
+ *   caller, whatever the asset's visibility. The right default.
+ * - {@link AssetsApi.publicUrl} — a synchronous string builder for an asset
+ *   KNOWN to be public (avatars). A private asset renders a hard 404 there.
+ * - {@link AssetsApi.urls} — {@link AssetsApi.url} for a whole grid in one
+ *   round trip.
+ *
+ * The service-token asset routes (metadata by id / by hash, linked download
+ * URLs) are `OxyServer`'s `assets` (`@oxy.so/core/server`).
+ */
+import { isReactNative } from '@oxy.so/protocol/random';
+import { logger } from '../logger/index.js';
+import { AssetUrlResolutionError } from '../OxyServices.errors.js';
+import { extractErrorStatus } from '../utils/errorUtils.js';
+/**
+ * Conservative lower bound (10 min) the SDK assumes for the lifetime of the
+ * scoped media token (`mt`) the API embeds in a private asset's stream URL. The
+ * API mints 900s (`MEDIA_TOKEN_TTL_SECONDS`); core assumes a shorter floor
+ * because it cannot observe a server-side change at runtime, and
+ * under-assuming only ever shortens the cache (more refetches, never a dead URL).
+ */
+const ASSET_MEDIA_TOKEN_TTL_MS = 10 * 60 * 1000;
+/**
+ * Fraction of a resolved URL's lifetime it may stay cached: a URL dies with its
+ * media token, so caching for the full lifetime guarantees a window that hands
+ * out dead URLs (clock skew, render latency, queued image requests).
+ */
+const ASSET_URL_CACHE_LIFETIME_FRACTION = 0.5;
+/** Assumed URL lifetime (seconds) when no `expiresIn` is asked for; the API default. */
+const DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS = 3600;
+const ASSET_TTL = 5 * 60 * 1000;
+/**
+ * How long a resolved asset URL may stay in the SDK's GET cache, in ms: never
+ * longer than the media token's lifetime, and discounted below it.
+ */
+export function assetUrlCacheTTL(expiresIn) {
+    const requestedLifetimeMs = (expiresIn ?? DEFAULT_ASSET_URL_EXPIRES_IN_SECONDS) * 1000;
+    const boundedLifetimeMs = Math.min(requestedLifetimeMs, ASSET_MEDIA_TOKEN_TTL_MS);
+    return Math.floor(boundedLifetimeMs * ASSET_URL_CACHE_LIFETIME_FRACTION);
+}
+export class AssetsApi {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    // ── Upload ───────────────────────────────────────────────────────────────
+    /**
+     * Upload a file. Accepts a web `File`/`Blob` or a React Native
+     * `{ uri, type?, name?, size? }` descriptor.
+     *
+     * On React Native the descriptor goes into the multipart body as-is (RN's
+     * FormData reads the file from disk). On the web a plain `{ uri }` cannot be
+     * read by FormData (it would upload `[object Object]` — a 0-byte asset), so
+     * the uri is materialised into a Blob first; an empty result throws.
+     */
+    async upload(file, options = {}) {
+        const fileName = 'name' in file && file.name ? file.name : 'unknown';
+        const fileSize = 'size' in file && file.size ? file.size : 0;
+        const formData = new FormData();
+        if ((typeof File !== 'undefined' && file instanceof File) || (typeof Blob !== 'undefined' && file instanceof Blob)) {
+            formData.append('file', file, fileName);
+        }
+        else if ('uri' in file && typeof file.uri === 'string') {
+            const descriptor = file;
+            if (isReactNative()) {
+                // No in-JS Blob on RN: that fails on Hermes for ArrayBuffer-backed Blobs.
+                formData.append('file', descriptor, fileName);
+            }
+            else {
+                // `fetch` resolves blob:, data: and http(s): uris on the web.
+                const res = await fetch(descriptor.uri);
+                if (!res.ok) {
+                    throw new Error(`Failed to read file from uri (status ${res.status})`);
+                }
+                const fetched = await res.blob();
+                const blob = fetched.type === '' && descriptor.type ? new Blob([fetched], { type: descriptor.type }) : fetched;
+                if (blob.size === 0) {
+                    throw new Error('Cannot upload an empty file');
+                }
+                formData.append('file', blob, fileName);
+            }
+        }
+        else {
+            throw new Error('Unsupported file input: expected File, Blob, or { uri, type?, name?, size? } descriptor');
+        }
+        if (options.visibility)
+            formData.append('visibility', options.visibility);
+        if (options.metadata)
+            formData.append('metadata', JSON.stringify(options.metadata));
+        try {
+            const response = await this.ctx.request('POST', '/assets/upload', formData, { cache: false });
+            options.onProgress?.(100);
+            return response;
+        }
+        catch (error) {
+            logger.error('File upload error', error, { component: 'oxy.assets' });
+            error.fileContext = { fileName, fileSize };
+            throw error;
+        }
+    }
+    /**
+     * Upload a public avatar and link it to `userId`'s profile. Does not change
+     * the profile's `avatar` field — set it with `users.updateMe`.
+     */
+    async uploadAvatar(file, userId, app = 'profiles') {
+        const asset = await this.upload(file, { visibility: 'public' });
+        await this.link(asset.file.id, { app, entityType: 'avatar', entityId: userId }, { visibility: 'public' });
+        return asset;
+    }
+    // ── Links ────────────────────────────────────────────────────────────────
+    /** Link an asset to an entity (what keeps it alive). */
+    async link(fileId, target, options = {}) {
+        const body = { ...target };
+        if (options.visibility)
+            body.visibility = options.visibility;
+        if (options.webhookUrl)
+            body.webhookUrl = options.webhookUrl;
+        const res = await this.ctx.request('POST', `/assets/${enc(fileId)}/links`, body, {
+            cache: false,
+        });
+        this.ctx.oxy.cache.delete(`GET:/assets/${enc(fileId)}`);
+        return res;
+    }
+    /** Remove an asset's link to an entity. */
+    async unlink(fileId, target) {
+        const res = await this.ctx.request('DELETE', `/assets/${enc(fileId)}/links`, target, { cache: false });
+        this.ctx.oxy.cache.delete(`GET:/assets/${enc(fileId)}`);
+        return res;
+    }
+    // ── Reads ────────────────────────────────────────────────────────────────
+    /** An asset's record: size, mime, visibility, links, variants. */
+    async get(fileId) {
+        return this.ctx.request('GET', `/assets/${enc(fileId)}`, undefined, { cache: true, cacheTTL: ASSET_TTL });
+    }
+    /** The signed-in user's files, newest first. */
+    async list(params = {}) {
+        const query = {};
+        if (params.limit)
+            query.limit = params.limit;
+        if (params.offset)
+            query.offset = params.offset;
+        return this.ctx.request('GET', '/assets', query, { cache: false });
+    }
+    /** The account's storage usage, aggregated from its assets. */
+    async usage() {
+        return this.ctx.request('GET', '/storage/usage', undefined, { cache: false });
+    }
+    // ── URLs ─────────────────────────────────────────────────────────────────
+    /**
+     * A URL for `fileId` valid for the CURRENT caller, whatever its visibility
+     * (`GET /assets/:id/url`): the CDN form for a public asset, an API-origin
+     * stream URL with a scoped media token for a private one the caller may
+     * read. Returned exactly as the API produced it.
+     *
+     * Throws {@link AssetUrlResolutionError} when the API returns no URL or the
+     * request fails (401/403/404 included) — deliberately never falling back to
+     * {@link publicUrl}, which would hand back a known-404 for a private asset and
+     * hide the real failure.
+     *
+     * Cached per identity for well under the media token's lifetime.
+     */
+    async url(fileId, variant, expiresIn) {
+        let url;
+        try {
+            url = await this.resolveUrl(fileId, variant, expiresIn);
+        }
+        catch (error) {
+            throw new AssetUrlResolutionError(fileId, variant, extractErrorStatus(error), error);
+        }
+        if (!url) {
+            throw new AssetUrlResolutionError(fileId, variant, undefined);
+        }
+        return url;
+    }
+    /**
+     * A synchronous `<img src>` URL for an asset KNOWN to be **public** — a pure
+     * string builder with no knowledge of visibility: `${cloudURL}/<id>[?variant]`.
+     * A private or unlisted asset 404s there; use {@link url}.
+     *
+     * It never embeds the caller's bearer token (the string lands in DOM
+     * attributes, network panels, caches and logs). With `expiresIn` it builds
+     * the API-origin stream form, still credential-less: there is no synchronous
+     * private-asset path.
+     */
+    publicUrl(fileId, variant, expiresIn) {
+        if (!expiresIn) {
+            const variantQs = variant ? `?variant=${encodeURIComponent(variant)}` : '';
+            return `${this.ctx.oxy.cloudURL}/${enc(fileId)}${variantQs}`;
+        }
+        const params = new URLSearchParams();
+        if (variant)
+            params.set('variant', variant);
+        params.set('expiresIn', String(expiresIn));
+        params.set('fallback', 'placeholderVisible');
+        return `${this.ctx.oxy.baseURL}/assets/${enc(fileId)}/stream?${params.toString()}`;
+    }
+    /**
+     * {@link url} for many assets — each with its OWN variant — in one round
+     * trip. Ids the caller cannot read (or that do not exist) are OMITTED from
+     * the map: no CDN fallback, so a grid never renders a known-404. Keyed by
+     * `fileId`.
+     */
+    async urls(requests, options) {
+        const response = await this.access(requests, options);
+        const urls = {};
+        for (const [id, result] of Object.entries(response.results ?? {})) {
+            if (result.allowed && result.url)
+                urls[id] = result.url;
+        }
+        return urls;
+    }
+    /**
+     * The raw per-file access envelope behind {@link urls}
+     * (`POST /assets/batch-access`): `allowed`, `url`, `visibility`, `mime` or
+     * `error` per file. Blank ids are dropped and exact `(fileId, variant)`
+     * duplicates collapsed; an empty list makes no call. The server caps a batch
+     * at 100 entries.
+     */
+    async access(requests, options) {
+        const files = dedupeFileAccessRequests(requests);
+        if (files.length === 0)
+            return { results: {} };
+        const body = { files };
+        if (typeof options?.expiresIn === 'number')
+            body.expiresIn = options.expiresIn;
+        if (typeof options?.context === 'string')
+            body.context = options.context;
+        return this.ctx.request('POST', '/assets/batch-access', body, { cache: false });
+    }
+    // ── Content ──────────────────────────────────────────────────────────────
+    /** An asset's content as text. */
+    async text(fileId, variant) {
+        const response = await this.fetchContent(fileId, variant);
+        return response.text();
+    }
+    /** An asset's content as a Blob. */
+    async blob(fileId, variant) {
+        const response = await this.fetchContent(fileId, variant);
+        return response.blob();
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    /**
+     * Delete an asset. With active links the server refuses and answers the
+     * summary of what would break, unless `force`.
+     */
+    async delete(fileId, options = {}) {
+        const url = `/assets/${enc(fileId)}${options.force ? '?force=true' : ''}`;
+        const res = await this.ctx.request('DELETE', url, undefined, { cache: false });
+        this.evict(fileId);
+        return res;
+    }
+    /** Restore an asset from the trash. */
+    async restore(fileId) {
+        const res = await this.ctx.request('POST', `/assets/${enc(fileId)}/restore`, undefined, { cache: false });
+        this.ctx.oxy.cache.delete(`GET:/assets/${enc(fileId)}`);
+        return res;
+    }
+    /** Change an asset's visibility. */
+    async setVisibility(fileId, visibility) {
+        const res = await this.ctx.request('PATCH', `/assets/${enc(fileId)}/visibility`, { visibility }, { cache: false });
+        // Visibility changes the record AND the resolved URL (CDN vs signed).
+        this.evict(fileId);
+        return res;
+    }
+    // ── Internals ────────────────────────────────────────────────────────────
+    async resolveUrl(fileId, variant, expiresIn) {
+        const params = {};
+        if (variant)
+            params.variant = variant;
+        if (expiresIn)
+            params.expiresIn = expiresIn;
+        const res = await this.ctx.request('GET', `/assets/${enc(fileId)}/url`, Object.keys(params).length ? params : undefined, { cache: true, cacheTTL: assetUrlCacheTTL(expiresIn) });
+        return res?.url || undefined;
+    }
+    async fetchContent(fileId, variant) {
+        const url = await this.resolveUrl(fileId, variant);
+        if (!url)
+            throw new Error('No download URL returned for asset');
+        const response = await fetch(url, {
+            // Cookies only to the API's own origin — never to a caller-supplied host.
+            credentials: isSameOrigin(url, this.ctx.oxy.baseURL) ? 'include' : 'omit',
+        });
+        if (!response?.ok) {
+            throw new Error(`Failed to fetch asset content (status ${response?.status})`);
+        }
+        return response;
+    }
+    /** Drop the cached record and every cached URL variant of an asset, in one pass. */
+    evict(fileId) {
+        this.ctx.http.invalidateCache({ keys: [`GET:/assets/${enc(fileId)}`], prefixes: [`GET:/assets/${enc(fileId)}/url`] });
+    }
+}
+const enc = encodeURIComponent;
+/**
+ * Drop blank ids and collapse exact `(fileId, variant)` duplicates (first wins,
+ * order kept). Two variants of one file are both kept — but the response is
+ * keyed by `fileId`, so a caller needing both must issue separate calls.
+ */
+function dedupeFileAccessRequests(requests) {
+    const seen = new Set();
+    const out = [];
+    for (const req of requests) {
+        if (typeof req?.fileId !== 'string' || req.fileId.trim().length === 0)
+            continue;
+        const key = `${req.fileId}\u0000${req.variant ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(req.variant === undefined ? { fileId: req.fileId } : { fileId: req.fileId, variant: req.variant });
+    }
+    return out;
+}
+function isSameOrigin(url, baseURL) {
+    try {
+        return new URL(url).origin === new URL(baseURL).origin;
+    }
+    catch {
+        return false;
+    }
+}