@faable/deploy-sdk 2.0.0 → 2.2.0

package/scripts/gen-client.mjs

@@ -0,0 +1,241 @@
+// Generates `src/api/generated-client.ts` + `src/api/api-types.ts` from the
+// OpenAPI spec. Ported from auth-sdk's generator (kept in sync by hand).
+//
+// Why: the SDK's typed methods (appGet, deploymentList, …) used to be
+// hand-written and always lagged the API. The TYPES are already generated by
+// openapi-typescript; this does the same for the METHODS, so the SDK covers the
+// whole deploy API for free and stays in sync on every build.
+//
+// Scope: every secured operation (all of them carry the same
+// apikey/faable_cli/faable_machine/faable_user scheme), MINUS internal
+// resources in EXCLUDE_RESOURCES and the unsecured github/webhook/oidc
+// endpoints. Reads the spec from a LOCAL file (downloaded by fetch-spec.mjs) so
+// types.ts and this client are generated from the exact same snapshot.
+//
+// Run via `npm run gentypes`. Output is committed and reviewed in diff like
+// `types.ts`. Do not edit the output by hand.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = resolve(__dirname, "..");
+
+const SPEC = process.env.DEPLOY_OPENAPI || resolve(ROOT, "spec/openapi.json");
+const OUT = resolve(ROOT, "src/api/generated-client.ts");
+const OUT_TYPES = resolve(ROOT, "src/api/api-types.ts");
+
+const spec = JSON.parse(readFileSync(SPEC, "utf8"));
+
+// operationId (`resource/action`, possibly snake/kebab in the action) →
+// camelCase. `app/list`→appList, `app/get_deploy_workflow`→appGetDeployWorkflow,
+// `secrets/list_app`→secretsListApp.
+const toMethodName = (operationId) =>
+  operationId
+    .split(/[/_-]/)
+    .filter(Boolean)
+    .map((seg, i) =>
+      i === 0
+        ? seg[0].toLowerCase() + seg.slice(1)
+        : seg[0].toUpperCase() + seg.slice(1),
+    )
+    .join("");
+
+// `/app/{id}/traffic` → ["id"], in order of appearance.
+const pathParamNames = (path) =>
+  [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+
+// `/app/{id}` → "/app/${id}" (template-literal body).
+const toUrlTemplate = (path) =>
+  path.replace(/\{([^}]+)\}/g, (_, name) => "${" + name + "}");
+
+// Include every operation that requires auth (all deploy ops share one scheme)
+// and isn't marked internal. Two exclusion layers:
+//   1. no `security`      → infra (github setup/webhook, oidc token exchange)
+//   2. `x-internal: true` → explicitly marked private in the API
+const isIncluded = (op) => {
+  if (!Array.isArray(op.security) || op.security.length === 0) return false;
+  return op["x-internal"] !== true;
+};
+
+const successSchema = (op) => {
+  const responses = op.responses || {};
+  const res = responses["200"] || responses["201"];
+  return res?.content?.["application/json"]?.schema;
+};
+
+// A paginated list response is `{ next, results }` (see buildPaginator in
+// sdk-base). Detected structurally so it tracks the server, not the op name.
+const isPaginated = (op) => {
+  const schema = successSchema(op);
+  const req = schema?.required;
+  return Array.isArray(req) && req.includes("next") && req.includes("results");
+};
+
+const escape = (s) => (s || "").replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ");
+
+// Collect + sort operations by operationId for a stable, reviewable diff.
+const operations = [];
+for (const [path, methods] of Object.entries(spec.paths || {})) {
+  for (const [httpMethod, op] of Object.entries(methods)) {
+    if (!op || typeof op !== "object" || !op.operationId) continue;
+    if (!["get", "post", "delete"].includes(httpMethod)) continue;
+    if (!isIncluded(op)) continue;
+    operations.push({ path, httpMethod, op });
+  }
+}
+operations.sort((a, b) => a.op.operationId.localeCompare(b.op.operationId));
+
+const emitMethod = ({ path, httpMethod, op }) => {
+  const id = op.operationId;
+  const name = toMethodName(id);
+  const pathParams = pathParamNames(path);
+  const queryParams = (op.parameters || []).filter((p) => p.in === "query");
+  const hasBody = !!op.requestBody;
+  const paginated = isPaginated(op);
+  const url = "`" + toUrlTemplate(path) + "`";
+
+  const hasQuery = queryParams.length > 0;
+  const args = pathParams.map((p) => `${p}: string`);
+  if (hasBody) args.push(`data: OpBody<"${id}">`);
+
+  // fetcher.post takes a strict FetcherConfig (string-only params), so a POST
+  // carrying query params needs extra handling. None exist today; fail loud if
+  // that changes rather than silently dropping the query.
+  if (httpMethod === "post" && hasQuery) {
+    throw new Error(
+      `gen-client: POST with query params not supported yet (${id}). ` +
+        "Extend emitMethod to thread query params through fetcher.post's config.",
+    );
+  }
+
+  let body;
+  if (paginated) {
+    args.push(`params?: Omit<OpQuery<"${id}">, "cursor" | "next">`);
+    // The paginator's request params are untyped (`any`), so array/number/enum
+    // query values pass straight through.
+    body = `return this.paginator<OpItem<"${id}">>({ url: ${url}, params });`;
+  } else if (httpMethod === "post") {
+    // fetcher.post rejects a falsy body ("empty body"), so bodyless POSTs send
+    // an empty object.
+    const data = hasBody ? "data" : "{}";
+    body = `return this.fetcher.post<OpResult<"${id}">>(${url}, ${data});`;
+  } else if (hasQuery) {
+    // GET/DELETE with query params route through fetcher.request: its `params`
+    // is untyped, sidestepping FetcherConfig's string-only constraint, and the
+    // GET path still goes through the ETag cache.
+    args.push(`params?: OpQuery<"${id}">`);
+    const method = httpMethod.toUpperCase();
+    body = `return this.fetcher.request<OpResult<"${id}">>({ method: "${method}", url: ${url}, params });`;
+  } else if (httpMethod === "delete") {
+    body = `return this.fetcher.delete<OpResult<"${id}">>(${url});`;
+  } else {
+    body = `return this.fetcher.get<OpResult<"${id}">>(${url});`;
+  }
+
+  const guards = pathParams.map((p) => `    requireId("${p}", ${p});`);
+  const doc = op.summary || op.description;
+  const jsdoc = [
+    "  /**",
+    `   * \`${httpMethod.toUpperCase()} ${path}\` — operationId: \`${id}\``,
+    ...(doc ? [`   *`, `   * ${escape(doc)}`] : []),
+    "   */",
+  ].join("\n");
+
+  return [
+    jsdoc,
+    `  ${name}(${args.join(", ")}) {`,
+    ...guards,
+    `    ${body}`,
+    "  }",
+  ].join("\n");
+};
+
+const header = `// AUTO-GENERATED by scripts/gen-client.mjs — do not edit by hand.
+// Regenerated from the OpenAPI spec on every build (npm run gentypes).
+// Source of truth: the deploy API's operationIds + security.
+
+import type { operations } from "./types.js";
+import { FaableApi } from "@faable/sdk-base";
+import { requireId } from "../helpers.js";
+
+// JSON body of an operation's request (typed from the generated \`operations\`).
+type OpBody<K extends keyof operations> = operations[K] extends {
+  requestBody: { content: { "application/json": infer B } };
+}
+  ? B
+  : never;
+
+// JSON body of an operation's 2xx response.
+type Content2xx<R> = R extends {
+  200: { content: { "application/json": infer T } };
+}
+  ? T
+  : R extends { 201: { content: { "application/json": infer T } } }
+    ? T
+    : void;
+
+type OpResult<K extends keyof operations> = operations[K] extends {
+  responses: infer R;
+}
+  ? Content2xx<R>
+  : void;
+
+// Item type of a paginated (\`{ next, results }\`) list response.
+type OpItem<K extends keyof operations> =
+  OpResult<K> extends { results: (infer I)[] } ? I : never;
+
+// Query parameters of an operation.
+type OpQuery<K extends keyof operations> = operations[K] extends {
+  parameters: { query?: infer Q };
+}
+  ? NonNullable<Q>
+  : Record<string, never>;
+`;
+
+const classBody = operations.map(emitMethod).join("\n\n");
+
+const out = `${header}
+/**
+ * Auto-generated deploy-API methods, one per secured operation in the OpenAPI
+ * spec. \`DeployApi\` extends this and adds the constructor, custom-logic
+ * helpers, and deprecated aliases.
+ */
+export abstract class GeneratedFaableDeployApi extends FaableApi {
+${classBody}
+}
+`;
+
+writeFileSync(OUT, out);
+console.warn(
+  `gen-client: wrote ${operations.length} methods → ${OUT.replace(ROOT + "/", "")}`,
+);
+
+// Simple-named aliases for every component schema (App, Deployment, Secret, …),
+// so consumers import `App` instead of `components["schemas"]["App"]`. One alias
+// per schema, sorted for a stable diff. Hand-maintained extras (friendlier event
+// names, the AppTraffic interface) live in custom-types.ts, which re-exports
+// this file.
+const schemaNames = Object.keys(spec.components?.schemas || {})
+  .filter((name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name))
+  .sort();
+
+const typeAliases = schemaNames
+  .map((name) => `export type ${name} = components["schemas"]["${name}"];`)
+  .join("\n");
+
+const typesOut = `// AUTO-GENERATED by scripts/gen-client.mjs — do not edit by hand.
+// Regenerated from the OpenAPI spec on every build (npm run gentypes).
+// One simple-named alias per schema in \`components["schemas"]\`.
+// Hand-maintained extras live in custom-types.ts.
+
+import type { components } from "./types.js";
+
+${typeAliases}
+`;
+
+writeFileSync(OUT_TYPES, typesOut);
+console.warn(
+  `gen-client: wrote ${schemaNames.length} type aliases → ${OUT_TYPES.replace(ROOT + "/", "")}`,
+);