@oxyhq/contracts 0.5.0 → 0.7.0

package/dist/esm/identity.js

@@ -62,16 +62,9 @@ export const didDocumentSchema = z.object({
 export const signedRecordEnvelopeSchema = z
     .object({
     version: z.union([z.literal(1), z.literal(2)]),
-    type: z.enum([
-        'identity',
-        'profile',
-        'reputation_attestation',
-        'real_life_attestation',
-        'validation_verdict',
-        'personhood_vouch',
-        'credential',
-        'node',
-    ]),
+    // Open, app-defined category (see the `type` doc above). The Oxy STORE
+    // re-narrows to `oxySignedRecordTypeSchema`; an app to its own constant.
+    type: z.string().min(1),
     subject: z.string(),
     issuer: z.string(),
     record: z.record(z.unknown()),

package/dist/esm/index.js

@@ -28,6 +28,12 @@ export {
 verificationMethodSchema, didServiceSchema, didDocumentSchema, signedRecordEnvelopeSchema, verifiedDomainSchema, domainVerificationRequestSchema, domainVerificationInstructionsSchema, authMethodEntrySchema, authMethodsResponseSchema, exportAttestationSchema, exportBundleSchema, } from './identity.js';
 export { 
 // Schemas
+oxySignedRecordTypeSchema, } from './oxyRecordTypes.js';
+export { 
+// Schemas
+chainHeadResponseSchema, logPageResponseSchema, } from './protocol.js';
+export { 
+// Schemas
 publicCardSchema, signedPublicCardSchema, realLifeAttestationRecordSchema, realLifeAttestationResultSchema, validationVerdictRecordSchema, validationOpenRequestSchema, validationOpenResultSchema, validationRequestSummarySchema, validationVoteResultSchema, personhoodVouchRecordSchema, personhoodBreakdownSchema, personhoodStatusResultSchema, vouchResultSchema, 
 // Verifiable Credentials (Fase 4 — NEW)
 credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResultSchema, credentialListResultSchema, credentialVerifyResultSchema, } from './civic.js';

package/dist/esm/oxyRecordTypes.js

@@ -0,0 +1,37 @@
+/**
+ * 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 const oxySignedRecordTypeSchema = z.enum([
+    'identity',
+    'profile',
+    'reputation_attestation',
+    'real_life_attestation',
+    'validation_verdict',
+    'personhood_vouch',
+    'credential',
+    'node',
+]);

package/dist/esm/protocol.js

@@ -0,0 +1,50 @@
+/**
+ * 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 { signedRecordEnvelopeSchema } from './identity.js';
+export const chainHeadResponseSchema = z.object({
+    headRecordId: z.string().nullable(),
+    seq: z.number().int(),
+    recordCount: z.number().int().nonnegative(),
+});
+export const logPageResponseSchema = z.object({
+    records: z.array(signedRecordEnvelopeSchema),
+    count: z.number().int().nonnegative(),
+});

package/dist/esm/userResponse.js

@@ -37,14 +37,16 @@ export const userNameSchema = z
     first: z.string().optional(),
     last: z.string().optional(),
     full: z.string().optional(),
-    displayName: z.string(),
+    displayName: z.string().optional(),
 })
     .passthrough();
 /**
  * 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}.