@oxy.so/contracts 4.12.0 → 4.14.0

package/dist/esm/accountGraph.js

@@ -7,6 +7,8 @@
  * {@link ACCOUNT_CATEGORY_IDS} for the four rules that govern it.
  */
 import { z } from 'zod';
+import { avatarCharacterSchema } from './avatarCharacter.js';
+import { ORGANIZATION_TYPES, ORGANIZATION_NAME_MAX_LENGTH, organizationNameSchema, } from './organizations.js';
 import { usernameSchema, usernameSchemaForAccountKind } from './username.js';
 /**
  * The union is spelled out above and the array proves coverage BOTH ways
@@ -368,11 +370,11 @@ export function kindAcceptsAccountCategories(kind) {
  * `composeDisplayName`, which already preferred an explicit value — only the
  * storage for one was missing).
  */
-const accountNameSchema = z
+export 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(),
+    displayName: z.string().trim().max(ORGANIZATION_NAME_MAX_LENGTH).optional(),
 })
     .optional();
 /**
@@ -425,6 +427,7 @@ export const createAccountRequestSchema = z
     color: z.string().trim().max(32).optional(),
     /** Ordered, PRIMARY FIRST — see rule 2 above {@link ACCOUNT_CATEGORY_IDS}. */
     accountCategories: accountCategoriesSchema.optional(),
