@cosmicdrift/kumiko-testing 0.411.0 → 0.413.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cosmicdrift/kumiko-testing",
3
- "version": "0.411.0",
3
+ "version": "0.413.0",
4
4
  "description": "Test template for Kumiko apps: per-flow seedTenant, app test stack, canonical test preloads, bunfig generator and integration runner.",
5
5
  "license": "MIT",
6
6
  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -26,6 +26,10 @@
26
26
  "types": "./src/stack/index.ts",
27
27
  "default": "./src/stack/index.ts"
28
28
  },
29
+ "./api-examples": {
30
+ "types": "./src/api-examples/index.ts",
31
+ "default": "./src/api-examples/index.ts"
32
+ },
29
33
  "./provider-env-keys": {
30
34
  "types": "./src/provider-env-keys.ts",
31
35
  "default": "./src/provider-env-keys.ts"
@@ -103,9 +107,9 @@
103
107
  "kumiko-testing": "./bin/kumiko-testing.ts"
104
108
  },
105
109
  "dependencies": {
106
- "@cosmicdrift/kumiko-framework": "0.411.0",
107
- "@cosmicdrift/kumiko-guards": "0.411.0",
108
- "@cosmicdrift/kumiko-types": "0.411.0",
110
+ "@cosmicdrift/kumiko-framework": "0.413.0",
111
+ "@cosmicdrift/kumiko-guards": "0.413.0",
112
+ "@cosmicdrift/kumiko-types": "0.413.0",
109
113
  "zod": "^4.6.7"
110
114
  },
111
115
  "peerDependencies": {
@@ -129,8 +133,8 @@
129
133
  }
130
134
  },
