@oxyhq/contracts 0.1.0 → 0.2.0

package/dist/esm/fedcmToken.js

@@ -0,0 +1,46 @@
+/**
+ * Canonical contract for the FedCM ID-token JWT payload.
+ *
+ * SINGLE SOURCE OF TRUTH for the decoded claims of the HS256 ID token the auth
+ * IdP (`auth.oxy.so`) signs and `POST /fedcm/exchange` consumes. The API decodes
+ * the JWT, verifies its signature, then validates the resulting claim object
+ * against this schema before trusting any field — a malformed payload (e.g. a
+ * forged token whose signature happened to match but whose body is the wrong
+ * shape) is rejected at the boundary instead of being cast and used.
+ *
+ * Validation philosophy — match the existing exchange behaviour exactly:
+ *  - This schema validates the STRUCTURAL shape of the decoded claims only
+ *    (types of the fields, not their presence or business-rule validity).
+ *  - `sub` / `aud` / `nonce` / `iss` / `exp` presence + value checks remain in
+ *    `fedcm.service.exchangeIdToken`, which returns the specific
+ *    `missing_required_fields` / `invalid_issuer` / `token_expired` errors. So
+ *    every field is `.optional()` here: a token missing `nonce` must still reach
+ *    the `missing_required_fields` branch, not be rejected as a malformed token.
+ *  - `.passthrough()` preserves any additional claims the IdP may add without a
+ *    coordinated contract bump.
+ *
+ * Faithful to the producer:
+ *  - `packages/auth/server/index.ts` `mintSessionForClient` — builds the
+ *    assertion with `iss` (central issuer), `sub` (user id), `aud` (RP origin),
+ *    `exp` / `iat` (numeric epoch seconds), and `nonce` (the server-minted,
+ *    origin-bound nonce).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Decoded FedCM ID-token claims. Every field is optional because presence is
+ * enforced downstream (see module doc); the schema's job is to guarantee that
+ * any present claim has the correct primitive type before it is read.
+ */
+export const fedcmTokenPayloadSchema = z
+    .object({
+    iss: z.string().optional(),
+    sub: z.string().optional(),
+    aud: z.string().optional(),
+    exp: z.number().optional(),
+    iat: z.number().optional(),
+    nonce: z.string().optional(),
+})
+    .passthrough();

package/dist/esm/index.js

@@ -11,6 +11,15 @@
  */
 export { 
 // Schemas
-userNameSchema, userResponseSchema, refreshAllAccountSchema, refreshAllResponseSchema, currentUserResponseSchema, deviceSessionAccountSchema, deviceSessionsResponseSchema, 
+userNameSchema, userResponseSchema, userProfileUpdateSchema, refreshAllAccountSchema, refreshAllResponseSchema, currentUserResponseSchema, deviceSessionAccountSchema, deviceSessionsResponseSchema, 
 // Helpers
 resolveUserId, safeParseContract, } from './userResponse.js';
+export { 
+// Schemas
+applicationTypeSchema, publicApplicationSchema, sessionStatusSchema, } from './sessionStatus.js';
+export { 
+// Schemas
+fedcmTokenPayloadSchema, } from './fedcmToken.js';
+export { 
+// Schemas
+recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, } from './recommendations.js';

package/dist/esm/recommendations.js

