@oxy.so/contracts 4.16.0 → 4.21.0

package/dist/esm/client/identityProof.js

@@ -0,0 +1,104 @@
+/**
+ * The identity-proof message format, without Zod. Schemas: `../identityProof.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+export const IDENTITY_PROOF_VERSION = 2;
+export const IDENTITY_PROOF_DOMAIN = 'oxy-identity-proof';
+/** The audience every API-verified identity proof names. */
+export const IDENTITY_PROOF_AUDIENCE = 'oxy-api/identity';
+/** How long a proof challenge lives: one interactive ceremony. */
+export const IDENTITY_PROOF_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Everything a root proof may authorize. A challenge is minted for exactly one
+ * action and spent only by a proof for that action.
+ */
+export const IDENTITY_PROOF_ACTIONS = {
+    /**
+     * Link Commons' root to an account that has none (`POST /auth/link`).
+     * The account becomes self-custodied and its email is deleted
+     * (ADR 0029 D3).
+     */
+    link: 'link_identity',
+};
+export const IDENTITY_PROOF_ACTION_VALUES = Object.values(IDENTITY_PROOF_ACTIONS);
+export const HEX_DIGEST = /^[0-9a-f]{64}$/;
+export const ROOT_KEY = /^04[0-9a-f]{128}$/;
+export const CHALLENGE = /^[0-9a-f]{64}$/;
+/**
+ * Canonical JSON: object keys sorted by UTF-16 code unit, no whitespace,
+ * `undefined` members omitted, arrays in order. Numbers must be finite. This is
+ * the ONLY serializer for anything digested into a proof.
+ */
+export function canonicalJson(value) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'string':
+        case 'boolean':
+            return JSON.stringify(value);
+        case 'number':
+            if (!Number.isFinite(value))
+                throw new Error('canonicalJson: non-finite number');
+            return JSON.stringify(value);
+        case 'object': {
+            if (Array.isArray(value)) {
+                return `[${value.map((entry) => (entry === undefined ? 'null' : canonicalJson(entry))).join(',')}]`;
+            }
+            const record = value;
+            const keys = Object.keys(record)
+                .filter((key) => record[key] !== undefined)
+                .sort();
+            return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+        }
+        default:
+            throw new Error(`canonicalJson: unsupported ${typeof value}`);
+    }
+}
+/**
+ * The exact bytes a root signs. Throws on a malformed claim rather than signing
+ * (or verifying) something ambiguous.
+ */
+export function buildIdentityProofMessage(claims) {
+    if (!IDENTITY_PROOF_ACTION_VALUES.includes(claims.action))
+        throw new Error('identity proof: unknown action');
+    if (!claims.subject || !claims.actor)
+        throw new Error('identity proof: subject and actor are required');
+    if (!ROOT_KEY.test(claims.rootPublicKey))
+        throw new Error('identity proof: rootPublicKey must be canonical');
+    if (claims.payloadDigest !== null && !HEX_DIGEST.test(claims.payloadDigest)) {
+        throw new Error('identity proof: payloadDigest must be a lowercase SHA-256 hex digest');
+    }
+    if (claims.expectedRevision !== null &&
+        (!Number.isSafeInteger(claims.expectedRevision) || claims.expectedRevision < 0)) {
+        throw new Error('identity proof: expectedRevision must be a non-negative integer');
+    }
+    if (!CHALLENGE.test(claims.challenge))
+        throw new Error('identity proof: challenge must be 64 lowercase hex characters');
+    if (!Number.isSafeInteger(claims.expiresAt) || claims.expiresAt <= 0)
+        throw new Error('identity proof: expiresAt must be unix milliseconds');
+    return canonicalJson({
+        v: IDENTITY_PROOF_VERSION,
+        domain: IDENTITY_PROOF_DOMAIN,
+        action: claims.action,
+        subject: claims.subject,
+        actor: claims.actor,
+        rootPublicKey: claims.rootPublicKey,
+        payloadDigest: claims.payloadDigest,
+        expectedRevision: claims.expectedRevision,
+        audience: claims.audience,
+        challenge: claims.challenge,
+        expiresAt: claims.expiresAt,
+    });
+}
+/**
+ * Stable error codes the root routes answer with (`error.code` in the API error
+ * body). Clients map these through their localization, never the English message.
+ */
+export const IDENTITY_ERROR_CODES = {
+    proofInvalid: 'IDENTITY_PROOF_INVALID',
+    rootAlreadyLinked: 'IDENTITY_ROOT_ALREADY_LINKED',
+    rootLinkedElsewhere: 'IDENTITY_ROOT_LINKED_ELSEWHERE',
+    freshFactorRequired: 'IDENTITY_FRESH_FACTOR_REQUIRED',
+    notPersonal: 'IDENTITY_NOT_PERSONAL_ACCOUNT',
+};

