@oxy.so/contracts 1.0.0

package/dist/esm/updates.js

@@ -0,0 +1,249 @@
+/**
+ * Oxy Updates (self-hosted expo-updates protocol) — publish/admin API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the AUTHENTICATED publish/admin
+ * surface that the `oxy-ship` CLI and the console Updates tab call. The PUBLIC
+ * manifest endpoint (`GET /updates/v1/apps/:clientId/manifest`) speaks the
+ * expo-updates v1 protocol verbatim (multipart/mixed, signed) and is therefore
+ * NOT modelled here — its shape is dictated by the Expo spec, not by us.
+ *
+ * The API validates its OUTPUT against these schemas; every consumer (the ship
+ * CLI, the console hook) validates its INPUT against the same definitions, so
+ * producer and consumers cannot drift.
+ *
+ * Domain model (mirrors the Mongoose models in `@oxy.so/api`):
+ *  - A `channel` (e.g. `production`, `preview`, `pr-123`) is a named release
+ *    track for one application.
+ *  - An `update` is one published bundle for a single `(channel, runtimeVersion,
+ *    platform)`. Its `updateId` is a UUIDv4 (the client parses it as a UUID).
+ *    The HEAD of a track is the newest `published` update for that tuple.
+ *  - An `asset` is content-addressed by its `sha256`; assets are shared across
+ *    updates and applications (an unchanged JS bundle is uploaded once).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/* -------------------------------------------------------------------------- */
+/*  Shared primitives                                                         */
+/* -------------------------------------------------------------------------- */
+/** The two platforms the expo-updates protocol addresses. */
+export const updatePlatformSchema = z.enum(['ios', 'android']);
+/** Lifecycle of a single published update row. */
+export const updateStatusSchema = z.enum(['published', 'superseded', 'rolled_back']);
+/** Upload lifecycle of a content-addressed asset. */
+export const updateAssetStatusSchema = z.enum(['pending', 'uploaded']);
+/** Lowercase-hex SHA-256 content hash (64 hex chars). */
+export const sha256HexSchema = z
+    .string()
+    .regex(/^[a-f0-9]{64}$/, 'sha256 must be 64 lowercase hex characters');
+/**
+ * A channel name. Constrained to a URL/path-safe slug so it can appear in the
+ * `expo-channel-name` header and be used CI-friendly for `pr-<n>` tracks. No
+ * colon (BullMQ/id safety) and no slash (path safety).
+ */
+export const channelNameSchema = z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/, 'channel name must be a URL-safe slug');
+/** A runtime version string (expo-updates `runtimeVersion`, e.g. an appVersion). */
+export const runtimeVersionSchema = z.string().min(1).max(255);
+/** A rollout percentage: 0 rolls out to nobody, 100 to everybody. */
+export const rolloutPercentSchema = z.number().int().min(0).max(100);
+/* -------------------------------------------------------------------------- */
+/*  Assets: init + complete                                                   */
+/* -------------------------------------------------------------------------- */
+/**
+ * One asset the client intends to upload as part of an update. `sha256` is the
+ * content hash (dedup key); `contentType` and `size` describe the object the
+ * server will accept at the presigned URL.
+ */
+export const assetInitItemSchema = z.object({
+    sha256: sha256HexSchema,
+    contentType: z.string().min(1).max(255),
+    size: z.number().int().positive(),
+});
+/**
+ * `POST /updates/v1/assets/init` request. Declares the full asset set of an
+ * update; the server replies with a presigned PUT for every asset it does NOT
+ * already hold (content-addressed dedup — unchanged assets are never re-uploaded).
+ */
+export const assetInitRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    assets: z.array(assetInitItemSchema).min(1).max(2000),
+});
+/** One presigned upload the client must PUT its bytes to before completing. */
+export const assetUploadTicketSchema = z.object({
+    sha256: sha256HexSchema,
+    /** Presigned S3 PUT URL. The client PUTs the exact bytes here. */
+    uploadUrl: z.string(),
+    /** The S3 key the object will live at (`public/updates/assets/<sha256>`). */
+    storageKey: z.string(),
+    /** The Content-Type the presigned URL was signed for; echo it on the PUT. */
+    contentType: z.string(),
+    /**
+     * The Cache-Control the presigned URL was signed for; the client MUST send it
+     * verbatim on the PUT so the SigV4 signature matches and the stored object
+     * carries the long immutable cache header (assets are content-addressed).
+     */
+    cacheControl: z.string(),
+    /** Base64 SHA-256 value required in the presigned PUT's checksum header. */
+    checksumSHA256: z.string(),
+});
+/**
+ * `POST /updates/v1/assets/init` response. `missing` holds a presigned upload
+ * for each asset the server does not yet have; `existing` lists the sha256s it
+ * already holds (the client skips those).
+ */
+export const assetInitResponseSchema = z.object({
+    missing: z.array(assetUploadTicketSchema),
+    existing: z.array(sha256HexSchema),
+});
+/**
+ * `POST /updates/v1/assets/complete` request. Sent after the client has PUT
+ * every `missing` asset. The server HEADs each object and flips it to
+ * `uploaded`; an object that is absent or size-mismatched is rejected.
+ */
+export const assetCompleteRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    sha256s: z.array(sha256HexSchema).min(1).max(2000),
+});
+/** Per-asset verification outcome from `assets/complete`. */
+export const assetCompleteResultItemSchema = z.object({
+    sha256: sha256HexSchema,
+    status: updateAssetStatusSchema,
+    size: z.number().int().nonnegative(),
+});
+export const assetCompleteResponseSchema = z.object({
+    assets: z.array(assetCompleteResultItemSchema),
+});
+/* -------------------------------------------------------------------------- */
+/*  Create update                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * A single asset reference inside a create-update request. `key` is the
+ * expo-export asset key (the md5-basename the client uses to look the asset up
+ * and skip embedded ones); `fileExtension` is the suggested on-disk extension.
+ */
+export const updateAssetRefSchema = z.object({
+    sha256: sha256HexSchema,
+    /** expo-export asset key (md5 basename) — how app code references the asset. */
+    key: z.string().min(1),
+    contentType: z.string().min(1),
+    /** Suggested file extension including the leading dot (e.g. `.js`, `.png`). */
+    fileExtension: z.string().optional(),
+});
+/**
+ * `POST /updates/v1/updates` request. Publishes one bundle for one platform to a
+ * channel (the channel is created on demand — CI-friendly for `pr-<n>`). All
+ * referenced assets MUST already be `uploaded` (via init/complete). `extra`
+ * MUST carry `expoClient` so `Constants.expoConfig` works after an OTA update.
+ */
+export const createUpdateRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    channel: channelNameSchema,
+    runtimeVersion: runtimeVersionSchema,
+    platform: updatePlatformSchema,
+    /** The launch (entry-point) asset — its `fileExtension` is ignored by clients. */
+    launchAsset: updateAssetRefSchema,
+    assets: z.array(updateAssetRefSchema),
+    /**
+     * Opaque `extra` blob embedded verbatim in the signed manifest. MUST contain
+     * `expoClient` (the public expo config) so `Constants.expoConfig` resolves
+     * after an OTA update; MAY carry other third-party config.
+     */
+    extra: z
+        .object({ expoClient: z.record(z.string(), z.unknown()) })
+        .catchall(z.unknown()),
+    /** String→string metadata dict; filtered client-side via manifest filters. */
+    metadata: z.record(z.string(), z.string()).optional(),
+    /** Initial rollout percentage (default 100 — full rollout). */
+    rolloutPercent: rolloutPercentSchema.optional(),
+    /** Git commit the bundle was built from (audit / console display). */
+    gitCommit: z.string().max(100).optional(),
+    /** Git branch the bundle was built from (audit / console display). */
+    gitBranch: z.string().max(200).optional(),
+    /** Human-readable publish message (console display). */
+    message: z.string().max(500).optional(),
+});
+export const updateSchema = z.object({
+    id: z.string(),
+    applicationId: z.string(),
+    channel: z.string(),
+    runtimeVersion: z.string(),
+    platform: updatePlatformSchema,
+    status: updateStatusSchema,
+    rolloutPercent: rolloutPercentSchema,
+    launchAssetSha256: sha256HexSchema,
+    assetSha256s: z.array(sha256HexSchema),
+    gitCommit: z.string().optional(),
+    gitBranch: z.string().optional(),
+    message: z.string().optional(),
+    promotedFromUpdateId: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const createUpdateResponseSchema = z.object({
+    update: updateSchema,
+});
+export const rollbackToEmbeddedEntrySchema = z.object({
+    runtimeVersion: z.string(),
+    platform: updatePlatformSchema,
+    commitTime: z.string(),
+});
+export const channelSchema = z.object({
+    id: z.string(),
+    applicationId: z.string(),
+    name: z.string(),
+    rollbacksToEmbedded: z.array(rollbackToEmbeddedEntrySchema),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const channelListResponseSchema = z.object({
+    channels: z.array(channelSchema),
+});
+export const updateListResponseSchema = z.object({
+    updates: z.array(updateSchema),
+});
+/* -------------------------------------------------------------------------- */
+/*  Rollback / rollback-to-embedded / promote / rollout                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * `POST /updates/v1/channels/:channel/rollback` request. Marks the current head
+ * for `(runtimeVersion, platform)` `rolled_back` so the previous published
+ * update (if any) becomes head again. Nothing is deleted.
+ */
+export const rollbackRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    runtimeVersion: runtimeVersionSchema,
+    platform: updatePlatformSchema,
+});
+/**
+ * `POST /updates/v1/channels/:channel/rollback-to-embedded` request. Records a
+ * `rollBackToEmbedded` directive so clients on this `(runtimeVersion, platform)`
+ * fall back to the update embedded in their binary.
+ */
+export const rollbackToEmbeddedRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    runtimeVersion: runtimeVersionSchema,
+    platform: updatePlatformSchema,
+});
+/**
+ * `POST /updates/v1/channels/:channel/promote` request. Promotes an existing
+ * update (by `updateId`) into the target channel by creating a NEW update (new
+ * UUID) pointing at the SAME assets. `toChannel` defaults to the path channel.
+ */
+export const promoteRequestSchema = z.object({
+    applicationId: z.string().min(1),
+    updateId: z.string().min(1),
+    /** Target channel to promote into. Defaults to the path `:channel`. */
+    toChannel: channelNameSchema.optional(),
+    /** Rollout percentage for the promoted update (default 100). */
+    rolloutPercent: rolloutPercentSchema.optional(),
+});
+/** `PATCH /updates/v1/updates/:updateId` request — adjust a rollout in place. */
+export const updateRolloutPatchSchema = z.object({
+    applicationId: z.string().min(1),
+    rolloutPercent: rolloutPercentSchema,
+});

