@oxy.so/core 1.0.1 → 1.1.2

package/src/utils/textNormalization.ts

@@ -90,7 +90,7 @@ const LEADING_HORIZONTAL_WHITESPACE = /\n +/g;
 const EXCESS_BLANK_LINES = /\n{3,}/g;
 
 /**
- * Normalize a SINGLE-LINE text value: page/link-preview titles, `siteName`,
+ * Normalize a SINGLE-LINE text value such as a page title or `siteName`,
  * display names, image alt text, handles, profile field labels.
  *
  * A line break in such a value is never meaningful — it is an artifact of the

package/dist/cjs/mixins/OxyServices.links.js

@@ -1,72 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.OxyServicesLinksMixin = OxyServicesLinksMixin;
-const apiUtils_1 = require("../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;
-function OxyServicesLinksMixin(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-        /**
-         * 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, opts) {
-            try {
-                const path = (0, apiUtils_1.buildUrl)('/links/preview', { url, wait: opts?.wait ? 1 : 0 });
-                return await this.makeRequest('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 result 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.
-         *
-         * `makeRequest` unwraps the API's top-level `{ data }` envelope (same as
-         * `getUsersByIds`'s `makeServiceRequest<User[]>`), so each chunk response is
-         * already the `Record<url, LinkPreview>` map — merge it directly.
-         *
-         * 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) {
-            const uniqueUrls = Array.from(new Set(urls.filter((u) => typeof u === 'string' && u.trim().length > 0)));
-            if (uniqueUrls.length === 0) {
-                return {};
-            }
-            const chunks = [];
-            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('POST', '/links/previews', { urls: chunk }, { cache: false })));
-                return responses.reduce((merged, response) => Object.assign(merged, response ?? {}), {});
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-    };
-}

package/dist/esm/mixins/OxyServices.links.js

@@ -1,69 +0,0 @@
-import { buildUrl } from '../utils/apiUtils.js';
-/**
- * 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(Base) {
-    return class extends Base {
-        constructor(...args) {
-            super(...args);
-        }
-        /**
-         * 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, opts) {
-            try {
-                const path = buildUrl('/links/preview', { url, wait: opts?.wait ? 1 : 0 });
-                return await this.makeRequest('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 result 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.
-         *
-         * `makeRequest` unwraps the API's top-level `{ data }` envelope (same as
-         * `getUsersByIds`'s `makeServiceRequest<User[]>`), so each chunk response is
-         * already the `Record<url, LinkPreview>` map — merge it directly.
-         *
-         * 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) {
-            const uniqueUrls = Array.from(new Set(urls.filter((u) => typeof u === 'string' && u.trim().length > 0)));
-            if (uniqueUrls.length === 0) {
-                return {};
-            }
-            const chunks = [];
-            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('POST', '/links/previews', { urls: chunk }, { cache: false })));
-                return responses.reduce((merged, response) => Object.assign(merged, response ?? {}), {});
-            }
-            catch (error) {
-                throw this.handleError(error);
-            }
-        }
-    };
-}

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

@@ -1,104 +0,0 @@
-/**
- * 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 `@oxy.so/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 '@oxy.so/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 result 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.
-         *
-         * `makeRequest` unwraps the API's top-level `{ data }` envelope (same as
-         * `getUsersByIds`'s `makeServiceRequest<User[]>`), so each chunk response is
-         * already the `Record<url, LinkPreview>` map — merge it directly.
-         *
-         * 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;
-        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/src/mixins/OxyServices.links.ts

@@ -1,107 +0,0 @@
-/**
- * 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 `@oxy.so/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 '@oxy.so/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 result 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.
-     *
-     * `makeRequest` unwraps the API's top-level `{ data }` envelope (same as
-     * `getUsersByIds`'s `makeServiceRequest<User[]>`), so each chunk response is
-     * already the `Record<url, LinkPreview>` map — merge it directly.
-     *
-     * 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<Record<string, LinkPreview>>(
-              'POST',
-              '/links/previews',
-              { urls: chunk },
-              { cache: false },
-            ),
-          ),
-        );
-
-        return responses.reduce<Record<string, LinkPreview>>(
-          (merged, response) => Object.assign(merged, response ?? {}),
-          {},
-        );
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-  };
-}

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

@@ -1,154 +0,0 @@
-/**
- * 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 } from '@oxy.so/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 () => {
-      // makeRequest unwraps the API's `{ data }` envelope, so the resolved value
-      // is the bare record (NOT `{ data: {...} }`) — mirror that real shape here.
-      const record: Record<string, LinkPreview> = { 'https://a.test/': sampleResolved };
-      makeRequestSpy.mockResolvedValueOnce(record);
-
-      const result = await oxy.getLinkPreviews([
-        'https://a.test/',
-        'https://a.test/', // duplicate
-        '   ', // dropped
-      ]);
-
-      expect(result).toEqual(record);
-      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<Record<string, LinkPreview>> => {
-          const chunkUrls = data?.urls ?? [];
-          const dataMap: Record<string, LinkPreview> = {};
-          for (const u of chunkUrls) {
-            dataMap[u] = { url: u, status: 'resolved', title: `t-${u}` };
-          }
-          return 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');
-    });
-  });
-});