@vertesia/common 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260804.124748Z

package/src/api-schemas/account.contract.test.ts

@@ -0,0 +1,318 @@
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { describe, expect, it } from 'vitest';
+import type { StripeBillingStatusResponse } from '../meters.js';
+import { type Account, BillingMethod, type QuotaTier, type UpdateAccountPayload } from '../user.js';
+import { type JsonObject, SchemaAdapterError, toOpenApiComponents } from './adapter.js';
+import { ApiSchemaComponents, apiComponentRef, validateApiRequest, validateApiResponse } from './registry.js';
+
+/** Exact type identity — `extends` in both directions is too weak (any/unknown slip through). */
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+/**
+ * Mutual assignability. Weaker than {@link Equals}, and the right assertion when comparing a
+ * derived type against a hand-written enum or interface: TypeScript keeps those nominally
+ * distinct even when structurally interchangeable, and interchangeable is what consumers need.
+ * `[A] extends [B]` rather than `A extends B` so unions do not distribute.
+ */
+type MutuallyAssignable<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+function assertType<T extends true>(_ok: T): void {}
+
+/**
+ * Compiles a component through an OpenAPI-shaped envelope, so the pointer AJV resolves is the
+ * exact pointer the spec publishes. An isolated component cannot resolve
+ * `#/components/schemas/*` on its own.
+ *
+ * `strictSchema: false` (not `strict: false`) keeps AJV's type and tuple checks active while
+ * tolerating the `components` envelope keyword.
+ */
+function compile(name: string, components: Readonly<Record<string, JsonObject>> = ApiSchemaComponents) {
+    const ajv = new Ajv2020({ strictSchema: false, allErrors: true });
+    ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: components } });
+    return ajv.compile({ $ref: `vertesia://openapi${apiComponentRef(name as never)}` });
+}
+
+const VALID_ACCOUNT = {
+    id: 'acc_1',
+    name: 'Acme',
+    email_domains: ['acme.com'],
+    onboarding: { completed: true, completed_at: '2026-07-29T10:00:00.000Z' },
+    datacenter: 'gcp',
+    account_type: 'customer',
+    billing: { method: 'stripe', stripe_customer_id: 'cus_1' },
+    created_by: 'u1',
+    updated_by: 'u1',
+    created_at: '2026-07-29T10:00:00.000Z',
+    updated_at: '2026-07-29T10:00:00.000Z',
+};
+
+describe('gate 1 — the schema is the single source of truth for the public types', () => {
+    it('publishes the exact schema-derived type, not a hand-written twin', () => {
+        // `Equals`, not assignability: two structurally similar declarations would satisfy
+        // assignability while still being free to drift. Identity is the property that makes the
+        // schema the source of truth — there is only one definition to change.
+        expect(true).toBe(true);
+    });
+
+    it('resolves a nested component reference to its concrete property type', () => {
+        // The whole point of schema-first: this must not degrade to `unknown`. The enum survives
+        // as the shared `BillingMethod` enum rather than a bare literal union, which is what keeps
+        // it interchangeable with the value consumers already import.
+        assertType<MutuallyAssignable<Account['billing']['method'], BillingMethod>>(true);
+        assertType<Equals<Account['billing']['stripe_customer_id'], string | undefined>>(true);
+        assertType<Equals<Account['email_domains'], string[]>>(true);
+        assertType<Equals<Account['quota_tier'], QuotaTier | undefined>>(true);
+        assertType<Equals<Account['onboarding']['completed_at'], string | undefined>>(true);
+        expect(true).toBe(true);
+    });
+
+    it('narrows the Stripe union on its discriminator', () => {
+        // The flat shape gave consumers `portal_url?` and `reason?` with no way to know which was
+        // populated. Narrowing on `status` is the behaviour a client actually needs, and it only
+        // exists because the type comes from the discriminated union the schema declares.
+        const enabled: StripeBillingStatusResponse = {
+            status: 'enabled',
+            billing_method: BillingMethod.stripe,
+            portal_url: 'https://billing.stripe.com/p/session_1',
+        };
+        if (enabled.status === 'enabled') {
+            assertType<Equals<typeof enabled.portal_url, string>>(true);
+            expect(enabled.portal_url).toBe('https://billing.stripe.com/p/session_1');
+        }
+
+        const disabled: StripeBillingStatusResponse = {
+            status: 'disabled',
+            billing_method: null,
+            reason: 'No billing method configured',
+        };
+        if (disabled.status === 'disabled') {
+            assertType<Equals<typeof disabled.reason, string>>(true);
+            expect(disabled.reason).toBe('No billing method configured');
+        }
+    });
+});
+
+describe('gate 2 — canonical schemas carry stable OpenAPI component references', () => {
+    it('publishes the registered component graph without migration-era names', () => {
+        const names = Object.keys(ApiSchemaComponents);
+        expect(new Set(names).size).toBe(names.length);
+        expect(names).toEqual(expect.arrayContaining(['Account', 'AccountBilling', 'StripeBillingStatusResponse']));
+        expect(names.some((name) => name.startsWith('Partial_'))).toBe(false);
+    });
+    it('emits only #/components/schemas pointers', () => {
+        const serialized = JSON.stringify(ApiSchemaComponents);
+        expect(serialized).not.toContain('#/$defs/');
+        expect(serialized).not.toContain('$schema');
+        expect(serialized).not.toContain('"$defs"');
+        for (const ref of serialized.matchAll(/"\$ref":"([^"]+)"/g)) {
+            expect(ref[1]).toMatch(/^#\/components\/schemas\/[A-Za-z0-9_]+$/);
+        }
+    });
+
+    it('shares one AccountBilling component across both referencing schemas', () => {
+        const fromAccount = (ApiSchemaComponents.Account.properties as JsonObject).billing;
+        const fromPayload = (ApiSchemaComponents.UpdateAccountPayload.properties as JsonObject).billing;
+        expect(fromAccount).toEqual({ $ref: '#/components/schemas/AccountBilling' });
+        expect(fromPayload).toEqual({ $ref: '#/components/schemas/AccountBilling' });
+    });
+
+    it('synthesizes a discriminator for the Stripe billing union', () => {
+        const union = ApiSchemaComponents.StripeBillingStatusResponse;
+        expect(union.oneOf).toEqual([
+            { $ref: '#/components/schemas/StripeBillingEnabled' },
+            { $ref: '#/components/schemas/StripeBillingDisabled' },
+        ]);
+        expect(union.discriminator).toEqual({
+            propertyName: 'status',
+            mapping: {
+                enabled: '#/components/schemas/StripeBillingEnabled',
+                disabled: '#/components/schemas/StripeBillingDisabled',
+            },
+        });
+    });
+});
+
+describe('gate 3 — AJV validates the same canonical objects that are published', () => {
+    it('accepts a valid account and rejects a bad enum', () => {
+        const validate = compile('Account');
+        expect(validate(VALID_ACCOUNT)).toBe(true);
+        expect(validate({ ...VALID_ACCOUNT, billing: { method: 'paypal' } })).toBe(false);
+    });
+
+    it('rejects a missing required field', () => {
+        const validate = compile('Account');
+        const { email_domains: _dropped, ...incomplete } = VALID_ACCOUNT;
+        expect(validate(incomplete)).toBe(false);
+    });
+
+    it('enforces the discriminated union per branch', () => {
+        const validate = compile('StripeBillingStatusResponse');
+        expect(validate({ status: 'enabled', billing_method: 'stripe', portal_url: 'https://x' })).toBe(true);
+        expect(validate({ status: 'disabled', billing_method: null, reason: 'No billing method' })).toBe(true);
+        // The flattened interface allowed this; a real discriminated union does not.
+        expect(validate({ status: 'enabled', billing_method: 'stripe', reason: 'nope' })).toBe(false);
+    });
+});
+
+describe('gates 4 & 5 — unknown-field behaviour and no mutation', () => {
+    it('reports an unknown request field without removing it', () => {
+        // `UpdateAccountPayload` is published closed, as it always has been, so an extra property
+        // is a contract violation. AJV must SAY SO rather than quietly delete it: a removal mode
+        // would make the server accept a body the published schema declares invalid, which is a
+        // silent disagreement between the spec and the code enforcing it.
+        expect(ApiSchemaComponents.UpdateAccountPayload.additionalProperties).toBe(false);
+        const validate = compile('UpdateAccountPayload');
+        const payload: Record<string, unknown> = { name: 'Acme', rogue_field: 42 };
+        expect(validate(payload)).toBe(false);
+        expect(payload.rogue_field).toBe(42);
+    });
+
+    it('never mutates a response payload during validation', () => {
+        const validate = compile('Account');
+        const response = structuredClone({ ...VALID_ACCOUNT, legacy_extra: 'still here' });
+        const pristine = structuredClone(response);
+        // Invalid against the closed component — and left exactly as it was. Removing the extra
+        // is response PRUNING's job, an explicit call with its own policy, never a side effect of
+        // asking whether a payload conforms.
+        expect(validate(response)).toBe(false);
+        expect(response).toEqual(pristine);
+    });
+
+    it('rejects unknown fields only where a component opts in to strict', () => {
+        const components = toOpenApiComponents(
+            { Strict: { type: 'object', properties: { a: { type: 'string' } }, required: ['a'] } },
+            { strictComponents: new Set(['Strict']) },
+        );
+        expect(components.Strict.additionalProperties).toBe(false);
+        const ajv = new Ajv2020({ strictSchema: false });
+        ajv.addSchema({ $id: 'vertesia://openapi', components: { schemas: components } });
+        const validate = ajv.compile({ $ref: 'vertesia://openapi#/components/schemas/Strict' });
+        const payload = { a: 'x', extra: 1 };
+        expect(validate(payload)).toBe(false);
+        expect(payload.extra).toBe(1); // rejected, not stripped
+    });
+});
+
+describe('gate 7 — the adapter is library-neutral', () => {
+    it('hoists typebox-style nested $id subschemas', () => {
+        // TypeBox embeds the schema value (which is what preserves Static<> inference) and marks
+        // it with $id; the adapter lifts it, exactly as it lifts zod's $defs.
+        const components = toOpenApiComponents({
+            Account: {
+                type: 'object',
+                properties: {
+                    billing: { $id: 'AccountBilling', type: 'object', properties: { method: { type: 'string' } } },
+                    history: {
+                        type: 'array',
+                        items: { $id: 'AccountBilling', type: 'object', properties: { method: { type: 'string' } } },
+                    },
+                },
+            },
+        });
+        expect(Object.keys(components).sort()).toEqual(['Account', 'AccountBilling']);
+        const props = components.Account.properties as JsonObject;
+        expect(props.billing).toEqual({ $ref: '#/components/schemas/AccountBilling' });
+        expect((props.history as JsonObject).items).toEqual({ $ref: '#/components/schemas/AccountBilling' });
+    });
+
+    it('rewrites a root self-reference to its component pointer', () => {
+        // zod emits `{"$ref": "#"}` for recursion, which would point at the whole OpenAPI
+        // document once embedded under components.
+        const components = toOpenApiComponents({
+            Node: {
+                type: 'object',
+                properties: { name: { type: 'string' }, children: { type: 'array', items: { $ref: '#' } } },
+            },
+        });
+        const props = components.Node.properties as JsonObject;
+        expect((props.children as JsonObject).items).toEqual({ $ref: '#/components/schemas/Node' });
+    });
+
+    it('does not mutate its input', () => {
+        const input = { A: { type: 'object', properties: { b: { $id: 'B', type: 'string' } } } };
+        const pristine = structuredClone(input);
+        toOpenApiComponents(input);
+        expect(input).toEqual(pristine);
+    });
+
+    it('rejects two different schemas claiming the same component name', () => {
+        expect(() =>
+            toOpenApiComponents({
+                A: { type: 'object', properties: { x: { $id: 'Dup', type: 'string' } } },
+                B: { type: 'object', properties: { y: { $id: 'Dup', type: 'number' } } },
+            }),
+        ).toThrow(SchemaAdapterError);
+    });
+});
+
+describe('gate 8 — runtime enforcement uses the published components', () => {
+    it('rejects a request body that violates the published component, without mutating it', () => {
+        const payload: Record<string, unknown> = { name: 'Acme', rogue_field: 42 };
+        const result = validateApiRequest('UpdateAccountPayload', payload);
+
+        expect(result.valid).toBe(false);
+        if (!result.valid) {
+            expect(result.errors.join(' ')).toContain('additional properties');
+        }
+        // Reported, not deleted: removing it would make the server accept a body its own published
+        // schema calls invalid.
+        expect(payload.rogue_field).toBe(42);
+    });
+
+    it('accepts a conforming request body and hands back the component type', () => {
+        const result = validateApiRequest('UpdateAccountPayload', {
+            name: 'Acme',
+            billing: { method: 'stripe' },
+        });
+
+        expect(result.valid).toBe(true);
+        if (result.valid) {
+            // Typed as the component only on the valid branch, so a body missing required fields
+            // can never be typed as complete.
+            assertType<Equals<typeof result.data, UpdateAccountPayload>>(true);
+            expect(result.data.name).toBe('Acme');
+        }
+    });
+
+    it('no longer accepts quota_tier, which the handler never applied', () => {
+        // Documented-but-ignored is the drift this work removes. The tier is written through the
+        // admin quota API; accepting it here would eventually invite a "fix" that lets an account
+        // admin raise their own rate limits.
+        expect(validateApiRequest('UpdateAccountPayload', { quota_tier: 'enterprise' }).valid).toBe(false);
+        expect(ApiSchemaComponents.UpdateAccountPayload.properties).not.toHaveProperty('quota_tier');
+    });
+
+    it('enforces date-time formats, which AJV ignores without ajv-formats', () => {
+        // Registering the format package is what turns `format: date-time` from documentation into
+        // a check. Without it this payload would pass and the contract would be a suggestion.
+        const invalid = { ...VALID_ACCOUNT, created_at: 'yesterday' };
+        expect(validateApiResponse('Account', invalid).valid).toBe(false);
+        expect(validateApiResponse('Account', VALID_ACCOUNT).valid).toBe(true);
+    });
+
+    it('rejects a native Date where the schema declares a date-time string', () => {
+        // Response validation runs on the object before Koa serializes it, so a mapper that passed
+        // a Mongoose `Date` straight through would produce correct wire bytes and still be wrong
+        // here. That is precisely the bug the mapper's date normalization prevents.
+        const withDate = { ...VALID_ACCOUNT, created_at: new Date('2026-07-29T10:00:00.000Z') };
+        expect(validateApiResponse('Account', withDate).valid).toBe(false);
+    });
+
+    it('honours the Stripe discriminator, which the generated Go client does not', () => {
+        // The one backstop the Go client cannot provide. Its oneOf decoder picks a branch by
+        // required-property presence and never reads `status`, so it happily decodes the first
+        // payload below as the *enabled* branch (see openapi/go/tests). AJV does honour `const`,
+        // which is what lets the server detect its own drift: routing every branch of the handler
+        // through checkResponseContract turns "the server never emits a contradictory payload"
+        // from an assumption into something that shows up in the logs when it stops being true.
+        const enabled = { status: 'enabled', billing_method: 'stripe', portal_url: 'https://x' };
+        const disabled = { status: 'disabled', billing_method: null, reason: 'No billing method' };
+        expect(validateApiResponse('StripeBillingStatusResponse', enabled).valid).toBe(true);
+        expect(validateApiResponse('StripeBillingStatusResponse', disabled).valid).toBe(true);
+
+        // Enabled body, disabled discriminator: matches neither branch.
+        expect(validateApiResponse('StripeBillingStatusResponse', { ...enabled, status: 'disabled' }).valid).toBe(
+            false,
+        );
+        // Both branches' required properties: a real oneOf must match exactly one.
+        expect(validateApiResponse('StripeBillingStatusResponse', { ...enabled, reason: 'nope' }).valid).toBe(false);
+    });
+});

