@oxyhq/core 3.15.0 → 3.16.1

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

@@ -1,9 +1,5 @@
 import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, AssetVariant } from '../models/interfaces';
 import type { OxyServicesBase } from '../OxyServices.base';
-interface FileDownloadUrlOptions {
-    /** Omit bearer access tokens from generated URLs, even when authenticated. */
-    omitToken?: boolean;
-}
 export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -11,32 +7,16 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
          */
         deleteFile(fileId: string): Promise<any>;
         /**
-         * Build a synchronous file URL from an Oxy asset id.
+         * Build a synchronous, `<img src>`-ready file URL from an Oxy asset id.
          *
-         * This is the single chokepoint every Oxy app uses to turn a stored file id
-         * (avatars, post media, etc.) into a `<img src>`-ready URL, so it resolves to
-         * one of two forms depending on whether the caller needs a signed/private URL:
-         *
-         * - **Public asset (default)** — no access token planted on the client AND no
-         *   `expiresIn` requested → returns the clean CDN form
-         *   `${cloudURL}/<id>[?variant=...]` (e.g. `https://cloud.oxy.so/<id>?variant=thumb`).
-         *   CloudFront resolves the id against the public media origin. No token,
-         *   `fallback`, or origin query params are emitted — these URLs are cacheable
-         *   and shareable.
-         * - **Signed / private asset** — an access token is present on the client OR
-         *   `expiresIn` was passed (the caller explicitly wants an expiring/authorized
-         *   URL) → keeps the authenticated origin form
-         *   `${baseURL}/assets/<id>/stream?...&token=...`. Private assets are NOT on
-         *   the public CDN, so they must go through the API origin that can authorize
-         *   the request.
-         *
-         * `cloudURL` (default `https://cloud.oxy.so`) is configured once on the
-         * `OxyServices` constructor and read via `getCloudURL()`; the API origin is
-         * `getBaseURL()` (e.g. `https://api.oxy.so`).
-         *
-         * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
+         * This method must never embed the caller's general access token in the
+         * returned URL. The URL is commonly rendered into DOM attributes, browser
+         * network panels, caches, and logs. Public asset URLs use the clean CDN
+         * origin; callers that need authorized/private access should use
+         * {@link getFileDownloadUrlAsync}, which asks the API for a scoped download
+         * URL instead of exposing the in-memory bearer token in a query string.
          */
-        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number, options?: FileDownloadUrlOptions): string;
+        getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string;
         /**
          * Get file download URL asynchronously (returns signed URL directly from CDN)
          */
@@ -172,4 +152,3 @@ export declare function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>
         }>;
     };
 } & T;
-export {};

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

