@oxyhq/contracts 0.1.1 → 0.2.1

package/dist/types/fedcmToken.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 declare const fedcmTokenPayloadSchema: z.ZodObject<{
+    iss: z.ZodOptional<z.ZodString>;
+    sub: z.ZodOptional<z.ZodString>;
+    aud: z.ZodOptional<z.ZodString>;
+    exp: z.ZodOptional<z.ZodNumber>;
+    iat: z.ZodOptional<z.ZodNumber>;
+    nonce: z.ZodOptional<z.ZodString>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    iss: z.ZodOptional<z.ZodString>;
+    sub: z.ZodOptional<z.ZodString>;
+    aud: z.ZodOptional<z.ZodString>;
+    exp: z.ZodOptional<z.ZodNumber>;
+    iat: z.ZodOptional<z.ZodNumber>;
+    nonce: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    iss: z.ZodOptional<z.ZodString>;
+    sub: z.ZodOptional<z.ZodString>;
+    aud: z.ZodOptional<z.ZodString>;
+    exp: z.ZodOptional<z.ZodNumber>;
+    iat: z.ZodOptional<z.ZodNumber>;
+    nonce: z.ZodOptional<z.ZodString>;
+}, z.ZodTypeAny, "passthrough">>;
+export type FedcmTokenPayload = z.infer<typeof fedcmTokenPayloadSchema>;

package/dist/types/index.d.ts

