@colixsystems/link-preview-client

Scoped client for the AppStudio link-preview API. It is a sibling of @colixsystems/translation-client, @colixsystems/agents-client and the other domain clients: a standalone fetch-based client you instantiate with createLinkPreviewClient({ baseUrl, getToken, getTenantId }).

Two surfaces, one package. This client serves two callers:

1. External / server-side integrations instantiate it directly and call get below.
2. The widget runtime — the Player and the exported Expo app instantiate the same package and inject it into WidgetContext.linkPreviews. Widgets never import this package; they call the SDK hook useLinkPreview(url) from @colixsystems/widget-sdk. Both surfaces speak the identical snake_case REST contract.

What it does

Given an http: or https: URL, the AppStudio backend fetches the page and returns its title, description, site name and preview image. The fetch happens on the server, so the device showing the link never contacts the linked site, and the image is served through a signed AppStudio proxy URL.

A page that cannot be previewed (unreachable, not HTML, too slow, or not allowed) is not an error: the call resolves with every field except url set to null. Render the plain link in that case.

Status

v0.1.0 — pre-publish. Not yet published to npm.

Wire format — snake_case, no transform

The response is returned snake_case verbatim: { url, title, description, site_name, image_url }. The only caller-facing camelCase is the method name (get) and the factory option names.

image_url arrives from the server as a server-relative path. The client prefixes it with the origin of baseUrl, so it loads in a native app, which has no page origin to resolve it against. With a relative baseUrl (a same-origin web app) it stays relative. The URL carries its own signed token, so load it directly in an <Image>; it needs no auth headers.

Public API

import {
  createLinkPreviewClient,
  LinkPreviewError,
} from "@colixsystems/link-preview-client";

const client = createLinkPreviewClient({
  baseUrl: "https://api.appstudio.io/api/v1",
  getToken: () => "Bearer ...",
  getTenantId: () => "tenant_abc",
  // Optional: per-request extra headers. Called with
  // { namespace: "link-previews", operation: "get" } and merged in.
  getRequestHeaders: ({ namespace, operation }) => ({}),
  // fetchImpl defaults to globalThis.fetch; timeoutMs defaults to 15 000.
});

const preview = await client.get("https://example.com/article");
// → { url: "https://example.com/article", title: "…", description: "…",
//     site_name: "Example", image_url: "https://api.appstudio.io/api/v1/link-previews/image?token=…" }

The request is GET {baseUrl}/link-previews?url=<encoded url> with Authorization: Bearer <token> and x-tenant-id. Any signed-in principal may call it; an anonymous caller gets AUTH_REQUIRED.

Errors

Every failure is a LinkPreviewError with a stable code, the HTTP status (0 when there was no response) and the error body as details.

| code | Status | When | | ------ | ------ | ---- | | VALIDATION | 400 | The URL is missing, malformed, not http(s), or too long | | AUTH_REQUIRED | 401 | No signed-in principal | | RATE_LIMITED | 429 | Too many previews requested; retryAfter holds the server's hint in seconds | | NETWORK | 0 | No HTTP answer: offline, DNS failure, or the 15 s timeout | | INTERNAL | other | Anything else, including 5xx |

A NETWORK failure or a 5xx is retried twice (after 250 ms and 750 ms); the request is a GET, so a repeat is harmless. A 4xx or 429 is never retried.

License

MIT