@oxyhq/contracts 0.4.0 → 0.5.0

package/dist/types/index.d.ts

@@ -21,3 +21,5 @@ export { verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRe
 export type { VerificationMethod, DidService, DidDocument, SignedRecordEnvelope, SignedRecordType, VerifiedDomain, DomainVerificationRequest, DomainVerificationInstructions, AuthMethodEntry, AuthMethodsResponse, ExportAttestation, ExportBundle, } from './identity';
 export { publicCardSchema, signedPublicCardSchema, realLifeAttestationRecordSchema, realLifeAttestationResultSchema, validationVerdictRecordSchema, validationOpenRequestSchema, validationOpenResultSchema, validationRequestSummarySchema, validationVoteResultSchema, personhoodVouchRecordSchema, personhoodBreakdownSchema, personhoodStatusResultSchema, vouchResultSchema, credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResultSchema, credentialListResultSchema, credentialVerifyResultSchema, } from './civic';
 export type { CardTrustTier, PersonhoodStatus, PublicCard, SignedPublicCard, RealLifeAttestationRecord, RealLifeAttestationResult, ValidationVerdict, ValidationRequestStatus, ValidationVerdictRecord, ValidationOpenRequest, ValidationOpenResult, ValidationRequestSummary, ValidationVoteResult, PersonhoodVouchRecord, PersonhoodBreakdown, PersonhoodStatusResult, VouchResult, CredentialStatus, CredentialRecord, VerifiableCredentialResponse, CredentialIssueResult, CredentialListResult, CredentialVerifyResult, } from './civic';
+export { linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links';
+export type { LinkPreviewStatus, LinkPreview, LinkPreviewBatchRequest, LinkPreviewBatchResponse, } from './links';

package/dist/types/links.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Link-preview / unfurl API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of Oxy's link-preview ("unfurl")
+ * resolution surface: the single `GET` lookup and the `POST` batch lookup that
+ * every app calls through the SDK so apps stop duplicating their own
+ * link-metadata fetching. The API validates its OUTPUT against these schemas;
+ * every consumer (`@oxyhq/core`'s link mixin and the apps that call it)
+ * validates its INPUT against the same definitions, so producer and consumers
+ * cannot drift.
+ *
+ * Design anchors:
+ *  - Oxy owns resolution. The `image` (and `favicon`) URLs a preview carries are
+ *    re-hosted on Oxy media (`cloud.oxy.so/<fileId>`), never raw remote URLs —
+ *    apps render them directly with no per-app proxy.
+ *  - Resolution is best-effort and asynchronous. A preview is `'resolved'` once
+ *    metadata is materialised, `'pending'` while a first-seen URL is being
+ *    fetched in the background, or `'empty'` when the target yielded no usable
+ *    metadata. `resolvedAt` (ISO datetime) is present only once `'resolved'`.
+ *  - The batch response is keyed by the REQUESTED url (the exact string the
+ *    caller sent), not the canonical/final URL, so a caller can always look its
+ *    own input back up; the canonical URL lives on `LinkPreview.url`.
+ *
+ * The `LinkPreview` / `LinkPreviewBatchResponse` exports are declared as explicit
+ * `interface`s (with their runtime schemas annotated `z.ZodType<Interface>`),
+ * following the same rationale as `UserNameResponse` in `./userResponse`: a
+ * `z.infer<>` of a nested-object schema can degrade to `{}` under a consumer's
+ * `moduleResolution: "node"` (node10) resolution. A literal interface emits the
+ * field types verbatim in the `.d.ts` and survives BOTH `node` and `bundler`
+ * resolution. The flat batch-request schema (no nested-object hazard) is inferred
+ * via `z.infer<>`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Resolution state of a {@link LinkPreview}.
+ *
+ * - `resolved` — metadata materialised; `resolvedAt` is present.
+ * - `pending`  — a first-seen URL is being fetched in the background; metadata
+ *   fields and `resolvedAt` may be absent. The caller may re-fetch shortly.
+ * - `empty`    — the target yielded no usable metadata (e.g. a bare binary, a
+ *   404, or an opted-out host); the negative result is cached.
+ */
+export type LinkPreviewStatus = 'resolved' | 'pending' | 'empty';
+/**
+ * A single resolved (or in-flight) link preview.
+ *
+ * `url` is the canonical / final resolved URL (after redirects). The optional
+ * metadata fields are present on a best-effort basis once `status` is
+ * `'resolved'`. `image` and `favicon` are absolute Oxy-hosted
+ * (`cloud.oxy.so/<fileId>`) URLs — render them directly, never proxy them.
+ */
+export interface LinkPreview {
+    /** Canonical / final resolved URL (after following redirects). */
+    url: string;
+    status: LinkPreviewStatus;
+    title?: string;
+    description?: string;
+    /** Absolute Oxy-hosted (`cloud.oxy.so`) image URL. */
+    image?: string;
+    siteName?: string;
+    /** Absolute Oxy-hosted (`cloud.oxy.so`) favicon URL. */
+    favicon?: string;
+    /** ISO 8601 datetime of resolution; absent while `status` is `'pending'`. */
+    resolvedAt?: string;
+}
+export declare const linkPreviewSchema: z.ZodType<LinkPreview>;
+/**
+ * Request body for the batch unfurl endpoint. Between 1 and 50 URLs per call;
+ * the server resolves each (returning a `'pending'` placeholder for any URL it
+ * has not seen before and is fetching in the background).
+ */
+export declare const linkPreviewBatchRequestSchema: z.ZodObject<{
+    urls: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    urls: string[];
+}, {
+    urls: string[];
+}>;
+export type LinkPreviewBatchRequest = z.infer<typeof linkPreviewBatchRequestSchema>;
+/**
+ * Batch unfurl response. `data` is keyed by the REQUESTED url (the exact string
+ * the caller sent in `urls`), so a caller can always look its own input back up;
+ * the canonical/final URL is on each {@link LinkPreview}'s `url` field.
+ */
+export interface LinkPreviewBatchResponse {
+    data: Record<string, LinkPreview>;
+}
+export declare const linkPreviewBatchResponseSchema: z.ZodType<LinkPreviewBatchResponse>;
+/**
+ * Wire shape of the single-URL unfurl lookup (`GET`) — a bare
+ * {@link LinkPreview}.
+ */
+export declare const linkPreviewResponseSchema: z.ZodType<LinkPreview, z.ZodTypeDef, LinkPreview>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/contracts",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",