@oxyhq/contracts 0.19.0 → 0.21.0

package/dist/esm/reputation.js

@@ -0,0 +1,293 @@
+/**
+ * Oxy Trust — reputation API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the reputation ledger's wire shapes: the closed
+ * value sets (`REPUTATION_CATEGORIES`, `TRUST_TIERS`, …), the response entities
+ * (`ReputationTransaction`, the two balance views, `ReputationDispute`,
+ * `ReputationRule`, the leaderboard entry) and the request bodies the write
+ * endpoints accept. The API validates its OUTPUT against these schemas and its
+ * INPUT with the same request schemas the SDK's input types are derived from;
+ * `@oxyhq/core`'s reputation mixin imports every type from here rather than
+ * declaring its own.
+ *
+ * Why this module exists: the balance endpoint was view-split server-side
+ * without the SDK type moving with it, and for hours the SDK affirmatively
+ * type-checked a read of `balance.reliability.reportAccuracyScore` against a
+ * response that no longer carried `reliability`. Nothing structural connected
+ * the API's hand-written serializers (which returned `Record<string, unknown>`)
+ * to the SDK's interfaces — only human attention. With the serializers
+ * annotated against these definitions, that divergence is a build failure.
+ *
+ * Design anchors:
+ *  - **Ids are strings, timestamps are ISO 8601 strings.** The server holds
+ *    `ObjectId`s and `Date`s; every serializer converts at the boundary, so a
+ *    `Date` leaking into a field this module types as `string` fails to compile.
+ *  - **The balance has two views, and the union is the contract.** See
+ *    {@link ReputationBalanceView} — the compile-time assertions below are what
+ *    stop the private view's fields becoming reachable on a stranger's balance.
+ *  - **The closed value sets live here, not beside the mongoose models.** The
+ *    API's model enums and the SDK's unions are the same `as const` tuple, so a
+ *    seventh category cannot be added on one side only.
+ *
+ * The response entities are declared as explicit `interface`s with their runtime
+ * schemas annotated `z.ZodType<Interface>`, following `./links` and
+ * `./userResponse`: a `z.infer<>` of a nested-object schema can degrade to `{}`
+ * under a consumer's `moduleResolution: "node"` (node10) resolution, while a
+ * literal interface emits the field types verbatim in the `.d.ts` and survives
+ * both `node` and `bundler`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+import { userNameSchema } from './userResponse.js';
+import { reputationConductSchema, reputationContextualInfluenceSchema, reputationContributionSchema, reputationPersonhoodSchema, reputationReportingSchema, reputationReviewingSchema, } from './moderationReputation.js';
+/* -------------------------------------------------------------------------- */
+/*  Closed value sets                                                         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Category bucket a reputation transaction falls into. Drives the per-category
+ * balance breakdown; every rule and transaction carries exactly one.
+ *
+ * - `content`    — posts, comments, media a user authored.
+ * - `social`     — follows, likes, social interactions.
+ * - `trust`      — identity / verification / trust-graph signals.
+ * - `moderation` — reports filed, moderation actions, review outcomes.
+ * - `physical`   — real-world signals (event check-ins, verified purchases).
+ * - `penalty`    — negative adjustments for abuse / policy violations.
+ * - `other`      — anything that does not fit the buckets above.
+ */
+export const REPUTATION_CATEGORIES = [
+    'content',
+    'social',
+    'trust',
+    'moderation',
+    'physical',
+    'penalty',
+    'other',
+];
+export const reputationCategorySchema = z.enum(REPUTATION_CATEGORIES);
+/**
+ * Transaction lifecycle status.
+ *
+ * - `active`   — counts toward the balance.
+ * - `disputed` — under dispute; still counts until the dispute resolves.
+ * - `reversed` — superseded by a compensating reversal transaction; excluded.
+ * - `voided`   — administratively excluded with no compensating entry.
+ */
+export const REPUTATION_TRANSACTION_STATUSES = [
+    'active',
+    'disputed',
+    'reversed',
+    'voided',
+];
+export const reputationTransactionStatusSchema = z.enum(REPUTATION_TRANSACTION_STATUSES);
+/**
+ * Trust tiers, lowest → highest trust, plus the punitive `restricted`.
+ *
+ * Publicly visible: this is the contribution ladder the reputation system
+ * exists to publish. Note it doubles as the sanction marker — a `restricted`
+ * account is publicly identifiable as such.
+ */
+export const TRUST_TIERS = ['restricted', 'new', 'trusted', 'high_trust', 'verified'];
+export const trustTierSchema = z.enum(TRUST_TIERS);
+/** Kind of entity a transaction may target. */
+export const REPUTATION_TARGET_ENTITY_TYPES = [
+    'post',
+    'comment',
+    'report',
+    'purchase',
+    'event',
+    'check_in',
+    'manual_review',
+    'user',
+    'other',
+];
+export const reputationTargetEntityTypeSchema = z.enum(REPUTATION_TARGET_ENTITY_TYPES);
+/** Dispute lifecycle status. */
+export const REPUTATION_DISPUTE_STATUSES = [
+    'open',
+    'accepted',
+    'rejected',
+    'needs_review',
+];
+export const reputationDisputeStatusSchema = z.enum(REPUTATION_DISPUTE_STATUSES);
+/** Influence context selecting which capped weight axis to read. */
+export const REPUTATION_INFLUENCE_CONTEXTS = [
+    'default',
+    'report',
+    'moderation',
+    'ranking',
+];
+export const reputationInfluenceContextSchema = z.enum(REPUTATION_INFLUENCE_CONTEXTS);
+export const reputationTransactionSchema = z.object({
+    id: z.string(),
+    userId: z.string(),
+    points: z.number(),
+    actionType: z.string(),
+    category: reputationCategorySchema,
+    applicationId: z.string().optional(),
+    credentialId: z.string().optional(),
+    sourceActionId: z.string().optional(),
+    sourceActionType: z.string().optional(),
+    targetEntityId: z.string().optional(),
+    targetEntityType: reputationTargetEntityTypeSchema.optional(),
+    status: reputationTransactionStatusSchema,
+    reversedTransactionId: z.string().optional(),
+    reason: z.string().optional(),
+    metadata: z.record(z.unknown()).optional(),
+    createdByUserId: z.string().optional(),
+    reviewedByUserId: z.string().optional(),
+    reviewedAt: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const reputationBalanceBreakdownSchema = z.object({
+    content: z.number(),
+    social: z.number(),
+    trust: z.number(),
+    moderation: z.number(),
+    physical: z.number(),
+    penalties: z.number(),
+});
+export const reputationInfluenceSchema = z.object({
+    defaultWeight: z.number(),
+    reportWeight: z.number(),
+    moderationWeight: z.number(),
+    rankingFeedbackWeight: z.number(),
+});
+export const reputationReliabilitySchema = z.object({
+    accurateReports: z.number(),
+    rejectedReports: z.number(),
+    reportAccuracyScore: z.number(),
+    abuseScore: z.number(),
+});
+/** The fields both balance views share. Kept as a shape so the full view can spread it. */
+const balanceSummaryShape = {
+    userId: z.string(),
+    total: z.number(),
+    trustTier: trustTierSchema,
+};
+export const reputationBalanceSummarySchema = z.object(balanceSummaryShape);
+export const reputationBalanceSchema = z.object({
+    ...balanceSummaryShape,
+    positive: z.number(),
+    negative: z.number(),
+    breakdown: reputationBalanceBreakdownSchema,
+    influence: reputationInfluenceSchema,
+    reliability: reputationReliabilitySchema,
+    recalculatedAt: z.string(),
+    updatedAt: z.string(),
+    personhood: reputationPersonhoodSchema.optional(),
+    contribution: reputationContributionSchema.optional(),
+    conduct: reputationConductSchema.optional(),
+    reporting: reputationReportingSchema.optional(),
+    reviewing: reputationReviewingSchema.optional(),
+    contextualInfluence: reputationContextualInfluenceSchema.optional(),
+});
+/**
+ * The fields the full {@link ReputationBalance} carries beyond the public
+ * {@link ReputationBalanceSummary} that the API sends ALL-OR-NOTHING. The
+ * runtime discriminant between the two views.
+ *
+ * The V2 blocks (`conduct`, `contribution`, …) are deliberately NOT listed:
+ * they are optional on the wire, so requiring them here would make a balance
+ * from a server that predates them fail to narrow, hiding the whole private
+ * view. Read a V2 block by checking that block.
+ */
+const FULL_BALANCE_FIELDS = [
+    'positive',
+    'negative',
+    'breakdown',
+    'influence',
+    'reliability',
+    'recalculatedAt',
+    'updatedAt',
+];
+/**
+ * Whether a balance came back as the SUBJECT view, and so carries the
+ * breakdown / influence / reliability blocks.
+ *
+ * Checks every extra field rather than one representative: the point of the
+ * guard is that the caller then dereferences those blocks, so a partial payload
+ * must not narrow.
+ *
+ * @param balance - A balance from `getReputationBalance`.
+ */
+export function isFullReputationBalance(balance) {
+    return FULL_BALANCE_FIELDS.every((field) => field in balance);
+}
+export const reputationDisputeSchema = z.object({
+    id: z.string(),
+    transactionId: z.string(),
+    userId: z.string(),
+    reason: z.string(),
+    status: reputationDisputeStatusSchema,
+    evidence: z.array(z.string()).optional(),
+    resolvedAt: z.string().optional(),
+    resolvedByUserId: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const reputationRuleSchema = z.object({
+    id: z.string(),
+    actionType: z.string(),
+    points: z.number(),
+    category: reputationCategorySchema,
+    description: z.string(),
+    cooldownInMinutes: z.number(),
+    isEnabled: z.boolean(),
+});
+export const reputationLeaderboardUserSchema = z.object({
+    id: z.string(),
+    username: z.string(),
+    name: userNameSchema,
+    avatar: z.string().optional(),
+    publicKey: z.string().optional(),
+});
+export const reputationLeaderboardEntrySchema = z.object({
+    user: reputationLeaderboardUserSchema,
+    total: z.number(),
+    trustTier: trustTierSchema,
+    rank: z.number(),
+});
+export const reputationInfluenceResultSchema = z.object({
+    context: reputationInfluenceContextSchema,
+    weight: z.number(),
+    influence: reputationInfluenceSchema,
+});
+export const reverseReputationTransactionResultSchema = z.object({
+    original: reputationTransactionSchema,
+    reversal: reputationTransactionSchema,
+});
+export const awardReputationSchema = z.object({
+    userId: z.string().trim().min(1),
+    actionType: z.string().trim().min(1),
+    applicationId: z.string().trim().min(1).optional(),
+    credentialId: z.string().trim().min(1).optional(),
+    sourceActionId: z.string().trim().min(1).optional(),
+    sourceActionType: z.string().trim().min(1).optional(),
+    targetEntityId: z.string().trim().min(1).optional(),
+    targetEntityType: reputationTargetEntityTypeSchema.optional(),
+    reason: z.string().trim().max(500).optional(),
+    metadata: z.record(z.unknown()).optional(),
+});
+export const createReputationDisputeSchema = z.object({
+    transactionId: z.string().trim().min(1),
+    reason: z.string().trim().min(1).max(1000),
+    evidence: z.array(z.string().trim().min(1)).max(20).optional(),
+});
+export const resolveReputationDisputeSchema = z.object({
+    status: z.enum(['accepted', 'rejected']),
+});
+export const upsertReputationRuleSchema = z.object({
+    actionType: z.string().trim().min(1),
+    points: z.number(),
+    category: reputationCategorySchema,
+    description: z.string().trim().min(1).max(500),
+    cooldownInMinutes: z.number().int().min(0).default(0),
+    isEnabled: z.boolean().default(true),
+});
+export const reverseReputationTransactionSchema = z.object({
+    reason: z.string().trim().max(500).optional(),
+});

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 `@oxyhq/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(),
+});