@oxyhq/contracts 0.18.0 → 0.20.0

package/dist/esm/commonsSignIn.js

@@ -0,0 +1,56 @@
+/**
+ * Canonical contract for the "Sign in with Oxy" approval handoff.
+ *
+ * SINGLE SOURCE OF TRUTH for the closed set of reasons an approver may attach
+ * when it DENIES a pending request via
+ * `POST /auth/session/deny/:authorizeCode`.
+ *
+ * That endpoint is UNAUTHENTICATED — the public `authorizeCode` is the only
+ * credential — so a free-form string from it is never stored: it would be an
+ * unauthenticated write of arbitrary text onto a record other surfaces read.
+ * The set is therefore deliberately tiny, and closed:
+ *
+ *  - `'declined'` the approver rejected a request they recognised ("Not now").
+ *  - `'not_me'`   the approver did not start the request ("This wasn't me").
+ *                 The ONE value that records the denial as suspicious rather
+ *                 than an ordinary cancel, so a UI may only offer it where the
+ *                 user genuinely said so.
+ *
+ * Why this lives in `@oxyhq/contracts` rather than in either consumer: the same
+ * closed set is enforced in three places — the request schema of the API route,
+ * the `enum` of the persisted `AuthSession.deniedReason` field, and the client
+ * SDK's `denyCommonsSignIn` parameter. Two hand-maintained copies of a wire
+ * contract drift the moment a value is added on one side only, and the failure
+ * lands at runtime, in an auth path, as a generic validation error. One
+ * declaration makes that impossible.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+/**
+ * The closed set, as a value — consumed directly where a runtime list is
+ * required (e.g. the Mongoose `enum` of `AuthSession.deniedReason`, which is
+ * the storage-level guarantee that an unauthenticated caller can never write
+ * free-form text into the field).
+ */
+export const COMMONS_DENY_REASONS = ['declined', 'not_me'];
+/**
+ * The same set as a zod enum — the edge validator. Anything outside it
+ * (including free-form text) is rejected with 400 before any handler runs.
+ */
+export const commonsDenyReasonSchema = z.enum(COMMONS_DENY_REASONS);
+/**
+ * Android notification channel id the identity-approval push is sent on.
+ *
+ * A wire contract for the same reason the deny set is: Android 8+ DROPS a
+ * notification whose channel id the app has not created, silently and with no
+ * client-side error. The API attaches this id when it sends, and the vault
+ * creates the channel with it before registering a push token — two hand-typed
+ * copies of that string would fail as "the notification never arrived", which
+ * is the single hardest push symptom to diagnose.
+ *
+ * The channel's user-visible NAME and description are deliberately NOT here:
+ * those are localized app copy, and the vault owns them.
+ */
+export const IDENTITY_APPROVAL_PUSH_CHANNEL = 'auth-approval';

package/dist/esm/deviceSession.js

@@ -57,28 +57,6 @@ export const deviceTokenMintResponseSchema = z.object({
     state: deviceSessionStateSchema,
 });
 /* -------------------------------------------------------------------------- */
