@oxyhq/contracts 0.1.1 → 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

@@ -17,3 +17,9 @@ 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' });