feat: generate TWILIO_MESSAGE from Twilio OpenAPI spec

Replace the hand-written TWILIO_MESSAGE zod schema with one generated from
Twilio's official OpenAPI specification (twilio/twilio-oai,
spec/json/twilio_api_v2010.json), mirroring the woocommerce-action and
shopware-action generation pipeline.

- scripts/filterTwilioSpec.mjs reduces the large v2010 spec to the
  api.v2010.account.message component, re-exposed as `TwilioMessage`
- scripts/patchGeneratedSchemas.mjs applies the zod v3 -> v4 z.record fix
- package.json: add openapi-zod-client and a generate:twilio-schemas script
- twilioMessage.ts now uses schemas.TwilioMessage from the generated file

NOTE: run `npm install && npm run generate:twilio-schemas` to produce and
commit src/generated/twilio-schemas.ts; the action does not build until that
generated file exists.

Refs #33

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Hrvb3LRhmxcrASCuSXc7Jn

Author: claude

actions/twilio-action/package.json

@@ -7,6 +7,7 @@
   "scripts": {
     "dev": "tsx watch src/index.ts",
     "typecheck": "tsc --noEmit",
+    "generate:twilio-schemas": "curl -fsSL --create-dirs -o schemas/twilio-api-v2010-openapi.json https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/json/twilio_api_v2010.json && node scripts/filterTwilioSpec.mjs && mkdir -p src/generated && openapi-zod-client schemas/twilio-api-v2010-openapi.filtered.json -o src/generated/twilio-schemas.ts -t node_modules/openapi-zod-client/src/templates/schemas-only.hbs --export-schemas && node scripts/patchGeneratedSchemas.mjs",
     "build": "vite build",
     "test": "vitest run",
     "start": "node dist/index.js"
@@ -17,6 +18,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "openapi-zod-client": "^1.18.3",
     "tsx": "^4.0.0",
     "typescript": "^5.9.3",
     "vite": "^8.0.3",

actions/twilio-action/scripts/filterTwilioSpec.mjs

@@ -0,0 +1,61 @@
+// Twilio's api v2010 spec (twilio_api_v2010.json) defines the entire 2010 API
+// and is large and heavily cross-referenced. Only the Message resource schema
+// is needed for the TWILIO_MESSAGE data type, so this script reduces the
+// downloaded spec before code generation, mirroring filterShopwareSpec.mjs in
+// shopware-action:
+//   - keeps `api.v2010.account.message`, re-exposed under the stable name
+//     `TwilioMessage` so the generated schema has a predictable identifier
+//     regardless of how openapi-zod-client would sanitize the dotted name
+//   - replaces $refs to any other component with a permissive untyped object,
+//     cutting the rest of the graph
+// Runs as part of "generate:twilio-schemas" right after the download.
+import {readFileSync, writeFileSync} from "node:fs";
+
+const SOURCE_NAME = "api.v2010.account.message";
+const TARGET_NAME = "TwilioMessage";
+
+const input = new URL("../schemas/twilio-api-v2010-openapi.json", import.meta.url);
+const output = new URL("../schemas/twilio-api-v2010-openapi.filtered.json", import.meta.url);
+
+const spec = JSON.parse(readFileSync(input, "utf8"));
+const allSchemas = spec.components?.schemas ?? {};
+
+if (!(SOURCE_NAME in allSchemas)) {
+    throw new Error(`Schema "${SOURCE_NAME}" not found in ${input}`);
+}
+
+// Rewrite $refs: self-references point at the renamed schema, every other
+// component reference is stubbed out as an untyped object.
+const rewriteRefs = (node) => {
+    if (Array.isArray(node)) {
+        return node.map(rewriteRefs);
+    }
+    if (node !== null && typeof node === "object") {
+        const ref = node.$ref;
+        if (typeof ref === "string") {
+            const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+            if (match) {
+                if (match[1] === SOURCE_NAME) {
+                    return {$ref: `#/components/schemas/${TARGET_NAME}`};
+                }
+                return {type: "object", additionalProperties: true};
+            }
+        }
+        return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, rewriteRefs(value)]));
+    }
+    return node;
+};
+
+const filtered = {
+    openapi: spec.openapi,
+    info: spec.info,
+    paths: {},
+    components: {
+        schemas: {
+            [TARGET_NAME]: rewriteRefs(allSchemas[SOURCE_NAME]),
+        },
+    },
+};
+
+writeFileSync(output, JSON.stringify(filtered, null, 2));
+console.log(`Kept "${SOURCE_NAME}" as "${TARGET_NAME}" (of ${Object.keys(allSchemas).length} schemas)`);

