@faable/deploy-sdk 2.14.0 → 2.16.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@faable/deploy-sdk",
   "description": "Codebase for SDK building",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@faable/sdk-base": "^1.5.6"
+    "@faable/sdk-base": "^1.7.0"
   },
   "devDependencies": {
     "@septh/ts-run": "^1.3.0",

package/scripts/gen-client.mjs

@@ -87,6 +87,40 @@ for (const [path, methods] of Object.entries(spec.paths || {})) {
 }
 operations.sort((a, b) => a.op.operationId.localeCompare(b.op.operationId));
 
+// Multi-line descriptions become one JSDoc line each.
+const escapeBlock = (text) =>
+  String(text)
+    .split("\n")
+    .map((l) => `   * ${escape(l)}`);
+
+// The server documents each 4xx/5xx as an ErrorResponse whose `error_code`
+// is restricted to an enum, and describes every code in the response
+// description as "`code` — text" lines. Read both back so the docstring can
+// list what a caller may branch on.
+const errorCodesOf = (op) => {
+  const out = [];
+  const seen = new Set();
+  for (const [status, res] of Object.entries(op.responses || {})) {
+    if (!/^[45]\d\d$/.test(status)) continue;
+    const schema = res?.content?.["application/json"]?.schema;
+    const parts = schema?.allOf || (schema ? [schema] : []);
+    const codes = parts.flatMap((p) => p?.properties?.error_code?.enum || []);
+    const descriptions = new Map(
+      String(res?.description || "")
+        .split("\n")
+        .map((l) => l.match(/^`([a-z_]+)` — (.*)$/))
+        .filter(Boolean)
+        .map((m) => [m[1], m[2]]),
+    );
+    for (const code of codes) {
+      if (seen.has(code)) continue;
+      seen.add(code);
+      out.push({ code, status, description: descriptions.get(code) });
+    }
+  }
+  return out;
+};
+
 const emitMethod = ({ path, httpMethod, op }) => {
   const id = op.operationId;
   const name = toMethodName(id);
@@ -146,11 +180,23 @@ const emitMethod = ({ path, httpMethod, op }) => {
   }
 
   const guards = pathParams.map((p) => `    requireId("${p}", ${p});`);
-  const doc = op.summary || op.description;
+  // Summary AND description: the CRUD summaries are generic ("Get User") and
+  // used to hide the prose that actually explains the endpoint.
+  const docLines = [op.summary, op.description]
+    .filter((x, i, all) => x && all.indexOf(x) === i)
+    .flatMap((text, i) => [...(i ? ["   *"] : []), ...escapeBlock(text)]);
+  // One `@throws` per documented error code, read from the 4xx/5xx responses
+  // the server injects (see auth's server/openapi_errors.ts). The code is
+  // `err.error_code` on the FaableApiError the fetcher throws.
+  const throwsLines = errorCodesOf(op).map(
+    ({ code, status, description }) =>
+      `   * @throws {FaableApiError} \`${code}\` (${status})${description ? ` — ${escape(description)}` : ""}`,
+  );
   const jsdoc = [
     "  /**",
     `   * \`${httpMethod.toUpperCase()} ${path}\` — operationId: \`${id}\``,
-    ...(doc ? [`   *`, `   * ${escape(doc)}`] : []),
+    ...(docLines.length ? ["   *", ...docLines] : []),
+    ...(throwsLines.length ? ["   *", ...throwsLines] : []),
     "   */",
   ].join("\n");