@oxyhq/contracts 0.3.0 → 0.5.0

package/dist/types/civic.d.ts

@@ -0,0 +1,338 @@
+/**
+ * Civic / Commons API contracts (Fase 1 — DNI + crypto-owned reputation).
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the public "DNI" card a Commons
+ * user shows (and others scan): the user's DID, display identity, trust tier,
+ * personhood status, verified domains, and credential badges — sealed with an
+ * Oxy custodial attestation so a scanner can verify it OFFLINE against the Oxy
+ * public key (the same `ES256K-DER-SHA256` scheme as the signed data export).
+ *
+ * The QR encodes ONLY the DID (`oxydni://card?did=…`) — never trust data — so a
+ * card cannot be spoofed by crafting a QR; the scanner resolves the signed card
+ * server-side and verifies the Oxy signature. The attestation is computed over
+ * the canonical-JSON of the `card` object, so a consumer re-canonicalizes the
+ * card it received and verifies `attestation.signature` against
+ * `attestation.publicKey` (which MUST be a current verification method of the
+ * Oxy DID).
+ *
+ * Explicit-`interface` exports (PublicCard, SignedPublicCard) follow the same
+ * node-resolution rationale as `UserNameResponse` / the identity contracts: a
+ * nested `z.infer<>` can degrade to `{}` under a consumer's
+ * `moduleResolution: "node"`, so the load-bearing shapes are declared as literal
+ * interfaces and the runtime schemas are annotated `z.ZodType<Interface>`.
+ *
+ * The `attestation` reuses the export-bundle `ExportAttestation` shape from
+ * `./identity` (mirrored, not duplicated): `{ issuer, publicKey, alg, signature,
+ * signedAt }`. It is `null` ONLY when the Oxy signing key is unconfigured (dev).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+import { type ExportAttestation } from './identity';
+/**
+ * The trust tier shown on the card. Mirrors the API's reputation `TRUST_TIERS`
+ * (lowest → highest, plus the punitive `restricted`). Declared as a literal
+ * union here (NOT imported from the API) so the contract package stays
+ * dependency-free while giving consumers an exhaustive type to render against.
+ */
+export type CardTrustTier = 'restricted' | 'new' | 'trusted' | 'high_trust' | 'verified';
+/**
+ * Personhood verification status. `unverified` for everyone in Fase 1; the
+ * web-of-trust pipeline (Fase 3) graduates users to `pending` / `verified`.
+ */
+export type PersonhoodStatus = 'unverified' | 'pending' | 'verified';
+/**
+ * The public, render-ready "DNI" card for a Commons user. Assembled server-side
+ * from the canonical account fields and signed by Oxy.
+ *
+ * - `name` is the canonical composed display name (`name.displayName`) — a
+ *   consumer renders it directly and NEVER recomposes it from `name.first` etc.
+ * - `username` / `avatarUrl` are OPTIONAL (omitted entirely for accounts that
+ *   have none) — `avatarUrl` is the public `cloud.oxy.so` URL when an avatar is
+ *   set. The server emits ONLY present keys so a consumer re-canonicalizing the
+ *   card it received derives byte-identical bytes for signature verification.
+ * - `trustTier` is the user's current reputation tier; `personhoodStatus` is
+ *   `unverified` for everyone in Fase 1 (Fase 3 graduates users) and
+ *   `credentialBadges` is `[]` until verifiable credentials land (Fase 4).
+ * - `issuedAt` is epoch milliseconds — part of the signed bytes (the attestation
+ *   covers the canonical-JSON of the whole card), so a scanner can detect a
+ *   stale/replayed card.
+ */
+export interface PublicCard {
+    did: string;
+    userId: string;
+    name: string;
+    username?: string;
+    avatarUrl?: string;
+    trustTier: CardTrustTier;
+    personhoodStatus: PersonhoodStatus;
+    verifiedDomains: string[];
+    credentialBadges: string[];
+    issuedAt: number;
+}
+export declare const publicCardSchema: z.ZodType<PublicCard>;
+/**
+ * A {@link PublicCard} sealed with an Oxy custodial attestation. The attestation
+ * is an `ES256K-DER-SHA256` signature over the canonical-JSON of `card` (the
+ * exact `ExportAttestation` shape reused from the signed data export). It is
+ * `null` ONLY when the Oxy signing key (`OXY_PRIVATE_KEY`/`OXY_PUBLIC_KEY`) is
+ * unconfigured (dev / pre-prod) — in production it is always present. A consumer
+ * MUST check `attestation !== null` and that `attestation.publicKey` is the Oxy
+ * custodial key before trusting the card.
+ */
+export interface SignedPublicCard {
+    card: PublicCard;
+    attestation: ExportAttestation | null;
+}
+export declare const signedPublicCardSchema: z.ZodType<SignedPublicCard>;
+/**
+ * The `record` payload of a `real_life_attestation` signed envelope. The
+ * COUNTERPARTY (B) signs this with their OWN key as a self-issued v2 record on
+ * THEIR chain (`subject === issuer === B.did`); the subject being attested (A)
+ * is referenced by `about` (A's DID). The server resolves `about` → A's account
+ * and awards A the HIGH-weight `real_life_attested` points, recording B as the
+ * attestor (so B can be slashed if A's action is later found fraudulent).
+ *
+ * - `context` is an opaque interaction id from the QR (`oxydni://attest?ctx=…`).
+ * - `nonce` is the single-use replay guard from the QR; `exp` is its expiry
+ *   (epoch ms) — both are part of the signed bytes.
+ * - `geohash` (optional) is a coarse co-location proof; `biometricOk` (optional)
+ *   signals B's device biometric gate fired before signing (a support signal,
+ *   never sufficient alone).
+ */
+export interface RealLifeAttestationRecord {
+    about: string;
+    context: string;
+    nonce: string;
+    exp: number;
+    geohash?: string;
+    biometricOk?: boolean;
+}
+export declare const realLifeAttestationRecordSchema: z.ZodType<RealLifeAttestationRecord>;
+/**
+ * The result of `POST /civic/attestations` on success: the stored attestation
+ * record id (B's envelope), the subject + attestor account ids, and the points
+ * awarded to the subject.
+ */
+export interface RealLifeAttestationResult {
+    accepted: true;
+    recordId: string;
+    subjectUserId: string;
+    attestorUserId: string;
+    points: number;
+}
+export declare const realLifeAttestationResultSchema: z.ZodType<RealLifeAttestationResult>;
+/** A juror's verdict on a validation request. */
+export type ValidationVerdict = 'valid' | 'invalid' | 'abstain';
+/** The lifecycle status of a validation request. */
+export type ValidationRequestStatus = 'pending' | 'quorum_met' | 'validated' | 'rejected' | 'expired';
+/**
+ * The `record` payload of a `validation_verdict` signed envelope — a juror's
+ * SELF-ISSUED verdict, bound to the request id + the canonical payload hash (so
+ * a verdict cannot be replayed onto a different request or an altered payload).
+ */
+export interface ValidationVerdictRecord {
+    requestId: string;
+    payloadHash: string;
+    verdict: ValidationVerdict;
+}
+export declare const validationVerdictRecordSchema: z.ZodType<ValidationVerdictRecord>;
+/** Request body for opening a validation request (`POST /civic/validations`). */
+export declare const validationOpenRequestSchema: z.ZodObject<{
+    subjectUserId: z.ZodString;
+    actionType: z.ZodString;
+    sourceActionId: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    highValue: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    subjectUserId: string;
+    actionType: string;
+    sourceActionId: string;
+    payload: Record<string, unknown>;
+    highValue?: boolean | undefined;
+}, {
+    subjectUserId: string;
+    actionType: string;
+    sourceActionId: string;
+    payload: Record<string, unknown>;
+    highValue?: boolean | undefined;
+}>;
+export type ValidationOpenRequest = z.infer<typeof validationOpenRequestSchema>;
+/** The result of opening a validation request (`POST /civic/validations`). */
+export interface ValidationOpenResult {
+    requestId: string;
+    selectedValidatorCount: number;
+    expiresAt: string;
+}
+export declare const validationOpenResultSchema: z.ZodType<ValidationOpenResult>;
+/**
+ * A pending validation request as shown in a juror's inbox. `payload` is the
+ * claim the juror inspects; `payloadHash` is what their verdict must bind to.
+ */
+export interface ValidationRequestSummary {
+    id: string;
+    subjectUserId: string;
+    actionType: string;
+    payload: Record<string, unknown>;
+    payloadHash: string;
+    status: ValidationRequestStatus;
+    highValue: boolean;
+    expiresAt: string;
+}
+export declare const validationRequestSummarySchema: z.ZodType<ValidationRequestSummary>;
+/** The result of casting a vote (`POST /civic/validations/:id/vote`). */
+export interface ValidationVoteResult {
+    recorded: true;
+    requestId: string;
+    verdict: ValidationVerdict;
+    status: ValidationRequestStatus;
+}
+export declare const validationVoteResultSchema: z.ZodType<ValidationVoteResult>;
+/**
+ * The `record` payload of a `personhood_vouch` signed envelope. The VOUCHER (B)
+ * signs this with their OWN key as a self-issued v2 record on THEIR chain
+ * (`subject === issuer === B.did`); the person being vouched for (A) is
+ * referenced by `about` (A's DID). The server resolves `about` → A's account,
+ * stakes the voucher, awards A the `personhood_vouched` points, and recomputes
+ * A's personhood.
+ *
+ * - `about` is A's DID (`did:web:oxy.so:u:<userId>`).
+ * - `context` (optional) is an opaque note from the vouching UI.
+ * - `stake` (optional) is the voucher's chosen stake; the server clamps it into
+ *   `[PERSONHOOD_VOUCH_MIN_STAKE, PERSONHOOD_VOUCH_MAX_STAKE]` and defaults it
+ *   when omitted. (Note: the wire field is `stake`, NOT `stakeAmount` — the
+ *   latter is the server's clamped, awarded value echoed in {@link VouchResult}.)
+ */
+export interface PersonhoodVouchRecord {
+    about: string;
+    context?: string;
+    stake?: number;
+}
+export declare const personhoodVouchRecordSchema: z.ZodType<PersonhoodVouchRecord>;
+/**
+ * The signal sub-scores behind a personhood score (audit / UI breakdown),
+ * mirroring the API `PersonhoodStatus` model's embedded `breakdown`.
+ */
+export interface PersonhoodBreakdown {
+    /** Saturated [0,1] vouch signal from the weighted vouch sum. */
+    vouchSignal: number;
+    /** Saturated [0,1] real-life-attestation signal. */
+    realLifeSignal: number;
+    /** 1 when the account is biometric-bound, else 0. */
+    biometricSignal: number;
+    /** Weighted blend of the three signals before the sybil penalty. */
+    evidence: number;
+    /** The [0,1] sybil penalty subtracted from the evidence. */
+    sybilPenalty: number;
+    /** True when the score came from the seed-verifier genesis short-circuit. */
+    seed: boolean;
+}
+export declare const personhoodBreakdownSchema: z.ZodType<PersonhoodBreakdown>;
+/**
+ * The public personhood status snapshot returned by
+ * `GET /civic/personhood/:userId` (and `POST /civic/personhood/:userId/recompute`).
+ * Mirrors the API `PersonhoodStatus` model's serialized response exactly — a
+ * cached, recomputable proof-of-personhood snapshot.
+ *
+ * - `score` is in `[0,1]`; `isRealPerson` is `score >= θ`.
+ * - `breakdown` is `null` ONLY on a public read of a user who has no status
+ *   document yet (the zeroed `unverified` shape); otherwise it is the full
+ *   {@link PersonhoodBreakdown}.
+ * - `updatedAt` is the ISO-8601 timestamp of the last recompute, or `null` when
+ *   no status document exists yet. (Distinct from the card's coarse
+ *   {@link PersonhoodStatus} enum, which is `'unverified' | 'pending' |
+ *   'verified'`.)
+ */
+export interface PersonhoodStatusResult {
+    userId: string;
+    score: number;
+    isRealPerson: boolean;
+    vouchCount: number;
+    realLifeCount: number;
+    biometricBound: boolean;
+    sybilPenalty: number;
+    breakdown: PersonhoodBreakdown | null;
+    updatedAt: string | null;
+}
+export declare const personhoodStatusResultSchema: z.ZodType<PersonhoodStatusResult>;
+/**
+ * The result of `POST /civic/personhood/vouch` on success: the stored vouch
+ * record id (the voucher's envelope), the subject + voucher account ids, the
+ * clamped stake the server recorded, and the points awarded to the subject.
+ */
+export interface VouchResult {
+    accepted: true;
+    recordId: string;
+    subjectUserId: string;
+    voucherUserId: string;
+    stakeAmount: number;
+    points: number;
+}
+export declare const vouchResultSchema: z.ZodType<VouchResult>;
+/** The lifecycle status of a stored verifiable credential. */
+export type CredentialStatus = 'active' | 'revoked' | 'expired';
+/**
+ * The `record` payload of a `credential` signed envelope — the W3C-VC-flavoured
+ * claim the issuer signs.
+ *
+ * - `about` is the HOLDER's DID (`did:web:oxy.so:u:<userId>`), i.e. the W3C
+ *   `credentialSubject.id`. (Named `about` to match the sibling civic records
+ *   and to avoid colliding with the envelope's own chain `subject` field.)
+ * - `types` are the VC type tags; `'VerifiableCredential'` MUST be present as the
+ *   base type, with at least one specific type (e.g. `'EmploymentCredential'`).
+ * - `claims` is the arbitrary, issuer-asserted claim set about the holder.
+ * - `expiresAt` (optional) is epoch milliseconds; absent = non-expiring. It is
+ *   part of the signed bytes, so a holder cannot extend a credential's validity.
+ */
+export interface CredentialRecord {
+    about: string;
+    types: string[];
+    claims: Record<string, unknown>;
+    expiresAt?: number;
+}
+export declare const credentialRecordSchema: z.ZodType<CredentialRecord>;
+/**
+ * The serialized verifiable credential as returned by the list + verify routes.
+ * `issuerUserId` is present only for user-issued credentials (absent for
+ * app/org-issued credentials signed by the Oxy custodial key). All timestamps
+ * are epoch milliseconds.
+ */
+export interface VerifiableCredentialResponse {
+    id: string;
+    recordId: string;
+    holderUserId: string;
+    holderDid: string;
+    issuerUserId?: string;
+    issuerDid: string;
+    types: string[];
+    claims: Record<string, unknown>;
+    status: CredentialStatus;
+    issuedAt: number;
+    expiresAt?: number;
+    revokedAt?: number;
+}
+export declare const verifiableCredentialResponseSchema: z.ZodType<VerifiableCredentialResponse>;
+/** The result of `POST /civic/credentials` on success. */
+export interface CredentialIssueResult {
+    accepted: true;
+    credential: VerifiableCredentialResponse;
+}
+export declare const credentialIssueResultSchema: z.ZodType<CredentialIssueResult>;
+/** The result of `GET /civic/credentials/:holderUserId` (list). */
+export interface CredentialListResult {
+    credentials: VerifiableCredentialResponse[];
+}
+export declare const credentialListResultSchema: z.ZodType<CredentialListResult>;
+/**
+ * The result of `GET /civic/credentials/by-record/:recordId/verify`. `valid` is
+ * `true` ONLY when the signature verifies against a CURRENT verification method
+ * of the issuer DID AND the credential is neither revoked nor expired. `reason`
+ * is a stable, machine-readable rejection code when `valid` is `false`.
+ * `credential` is `null` when no credential exists for the record id.
+ */
+export interface CredentialVerifyResult {
+    valid: boolean;
+    reason?: string;
+    credential: VerifiableCredentialResponse | null;
+}
+export declare const credentialVerifyResultSchema: z.ZodType<CredentialVerifyResult>;

