@oxyhq/contracts 0.22.0 → 0.23.0

package/dist/types/accountGraph.d.ts

@@ -1,10 +1,10 @@
 /**
- * Account graph wire contracts — the account-kind vocabulary, organization
- * taxonomy, and create-account input.
+ * Account graph wire contracts — the account-kind vocabulary, the account
+ * category taxonomy, and the create-account input.
  *
- * `organizationCategory` classifies `kind: 'organization'` accounts (agency,
- * cooperative, landlord, …) without polluting `User.kind`. Meaningful only when
- * `kind === 'organization'`.
+ * `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';
 /**
@@ -20,7 +20,7 @@ export type AccountKind = 'personal' | 'organization' | 'project' | 'bot' | 'cha
 /**
  * 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
- * `ORGANIZATION_CATEGORIES` / `TRUST_TIERS` pairs use, and the one
+ * `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
@@ -70,14 +70,123 @@ export declare function isActAsEligibleKind(kind: AccountKind | null | undefined
  * would otherwise hand-roll this check and they would drift on what counts.
  */
 export declare function isAccountKind(value: unknown): value is AccountKind;
-export declare const ORGANIZATION_CATEGORIES: readonly ["agency", "cooperative", "landlord", "other"];
-export type OrganizationCategory = (typeof ORGANIZATION_CATEGORIES)[number];
-export declare const organizationCategorySchema: z.ZodEnum<["agency", "cooperative", "landlord", "other"]>;
+/**
+ * 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
+ * `@oxyhq/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 isActAsEligibleKind} 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.
- * `organizationCategory` is accepted only when `kind` is `organization`.
+ *
+ * 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<{
+export declare const createAccountRequestSchema: z.ZodObject<{
     parentAccountId: z.ZodOptional<z.ZodString>;
     kind: z.ZodEnum<["organization", "project", "bot", "channel"]>;
     username: z.ZodString;
@@ -97,7 +206,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     bio: z.ZodOptional<z.ZodString>;
     avatar: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    organizationCategory: z.ZodOptional<z.ZodEnum<["agency", "cooperative", "landlord", "other"]>>;
+    /** 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")[]>>;
 }, "strip", z.ZodTypeAny, {
     kind: "organization" | "project" | "bot" | "channel";
     username: string;
@@ -110,33 +220,7 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     bio?: string | undefined;
     avatar?: string | undefined;
     description?: string | undefined;
-    organizationCategory?: "agency" | "cooperative" | "landlord" | "other" | undefined;
-}, {
-    kind: "organization" | "project" | "bot" | "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;
-    organizationCategory?: "agency" | "cooperative" | "landlord" | "other" | undefined;
-}>, {
-    kind: "organization" | "project" | "bot" | "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;
-    organizationCategory?: "agency" | "cooperative" | "landlord" | "other" | 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;
 }, {
     kind: "organization" | "project" | "bot" | "channel";
     username: string;
@@ -149,6 +233,6 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     bio?: string | undefined;
     avatar?: string | undefined;
     description?: string | undefined;
-    organizationCategory?: "agency" | "cooperative" | "landlord" | "other" | 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;
 }>;
 export type CreateAccountRequest = z.infer<typeof createAccountRequestSchema>;

package/dist/types/deviceSession.d.ts

@@ -193,10 +193,11 @@ export declare const deviceTokenMintRequestSchema: z.ZodObject<{
 }>;
 /**
  * Wire shape of a successful `POST /session/device/token`: the freshly-minted
- * short access token for the active account, its expiry, the NEXT rotating
- * device secret the client must persist (rotation-in-use — the presented secret
- * stays valid for a short grace so multi-tab races don't lock out), and the
- * projected device-session state.
+ * short access token for the active account, its expiry, the device secret the
+ * client must persist (`nextDeviceSecret` — on mint this echoes the presented
+ * secret unchanged so concurrent refreshes from multiple origins do not race),
+ * and the projected device-session state. Sign-in rotates the secret via
+ * `issueDeviceSecret`; mint does not.
  */
 export declare const deviceTokenMintResponseSchema: z.ZodObject<{
     accessToken: z.ZodString;

package/dist/types/index.d.ts

@@ -9,8 +9,8 @@
  * Platform-agnostic — zod is the only runtime dependency. No react/react-native/
  * expo, no `require()` in the ESM build.
  */
-export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isActAsEligibleKind, ORGANIZATION_CATEGORIES, organizationCategorySchema, createAccountRequestSchema, } from './accountGraph';
-export type { AccountKind, ChildAccountKind, OrganizationCategory, CreateAccountRequest, } from './accountGraph';
+export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isActAsEligibleKind, ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, accountCategoriesSchema, accountCategoryIdSchema, isSelectableAccountCategoryId, kindAcceptsAccountCategories, MAX_ACCOUNT_CATEGORIES, newlyAddedRetiredCategories, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, createAccountRequestSchema, } from './accountGraph';
+export type { AccountKind, AccountCategoryId, AccountCategoryKind, ChildAccountKind, CreateAccountRequest, } from './accountGraph';
 export { userNameSchema, userRelationshipSchema, themePreferenceSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, resolveUserId, safeParseContract, } from './userResponse';
 export type { UserNameResponse, UserRelationship, ThemePreference, UserResponse, UserProfileUpdate, CurrentUserResponseContract, DeviceLinkedSessionResponse, DeviceLinkedSessionsResponseContract, } from './userResponse';
 export { applicationTypeSchema, publicApplicationSchema, sessionStatusSchema, } from './sessionStatus';