@@ -0,0 +1,122 @@
+/**
+ * Recommendation-engine API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the reputation-weighted
+ * profile-recommendation surface (`POST /profiles/recommendations`) and the
+ * cross-app signal-ingest endpoint (`POST /app-signals/ingest`). The API
+ * validates its INPUT/OUTPUT against these schemas; consumer SDKs validate the
+ * same definitions, so the producer and every consumer cannot drift.
+ *
+ * Platform-agnostic — zod is the only runtime dependency (no react / react-native
+ * / expo, ESM-safe).
+ */
+import { z } from 'zod';
+import { userNameSchema } from './userResponse.js';
+/** User-type filters a caller may exclude from the recommendation surface. */
+export const recommendationExcludeTypeSchema = z.enum([
+    'federated',
+    'agent',
+    'automated',
+]);
+/**
+ * A caller-supplied editorial boost. `userIds` are nudged up (or down, for a
+ * negative weight) in the ranking; the optional `reason` is for audit/telemetry
+ * only and never surfaced to end users. Boost members still pass the eligibility
+ * gate — a boost cannot resurrect a private/restricted/ineligible account.
+ */
+export const recommendationBoostSchema = z.object({
+    userIds: z.array(z.string().trim().min(1)).min(1).max(200),
+    weight: z.number().min(-5).max(5),
+    reason: z.string().trim().max(120).optional(),
+});
+/**
+ * Per-request overrides for the scoring signal weights. Every key is optional
+ * and clamped server-side to the resolved weight profile's allowed range — a
+ * caller can re-weight signals but never escape the profile's bounds.
+ */
+export const recommendationSignalWeightsSchema = z
+    .object({
+    graph: z.number().min(0).max(10).optional(),
+    completeness: z.number().min(0).max(10).optional(),
+    verified: z.number().min(0).max(10).optional(),
+    curation: z.number().min(0).max(10).optional(),
+    interest: z.number().min(0).max(10).optional(),
+    appBoost: z.number().min(0).max(10).optional(),
+    repCandidate: z.number().min(0).max(10).optional(),
+})
+    .partial();
+/**
+ * Request body for `POST /profiles/recommendations`.
+ *
+ * `clientId` selects the per-app weight profile (the Application `_id`); when
+ * omitted the default profile is used. `excludeIds` removes accounts the caller
+ * has already seen/handled; `boosts` and `signalWeights` let the caller bias the
+ * ranking within server-enforced bounds.
+ */
+export const recommendationRequestSchema = z.object({
+    clientId: z.string().trim().min(1).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+    offset: z.number().int().min(0).optional(),
+    excludeTypes: z.array(recommendationExcludeTypeSchema).optional(),
+    excludeIds: z.array(z.string().trim().min(1)).max(500).optional(),
+    boosts: z.array(recommendationBoostSchema).max(50).optional(),
+    signalWeights: recommendationSignalWeightsSchema.optional(),
+});
+/** Follower/following counts attached to a recommendation item. */
+export const recommendationCountSchema = z.object({
+    followers: z.number().int().nonnegative(),
+    following: z.number().int().nonnegative(),
+});
+/**
+ * A single recommended profile.
+ *
+ * `name` reuses the canonical {@link userNameSchema} so `name.displayName` is the
+ * already-resolved server-side value. `score` and `matchedSignals` are present
+ * only on the scored (v2) path; `mutualCount` and `_count` are always present.
+ */
+export const recommendationItemSchema = z
+    .object({
+    id: z.string(),
+    username: z.string().optional(),
+    name: userNameSchema,
+    avatar: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    verified: z.boolean().optional(),
+    trustTier: z.string().optional(),
+    mutualCount: z.number().int().nonnegative(),
+    score: z.number().optional(),
+    matchedSignals: z.array(z.string()).optional(),
+    isFederated: z.boolean().optional(),
+    isAgent: z.boolean().optional(),
+    isAutomated: z.boolean().optional(),
+    instance: z.string().optional(),
+    _count: recommendationCountSchema,
+})
+    .passthrough();
+/** Wire shape of the recommendation response — an array of items. */
+export const recommendationResponseSchema = z.array(recommendationItemSchema);
+/** One endorsement edge an app reports: `ownerId` endorses `memberId`. */
+export const appEndorsementInputSchema = z.object({
+    ownerId: z.string().trim().min(1),
+    memberId: z.string().trim().min(1),
+    op: z.enum(['add', 'remove']).default('add'),
+    sourceId: z.string().trim().min(1).optional(),
+});
+/** One interest signal an app reports: how interested `userId` is in a topic. */
+export const appInterestInputSchema = z.object({
+    userId: z.string().trim().min(1),
+    interestScore: z.number().min(0).max(1),
+});
+/**
+ * Request body for `POST /app-signals/ingest` (service token, `signals:write`).
+ *
+ * At least one of `endorsements` / `interests` must be non-empty — an ingest
+ * with neither is a no-op and rejected so a misconfigured caller is surfaced
+ * rather than silently succeeding.
+ */
+export const appUserSignalIngestSchema = z
+    .object({
+    endorsements: z.array(appEndorsementInputSchema).max(500).optional(),
+    interests: z.array(appInterestInputSchema).max(500).optional(),
+})
+    .refine((value) => (value.endorsements?.length ?? 0) > 0 || (value.interests?.length ?? 0) > 0, { message: 'At least one of endorsements or interests must be non-empty' });

