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

package/src/api-schemas/bulk-operation.contract.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import type { BulkOperationPayload, BulkOperationResponse } from '../common.js';
+import type { BulkOperationPayloadSchema, BulkOperationResponseSchema } from './bulk-operation.js';
+import { validateApiRequest, validateApiResponse } from './registry.js';
+
+type Equals<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+function assertType<T extends true>(_value: T): void {}
+
+describe('bulk-operation API contract', () => {
+    it('derives the public request and response types from the schemas', () => {
+        assertType<Equals<BulkOperationPayload, typeof BulkOperationPayloadSchema._output>>(true);
+        assertType<Equals<BulkOperationResponse, typeof BulkOperationResponseSchema._output>>(true);
+    });
+
+    it('validates the exact published request component', () => {
+        const valid = { name: 'change_type', ids: ['object-1'], params: { type: 'invoice' } };
+        expect(validateApiRequest('BulkOperationPayload', valid).valid).toBe(true);
+        expect(validateApiRequest('BulkOperationPayload', { ...valid, extra: true }).valid).toBe(false);
+    });
+
+    it('enforces the response branch selected by operation', () => {
+        expect(
+            validateApiResponse('BulkOperationResponse', {
+                operation: 'delete',
+                status: 'completed',
+                deleted: 2,
+                failed: [],
+            }).valid,
+        ).toBe(true);
+        expect(
+            validateApiResponse('BulkOperationResponse', {
+                operation: 'delete',
+                status: 'completed',
+                updated: 2,
+                failed: [],
+            }).valid,
+        ).toBe(false);
+    });
+});

package/src/api-schemas/bulk-operation.ts

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+
+export const BulkObjectDeleteResultSchema = z
+    .strictObject({
+        operation: z.literal('delete'),
+        status: z.enum(['in_progress', 'completed', 'failed']),
+        deleted: z.number().meta({ description: 'Number of documents deleted (including revisions)' }),
+        failed: z
+            .array(z.string())
+            .meta({ description: 'IDs that were not found or user had no permission to delete' }),
+    })
+    .meta({ id: 'BulkObjectDeleteResult' });
+
+export const BulkObjectUpdateResultSchema = z
+    .strictObject({
+        operation: z.literal('update'),
+        status: z.enum(['in_progress', 'completed', 'failed']),
+        updated: z.number().meta({ description: 'Number of documents successfully updated' }),
+        failed: z
+            .array(z.string())
+            .meta({ description: 'IDs that were not found, not authorized, or failed to update' }),
+    })
+    .meta({ id: 'BulkObjectUpdateResult' });
+
+export const BulkObjectCreateResultSchema = z
+    .strictObject({
+        operation: z.literal('create'),
+        status: z.enum(['in_progress', 'completed', 'failed']),
+        created: z.number().meta({ description: 'Number of documents successfully created' }),
+        objects: z
+            .array(
+                z.strictObject({
+                    id: z.string(),
+                    index: z.number().optional(),
+                    external_id: z.string().optional(),
+                }),
+            )
+            .meta({ description: 'Successfully created objects with their IDs' }),
+        failed: z
+            .array(
+                z.strictObject({
+                    external_id: z.string().optional(),
+                    index: z.number(),
+                    error: z.string(),
+                }),
+            )
+            .meta({ description: 'Objects that failed to create' }),
+    })
+    .meta({ id: 'BulkObjectCreateResult' });
+
+export const BulkOperationResultSchema = z
+    .strictObject({
+        operation: z.literal('generic'),
+        status: z.enum(['in_progress', 'completed', 'failed']),
+    })
+    .meta({ id: 'BulkOperationResult' });
+
+export const BulkOperationPayloadSchema = z
+    .strictObject({
+        name: z
+            .enum(['change_type', 'create', 'delete', 'start_workflow', 'update'])
+            .meta({ description: 'The operation name' }),
+        ids: z.array(z.string()).meta({ description: 'The IDs of the objects to operate on' }),
+        params: z.looseObject({}).meta({ description: 'The operation parameters.' }),
+    })
+    .meta({ id: 'BulkOperationPayload' });
+
+export const BulkOperationResponseSchema = z
+    .discriminatedUnion('operation', [
+        BulkOperationResultSchema,
+        BulkObjectCreateResultSchema,
+        BulkObjectUpdateResultSchema,
+        BulkObjectDeleteResultSchema,
+    ])
+    .meta({ id: 'BulkOperationResponse' });