package/dist/esm/client/index.js

@@ -0,0 +1,37 @@
+/**
+ * `@oxy.so/contracts/client` — the contracts without Zod, for client bundles.
+ *
+ * The root entry is the contract: Zod schemas the API parses with, and the
+ * types inferred from them. Zod's runtime is ~120 KB of JavaScript, evaluated
+ * at startup, that a client only needed to answer "does this response have
+ * the shape its type promises". This entry answers that with small structural
+ * checks (`*Check`, used through {@link checkContract} / {@link parseContract}),
+ * and carries the constants and pure helpers clients use, so an app or SDK
+ * that imports only from here ships no Zod at all.
+ *
+ * Every check is the twin of one schema in the root entry: it is tied to the
+ * schema's type at compile time (`exact` in `./check.ts`) and to its runtime
+ * behaviour by `__tests__/clientChecks.parity.test.ts`. Types are not repeated
+ * here; import them from `@oxy.so/contracts` with `import type`.
+ */
+export { ContractCheckError, checkContract, formatCheckPath, parseContract, } from './check.js';
+export { ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, ACCOUNT_KINDS, CHILD_ACCOUNT_KINDS, MAX_ACCOUNT_CATEGORIES, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, isAccountKind, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, isSelectableAccountCategoryId, kindAcceptsAccountCategories, newlyAddedRetiredCategories, } from './accountGraph.js';
+export { EMAIL_CODE_LENGTH, EMAIL_CODE_MAX_ATTEMPTS, EMAIL_CODE_TTL_MS, EMAIL_TICKET_TTL_MS, EMAIL_VERIFICATION_ERROR_CODES, EMAIL_VERIFICATION_PURPOSES, emailAddressCheck, emailTicketCheck, emailVerificationConfirmResponseCheck, emailVerificationStartResponseCheck, } from './accountEmail.js';
+export { ACCOUNT_AUTH_METHODS, AGENT_PROOF_ACTIONS, AGENT_PROOF_AUDIENCE, AGENT_PROOF_TTL_MS, agentChallengeRequestCheck, agentKeyListResponseCheck, agentKeyOperationChallengeCheck, agentKeyOperationCheck, agentKeyOperationResultCheck, agentProofClaimsCheck, agentVerifyRequestCheck, executeAgentKeyOperationCheck, } from './agentKeys.js';
+export { isLoopbackOrigin } from '../capabilityBindings.js';
+export { loginResultCheck } from './deviceBoot.js';
+export { externalIdentityReferenceCheck } from './externalIdentity.js';
+export { signedRecordEnvelopeCheck } from './identity.js';
+export { deviceActivateResponseCheck, deviceDirectoryCheck, deviceDirectorySyncCheck, } from './deviceDirectory.js';
+export { SESSION_ACCOUNTS_CHANGED_EVENT, activeTokenCheck, deviceBackgroundCredentialResponseCheck, deviceJoinCodeResponseCheck, deviceJoinResponseCheck, deviceRegisterResponseCheck, deviceSessionStateCheck, deviceSessionSyncCheck, deviceTokenMintResponseCheck, sessionAccountsChangedEventCheck, } from './deviceSession.js';
+export { IDENTITY_LINK_QR_PREFIX, IDENTITY_LINK_STATUSES, buildIdentityLinkQrPayload, identityLinkCreateResponseCheck, identityLinkStateCheck, parseIdentityLinkQrPayload, } from './identityLink.js';
+export { IDENTITY_ERROR_CODES, IDENTITY_PROOF_ACTIONS, IDENTITY_PROOF_ACTION_VALUES, IDENTITY_PROOF_AUDIENCE, IDENTITY_PROOF_CHALLENGE_TTL_MS, IDENTITY_PROOF_DOMAIN, IDENTITY_PROOF_VERSION, buildIdentityProofMessage, canonicalJson, } from './identityProof.js';
+export { ORGANIZATION_ALIAS_KINDS, ORGANIZATION_CLAIM_DECISIONS, ORGANIZATION_CLAIM_STATUSES, ORGANIZATION_ERROR_CODES, ORGANIZATION_NAME_MAX_LENGTH, ORGANIZATION_STATUSES, ORGANIZATION_TYPES, createOrganizationCheck, organizationBatchCheck, organizationCheck, organizationClaimCheck, organizationClaimDetailCheck, organizationClaimInputCheck, organizationClaimListCheck, organizationClaimReviewCheck, organizationCurationResultCheck, organizationExternalCheck, organizationExternalResolutionCheck, organizationImportBatchResultCheck, organizationListCheck, organizationNameCheck, updateOrganizationCheck, } from './organizations.js';
+export { cancelProductSubscriptionCheck, personalPlanCatalogueCheck, personalPlanCheckoutRequestCheck, personalPlanCheckoutResultCheck, productSubscriptionCancellationResultCheck, productSubscriptionsResponseCheck, subjectProductAccessCheck, subjectProductAccessQueryCheck, subscriptionCreditGrantsResponseCheck, } from './products.js';
+export { recommendationRequestCheck } from './recommendations.js';
+export { isFullReputationBalance } from './reputation.js';
+export { PURCHASE_APPROVAL_STATUSES, SAFETY_POLICY_VERSION, SUPERVISED_ACTIONS, SUPERVISION_CONSENT_VERSION, SUPERVISION_INVITATION_STATUSES, SUPERVISION_STATUSES, profileAccessDecisionCheck, profileAccessInputCheck, purchaseApprovalCheck, purchaseApprovalListCheck, purchaseReviewInputCheck, safetyOrganizationsInputCheck, safetyOrganizationsResponseCheck, safetyPeopleInputCheck, safetyPeopleResponseCheck, supervisionAcceptInputCheck, supervisionContactInputCheck, supervisionContactsResponseCheck, supervisionInvitationCheck, supervisionInviteInputCheck, supervisionReviewInputCheck, supervisionStateCheck, } from './safety.js';
+export { publicApplicationCheck } from './sessionStatus.js';
+export { EMAIL_ACCOUNTS_MAX, EMAIL_SIGNIN_CHOICE_TTL_MS, EMAIL_SIGNIN_LINK_TTL_MS, EMAIL_SIGNIN_LONG_CODE_ALPHABET, EMAIL_SIGNIN_LONG_CODE_LENGTH, PASSWORD_MAX_LENGTH, PASSWORD_MIN_LENGTH, REAUTH_ACTIONS, SIGNIN_SECOND_FACTOR_MAX_ATTEMPTS, SIGNIN_SECOND_FACTOR_TTL_MS, SIGN_IN_ERROR_CODES, TOTP_BACKUP_CODE_COUNT, TOTP_DIGITS, TOTP_PERIOD_SECONDS, emailSignInChooseAccountCheck, emailSignInLinkResponseCheck, emailSignInPendingCheck, emailSignInStartResponseCheck, isEmailSignInChooseAccount, isSecondFactorRequired, normalizeEmailSignInCode, reauthProofCheck, secondFactorRequiredCheck, signInMethodsCheck, totpBackupCodesResponseCheck, totpEnrollResponseCheck, } from './signIn.js';
+export { BOT_USERNAME_INVALID_MESSAGE, BOT_USERNAME_SUFFIX, NUMERIC_USERNAME_MESSAGE, RESERVED_USERNAMES, RESERVED_USERNAME_MESSAGE, USERNAME_INVALID_MESSAGE, USERNAME_MAX_LENGTH, USERNAME_MIN_LENGTH, USERNAME_PATTERN_SOURCE, applyBotUsernameSuffix, botUsernameCheck, stripDisallowedUsernameCharacters, usernameCheck, usernameCheckForAccountKind, } from './username.js';
+export { userNameCheck } from './userResponse.js';

