@faable/deploy-sdk 2.14.0 → 2.15.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");
 

package/spec/openapi.json

@@ -69,6 +69,105 @@
       }
     },
     "schemas": {
+      "ProjectLimits": {
+        "type": "object",
+        "required": [
+          "can_create",
+          "reason",
+          "message",
+          "free_projects",
+          "max_free_projects",
+          "upgradable_projects",
+          "new_account_window_ends_at",
+          "resolved"
+        ],
+        "properties": {
+          "can_create": {
+            "type": "boolean"
+          },
+          "reason": {
+            "anyOf": [
+              {
+                "type": "string",
+                "enum": [
+                  "free_project_limit"
+                ]
+              },
+              {
+                "type": "string",
+                "enum": [
+                  "new_account_window"
+                ]
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "message": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "free_projects": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "max_free_projects": {
+            "anyOf": [
+              {
+                "type": "integer"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "upgradable_projects": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "name"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "new_account_window_ends_at": {
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "date-time"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "resolved": {
+            "type": "boolean"
+          }
+        }
+      },
       "ProjectInvite": {
         "type": "object",
         "required": [
@@ -1040,7 +1139,8 @@
           "description": {
             "type": "string"
           }
-        }
+        },
+        "additionalProperties": false
       },
       "AppUpdate": {
         "type": "object",
@@ -1074,6 +1174,44 @@
         },
         "additionalProperties": false
       },
+      "AppRepoLinkable": {
+        "type": "object",
+        "required": [
+          "linkable"
+        ],
+        "properties": {
+          "linkable": {
+            "type": "boolean"
+          },
+          "code": {
+            "type": "string",
+            "enum": [
+              "repository_already_linked"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "details": {
+            "type": "object",
+            "required": [
+              "app_id"
+            ],
+            "properties": {
+              "app_id": {
+                "type": "string"
+              },
+              "app_name": {
+                "type": "string"
+              },
+              "project": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "description": "Repository link pre-check"
+      },
       "DeployBranchResult": {
         "type": "object",
         "required": [
@@ -1358,6 +1496,16 @@
             "type": "string",
             "description": "Why the deployment failed (shown to the user on ERROR)"
           },
+          "failure_code": {
+            "type": "string",
+            "description": "Producer's own name for what failed (e.g. detect_no_buildpack). Not the fault taxonomy."
+          },
+          "failure_detail": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": true,
+            "description": "Structured context the producer had before writing `reason` (found_files, subdir_hits, workdir, root_dir…). Never free build output: it must carry no repository paths beyond the entry names detection already lists."
+          },
           "cold_state": {
             "anyOf": [
               {
@@ -4117,6 +4265,48 @@
     }
   },
   "paths": {
+    "/project/limits": {
+      "get": {
+        "operationId": "project/limits",
+        "summary": "Project creation limits for the caller",
+        "tags": [
+          "projects"
+        ],
+        "description": "Whether the caller can create another project, and why not",
+        "security": [
+          {
+            "faable_user": []
+          },
+          {
+            "faable_cli": []
+          },
+          {
+            "faable_m2m": []
+          },
+          {
+            "faable_machine": []
+          },
+          {
+            "apikey_basic": []
+          },
+          {
+            "apikey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProjectLimits"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/project/{id}/invite": {
       "post": {
         "operationId": "project/invite",
@@ -5067,7 +5257,8 @@
                   "description": {
                     "type": "string"
                   }
-                }
+                },
+                "additionalProperties": false
               }
             }
           }
@@ -6597,6 +6788,71 @@
         }
       }
     },
+    "/app/repo-linkable": {
+      "get": {
+        "operationId": "app/repo_linkable",
+        "summary": "Check whether a repository can be linked to a new app",
+        "tags": [
+          "apps",
+          "github"
+        ],
+        "description": "Runs the free-plan \"one repository, one app\" guard before the app exists. Always 200: `linkable:false` names the app that already has the repository (and its project when it is another one of yours), with the same message the link would refuse with.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "minLength": 3,
+              "maxLength": 255
+            },
+            "in": "query",
+            "name": "repository",
+            "required": true,
+            "description": "GitHub repository full name, e.g. acme/api"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "github_installation_id",
+            "required": false,
+            "description": "GitHub App installation the repo belongs to"
+          }
+        ],
+        "security": [
+          {
+            "faable_user": []
+          },
+          {
+            "faable_cli": []
+          },
+          {
+            "faable_m2m": []
+          },
+          {
+            "faable_machine": []
+          },
+          {
+            "apikey_basic": []
+          },
+          {
+            "apikey": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Repository link pre-check",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AppRepoLinkable"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/app/{app_id}/registry": {
       "get": {
         "operationId": "app/get_registry",
@@ -6870,7 +7126,8 @@
                     "origin_status_codes",
                     "latency",
                     "top_referrers",
-                    "top_user_agents"
+                    "top_user_agents",
+                    "degraded"
                   ],
                   "properties": {
                     "range": {
@@ -7089,6 +7346,12 @@
                           }
                         }
                       }
+                    },
+                    "degraded": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
                     }
                   }
                 }