@oxy.so/core 1.0.0 → 1.1.0

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/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');
-    });
-  });
-});