@oxy.so/contracts 4.16.0 → 4.17.0

package/dist/types/client/products.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 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`).
+ */
+export declare const subjectProductAccessQueryCheck: import("./check").Check<{
+    schemaVersion: 1;
+    subjectAccountId: string & import("zod").BRAND<"OxyAccountId">;
+    productId: string;
+}>;
+export declare const subjectProductAccessCheck: import("./check").Check<{
+    schemaVersion: 1;
+    subjectAccountId: string & import("zod").BRAND<"OxyAccountId">;
+    capabilities: {
+        key: string;
+        grantIds: string[];
+    }[];
+    evaluatedAt: string;
+    productId: string;
+    quotas: {
+        key: string;
+        unit: string;
+        included: number;
+        combination: "maximum" | "sum" | "exclusive";
+        grantIds: string[];
+    }[];
+    conflicts: {
+        key: string;
+        reason: "combination_mismatch" | "unit_mismatch" | "exclusive_overlap" | "unsafe_total";
+        grantIds: string[];
+    }[];
+}>;
+export declare const personalPlanCatalogueCheck: import("./check").Check<{
+    schemaVersion: 1;
+    state: "unconfigured" | "configured";
+    purchase: "unavailable";
+    plans: {
+        kind: "oxy_one";
+        displayName: string;
+        audience: "personal";
+        benefits: {
+            displayName: string;
+            benefit: {
+                kind: "capability";
+                key: string;
+                productId: string;
+            } | {
+                kind: "quota";
+                key: string;
+                unit: string;
+                included: number;
+                productId: string;
+                combination: "maximum" | "sum" | "exclusive";
+            };
+        }[];
+        offerId: string;
+        offerVersion: number;
+        price?: {
+            currency: string;
+            amountMinorUnits: number;
+            interval: "month";
+            trial: "none";
+            taxTreatment: "inclusive";
+            merchantTotal: "final";
+        } | undefined;
+    }[];
+}>;
+export declare const personalPlanCheckoutRequestCheck: import("./check").Check<{
+    idempotencyKey: string;
+    offerId: string;
+    offerVersion: number;
+    expectedSubjectAccountId: string & import("zod").BRAND<"OxyAccountId">;
+}>;
+export declare const personalPlanCheckoutResultCheck: import("./check").Check<{
+    reason: "provider_unconfigured" | "offer_unconfigured" | "price_unconfigured";
+    state: "unconfigured";
+} | {
+    state: "pending";
+    intentId: string;
+    checkoutUrl?: string | undefined;
+} | {
+    state: "closed";
+    intentId: string;
+} | {
+    state: "fulfilled";
+    intentId: string;
+}>;
+export declare const productSubscriptionsResponseCheck: import("./check").Check<{
+    subscriptions: {
+        status: "active" | "incomplete" | "canceled" | "incomplete_expired" | "past_due" | "paused" | "trialing" | "unpaid";
+        sourceId: string;
+        cancelAtPeriodEnd: boolean;
+        period: {
+            start: string;
+            end: string;
+        };
+        canCancel: boolean;
+        offers: {
+            displayName: string;
+            period: {
+                start: string;
+                end: string;
+            };
+            offerId: string;
+            offerVersion: number;
+            origin: "bundle" | "individual";
+            segmentId: string;
+            current: boolean;
+            products: {
+                id: string;
+                displayName: string;
+            }[];
+        }[];
+    }[];
+}>;
+export declare const subscriptionCreditGrantsResponseCheck: import("./check").Check<{
+    grants: {
+        createdAt: string;
+        id: string;
+        granted: number;
+        remaining: number;
+        period: {
+            start: string;
+            end: string;
+        };
+        origin: "subscription_payment" | "subscription_proration" | "subscription_promotional_grant";
+        invoiceId: string;
+        consumed: number;
+        clawed: number;
+        promotionId: string | null;
+    }[];
+}>;
+export declare const cancelProductSubscriptionCheck: import("./check").Check<{
+    sourceId: string;
+    actionId?: string | undefined;
+    expectedSubjectAccountId?: (string & import("zod").BRAND<"OxyAccountId">) | undefined;
+}>;
+export declare const productSubscriptionCancellationResultCheck: import("./check").Check<{
+    sourceId: string;
+    cancelAtPeriodEnd: true;
+} | {
+    sourceId: string;
+    reconciliationPending: true;
+}>;

package/dist/types/client/recommendations.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The recommendation-request check, without Zod. Schemas: `../recommendations.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+export declare const recommendationRequestCheck: import("./check").Check<{
+    limit?: number | undefined;
+    clientId?: string | undefined;
+    offset?: number | undefined;
+    excludeTypes?: ("agent" | "federated" | "automated")[] | undefined;
+    excludeIds?: string[] | undefined;
+    boosts?: {
+        userIds: string[];
+        weight: number;
+        reason?: string | undefined;
+    }[] | undefined;
+    signalWeights?: {
+        verified?: number | undefined;
+        graph?: number | undefined;
+        completeness?: number | undefined;
+        curation?: number | undefined;
+        interest?: number | undefined;
+        appBoost?: number | undefined;
+        repCandidate?: number | undefined;
+        affinity?: number | undefined;
+    } | undefined;
+}>;

