@oxy.so/contracts 4.12.0 → 4.13.0

package/dist/esm/accountGraph.js

@@ -7,6 +7,7 @@
  * {@link ACCOUNT_CATEGORY_IDS} for the four rules that govern it.
  */
 import { z } from 'zod';
+import { avatarCharacterSchema } from './avatarCharacter.js';
 import { usernameSchema, usernameSchemaForAccountKind } from './username.js';
 /**
  * The union is spelled out above and the array proves coverage BOTH ways
@@ -466,8 +467,22 @@ export const createAccountRequestSchema = z
      * remedy must not either.
      */
     isPrivateAccount: z.boolean().optional(),
+    /**
+     * The 3D avatar character of a `bot` — and ONLY of a bot (the refinement
+     * below). Optional on the wire: a bot created without one is given a look
+     * seeded from its handle (`avatarCharacterFor`), so every bot account has a
+     * character from birth and the owner customizes it afterwards.
+     */
+    character: avatarCharacterSchema.optional(),
 })
     .superRefine((request, ctx) => {
+    if (request.character !== undefined && request.kind !== 'bot') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['character'],
+            message: 'Only a bot account carries an avatar character',
+        });
+    }
     // The ONE place `kind` and `username` arrive in the same object, so it is the
     // only place a wire schema CAN apply the per-kind half of the policy: a bot's
     // handle must end in `bot`. Not a second rule — it asks

package/dist/esm/avatarCharacter.js

