@oxyhq/contracts 0.1.0

package/dist/cjs/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * @oxyhq/contracts — single source of truth for API request/response contracts.
+ *
+ * Zod schemas plus their inferred types, shared by the backend (`@oxyhq/api`)
+ * and the client SDKs (`@oxyhq/core`, `@oxyhq/auth`, `@oxyhq/services`). The
+ * producer validates its output and every consumer validates its input against
+ * exactly the same definitions, so the wire shape cannot drift.
+ *
+ * Platform-agnostic — zod is the only runtime dependency. No react/react-native/
+ * expo, no `require()` in the ESM build.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeParseContract = exports.resolveUserId = exports.deviceSessionsResponseSchema = exports.deviceSessionAccountSchema = exports.currentUserResponseSchema = exports.refreshAllResponseSchema = exports.refreshAllAccountSchema = exports.userResponseSchema = exports.userNameSchema = void 0;
+var userResponse_1 = require("./userResponse");
+// Schemas
+Object.defineProperty(exports, "userNameSchema", { enumerable: true, get: function () { return userResponse_1.userNameSchema; } });
+Object.defineProperty(exports, "userResponseSchema", { enumerable: true, get: function () { return userResponse_1.userResponseSchema; } });
+Object.defineProperty(exports, "refreshAllAccountSchema", { enumerable: true, get: function () { return userResponse_1.refreshAllAccountSchema; } });
+Object.defineProperty(exports, "refreshAllResponseSchema", { enumerable: true, get: function () { return userResponse_1.refreshAllResponseSchema; } });
+Object.defineProperty(exports, "currentUserResponseSchema", { enumerable: true, get: function () { return userResponse_1.currentUserResponseSchema; } });
+Object.defineProperty(exports, "deviceSessionAccountSchema", { enumerable: true, get: function () { return userResponse_1.deviceSessionAccountSchema; } });
+Object.defineProperty(exports, "deviceSessionsResponseSchema", { enumerable: true, get: function () { return userResponse_1.deviceSessionsResponseSchema; } });
+// Helpers
+Object.defineProperty(exports, "resolveUserId", { enumerable: true, get: function () { return userResponse_1.resolveUserId; } });
+Object.defineProperty(exports, "safeParseContract", { enumerable: true, get: function () { return userResponse_1.safeParseContract; } });

