@oxy.so/contracts 4.13.0 → 4.15.0

package/dist/esm/accountGraph.js

@@ -8,6 +8,7 @@
  */
 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
@@ -369,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();
 /**
@@ -426,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.
      *
@@ -483,6 +485,23 @@ export const createAccountRequestSchema = z
             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/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 { 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';
@@ -200,5 +200,7 @@ export { meteredGenerationSchema } from './inference/economics.js';
 export { canonicalCapabilityJson, inputSatisfiesCapabilityLimits, isLoopbackOrigin, } from './capabilityBindings.js';
 export * from './agentKeys.js';
 export { productSubscriptionSummarySchema, productSubscriptionsResponseSchema, subscriptionCreditGrantSchema, subscriptionCreditGrantsResponseSchema, cancelProductSubscriptionSchema, productSubscriptionCancellationResultSchema, } from './products/billing.js';
-export { personalPlanDisplayPriceSchema, personalPlanCatalogueSchema, } from './products/plans.js';
+export { personalPlanDisplayPriceSchema, personalPlanCatalogueSchema, productPlanCatalogueSchema, } 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/products/billing.js

@@ -24,6 +24,7 @@ export const productSubscriptionSummarySchema = z
     period,
     cancelAtPeriodEnd: z.boolean(),
     canCancel: z.boolean(),
+    canRenew: z.boolean().optional(),
     offers: z.array(z
         .object({
         segmentId: id,

package/dist/esm/products/checkout.js

@@ -30,3 +30,16 @@ export const personalPlanCheckoutResultSchema = z.discriminatedUnion('state', [
     z.object({ state: z.literal('closed'), intentId: z.string().min(1).max(160) }).strict(),
     z.object({ state: z.literal('fulfilled'), intentId: z.string().min(1).max(160) }).strict(),
 ]);
+/** Explicit individual product offer; still owned and paid through Oxy. */
+export const productPlanCheckoutRequestSchema = personalPlanCheckoutRequestSchema
+    .extend({
+    productId: z.string().min(1).max(160),
+})
+    .strict();
+export const productSubscriptionRenewalRequestSchema = z
+    .object({
+    expectedSubjectAccountId: oxyAccountIdSchema,
+    sourceId: z.string().min(1).max(160),
+    idempotencyKey: personalPlanCheckoutRequestSchema.shape.idempotencyKey,
+})
+    .strict();

package/dist/esm/products/plans.js

@@ -16,7 +16,7 @@ export const personalPlanCatalogueSchema = z
     .object({
     schemaVersion: z.literal(1),
     state: z.enum(['unconfigured', 'configured']),
-    purchase: z.literal('unavailable'),
+    purchase: z.enum(['unavailable', 'available']),
     plans: z.array(z
         .object({
         offerId: z.string().min(1).max(160),
@@ -33,3 +33,19 @@ export const personalPlanCatalogueSchema = z
 })
     .strict()
     .refine((value) => (value.state === 'unconfigured') === (value.plans.length === 0), 'Catalogue state must match published plans');
+export const productPlanCatalogueSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    productId: z.string().min(1).max(160),
+    purchase: z.enum(['unavailable', 'available']),
+    plans: z.array(z
+        .object({
+        productId: z.string().min(1).max(160),
+        offerId: z.string().min(1).max(160),
+        offerVersion: z.number().int().positive().safe(),
+        displayName: z.string().min(1).max(100),
+        price: personalPlanDisplayPriceSchema.extend({ interval: z.enum(['month', 'year']) }),
+    })
+        .strict()),
+})
+    .strict();

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

@@ -241,6 +241,10 @@ export const userResponseSchema = z
      * so it is present on the current-user DTO (`GET /users/me`,
      * `GET /session/user/:sessionId`) and absent until the user sets it.
      */
+    userPreferences: z
+        .object({ displayCurrency: z.enum(['USD', 'EUR', 'FAIR']).optional() })
+        .catchall(z.unknown())
+        .optional(),
     themePreference: themePreferenceSchema.optional(),
     personalization: z
         .object({
@@ -301,7 +305,10 @@ export const userProfileUpdateSchema = z
     languages: z.array(z.string()).optional(),
     accountExpiresAfterInactivityDays: z.number().nullable().optional(),
     notificationPreferences: z.record(z.unknown()).optional(),
-    userPreferences: z.record(z.unknown()).optional(),
+    userPreferences: z
+        .object({ displayCurrency: z.enum(['USD', 'EUR', 'FAIR']).optional() })
+        .catchall(z.unknown())
+        .optional(),
     privacySettings: z.record(z.unknown()).optional(),
     /**
      * Portable theme preference. Written through the same `PUT /users/me`