package/dist/types/identity.d.ts

@@ -85,20 +85,55 @@ export interface DidDocument {
     service: DidService[];
 }
 export declare const didDocumentSchema: z.ZodType<DidDocument>;
+/**
+ * The category of a signed record. v1 only ever carried `identity` / `profile`
+ * (already in production); v2 widens the union with the civic record types
+ * (reputation attestations, real-life / peer validations, personhood vouches,
+ * verifiable credentials) and the user-node registration record. The signing
+ * input includes `type`, so this union is part of the signed bytes.
+ */
+export type SignedRecordType = 'identity' | 'profile' | 'reputation_attestation' | 'real_life_attestation' | 'validation_verdict' | 'personhood_vouch' | 'credential' | 'node';
 /**
  * A signed record envelope. `record` is the arbitrary payload; the signing
  * input is the canonical-JSON of every envelope field EXCEPT `publicKey` and
  * `signature`. `subject` and `issuer` are DIDs (the subject the record is about
  * and the signer's DID — equal for self-issued records, `OXY_DID` for a
  * custodial provenance attestation). `issuedAt` is epoch milliseconds.
+ *
+ * ## Versioning
+ *
+ * - **v1** is the original shape (`{version, type, subject, issuer, record,
+ *   issuedAt}` + `publicKey/alg/signature`). It carries NONE of the v2 chain
+ *   fields and remains accepted unchanged — every `identity`/`profile` record
+ *   already in production verifies byte-identically.
+ * - **v2** adds a per-subject hash-chain (an append-only "personal blockchain"
+ *   of a single signer, no consensus/mining). The four chain fields are part of
+ *   the signed bytes (so the chain cannot be forged):
+ *     - `seq` — strictly-increasing sequence number per subject.
+ *     - `prev` — the `recordId` (content address) of the previous record in this
+ *       subject's chain, or `null` at genesis.
+ *     - `collection` + `rkey` — an AtProto-style record key (e.g.
+ *       `collection: 'app.oxy.identity'`, `rkey: 'self'`) used for
+ *       materialization and last-writer-wins reconciliation.
+ *
+ * The chain fields are OPTIONAL on the interface so v1 envelopes (which omit
+ * them) still type-check; the schema enforces "present iff version === 2".
  */
 export interface SignedRecordEnvelope {
-    version: 1;
-    type: 'identity' | 'profile';
+    version: 1 | 2;
+    type: SignedRecordType;
     subject: string;
     issuer: string;
     record: Record<string, unknown>;
     issuedAt: number;
+    /** v2 only: strictly-increasing sequence number for this subject's chain. */
+    seq?: number;
+    /** v2 only: `recordId` of the previous record in the chain, `null` at genesis. */
+    prev?: string | null;
+    /** v2 only: AtProto-style collection namespace (e.g. `app.oxy.identity`). */
+    collection?: string;
+    /** v2 only: AtProto-style record key within the collection (e.g. `self`). */
+    rkey?: string;
     publicKey: string;
     alg: 'ES256K-DER-SHA256';
     signature: string;

package/dist/types/index.d.ts

@@ -18,4 +18,8 @@ export type { FedcmTokenPayload, } from './fedcmToken';
 export { recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, } from './recommendations';
 export type { RecommendationExcludeType, RecommendationBoost, RecommendationSignalWeights, RecommendationRequest, RecommendationCount, RecommendationItem, RecommendationResponse, AppEndorsementInput, AppInterestInput, AppUserSignalIngest, } from './recommendations';
 export { verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportBundleSchema, } from './identity';
-export type { VerificationMethod, DidService, DidDocument, SignedRecordEnvelope, VerifiedDomain, DomainVerificationRequest, DomainVerificationInstructions, AuthMethodEntry, AuthMethodsResponse, ExportAttestation, ExportBundle, } from './identity';
+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/sessionStatus.d.ts

@@ -151,6 +151,7 @@ export declare const sessionStatusSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     status: string;
     publicKey?: string | null | undefined;
+    userId?: string | null | undefined;
     expiresAt?: string | undefined;
     sessionId?: string | null | undefined;
     authorized?: boolean | undefined;
@@ -167,10 +168,10 @@ export declare const sessionStatusSchema: z.ZodObject<{
         websiteUrl?: string | undefined;
         developerName?: string | undefined;
     } | null | undefined;
-    userId?: string | null | undefined;
 }, {
     status: string;
     publicKey?: string | null | undefined;
+    userId?: string | null | undefined;
     expiresAt?: string | undefined;
     sessionId?: string | null | undefined;
     authorized?: boolean | undefined;
@@ -187,6 +188,5 @@ export declare const sessionStatusSchema: z.ZodObject<{
         websiteUrl?: string | undefined;
         developerName?: string | undefined;
     } | null | undefined;
-    userId?: string | null | undefined;
 }>;
 export type SessionStatusResponse = z.infer<typeof sessionStatusSchema>;