package/dist/cjs/userResponse.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Canonical API user-response contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of every user object the API emits
+ * and every consumer (the auth app, services, accounts) parses. The API
+ * validates its OUTPUT against these schemas; web/RN consumers validate their
+ * INPUT against the same schemas. Because there is exactly one definition, the
+ * producer and the consumers cannot drift — the class of bugs that motivated
+ * this module (the auth app's local Zod schema requiring `name` to be a plain
+ * string, dropping every account that had a structured name) is impossible.
+ *
+ * This package (`@oxyhq/contracts`) is the dedicated, zero-dependency home for
+ * these contracts so the backend (`@oxyhq/api`) and the client SDKs
+ * (`@oxyhq/core`, `@oxyhq/auth`, `@oxyhq/services`) can all depend on it without
+ * the backend having to depend on a client SDK to obtain its schemas.
+ *
+ * Faithful to the producers:
+ *  - `packages/api/src/utils/userTransform.ts` `formatUserResponse` — the
+ *    canonical serialization used by `/auth/refresh-all`, device sessions, etc.
+ *    Emits `id` (NOT `_id`), forwards `username` verbatim (may be absent), and
+ *    emits `name` as the structured `{ first, last, full }` subdocument.
+ *  - `packages/api/src/models/User.ts` — `NameSchema` (`first`/`last` default
+ *    `''`; `full` is a Mongoose VIRTUAL) and the `displayName` virtual. Because
+ *    virtuals are only present when a query uses `.lean({ virtuals: true })` (or
+ *    a hydrated doc), `name.full` and `displayName` MUST be treated as OPTIONAL.
+ *  - The `/auth/refresh-all` handler in `packages/api/src/routes/auth.ts`, whose
+ *    per-slot `authuser` is `number | null` (null = legacy un-suffixed `oxy_rt`
+ *    cookie slot).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deviceSessionsResponseSchema = exports.deviceSessionAccountSchema = exports.currentUserResponseSchema = exports.refreshAllResponseSchema = exports.refreshAllAccountSchema = exports.userResponseSchema = exports.userNameSchema = void 0;
+exports.resolveUserId = resolveUserId;
+exports.safeParseContract = safeParseContract;
+const zod_1 = require("zod");
+/**
+ * Structured human name subdocument. Mirrors `User.name` (`NameSchema`).
+ *
+ * - `first` / `last` default to `''` in Mongo, so they are optional on the wire.
+ * - `full` is a Mongoose virtual — ABSENT unless the query materialised virtuals.
+ *
+ * `.passthrough()` is intentional: it tolerates additive name fields without a
+ * coordinated contract bump, while the three known keys stay strongly typed.
+ */
+exports.userNameSchema = zod_1.z
+    .object({
+    first: zod_1.z.string().optional(),
+    last: zod_1.z.string().optional(),
+    full: zod_1.z.string().optional(),
+})
+    .passthrough();
+/**
+ * The canonical user object emitted by `formatUserResponse`.
+ *
+ * Only `id` is guaranteed present (it is the early-return guard in
+ * `formatUserResponse`). Every other field is forwarded verbatim from the user
+ * document and may be absent depending on the query's `.select(...)`/`.lean()`
+ * projection — so all are optional/nullable to match reality. Both `id` and
+ * `_id` are accepted because RAW-document responses (e.g. `GET /users/me`,
+ * which does NOT pass through `formatUserResponse`) carry `_id` instead of `id`;
+ * resolve the identifier with {@link resolveUserId}.
+ *
+ * `.passthrough()` keeps the large tail of profile fields
+ * (`privacySettings`, `locations`, `links`, `linksMetadata`, `bio`,
+ * `description`, `language`, `verified`, timestamps, …) available to callers
+ * that need them without enumerating every nested shape here — the load-bearing
+ * identity/display fields are the ones we pin precisely.
+ */
+exports.userResponseSchema = zod_1.z
+    .object({
+    /** MongoDB ObjectId as a string. Present on `formatUserResponse` output. */
+    id: zod_1.z.string().optional(),
+    /** Raw-document id (e.g. `GET /users/me`). Present when `id` is not. */
+    _id: zod_1.z.string().optional(),
+    publicKey: zod_1.z.string().optional(),
+    username: zod_1.z.string().optional(),
+    email: zod_1.z.string().optional(),
+    /** Avatar file id (string) or null. */
+    avatar: zod_1.z.string().nullable().optional(),
+    /** Named Bloom color preset (e.g. `"blue"`) or null. */
+    color: zod_1.z.string().nullable().optional(),
+    name: exports.userNameSchema.optional(),
+    /** Server `displayName` virtual (`username || truncatedKey`). Optional. */
+    displayName: zod_1.z.string().optional(),
+    verified: zod_1.z.boolean().optional(),
+    language: zod_1.z.string().optional(),
+})
+    .passthrough();
+/**
+ * Resolve the canonical user id from a {@link UserResponse}, accepting either
+ * the `formatUserResponse` `id` field or the raw-document `_id` field.
+ */
+function resolveUserId(user) {
+    return user.id ?? user._id;
+}
+/**
+ * One rotated account entry from `POST /auth/refresh-all`.
+ *
+ * `authuser` is the device-local slot index (`0..N-1`). The server emits
+ * `authuser: null` for the legacy un-suffixed `oxy_rt` cookie slot — accept null
+ * so a browser holding only a legacy cookie is NOT dropped from the account
+ * chooser. `user` is the canonical {@link userResponseSchema} shape (the handler
+ * projects a whitelist and runs it through `formatUserResponse`).
+ */
+exports.refreshAllAccountSchema = zod_1.z.object({
+    authuser: zod_1.z.number().int().nonnegative().nullable(),
+    accessToken: zod_1.z.string(),
+    expiresAt: zod_1.z.string(),
+    sessionId: zod_1.z.string(),
+    user: exports.userResponseSchema,
+});
+/**
+ * Wire shape of `POST /auth/refresh-all`: every valid device-local account,
+ * sorted by `authuser` ascending. An empty `accounts` array means "no signed-in
+ * accounts on this device" — the IdP must show the sign-in form. A 404 means the
+ * endpoint is not deployed and the caller falls back to single-account
+ * `/auth/refresh`.
+ */
+exports.refreshAllResponseSchema = zod_1.z.object({
+    accounts: zod_1.z.array(exports.refreshAllAccountSchema),
+});
+/**
+ * Wire shape of `GET /users/me` — the API success envelope (`{ data: <user> }`)
+ * wrapping the RAW Mongo user document. It does NOT pass through
+ * `formatUserResponse`, so the id field is `_id` (resolve via
+ * {@link resolveUserId}) and virtuals (`name.full`, `displayName`) may be
+ * present when the query materialised them.
+ */
+exports.currentUserResponseSchema = zod_1.z.object({
+    data: exports.userResponseSchema,
+});
+/**
+ * One entry of `GET /session/device/sessions/:sessionId` — the deduplicated
+ * accounts signed in on this physical device (one per user, most recent
+ * session). Backs the multi-account chooser. The embedded user mirrors
+ * `formatUserResponse`; it is nullable on slots that lost their user document.
+ */
+exports.deviceSessionAccountSchema = zod_1.z.object({
+    sessionId: zod_1.z.string(),
+    isCurrent: zod_1.z.boolean().optional(),
+    user: exports.userResponseSchema.nullable().optional(),
+});
+/** Wire shape of `GET /session/device/sessions/:sessionId` (an array). */
+exports.deviceSessionsResponseSchema = zod_1.z.array(exports.deviceSessionAccountSchema);
+/**
+ * Safely parse a value against a contract schema. Returns the parsed (typed)
+ * value, or `null` when validation fails — the same ergonomics the auth app's
+ * local `safeParse` provided, now sourced from the contracts package so the
+ * parse helper and the schemas live together.
+ */
+function safeParseContract(schema, data) {
+    const result = schema.safeParse(data);
+    return result.success ? result.data : null;
+}