@@ -0,0 +1,115 @@
+/**
+ * The 3D avatar character a `bot` account carries.
+ *
+ * ONE definition for the wire shape, its validator and the generator that picks
+ * a look for a new bot, shared by the Oxy API (which stores and serves it) and
+ * every client. It mirrors Bloom's flat `AvatarCharacter`
+ * (`@oxy.so/bloom/agent-avatar`).
+ *
+ * ## The vocabulary is Bloom's and is NOT enforced here
+ *
+ * Bloom is a React Native package this one cannot depend on, so the ids a
+ * character is made of are restated below as a curated SUBSET, only to PICK a
+ * look for a new bot ({@link avatarCharacterFor}). A STORED character is never
+ * checked against them: validating against a stale copy of somebody else's
+ * catalogue is how a working look starts being refused. What the schema checks
+ * is the SHAPE of what a client writes: only the keys a character has, each an
+ * id-like string, a `#rrggbb` paint, a spacing in range. The client resolves
+ * the ids and falls back on a default look for one it cannot draw.
+ */
+import { z } from 'zod';
+const ID = /^[a-z][a-z0-9_]{0,39}$/;
+const HEX = /^#[0-9a-fA-F]{6}$/;
+/** Bounds of {@link AvatarCharacter.eyeSpacing}. */
+export const AVATAR_EYE_SPACING = { min: 0.5, max: 1.5 };
+const idSchema = z.string().regex(ID);
+/**
+ * A character a client sends. `.strict()` so a misspelled field is a refusal
+ * now rather than a look that never takes effect. A character with nothing in
+ * it draws nothing: it needs a preset, or a shape and a paint.
+ */
+export const avatarCharacterSchema = z
+    .object({
+    preset: idSchema.optional(),
+    shape: idSchema.optional(),
+    eyes: idSchema.optional(),
+    eyewear: idSchema.optional(),
+    accessory: idSchema.optional(),
+    color: idSchema.optional(),
+    bodyColor: z
+        .string()
+        .regex(HEX)
+        .transform((hex) => hex.toLowerCase())
+        .optional(),
+    eyeSpacing: z
+        .number()
+        .finite()
+        .min(AVATAR_EYE_SPACING.min)
+        .max(AVATAR_EYE_SPACING.max)
+        .optional(),
+})
+    .strict()
+    .refine((c) => c.preset !== undefined ||
+    (c.shape !== undefined && (c.color !== undefined || c.bodyColor !== undefined)), { message: 'A character needs a preset, or a shape and a color' });
+/** The validated character, or `null` for anything that is not one. */
+export function parseAvatarCharacter(value) {
+    const parsed = avatarCharacterSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+/** The parts a new bot's look is picked from: the plain, friendly shapes, in the editor's order. */
+export const AVATAR_PICKABLE_SHAPES = [
+    'rounded_triangle',
+    'capsule',
+    'rounded_head_two_ears',
+    'six_lobed_flower',
+    'heart',
+    'four_lobed_butterfly',
+    'circle_two_ears',
+    'twelve_scalloped_rosette',
+    'rounded_cube',
+    'rounded_diamond',
+    'slender',
+    'pocket',
+    'petal',
+    'star',
+    'cloud',
+    'shield',
+    'pebble',
+    'squircle',
+];
+/** Bloom's named paints. */
+export const AVATAR_PICKABLE_COLORS = [
+    'pink',
+    'orchid',
+    'violet',
+    'blue',
+    'cyan',
+    'teal',
+    'lime',
+    'yellow',
+    'coral',
+];
+/** A small, stable hash: the same seed always picks the same look. */
+function hash(seed) {
+    let h = 2166136261;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/**
+ * A look for a new bot, picked from its seed (its handle): a shape and a paint,
+ * plain oval eyes, nothing on its head. Stable — the same seed is the same look
+ * — and the owner changes it afterwards.
+ */
+export function avatarCharacterFor(seed) {
+    const h = hash(seed);
+    return {
+        shape: AVATAR_PICKABLE_SHAPES[h % AVATAR_PICKABLE_SHAPES.length],
+        eyes: 'oval',
+        eyewear: 'none',
+        accessory: 'none',
+        color: AVATAR_PICKABLE_COLORS[Math.floor(h / AVATAR_PICKABLE_SHAPES.length) % AVATAR_PICKABLE_COLORS.length],
+    };
+}

package/dist/esm/index.js

@@ -10,6 +10,7 @@
  * expo, no `require()` in the ESM build.
  */
 export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, 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.js';
+export { AVATAR_EYE_SPACING, AVATAR_PICKABLE_COLORS, AVATAR_PICKABLE_SHAPES, avatarCharacterFor, avatarCharacterSchema, parseAvatarCharacter, } from './avatarCharacter.js';
 export { ACCOUNT_ACTOR_NATURES, ACCOUNT_SUBJECT_CONTRACT_VERSION, FINANCIAL_EFFECT_DIRECTIONS, KIND_INDEPENDENT_ACCOUNT_DIMENSIONS, accountActorChainFromSession, accountActorChainSchema, accountActorNatureSchema, accountKindActorNature, accountKindActsAsItself, attributeFinancialEffect, financialEffectAttributionSchema, } from './accountSubject.js';
 export { usernameSchema, usernameSchemaForAccountKind, isValidUsername, stripDisallowedUsernameCharacters, applyBotUsernameSuffix, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, BOT_USERNAME_INVALID_MESSAGE, RESERVED_USERNAME_MESSAGE, NUMERIC_USERNAME_MESSAGE, } from './username.js';
 export { 

package/dist/esm/recommendations.js

@@ -11,6 +11,7 @@
  * / expo, ESM-safe).
  */
 import { z } from 'zod';
+import { avatarCharacterSchema } from './avatarCharacter.js';
 import { userNameSchema } from './userResponse.js';
 /** User-type filters a caller may exclude from the recommendation surface. */
 export const recommendationExcludeTypeSchema = z.enum(['federated', 'agent', 'automated']);
@@ -77,6 +78,8 @@ export const recommendationItemSchema = z
     username: z.string().optional(),
     name: userNameSchema,
     avatar: z.string().nullable().optional(),
+    /** A bot's 3D avatar character; absent for every other kind. */
+    character: avatarCharacterSchema.optional(),
     /** The account's accent colour, as on every profile; absent when unset. */
     color: z.string().optional(),
     description: z.string().nullable().optional(),

package/dist/esm/userResponse.js

@@ -46,6 +46,7 @@ export const USER_PROFILE_COLOR_PRESETS = [
 import { z } from 'zod';
 import { verifiedDomainSchema } from './identity.js';
 import { accountCategoriesSchema, accountKindSchema } from './accountGraph.js';
+import { avatarCharacterSchema } from './avatarCharacter.js';
 export const userNameSchema = z
     .object({
     first: z.string().optional(),
@@ -222,6 +223,12 @@ export const userResponseSchema = z
      * `user.accountCategories ?? []`.
      */
     accountCategories: accountCategoriesSchema.optional(),
+    /**
+     * The 3D avatar character of a `kind: 'bot'` account — what Bloom's
+     * `Avatar` draws instead of a picture. Present ONLY on a bot's payload,
+     * never on a person's or an organization's, so those DTOs do not grow.
+     */
+    character: avatarCharacterSchema.optional(),
     /**
      * The authenticated viewer's relationship to this profile. Present ONLY
      * on single-profile fetches (`GET /profiles/username/:username`,