package/dist/types/client/reputation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The reputation view guard, without Zod. Schemas: `../reputation.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import type { ReputationBalance, ReputationBalanceView } from '../reputation';
+/**
+ * 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 declare const FULL_BALANCE_FIELDS: readonly ["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 declare function isFullReputationBalance(balance: ReputationBalanceView): balance is ReputationBalance;

package/dist/types/client/safety.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Profile-access checks, without Zod. Schemas: `../safety.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+export declare const profileAccessInputCheck: import("./check").Check<{
+    subjectAccountId: string;
+}>;
+export declare const profileAccessDecisionCheck: import("./check").Check<{
+    allowed: boolean;
+    reason: "unavailable" | "owner" | "public" | "private" | "blocked";
+    policyVersion: "1";
+}>;

package/dist/types/client/sessionStatus.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The public-application check, without Zod. Schemas: `../sessionStatus.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+export declare const publicApplicationCheck: import("./check").Check<{
+    type: "system" | "internal" | "first_party" | "third_party";
+    name: string;
+    id: string;
+    scopes: string[];
+    isOfficial: boolean;
+    isInternal: boolean;
+    websiteUrl?: string | undefined;
+    description?: string | undefined;
+    icon?: string | undefined;
+    privacyPolicyUrl?: string | undefined;
+    termsUrl?: string | undefined;
+    developerName?: string | undefined;
+}>;

package/dist/types/client/signIn.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Sign-in constants, guards and response checks, without Zod. Schemas: `../signIn.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import type { EmailSignInChooseAccount, EmailSignInLinkResponse, EmailSignInPending, EmailSignInStartResponse, EmailSignInStepResult, SecondFactorRequired, SignInMethods, TotpBackupCodesResponse, TotpEnrollResponse } from '../signIn';
+/** How long the link in a sign-in email can be opened. */
+export declare const EMAIL_SIGNIN_LINK_TTL_MS: number;
+/** How long a second-factor challenge can be answered. */
+export declare const SIGNIN_SECOND_FACTOR_TTL_MS: number;
+/** Wrong second-factor codes one challenge accepts. */
+export declare const SIGNIN_SECOND_FACTOR_MAX_ATTEMPTS = 5;
+/** Shortest password Oxy accepts when one is set. */
+export declare const PASSWORD_MIN_LENGTH = 10;
+/** Longest password Oxy accepts (characters). */
+export declare const PASSWORD_MAX_LENGTH = 256;
+/** Digits in an authenticator code. */
+export declare const TOTP_DIGITS = 6;
+/** Seconds each authenticator code lasts. */
+export declare const TOTP_PERIOD_SECONDS = 30;
+/** Backup codes issued when an authenticator is enabled or they are regenerated. */
+export declare const TOTP_BACKUP_CODE_COUNT = 10;
+/**
+ * The long sign-in code: ten characters of Crockford base32 without the
+ * look-alikes (no 0, O, 1, I, L, U), shown as `XXXXX-XXXXX`. An account whose
+ * sign-in codes were guessed at too often today (the per-account ceiling) is
+ * sent this instead of 6 digits for the rest of the day, so its owner can still
+ * type a code while guessing one is infeasible.
+ */
+export declare const EMAIL_SIGNIN_LONG_CODE_ALPHABET = "23456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const EMAIL_SIGNIN_LONG_CODE_LENGTH = 10;
+/**
+ * Normalise a typed sign-in code: 6 digits stay as they are; a long code is
+ * upper-cased with its dash and spaces removed. Anything else is returned
+ * trimmed (and will simply be wrong).
+ */
+export declare function normalizeEmailSignInCode(code: string): string;
+/**
+ * How long, once the email is proven, the person has to choose which of its
+ * accounts signs in.
+ */
+export declare const EMAIL_SIGNIN_CHOICE_TTL_MS: number;
+/** Most accounts one email can hold; sign-up refuses another past it. */
+export declare const EMAIL_ACCOUNTS_MAX = 20;
+/** Narrow a {@link SignInStepResult}. */
+export declare function isSecondFactorRequired(result: EmailSignInStepResult | EmailSignInPending): result is SecondFactorRequired;
+/** Narrow an {@link EmailSignInStepResult}. */
+export declare function isEmailSignInChooseAccount(result: EmailSignInStepResult | EmailSignInPending): result is EmailSignInChooseAccount;
+/**
+ * What a re-verification email code confirms. The code is bound to it: a code
+ * asked for one change never authorises another, and the email names it.
+ */
+export declare const REAUTH_ACTIONS: readonly ["change_password", "totp", "link_commons", "delete_account", "credentials_manage"];
+export type ReauthAction = (typeof REAUTH_ACTIONS)[number];
+/**
+ * Stable error codes (`error.code` in the API error body). Clients map these
+ * through their localization, never the English message.
+ */
+export declare const SIGN_IN_ERROR_CODES: {
+    /** Wrong identifier or password — never says which. */
+    readonly invalidCredentials: "SIGNIN_INVALID_CREDENTIALS";
+    /** The request is unknown, expired, spent, or its secret is wrong. */
+    readonly requestInvalid: "SIGNIN_REQUEST_INVALID";
+    /** The link is unknown, expired or already used. */
+    readonly linkInvalid: "SIGNIN_LINK_INVALID";
+    /** The link was opened in another browser: type the code in the app instead. */
+    readonly linkOtherDevice: "SIGNIN_LINK_OTHER_DEVICE";
+    /** The second-factor challenge or its code is wrong, expired or spent. */
+    readonly secondFactorInvalid: "SECOND_FACTOR_INVALID";
+    /** Too many failures for this account: wait and try again. */
+    readonly locked: "SIGNIN_LOCKED";
+    /** The step needs a fresh proof (`reauth`). */
+    readonly reauthRequired: "REAUTH_REQUIRED";
+    /** The fresh proof was wrong. */
+    readonly reauthInvalid: "REAUTH_INVALID";
+    /** The account has an authenticator: the proof must carry its code. */
+    readonly totpRequired: "TOTP_REQUIRED";
+    /** Enrolling or confirming an authenticator that is already on. */
+    readonly totpAlreadyEnabled: "TOTP_ALREADY_ENABLED";
+    /** Disabling, confirming or regenerating codes with no authenticator (or no pending one). */
+    readonly totpNotEnabled: "TOTP_NOT_ENABLED";
+    /** The code the authenticator showed at enrolment is wrong. */
+    readonly totpCodeInvalid: "TOTP_CODE_INVALID";
+    /** Only official Oxy apps and auth.oxy.so may sign people in here. */
+    readonly originNotAllowed: "SIGNIN_ORIGIN_NOT_ALLOWED";
+    /** The username is taken. */
+    readonly usernameTaken: "USERNAME_TAKEN";
+    /** The email already holds `EMAIL_ACCOUNTS_MAX` accounts: no sign-up adds another. */
+    readonly emailAccountsFull: "EMAIL_ACCOUNTS_FULL";
+};
+export type SignInErrorCode = (typeof SIGN_IN_ERROR_CODES)[keyof typeof SIGN_IN_ERROR_CODES];
+export declare const emailSignInStartResponseCheck: import("./check").Check<EmailSignInStartResponse>;
+export declare const emailSignInLinkResponseCheck: import("./check").Check<EmailSignInLinkResponse>;
+export declare const secondFactorRequiredCheck: import("./check").Check<SecondFactorRequired>;
+export declare const emailSignInPendingCheck: import("./check").Check<EmailSignInPending>;
+export declare const emailSignInChooseAccountCheck: import("./check").Check<EmailSignInChooseAccount>;
+export declare const signInMethodsCheck: import("./check").Check<SignInMethods>;
+export declare const totpEnrollResponseCheck: import("./check").Check<TotpEnrollResponse>;
+export declare const totpBackupCodesResponseCheck: import("./check").Check<TotpBackupCodesResponse>;
+export declare const reauthProofCheck: import("./check").Check<{
+    password?: string | undefined;
+    emailCode?: {
+        code: string;
+        verificationId: string;
+    } | undefined;
+    totpCode?: string | undefined;
+}>;

