@faable/auth-sdk 2.2.1 → 2.3.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./FaableAuthApi.js";
+export * from "./api/generated-client.js";
 export * from "./api/api-types.js";
 export * from "./api/types.js";
 export { authClientCredentials, authApikey } from "@faable/sdk-base";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./FaableAuthApi.js";
+export * from "./api/generated-client.js";
 export * from "./api/api-types.js";
 export * from "./api/types.js";
 // Re-export the auth strategies (and their config/types) from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/auth-sdk",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,7 @@
     "typescript": "^5.3.3"
   },
   "scripts": {
-    "gentypes": "openapi-typescript ${AUTH_OPENAPI:-spec/openapi.json} -o src/api/types.ts",
+    "gentypes": "openapi-typescript ${AUTH_OPENAPI:-spec/openapi.json} -o src/api/types.ts && node scripts/gen-client.mjs",
     "build": "rimraf dist && tsc",
     "prebuild": "npm run gentypes",
     "prepublishOnly": "npm run build",

package/scripts/gen-client.mjs

@@ -0,0 +1,205 @@
+// Generates `src/api/generated-client.ts` from the OpenAPI spec.
+//
+// Why: the SDK's typed methods (userGet, teamList, …) used to be hand-written
+// and always lagged the server. The TYPES are already auto-generated by
+// openapi-typescript; this script does the same for the METHODS, so the SDK
+// covers the whole management API for free and stays in sync on every build.
+//
+// Scope: only operations whose `security` includes `bearerAuth` (the management
+// API). OAuth/OIDC/session/login browser flows carry no bearerAuth and are
+// skipped — they are not SDK convenience calls. All included operationIds have
+// the stable `resource/action` shape, so the camelCase names come out clean.
+//
+// Run via `npm run gentypes` (after openapi-typescript). 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.AUTH_OPENAPI || resolve(ROOT, "spec/openapi.json");
+const OUT = resolve(ROOT, "src/api/generated-client.ts");
+
+const spec = JSON.parse(readFileSync(SPEC, "utf8"));
+
+// operationId (`resource/action`, possibly snake/kebab in the action) → camelCase
+// method name. `user/list`→userList, `client/rotateSecret`→clientRotateSecret,
+// `role/assign_users`→roleAssignUsers.
+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("");
+
+// `/team/{team_id}/member/check/{user_id}` → ["team_id", "user_id"], in order.
+const pathParamNames = (path) =>
+  [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1]);
+
+// `/user/{user_id}` → "/user/${user_id}" (template-literal body).
+const toUrlTemplate = (path) =>
+  path.replace(/\{([^}]+)\}/g, (_, name) => "${" + name + "}");
+
+const hasBearerAuth = (op) =>
+  Array.isArray(op.security) &&
+  op.security.some((req) => req && Object.keys(req).includes("bearerAuth"));
+
+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 (!hasBearerAuth(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}">`);
+
+  // The only POST without a query in the spec; if that ever changes the
+  // generator must learn to pass query on a POST (fetcher.post takes a strict
+  // FetcherConfig). Fail loud rather than silently drop the query params.
+  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 (e.g.
+    // client/rotateSecret) 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 auth server's operationIds + bearerAuth 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 management-API methods, one per \`bearerAuth\` operation in the
+ * OpenAPI spec. \`FaableAuthApi\` extends this and adds the constructor,
+ * custom-logic helpers, and deprecated aliases.
+ */
+export abstract class GeneratedFaableAuthApi extends FaableApi {
+${classBody}
+}
+`;
+
+writeFileSync(OUT, out);
+console.warn(
+  `gen-client: wrote ${operations.length} methods → ${OUT.replace(ROOT + "/", "")}`,
+);