package/dist/esm/userInvalidation.js

@@ -0,0 +1,85 @@
+/**
+ * Canonical contract for the Oxy user-invalidation broadcast.
+ *
+ * Oxy owns identity, but consumers cache it: Mention keeps a Redis summary per
+ * post author, and every backend using `@oxy.so/core` holds the SDK's own GET
+ * response cache. Both go stale the moment a profile is edited, and neither has
+ * any way to find out — the writer is a different process in a different repo.
+ * This is the signal that tells them.
+ *
+ * The channel name and the payload shape are wire contracts between oxy-api (the
+ * publisher) and every consuming backend (the subscribers), so they live here
+ * rather than in either side. A hand-typed copy of the channel name fails as
+ * "the invalidation never arrives" — silently, because pub/sub has no delivery
+ * receipt and a message nobody is listening for is indistinguishable from a
+ * message nobody sent.
+ *
+ * DELIVERY IS AT-MOST-ONCE, AND THAT IS THE DESIGN. Every consumer's cache still
+ * carries its own TTL, so a dropped message degrades to exactly the behaviour
+ * before this signal existed and never to something worse. That property is what
+ * makes a bare Redis PUBLISH sufficient here and an outbox, retries, delivery
+ * receipts and payload signatures unnecessary. Do not treat a received event as
+ * authoritative for anything except "re-read this user from Oxy".
+ *
+ * PRIVACY — the payload carries NO user data, only an id, a reason and a
+ * timestamp. The channel rides the shared Valkey that every Oxy backend can
+ * subscribe to, so anything placed on it is readable by every service in the
+ * ecosystem. Never add a name, handle, email, avatar or any profile field: a
+ * subscriber that wants the new values re-reads them from Oxy through its normal
+ * authenticated path, where the usual authorization applies.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/** Redis pub/sub channel carrying user-invalidation events. */
+export const OXY_USER_INVALIDATION_CHANNEL = 'oxy:user:invalidate';
+/**
+ * Why a user record changed, as classified by the writer in oxy-api.
+ *
+ * - `profile` — anything a consumer renders or caches as IDENTITY: display name,
+ *   username, avatar, bio, verification, federation fields, account status. This
+ *   is the DEFAULT for every writer, so a site that forgets to classify itself
+ *   over-invalidates (correct, marginally slower) rather than under-invalidates
+ *   (silently wrong). Keep that asymmetry if you add a reason.
+ * - `graph` — follow-edge churn only (follower/following counts). High frequency,
+ *   and bulk follow/unfollow moves up to 200 edges in one call. Nothing renders
+ *   identity from it and a stale count is harmless to ranking, so it is NOT
+ *   broadcast — see {@link OXY_PUBLISHED_USER_CHANGE_REASONS}.
+ */
+export const OXY_USER_CHANGE_REASONS = ['profile', 'graph'];
+/**
+ * The reasons that are actually put on the wire.
+ *
+ * A reason absent from this list is a local cache eviction in oxy-api and
+ * nothing more: no message is published at all, rather than a message every
+ * subscriber receives and discards. The distinction matters at bulk-follow
+ * scale, where the discarded variant is a 200-message burst on a channel every
+ * Oxy backend is subscribed to.
+ *
+ * This is deliberately a shared list rather than a check inside the publisher:
+ * a subscriber needs to know what it can receive, and the schema below rejects
+ * anything else, so publisher and subscriber cannot drift into disagreeing about
+ * which events exist. Adding a reason therefore forces an explicit decision about
+ * whether it broadcasts.
+ */
+export const OXY_PUBLISHED_USER_CHANGE_REASONS = ['profile'];
+/** Whether a change of this kind is broadcast to consumers at all. */
+export function isPublishedOxyUserChangeReason(reason) {
+    return OXY_PUBLISHED_USER_CHANGE_REASONS.includes(reason);
+}
+/**
+ * A single user-invalidation event.
+ *
+ * `at` is the publisher's epoch-ms clock, carried for diagnosis (measuring
+ * end-to-end propagation, spotting a wedged subscriber) — never for ordering or
+ * conflict resolution. Two Oxy tasks publish from unsynchronised clocks, and the
+ * event says only "re-read this user", which is idempotent and order-independent.
+ */
+export const oxyUserInvalidationEventSchema = z.object({
+    /** The Oxy user whose record changed. */
+    userId: z.string().min(1),
+    /** Why it changed. Only broadcast reasons appear on the wire. */
+    reason: z.enum(OXY_PUBLISHED_USER_CHANGE_REASONS),
+    /** Publisher's epoch-ms timestamp. Diagnostic only. */
+    at: z.number().int().nonnegative(),
+});