package/dist/esm/sessionStatus.js

@@ -0,0 +1,99 @@
+/**
+ * Canonical contract for `GET /auth/session/status/:sessionToken`.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of the cross-app device-flow
+ * session-status payload and the sanitized public application identity it
+ * embeds. The API validates its OUTPUT against these schemas; the auth app
+ * (consent UI) validates its INPUT against the same schemas. Because there is
+ * exactly one definition, the producer and the consumer cannot drift.
+ *
+ * The class of bug that motivated moving this into `@oxyhq/contracts`: the auth
+ * app's LOCAL `sessionStatusSchema` typed `sessionId` as a non-nullable
+ * `z.string().optional()`. The producer emits `sessionId: authorizedSessionId ||
+ * null`, so a PENDING session (not yet authorized) carries `sessionId: null` —
+ * `.optional()` permits `undefined`/missing but REJECTS `null`, so `safeParse`
+ * failed, the whole response collapsed to `null`, and the consent screen showed
+ * "Unable to identify the requesting application". Pinning the nullability in one
+ * shared place makes that drift impossible.
+ *
+ * Faithful to the producers:
+ *  - `packages/api/src/utils/serializeApplication.ts` `serializePublicApplication`
+ *    — the ONLY shape returned to an unauthenticated consent UI. Optional fields
+ *    (`description`, `icon`, `websiteUrl`, `developerName`) are OMITTED when
+ *    absent (never serialized as `null`), so they are `.optional()` — NOT
+ *    `.nullable()`. `type` is the `Application.type` enum.
+ *  - `packages/api/src/routes/auth.ts` `GET /session/status/:sessionToken` — the
+ *    inner object of the API's `{ data: ... }` success envelope. The handler
+ *    ALWAYS emits `status`, `authorized` (`status === 'authorized'`),
+ *    `sessionToken`, `expiresAt` (ISO string), and `application` (resolved object
+ *    OR `null`). It ALWAYS emits `sessionId` / `publicKey` / `userId`, each as a
+ *    string value OR `null` (`authorizedSessionId || null`, `authorizedBy ||
+ *    null`, `authorizedUserId?.toString() || null`).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * Application `type` enum. Mirrors `APPLICATION_TYPES` in
+ * `packages/api/src/models/Application.ts` (`first_party` | `third_party` |
+ * `internal` | `system`).
+ */
+export const applicationTypeSchema = z.enum([
+    'first_party',
+    'third_party',
+    'internal',
+    'system',
+]);
+/**
+ * The display-safe public identity of a requesting application, exactly as
+ * `serializePublicApplication` emits it. Returned by the API inside
+ * `GET /auth/session/status/:sessionToken` (device flow) and
+ * `GET /auth/oauth/client/:clientId` (OAuth code flow).
+ *
+ * Optional fields are `.optional()` (NOT `.nullable()`): the serializer OMITS
+ * `description` / `icon` / `websiteUrl` / `developerName` when the underlying
+ * value is absent — it never writes `null` for them. `developerName` is only
+ * attached for non-official apps when a name could be resolved.
+ */
+export const publicApplicationSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+    icon: z.string().optional(),
+    websiteUrl: z.string().optional(),
+    type: applicationTypeSchema,
+    isOfficial: z.boolean(),
+    isInternal: z.boolean(),
+    scopes: z.array(z.string()),
+    developerName: z.string().optional(),
+});
+/**
+ * The inner object of `GET /auth/session/status/:sessionToken` (inside the API's
+ * `{ data: ... }` envelope).
+ *
+ * `application` is the resolved {@link publicApplicationSchema} identity of the
+ * requesting application, or `null` when the bound app was hard-deleted / is no
+ * longer `active` (defensive — normally always present).
+ *
+ * `sessionId` / `publicKey` / `userId` are `.nullable().optional()`: the producer
+ * ALWAYS emits the key, with a string for an AUTHORIZED session or `null` for a
+ * PENDING one. `.nullable()` accepts the PENDING `null`; `.optional()` is belt-
+ * and-braces so a consumer is never broken by a future projection that drops the
+ * key. (`.optional()` alone would REJECT the PENDING `null` — that was the bug.)
+ *
+ * `authorized` / `sessionToken` / `expiresAt` are emitted unconditionally by the
+ * current producer and are never `null`, but stay `.optional()` so the contract
+ * tolerates leaner shapes from other producers of this same payload without a
+ * coordinated bump.
+ */
+export const sessionStatusSchema = z.object({
+    status: z.string(),
+    authorized: z.boolean().optional(),
+    sessionToken: z.string().optional(),
+    application: publicApplicationSchema.nullable().optional(),
+    expiresAt: z.string().optional(),
+    sessionId: z.string().nullable().optional(),
+    publicKey: z.string().nullable().optional(),
+    userId: z.string().nullable().optional(),
+});