131
135
  "devDependencies": {
132
- "@cosmicdrift/kumiko-bundled-features": "0.411.0",
133
- "@cosmicdrift/kumiko-dev-server": "0.411.0",
136
+ "@cosmicdrift/kumiko-bundled-features": "0.413.0",
137
+ "@cosmicdrift/kumiko-dev-server": "0.413.0",
134
138
  "@happy-dom/global-registrator": "^21.0.4",
135
139
  "@playwright/test": "^1.64.1",
136
140
  "@testing-library/dom": "^10.4.2",
@@ -0,0 +1,11 @@
1
+ export { normalizeApiExample, normalizeWebhookExample } from "./normalize.ts";
2
+ export {
3
+ RECORD_API_EXAMPLES_ENV,
4
+ type RecordApiExampleOptions,
5
+ recordApiExample,
6
+ } from "./record.ts";
7
+ export {
8
+ type RecordWebhookExampleOptions,
9
+ recordWebhookExample,
10
+ WEBHOOK_EXAMPLES_SUBDIR,
11
+ } from "./webhook-record.ts";
@@ -0,0 +1,76 @@
1
+ import {
2
+ type ApiExampleFile,
3
+ ApiExampleFileSchema,
4
+ type WebhookExampleFile,
5
+ WebhookExampleFileSchema,
6
+ } from "@cosmicdrift/kumiko-types/api-example";
7
+
8
+ export const EXAMPLE_TIMESTAMP = "2026-01-15T09:30:00.000Z";
9
+ export const EXAMPLE_REQUEST_ID = "11111111-1111-4111-8111-111111111111";
10
+ export const EXAMPLE_CURSOR = "CURSOR";
11
+ export const EXAMPLE_TOKEN = "kpat_EXAMPLE";
12
+ export const EXAMPLE_SECRET = "REDACTED";
13
+
14
+ // Recordings are committed and published, so credentials sent in a payload never reach the file.
15
+ const SECRET_KEY = /password|secret|mfaCode/i;
16
+
17
+ const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
18
+ const ISO_TIMESTAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})/g;
19
+ const PAT_TOKEN = /kpat_[A-Za-z0-9_-]+/g;
20
+
21
+ function placeholderUuid(index: number): string {
22
+ return `00000000-0000-4000-8000-${String(index).padStart(12, "0")}`;
23
+ }
24
+
25
+ function isRecord(value: unknown): value is Record<string, unknown> {
26
+ return typeof value === "object" && value !== null && !Array.isArray(value);
27
+ }
28
+
29
+ /** One walker per recording: UUIDs are numbered by first occurrence across everything it walks. */
30
+ function createExampleWalker(): (value: unknown) => unknown {
31
+ const uuids = new Map<string, string>();
32
+ const normalizeString = (text: string): string =>
33
+ text
34
+ .replace(PAT_TOKEN, EXAMPLE_TOKEN)
35
+ .replace(UUID, (found) => {
36
+ const key = found.toLowerCase();
37
+ const known = uuids.get(key);
38
+ if (known !== undefined) return known;
39
+ const created = placeholderUuid(uuids.size + 1);
40
+ uuids.set(key, created);
41
+ return created;
42
+ })
43
+ .replace(ISO_TIMESTAMP, EXAMPLE_TIMESTAMP);
44
+
45
+ const walk = (value: unknown): unknown => {
46
+ if (typeof value === "string") return normalizeString(value);
47
+ if (Array.isArray(value)) return value.map(walk);
48
+ if (!isRecord(value)) return value;
49
+ return Object.fromEntries(
50
+ Object.entries(value).map(([key, entry]): [string, unknown] => {
51
+ if (SECRET_KEY.test(key) && typeof entry === "string") return [key, EXAMPLE_SECRET];
52
+ if (key === "requestId") return [key, EXAMPLE_REQUEST_ID];
53
+ if (key === "timestamp") return [key, EXAMPLE_TIMESTAMP];
54
+ if (key === "nextCursor" && entry !== null && entry !== undefined) {
55
+ return [key, EXAMPLE_CURSOR];
56
+ }
57
+ return [key, walk(entry)];
58
+ }),
59
+ );
60
+ };
61
+ return walk;
62
+ }
63
+
64
+ /** Makes a recording stable across runs: the same input shape always yields the same file. */
65
+ export function normalizeApiExample(example: ApiExampleFile): ApiExampleFile {
66
+ // Numbered by first occurrence, request before response; the same UUID keeps its number.
67
+ const walk = createExampleWalker();
68
+ const request = walk(example.request);
69
+ const response = walk(example.response);
70
+ return ApiExampleFileSchema.parse({ request, response });
71
+ }
72
+
73
+ export function normalizeWebhookExample(example: WebhookExampleFile): WebhookExampleFile {
74
+ const walk = createExampleWalker();
75
+ return WebhookExampleFileSchema.parse({ ...example, payload: walk(example.payload) });
76
+ }
@@ -0,0 +1,40 @@
1
+ import { join } from "node:path";
2
+ import type { ApiExampleEndpoint, ApiExampleFile } from "@cosmicdrift/kumiko-types/api-example";
3
+ import type { RequestHelper } from "../stack/request-helper.ts";
4
+ import { normalizeApiExample } from "./normalize.ts";
5
+
6
+ export const RECORD_API_EXAMPLES_ENV = "KUMIKO_RECORD_API_EXAMPLES";
7
+
8
+ export type RecordApiExampleOptions = {
9
+ /** File name without extension. */
10
+ readonly name: string;
11
+ readonly dir: string;
12
+ readonly endpoint: ApiExampleEndpoint;
13
+ readonly body: ApiExampleFile["request"]["body"];
14
+ /** Raw personal access token; sent as bearer token and never written to the file. */
15
+ readonly token: string;
16
+ };
17
+
18
+ /** Sends the request as an API client would and returns the result. The recording is only
19
+ * written when KUMIKO_RECORD_API_EXAMPLES=1, so ordinary test runs leave the files alone. */
20
+ export async function recordApiExample(
21
+ http: Pick<RequestHelper, "raw">,
22
+ options: RecordApiExampleOptions,
23
+ ): Promise<{ readonly status: number; readonly body: unknown }> {
24
+ const response = await http.raw("POST", options.endpoint, options.body, {
25
+ Authorization: `Bearer ${options.token}`,
26
+ });
27
+ const body: unknown = await response.json();
28
+ const result = { status: response.status, body };
29
+ if (process.env[RECORD_API_EXAMPLES_ENV] === "1") {
30
+ const file = normalizeApiExample({
31
+ request: { endpoint: options.endpoint, body: options.body },
32
+ response: result,
33
+ });
34
+ await Bun.write(
35
+ join(options.dir, `${options.name}.json`),
36
+ `${JSON.stringify(file, null, 2)}\n`,
37
+ );
38
+ }
39
+ return result;
40
+ }
@@ -0,0 +1,45 @@
1
+ import { join } from "node:path";
2
+ import {
3
+ formatWebhookPayloadIssues,
4
+ parseWebhookPayload,
5
+ } from "@cosmicdrift/kumiko-framework/engine";
6
+ import type { WebhookEventContract } from "@cosmicdrift/kumiko-types/feature";
7
+ import { normalizeWebhookExample } from "./normalize.ts";
8
+ import { RECORD_API_EXAMPLES_ENV } from "./record.ts";
9
+
10
+ export const WEBHOOK_EXAMPLES_SUBDIR = "webhooks";
11
+
12
+ export type RecordWebhookExampleOptions = {
13
+ /** File name without extension. */
14
+ readonly name: string;
15
+ /** The examples directory; the file lands in its `webhooks/` subdirectory. */
16
+ readonly dir: string;
17
+ readonly contract: WebhookEventContract;
18
+ readonly payload: unknown;
19
+ };
20
+
21
+ /** Checks the payload against its contract and returns what delivery would send. A recording
22
+ * can therefore never contradict the contract; the file is only written when
23
+ * KUMIKO_RECORD_API_EXAMPLES=1. */
24
+ export async function recordWebhookExample(
25
+ options: RecordWebhookExampleOptions,
26
+ ): Promise<Record<string, unknown>> {
27
+ const parsed = parseWebhookPayload(options.contract, options.payload);
28
+ if (!parsed.ok) {
29
+ throw new Error(
30
+ `Webhook example "${options.name}" violates the contract of ${options.contract.qn}: ${formatWebhookPayloadIssues(parsed.issues)}`,
31
+ );
32
+ }
33
+ if (process.env[RECORD_API_EXAMPLES_ENV] === "1") {
34
+ const file = normalizeWebhookExample({
35
+ event: options.contract.qn,
36
+ version: options.contract.version,
37
+ payload: parsed.payload,
38
+ });
39
+ await Bun.write(
40
+ join(options.dir, WEBHOOK_EXAMPLES_SUBDIR, `${options.name}.json`),
41
+ `${JSON.stringify(file, null, 2)}\n`,
42
+ );
43
+ }
44
+ return parsed.payload;
45
+ }
package/src/changes.json CHANGED
@@ -1,4 +1,16 @@
1
1
  [
2
+ {
3
+ "version": "0.412.0",
4
+ "type": "improvement",
5
+ "title": "recordApiExample records real API responses for the generated docs",
6
+ "detail": "`recordApiExample(http, { name, dir, endpoint, body, token })` from `@cosmicdrift/kumiko-testing/api-examples` sends the request with the token as Bearer and returns status and body. With `KUMIKO_RECORD_API_EXAMPLES=1` it also writes `<dir>/<name>.json` with ids, timestamps, tokens, request ids and cursors replaced by stable placeholders and values under password, secret and mfaCode keys redacted. `kumiko api-docs` uses a recording for the example request and the example response of the matching handler. The recipe `samples/recipes/api-docs` shows the whole flow."
7
+ },
8
+ {
9
+ "version": "0.412.0",
10
+ "type": "improvement",
11
+ "title": "recordWebhookExample records validated webhook payloads for the generated docs",
12
+ "detail": "`recordWebhookExample({ name, dir, contract, payload })` from `@cosmicdrift/kumiko-testing/api-examples` validates the payload with `parseWebhookPayload` and throws with the issues when it breaks the contract. With `KUMIKO_RECORD_API_EXAMPLES=1` it writes `<dir>/webhooks/<name>.json` with ids, timestamps and secrets normalized. It always returns the parsed payload. `WebhookExampleFileSchema` is exported from `@cosmicdrift/kumiko-types/api-example`."
13
+ },
2
14
  {
3
15
  "version": "0.411.0",
4
16
  "type": "improvement",