@oxy.so/contracts 1.0.0

package/dist/types/accountGraph.d.ts

@@ -0,0 +1,378 @@
+/**
+ * Account graph wire contracts — the account-kind vocabulary, the account
+ * category taxonomy, and the create-account input.
+ *
+ * `accountCategories` classifies a NON-PERSONAL account — what it is about, what
+ * it does — without polluting `User.kind`. See the block above
+ * {@link ACCOUNT_CATEGORY_IDS} for the four rules that govern it.
+ */
+import { z } from 'zod';
+/**
+ * Account-graph classification — the ONE authority for the kind vocabulary.
+ *
+ * `personal` is the only kind minted by signup and the only one that carries
+ * its own credentials; every other kind is a child account created under a
+ * parent and operated through `account_members`. The API schema, the Drizzle
+ * table and the SDK all derive from this list rather than restating it, so a
+ * new kind is one edit here instead of four literals that can drift.
+ */
+export type AccountKind = 'personal' | 'organization' | 'project' | 'bot' | 'channel';
+/**
+ * The union is spelled out above and the array proves coverage BOTH ways
+ * (`satisfies` here, the `Gap` alias below) — the same shape this package's
+ * `ACCOUNT_CATEGORY_IDS` / `TRUST_TIERS` pairs use, and the one
+ * `db/schema/users.ts` mirrors to keep the `users_kind_check` CHECK honest.
+ *
+ * Deriving the union from the array instead would cost nothing here and be paid
+ * by consumers: `kind` travels into `@oxy.so/services` on every device-directory
+ * context (`deviceContextSchema.kind` → `DeviceContext` → the switcher rows),
+ * and an indexed-access type is materially more expensive to check there than a
+ * literal union.
+ */
+export declare const ACCOUNT_KINDS: readonly ["personal", "organization", "project", "bot", "channel"];
+/** `never` while `ACCOUNT_KINDS` covers the union. */
+export type AccountKindGap = Exclude<AccountKind, (typeof ACCOUNT_KINDS)[number]>;
+export declare const accountKindSchema: z.ZodEnum<["personal", "organization", "project", "bot", "channel"]>;
+/**
+ * Kinds that may be CREATED as children of another account. Exactly
+ * `ACCOUNT_KINDS` minus `personal`, which is always a tree root.
+ */
+export type ChildAccountKind = Exclude<AccountKind, 'personal'>;
+export declare const CHILD_ACCOUNT_KINDS: readonly ["organization", "project", "bot", "channel"];
+/** `never` while `CHILD_ACCOUNT_KINDS` covers the child union. */
+export type ChildAccountKindGap = Exclude<ChildAccountKind, (typeof CHILD_ACCOUNT_KINDS)[number]>;
+export declare const childAccountKindSchema: z.ZodEnum<["organization", "project", "bot", "channel"]>;
+/**
+ * Whether an account of this kind may be the SUBJECT OF A DELEGATION — an
+ * application acting as it on some person's authority. `POST /internal/accounts/
+ * :id/service-switch` and the OAuth delegated subject both gate on this.
+ *
+ * It is NOT the question an account switcher asks. See
+ * {@link isOperatorSwitchTargetKind}, and the note below on why the difference
+ * is `bot`.
+ *
+ * Two kinds are refused, for opposite reasons:
+ *
+ *  - `personal` is a human login, so assuming it would be impersonation.
+ *  - `channel` is a CONTENT identity, not an operating one. A channel exists so
+ *    that posts can be authored BY it; it is never a seat anybody occupies. Its
+ *    operators act on it through their own membership, and an application
+ *    publishes to it with its own credential. Refusing act-as is what makes
+ *    "no login, ever" structural rather than incidental: no session can be
+ *    minted whose subject is a channel, so no bearer exists that could add an
+ *    auth method to one (every auth-method write resolves its target from the
+ *    authenticated subject, never from a parameter).
+ *
+ * Consumers must gate on this predicate rather than testing `kind === 'personal'`,
+ * which silently admits every kind added after it was written.
+ */
+export declare function isDelegatedActAsEligibleKind(kind: AccountKind | null | undefined): boolean;
+/**
+ * Whether a PERSON may switch into an account of this kind — become it, in an
+ * account switcher, for the rest of their session.
+ *
+ * ## Why this is not the same question as {@link isDelegatedActAsEligibleKind}
+ *
+ * The two differ on exactly one kind, `bot`, and that difference is the whole
+ * reason both exist.
+ *
+ * **A bot is not something you become. It is something that operates on your
+ * behalf.** Its whole purpose is to act while nobody is present: an application
+ * holds a credential, names the human whose authority it borrows, and speaks as
+ * the bot. That is delegation, and it is what
+ * {@link isDelegatedActAsEligibleKind} admits it for.
+ *
+ * Handing a person the bot's seat instead inverts that. It puts a human inside
+ * the identity that exists to act without one, and it does so on the human's own
+ * device, next to their personal login — which is precisely what happened: a
+ * `bot` account held a live session on a person's device, offered to them by a
+ * switcher that had asked the delegation question by mistake.
+ *
+ * `channel` is refused here as well, for the reason set out above, and
+ * `personal` because assuming somebody else's login is impersonation.
+ *
+ * ## This is the narrower predicate, deliberately
+ *
+ * Everything a person may become, a service may also act as; the reverse does
+ * not hold. A caller that is unsure which question it is asking wants THIS one:
+ * being wrong here withholds an affordance, while being wrong the other way
+ * hands out a seat.
+ */
+export declare function isOperatorSwitchTargetKind(kind: AccountKind | null | undefined): boolean;
+/**
+ * Narrow an unknown value to an {@link AccountKind}.
+ *
+ * The user-DTO serializers read from structurally-permissive `unknown` sources
+ * (a Drizzle row, a Mongo document, an already-formatted object), so each one
+ * would otherwise hand-roll this check and they would drift on what counts.
+ */
+export declare function isAccountKind(value: unknown): value is AccountKind;
+/**
+ * Every account category, by stable id.
+ *
+ * Grouped by comment for readability only; the storage, the wire and the picker
+ * all treat this as one flat list. `other` is the escape hatch for an account
+ * that fits nothing here.
+ *
+ * TO ADD ONE: append an id (lowercase ASCII, `snake_case`) here, publish
+ * `@oxy.so/contracts`, then ship a migration that widens
+ * `users_account_categories_check` — never edit an existing migration — and add
+ * an `accounts.accountCategory.<id>` label to each client's locales.
+ *
+ * TO WITHDRAW ONE: leave the id here and add it to
+ * {@link RETIRED_ACCOUNT_CATEGORY_IDS}. See rule 3 above.
+ */
+export declare const ACCOUNT_CATEGORY_IDS: readonly ["news", "politics", "business", "startup", "finance", "crypto", "marketplace", "retail", "real_estate", "agency", "landlord", "cooperative", "architecture", "technology", "software", "ai", "security", "automation", "science", "education", "books", "health", "fitness", "sports", "gaming", "music", "film", "podcast", "art", "photography", "comedy", "food", "travel", "fashion", "home_garden", "diy", "automotive", "animals", "family", "nonprofit", "government", "community", "activism", "environment", "religion", "other"];
+export type AccountCategoryId = (typeof ACCOUNT_CATEGORY_IDS)[number];
+/**
+ * Accepts EVERY id, withdrawn ones included — see rule 3.
+ *
+ * A schema that rejected a withdrawn id would 400 the whole request whenever a
+ * client round-trips the categories it was served, so an account that had
+ * picked one could no longer save its bio either. That is the same failure the
+ * nullable `bio` / `avatar` fix addressed, wearing a different hat.
+ */
+export declare const accountCategoryIdSchema: z.ZodEnum<["news", "politics", "business", "startup", "finance", "crypto", "marketplace", "retail", "real_estate", "agency", "landlord", "cooperative", "architecture", "technology", "software", "ai", "security", "automation", "science", "education", "books", "health", "fitness", "sports", "gaming", "music", "film", "podcast", "art", "photography", "comedy", "food", "travel", "fashion", "home_garden", "diy", "automotive", "animals", "family", "nonprofit", "government", "community", "activism", "environment", "religion", "other"]>;
+/**
+ * Ids withdrawn from the picker. Empty today.
+ *
+ * A withdrawn id keeps working everywhere it is already stored: it validates,
+ * it survives a round-trip save, it still renders from its label key, and it
+ * stays PRIMARY if it was primary. Nothing rewrites a stored list — a read-time
+ * or migration-time demotion would silently replace a choice its owner made,
+ * which is precisely what stable ids exist to prevent. The owner drops it on
+ * their next edit; until then it is honoured.
+ *
+ * What withdrawal changes is only this: the id leaves
+ * {@link SELECTABLE_ACCOUNT_CATEGORY_IDS}, so no picker offers it, and
+ * {@link newlyAddedRetiredCategories} refuses to let a write ADD it to an
+ * account that did not already have it.
+ */
+export declare const RETIRED_ACCOUNT_CATEGORY_IDS: readonly AccountCategoryId[];
+/** Whether a category may still be OFFERED. A stored one is readable either way. */
+export declare function isSelectableAccountCategoryId(id: AccountCategoryId): boolean;
+/** The ids a picker may offer, in declaration order. */
+export declare const SELECTABLE_ACCOUNT_CATEGORY_IDS: readonly AccountCategoryId[];
+/**
+ * Which of `next` are withdrawn ids the account did not already carry — i.e.
+ * the ones a write must be refused for.
+ *
+ * `retired` is a parameter rather than a module read so the rule can be
+ * exercised against a non-empty set while the production one is empty; a test
+ * over `RETIRED_ACCOUNT_CATEGORY_IDS` alone would pass vacuously today and stay
+ * passing if the rule were deleted.
+ */
+export declare function newlyAddedRetiredCategories(next: readonly AccountCategoryId[], previous: readonly AccountCategoryId[], retired: readonly AccountCategoryId[]): AccountCategoryId[];
+/**
+ * How many categories one account may carry.
+ *
+ * Four, not "as many as you like". Three reasons, in the order they bind:
+ *
+ *  - The primary has to MEAN something. At ten categories the first element
+ *    reads as a sort artifact rather than a choice, and rule 2 above is the
+ *    entire mechanism by which a primary exists.
+ *  - The profile RENDERS them as a row of chips; four labels of this length is
+ *    what fits a phone-width profile header before the row wraps or truncates.
+ *  - Four is enough to place a genuinely compound account without a tag cloud:
+ *    a housing cooperative that is also a non-profit serving a local community
+ *    spends `cooperative`, `nonprofit`, `community`, `real_estate` — and is the
+ *    most compound real example in the ecosystem.
+ *
+ * One constant, read by the wire schema, the database CHECK and the picker, so
+ * changing it is one edit plus a migration.
+ */
+export declare const MAX_ACCOUNT_CATEGORIES = 4;
+/**
+ * An account's categories on the wire. ORDER IS MEANINGFUL — index 0 is the
+ * primary (rule 2).
+ *
+ * A duplicate is REJECTED rather than silently collapsed. De-duplicating would
+ * rewrite the caller's list, and any rewrite of this list can move which id sits
+ * at index 0 — so the one repair available here is the one that would break the
+ * property the list exists to carry. A duplicate only ever comes from a client
+ * bug, and a 400 naming the index is how that bug gets found.
+ */
+export declare const accountCategoriesSchema: z.ZodEffects<z.ZodArray<z.ZodEnum<["news", "politics", "business", "startup", "finance", "crypto", "marketplace", "retail", "real_estate", "agency", "landlord", "cooperative", "architecture", "technology", "software", "ai", "security", "automation", "science", "education", "books", "health", "fitness", "sports", "gaming", "music", "film", "podcast", "art", "photography", "comedy", "food", "travel", "fashion", "home_garden", "diy", "automotive", "animals", "family", "nonprofit", "government", "community", "activism", "environment", "religion", "other"]>, "many">, ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[], ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[]>;
+/**
+ * Kinds that may carry categories: every kind EXCEPT `personal`.
+ *
+ * A person has interests, not a sector — and their interests are not a
+ * classification anybody else gets to read off their profile. Spelled out
+ * positively, like {@link isDelegatedActAsEligibleKind} and for the same reason: a `kind
+ * !== 'personal'` test silently admits every kind invented after it was
+ * written, whereas this list forces whoever adds one to decide.
+ */
+export declare const ACCOUNT_CATEGORY_KINDS: readonly ["organization", "project", "bot", "channel"];
+export type AccountCategoryKind = (typeof ACCOUNT_CATEGORY_KINDS)[number];
+/**
+ * Whether an account of this kind may carry categories.
+ *
+ * The API refuses the write and the `users_account_categories_kind_check`
+ * constraint makes it unrepresentable; both derive from
+ * {@link ACCOUNT_CATEGORY_KINDS}, so they cannot disagree.
+ */
+export declare function kindAcceptsAccountCategories(kind: AccountKind | null | undefined): boolean;
+/**
+ * POST /accounts — create a non-personal account under the caller's tree.
+ *
+ * No cross-field refinement guards `accountCategories`, and that is not an
+ * omission: `kind` here is a CHILD kind, and every child kind is in
+ * {@link ACCOUNT_CATEGORY_KINDS}, so `personal` is already unrepresentable on
+ * this route. The refinement the single-valued predecessor needed disappeared
+ * along with the restriction that made it necessary. A child kind that does NOT
+ * accept categories would break that reasoning silently, so
+ * `__tests__/accountGraph.test.ts` asserts the two lists agree.
+ */
+export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
+    parentAccountId: z.ZodOptional<z.ZodString>;
+    kind: z.ZodEnum<["organization", "project", "bot", "channel"]>;
+    /**
+     * The SAME policy a person's handle is held to. `users.username` is one unique
+     * index, so a managed account may not reserve a name a person could not ask
+     * for — and this route's predecessor (`.min(1).max(100)` here, `^[\w.-]+$`
+     * with no ceiling in the service) is how a one-character or dotted or
+     * 100-character handle became reachable for bots alone.
+     *
+     * A `bot` is held to that AND to the label its handle must end in. That half
+     * cannot live on this field — it depends on `kind`, a sibling — so it is in the
+     * `superRefine` below, which reports its issue against this path.
+     */
+    username: z.ZodString;
+    name: z.ZodOptional<z.ZodObject<{
+        first: z.ZodOptional<z.ZodString>;
+        last: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        first?: string | undefined;
+        last?: string | undefined;
+        displayName?: string | undefined;
+    }, {
+        first?: string | undefined;
+        last?: string | undefined;
+        displayName?: string | undefined;
+    }>>;
+    bio: z.ZodOptional<z.ZodString>;
+    avatar: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * A named color preset KEY (`"blue"`, `"mint"`, …), never a hex value.
+     *
+     * Here at CREATION for the reason `isPrivateAccount` is, in miniature: for a
+     * managed account the color is a visual identity, and an account that is
+     * discoverable without one and acquires it on a second request is a face that
+     * changes by itself. One statement, one row, born looking like what its owner
+     * chose.
+     *
+     * The VALUE is checked in the API rather than here. The vocabulary is
+     * `USER_COLOR_PRESETS`, which is declared next to the `users_color_check` CHECK
+     * that is rendered from it — pinning the list a second time in this package
+     * would be a second source of truth for what the database accepts, and the two
+     * would drift apart silently. What this shape does is keep an over-long or
+     * non-string value from reaching the service at all.
+     */
+    color: z.ZodOptional<z.ZodString>;
+    /** Ordered, PRIMARY FIRST — see rule 2 above {@link ACCOUNT_CATEGORY_IDS}. */
+    accountCategories: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["news", "politics", "business", "startup", "finance", "crypto", "marketplace", "retail", "real_estate", "agency", "landlord", "cooperative", "architecture", "technology", "software", "ai", "security", "automation", "science", "education", "books", "health", "fitness", "sports", "gaming", "music", "film", "podcast", "art", "photography", "comedy", "food", "travel", "fashion", "home_garden", "diy", "automotive", "animals", "family", "nonprofit", "government", "community", "activism", "environment", "religion", "other"]>, "many">, ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[], ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[]>>;
+    /**
+     * Create the account already opted OUT of discovery.
+     *
+     * ## Why this belongs at CREATION and not only on the privacy route
+     *
+     * Every account is born discoverable: the column defaults to `false` and
+     * nothing on the create path wrote it, so a new account appears in people
+     * search the instant it exists. For a human signing themselves up that is the
+     * right default and it is NOT changed here. For an account a program creates
+     * on someone's behalf — an agent, an unlaunched project, an organization for
+     * something not yet announced — it publishes the thing before its owner ever
+     * decided to.
+     *
+     * The alternative is a second call right after create, which is a window in
+     * which the account IS public, and a window whose closing depends on a second
+     * request succeeding. A field here has neither: one statement, one row, born
+     * in the state the caller asked for.
+     *
+     * ## It reuses the existing flag deliberately
+     *
+     * This is `privacy_is_private_account`, the same one `PUT /users/:id/privacy`
+     * toggles — not a new "published" column. A second visibility flag would be a
+     * second source of truth for one question, and the two would disagree.
+     *
+     * Inherited semantics, stated because reusing a flag means inheriting ALL of
+     * it: the account is kept out of people search, out of the follow-graph lists
+     * (`followers` / `following` / `mutuals`), out of `/similar` and out of the
+     * recommendation candidate pools, and its non-public, non-unlisted media
+     * becomes follower-gated. It does NOT hide the profile from someone who knows
+     * the handle, and it carries NO follow-approval flow — following is immediate
+     * and unilateral whatever this says, so nothing here creates a request queue
+     * nobody attends.
+     *
+     * ## Not conditioned on `kind`, on purpose
+     *
+     * The same reasoning as `accountCategories` above: this object does not
+     * refine on kind, and an unlaunched organization has exactly the problem an
+     * unpublished agent does. The discovery predicate never reads `kind`, so the
+     * remedy must not either.
+     */
+    isPrivateAccount: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    kind: "bot" | "organization" | "project" | "channel";
+    username: string;
+    parentAccountId?: string | undefined;
+    name?: {
+        first?: string | undefined;
+        last?: string | undefined;
+        displayName?: string | undefined;
+    } | undefined;
+    bio?: string | undefined;
+    avatar?: string | undefined;
+    description?: string | undefined;
+    color?: string | undefined;
+    accountCategories?: ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
+    isPrivateAccount?: boolean | undefined;
+}, {
+    kind: "bot" | "organization" | "project" | "channel";
+    username: string;
+    parentAccountId?: string | undefined;
+    name?: {
+        first?: string | undefined;
+        last?: string | undefined;
+        displayName?: string | undefined;
+    } | undefined;
+    bio?: string | undefined;
+    avatar?: string | undefined;
+    description?: string | undefined;
+    color?: string | undefined;
+    accountCategories?: ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
+    isPrivateAccount?: boolean | undefined;
+}>, {
+    kind: "bot" | "organization" | "project" | "channel";
+    username: string;
+    parentAccountId?: string | undefined;
+    name?: {
+        first?: string | undefined;
+        last?: string | undefined;
+        displayName?: string | undefined;
+    } | undefined;
+    bio?: string | undefined;
+    avatar?: string | undefined;
+    description?: string | undefined;
+    color?: string | undefined;
+    accountCategories?: ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
+    isPrivateAccount?: boolean | undefined;
+}, {
+    kind: "bot" | "organization" | "project" | "channel";
+    username: string;
+    parentAccountId?: string | undefined;
+    name?: {
+        first?: string | undefined;
+        last?: string | undefined;
+        displayName?: string | undefined;
+    } | undefined;
+    bio?: string | undefined;
+    avatar?: string | undefined;
+    description?: string | undefined;
+    color?: string | undefined;
+    accountCategories?: ("news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "security" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
+    isPrivateAccount?: boolean | undefined;
+}>;
+export type CreateAccountRequest = z.infer<typeof createAccountRequestSchema>;