package/dist/esm/index.js

@@ -0,0 +1,16 @@
+/**
+ * @oxyhq/contracts — single source of truth for API request/response contracts.
+ *
+ * Zod schemas plus their inferred types, shared by the backend (`@oxyhq/api`)
+ * and the client SDKs (`@oxyhq/core`, `@oxyhq/auth`, `@oxyhq/services`). The
+ * producer validates its output and every consumer validates its input against
+ * exactly the same definitions, so the wire shape cannot drift.
+ *
+ * Platform-agnostic — zod is the only runtime dependency. No react/react-native/
+ * expo, no `require()` in the ESM build.
+ */
+export { 
+// Schemas
+userNameSchema, userResponseSchema, refreshAllAccountSchema, refreshAllResponseSchema, currentUserResponseSchema, deviceSessionAccountSchema, deviceSessionsResponseSchema, 
+// Helpers
+resolveUserId, safeParseContract, } from './userResponse.js';

package/dist/esm/userResponse.js

@@ -0,0 +1,152 @@
+/**
+ * Canonical API user-response contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of every user object the API emits
+ * and every consumer (the auth app, services, accounts) parses. The API
+ * validates its OUTPUT against these schemas; web/RN consumers validate their
+ * INPUT against the same schemas. Because there is exactly one definition, the
+ * producer and the consumers cannot drift — the class of bugs that motivated
+ * this module (the auth app's local Zod schema requiring `name` to be a plain
+ * string, dropping every account that had a structured name) is impossible.
+ *
+ * This package (`@oxyhq/contracts`) is the dedicated, zero-dependency home for
+ * these contracts so the backend (`@oxyhq/api`) and the client SDKs
+ * (`@oxyhq/core`, `@oxyhq/auth`, `@oxyhq/services`) can all depend on it without
+ * the backend having to depend on a client SDK to obtain its schemas.
+ *
+ * Faithful to the producers:
+ *  - `packages/api/src/utils/userTransform.ts` `formatUserResponse` — the
+ *    canonical serialization used by `/auth/refresh-all`, device sessions, etc.
+ *    Emits `id` (NOT `_id`), forwards `username` verbatim (may be absent), and
+ *    emits `name` as the structured `{ first, last, full }` subdocument.
+ *  - `packages/api/src/models/User.ts` — `NameSchema` (`first`/`last` default
+ *    `''`; `full` is a Mongoose VIRTUAL) and the `displayName` virtual. Because
+ *    virtuals are only present when a query uses `.lean({ virtuals: true })` (or
+ *    a hydrated doc), `name.full` and `displayName` MUST be treated as OPTIONAL.
+ *  - The `/auth/refresh-all` handler in `packages/api/src/routes/auth.ts`, whose
+ *    per-slot `authuser` is `number | null` (null = legacy un-suffixed `oxy_rt`
+ *    cookie slot).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Structured human name subdocument. Mirrors `User.name` (`NameSchema`).
+ *
+ * - `first` / `last` default to `''` in Mongo, so they are optional on the wire.
+ * - `full` is a Mongoose virtual — ABSENT unless the query materialised virtuals.
+ *
+ * `.passthrough()` is intentional: it tolerates additive name fields without a
+ * coordinated contract bump, while the three known keys stay strongly typed.
+ */
+export const userNameSchema = z
+    .object({
+    first: z.string().optional(),
+    last: z.string().optional(),
+    full: z.string().optional(),
+})
+    .passthrough();
+/**
+ * The canonical user object emitted by `formatUserResponse`.
+ *
+ * Only `id` is guaranteed present (it is the early-return guard in
+ * `formatUserResponse`). Every other field is forwarded verbatim from the user
+ * document and may be absent depending on the query's `.select(...)`/`.lean()`
+ * projection — so all are optional/nullable to match reality. Both `id` and
+ * `_id` are accepted because RAW-document responses (e.g. `GET /users/me`,
+ * which does NOT pass through `formatUserResponse`) carry `_id` instead of `id`;
+ * resolve the identifier with {@link resolveUserId}.
+ *
+ * `.passthrough()` keeps the large tail of profile fields
+ * (`privacySettings`, `locations`, `links`, `linksMetadata`, `bio`,
+ * `description`, `language`, `verified`, timestamps, …) available to callers
+ * that need them without enumerating every nested shape here — the load-bearing
+ * identity/display fields are the ones we pin precisely.
+ */
+export const userResponseSchema = z
+    .object({
+    /** MongoDB ObjectId as a string. Present on `formatUserResponse` output. */
+    id: z.string().optional(),
+    /** Raw-document id (e.g. `GET /users/me`). Present when `id` is not. */
+    _id: z.string().optional(),
+    publicKey: z.string().optional(),
+    username: z.string().optional(),
+    email: z.string().optional(),
+    /** Avatar file id (string) or null. */
+    avatar: z.string().nullable().optional(),
+    /** Named Bloom color preset (e.g. `"blue"`) or null. */
+    color: z.string().nullable().optional(),
+    name: userNameSchema.optional(),
+    /** Server `displayName` virtual (`username || truncatedKey`). Optional. */
+    displayName: z.string().optional(),
+    verified: z.boolean().optional(),
+    language: z.string().optional(),
+})
+    .passthrough();
+/**
+ * Resolve the canonical user id from a {@link UserResponse}, accepting either
+ * the `formatUserResponse` `id` field or the raw-document `_id` field.
+ */
+export function resolveUserId(user) {
+    return user.id ?? user._id;
+}
+/**
+ * One rotated account entry from `POST /auth/refresh-all`.
+ *
+ * `authuser` is the device-local slot index (`0..N-1`). The server emits
+ * `authuser: null` for the legacy un-suffixed `oxy_rt` cookie slot — accept null
+ * so a browser holding only a legacy cookie is NOT dropped from the account
+ * chooser. `user` is the canonical {@link userResponseSchema} shape (the handler
+ * projects a whitelist and runs it through `formatUserResponse`).
+ */
+export const refreshAllAccountSchema = z.object({
+    authuser: z.number().int().nonnegative().nullable(),
+    accessToken: z.string(),
+    expiresAt: z.string(),
+    sessionId: z.string(),
+    user: userResponseSchema,
+});
+/**
+ * Wire shape of `POST /auth/refresh-all`: every valid device-local account,
+ * sorted by `authuser` ascending. An empty `accounts` array means "no signed-in
+ * accounts on this device" — the IdP must show the sign-in form. A 404 means the
+ * endpoint is not deployed and the caller falls back to single-account
+ * `/auth/refresh`.
+ */
+export const refreshAllResponseSchema = z.object({
+    accounts: z.array(refreshAllAccountSchema),
+});
+/**
+ * Wire shape of `GET /users/me` — the API success envelope (`{ data: <user> }`)
+ * wrapping the RAW Mongo user document. It does NOT pass through
+ * `formatUserResponse`, so the id field is `_id` (resolve via
+ * {@link resolveUserId}) and virtuals (`name.full`, `displayName`) may be
+ * present when the query materialised them.
+ */
+export const currentUserResponseSchema = z.object({
+    data: userResponseSchema,
+});
+/**
+ * One entry of `GET /session/device/sessions/:sessionId` — the deduplicated
+ * accounts signed in on this physical device (one per user, most recent
+ * session). Backs the multi-account chooser. The embedded user mirrors
+ * `formatUserResponse`; it is nullable on slots that lost their user document.
+ */
+export const deviceSessionAccountSchema = z.object({
+    sessionId: z.string(),
+    isCurrent: z.boolean().optional(),
+    user: userResponseSchema.nullable().optional(),
+});
+/** Wire shape of `GET /session/device/sessions/:sessionId` (an array). */
+export const deviceSessionsResponseSchema = z.array(deviceSessionAccountSchema);
+/**
+ * Safely parse a value against a contract schema. Returns the parsed (typed)
+ * value, or `null` when validation fails — the same ergonomics the auth app's
+ * local `safeParse` provided, now sourced from the contracts package so the
+ * parse helper and the schemas live together.
+ */
+export function safeParseContract(schema, data) {
+    const result = schema.safeParse(data);
+    return result.success ? result.data : null;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @oxyhq/contracts — single source of truth for API request/response contracts.
+ *
+ * Zod schemas plus their inferred types, shared by the backend (`@oxyhq/api`)
+ * and the client SDKs (`@oxyhq/core`, `@oxyhq/auth`, `@oxyhq/services`). The
+ * producer validates its output and every consumer validates its input against
+ * exactly the same definitions, so the wire shape cannot drift.
+ *
+ * Platform-agnostic — zod is the only runtime dependency. No react/react-native/
+ * expo, no `require()` in the ESM build.
+ */
+export { userNameSchema, userResponseSchema, refreshAllAccountSchema, refreshAllResponseSchema, currentUserResponseSchema, deviceSessionAccountSchema, deviceSessionsResponseSchema, resolveUserId, safeParseContract, } from './userResponse';
+export type { UserNameResponse, UserResponse, RefreshAllAccountResponse, RefreshAllResponseContract, CurrentUserResponseContract, DeviceSessionAccountResponse, DeviceSessionsResponseContract, } from './userResponse';