recflare/apps/accounts/src/openapi.ts

import { resolver } from 'hono-openapi'
import { z } from 'zod'

import type { OpenAPIV3_1 } from 'openapi-types'

/**
 * OpenAPI schemas for the accounts worker.
 *
 * IMPORTANT: these are DESCRIPTIVE ONLY. They are passed to `describeRoute` to
 * generate the spec and are never wired into `hono-openapi`'s `validator()`.
 *
 * As with the auth worker, this is deliberate. The Rec Room client is the only real
 * consumer and the handlers are intentionally lenient — form fields are read as
 * `typeof value === 'string' ? value : ''` and missing/malformed input falls through
 * to a graceful path (or a synthesized default account) rather than a hard error.
 * These schemas record what the client is observed to send and what we send back; to
 * enforce one, do it per-route and land a test with it.
 */

/** Emit a zod schema as an `application/json` response body. */
export function json(schema: z.ZodType, description: string) {
	return { description, content: { 'application/json': { schema: resolver(schema) } } }
}

/**
 * Emit a zod schema as a form request body. `describeRoute`'s `requestBody` takes a
 * plain OpenAPI schema (not a `resolver()`), so convert here. zod's `$schema` key and
 * `additionalProperties: false` are dropped — these handlers read the fields they know
 * and ignore the rest, so claiming a closed object would misreport them as stricter
 * than they are. The client posts both urlencoded and multipart, hence the wildcard.
 */
export function form(schema: z.ZodType, description: string): OpenAPIV3_1.RequestBodyObject {
	const { $schema: _$schema, additionalProperties: _extra, ...jsonSchema } = z.toJSONSchema(schema)
	return {
		description,
		content: {
			// zod's JSONSchema type is far wider than OpenAPI's SchemaObject; cast at the
			// boundary (the emitted value is valid OpenAPI 3.1).
			'application/x-www-form-urlencoded': { schema: jsonSchema as OpenAPIV3_1.SchemaObject },
			'multipart/form-data': { schema: jsonSchema as OpenAPIV3_1.SchemaObject },
		},
	}
}

/**
 * The public account DTO (`toAccountDto`) — the camelCase shape returned for any
 * account, with private fields (email, birthday) excluded. Fields the client parses
 * as enums are numbers here.
 */
export const AccountDto = z.object({
	accountId: z.int(),
	username: z.string(),
	displayName: z.string(),
	profileImage: z.string().describe('Avatar object key'),
	bannerImage: z.string().describe('Profile banner key — always "" (nothing sets it yet)'),
	displayEmoji: z.string().describe('Emoji beside the display name — always "" (nothing sets it yet)'),
	isJunior: z.boolean(),
	platforms: z.int().describe('PlatformType bitmask of linked platforms'),
	personalPronouns: z.int().describe('Pronoun flags bitmask'),
	identityFlags: z.int().describe('Identity flags bitmask'),
	createdAt: z.iso.datetime(),
})

/**
 * The private self DTO (`toSelfAccountDto`, the `/account/me` shape) — the public DTO
 * plus owner-only fields. `juniorState`/`parentAccountId` are omitted entirely when
 * unset (emitting `null` makes the client's enum parser throw); `email`/`birthday` are
 * kept as nullable since they aren't enums.
 */
export const SelfAccountDto = AccountDto.extend({
	email: z.string().nullable(),
	birthday: z.null().describe('Always null — birthday is not stored'),
	availableUsernameChanges: z.int().describe('Remaining username changes'),
})

/** Player bio, from `GET /account/:id/bio`. */
export const BioResponse = z.object({
	accountId: z.int(),
	bio: z.string().describe('"" when unset'),
})

/** A bare `{ success: true }` ack, returned by most profile mutations. */
export const SuccessResponse = z.object({ success: z.literal(true) })

/** The RecNet result envelope `{ success, value }` used by create + username change. */
export function envelope(value: z.ZodType) {
	return z.object({
		success: z.boolean(),
		value,
		error: z.string().optional().describe('Present (with success:false) on failure'),
	})
}

/**
 * The username-change envelope. Always HTTP 200 even on failure: `success:false` with
 * a message in `error` and `value` an empty string; on success `value` is the updated
 * public account.
 */
export const UsernameResult = envelope(z.union([AccountDto, z.literal('')])).describe(
	'value is the updated account on success, "" on failure'
)

/** `POST /account/create` response. */
export const CreateAccountResult = envelope(AccountDto)

/** `GET /parentalcontrol/me` response. */
export const ParentalControl = z.object({ accountId: z.int(), disallowInAppPurchases: z.boolean() })

/**
 * `GET /accountprivacysettings/:id` response. A bare `{}` fails the client's
 * deserializer, so the id is echoed back and recent history reported visible; nothing
 * stores per-player privacy yet.
 */
export const PrivacySettings = z.object({ accountId: z.int(), isRecentHistoryVisible: z.boolean() })

/** Root health check. */
export const HealthResponse = z.object({ service: z.literal('accounts'), status: z.literal('ok') })

// ---- Request bodies --------------------------------------------------------

/** `POST /account/create` form body. Both fields are parsed but not yet persisted. */
export const CreateAccountRequest = z.object({
	platform: z.string().optional().describe('PlatformType integer string; defaults to 0'),
	platformId: z.string().optional().describe('Parsed for fidelity; currently unused'),
})

/** Single-string form bodies, one per profile mutation. */
export const DisplayNameRequest = z.object({
	displayName: z.string().describe('Trimmed; empty is rejected (400)'),
})

export const UsernameRequest = z.object({
	username: z.string().describe('Trimmed; must be unique and changes must remain'),
})

export const EmailRequest = z.object({
	email: z.string().describe('Must contain "@"; otherwise 400'),
})

export const PhoneRequest = z.object({
	phone: z.string().describe('Trimmed; empty is rejected (400)'),
})

export const IdentityFlagsRequest = z.object({
	identityFlags: z.string().describe('Integer string bitmask; non-numeric is 400'),
})

export const PronounsRequest = z.object({
	pronounFlags: z.string().describe('Integer string bitmask; non-numeric is 400'),
})

export const BioRequest = z.object({ bio: z.string().describe('Free text; empty is allowed') })

export const ProfileImageRequest = z.object({
	imageName: z.string().describe('Avatar object key; empty is rejected (400)'),
})