package/src/api-schemas/bundle-isolation.test.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { gzipSync } from 'node:zlib';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Guards the packaging boundary that keeps schema-authoring runtime code out of ordinary
+ * `@vertesia/common` and `@vertesia/client` consumers.
+ *
+ * `lib/index.js` is bundled wholesale into `lib/vertesia-common.js` by rolldown, and
+ * `apps/composable-ui/build/shared-libs.ts` serves that single file to the browser mapped to the
+ * bare specifier `@vertesia/common`. There is no per-consumer tree-shaking anywhere on that path,
+ * so `import type` erasure in app code cannot save us: anything runtime-reachable from the root
+ * barrel ships to every UI user.
+ *
+ * The rule this enforces: the root may re-export schema-derived TYPES (`export type`, erased by
+ * tsc) but must never runtime-export `./api-schemas/*`. `@vertesia/client` is covered too — it is
+ * shipped to the browser by the same mechanism, so a schema import there leaks just as badly. Its
+ * default and Node.js entries are checked independently because this is also an SDK dependency
+ * boundary for Node.js, serverless, CLI, and other JavaScript applications—not only a browser-size
+ * concern.
+ *
+ * Runs against build output, so each artifact is skipped when it has not been built.
+ */
+const path = (relative: string) => new URL(relative, import.meta.url).pathname;
+
+const COMMON_BUNDLE = path('../../lib/vertesia-common.js');
+const COMMON_ENTRY = path('../../lib/index.js');
+const CLIENT_BUNDLE = path('../../../client/lib/vertesia-client.js');
+/** `.` and `./node` in the client's exports map — the latter is `lib/nodejs/index.js`, not `lib/index.js`. */
+const CLIENT_ENTRIES = [
+    { label: 'client default entry (.)', file: path('../../../client/lib/index.js') },
+    { label: 'client node entry (./node)', file: path('../../../client/lib/nodejs/index.js') },
+];
+
+/** Markers that prove a runtime schema import leaked into a browser artifact. */
+const FORBIDDEN = ['zod', '_zod', 'ZodObject', 'api-schemas', 'toOpenApiComponents', 'ApiSchemaComponents'];
+
+/** Headroom over the current ~34 KB gzip; pulling zod in would add roughly 60 KB. */
+const MAX_COMMON_GZIP_BYTES = 45 * 1024;
+
+function expectNoSchemaRuntime(file: string, label: string): void {
+    const contents = readFileSync(file, 'utf8');
+    for (const marker of FORBIDDEN) {
+        expect(contents, `${label} must not contain '${marker}'`).not.toContain(marker);
+    }
+}
+
+describe.skipIf(!existsSync(COMMON_BUNDLE))('@vertesia/common runtime schema isolation', () => {
+    it('does not runtime-reference the api-schemas subpath from the root entry', () => {
+        expect(readFileSync(COMMON_ENTRY, 'utf8')).not.toContain('api-schemas');
+    });
+
+    it('contains no zod import or implementation code', () => {
+        expectNoSchemaRuntime(COMMON_BUNDLE, 'common browser bundle');
+    });
+
+    it('stays within its gzip budget', () => {
+        const gzipped = gzipSync(readFileSync(COMMON_BUNDLE)).byteLength;
+        expect(
+            gzipped,
+            `common browser bundle grew to ${(gzipped / 1024).toFixed(1)} KB gzip — check whether a ` +
+                'runtime schema export leaked into the root barrel',
+        ).toBeLessThan(MAX_COMMON_GZIP_BYTES);
+    });
+});
+
+describe.skipIf(!existsSync(CLIENT_BUNDLE))('@vertesia/client consumer runtime isolation', () => {
+    it('contains no zod import or schema registry code', () => {
+        // The client is served to the browser the same way common is, so importing
+        // `@vertesia/common/api-schemas` from an SDK method would ship zod to every UI user.
+        expectNoSchemaRuntime(CLIENT_BUNDLE, 'client browser bundle');
+    });
+
+    it.each(CLIENT_ENTRIES)('does not reference the api-schemas subpath from the $label', ({ label, file }) => {
+        // Asserted rather than skipped: a missing artifact means the entry moved or stopped being
+        // built, and silently passing would let a packaging regression through unnoticed.
+        expect(existsSync(file), `${label} not found at ${file} — has the exports map changed?`).toBe(true);
+        expect(readFileSync(file, 'utf8'), `${label} must not import api-schemas`).not.toContain('api-schemas');
+    });
+});

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

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { validateApiRequest, validateApiResponse } from './registry.js';
+
+/**
+ * The migration-command contracts, pinned where converting them changed what the document says.
+ *
+ * Both changes are widenings — every request and response that was valid before is still valid — but
+ * both are visible in the generated clients, so each one is asserted here rather than described in a
+ * commit message.
+ */
+describe('RunMigrationPayload', () => {
+    it('accepts the params object migrations are actually invoked with', () => {
+        // The shape from `migrate-agent-runs`' own usage comment. The published component declared
+        // only `force`, so enforcing it closed would have rejected this.
+        expect(
+            validateApiRequest('RunMigrationPayload', {
+                force: true,
+                params: { tenantId: 'abc123_def456', since: '2025-01-01' },
+            }),
+        ).toMatchObject({ valid: true });
+    });
+
+    it('still accepts the bare force body, and an empty one', () => {
+        expect(validateApiRequest('RunMigrationPayload', { force: true }).valid).toBe(true);
+        expect(validateApiRequest('RunMigrationPayload', {}).valid).toBe(true);
+    });
+
+    it('rejects an undeclared sibling of params, so the body stays closed', () => {
+        // `params` is freeform INSIDE; that is not the same as the body being open. A typo like
+        // `parms` has to fail rather than be silently dropped on the floor by the migration.
+        const result = validateApiRequest('RunMigrationPayload', { parms: { tenantId: 'x' } });
+        expect(result.valid).toBe(false);
+        expect(result.valid === false && result.errors.join('; ')).toContain('additional properties');
+    });
+});
+
+describe('MigrationListResponse', () => {
+    it('validates the shape the handler returns', () => {
+        expect(
+            validateApiResponse('MigrationListResponse', { migrations: [{ name: 'migrate-agent-runs' }] }),
+        ).toMatchObject({ valid: true });
+    });
+
+    it('rejects a response that is no longer the listing', () => {
+        // The point of giving the component a body: as `z.unknown()` every one of these passed, so
+        // the endpoint was wired to the enforcer while validating nothing at all.
+        expect(validateApiResponse('MigrationListResponse', { migrations: ['a'] }).valid).toBe(false);
+        expect(validateApiResponse('MigrationListResponse', { migration: [] }).valid).toBe(false);
+        expect(validateApiResponse('MigrationListResponse', ['migrate-agent-runs']).valid).toBe(false);
+    });
+});