actions/twilio-action/scripts/patchGeneratedSchemas.mjs

@@ -0,0 +1,10 @@
+// openapi-zod-client emits zod v3 code, but this project uses zod v4,
+// where z.record() requires an explicit key schema. Rewrites the
+// generated single-argument form z.record(Value) to
+// z.record(z.string(), Value). Runs as part of
+// "generate:twilio-schemas" right after code generation.
+import {readFileSync, writeFileSync} from "node:fs";
+
+const file = new URL("../src/generated/twilio-schemas.ts", import.meta.url);
+const source = readFileSync(file, "utf8");
+writeFileSync(file, source.replaceAll("z.record(", "z.record(z.string(), "));

actions/twilio-action/src/data_types/twilioMessage.ts

@@ -1,43 +1,15 @@
 import { DisplayMessage, Identifier, Name, Schema } from "@code0-tech/hercules";
 import { z } from "zod";
+import { schemas } from "../generated/twilio-schemas.js";
 
 /**
- * Represents a Twilio Message resource as returned by the Messages API.
- * See https://www.twilio.com/docs/messaging/api/message-resource
+ * TWILIO_MESSAGE is generated from Twilio's official OpenAPI spec
+ * (twilio/twilio-oai, spec/json/twilio_api_v2010.json). The spec is filtered
+ * down to the `api.v2010.account.message` component and re-exposed as
+ * `TwilioMessage` (see scripts/filterTwilioSpec.mjs), then converted to a zod
+ * schema by openapi-zod-client. Regenerate with `npm run generate:twilio-schemas`.
  */
-export const TwilioMessageSchema = z.object({
-    sid: z.string().describe("The unique string that identifies the message resource."),
-    account_sid: z.string().describe("The SID of the Account that created the message resource."),
-    messaging_service_sid: z
-        .string()
-        .nullish()
-        .describe("The SID of the Messaging Service used, if the message was sent through one."),
-    from: z
-        .string()
-        .nullish()
-        .describe("The sender's phone number, short code, or channel address (e.g. whatsapp:+1...)."),
-    to: z.string().describe("The recipient's phone number, short code, or channel address."),
-    body: z.string().nullish().describe("The text body of the message. Up to 1600 characters long."),
-    status: z
-        .string()
-        .describe(
-            "The status of the message. Common values: accepted, scheduled, queued, sending, sent, receiving, received, delivered, undelivered, failed, read, canceled."
-        ),
-    direction: z
-        .string()
-        .describe("The direction of the message: inbound, outbound-api, outbound-call, or outbound-reply."),
-    num_segments: z.string().nullish().describe("The number of segments that make up the complete message."),
-    num_media: z.string().nullish().describe("The number of media files associated with the message."),
-    price: z.string().nullish().describe("The amount billed for the message, in the currency specified by price_unit."),
-    price_unit: z.string().nullish().describe("The currency in which price is measured, in ISO 4127 format (e.g. USD)."),
-    error_code: z.number().nullish().describe("The error code returned if the message status is failed or undelivered."),
-    error_message: z.string().nullish().describe("A human-readable description of the error_code, if any."),
-    date_created: z.string().nullish().describe("The date and time the message was created, in RFC 2822 format."),
-    date_updated: z.string().nullish().describe("The date and time the message was last updated, in RFC 2822 format."),
-    date_sent: z.string().nullish().describe("The date and time the message was sent, in RFC 2822 format."),
-    api_version: z.string().nullish().describe("The version of the Twilio API used to process the message."),
-    uri: z.string().nullish().describe("The URI of the message resource, relative to https://api.twilio.com."),
-});
+export const TwilioMessageSchema = schemas.TwilioMessage;
 export type TwilioMessage = z.infer<typeof TwilioMessageSchema>;
 
 @Identifier("TWILIO_MESSAGE")