package/dist/types/recommendations.d.ts

@@ -172,11 +172,11 @@ export declare const recommendationCountSchema: z.ZodObject<{
     followers: z.ZodNumber;
     following: z.ZodNumber;
 }, "strip", z.ZodTypeAny, {
-    followers: number;
     following: number;
-}, {
     followers: number;
+}, {
     following: number;
+    followers: number;
 }>;
 export type RecommendationCount = z.infer<typeof recommendationCountSchema>;
 /**
@@ -205,11 +205,11 @@ export declare const recommendationItemSchema: z.ZodObject<{
         followers: z.ZodNumber;
         following: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        followers: number;
         following: number;
-    }, {
         followers: number;
+    }, {
         following: number;
+        followers: number;
     }>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodString;
@@ -230,11 +230,11 @@ export declare const recommendationItemSchema: z.ZodObject<{
         followers: z.ZodNumber;
         following: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        followers: number;
         following: number;
-    }, {
         followers: number;
+    }, {
         following: number;
+        followers: number;
     }>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodString;
@@ -255,11 +255,11 @@ export declare const recommendationItemSchema: z.ZodObject<{
         followers: z.ZodNumber;
         following: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        followers: number;
         following: number;
-    }, {
         followers: number;
+    }, {
         following: number;
+        followers: number;
     }>;
 }, z.ZodTypeAny, "passthrough">>;
 export type RecommendationItem = z.infer<typeof recommendationItemSchema>;
@@ -283,11 +283,11 @@ export declare const recommendationResponseSchema: z.ZodArray<z.ZodObject<{
         followers: z.ZodNumber;
         following: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        followers: number;
         following: number;
-    }, {
         followers: number;
+    }, {
         following: number;
+        followers: number;
     }>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     id: z.ZodString;
@@ -308,11 +308,11 @@ export declare const recommendationResponseSchema: z.ZodArray<z.ZodObject<{
         followers: z.ZodNumber;
         following: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        followers: number;
         following: number;
-    }, {
         followers: number;
+    }, {
         following: number;
+        followers: number;
     }>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     id: z.ZodString;
@@ -333,11 +333,11 @@ export declare const recommendationResponseSchema: z.ZodArray<z.ZodObject<{
         followers: z.ZodNumber;
         following: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        followers: number;
         following: number;
-    }, {
         followers: number;
+    }, {
         following: number;
+        followers: number;
     }>;
 }, z.ZodTypeAny, "passthrough">>, "many">;
 export type RecommendationResponse = z.infer<typeof recommendationResponseSchema>;

package/dist/types/updates.d.ts

@@ -337,6 +337,7 @@ export declare const createUpdateRequestSchema: z.ZodObject<{
     /** Human-readable publish message (console display). */
     message: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    channel: string;
     applicationId: string;
     assets: {
         sha256: string;
@@ -344,7 +345,6 @@ export declare const createUpdateRequestSchema: z.ZodObject<{
         key: string;
         fileExtension?: string | undefined;
     }[];
-    channel: string;
     runtimeVersion: string;
     platform: "ios" | "android";
     launchAsset: {
@@ -364,6 +364,7 @@ export declare const createUpdateRequestSchema: z.ZodObject<{
     gitCommit?: string | undefined;
     gitBranch?: string | undefined;
 }, {
+    channel: string;
     applicationId: string;
     assets: {
         sha256: string;
@@ -371,7 +372,6 @@ export declare const createUpdateRequestSchema: z.ZodObject<{
         key: string;
         fileExtension?: string | undefined;
     }[];
-    channel: string;
     runtimeVersion: string;
     platform: "ios" | "android";
     launchAsset: {