package/src/api-schemas/commands.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+
+export const GenericCommandResponseSchema = z
+    .strictObject({
+        status: z.string(),
+        message: z.string(),
+        err: z.unknown().optional(),
+        details: z.unknown().optional(),
+    })
+    .meta({ id: 'GenericCommandResponse' });
+
+export const RunMigrationResponseSchema = z
+    .strictObject({
+        status: z.string(),
+    })
+    .meta({ id: 'RunMigrationResponse' });
+
+/**
+ * The migration-command body, including the `params` the published component omitted.
+ *
+ * `force` was all the document ever declared, and while nothing enforced the closed component that
+ * was merely incomplete rather than wrong: `MigrationTool.migrate()` reads `payload.params` off the
+ * same body and hands it to `doMigrate()`, which is how `migrate-agent-runs` receives its `tenantId`
+ * and `since`. Publishing only `force` on a closed component and then enforcing it would have made
+ * the endpoint reject the invocation documented in the migration's own header comment.
+ *
+ * `params` is freeform because it genuinely is: `MigrationTool<P>` is generic and each migration
+ * names its own parameter type, so there is no single shape to publish. The alternative — one
+ * component per migration — would put the operator endpoint's registry entries in step with a list
+ * that changes every time someone adds a backfill.
+ */
+export const RunMigrationPayloadSchema = z
+    .strictObject({
+        force: z.boolean().optional(),
+        params: z.looseObject({}).optional(),
+    })
+    .meta({ id: 'RunMigrationPayload' });
+
+/**
+ * The migration listing, given the shape the handler has always returned.
+ *
+ * The converted component was `z.unknown()`, faithfully reproducing what the document published —
+ * the endpoint declared a response component and never described it, so the middleware validated
+ * every response against "anything". Nothing about that was a conversion artifact worth preserving:
+ * the handler returns `{ migrations: [{ name }] }` and has since it was written.
+ *
+ * Widening a published `{}` to a real object is a contract ADDITION rather than a restriction —
+ * every response that validated before still validates — but it is visible in the generated clients,
+ * which gain a model where they had a bare object. See operation 27 of the 1.5 runbook.
+ */
+export const MigrationListResponseSchema = z
+    .strictObject({
+        migrations: z.array(z.strictObject({ name: z.string() })),
+    })
+    .meta({ id: 'MigrationListResponse' });
+
+export const DeleteCountResultSchema = z
+    .strictObject({
+        id: z.string(),
+        count: z.number(),
+    })
+    .meta({ id: 'DeleteCountResult' });