@oxyhq/contracts 0.5.0 → 0.7.0

package/dist/types/identity.d.ts

@@ -85,14 +85,6 @@ 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
@@ -100,6 +92,18 @@ export type SignedRecordType = 'identity' | 'profile' | 'reputation_attestation'
  * and the signer's DID — equal for self-issued records, `OXY_DID` for a
  * custodial provenance attestation). `issuedAt` is epoch milliseconds.
  *
+ * ## `type` — open by design
+ *
+ * `type` is an OPEN, non-empty string: it is the application-defined category of
+ * the record (e.g. Oxy's `identity`/`profile`/civic types, or `app.mention.*`'s
+ * `app_record`). The base envelope is app-agnostic, so it cannot enumerate every
+ * app's record categories — each app re-narrows `type` to its own closed set on
+ * the way INTO its own store (Oxy via {@link OxySignedRecordType}; an app via
+ * its own constant). Widening `type` from a closed enum to a string is
+ * canonical-bytes-safe: {@link signedRecordSigningInput} serializes `type` as the
+ * same JSON string either way, so every record already signed in production
+ * verifies byte-for-byte.
+ *
  * ## Versioning
  *
  * - **v1** is the original shape (`{version, type, subject, issuer, record,
@@ -121,7 +125,8 @@ export type SignedRecordType = 'identity' | 'profile' | 'reputation_attestation'
  */
 export interface SignedRecordEnvelope {
     version: 1 | 2;
-    type: SignedRecordType;
+    /** App-defined record category (open string); each store re-narrows it. */
+    type: string;
     subject: string;
     issuer: string;
     record: Record<string, unknown>;

package/dist/types/index.d.ts

@@ -18,7 +18,11 @@ 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, SignedRecordType, VerifiedDomain, DomainVerificationRequest, DomainVerificationInstructions, AuthMethodEntry, AuthMethodsResponse, ExportAttestation, ExportBundle, } from './identity';
+export type { VerificationMethod, DidService, DidDocument, SignedRecordEnvelope, VerifiedDomain, DomainVerificationRequest, DomainVerificationInstructions, AuthMethodEntry, AuthMethodsResponse, ExportAttestation, ExportBundle, } from './identity';
+export { oxySignedRecordTypeSchema, } from './oxyRecordTypes';
+export type { OxySignedRecordType, } from './oxyRecordTypes';
+export { chainHeadResponseSchema, logPageResponseSchema, } from './protocol';
+export type { LexiconRecord, ChainHeadResponse, LogPageResponse, } from './protocol';
 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';

package/dist/types/oxyRecordTypes.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Oxy-scoped signed-record types.
+ *
+ * The base `signedRecordEnvelopeSchema` (`./identity`) now treats `type` as an
+ * OPEN, non-empty string so ANY Oxy app may define its own record categories
+ * (e.g. `app.mention.*`'s `app_record`) on the shared envelope grammar. The Oxy
+ * identity/civic/node STORE, however, accepts ONLY the closed set of categories
+ * it knows how to verify and materialize — this module is that closed set.
+ *
+ * `oxySignedRecordTypeSchema` is the runtime gate the Oxy store re-narrows with
+ * (the API's `verifyEnvelope` rejects any `type` outside it; the Mongoose
+ * `SignedRecord.type` enum is derived from `.options`); `OxySignedRecordType` is
+ * the matching compile-time union the SDK identity/civic mixins type against.
+ *
+ * The signing input INCLUDES `type`, so this set is part of the signed bytes —
+ * a record cannot have its category swapped after signing.
+ *
+ * v1 only ever carried `identity` / `profile` (already in production); v2 added
+ * the civic record types (reputation attestations, real-life / peer validations,
+ * personhood vouches, verifiable credentials) and the user-node registration
+ * record. Every value here is an Oxy `app.oxy.*` (or legacy v1) category — an
+ * app's own `type` (e.g. `app_record`) is intentionally NOT in this set and is
+ * rejected by the Oxy store.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+export declare const oxySignedRecordTypeSchema: z.ZodEnum<["identity", "profile", "reputation_attestation", "real_life_attestation", "validation_verdict", "personhood_vouch", "credential", "node"]>;
+/**
+ * The closed set of record categories the Oxy identity/civic/node store accepts.
+ * The base envelope `type` is an open string; this is what the Oxy store
+ * re-narrows it to.
+ */
+export type OxySignedRecordType = z.infer<typeof oxySignedRecordTypeSchema>;

package/dist/types/protocol.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Generic "Oxy Protocol" record surface — the app-agnostic conventions every app
+ * follows to decentralize its own content on the shared signed-record substrate.
+ *
+ * The base `signedRecordEnvelopeSchema` (`./identity`) is the WIRE grammar: a
+ * signed envelope whose `type` is an open string and whose `record` is an opaque
+ * `Record<string, unknown>`. An app layers its own LEXICON on top of that
+ * grammar — a typed projection of the `record` payload, addressed by an
+ * AtProto-style `(collection, rkey)` key — WITHOUT forking the envelope schema.
+ *
+ * ## Recipe — defining an app lexicon record
+ *
+ * For each record kind an app wants to publish:
+ *
+ * 1. Define the `record` PAYLOAD schema as a `z.ZodType<XPayload>` (e.g.
+ *    `app.mention.feed.post` → `mentionPostRecordSchema: z.ZodType<MentionPost>`).
+ *    This validates ONLY the inner `record`, not the envelope.
+ * 2. Declare the `collection` NSID as a constant (e.g.
+ *    `export const MENTION_POST_COLLECTION = 'app.mention.feed.post'`).
+ * 3. Reuse the UNCHANGED {@link signedRecordEnvelopeSchema} for the envelope. The
+ *    base treats `record` as `z.record(z.unknown())`, so the app validates the
+ *    envelope with the base schema first, then parses `envelope.record` with its
+ *    own payload schema. {@link LexiconRecord} is the typed projection that pairs
+ *    the `(collection, rkey)` key with the parsed payload.
+ *
+ * The Oxy civic contracts (`./civic`) already follow this convention implicitly:
+ * each civic record (`real_life_attestation`, `personhood_vouch`, `credential`,
+ * …) ships a `record`-payload schema and is carried by the base envelope.
+ *
+ * ## Chain-wire shapes
+ *
+ * {@link ChainHeadResponse} and {@link LogPageResponse} are the shared response
+ * shapes every chain store exposes (Oxy's `GET /identity/records/:userId/chain/head`,
+ * `GET /identity/head/:userId`, `GET /identity/log/:userId`, and any app node's
+ * equivalents). They are defined ONCE here so producers and consumers (the API
+ * handlers, the SDK identity/nodes mixins, app nodes) cannot drift.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo, ESM-safe.
+ */
+import { z } from 'zod';
+import { type SignedRecordEnvelope } from './identity';
+/**
+ * The typed projection of a signed envelope's `record` payload, addressed by an
+ * AtProto-style `(collection, rkey)` key.
+ *
+ * - `collection` is the lexicon NSID (e.g. `app.mention.feed.post`) — the
+ *   envelope's `collection` field.
+ * - `rkey` is the record key within the collection (e.g. a post id) — the
+ *   envelope's `rkey` field.
+ * - `record` is the app-typed payload (`TPayload`) the app validated out of the
+ *   envelope's opaque `record`.
+ *
+ * This is a COMPILE-TIME convenience only: the wire shape is the base envelope.
+ * An app builds a `LexiconRecord<TPayload>` from a verified envelope by parsing
+ * `envelope.record` with its own `z.ZodType<TPayload>` payload schema.
+ */
+export interface LexiconRecord<TPayload> {
+    collection: string;
+    rkey: string;
+    record: TPayload;
+}
+/**
+ * The current head of a subject's per-subject hash chain.
+ *
+ * `headRecordId` is the content address of the latest record (or `null` when the
+ * subject has no chain yet); `seq` is its sequence number (`-1` when there is no
+ * chain — so the next record's coordinates are always `seq: head.seq + 1`,
+ * genesis `0`, and `prev: head.headRecordId`, genesis `null`); `recordCount` is
+ * the total number of records on the chain.
+ */
+export interface ChainHeadResponse {
+    headRecordId: string | null;
+    seq: number;
+    recordCount: number;
+}
+export declare const chainHeadResponseSchema: z.ZodType<ChainHeadResponse>;
+/**
+ * An ordered page of a subject's verified signed-record chain — the FULL
+ * envelopes (so a node or any verifier re-checks them independently). `count` is
+ * `records.length`, echoed for convenience.
+ */
+export interface LogPageResponse {
+    records: SignedRecordEnvelope[];
+    count: number;
+}
+export declare const logPageResponseSchema: z.ZodType<LogPageResponse>;

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.5.0",
+  "version": "0.7.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",