-/*  Hub ticket — server-side cross-origin device credential sync               */
-/* -------------------------------------------------------------------------- */
-/** Request body for `POST /session/device/hub-ticket`. */
-export const deviceHubTicketIssueRequestSchema = z.object({
-    returnOrigin: z.string().min(1),
-});
-/** Response from `POST /session/device/hub-ticket`. */
-export const deviceHubTicketIssueResponseSchema = z.object({
-    ticket: z.string().min(1),
-    expiresIn: z.number().int().positive(),
-});
-/** Request body for `POST /session/device/redeem-ticket`. */
-export const deviceHubTicketRedeemRequestSchema = z.object({
-    ticket: z.string().min(1),
-    returnOrigin: z.string().min(1),
-});
-/** Response from `POST /session/device/redeem-ticket`. */
-export const deviceHubTicketRedeemResponseSchema = z.object({
-    deviceId: z.string().min(1),
-    deviceSecret: z.string().min(1),
-});
-/* -------------------------------------------------------------------------- */
 /*  Instant cross-app session sync (token-free socket signal)                 */
 /* -------------------------------------------------------------------------- */
 /**
@@ -119,3 +97,64 @@ export const sessionAccountsChangedEventSchema = z.object({
     revision: z.number().int().nonnegative(),
     reason: sessionAccountsChangedReasonSchema,
 });
+/* -------------------------------------------------------------------------- */
+/*  Background credential — native background code with no JS runtime         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Response from `POST /session/device/background-credential` — provisioned by
+ * the SDK WHILE THE APP IS RUNNING (bearer required, `deviceId` and account
+ * derived server-side from it) and consumed afterwards only by native
+ * background code, which has no JS runtime to mint a token for itself.
+ *
+ * Deliberately a SEPARATE credential from the rotating `deviceSecret`: that one
+ * rotates on every mint, so background code presenting it would become a second
+ * writer of a value the JS runtime depends on, and background code killed
+ * mid-rotation would silently sign the user out on the next cold start. Against
+ * this credential background code is the sole writer, and it can never rotate
+ * anything JS reads.
+ *
+ * The raw `secret` is returned exactly once, at provision time — never stored
+ * retrievably, never logged, never re-read. A caller that loses it provisions
+ * a new one.
+ *
+ * `expiresAt` is an unvalidated string, like every other expiry in this file:
+ * no consumer on the JS path interprets it (native background code parses it
+ * itself), and a `.datetime()` here alone would leave one strict field beside
+ * two lax ones. If expiry is ever validated it goes on all three at once, with
+ * the API's serializers checked against it — the producer is the same server.
+ */
+export const deviceBackgroundCredentialResponseSchema = z.object({
+    deviceId: z.string().min(1),
+    secret: z.string().min(1),
+    accountId: z.string().min(1),
+    expiresAt: z.string(),
+});
+/**
+ * Request body for `POST /session/device/background-token` — presented by
+ * native background code with NO bearer and NO cookies: possession of the
+ * background `secret` IS the proof, as it is for the device-secret mint.
+ *
+ * Unlike that mint this one NEVER rotates the presented secret (hence no
+ * `next…` field to persist in the response), so background code interrupted
+ * anywhere between request and response leaves the credential intact and
+ * usable on its next run.
+ */
+export const deviceBackgroundTokenRequestSchema = z.object({
+    deviceId: z.string().min(1),
+    secret: z.string().min(1),
+});
+/**
+ * Wire shape of a successful `POST /session/device/background-token`: the short
+ * access token, its expiry, and the account the token belongs to — the last so
+ * a caller can key cached data per account and drop data belonging to a
+ * foreign one.
+ *
+ * Carries NO device state — no account list, no `activeAccountId`, no
+ * `revision`, unlike {@link deviceTokenMintResponseSchema} — deliberately, to
+ * cap what a compromised credential record yields.
+ */
+export const deviceBackgroundTokenResponseSchema = z.object({
+    accessToken: z.string(),
+    expiresAt: z.string(),
+    accountId: z.string().min(1),
+});

package/dist/esm/inboxPush.js

@@ -0,0 +1,21 @@
+/**
+ * Canonical contract for Inbox new-mail push notifications.
+ *
+ * The Android channel id and payload `type` are wire contracts: Android 8+
+ * drops a notification whose channel the app has not created, and the client
+ * only routes taps it recognises. Two hand-typed copies of either string fail as
+ * "the notification never arrived" or "tapping does nothing" — the hardest push
+ * symptoms to diagnose.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/** Android notification channel id the new-mail push is sent on. */
+export const INBOX_EMAIL_PUSH_CHANNEL = 'email';
+/** Runtime type discriminator of the new-mail push payload. */
+export const INBOX_EMAIL_PUSH_TYPE = 'oxy_inbox_new_message';
+export const inboxEmailPushDataSchema = z.object({
+    type: z.literal(INBOX_EMAIL_PUSH_TYPE),
+    messageId: z.string().min(1),
+    mailboxId: z.string().min(1),
+});

package/dist/esm/index.js

