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

package/lib/api-schemas/account.js

@@ -0,0 +1,136 @@
+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' });
+//# sourceMappingURL=account.js.map

package/lib/api-schemas/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../../src/api-schemas/account.ts"],"names":[],"mappings":"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"}

package/lib/api-schemas/adapter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Library-neutral JSON Schema -> OpenAPI 3.1 `components.schemas` adapter.
+ *
+ * Input is plain JSON Schema, so this works for any authoring library. It normalizes the three
+ * ways a schema library expresses a named reference into the one form OpenAPI needs:
+ *
+ * - zod       `$defs` + `{"$ref": "#/$defs/X"}`   (and `{"$ref": "#"}` for self-recursion)
+ * - typebox   a nested subschema carrying `$id`   (hoisted here, per the same contract)
+ * - either    a bare `{"$ref": "X"}` id pointer
+ *
+ * All three become `{"$ref": "#/components/schemas/X"}` with the target hoisted into components,
+ * so the pointer that is published is byte-identical to the pointer AJV compiles. That identity
+ * is the whole point: the spec cannot drift from the enforced contract because they are the same
+ * object.
+ *
+ * The input is never mutated.
+ */
+export type JsonObject = Record<string, unknown>;
+/** How a component treats properties it does not declare. */
+export type AdditionalPropertiesPolicy = 'open' | 'closed';
+export interface AdapterOptions {
+    /**
+     * Components that reject undeclared properties. Everything else is left open — omitting the
+     * keyword entirely, so extras are accepted and RETAINED. Existing endpoints must stay open:
+     * they currently cast the payload without validating, so rejecting extras would be a breaking
+     * API change. Only new endpoints should opt in to 'closed'.
+     */
+    strictComponents?: ReadonlySet<string>;
+    /**
+     * Already-published components that roots may reference without redefining. They participate in
+     * reference resolution and discriminator synthesis, but are not copied into the returned map or
+     * subjected to this adaptation pass.
+     */
+    referenceComponents?: Readonly<Record<string, JsonObject>>;
+}
+export declare class SchemaAdapterError extends Error {
+}
+/**
+ * Converts a map of named JSON Schemas into OpenAPI `components.schemas`.
+ *
+ * @param roots  component name -> plain JSON Schema
+ */
+export declare function toOpenApiComponents(roots: Readonly<Record<string, unknown>>, options?: AdapterOptions): Record<string, JsonObject>;
+/**
+ * {@link resolveChain} for callers that only need to know whether resolution succeeded.
+ *
+ * Exported so parameter normalization follows the same reference semantics as pruning rather than
+ * carrying a second, subtly different resolver. A query parameter typed by a hoisted enum is reached
+ * through exactly the chain walked here, so what the normalizer coerces towards and what the spec
+ * publishes are read off the same node.
+ */
+export declare function resolveSchemaRef(schema: JsonObject, components: Readonly<Record<string, JsonObject>>): JsonObject | undefined;
+/**
+ * Reports the paths within a component where {@link pruneToSchema} cannot narrow. Values at those
+ * paths pass through untouched, extras included.
+ *
+ * An empty report means every path is structurally prunable FOR SCHEMA-CONFORMING INPUT. It is not
+ * a guarantee about arbitrary payloads: a discriminated union whose discriminator carries a value
+ * with no mapping entry still passes through, because no branch describes it. Treat an empty
+ * report as "no structural gaps", not as "nothing can escape".
+ */
+export declare function findUnprunablePaths(schema: JsonObject, components: Readonly<Record<string, JsonObject>>): string[];
+/**
+ * Best-effort narrowing of a response payload to the properties its published schema declares.
+ *
+ * NOT A SECURITY BOUNDARY. Where the schema is ambiguous — an `allOf` intersection, a union with
+ * no discriminator, a discriminator value with no mapping entry, or an unresolvable `$ref` — the
+ * value passes through UNTOUCHED, extras included. Losing data is worse than guessing, so the
+ * pruner declines rather than improvises. Anything that must never reach a client (secrets,
+ * internal identifiers) still needs an explicit response mapper or a request/response type split;
+ * this must not be relied on to remove it. {@link findUnprunablePaths} reports where a given
+ * component falls into those gaps.
+ *
+ * Responses are pruned rather than rejected: a document carrying an undocumented field is the
+ * server's problem, not the caller's, and failing would turn drift into a 500.
+ *
+ * The input is never mutated.
+ */
+export declare function pruneToSchema(value: unknown, schema: JsonObject, components: Readonly<Record<string, JsonObject>>): unknown;
+//# sourceMappingURL=adapter.d.ts.map

package/lib/api-schemas/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/api-schemas/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,6DAA6D;AAC7D,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC3B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;CAC9D;AAED,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAkQhD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAC/B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,OAAO,GAAE,cAAmB,GAC7B,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAoD5B;AAqND;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC5B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GACjD,UAAU,GAAG,SAAS,CAGxB;AA+CD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAAG,MAAM,EAAE,CAmDlH;AAoBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CACzB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GACjD,OAAO,CA8CT"}