package/dist/esm/client/organizations.js

@@ -0,0 +1,111 @@
+/**
+ * Organization vocabularies and checks, without Zod. Schemas: `../organizations.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { array, boolean, datetime, exact, maxItems, maxLength, minLength, nullable, oneOf, optional, pattern, refine, strictObject, string, trim, url, } from './check.js';
+/** Real-world identity classification, independent of account topics and permissions. */
+export const ORGANIZATION_TYPES = [
+    'business',
+    'nonprofit',
+    'public_body',
+    'community',
+    'other',
+];
+export const ORGANIZATION_STATUSES = ['active', 'inactive', 'merged', 'suppressed'];
+export const ORGANIZATION_CLAIM_STATUSES = ['unclaimed', 'claimed'];
+export const ORGANIZATION_ALIAS_KINDS = [
+    'name_variant',
+    'former_name',
+    'localized_name',
+    'marketing_name',
+    'misspelling',
+];
+export const ORGANIZATION_CLAIM_DECISIONS = ['pending', 'approved', 'rejected'];
+export const ORGANIZATION_NAME_MAX_LENGTH = 300;
+export const ORGANIZATION_ERROR_CODES = [
+    'bad_request',
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'unknown_route',
+    'conflict',
+    'validation_failed',
+    'rate_limited',
+    'internal_error',
+    'service_unavailable',
+];
+/* -------------------------------------------------------------------------- */
+/*  Checks                                                                    */
+/* -------------------------------------------------------------------------- */
+const id = string(minLength(1), maxLength(128));
+const optionalText = (max) => optional(nullable(string(trim, minLength(1), maxLength(max))));
+const evidenceReference = string(trim, minLength(1), maxLength(1000));
+const createdAt = string(datetime);
+const organizationAlias = strictObject({
+    alias: string(trim, minLength(1), maxLength(300)),
+    kind: oneOf(ORGANIZATION_ALIAS_KINDS),
+    language: optional(string(minLength(2), maxLength(35))),
+});
+/** The twin of `organizationNameSchema`. */
+export const organizationNameCheck = refine(string(trim, minLength(1), maxLength(ORGANIZATION_NAME_MAX_LENGTH)), (value) => !/[<>]/.test(value) &&
+    Array.from(value).every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127), 'Organization name must be plain text');
+const organizationFields = {
+    name: organizationNameCheck,
+    organizationType: oneOf(ORGANIZATION_TYPES),
+    legalName: optionalText(300),
+    websiteUrl: optional(nullable(refine(string(url, maxLength(2048)), (value) => /^https?:\/\//.test(value), 'Use HTTP or HTTPS'))),
+    countryCode: optional(nullable(string(pattern(/^[A-Z]{2}$/)))),
+    aliases: optional(array(organizationAlias, maxItems(100))),
+};
+export const createOrganizationCheck = exact()(strictObject(organizationFields));
+export const updateOrganizationCheck = exact()(strictObject({
+    ...organizationFields,
+    name: optional(organizationNameCheck),
+    organizationType: optional(organizationFields.organizationType),
+}));
+export const organizationCheck = exact()(strictObject({
+    name: organizationNameCheck,
+    organizationType: oneOf(ORGANIZATION_TYPES),
+    legalName: nullable(string()),
+    websiteUrl: nullable(string()),
+    countryCode: nullable(string()),
+    aliases: array(organizationAlias),
+    accountId: id,
+    username: nullable(string()),
+    avatar: nullable(string()),
+    verifiedDomains: array(string()),
+    claimStatus: oneOf(ORGANIZATION_CLAIM_STATUSES),
+    status: oneOf(ORGANIZATION_STATUSES),
+    mergedIntoAccountId: nullable(id),
+    createdAt,
+    updatedAt: string(datetime),
+}));
+export const organizationListCheck = exact()(strictObject({ items: array(organizationCheck), nextCursor: nullable(string()) }));
+export const organizationBatchCheck = exact()(strictObject({
+    items: array(strictObject({ requestedAccountId: id, organization: organizationCheck })),
+    missingIds: array(id),
+}));
+export const organizationClaimInputCheck = exact()(strictObject({ evidenceReference }));
+const organizationClaimFields = {
+    id,
+    accountId: id,
+    claimantUserId: id,
+    status: oneOf(ORGANIZATION_CLAIM_DECISIONS),
+    createdAt,
+};
+export const organizationClaimCheck = exact()(strictObject(organizationClaimFields));
+export const organizationClaimDetailCheck = exact()(strictObject({
+    ...organizationClaimFields,
+    evidenceReference: string(),
+    reviewEvidenceReference: nullable(string()),
+    reviewedAt: nullable(string(datetime)),
+}));
+export const organizationClaimListCheck = exact()(strictObject({ items: array(organizationClaimDetailCheck), nextCursor: nullable(string()) }));
+export const organizationClaimReviewCheck = exact()(strictObject({ decision: oneOf(['approved', 'rejected']), evidenceReference }));
+export const organizationImportBatchResultCheck = exact()(strictObject({
+    items: array(strictObject({ externalId: string(), accountId: id, created: boolean })),
+}));
+export const organizationExternalCheck = exact()(strictObject({ accountId: id, created: boolean }));
+export const organizationExternalResolutionCheck = exact()(strictObject({ accountId: id }));
+export const organizationCurationResultCheck = exact()(strictObject({ accountId: id, status: oneOf(['active', 'inactive', 'suppressed']) }));

package/dist/esm/client/products.js

@@ -0,0 +1,150 @@
+/**
+ * Product access, plans, checkout and subscription checks, without Zod.
+ * Schemas: `../products/*.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { array, boolean, branded, datetime, discriminatedUnion, exact, int, literal, maxLength, minLength, nonnegative, nullable, number, oneOf, optional, pattern, positive, refine, safe, startsWith, strictObject, string, union, url, } from './check.js';
+const identifier = string(minLength(1), maxLength(160));
+const displayName = string(minLength(1), maxLength(100));
+const count = number(int, nonnegative, safe);
+const version = number(int, positive, safe);
+const oxyAccountId = branded(string(minLength(1), maxLength(64)));
+const actionKey = string(minLength(8), maxLength(160), pattern(/^[a-zA-Z0-9_-]+$/));
+const combination = oneOf(['maximum', 'sum', 'exclusive']);
+const origin = oneOf(['individual', 'bundle']);
+const period = (message) => refine(strictObject({ start: string(datetime), end: string(datetime) }), (value) => Date.parse(value.end) > Date.parse(value.start), message);
+const productBenefit = discriminatedUnion('kind', {
+    capability: strictObject({ kind: literal('capability'), productId: identifier, key: identifier }),
+    quota: strictObject({
+        kind: literal('quota'),
+        productId: identifier,
+        key: identifier,
+        unit: identifier,
+        included: count,
+        combination,
+    }),
+});
+export const subjectProductAccessQueryCheck = exact()(strictObject({
+    schemaVersion: literal(1),
+    subjectAccountId: oxyAccountId,
+    productId: identifier,
+}));
+export const subjectProductAccessCheck = exact()(strictObject({
+    schemaVersion: literal(1),
+    subjectAccountId: oxyAccountId,
+    productId: identifier,
+    evaluatedAt: string(datetime),
+    capabilities: array(strictObject({ key: identifier, grantIds: array(identifier) })),
+    quotas: array(strictObject({
+        key: identifier,
+        unit: identifier,
+        included: count,
+        combination,
+        grantIds: array(identifier),
+    })),
+    conflicts: array(strictObject({
+        key: identifier,
+        reason: oneOf([
+            'combination_mismatch',
+            'unit_mismatch',
+            'exclusive_overlap',
+            'unsafe_total',
+        ]),
+        grantIds: array(identifier),
+    })),
+}));
+export const personalPlanCatalogueCheck = exact()(refine(strictObject({
+    schemaVersion: literal(1),
+    state: oneOf(['unconfigured', 'configured']),
+    purchase: literal('unavailable'),
+    plans: array(strictObject({
+        offerId: identifier,
+        offerVersion: version,
+        displayName,
+        audience: literal('personal'),
+        kind: literal('oxy_one'),
+        price: optional(strictObject({
+            currency: string(pattern(/^[A-Z]{3}$/)),
+            amountMinorUnits: version,
+            interval: literal('month'),
+            trial: literal('none'),
+            taxTreatment: literal('inclusive'),
+            merchantTotal: literal('final'),
+        })),
+        benefits: array(strictObject({ displayName, benefit: productBenefit })),
+    })),
+}), (value) => (value.state === 'unconfigured') === (value.plans.length === 0), 'Catalogue state must match published plans'));
+export const personalPlanCheckoutRequestCheck = exact()(strictObject({
+    expectedSubjectAccountId: oxyAccountId,
+    offerId: identifier,
+    offerVersion: version,
+    idempotencyKey: actionKey,
+}));
+export const personalPlanCheckoutResultCheck = exact()(discriminatedUnion('state', {
+    unconfigured: strictObject({
+        state: literal('unconfigured'),
+        reason: oneOf(['provider_unconfigured', 'offer_unconfigured', 'price_unconfigured']),
+    }),
+    pending: strictObject({
+        state: literal('pending'),
+        intentId: identifier,
+        checkoutUrl: optional(string(url, startsWith('https://'))),
+    }),
+    closed: strictObject({ state: literal('closed'), intentId: identifier }),
+    fulfilled: strictObject({ state: literal('fulfilled'), intentId: identifier }),
+}));
+const billingPeriod = period('Period end must follow start');
+export const productSubscriptionsResponseCheck = exact()(strictObject({
+    subscriptions: array(strictObject({
+        sourceId: identifier,
+        status: oneOf([
+            'active',
+            'trialing',
+            'past_due',
+            'unpaid',
+            'canceled',
+            'paused',
+            'incomplete',
+            'incomplete_expired',
+        ]),
+        period: billingPeriod,
+        cancelAtPeriodEnd: boolean,
+        canCancel: boolean,
+        offers: array(strictObject({
+            segmentId: identifier,
+            offerId: identifier,
+            offerVersion: version,
+            displayName,
+            origin,
+            period: billingPeriod,
+            current: boolean,
+            products: array(strictObject({ id: identifier, displayName })),
+        })),
+    })),
+}));
+export const subscriptionCreditGrantsResponseCheck = exact()(strictObject({
+    grants: array(refine(strictObject({
+        id: identifier,
+        invoiceId: identifier,
+        origin: oneOf([
+            'subscription_payment',
+            'subscription_proration',
+            'subscription_promotional_grant',
+        ]),
+        period: billingPeriod,
+        granted: count,
+        consumed: count,
+        clawed: count,
+        remaining: count,
+        promotionId: nullable(identifier),
+        createdAt: string(datetime),
+    }), (value) => BigInt(value.consumed) + BigInt(value.clawed) + BigInt(value.remaining) ===
+        BigInt(value.granted), 'Grant conservation differs')),
+}));
+export const cancelProductSubscriptionCheck = exact()(strictObject({
+    sourceId: identifier,
+    actionId: optional(actionKey),
+    expectedSubjectAccountId: optional(oxyAccountId),
+}));
+export const productSubscriptionCancellationResultCheck = exact()(union(strictObject({ sourceId: identifier, cancelAtPeriodEnd: literal(true) }), strictObject({ sourceId: identifier, reconciliationPending: literal(true) })));

package/dist/esm/client/recommendations.js

@@ -0,0 +1,30 @@
+/**
+ * The recommendation-request check, without Zod. Schemas: `../recommendations.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { array, atLeast, atMost, exact, int, maxItems, maxLength, minItems, minLength, number, object, oneOf, optional, string, trim, } from './check.js';
+const id = string(trim, minLength(1));
+const weight = optional(number(atLeast(0), atMost(10)));
+export const recommendationRequestCheck = exact()(object({
+    clientId: optional(string(trim, minLength(1))),
+    limit: optional(number(int, atLeast(1), atMost(100))),
+    offset: optional(number(int, atLeast(0))),
+    excludeTypes: optional(array(oneOf(['federated', 'agent', 'automated']))),
+    excludeIds: optional(array(id, maxItems(500))),
+    boosts: optional(array(object({
+        userIds: array(id, minItems(1), maxItems(200)),
+        weight: number(atLeast(-5), atMost(5)),
+        reason: optional(string(trim, maxLength(120))),
+    }), maxItems(50))),
+    signalWeights: optional(object({
+        graph: weight,
+        completeness: weight,
+        verified: weight,
+        curation: weight,
+        interest: weight,
+        appBoost: weight,
+        repCandidate: weight,
+        affinity: weight,
+    })),
+}));

package/dist/esm/client/reputation.js

@@ -0,0 +1,37 @@
+/**
+ * The reputation view guard, without Zod. Schemas: `../reputation.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+/**
+ * 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.
+ */
+export 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);
+}

package/dist/esm/client/safety.js

@@ -0,0 +1,193 @@
+/**
+ * Safety and supervision checks, without Zod. Schemas: `../safety.ts`.
+ *
+ * Only what a browser or device sends and reads is here: the profile-access
+ * read, supervision management and the guardian's purchase review. The service
+ * decision lanes are server-only (`@oxy.so/core/server`) and parse with the
+ * Zod schemas directly.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { array, atLeast, atMost, boolean, datetime, exact, int, literal, maxItems, maxLength, minItems, minLength, nonnegative, nullable, number, oneOf, optional, pattern, refine, refineAt, strictObject, string, transform, trim, union, } from './check.js';
+import { ORGANIZATION_TYPES } from './organizations.js';
+import { reauthProofCheck } from './signIn.js';
+/** Supervision is a personal-account safety policy, never a new login/account kind. */
+export const SUPERVISED_ACTIONS = ['profile', 'messaging', 'content', 'purchases'];
+export const SAFETY_POLICY_VERSION = '2';
+export const SUPERVISION_CONSENT_VERSION = '1';
+export const SUPERVISION_STATUSES = ['active', 'orphaned', 'ended'];
+export const SUPERVISION_INVITATION_STATUSES = ['pending', 'accepted', 'cancelled'];
+export const PURCHASE_APPROVAL_STATUSES = [
+    'pending',
+    'approved',
+    'rejected',
+    'reserved',
+    'confirmed',
+    'cancelled',
+];
+export const profileAccessInputCheck = exact()(strictObject({ subjectAccountId: string(minLength(1), maxLength(128)) }));
+export const profileAccessDecisionCheck = exact()(strictObject({
+    allowed: boolean,
+    reason: oneOf(['public', 'owner', 'private', 'blocked', 'unavailable']),
+    policyVersion: literal('1'),
+}));
+const accountId = string(minLength(1), maxLength(128));
+const resourceId = string(trim, minLength(1), maxLength(256));
+const uniqueIds = (max) => refine(array(accountId, minItems(1), maxItems(max)), (ids) => new Set(ids).size === ids.length, 'Account IDs must be unique');
+/* -------------------------------------------------------------------------- */
+/*  Supervision management                                                    */
+/* -------------------------------------------------------------------------- */
+const supervisionCheck = exact()(strictObject({
+    childAccountId: accountId,
+    guardianAccountId: nullable(accountId),
+    status: oneOf(SUPERVISION_STATUSES),
+    policyVersion: literal(SAFETY_POLICY_VERSION),
+    consentVersion: literal(SUPERVISION_CONSENT_VERSION),
+    createdAt: string(datetime),
+}));
+export const supervisionInvitationCheck = exact()(strictObject({
+    id: accountId,
+    childAccountId: accountId,
+    guardianAccountId: accountId,
+    status: oneOf(SUPERVISION_INVITATION_STATUSES),
+    expiresAt: string(datetime),
+    consentVersion: literal(SUPERVISION_CONSENT_VERSION),
+    createdAt: string(datetime),
+}));
+export const supervisionStateCheck = exact()(strictObject({
+    self: nullable(supervisionCheck),
+    children: array(supervisionCheck, maxItems(100)),
+    invitations: array(supervisionInvitationCheck, maxItems(100)),
+}));
+export const supervisionContactsResponseCheck = exact()(strictObject({
+    items: array(strictObject({
+        childAccountId: accountId,
+        contactAccountId: accountId,
+        approvedAt: string(datetime),
+    }), maxItems(1000)),
+}));
+export const supervisionInviteInputCheck = exact()(strictObject({
+    guardianAccountId: accountId,
+    consentVersion: literal(SUPERVISION_CONSENT_VERSION),
+    reauth: reauthProofCheck,
+}));
+export const supervisionAcceptInputCheck = exact()(strictObject({ consentVersion: literal(SUPERVISION_CONSENT_VERSION), reauth: reauthProofCheck }));
+export const supervisionContactInputCheck = exact()(strictObject({
+    childAccountId: accountId,
+    contactAccountId: accountId,
+    reauth: reauthProofCheck,
+}));
+export const supervisionReviewInputCheck = exact()(strictObject({
+    childAccountId: accountId,
+    action: oneOf(['end', 'transfer']),
+    guardianAccountId: optional(accountId),
+    evidenceReference: string(trim, minLength(1), maxLength(2048)),
+    reauth: reauthProofCheck,
+}));
+/* -------------------------------------------------------------------------- */
+/*  Minimal identities for the management screens                            */
+/* -------------------------------------------------------------------------- */
+const safetyPersonCheck = exact()(strictObject({ accountId, username: nullable(string()), displayName: nullable(string()) }));
+export const safetyPeopleInputCheck = exact()(union(strictObject({ query: string(trim, minLength(2), maxLength(100)) }), strictObject({ accountIds: uniqueIds(100) })));
+export const safetyPeopleResponseCheck = exact()(strictObject({ items: array(safetyPersonCheck, maxItems(100)) }));
+export const safetyOrganizationsInputCheck = exact()(union(strictObject({
+    query: string(trim, minLength(1), maxLength(100)),
+    limit: optional(number(int, atLeast(1), atMost(20))),
+}), strictObject({ ids: uniqueIds(100) })));
+export const safetyOrganizationsResponseCheck = exact()(strictObject({
+    items: array(strictObject({
+        requestedAccountId: accountId,
+        organization: strictObject({
+            accountId,
+            username: nullable(string()),
+            name: string(),
+            organizationType: oneOf(ORGANIZATION_TYPES),
+        }),
+    }), maxItems(100)),
+    missingIds: array(accountId, maxItems(100)),
+}));
+/* -------------------------------------------------------------------------- */
+/*  Purchase approvals                                                        */
+/* -------------------------------------------------------------------------- */
+const fingerprint = string(pattern(/^[a-f0-9]{64}$/));
+const minorUnits = number(int, nonnegative, atMost(Number.MAX_SAFE_INTEGER));
+const purchaseApprovalLineCheck = exact()(strictObject({
+    itemReference: resourceId,
+    title: string(trim, minLength(1), maxLength(300)),
+    optionsText: string(trim, maxLength(300)),
+    merchantAccountId: accountId,
+    quantity: number(int, atLeast(1), atMost(1000000)),
+    unitAmountMinor: minorUnits,
+    lineAmountMinor: minorUnits,
+}));
+/** The effect fields every approval shape shares, in the schema's key order. */
+const purchaseEffectFields = {
+    operationId: resourceId,
+    resourceId,
+    cartFingerprint: fingerprint,
+    summary: string(trim, minLength(1), maxLength(300)),
+    merchantAccountIds: transform(refine(array(accountId, minItems(1), maxItems(100)), (ids) => new Set(ids).size === ids.length, 'Merchant accounts must be unique'), (ids) => [...ids].sort()),
+};
+const purchaseAmountFields = {
+    shippingMinor: minorUnits,
+    taxMinor: minorUnits,
+    discountMinor: minorUnits,
+    roundingAdjustmentMinor: number(int, atLeast(-Number.MAX_SAFE_INTEGER), atMost(Number.MAX_SAFE_INTEGER)),
+    paymentFingerprint: fingerprint,
+    amountMinor: minorUnits,
+    currency: string(pattern(/^[A-Z]{3}$/)),
+    expiresAt: string(datetime),
+};
+const purchaseApprovalFields = {
+    id: accountId,
+    childAccountId: accountId,
+    applicationId: accountId,
+    status: oneOf(PURCHASE_APPROVAL_STATUSES),
+    createdAt: string(datetime),
+    receiptReference: nullable(string(maxLength(512))),
+};
+/** The first problem `validatePurchaseEvidence` in `../safety.ts` reports, in its order. */
+function purchaseEvidenceProblem(value) {
+    const merchants = new Set(value.merchantAccountIds);
+    const references = new Set();
+    for (const line of value.lineItems) {
+        const key = `${line.merchantAccountId}:${line.itemReference}`;
+        if (!merchants.has(line.merchantAccountId) || references.has(key)) {
+            return {
+                path: [],
+                message: 'Purchase lines must name an included merchant and unique item reference',
+            };
+        }
+        references.add(key);
+    }
+    if (merchants.size !== new Set(value.lineItems.map((line) => line.merchantAccountId)).size) {
+        return { path: [], message: 'Every merchant must have an approval line' };
+    }
+    const total = value.lineItems.reduce((sum, line) => sum + BigInt(line.lineAmountMinor), 0n) +
+        BigInt(value.shippingMinor) +
+        BigInt(value.taxMinor) -
+        BigInt(value.discountMinor) +
+        BigInt(value.roundingAdjustmentMinor);
+    if (total < 0n ||
+        total > BigInt(Number.MAX_SAFE_INTEGER) ||
+        total !== BigInt(value.amountMinor)) {
+        return { path: [], message: 'Approval evidence must equal the exact payment total' };
+    }
+    if (Math.abs(value.roundingAdjustmentMinor) >
+        value.lineItems.length + 3 * value.merchantAccountIds.length) {
+        return { path: [], message: 'Rounding adjustment exceeds the bounded conversion stages' };
+    }
+    return undefined;
+}
+export const purchaseApprovalCheck = exact()(refineAt(strictObject({
+    ...purchaseEffectFields,
+    lineItems: array(purchaseApprovalLineCheck, minItems(1), maxItems(200)),
+    ...purchaseAmountFields,
+    ...purchaseApprovalFields,
+}), purchaseEvidenceProblem));
+const purchaseApprovalSummaryCheck = exact()(strictObject({ ...purchaseEffectFields, ...purchaseAmountFields, ...purchaseApprovalFields }));
+export const purchaseApprovalListCheck = exact()(strictObject({
+    items: array(purchaseApprovalSummaryCheck, maxItems(100)),
+    nextCursor: nullable(string()),
+}));
+export const purchaseReviewInputCheck = exact()(strictObject({ decision: oneOf(['approved', 'rejected']), reauth: reauthProofCheck }));