@@ -19,6 +19,12 @@ export {
 // Schemas
 applicationTypeSchema, publicApplicationSchema, sessionStatusSchema, } from './sessionStatus.js';
 export { 
+// Closed set of denial reasons for POST /auth/session/deny/:authorizeCode —
+// shared by the API request schema, the persisted `AuthSession.deniedReason`
+// enum, and the SDK's `denyCommonsSignIn`.
+COMMONS_DENY_REASONS, commonsDenyReasonSchema, IDENTITY_APPROVAL_PUSH_CHANNEL, } from './commonsSignIn.js';
+export { INBOX_EMAIL_PUSH_CHANNEL, INBOX_EMAIL_PUSH_TYPE, inboxEmailPushDataSchema, } from './inboxPush.js';
+export { 
 // Schemas
 recommendationExcludeTypeSchema, recommendationBoostSchema, recommendationSignalWeightsSchema, recommendationRequestSchema, recommendationCountSchema, recommendationItemSchema, recommendationResponseSchema, appEndorsementInputSchema, appInterestInputSchema, appUserSignalIngestSchema, appAffinityEventTypeSchema, appAffinityEventSchema, appAffinityEventsIngestSchema, } from './recommendations.js';
 export { 
@@ -36,9 +42,22 @@ publicCardSchema, signedPublicCardSchema, realLifeAttestationRecordSchema, realL
 // Verifiable Credentials (Fase 4 — NEW)
 credentialRecordSchema, verifiableCredentialResponseSchema, credentialIssueResultSchema, credentialListResultSchema, credentialVerifyResultSchema, } from './civic.js';
 export { 
+// Closed value sets — shared by the API's mongoose enums, the API's request
+// validation, and the SDK's unions, so a new category/tier/status cannot be
+// added on one side only.
+REPUTATION_CATEGORIES, REPUTATION_TRANSACTION_STATUSES, TRUST_TIERS, REPUTATION_TARGET_ENTITY_TYPES, REPUTATION_DISPUTE_STATUSES, REPUTATION_INFLUENCE_CONTEXTS, 
+// Schemas — closed value sets
+reputationCategorySchema, reputationTransactionStatusSchema, trustTierSchema, reputationTargetEntityTypeSchema, reputationDisputeStatusSchema, reputationInfluenceContextSchema, 
+// Schemas — responses
+reputationTransactionSchema, reputationBalanceBreakdownSchema, reputationInfluenceSchema, reputationReliabilitySchema, reputationBalanceSummarySchema, reputationBalanceSchema, reputationDisputeSchema, reputationRuleSchema, reputationLeaderboardUserSchema, reputationLeaderboardEntrySchema, reputationInfluenceResultSchema, reverseReputationTransactionResultSchema, 
+// Schemas — request bodies
+awardReputationSchema, createReputationDisputeSchema, resolveReputationDisputeSchema, upsertReputationRuleSchema, reverseReputationTransactionSchema, 
+// Narrows the two balance views apart at runtime.
+isFullReputationBalance, } from './reputation.js';
+export { 
 // Schemas
 linkPreviewSchema, linkPreviewBatchRequestSchema, linkPreviewBatchResponseSchema, linkPreviewResponseSchema, } from './links.js';
-export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceHubTicketIssueRequestSchema, deviceHubTicketIssueResponseSchema, deviceHubTicketRedeemRequestSchema, deviceHubTicketRedeemResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
+export { sessionAccountSchema, deviceSessionStateSchema, activeTokenSchema, deviceSessionSyncSchema, deviceTokenMintRequestSchema, deviceTokenMintResponseSchema, deviceBackgroundCredentialResponseSchema, deviceBackgroundTokenRequestSchema, deviceBackgroundTokenResponseSchema, SESSION_ACCOUNTS_CHANGED_EVENT, sessionAccountsChangedReasonSchema, sessionAccountsChangedEventSchema, } from './deviceSession.js';
 export { 
 // Schemas
 loginResultSchema, } from './deviceBoot.js';

package/dist/esm/reputation.js

@@ -0,0 +1,281 @@
+/**
+ * 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';
+/* -------------------------------------------------------------------------- */
+/*  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(),
+});
+/**
+ * Every field the full {@link ReputationBalance} carries beyond the public
+ * {@link ReputationBalanceSummary}. The runtime discriminant between the two
+ * views — the API sends this set all-or-nothing.
+ */
+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(),
+});