@oxyhq/contracts 0.4.0 → 0.6.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/dist/types/userResponse.d.ts

@@ -37,7 +37,10 @@ import { z } from 'zod';
  * - `first` / `last` default to `''` in Mongo, so they are optional on the wire.
  * - `full` is a Mongoose virtual — absent unless the query materialised
  *   virtuals or the serializer composed it.
- * - `displayName` is the required canonical app-facing display string.
+ * - `displayName` is the canonical app-facing display string when present.
+ *   It is OPTIONAL on the wire: the API still synthesizes a default today, but
+ *   the contract no longer guarantees it, so consumers fall back to a handle
+ *   (e.g. `getNormalizedUserHandle`) when it is absent.
  *
  * This is declared as an explicit `interface` rather than being inferred from
  * the runtime schema via `z.infer<typeof userNameSchema>`. Inferring it produced
@@ -47,7 +50,7 @@ import { z } from 'zod';
  * Under a consumer's `moduleResolution: "node"` (node10), that chain does not
  * always resolve, so `name.displayName` silently widened to `{}` and broke the
  * "render `name.displayName` directly" contract at the type level. An explicit
- * interface emits `displayName: string` literally and survives BOTH `node` and
+ * interface emits `displayName?: string` literally and survives BOTH `node` and
  * `bundler` resolution. The index signature preserves the passthrough behaviour
  * (additive name fields are tolerated without a coordinated contract bump).
  */
@@ -55,16 +58,18 @@ export interface UserNameResponse {
     first?: string;
     last?: string;
     full?: string;
-    /** Required canonical display string — render this directly. */
-    displayName: string;
+    /** Canonical display string when present — render this directly. */
+    displayName?: string;
     [key: string]: unknown;
 }
 export declare const userNameSchema: z.ZodType<UserNameResponse>;
 /**
  * The canonical user object emitted by `formatUserResponse`.
  *
- * `id` and `name.displayName` are guaranteed on formatted user DTOs. The rest
- * is forwarded from the user document and may be absent depending on the query's
+ * `id` is present on formatted user DTOs. `name.displayName` is OPTIONAL on the
+ * contract — the API still synthesizes a default today, but consumers must not
+ * assume it is present and should fall back to a handle when it is absent. The
+ * rest is forwarded from the user document and may be absent depending on the query's
  * `.select(...)`/`.lean()` projection. Both `id` and `_id` are accepted because
  * some raw-document responses carry `_id` instead of `id`; resolve the
  * identifier with {@link resolveUserId}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/contracts",
-  "version": "0.4.0",
+  "version": "0.6.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",