@oxyhq/contracts 0.21.0 → 0.22.0

package/dist/esm/accountGraph.js

@@ -1,11 +1,71 @@
 /**
- * Account graph wire contracts — organization taxonomy and create-account input.
+ * Account graph wire contracts — the account-kind vocabulary, organization
+ * taxonomy, and create-account input.
  *
  * `organizationCategory` classifies `kind: 'organization'` accounts (agency,
  * cooperative, landlord, …) without polluting `User.kind`. Meaningful only when
  * `kind === 'organization'`.
  */
 import { z } from 'zod';
+/**
+ * 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
+ * `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 `@oxyhq/services` through
+ * `SwitchableAccount`, where an indexed-access type is materially more
+ * expensive to check than a literal union.
+ */
+export const ACCOUNT_KINDS = [
+    'personal',
+    'organization',
+    'project',
+    'bot',
+    'channel',
+];
+export const accountKindSchema = z.enum(ACCOUNT_KINDS);
+export const CHILD_ACCOUNT_KINDS = [
+    'organization',
+    'project',
+    'bot',
+    'channel',
+];
+export const childAccountKindSchema = z.enum(CHILD_ACCOUNT_KINDS);
+/**
+ * Whether an operator may ACT AS an account of this kind — switch the whole app
+ * into it (`POST /accounts/:id/switch`) or authorise an app to act as it
+ * (an OAuth delegated subject).
+ *
+ * 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 function isActAsEligibleKind(kind) {
+    return kind === 'organization' || kind === 'project' || kind === 'bot';
+}
+/**
+ * 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 function isAccountKind(value) {
+    return typeof value === 'string' && ACCOUNT_KINDS.includes(value);
+}
 export const ORGANIZATION_CATEGORIES = [
     'agency',
     'cooperative',
@@ -13,10 +73,25 @@ export const ORGANIZATION_CATEGORIES = [
     'other',
 ];
 export const organizationCategorySchema = z.enum(ORGANIZATION_CATEGORIES);
+/**
+ * An account's name on the create/update wire.
+ *
+ * `displayName` is EXPLICIT and stored, not derived. `first`/`last` model a
+ * human name, and composing a display string from them is right for a person —
+ * but a non-personal account has a TITLE, not a given and family name. Without
+ * this field the only way to name a channel "Notas de Nate" was to put the whole
+ * title in `first`, which renders correctly by accident while recording it as
+ * somebody's given name.
+ *
+ * When present it wins over the composed `first`/`last` (see the API's
+ * `composeDisplayName`, which already preferred an explicit value — only the
+ * storage for one was missing).
+ */
 const accountNameSchema = z
     .object({
     first: z.string().trim().max(100).optional(),
     last: z.string().trim().max(100).optional(),
+    displayName: z.string().trim().max(100).optional(),
 })
     .optional();
 /**
@@ -26,7 +101,7 @@ const accountNameSchema = z
 export const createAccountRequestSchema = z
     .object({
     parentAccountId: z.string().trim().min(1).optional(),
-    kind: z.enum(['organization', 'project', 'bot']),
+    kind: childAccountKindSchema,
     username: z.string().trim().min(1).max(100),
     name: accountNameSchema,
     bio: z.string().trim().max(500).optional(),

package/dist/esm/index.js

@@ -9,7 +9,7 @@
  * Platform-agnostic — zod is the only runtime dependency. No react/react-native/
  * expo, no `require()` in the ESM build.
  */
-export { ORGANIZATION_CATEGORIES, organizationCategorySchema, createAccountRequestSchema, } from './accountGraph.js';
+export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isActAsEligibleKind, ORGANIZATION_CATEGORIES, organizationCategorySchema, createAccountRequestSchema, } from './accountGraph.js';
 export { 
 // Schemas
 userNameSchema, userRelationshipSchema, themePreferenceSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, 

package/dist/esm/userResponse.js

@@ -30,7 +30,7 @@
  */
 import { z } from 'zod';
 import { verifiedDomainSchema } from './identity.js';
-import { organizationCategorySchema } from './accountGraph.js';
+import { accountKindSchema, organizationCategorySchema } from './accountGraph.js';
 export const userNameSchema = z
     .object({
     first: z.string().optional(),
@@ -100,9 +100,23 @@ export const userResponseSchema = z
      * entry; present only when the account has verified at least one domain.
      */
     verifiedDomains: z.array(verifiedDomainSchema).optional(),
+    /**
+     * Account-graph classification — what KIND of account this is.
+     *
+     * ORTHOGONAL to `type` (`local` / `federated` / `agent` / `automated`),
+     * which says where the account lives and how it is driven; the two
+     * coexist and neither substitutes for the other. A `channel` is a
+     * publishing identity nobody can act as, so a consumer that renders
+     * authored content reads THIS to tell a channel's post from a person's.
+     *
+     * Optional because a DTO produced from a source that never carried the
+     * column omits it; absent should be read as `personal`, the column's
+     * default, not as unknown.
+     */
+    kind: accountKindSchema.optional(),
     /**
      * Real-estate / team taxonomy for `kind: 'organization'` accounts.
-     * Absent on personal, project, and bot accounts.
+     * Absent on personal, project, bot, and channel accounts.
      */
     organizationCategory: organizationCategorySchema.optional(),
     /**
@@ -126,6 +140,12 @@ export const userProfileUpdateSchema = z
         .object({
         first: z.string().optional(),
         last: z.string().optional(),
+        /**
+         * Explicit display name, stored rather than composed. Wins over
+         * `first`/`last` when set; send `''` to clear it and fall back
+         * to the composed pair.
+         */
+        displayName: z.string().optional(),
     })
         .optional(),
     username: z.string().optional(),