@@ -94,6 +94,14 @@ export interface CommonsApprovalInfo {
     scopes: string[];
     /** The origin the session is bound to (the RP web origin), when applicable. */
     boundOrigin?: string;
+    /**
+     * Server-authoritative anti-phishing flag: `true` only when this device-flow
+     * sign-in was started from a verified, registered origin of a trusted app.
+     * The approver (Commons) shows a warning when this is `false`. Always present
+     * — a missing/non-boolean server value is coerced to `false` (fail-safe to
+     * "not verified") by {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
+     */
+    originVerified: boolean;
     /** Server-authoritative expiry (epoch milliseconds). */
     expiresAt: number;
     /** Session lifecycle status. */

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

@@ -0,0 +1,102 @@
+/**
+ * Link Preview (unfurl) Mixin
+ *
+ * Resolves link previews ("unfurls") through the Oxy API so every Oxy app
+ * stops scraping link metadata locally. The API owns resolution and re-hosts
+ * the preview `image`/`favicon` on Oxy media (`cloud.oxy.so/<fileId>`), so
+ * consumers render the returned URLs directly with no per-app proxy.
+ *
+ * Wire shapes (`LinkPreview`, `LinkPreviewBatchResponse`) are the single source
+ * of truth in `@oxyhq/contracts`; this mixin imports them rather than
+ * redefining them so producer (oxy-api) and consumers cannot drift.
+ *
+ * Caching note: these GET/POST reads are NOT cached at the SDK layer (`cache:
+ * false`). A preview can be returned `'pending'` first and `'resolved'` on a
+ * later read, so an SDK GET cache would pin the stale `'pending'` snapshot.
+ * App-side caching (React Query / stores) owns this responsibility.
+ */
+import type { LinkPreview } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+export declare function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(Base: T): {
+    new (...args: any[]): {
+        /**
+         * Resolve a single link preview via `GET /links/preview?url=<encoded>&wait=0|1`.
+         *
+         * @param url - The URL to unfurl. Sent percent-encoded in the query string.
+         * @param opts.wait - When `true`, asks the server to resolve synchronously
+         *   (`wait=1`) instead of returning a `'pending'` placeholder for a
+         *   first-seen URL. Defaults to `false` (`wait=0`).
+         *
+         * Not cached at the SDK layer: a `'pending'` result can become `'resolved'`
+         * on a later read, so caching here would serve the stale placeholder.
+         */
+        getLinkPreview(url: string, opts?: {
+            wait?: boolean;
+        }): Promise<LinkPreview>;
+        /**
+         * Resolve multiple link previews via `POST /links/previews` (body `{ urls }`).
+         *
+         * Inputs are de-duplicated and split into chunks of {@link LINK_PREVIEWS_CHUNK_SIZE}
+         * (the server-side cap). Chunks run concurrently and their `data` maps are
+         * merged into a single result keyed by the REQUESTED url (the exact string
+         * passed in `urls`) — matching the batch contract — so a caller can always
+         * look its own input back up.
+         *
+         * An empty / whitespace-only input resolves immediately with `{}` and
+         * performs no network call. A failure in any chunk surfaces (via
+         * `handleError`) rather than being swallowed.
+         */
+        getLinkPreviews(urls: string[]): Promise<Record<string, LinkPreview>>;
+        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;
+        getSessionBaseUrl(): 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;
+        setActingAs(userId: string | null): void;
+        getActingAs(): string | 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/index.d.ts

@@ -31,6 +31,7 @@ import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
+import { OxyServicesLinksMixin } from './OxyServices.links';
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
  * `composeOxyServices()` produces a class whose instances expose all of
@@ -40,7 +41,7 @@ import { OxyServicesNodesMixin } from './OxyServices.nodes';
  * 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 OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<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 OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<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 OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
+type AllMixinInstances = InstanceType<ReturnType<typeof OxyServicesAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesFedCMMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSilentAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesRedirectAuthMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesSsoMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesUserMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesIdentityMixin<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 OxyServicesApplicationsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesWorkspacesMixin<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 OxyServicesManagedAccountsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>> & InstanceType<ReturnType<typeof OxyServicesLinksMixin<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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.15.0",
+  "version": "3.16.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -98,7 +98,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "0.4.0",
+    "@oxyhq/contracts": "0.5.0",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",

package/src/mixins/OxyServices.assets.ts

@@ -2,11 +2,6 @@ import type { AccountStorageUsageResponse, AssetUploadInput, AssetUrlResponse, A
 import type { OxyServicesBase } from '../OxyServices.base';
 import { isReactNative } from '../utils/platform';
 
-interface FileDownloadUrlOptions {
-  /** Omit bearer access tokens from generated URLs, even when authenticated. */
-  omitToken?: boolean;
-}
-
 export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -25,55 +20,30 @@ export function OxyServicesAssetsMixin<T extends typeof OxyServicesBase>(Base: T
     }
 
     /**
-     * Build a synchronous file URL from an Oxy asset id.
-     *
-     * This is the single chokepoint every Oxy app uses to turn a stored file id
-     * (avatars, post media, etc.) into a `<img src>`-ready URL, so it resolves to
-     * one of two forms depending on whether the caller needs a signed/private URL:
-     *
-     * - **Public asset (default)** — no access token planted on the client AND no
-     *   `expiresIn` requested → returns the clean CDN form
-     *   `${cloudURL}/<id>[?variant=...]` (e.g. `https://cloud.oxy.so/<id>?variant=thumb`).
-     *   CloudFront resolves the id against the public media origin. No token,
-     *   `fallback`, or origin query params are emitted — these URLs are cacheable
-     *   and shareable.
-     * - **Signed / private asset** — an access token is present on the client OR
-     *   `expiresIn` was passed (the caller explicitly wants an expiring/authorized
-     *   URL) → keeps the authenticated origin form
-     *   `${baseURL}/assets/<id>/stream?...&token=...`. Private assets are NOT on
-     *   the public CDN, so they must go through the API origin that can authorize
-     *   the request.
+     * Build a synchronous, `<img src>`-ready file URL from an Oxy asset id.
      *
-     * `cloudURL` (default `https://cloud.oxy.so`) is configured once on the
-     * `OxyServices` constructor and read via `getCloudURL()`; the API origin is
-     * `getBaseURL()` (e.g. `https://api.oxy.so`).
-     *
-     * For a CDN-signed URL fetched from the API, use {@link getFileDownloadUrlAsync}.
+     * This method must never embed the caller's general access token in the
+     * returned URL. The URL is commonly rendered into DOM attributes, browser
+     * network panels, caches, and logs. Public asset URLs use the clean CDN
+     * origin; callers that need authorized/private access should use
+     * {@link getFileDownloadUrlAsync}, which asks the API for a scoped download
+     * URL instead of exposing the in-memory bearer token in a query string.
      */
-    getFileDownloadUrl(
-      fileId: string,
-      variant?: string,
-      expiresIn?: number,
-      options: FileDownloadUrlOptions = {}
-    ): string {
-      const token = options.omitToken ? undefined : this.getClient().getAccessToken();
-
-      // Public case: no auth token and no expiry requested → clean CDN URL.
-      // CloudFront serves the public media origin under `${cloudURL}/<id>`.
-      if (!token && !expiresIn) {
+    getFileDownloadUrl(fileId: string, variant?: string, expiresIn?: number): string {
+      // Never embed the in-memory bearer token: this URL is rendered into DOM
+      // attributes, browser network panels, caches, and logs. Public assets get
+      // the clean CDN origin; private/authorized access goes through
+      // `getFileDownloadUrlAsync`.
+      if (!expiresIn) {
         const variantQs = variant ? `?variant=${encodeURIComponent(variant)}` : '';
         return `${this.getCloudURL()}/${encodeURIComponent(fileId)}${variantQs}`;
       }
 
-      // Signed / private case: route through the authenticated API origin's
-      // stream endpoint so the request can be authorized (private assets are not
-      // exposed on the public CDN).
       const base = this.getBaseURL();
       const params = new URLSearchParams();
       if (variant) params.set('variant', variant);
-      if (expiresIn) params.set('expiresIn', String(expiresIn));
+      params.set('expiresIn', String(expiresIn));
       params.set('fallback', 'placeholderVisible');
-      if (token) params.set('token', token);
 
       const qs = params.toString();
       return `${base}/assets/${encodeURIComponent(fileId)}/stream${qs ? `?${qs}` : ''}`;

package/src/mixins/OxyServices.auth.ts

@@ -125,12 +125,35 @@ export interface CommonsApprovalInfo {
   scopes: string[];
   /** The origin the session is bound to (the RP web origin), when applicable. */
   boundOrigin?: string;
+  /**
+   * Server-authoritative anti-phishing flag: `true` only when this device-flow
+   * sign-in was started from a verified, registered origin of a trusted app.
+   * The approver (Commons) shows a warning when this is `false`. Always present
+   * — a missing/non-boolean server value is coerced to `false` (fail-safe to
+   * "not verified") by {@link OxyServicesAuthMixin.getCommonsApprovalInfo}.
+   */
+  originVerified: boolean;
   /** Server-authoritative expiry (epoch milliseconds). */
   expiresAt: number;
   /** Session lifecycle status. */
   status: string;
 }
 
+/**
+ * @internal Raw server response of `GET /auth/session/approve-info/:code`.
+ * `originVerified` is typed loosely here because older servers may omit it (or
+ * send a non-boolean); the SDK coerces it to a strict `boolean` when mapping
+ * into {@link CommonsApprovalInfo}.
+ */
+interface CommonsApprovalInfoResponse {
+  application: PublicApplication;
+  scopes: string[];
+  boundOrigin?: string;
+  originVerified?: unknown;
+  expiresAt: number;
+  status: string;
+}
+
 /** Result of approving / denying a "Sign in with Oxy" request. */
 export interface CommonsSignInActionResult {
   success: boolean;
@@ -826,12 +849,23 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getCommonsApprovalInfo(authorizeCode: string): Promise<CommonsApprovalInfo> {
       try {
-        return await this.makeRequest<CommonsApprovalInfo>(
+        const raw = await this.makeRequest<CommonsApprovalInfoResponse>(
           'GET',
           `/auth/session/approve-info/${encodeURIComponent(authorizeCode)}`,
           undefined,
           { cache: false }
         );
+        return {
+          application: raw.application,
+          scopes: raw.scopes,
+          boundOrigin: raw.boundOrigin,
+          // Fail-safe: only a literal boolean `true` counts as verified. A
+          // missing or non-boolean value (older server, malformed response)
+          // coerces to `false` so a stale server can never imply trust.
+          originVerified: raw.originVerified === true,
+          expiresAt: raw.expiresAt,
+          status: raw.status,
+        };
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.links.ts

@@ -0,0 +1,103 @@
+/**
+ * Link Preview (unfurl) Mixin
+ *
+ * Resolves link previews ("unfurls") through the Oxy API so every Oxy app
+ * stops scraping link metadata locally. The API owns resolution and re-hosts
+ * the preview `image`/`favicon` on Oxy media (`cloud.oxy.so/<fileId>`), so
+ * consumers render the returned URLs directly with no per-app proxy.
+ *
+ * Wire shapes (`LinkPreview`, `LinkPreviewBatchResponse`) are the single source
+ * of truth in `@oxyhq/contracts`; this mixin imports them rather than
+ * redefining them so producer (oxy-api) and consumers cannot drift.
+ *
+ * Caching note: these GET/POST reads are NOT cached at the SDK layer (`cache:
+ * false`). A preview can be returned `'pending'` first and `'resolved'` on a
+ * later read, so an SDK GET cache would pin the stale `'pending'` snapshot.
+ * App-side caching (React Query / stores) owns this responsibility.
+ */
+import type { LinkPreview, LinkPreviewBatchResponse } from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { buildUrl } from '../utils/apiUtils';
+
+/**
+ * Maximum number of URLs sent per `POST /links/previews` request. Matches the
+ * server-side batch cap (`linkPreviewBatchRequestSchema`'s `.max(50)`); larger
+ * inputs are split into multiple chunked calls and the result maps merged,
+ * mirroring how `getUsersByIds` chunks at 100.
+ */
+const LINK_PREVIEWS_CHUNK_SIZE = 50;
+
+export function OxyServicesLinksMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Resolve a single link preview via `GET /links/preview?url=<encoded>&wait=0|1`.
+     *
+     * @param url - The URL to unfurl. Sent percent-encoded in the query string.
+     * @param opts.wait - When `true`, asks the server to resolve synchronously
+     *   (`wait=1`) instead of returning a `'pending'` placeholder for a
+     *   first-seen URL. Defaults to `false` (`wait=0`).
+     *
+     * Not cached at the SDK layer: a `'pending'` result can become `'resolved'`
+     * on a later read, so caching here would serve the stale placeholder.
+     */
+    async getLinkPreview(url: string, opts?: { wait?: boolean }): Promise<LinkPreview> {
+      try {
+        const path = buildUrl('/links/preview', { url, wait: opts?.wait ? 1 : 0 });
+        return await this.makeRequest<LinkPreview>('GET', path, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Resolve multiple link previews via `POST /links/previews` (body `{ urls }`).
+     *
+     * Inputs are de-duplicated and split into chunks of {@link LINK_PREVIEWS_CHUNK_SIZE}
+     * (the server-side cap). Chunks run concurrently and their `data` maps are
+     * merged into a single result keyed by the REQUESTED url (the exact string
+     * passed in `urls`) — matching the batch contract — so a caller can always
+     * look its own input back up.
+     *
+     * An empty / whitespace-only input resolves immediately with `{}` and
+     * performs no network call. A failure in any chunk surfaces (via
+     * `handleError`) rather than being swallowed.
+     */
+    async getLinkPreviews(urls: string[]): Promise<Record<string, LinkPreview>> {
+      const uniqueUrls = Array.from(
+        new Set(urls.filter((u): u is string => typeof u === 'string' && u.trim().length > 0)),
+      );
+      if (uniqueUrls.length === 0) {
+        return {};
+      }
+
+      const chunks: string[][] = [];
+      for (let i = 0; i < uniqueUrls.length; i += LINK_PREVIEWS_CHUNK_SIZE) {
+        chunks.push(uniqueUrls.slice(i, i + LINK_PREVIEWS_CHUNK_SIZE));
+      }
+
+      try {
+        const responses = await Promise.all(
+          chunks.map((chunk) =>
+            this.makeRequest<LinkPreviewBatchResponse>(
+              'POST',
+              '/links/previews',
+              { urls: chunk },
+              { cache: false },
+            ),
+          ),
+        );
+
+        return responses.reduce<Record<string, LinkPreview>>(
+          (merged, response) => Object.assign(merged, response?.data ?? {}),
+          {},
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/__tests__/OxyServices.links.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Link-preview mixin tests.
+ *
+ * Stubs `makeRequest` so the tests run with no network, then asserts:
+ *  - `getLinkPreview` builds `GET /links/preview?url=<percent-encoded>&wait=0|1`,
+ *    percent-encoding the target URL so its `?`/`&`/`=` cannot break out of the
+ *    query string, defaults `wait` to `0`, sends `wait=1` when `{ wait: true }`,
+ *    reads uncached (`cache:false`), returns the preview, and surfaces errors.
+ *  - `getLinkPreviews` de-duplicates input, no-ops to `{}` on empty input,
+ *    chunks at 50 URLs/request (`POST /links/previews`), merges every chunk's
+ *    `data` map keyed by the requested url, and surfaces a chunk failure.
+ */
+
+import type { LinkPreview, LinkPreviewBatchResponse } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+
+const sampleResolved: LinkPreview = {
+  url: 'https://news.example.com/a',
+  status: 'resolved',
+  title: 'Headline',
+  description: 'Lede',
+  image: 'https://cloud.oxy.so/img123',
+  siteName: 'Example News',
+  favicon: 'https://cloud.oxy.so/fav123',
+  resolvedAt: '2026-06-28T00:00:00.000Z',
+};
+
+describe('OxyServices.links', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('getLinkPreview', () => {
+    it('percent-encodes the URL and defaults wait=0', async () => {
+      makeRequestSpy.mockResolvedValueOnce(sampleResolved);
+
+      const result = await oxy.getLinkPreview('https://news.example.com/a?b=c&d=e');
+
+      expect(result).toEqual(sampleResolved);
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/links/preview?url=https%3A%2F%2Fnews.example.com%2Fa%3Fb%3Dc%26d%3De&wait=0',
+        undefined,
+        { cache: false },
+      );
+    });
+
+    it('sends wait=1 when opts.wait is true', async () => {
+      makeRequestSpy.mockResolvedValueOnce({ url: 'https://x.test/', status: 'pending' });
+
+      await oxy.getLinkPreview('https://x.test/', { wait: true });
+
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/links/preview?url=https%3A%2F%2Fx.test%2F&wait=1',
+        undefined,
+        { cache: false },
+      );
+    });
+
+    it('surfaces errors via handleError', async () => {
+      makeRequestSpy.mockRejectedValueOnce(new Error('boom'));
+
+      await expect(oxy.getLinkPreview('https://x.test/')).rejects.toThrow('boom');
+    });
+  });
+
+  describe('getLinkPreviews', () => {
+    it('returns {} and performs no network call for empty / whitespace input', async () => {
+      await expect(oxy.getLinkPreviews([])).resolves.toEqual({});
+      await expect(oxy.getLinkPreviews(['', '   '])).resolves.toEqual({});
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+    });
+
+    it('de-duplicates and sends a single chunk for <= 50 unique URLs', async () => {
+      const response: LinkPreviewBatchResponse = {
+        data: { 'https://a.test/': sampleResolved },
+      };
+      makeRequestSpy.mockResolvedValueOnce(response);
+
+      const result = await oxy.getLinkPreviews([
+        'https://a.test/',
+        'https://a.test/', // duplicate
+        '   ', // dropped
+      ]);
+
+      expect(result).toEqual(response.data);
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/links/previews',
+        { urls: ['https://a.test/'] },
+        { cache: false },
+      );
+    });
+
+    it('chunks at 50 URLs per request and merges each chunk data map', async () => {
+      const urls = Array.from({ length: 120 }, (_, i) => `https://site.test/${i}`);
+
+      makeRequestSpy.mockImplementation(
+        async (
+          _method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+          _url: string,
+          data?: { urls: string[] },
+        ): Promise<LinkPreviewBatchResponse> => {
+          const chunkUrls = data?.urls ?? [];
+          const dataMap: Record<string, LinkPreview> = {};
+          for (const u of chunkUrls) {
+            dataMap[u] = { url: u, status: 'resolved', title: `t-${u}` };
+          }
+          return { data: dataMap };
+        },
+      );
+
+      const result = await oxy.getLinkPreviews(urls);
+
+      // 120 unique URLs => 50 + 50 + 20 across three POSTs.
+      expect(makeRequestSpy).toHaveBeenCalledTimes(3);
+      const chunkSizes = makeRequestSpy.mock.calls.map((call) => (call[2] as { urls: string[] }).urls.length);
+      expect(chunkSizes).toEqual([50, 50, 20]);
+
+      // Every requested URL is present in the merged, request-keyed map.
+      expect(Object.keys(result)).toHaveLength(120);
+      expect(result['https://site.test/0']).toEqual({
+        url: 'https://site.test/0',
+        status: 'resolved',
+        title: 't-https://site.test/0',
+      });
+      expect(result['https://site.test/119']).toEqual({
+        url: 'https://site.test/119',
+        status: 'resolved',
+        title: 't-https://site.test/119',
+      });
+    });
+
+    it('surfaces a chunk failure via handleError', async () => {
+      const urls = Array.from({ length: 60 }, (_, i) => `https://site.test/${i}`);
+      makeRequestSpy
+        .mockResolvedValueOnce({ data: {} })
+        .mockRejectedValueOnce(new Error('chunk failed'));
+
+      await expect(oxy.getLinkPreviews(urls)).rejects.toThrow('chunk failed');
+    });
+  });
+});