@oxyhq/contracts 0.1.1 → 0.2.0

package/dist/cjs/fedcmToken.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * 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()`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fedcmTokenPayloadSchema = void 0;
+const zod_1 = require("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.
+ */
+exports.fedcmTokenPayloadSchema = zod_1.z
+    .object({
+    iss: zod_1.z.string().optional(),
+    sub: zod_1.z.string().optional(),
+    aud: zod_1.z.string().optional(),
+    exp: zod_1.z.number().optional(),
+    iat: zod_1.z.number().optional(),
+    nonce: zod_1.z.string().optional(),
+})
+    .passthrough();

package/dist/cjs/index.js

@@ -11,7 +11,7 @@
  * expo, no `require()` in the ESM build.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sessionStatusSchema = exports.publicApplicationSchema = exports.applicationTypeSchema = exports.safeParseContract = exports.resolveUserId = exports.deviceSessionsResponseSchema = exports.deviceSessionAccountSchema = exports.currentUserResponseSchema = exports.refreshAllResponseSchema = exports.refreshAllAccountSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.userNameSchema = void 0;
+exports.appUserSignalIngestSchema = exports.appInterestInputSchema = exports.appEndorsementInputSchema = exports.recommendationResponseSchema = exports.recommendationItemSchema = exports.recommendationCountSchema = exports.recommendationRequestSchema = exports.recommendationSignalWeightsSchema = exports.recommendationBoostSchema = exports.recommendationExcludeTypeSchema = exports.fedcmTokenPayloadSchema = exports.sessionStatusSchema = exports.publicApplicationSchema = exports.applicationTypeSchema = exports.safeParseContract = exports.resolveUserId = exports.deviceSessionsResponseSchema = exports.deviceSessionAccountSchema = exports.currentUserResponseSchema = exports.refreshAllResponseSchema = exports.refreshAllAccountSchema = exports.userProfileUpdateSchema = exports.userResponseSchema = exports.userNameSchema = void 0;
 var userResponse_1 = require("./userResponse");
 // Schemas
 Object.defineProperty(exports, "userNameSchema", { enumerable: true, get: function () { return userResponse_1.userNameSchema; } });
@@ -30,3 +30,18 @@ var sessionStatus_1 = require("./sessionStatus");
 Object.defineProperty(exports, "applicationTypeSchema", { enumerable: true, get: function () { return sessionStatus_1.applicationTypeSchema; } });
 Object.defineProperty(exports, "publicApplicationSchema", { enumerable: true, get: function () { return sessionStatus_1.publicApplicationSchema; } });
 Object.defineProperty(exports, "sessionStatusSchema", { enumerable: true, get: function () { return sessionStatus_1.sessionStatusSchema; } });
+var fedcmToken_1 = require("./fedcmToken");
+// Schemas
+Object.defineProperty(exports, "fedcmTokenPayloadSchema", { enumerable: true, get: function () { return fedcmToken_1.fedcmTokenPayloadSchema; } });
+var recommendations_1 = require("./recommendations");
+// Schemas
+Object.defineProperty(exports, "recommendationExcludeTypeSchema", { enumerable: true, get: function () { return recommendations_1.recommendationExcludeTypeSchema; } });
+Object.defineProperty(exports, "recommendationBoostSchema", { enumerable: true, get: function () { return recommendations_1.recommendationBoostSchema; } });
+Object.defineProperty(exports, "recommendationSignalWeightsSchema", { enumerable: true, get: function () { return recommendations_1.recommendationSignalWeightsSchema; } });
+Object.defineProperty(exports, "recommendationRequestSchema", { enumerable: true, get: function () { return recommendations_1.recommendationRequestSchema; } });
+Object.defineProperty(exports, "recommendationCountSchema", { enumerable: true, get: function () { return recommendations_1.recommendationCountSchema; } });
+Object.defineProperty(exports, "recommendationItemSchema", { enumerable: true, get: function () { return recommendations_1.recommendationItemSchema; } });
+Object.defineProperty(exports, "recommendationResponseSchema", { enumerable: true, get: function () { return recommendations_1.recommendationResponseSchema; } });
+Object.defineProperty(exports, "appEndorsementInputSchema", { enumerable: true, get: function () { return recommendations_1.appEndorsementInputSchema; } });
+Object.defineProperty(exports, "appInterestInputSchema", { enumerable: true, get: function () { return recommendations_1.appInterestInputSchema; } });
+Object.defineProperty(exports, "appUserSignalIngestSchema", { enumerable: true, get: function () { return recommendations_1.appUserSignalIngestSchema; } });

package/dist/cjs/recommendations.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appUserSignalIngestSchema = exports.appInterestInputSchema = exports.appEndorsementInputSchema = exports.recommendationResponseSchema = exports.recommendationItemSchema = exports.recommendationCountSchema = exports.recommendationRequestSchema = exports.recommendationSignalWeightsSchema = exports.recommendationBoostSchema = exports.recommendationExcludeTypeSchema = void 0;
+const zod_1 = require("zod");
+const userResponse_1 = require("./userResponse");
+/** User-type filters a caller may exclude from the recommendation surface. */
+exports.recommendationExcludeTypeSchema = zod_1.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.
+ */
+exports.recommendationBoostSchema = zod_1.z.object({
+    userIds: zod_1.z.array(zod_1.z.string().trim().min(1)).min(1).max(200),
+    weight: zod_1.z.number().min(-5).max(5),
+    reason: zod_1.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.
+ */
+exports.recommendationSignalWeightsSchema = zod_1.z
+    .object({
+    graph: zod_1.z.number().min(0).max(10).optional(),
+    completeness: zod_1.z.number().min(0).max(10).optional(),
+    verified: zod_1.z.number().min(0).max(10).optional(),
+    curation: zod_1.z.number().min(0).max(10).optional(),
+    interest: zod_1.z.number().min(0).max(10).optional(),
+    appBoost: zod_1.z.number().min(0).max(10).optional(),
+    repCandidate: zod_1.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.
+ */
+exports.recommendationRequestSchema = zod_1.z.object({
+    clientId: zod_1.z.string().trim().min(1).optional(),
+    limit: zod_1.z.number().int().min(1).max(100).optional(),
+    offset: zod_1.z.number().int().min(0).optional(),
+    excludeTypes: zod_1.z.array(exports.recommendationExcludeTypeSchema).optional(),
+    excludeIds: zod_1.z.array(zod_1.z.string().trim().min(1)).max(500).optional(),
+    boosts: zod_1.z.array(exports.recommendationBoostSchema).max(50).optional(),
+    signalWeights: exports.recommendationSignalWeightsSchema.optional(),
+});
+/** Follower/following counts attached to a recommendation item. */
+exports.recommendationCountSchema = zod_1.z.object({
+    followers: zod_1.z.number().int().nonnegative(),
+    following: zod_1.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.
+ */
+exports.recommendationItemSchema = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    username: zod_1.z.string().optional(),
+    name: userResponse_1.userNameSchema,
+    avatar: zod_1.z.string().nullable().optional(),
+    description: zod_1.z.string().nullable().optional(),
+    verified: zod_1.z.boolean().optional(),
+    trustTier: zod_1.z.string().optional(),
+    mutualCount: zod_1.z.number().int().nonnegative(),
+    score: zod_1.z.number().optional(),
+    matchedSignals: zod_1.z.array(zod_1.z.string()).optional(),
+    isFederated: zod_1.z.boolean().optional(),
+    isAgent: zod_1.z.boolean().optional(),
+    isAutomated: zod_1.z.boolean().optional(),
+    instance: zod_1.z.string().optional(),
+    _count: exports.recommendationCountSchema,
+})
+    .passthrough();
+/** Wire shape of the recommendation response — an array of items. */
+exports.recommendationResponseSchema = zod_1.z.array(exports.recommendationItemSchema);
+/** One endorsement edge an app reports: `ownerId` endorses `memberId`. */
+exports.appEndorsementInputSchema = zod_1.z.object({
+    ownerId: zod_1.z.string().trim().min(1),
+    memberId: zod_1.z.string().trim().min(1),
+    op: zod_1.z.enum(['add', 'remove']).default('add'),
+    sourceId: zod_1.z.string().trim().min(1).optional(),
+});
+/** One interest signal an app reports: how interested `userId` is in a topic. */
+exports.appInterestInputSchema = zod_1.z.object({
+    userId: zod_1.z.string().trim().min(1),
+    interestScore: zod_1.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.
+ */
+exports.appUserSignalIngestSchema = zod_1.z
+    .object({
+    endorsements: zod_1.z.array(exports.appEndorsementInputSchema).max(500).optional(),
+    interests: zod_1.z.array(exports.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' });