@oxyhq/contracts 0.19.0 → 0.21.0

package/dist/cjs/reputation.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * 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()`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reverseReputationTransactionSchema = exports.upsertReputationRuleSchema = exports.resolveReputationDisputeSchema = exports.createReputationDisputeSchema = exports.awardReputationSchema = exports.reverseReputationTransactionResultSchema = exports.reputationInfluenceResultSchema = exports.reputationLeaderboardEntrySchema = exports.reputationLeaderboardUserSchema = exports.reputationRuleSchema = exports.reputationDisputeSchema = exports.reputationBalanceSchema = exports.reputationBalanceSummarySchema = exports.reputationReliabilitySchema = exports.reputationInfluenceSchema = exports.reputationBalanceBreakdownSchema = exports.reputationTransactionSchema = exports.reputationInfluenceContextSchema = exports.REPUTATION_INFLUENCE_CONTEXTS = exports.reputationDisputeStatusSchema = exports.REPUTATION_DISPUTE_STATUSES = exports.reputationTargetEntityTypeSchema = exports.REPUTATION_TARGET_ENTITY_TYPES = exports.trustTierSchema = exports.TRUST_TIERS = exports.reputationTransactionStatusSchema = exports.REPUTATION_TRANSACTION_STATUSES = exports.reputationCategorySchema = exports.REPUTATION_CATEGORIES = void 0;
+exports.isFullReputationBalance = isFullReputationBalance;
+const zod_1 = require("zod");
+const userResponse_1 = require("./userResponse");
+const moderationReputation_1 = require("./moderationReputation");
+/* -------------------------------------------------------------------------- */
+/*  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.
+ */
+exports.REPUTATION_CATEGORIES = [
+    'content',
+    'social',
+    'trust',
+    'moderation',
+    'physical',
+    'penalty',
+    'other',
+];
+exports.reputationCategorySchema = zod_1.z.enum(exports.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.
+ */
+exports.REPUTATION_TRANSACTION_STATUSES = [
+    'active',
+    'disputed',
+    'reversed',
+    'voided',
+];
+exports.reputationTransactionStatusSchema = zod_1.z.enum(exports.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.
+ */
+exports.TRUST_TIERS = ['restricted', 'new', 'trusted', 'high_trust', 'verified'];
+exports.trustTierSchema = zod_1.z.enum(exports.TRUST_TIERS);
+/** Kind of entity a transaction may target. */
+exports.REPUTATION_TARGET_ENTITY_TYPES = [
+    'post',
+    'comment',
+    'report',
+    'purchase',
+    'event',
+    'check_in',
+    'manual_review',
+    'user',
+    'other',
+];
+exports.reputationTargetEntityTypeSchema = zod_1.z.enum(exports.REPUTATION_TARGET_ENTITY_TYPES);
+/** Dispute lifecycle status. */
+exports.REPUTATION_DISPUTE_STATUSES = [
+    'open',
+    'accepted',
+    'rejected',
+    'needs_review',
+];
+exports.reputationDisputeStatusSchema = zod_1.z.enum(exports.REPUTATION_DISPUTE_STATUSES);
+/** Influence context selecting which capped weight axis to read. */
+exports.REPUTATION_INFLUENCE_CONTEXTS = [
+    'default',
+    'report',
+    'moderation',
+    'ranking',
+];
+exports.reputationInfluenceContextSchema = zod_1.z.enum(exports.REPUTATION_INFLUENCE_CONTEXTS);
+exports.reputationTransactionSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    points: zod_1.z.number(),
+    actionType: zod_1.z.string(),
+    category: exports.reputationCategorySchema,
+    applicationId: zod_1.z.string().optional(),
+    credentialId: zod_1.z.string().optional(),
+    sourceActionId: zod_1.z.string().optional(),
+    sourceActionType: zod_1.z.string().optional(),
+    targetEntityId: zod_1.z.string().optional(),
+    targetEntityType: exports.reputationTargetEntityTypeSchema.optional(),
+    status: exports.reputationTransactionStatusSchema,
+    reversedTransactionId: zod_1.z.string().optional(),
+    reason: zod_1.z.string().optional(),
+    metadata: zod_1.z.record(zod_1.z.unknown()).optional(),
+    createdByUserId: zod_1.z.string().optional(),
+    reviewedByUserId: zod_1.z.string().optional(),
+    reviewedAt: zod_1.z.string().optional(),
+    createdAt: zod_1.z.string(),
+    updatedAt: zod_1.z.string(),
+});
+exports.reputationBalanceBreakdownSchema = zod_1.z.object({
+    content: zod_1.z.number(),
+    social: zod_1.z.number(),
+    trust: zod_1.z.number(),
+    moderation: zod_1.z.number(),
+    physical: zod_1.z.number(),
+    penalties: zod_1.z.number(),
+});
+exports.reputationInfluenceSchema = zod_1.z.object({
+    defaultWeight: zod_1.z.number(),
+    reportWeight: zod_1.z.number(),
+    moderationWeight: zod_1.z.number(),
+    rankingFeedbackWeight: zod_1.z.number(),
+});
+exports.reputationReliabilitySchema = zod_1.z.object({
+    accurateReports: zod_1.z.number(),
+    rejectedReports: zod_1.z.number(),
+    reportAccuracyScore: zod_1.z.number(),
+    abuseScore: zod_1.z.number(),
+});
+/** The fields both balance views share. Kept as a shape so the full view can spread it. */
+const balanceSummaryShape = {
+    userId: zod_1.z.string(),
+    total: zod_1.z.number(),
+    trustTier: exports.trustTierSchema,
+};
+exports.reputationBalanceSummarySchema = zod_1.z.object(balanceSummaryShape);
+exports.reputationBalanceSchema = zod_1.z.object({
+    ...balanceSummaryShape,
+    positive: zod_1.z.number(),
+    negative: zod_1.z.number(),
+    breakdown: exports.reputationBalanceBreakdownSchema,
+    influence: exports.reputationInfluenceSchema,
+    reliability: exports.reputationReliabilitySchema,
+    recalculatedAt: zod_1.z.string(),
+    updatedAt: zod_1.z.string(),
+    personhood: moderationReputation_1.reputationPersonhoodSchema.optional(),
+    contribution: moderationReputation_1.reputationContributionSchema.optional(),
+    conduct: moderationReputation_1.reputationConductSchema.optional(),
+    reporting: moderationReputation_1.reputationReportingSchema.optional(),
+    reviewing: moderationReputation_1.reputationReviewingSchema.optional(),
+    contextualInfluence: moderationReputation_1.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`.
+ */
+function isFullReputationBalance(balance) {
+    return FULL_BALANCE_FIELDS.every((field) => field in balance);
+}
+exports.reputationDisputeSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    transactionId: zod_1.z.string(),
+    userId: zod_1.z.string(),
+    reason: zod_1.z.string(),
+    status: exports.reputationDisputeStatusSchema,
+    evidence: zod_1.z.array(zod_1.z.string()).optional(),
+    resolvedAt: zod_1.z.string().optional(),
+    resolvedByUserId: zod_1.z.string().optional(),
+    createdAt: zod_1.z.string(),
+    updatedAt: zod_1.z.string(),
+});
+exports.reputationRuleSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    actionType: zod_1.z.string(),
+    points: zod_1.z.number(),
+    category: exports.reputationCategorySchema,
+    description: zod_1.z.string(),
+    cooldownInMinutes: zod_1.z.number(),
+    isEnabled: zod_1.z.boolean(),
+});
+exports.reputationLeaderboardUserSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    username: zod_1.z.string(),
+    name: userResponse_1.userNameSchema,
+    avatar: zod_1.z.string().optional(),
+    publicKey: zod_1.z.string().optional(),
+});
+exports.reputationLeaderboardEntrySchema = zod_1.z.object({
+    user: exports.reputationLeaderboardUserSchema,
+    total: zod_1.z.number(),
+    trustTier: exports.trustTierSchema,
+    rank: zod_1.z.number(),
+});
+exports.reputationInfluenceResultSchema = zod_1.z.object({
+    context: exports.reputationInfluenceContextSchema,
+    weight: zod_1.z.number(),
+    influence: exports.reputationInfluenceSchema,
+});
+exports.reverseReputationTransactionResultSchema = zod_1.z.object({
+    original: exports.reputationTransactionSchema,
+    reversal: exports.reputationTransactionSchema,
+});
+exports.awardReputationSchema = zod_1.z.object({
+    userId: zod_1.z.string().trim().min(1),
+    actionType: zod_1.z.string().trim().min(1),
+    applicationId: zod_1.z.string().trim().min(1).optional(),
+    credentialId: zod_1.z.string().trim().min(1).optional(),
+    sourceActionId: zod_1.z.string().trim().min(1).optional(),
+    sourceActionType: zod_1.z.string().trim().min(1).optional(),
+    targetEntityId: zod_1.z.string().trim().min(1).optional(),
+    targetEntityType: exports.reputationTargetEntityTypeSchema.optional(),
+    reason: zod_1.z.string().trim().max(500).optional(),
+    metadata: zod_1.z.record(zod_1.z.unknown()).optional(),
+});
+exports.createReputationDisputeSchema = zod_1.z.object({
+    transactionId: zod_1.z.string().trim().min(1),
+    reason: zod_1.z.string().trim().min(1).max(1000),
+    evidence: zod_1.z.array(zod_1.z.string().trim().min(1)).max(20).optional(),
+});
+exports.resolveReputationDisputeSchema = zod_1.z.object({
+    status: zod_1.z.enum(['accepted', 'rejected']),
+});
+exports.upsertReputationRuleSchema = zod_1.z.object({
+    actionType: zod_1.z.string().trim().min(1),
+    points: zod_1.z.number(),
+    category: exports.reputationCategorySchema,
+    description: zod_1.z.string().trim().min(1).max(500),
+    cooldownInMinutes: zod_1.z.number().int().min(0).default(0),
+    isEnabled: zod_1.z.boolean().default(true),
+});
+exports.reverseReputationTransactionSchema = zod_1.z.object({
+    reason: zod_1.z.string().trim().max(500).optional(),
+});

package/dist/cjs/userInvalidation.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oxyUserInvalidationEventSchema = exports.OXY_PUBLISHED_USER_CHANGE_REASONS = exports.OXY_USER_CHANGE_REASONS = exports.OXY_USER_INVALIDATION_CHANNEL = void 0;
+exports.isPublishedOxyUserChangeReason = isPublishedOxyUserChangeReason;
+const zod_1 = require("zod");
+/** Redis pub/sub channel carrying user-invalidation events. */
+exports.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}.
+ */
+exports.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.
+ */
+exports.OXY_PUBLISHED_USER_CHANGE_REASONS = ['profile'];
+/** Whether a change of this kind is broadcast to consumers at all. */
+function isPublishedOxyUserChangeReason(reason) {
+    return exports.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.
+ */
+exports.oxyUserInvalidationEventSchema = zod_1.z.object({
+    /** The Oxy user whose record changed. */
+    userId: zod_1.z.string().min(1),
+    /** Why it changed. Only broadcast reasons appear on the wire. */
+    reason: zod_1.z.enum(exports.OXY_PUBLISHED_USER_CHANGE_REASONS),
+    /** Publisher's epoch-ms timestamp. Diagnostic only. */
+    at: zod_1.z.number().int().nonnegative(),
+});