package/dist/esm/userResponse.js

@@ -0,0 +1,240 @@
+/**
+ * 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 (`@oxy.so/contracts`) is the dedicated, zero-dependency home for
+ * these contracts so the backend (`@oxy.so/api`) and the client SDKs
+ * (`@oxy.so/core`, `@oxy.so/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 login/signup, device sessions, etc.
+ *    Emits `id` (NOT `_id`), forwards `username` verbatim (may be absent), and
+ *    emits `name` as the structured `{ first, last, full, displayName }`
+ *    subdocument.
+ *  - `packages/api/src/models/User.ts` — `NameSchema` (`first`/`last` default
+ *    `''`; `full` and `displayName` are Mongoose VIRTUALS. Formatted API
+ *    responses compose both fields, while raw-document responses may omit the
+ *    virtuals if the query did not materialise them.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+import { verifiedDomainSchema } from './identity.js';
+import { accountCategoriesSchema, accountKindSchema } from './accountGraph.js';
+export const userNameSchema = z
+    .object({
+    first: z.string().optional(),
+    last: z.string().optional(),
+    full: z.string().optional(),
+    displayName: z.string().optional(),
+})
+    .passthrough();
+export const userRelationshipSchema = z.object({
+    isFollowing: z.boolean(),
+    followsYou: z.boolean(),
+});
+export const themePreferenceSchema = z.object({
+    mode: z.enum(['light', 'dark', 'system']),
+    colorPreset: z.string(),
+});
+/**
+ * The canonical user object emitted by `formatUserResponse`.
+ *
+ * `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}.
+ *
+ * `.passthrough()` keeps the large tail of profile fields
+ * (`privacySettings`, `locations`, `links`, `linksMetadata`, `bio`,
+ * `description`, `languages`, `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(),
+    phone: z.string().optional(),
+    address: z.string().optional(),
+    birthday: 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,
+    verified: z.boolean().optional(),
+    /**
+     * The account's languages as full BCP-47 locales (`language-REGION`,
+     * e.g. `es-ES`, `en-US`, `pt-BR`), ordered with the PRIMARY (UI) locale
+     * first. `languages[0]` is the primary locale — there is no singular
+     * `language` field.
+     */
+    languages: z.array(z.string()).optional(),
+    /**
+     * The account's self-sovereign identifier
+     * (`did:web:<FEDERATION_DOMAIN>:u:<userId>`). Surfaced as a `User`
+     * virtual; present on formatted DTOs once the identity layer is live.
+     */
+    did: z.string().optional(),
+    /**
+     * Proven domain-ownership badges. Each is a {@link verifiedDomainSchema}
+     * entry; present only when the account has verified at least one domain.
+     */
+    verifiedDomains: z.array(verifiedDomainSchema).optional(),
+    /**
+     * Account-graph classification — what KIND of account this is.
+     *
+     * ORTHOGONAL to `type` (`local` / `federated` / `agent` / `automated`),
+     * which says where the account lives and how it is driven; the two
+     * coexist and neither substitutes for the other. A `channel` is a
+     * publishing identity nobody can act as, so a consumer that renders
+     * authored content reads THIS to tell a channel's post from a person's.
+     *
+     * Optional because a DTO produced from a source that never carried the
+     * column omits it; absent should be read as `personal`, the column's
+     * default, not as unknown.
+     */
+    kind: accountKindSchema.optional(),
+    /**
+     * What this account is about — the field a profile screen RENDERS.
+     *
+     * **Ordered, primary first.** `accountCategories[0]` is the primary
+     * category; there is deliberately no sibling `primaryCategory` field,
+     * because two representations of one fact can disagree (see rule 2 in
+     * `accountGraph.ts`). Nothing downstream may sort, de-duplicate or
+     * otherwise reorder this array.
+     *
+     * **Ids, never labels.** Each element is a stable slug; the visible text
+     * comes from the reader's own translation catalogue, keyed
+     * `accounts.accountCategory.<id>`. A label on the wire would paint every
+     * profile in the language of whoever picked it.
+     *
+     * Absent when the account has none — which is every `personal` account,
+     * and any non-personal one that has not chosen. A renderer reads
+     * `user.accountCategories ?? []`.
+     */
+    accountCategories: accountCategoriesSchema.optional(),
+    /**
+     * The authenticated viewer's relationship to this profile. Present ONLY
+     * on single-profile fetches (`GET /profiles/username/:username`,
+     * `GET /users/:userId`) when the request is authenticated; OMITTED for
+     * anonymous requests and for the bulk `POST /users/by-ids` fan-out.
+     */
+    relationship: userRelationshipSchema.optional(),
+    /**
+     * Portable theme preference. Rides the self/session payload (cold boot),
+     * so it is present on the current-user DTO (`GET /users/me`,
+     * `GET /session/user/:sessionId`) and absent until the user sets it.
+     */
+    themePreference: themePreferenceSchema.optional(),
+})
+    .passthrough();
+export const userProfileUpdateSchema = z
+    .object({
+    name: z
+        .object({
+        first: z.string().optional(),
+        last: z.string().optional(),
+        /**
+         * Explicit display name, stored rather than composed. Wins over
+         * `first`/`last` when set; send `''` to clear it and fall back
+         * to the composed pair.
+         */
+        displayName: z.string().optional(),
+    })
+        .optional(),
+    username: z.string().optional(),
+    email: z.string().optional(),
+    avatar: z.string().optional(),
+    color: z.string().nullable().optional(),
+    bio: z.string().optional(),
+    description: z.string().optional(),
+    phone: z.string().optional(),
+    address: z.string().optional(),
+    birthday: z.string().optional(),
+    locations: z.array(z.unknown()).optional(),
+    links: z.array(z.string()).optional(),
+    linksMetadata: z
+        .array(z.object({
+        url: z.string(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        image: z.string().optional(),
+        id: z.string().optional(),
+    }))
+        .optional(),
+    /**
+     * Ordered account locales (`language-REGION`), primary first. Replaces
+     * the eliminated singular `language`; `languages[0]` is the primary UI
+     * locale.
+     */
+    languages: z.array(z.string()).optional(),
+    accountExpiresAfterInactivityDays: z.number().nullable().optional(),
+    notificationPreferences: z.record(z.unknown()).optional(),
+    userPreferences: z.record(z.unknown()).optional(),
+    privacySettings: z.record(z.unknown()).optional(),
+    /**
+     * Portable theme preference. Written through the same `PUT /users/me`
+     * settings-update path as `languages`/`userPreferences`.
+     */
+    themePreference: themePreferenceSchema.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;
+}
+/**
+ * Wire shape of `GET /users/me` — the API success envelope (`{ data: <user> }`)
+ * wrapping the current-user DTO. Some older producers use `_id` instead of
+ * `id`; resolve via {@link resolveUserId}. The display name still lives under
+ * `name.displayName`.
+ */
+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 deviceLinkedSessionSchema = 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 deviceLinkedSessionsResponseSchema = z.array(deviceLinkedSessionSchema);
+/**
+ * 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;
+}