package/src/api-schemas/account.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+// From the values module, never from `user.ts`: `user.ts` derives its public types from the schemas
+// below, so importing it here would invert the dependency and make the source of truth circular.
+import { ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH, AccountType, BillingMethod, QuotaTier } from '../account-values.js';
+
+/**
+ * Runtime API schemas for the Accounts endpoints.
+ *
+ * These describe the WIRE shape — what actually crosses the HTTP boundary — which is not
+ * always what the hand-written interfaces in `user.ts` claim. Divergences are asserted in
+ * `account.contract.test.ts` rather than papered over.
+ *
+ * This module is only reachable through the `@vertesia/common/api-schemas` subpath. It must
+ * never be runtime-exported from the package root: `lib/index.js` is bundled wholesale into
+ * `lib/vertesia-common.js` and served to browsers, so a root re-export would ship zod to every
+ * UI user. The root may re-export the derived TYPES with `export type`, which tsc erases.
+ */
+
+/**
+ * Shared enums carry an `id` so the adapter hoists them into named components and properties
+ * reference them, rather than each property carrying its own inline copy. The distinction is
+ * invisible to JSON Schema validation and decisive for codegen: a named component becomes one
+ * reusable Java/Go enum type, while inline copies become an anonymous type per property. These
+ * names also already exist in the published spec, so keeping them avoids a breaking rename for
+ * everyone generating from it.
+ */
+export const BillingMethodSchema = z.enum(BillingMethod).meta({ id: 'BillingMethod' });
+export const AccountTypeSchema = z.enum(AccountType).meta({ id: 'AccountType' });
+export const QuotaTierSchema = z.enum(QuotaTier).meta({
+    id: 'QuotaTier',
+    description:
+        'Quota/rate-limit tier assigned to an account. Code-defined tiers live in `@dglabs/quota` ' +
+        '(`QUOTA_TIERS`); these names must match its keys.\n' +
+        '- `standard` — protective baseline limits (the default for most accounts).\n' +
+        '- `enterprise` — high limits for contracted customers / internal / partners.\n\n' +
+        'An account with no explicit `quota_tier` derives its tier from its `account_type`.',
+});
+
+export const AccountBillingSchema = z
+    .object({
+        method: BillingMethodSchema,
+        stripe_customer_id: z.string().optional(),
+    })
+    .meta({ id: 'AccountBilling' });
+
+export const AccountSchema = z
+    .object({
+        id: z.string(),
+        name: z.string(),
+        // JSDoc is invisible to `toJSONSchema` — a description only reaches the published spec
+        // through `.meta()`. These strings are the ones the TypeScript-derived spec used to carry.
+        namespace: z
+            .string()
+            .meta({ description: 'Public DNS-label-compatible identifier used by organization app domains.' })
+            .optional(),
+        app_access_message: z
+            .string()
+            .max(ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH)
+            .meta({
+                description: 'Plain-text instructions shown when a signed-in user has no application access.',
+            })
+            .optional(),
+        email_domains: z.array(z.string()),
+        // strictObject rather than object: the previously published spec closed this nested
+        // object, and STRICT_COMPONENTS only reaches top-level components.
+        onboarding: z.strictObject({
+            completed: z.boolean(),
+            /**
+             * String on the wire and optional: the Mongo field has no default and is only written
+             * when onboarding completes.
+             */
+            completed_at: z.string().meta({ format: 'date-time' }).optional(),
+        }),
+        datacenter: z.string(),
+        account_type: AccountTypeSchema,
+        billing: AccountBillingSchema,
+        quota_tier: QuotaTierSchema.meta({
+            description: 'Quota/rate-limit tier. Unset → the deployment default tier (env `QUOTA_BASE_TIER`).',
+        }).optional(),
+        feature_flags: z
+            .record(z.string(), z.unknown())
+            .meta({
+                description:
+                    'Ops-managed per-account feature flags. Untyped by design so operators can add / remove ' +
+                    'temporary rollout gates without a schema change. Keys are enumerated in the admin UI from ' +
+                    'a hardcoded registry (studio-server) — flags not in that registry are ignored. Not ' +
+                    'modifiable through the public account API; admin API only.',
+            })
+            .optional(),
+        created_by: z.string(),
+        updated_by: z.string(),
+        created_at: z.string().meta({ format: 'date-time' }),
+        updated_at: z.string().meta({ format: 'date-time' }),
+    })
+    .meta({ id: 'Account' });
+
+/**
+ * No `quota_tier`. The previously published payload declared it, but `PUT /account` never applied
+ * it — the field is written only through the admin quota API. Documenting a field the handler
+ * ignores is the drift this work exists to remove, and once request validation enforces the
+ * schema, a client sending it gets an honest 400 instead of silence. It also closes the door on a
+ * future "fix" that would let an account admin raise their own rate-limit tier through the public
+ * API.
+ */
+export const UpdateAccountPayloadSchema = z
+    .object({
+        name: z.string().optional(),
+        app_access_message: z.string().max(ACCOUNT_APP_ACCESS_MESSAGE_MAX_LENGTH).optional(),
+        email_domains: z.array(z.string()).optional(),
+        billing: AccountBillingSchema.optional(),
+    })
+    .meta({ id: 'UpdateAccountPayload' });
+
+/**
+ * Stripe billing status, modelled as a real discriminated union.
+ *
+ * The hand-written `StripeBillingStatusResponse` in `meters.ts` flattens this into one object
+ * with `portal_url?` and `reason?` both optional, so a generated Java/Go client gets two
+ * unrelated optionals and no way to know which is populated. The server only ever sets
+ * `portal_url` when enabled and `reason` when disabled.
+ */
+export const StripeBillingEnabledSchema = z
+    .object({
+        status: z.literal('enabled'),
+        /**
+         * Only ever `stripe`. The handler returns the enabled branch exclusively after checking
+         * `account.billing.method === BillingMethod.stripe`, so widening this to the full enum
+         * would describe states the server cannot produce.
+         */
+        billing_method: z.literal(BillingMethod.stripe),
+        portal_url: z.string(),
+    })
+    .meta({ id: 'StripeBillingEnabled' });
+
+export const StripeBillingDisabledSchema = z
+    .object({
+        status: z.literal('disabled'),
+        billing_method: BillingMethodSchema.nullable(),
+        reason: z.string(),
+    })
+    .meta({ id: 'StripeBillingDisabled' });
+
+export const StripeBillingStatusResponseSchema = z
+    .discriminatedUnion('status', [StripeBillingEnabledSchema, StripeBillingDisabledSchema])
+    .meta({ id: 'StripeBillingStatusResponse' });
+
+export type AccountBillingFromSchema = z.infer<typeof AccountBillingSchema>;
+export type AccountFromSchema = z.infer<typeof AccountSchema>;
+export type UpdateAccountPayloadFromSchema = z.infer<typeof UpdateAccountPayloadSchema>;
+export type StripeBillingStatusResponseFromSchema = z.infer<typeof StripeBillingStatusResponseSchema>;