package/dist/esm/userResponse.js

@@ -18,14 +18,14 @@
  *  - `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.
+ *    emits `name` as the structured `{ first, last, full, displayName }`
+ *    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.
+ *    `''`; `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.
  *  - 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).
+ *    per-slot `authuser` is the numeric `oxy_rt_${authuser}` cookie slot.
  *
  * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
  * `require()`).
@@ -35,7 +35,9 @@ 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.
+ * - `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.
  *
  * `.passthrough()` is intentional: it tolerates additive name fields without a
  * coordinated contract bump, while the three known keys stay strongly typed.
@@ -45,18 +47,17 @@ export const userNameSchema = z
     first: z.string().optional(),
     last: z.string().optional(),
     full: z.string().optional(),
+    displayName: z.string(),
 })
     .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}.
+ * `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
+ * `.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`,
@@ -77,13 +78,44 @@ export const userResponseSchema = z
     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(),
+    name: userNameSchema,
     verified: z.boolean().optional(),
     language: z.string().optional(),
 })
     .passthrough();
+export const userProfileUpdateSchema = z
+    .object({
+    name: z
+        .object({
+        first: z.string().optional(),
+        last: 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(),
+    location: 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(),
+    language: 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(),
+})
+    .passthrough();
 /**
  * Resolve the canonical user id from a {@link UserResponse}, accepting either
  * the `formatUserResponse` `id` field or the raw-document `_id` field.
@@ -94,14 +126,12 @@ export function resolveUserId(user) {
 /**
  * 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`).
+ * `authuser` is the device-local slot index (`0..N-1`). `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(),
+    authuser: z.number().int().nonnegative(),
     accessToken: z.string(),
     expiresAt: z.string(),
     sessionId: z.string(),
@@ -110,19 +140,16 @@ export const refreshAllAccountSchema = z.object({
 /**
  * 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`.
+ * accounts on this device" — the IdP must show the sign-in form.
  */
 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.
+ * 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,