+    organizationType: z.enum(ORGANIZATION_TYPES).optional(),
     /**
      * Create the account already opted OUT of discovery.
      *
@@ -466,8 +469,39 @@ 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',
+        });
+    }
+    const displayName = request.name?.displayName;
+    if (displayName) {
+        const parsedName = request.kind === 'organization'
+            ? organizationNameSchema.safeParse(displayName)
+            : z.string().max(100).safeParse(displayName);
+        if (!parsedName.success) {
+            for (const issue of parsedName.error.issues) {
+                ctx.addIssue({ ...issue, path: ['name', 'displayName', ...issue.path] });
+            }
+        }
+    }
+    if (request.organizationType !== undefined && request.kind !== 'organization')
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['organizationType'],
+            message: 'Organization type requires an organization account',
+        });
     // 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

@@ -9,7 +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, 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 { 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, accountNameSchema, } 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 { 
@@ -201,3 +202,5 @@ export * from './agentKeys.js';
 export { productSubscriptionSummarySchema, productSubscriptionsResponseSchema, subscriptionCreditGrantSchema, subscriptionCreditGrantsResponseSchema, cancelProductSubscriptionSchema, productSubscriptionCancellationResultSchema, } from './products/billing.js';
 export { personalPlanDisplayPriceSchema, personalPlanCatalogueSchema, } from './products/plans.js';
 export * from './products/checkout.js';
+export * from './organizations.js';
+export * from './safety.js';

package/dist/esm/organizations.js

@@ -0,0 +1,207 @@
+import { z } from 'zod';
+/** Real-world identity classification, independent of account topics and permissions. */
+export const ORGANIZATION_TYPES = [
+    'business',
+    'nonprofit',
+    'public_body',
+    'community',
+    'other',
+];
+export const ORGANIZATION_STATUSES = ['active', 'inactive', 'merged', 'suppressed'];
+export const ORGANIZATION_CLAIM_STATUSES = ['unclaimed', 'claimed'];
+export const ORGANIZATION_ALIAS_KINDS = [
+    'name_variant',
+    'former_name',
+    'localized_name',
+    'marketing_name',
+    'misspelling',
+];
+export const ORGANIZATION_CLAIM_DECISIONS = ['pending', 'approved', 'rejected'];
+const id = z.string().min(1).max(128);
+const optionalText = (max) => z.string().trim().min(1).max(max).nullable().optional();
+export const organizationAliasSchema = z
+    .object({
+    alias: z.string().trim().min(1).max(300),
+    kind: z.enum(ORGANIZATION_ALIAS_KINDS),
+    language: z.string().min(2).max(35).optional(),
+})
+    .strict();
+export const ORGANIZATION_NAME_MAX_LENGTH = 300;
+export const organizationNameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(ORGANIZATION_NAME_MAX_LENGTH)
+    .refine((value) => !/[<>]/.test(value) &&
+    Array.from(value).every((character) => character.charCodeAt(0) >= 32 && character.charCodeAt(0) !== 127), 'Organization name must be plain text');
+export const createOrganizationSchema = z
+    .object({
+    name: organizationNameSchema,
+    organizationType: z.enum(ORGANIZATION_TYPES),
+    legalName: optionalText(300),
+    websiteUrl: z
+        .string()
+        .url()
+        .max(2048)
+        .refine((value) => /^https?:\/\//.test(value), 'Use HTTP or HTTPS')
+        .nullable()
+        .optional(),
+    countryCode: z
+        .string()
+        .regex(/^[A-Z]{2}$/)
+        .nullable()
+        .optional(),
+    aliases: z.array(organizationAliasSchema).max(100).optional(),
+})
+    .strict();
+export const updateOrganizationSchema = createOrganizationSchema.partial();
+export const organizationSchema = createOrganizationSchema
+    .extend({
+    accountId: id,
+    username: z.string().nullable(),
+    avatar: z.string().nullable(),
+    legalName: z.string().nullable(),
+    websiteUrl: z.string().nullable(),
+    countryCode: z.string().nullable(),
+    aliases: z.array(organizationAliasSchema),
+    verifiedDomains: z.array(z.string()),
+    claimStatus: z.enum(ORGANIZATION_CLAIM_STATUSES),
+    status: z.enum(ORGANIZATION_STATUSES),
+    mergedIntoAccountId: id.nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .strict();
+export const organizationSearchSchema = z
+    .object({
+    query: z.string().trim().max(200).default(''),
+    organizationType: z.enum(ORGANIZATION_TYPES).optional(),
+    limit: z.coerce.number().int().min(1).max(50).default(20),
+    cursor: z.string().min(1).max(2048).optional(),
+})
+    .strict();
+export const organizationListSchema = z
+    .object({ items: z.array(organizationSchema), nextCursor: z.string().nullable() })
+    .strict();
+export const organizationBatchInputSchema = z.object({ ids: z.array(id).min(1).max(100) }).strict();
+export const organizationBatchSchema = z
+    .object({
+    items: z.array(z.object({ requestedAccountId: id, organization: organizationSchema }).strict()),
+    missingIds: z.array(id),
+})
+    .strict();
+export const organizationClaimInputSchema = z
+    .object({
+    evidenceReference: z.string().trim().min(1).max(1000),
+})
+    .strict();
+export const organizationClaimSchema = z
+    .object({
+    id,
+    accountId: id,
+    claimantUserId: id,
+    status: z.enum(ORGANIZATION_CLAIM_DECISIONS),
+    createdAt: z.string().datetime(),
+})
+    .strict();
+export const organizationClaimDetailSchema = organizationClaimSchema
+    .extend({
+    evidenceReference: z.string(),
+    reviewEvidenceReference: z.string().nullable(),
+    reviewedAt: z.string().datetime().nullable(),
+})
+    .strict();
+export const organizationClaimListQuerySchema = z
+    .object({
+    status: z.enum(ORGANIZATION_CLAIM_DECISIONS).optional(),
+    limit: z.coerce.number().int().min(1).max(50).default(20),
+    cursor: z.string().min(1).max(2048).optional(),
+})
+    .strict();
+export const organizationClaimListSchema = z
+    .object({ items: z.array(organizationClaimDetailSchema), nextCursor: z.string().nullable() })
+    .strict();
+export const organizationClaimReviewSchema = z
+    .object({
+    decision: z.enum(['approved', 'rejected']),
+    evidenceReference: z.string().trim().min(1).max(1000),
+})
+    .strict();
+export const organizationExternalInputSchema = z
+    .object({
+    namespace: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+    externalId: z.string().min(1).max(256),
+    accountId: id.optional(),
+    organization: createOrganizationSchema,
+    evidenceReference: z.string().trim().min(1).max(1000),
+    avatarFileId: id.optional(),
+})
+    .strict();
+/** Automated ingestion can create neutral identities in its granted namespace only. */
+export const organizationImportBatchSchema = z
+    .object({
+    namespace: organizationExternalInputSchema.shape.namespace,
+    items: z
+        .array(organizationExternalInputSchema.pick({
+        externalId: true,
+        organization: true,
+        evidenceReference: true,
+        avatarFileId: true,
+    }))
+        .min(1)
+        .max(100),
+})
+    .strict()
+    .refine((input) => new Set(input.items.map((item) => item.externalId)).size === input.items.length, 'External IDs must be unique within the batch');
+export const organizationImportBatchResultSchema = z
+    .object({
+    items: z.array(z.object({ externalId: z.string(), accountId: id, created: z.boolean() }).strict()),
+})
+    .strict();
+export const organizationExternalSchema = z
+    .object({ accountId: id, created: z.boolean() })
+    .strict();
+export const organizationExternalResolutionSchema = z.object({ accountId: id }).strict();
+export const organizationMergeSchema = z
+    .object({
+    targetAccountId: id,
+    evidenceReference: z.string().trim().min(1).max(1000),
+})
+    .strict();
+export const ORGANIZATION_ERROR_CODES = [
+    'bad_request',
+    'unauthorized',
+    'forbidden',
+    'not_found',
+    'unknown_route',
+    'conflict',
+    'validation_failed',
+    'rate_limited',
+    'internal_error',
+    'service_unavailable',
+];
+export const organizationErrorSchema = z
+    .object({
+    error: z
+        .object({
+        code: z.enum(ORGANIZATION_ERROR_CODES),
+        message: z.string(),
+        details: z
+            .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+            .optional(),
+    })
+        .strict(),
+})
+    .strict();
+/** Staff curation corrects neutral facts or moderates visibility without claiming ownership. */
+export const organizationCurationSchema = z
+    .object({
+    changes: updateOrganizationSchema.optional(),
+    status: z.enum(['active', 'inactive', 'suppressed']).optional(),
+    evidenceReference: z.string().trim().min(1).max(1000),
+})
+    .strict()
+    .refine((input) => input.changes !== undefined || input.status !== undefined, 'At least one change is required');
+export const organizationCurationResultSchema = z
+    .object({ accountId: id, status: z.enum(['active', 'inactive', 'suppressed']) })
+    .strict();

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/safety.js

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+/** The requester is authenticated by the bearer; applications cannot submit viewer IDs. */
+export const profileAccessInputSchema = z
+    .object({ subjectAccountId: z.string().min(1).max(128) })
+    .strict();
+export const profileAccessDecisionSchema = z
+    .object({
+    allowed: z.boolean(),
+    reason: z.enum(['public', 'owner', 'private', 'blocked', 'unavailable']),
+    policyVersion: z.literal('1'),
+})
+    .strict();

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`,