package/dist/types/client/userResponse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * User-response checks, without Zod. Schemas: `../userResponse.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import type { UserNameResponse } from '../userResponse';
+export declare const userNameCheck: import("./check").Check<UserNameResponse>;

package/dist/types/client/username.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The username policy, without Zod. Schemas: `../username.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import type { AccountKind } from './accountGraph';
+import { type Check } from './check';
+/** Shortest storable handle. `oxy` sets the floor. */
+export declare const USERNAME_MIN_LENGTH = 3;
+/** Longest storable handle, and the `maxLength` an input field should carry. */
+export declare const USERNAME_MAX_LENGTH = 30;
+/** The 400 / inline-validation copy for every path that rejects a handle. */
+export declare const USERNAME_INVALID_MESSAGE: string;
+/**
+ * Exact-match handles nobody may newly claim, regardless of account kind.
+ *
+ * This is NOT a namespace tightening like the bot suffix — it is a list of
+ * names withheld from `users_lower_username_key` before anybody asks for
+ * them. Compared against the same normalization the unique index applies
+ * (`lower(btrim(username))`), so `Admin`, ` ADMIN ` and `admin` are the one
+ * name this list means.
+ *
+ * `oxy`, `mention`, `homiio`, `clarity`, `faircoin`, `astro` and `mercaria`
+ * are deliberately NOT here: each already has an `organization`/`project`
+ * row, so the unique index already refuses a second one, and `oxy` is the
+ * name `USERNAME_MIN_LENGTH` is pinned against in
+ * `__tests__/username.test.ts` — listing it would make
+ * `usernameSchema.safeParse('oxy')` fail and falsify that comment. A brand
+ * with no account of its own yet (measured 2026-09-18: Alia, Allo, TNP,
+ * Kaana, Bloom) has no row to protect it, so it is listed until one exists.
+ */
+export declare const RESERVED_USERNAMES: ReadonlySet<string>;
+/** The 400 / inline-validation copy for a handle on {@link RESERVED_USERNAMES}. */
+export declare const RESERVED_USERNAME_MESSAGE = "This username is reserved and cannot be registered";
+/**
+ * {@link RESERVED_USERNAMES}, minus `alia`, checked against each `-`/`_`
+ * separated SEGMENT of a candidate rather than the whole string — so
+ * `official-oxy`, `super-admin` and `team-kaana` are refused the same as the
+ * bare words, without banning every word that merely CONTAINS one as a
+ * substring (`superman`, `modern`, `grassroot`, `homeowner` all stay legal:
+ * none of them separates the reserved word from the rest with `-` or `_`).
+ *
+ * `alia` is excluded because `alia-` is the live internal-cost-centre
+ * namespace: `alia-production-chat` is a minted account and
+ * `alia-research` / `alia-voice` / `alia-evaluations` are pinned as legal
+ * slugs in `__tests__/username.test.ts` and `internalCostCenterSpecs.test.ts`.
+ * Segment-matching `alia` would refuse all four. The bare word `alia` is
+ * still refused — {@link RESERVED_USERNAMES} above catches it exactly.
+ */
+export declare const RESERVED_USERNAME_SEGMENTS: ReadonlySet<string>;
+/** The 400 / inline-validation copy for a handle that is only digits. */
+export declare const NUMERIC_USERNAME_MESSAGE = "Username cannot be only numbers";
+/**
+ * Alphanumeric runs joined by single separators, as a SOURCE string.
+ *
+ * A string rather than a literal because the OpenAPI docblocks that publish this
+ * rule (`POST /auth/register`, `PUT /users/:userId`) must quote it verbatim, and
+ * `usernamePolicySingleSource.test.ts` compares them against THIS constant. A
+ * published `pattern:` that drifts from the enforced rule is a lie told to every
+ * client that generates from the spec, and it is exactly the kind of copy nobody
+ * notices going stale.
+ *
+ * Deliberately NOT re-exported from the package barrel: it exists for the
+ * schema below and for that one gate. Anything validating a username uses
+ * {@link usernameSchema}, so there is no second way to ask the question.
+ *
+ * Written as an unambiguous alternation rather than a lookahead: every character
+ * belongs to exactly one branch, so matching is linear and there is no
+ * backtracking to bound. It also carries no `\p{…}` property escape, which
+ * mobile Hermes throws on at runtime — this module is reachable from every React
+ * Native consumer.
+ */
+export declare const USERNAME_PATTERN_SOURCE = "^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$";
+export declare const USERNAME_PATTERN: RegExp;
+/**
+ * Drop the characters the policy forbids, for an input field that filters
+ * keystrokes.
+ *
+ * This is a TYPING aid and nothing else — the result still has to pass
+ * {@link usernameSchema}, which is what decides. It does not lower-case (case is
+ * preserved, see the header) and it cannot repair a name: a value that is too
+ * short, edge-separated or doubly-separated comes back unchanged and fails
+ * validation with a message, which is the outcome the coercing rules this
+ * replaces used to hide.
+ */
+export declare function stripDisallowedUsernameCharacters(input: string): string;
+/**
+ * The label a bot's handle ends in — the ONE exception the policy carries.
+ *
+ * Lower-case here because it is what a generator appends; the comparison that
+ * enforces it folds case, so `MyBot` satisfies it just as `mybot` does.
+ *
+ * Deliberately NOT re-exported from the package barrel, for the same reason
+ * {@link USERNAME_PATTERN_SOURCE} is not: it exists for the schema and the
+ * generator aid below. A consumer that wants to SAY the rule uses
+ * {@link BOT_USERNAME_INVALID_MESSAGE}, which already quotes it, and one that
+ * wants to APPLY it uses {@link applyBotUsernameSuffix} — so there is no second
+ * way to spell the check.
+ */
+export declare const BOT_USERNAME_SUFFIX = "bot";
+/** The 400 / inline-validation copy for a bot handle that carries no label. */
+export declare const BOT_USERNAME_INVALID_MESSAGE = "A bot account's username must end in \"bot\"";
+/**
+ * Label a proposed bot handle, so a generator PROPOSES something the server will
+ * accept.
+ *
+ * Alia builds an agent's handle from its display name; without this it would
+ * propose `garden-helper` for a bot and be 400ed on submit, which is the same
+ * "suggest, then refuse" defect the minimum length already caused once.
+ *
+ * It appends and never inserts: a separator is the caller's choice, so
+ * `garden-helper` becomes `garden-helperbot` while a caller who typed
+ * `garden-helper-` gets `garden-helper-bot`. It truncates to leave room rather
+ * than overflowing {@link USERNAME_MAX_LENGTH}.
+ *
+ * Like {@link stripDisallowedUsernameCharacters} it is an aid, not a decision: it
+ * cannot repair a handle the base policy refuses, and the result still has to
+ * pass {@link botUsernameSchema}.
+ */
+export declare function applyBotUsernameSuffix(candidate: string): string;
+/** The username policy as a check — the twin of `usernameSchema`, same messages. */
+export declare const usernameCheck: Check<string>;
+/** A bot's username: the policy plus the `bot` suffix — the twin of `botUsernameSchema`. */
+export declare const botUsernameCheck: Check<string>;
+/** The twin of `usernameSchemaForAccountKind`. */
+export declare function usernameCheckForAccountKind(kind: AccountKind | null | undefined): Check<string>;