@@ -13,3 +13,7 @@ export { userNameSchema, userResponseSchema, userProfileUpdateSchema, refreshAll
 export type { UserNameResponse, UserResponse, UserProfileUpdate, RefreshAllAccountResponse, RefreshAllResponseContract, CurrentUserResponseContract, DeviceSessionAccountResponse, DeviceSessionsResponseContract, } from './userResponse';
 export { applicationTypeSchema, publicApplicationSchema, sessionStatusSchema, } from './sessionStatus';
 export type { ApplicationTypeContract, PublicApplicationResponse, SessionStatusResponse, } from './sessionStatus';
+export { fedcmTokenPayloadSchema, } from './fedcmToken';
+export type { FedcmTokenPayload, } from './fedcmToken';
+export { recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, } from './recommendations';
+export type { RecommendationExcludeType, RecommendationBoost, RecommendationSignalWeights, RecommendationRequest, RecommendationCount, RecommendationItem, RecommendationResponse, AppEndorsementInput, AppInterestInput, AppUserSignalIngest, } from './recommendations';

package/dist/types/recommendations.d.ts

@@ -0,0 +1,445 @@
+/**
+ * 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';
+/** User-type filters a caller may exclude from the recommendation surface. */
+export declare const recommendationExcludeTypeSchema: z.ZodEnum<["federated", "agent", "automated"]>;
+export type RecommendationExcludeType = z.infer<typeof recommendationExcludeTypeSchema>;
+/**
+ * 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 declare const recommendationBoostSchema: z.ZodObject<{
+    userIds: z.ZodArray<z.ZodString, "many">;
+    weight: z.ZodNumber;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    userIds: string[];
+    weight: number;
+    reason?: string | undefined;
+}, {
+    userIds: string[];
+    weight: number;
+    reason?: string | undefined;
+}>;
+export type RecommendationBoost = z.infer<typeof recommendationBoostSchema>;
+/**
+ * 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 declare const recommendationSignalWeightsSchema: z.ZodObject<{
+    graph: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    completeness: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    verified: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    curation: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    interest: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    appBoost: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    repCandidate: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    verified?: number | undefined;
+    graph?: number | undefined;
+    completeness?: number | undefined;
+    curation?: number | undefined;
+    interest?: number | undefined;
+    appBoost?: number | undefined;
+    repCandidate?: number | undefined;
+}, {
+    verified?: number | undefined;
+    graph?: number | undefined;
+    completeness?: number | undefined;
+    curation?: number | undefined;
+    interest?: number | undefined;
+    appBoost?: number | undefined;
+    repCandidate?: number | undefined;
+}>;
+export type RecommendationSignalWeights = z.infer<typeof recommendationSignalWeightsSchema>;
+/**
+ * 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 declare const recommendationRequestSchema: z.ZodObject<{
+    clientId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    excludeTypes: z.ZodOptional<z.ZodArray<z.ZodEnum<["federated", "agent", "automated"]>, "many">>;
+    excludeIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    boosts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        userIds: z.ZodArray<z.ZodString, "many">;
+        weight: z.ZodNumber;
+        reason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        userIds: string[];
+        weight: number;
+        reason?: string | undefined;
+    }, {
+        userIds: string[];
+        weight: number;
+        reason?: string | undefined;
+    }>, "many">>;
+    signalWeights: z.ZodOptional<z.ZodObject<{
+        graph: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        completeness: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        verified: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        curation: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        interest: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        appBoost: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+        repCandidate: z.ZodOptional<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        verified?: number | undefined;
+        graph?: number | undefined;
+        completeness?: number | undefined;
+        curation?: number | undefined;
+        interest?: number | undefined;
+        appBoost?: number | undefined;
+        repCandidate?: number | undefined;
+    }, {
+        verified?: number | undefined;
+        graph?: number | undefined;
+        completeness?: number | undefined;
+        curation?: number | undefined;
+        interest?: number | undefined;
+        appBoost?: number | undefined;
+        repCandidate?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    clientId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    excludeTypes?: ("federated" | "agent" | "automated")[] | undefined;
+    excludeIds?: string[] | undefined;
+    boosts?: {
+        userIds: string[];
+        weight: number;
+        reason?: string | undefined;
+    }[] | undefined;
+    signalWeights?: {
+        verified?: number | undefined;
+        graph?: number | undefined;
+        completeness?: number | undefined;
+        curation?: number | undefined;
+        interest?: number | undefined;
+        appBoost?: number | undefined;
+        repCandidate?: number | undefined;
+    } | undefined;
+}, {
+    clientId?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    excludeTypes?: ("federated" | "agent" | "automated")[] | undefined;
+    excludeIds?: string[] | undefined;
+    boosts?: {
+        userIds: string[];
+        weight: number;
+        reason?: string | undefined;
+    }[] | undefined;
+    signalWeights?: {
+        verified?: number | undefined;
+        graph?: number | undefined;
+        completeness?: number | undefined;
+        curation?: number | undefined;
+        interest?: number | undefined;
+        appBoost?: number | undefined;
+        repCandidate?: number | undefined;
+    } | undefined;
+}>;
+export type RecommendationRequest = z.infer<typeof recommendationRequestSchema>;
+/** Follower/following counts attached to a recommendation item. */
+export declare const recommendationCountSchema: z.ZodObject<{
+    followers: z.ZodNumber;
+    following: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    followers: number;
+    following: number;
+}, {
+    followers: number;
+    following: number;
+}>;
+export type RecommendationCount = z.infer<typeof recommendationCountSchema>;
+/**
+ * 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 declare const recommendationItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    name: z.ZodType<import("./userResponse").UserNameResponse, z.ZodTypeDef, import("./userResponse").UserNameResponse>;
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    verified: z.ZodOptional<z.ZodBoolean>;
+    trustTier: z.ZodOptional<z.ZodString>;
+    mutualCount: z.ZodNumber;
+    score: z.ZodOptional<z.ZodNumber>;
+    matchedSignals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isFederated: z.ZodOptional<z.ZodBoolean>;
+    isAgent: z.ZodOptional<z.ZodBoolean>;
+    isAutomated: z.ZodOptional<z.ZodBoolean>;
+    instance: z.ZodOptional<z.ZodString>;
+    _count: z.ZodObject<{
+        followers: z.ZodNumber;
+        following: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        followers: number;
+        following: number;
+    }, {
+        followers: number;
+        following: number;
+    }>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    name: z.ZodType<import("./userResponse").UserNameResponse, z.ZodTypeDef, import("./userResponse").UserNameResponse>;
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    verified: z.ZodOptional<z.ZodBoolean>;
+    trustTier: z.ZodOptional<z.ZodString>;
+    mutualCount: z.ZodNumber;
+    score: z.ZodOptional<z.ZodNumber>;
+    matchedSignals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isFederated: z.ZodOptional<z.ZodBoolean>;
+    isAgent: z.ZodOptional<z.ZodBoolean>;
+    isAutomated: z.ZodOptional<z.ZodBoolean>;
+    instance: z.ZodOptional<z.ZodString>;
+    _count: z.ZodObject<{
+        followers: z.ZodNumber;
+        following: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        followers: number;
+        following: number;
+    }, {
+        followers: number;
+        following: number;
+    }>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    name: z.ZodType<import("./userResponse").UserNameResponse, z.ZodTypeDef, import("./userResponse").UserNameResponse>;
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    verified: z.ZodOptional<z.ZodBoolean>;
+    trustTier: z.ZodOptional<z.ZodString>;
+    mutualCount: z.ZodNumber;
+    score: z.ZodOptional<z.ZodNumber>;
+    matchedSignals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isFederated: z.ZodOptional<z.ZodBoolean>;
+    isAgent: z.ZodOptional<z.ZodBoolean>;
+    isAutomated: z.ZodOptional<z.ZodBoolean>;
+    instance: z.ZodOptional<z.ZodString>;
+    _count: z.ZodObject<{
+        followers: z.ZodNumber;
+        following: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        followers: number;
+        following: number;
+    }, {
+        followers: number;
+        following: number;
+    }>;
+}, z.ZodTypeAny, "passthrough">>;
+export type RecommendationItem = z.infer<typeof recommendationItemSchema>;
+/** Wire shape of the recommendation response — an array of items. */
+export declare const recommendationResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    name: z.ZodType<import("./userResponse").UserNameResponse, z.ZodTypeDef, import("./userResponse").UserNameResponse>;
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    verified: z.ZodOptional<z.ZodBoolean>;
+    trustTier: z.ZodOptional<z.ZodString>;
+    mutualCount: z.ZodNumber;
+    score: z.ZodOptional<z.ZodNumber>;
+    matchedSignals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isFederated: z.ZodOptional<z.ZodBoolean>;
+    isAgent: z.ZodOptional<z.ZodBoolean>;
+    isAutomated: z.ZodOptional<z.ZodBoolean>;
+    instance: z.ZodOptional<z.ZodString>;
+    _count: z.ZodObject<{
+        followers: z.ZodNumber;
+        following: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        followers: number;
+        following: number;
+    }, {
+        followers: number;
+        following: number;
+    }>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    id: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    name: z.ZodType<import("./userResponse").UserNameResponse, z.ZodTypeDef, import("./userResponse").UserNameResponse>;
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    verified: z.ZodOptional<z.ZodBoolean>;
+    trustTier: z.ZodOptional<z.ZodString>;
+    mutualCount: z.ZodNumber;
+    score: z.ZodOptional<z.ZodNumber>;
+    matchedSignals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isFederated: z.ZodOptional<z.ZodBoolean>;
+    isAgent: z.ZodOptional<z.ZodBoolean>;
+    isAutomated: z.ZodOptional<z.ZodBoolean>;
+    instance: z.ZodOptional<z.ZodString>;
+    _count: z.ZodObject<{
+        followers: z.ZodNumber;
+        following: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        followers: number;
+        following: number;
+    }, {
+        followers: number;
+        following: number;
+    }>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    id: z.ZodString;
+    username: z.ZodOptional<z.ZodString>;
+    name: z.ZodType<import("./userResponse").UserNameResponse, z.ZodTypeDef, import("./userResponse").UserNameResponse>;
+    avatar: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    verified: z.ZodOptional<z.ZodBoolean>;
+    trustTier: z.ZodOptional<z.ZodString>;
+    mutualCount: z.ZodNumber;
+    score: z.ZodOptional<z.ZodNumber>;
+    matchedSignals: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    isFederated: z.ZodOptional<z.ZodBoolean>;
+    isAgent: z.ZodOptional<z.ZodBoolean>;
+    isAutomated: z.ZodOptional<z.ZodBoolean>;
+    instance: z.ZodOptional<z.ZodString>;
+    _count: z.ZodObject<{
+        followers: z.ZodNumber;
+        following: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        followers: number;
+        following: number;
+    }, {
+        followers: number;
+        following: number;
+    }>;
+}, z.ZodTypeAny, "passthrough">>, "many">;
+export type RecommendationResponse = z.infer<typeof recommendationResponseSchema>;
+/** One endorsement edge an app reports: `ownerId` endorses `memberId`. */
+export declare const appEndorsementInputSchema: z.ZodObject<{
+    ownerId: z.ZodString;
+    memberId: z.ZodString;
+    op: z.ZodDefault<z.ZodEnum<["add", "remove"]>>;
+    sourceId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ownerId: string;
+    memberId: string;
+    op: "add" | "remove";
+    sourceId?: string | undefined;
+}, {
+    ownerId: string;
+    memberId: string;
+    op?: "add" | "remove" | undefined;
+    sourceId?: string | undefined;
+}>;
+export type AppEndorsementInput = z.infer<typeof appEndorsementInputSchema>;
+/** One interest signal an app reports: how interested `userId` is in a topic. */
+export declare const appInterestInputSchema: z.ZodObject<{
+    userId: z.ZodString;
+    interestScore: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    userId: string;
+    interestScore: number;
+}, {
+    userId: string;
+    interestScore: number;
+}>;
+export type AppInterestInput = z.infer<typeof appInterestInputSchema>;
+/**
+ * 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 declare const appUserSignalIngestSchema: z.ZodEffects<z.ZodObject<{
+    endorsements: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ownerId: z.ZodString;
+        memberId: z.ZodString;
+        op: z.ZodDefault<z.ZodEnum<["add", "remove"]>>;
+        sourceId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        ownerId: string;
+        memberId: string;
+        op: "add" | "remove";
+        sourceId?: string | undefined;
+    }, {
+        ownerId: string;
+        memberId: string;
+        op?: "add" | "remove" | undefined;
+        sourceId?: string | undefined;
+    }>, "many">>;
+    interests: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        userId: z.ZodString;
+        interestScore: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        userId: string;
+        interestScore: number;
+    }, {
+        userId: string;
+        interestScore: number;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    endorsements?: {
+        ownerId: string;
+        memberId: string;
+        op: "add" | "remove";
+        sourceId?: string | undefined;
+    }[] | undefined;
+    interests?: {
+        userId: string;
+        interestScore: number;
+    }[] | undefined;
+}, {
+    endorsements?: {
+        ownerId: string;
+        memberId: string;
+        op?: "add" | "remove" | undefined;
+        sourceId?: string | undefined;
+    }[] | undefined;
+    interests?: {
+        userId: string;
+        interestScore: number;
+    }[] | undefined;
+}>, {
+    endorsements?: {
+        ownerId: string;
+        memberId: string;
+        op: "add" | "remove";
+        sourceId?: string | undefined;
+    }[] | undefined;
+    interests?: {
+        userId: string;
+        interestScore: number;
+    }[] | undefined;
+}, {
+    endorsements?: {
+        ownerId: string;
+        memberId: string;
+        op?: "add" | "remove" | undefined;
+        sourceId?: string | undefined;
+    }[] | undefined;
+    interests?: {
+        userId: string;
+        interestScore: number;
+    }[] | undefined;
+}>;
+export type AppUserSignalIngest = z.infer<typeof appUserSignalIngestSchema>;