@oxyhq/contracts 0.5.0 → 0.6.0

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.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",