@gusnips/sdkgen 0.1.0 → 0.2.0

package/README.md

@@ -1,7 +1,8 @@
 # @gusnips/sdkgen
 
-The parts of a script that writes a TypeScript SDK for your API. You keep the script, because the
-methods it writes are yours. This package holds the parts that are easy to get wrong.
+The parts of a script that writes a TypeScript SDK for your API. You keep the script: it picks the
+names, the doc text and anything written by hand. This package writes the rest, including the
+parts that are easy to get wrong.
 
 ```bash
 bun add -d @gusnips/sdkgen prettier
@@ -39,6 +40,9 @@ fieldsOf(inputJsonSchema(z.object({ to: z.string().describe("Who gets it.") })))
 | `camelCase`, `pascalCase` | `send_message` gives `sendMessage` and `SendMessage`.                              |
 | `inputJsonSchema`         | Turns a zod schema into JSON Schema. JSON Schema passes through as it is.          |
 | `writeGenerated`          | Formats and writes the files, or lists the ones that are out of date.              |
+| `sdkMethods`              | Writes one SDK method per operation, and the params type each one takes.           |
+| `transportSource`         | Returns the code every method runs on: the request, the retries, the error.        |
+| `retrySource`             | Returns the rule for when a failed call is worth another try.                      |
 
 ## Copy your API's types
 
@@ -76,6 +80,137 @@ output drops the comments. It finds `export interface`, `export type`, `export c
   If a real type has a name that short, the SDK will not compile, so you find out.
 - A quote inside a regex literal, like `/"/`, is read as the start of a string.
 
+## Write the methods
+
+Give each operation an `sdk` field that says what its method is called and what it returns. An
+operation without one gets no method.
+
+```ts
+import { sdkMethods } from "@gusnips/sdkgen";
+
+const { members } = sdkMethods([
+  {
+    name: "health",
+    method: "get",
+    path: "/health",
+    summary: "Check the API is up.",
+    sdk: { method: "health", returns: "HealthDto" },
+  },
+]);
+```
+
+`members` is the method as text, ready to go inside a class:
+
+```ts
+    /**
+     * Check the API is up.
+     */
+    health(opts?: RequestOptions): Promise<HealthDto> {
+        return this.request({ method: "GET", path: "/health" }, undefined, opts);
+    }
+```
+
+The operations are the same list you hand `buildOpenApi` from `@gusnips/server`, so you write them
+once. `sdk.method` is a name like `sendMessage`, or `numbers.pair` to put the method in a `numbers`
+group. `sdk.returns` is the type `data` holds: `MessageDto`, `NumberDto[]`, or `void` for a 204.
+From `@gusnips/server` 0.8.24, `buildOpenApi` checks the `sdk` field and writes it into the
+reference as `x-sdk`.
+
+Each method calls `this.request(spec, params, opts)`. Your class declares it and sends the call
+through the transport, below. `sdkMethods` also returns:
+
+- `params`: an `export interface …Params` for each method that takes arguments, written from the
+  operation's `input` schema. A path slot is filled from the field of its name, or the one
+  `params` maps to it.
+- `paramTypes` and `returnTypes`: the names your file has to import.
+
+Four options:
+
+- `namespaces`: the groups, in the order the client lists them. A group missing from the list is an
+  error, so a typo cannot start a new one.
+- `doc(op)`: the method's doc comment, one string per paragraph. Default: the summary, then the
+  description.
+- `specExtra(op)`: more fields on the spec, for your own `request` to read.
+- `inject`: methods you write by hand, such as one that polls a job. They go beside the generated
+  ones and must not take one of their names.
+
+It stops with an error that names the operation when a method name has more than one dot, two
+methods want one name, a status with no body (204, 205, 304) returns something, or a path slot is
+filled by a field the caller may leave out.
+
+## Send the calls
+
+Two more files go into the SDK. `transportSource()` is the code that sends each call: it fills the
+path, tries again when that is safe, and turns a failure into your SDK's own error.
+`retrySource()` is the rule it asks, from `@gusnips/http`. Both are plain TypeScript that import
+nothing else, so the SDK installs nothing.
+
+```ts
+import { retrySource, transportSource } from "@gusnips/sdkgen";
+
+const files = {
+  "packages/sdk/src/generated/retry.ts": retrySource(),
+  "packages/sdk/src/generated/transport.ts": transportSource(),
+};
+```
+
+Your client hands its settings to `send`, which returns `{ data, meta }`:
+
+```ts
+import { GeneratedOperations } from "./generated/operations.ts";
+import {
+  send,
+  type RequestOptions,
+  type RequestSpec,
+  type Transport,
+} from "./generated/transport.ts";
+
+export class Example extends GeneratedOperations {
+  private readonly transport: Transport;
+
+  constructor(apiKey: string) {
+    super();
+    this.transport = {
+      baseUrl: "https://api.example.com/v1",
+      headers: { authorization: `Bearer ${apiKey}` },
+      error: (failure) => new ExampleError(failure),
+    };
+  }
+
+  protected async request<T>(spec: RequestSpec, params?: object, opts?: RequestOptions) {
+    return (await send<T>(this.transport, spec, params, opts)).data;
+  }
+}
+```
+
+| Setting                   | Default   | What it does                                                                |
+| ------------------------- | --------- | --------------------------------------------------------------------------- |
+| `baseUrl`                 | required  | Where the API lives, with its base path.                                    |
+| `error(failure)`          | required  | Builds your SDK's error. The transport throws what it returns.              |
+| `headers`                 | none      | Sent on every call.                                                         |
+| `fetch`                   | global    | The fetch to call, such as a fake one in tests.                             |
+| `timeoutMs(spec, params)` | 30,000 ms | How long one try waits for an answer. A call's `opts.timeoutMs` wins.       |
+| `maxRetries`              | 2         | Extra tries after a failure worth repeating.                                |
+| `durableCodes`            | none      | Error codes that waiting does not fix, such as a spent monthly quota.       |
+| `mintKeys`                | false     | Makes up an idempotency key for a call that takes one, so it can try again. |
+
+`failure` has the status (0 when no answer came back), the API's `error`, the `Retry-After` wait,
+the request id, and the idempotency key the call went out with. A call that may have run can be
+sent again with that key, and the API answers from the first run.
+
+A failed call is tried again:
+
+- **After a 408, 425 or 429**, whatever it is. Those say the API did not run it.
+- **After no answer, a 5xx, or a 409 that says when to come back**, only if running it twice is
+  safe. A GET is. A write is when its operation reads an `Idempotency-Key` and the call has one, or
+  when its `sdk.repeatable` is true. A write without a key is not sent twice, because it may
+  already have run.
+- **Never** when the answer says waiting will not help: a code in `durableCodes`,
+  `details.retryAfterSecs: null`, or a wait longer than 10 seconds.
+
+It waits what the `Retry-After` header says, in seconds or as a date, then what
+`details.retryAfterSecs` says. With neither, it waits about 1 second, then 2.
+
 ## Keep the SDK current
 
 ```ts
@@ -108,6 +243,10 @@ error and not "out of date".
 - **A `*/` in a description is broken up**, so it cannot end the doc comment early.
 - **A zod schema needs zod 4.4 or later.** Older versions cannot describe themselves as JSON
   Schema, and the error says so.
+- **A call with a missing path value throws a TypeError** before anything is sent, rather than
+  calling `/numbers//pair`.
+- **An idempotency key on a call that takes none throws.** The API would ignore it, so it could not
+  stop the call running twice.
 
 ## Why it exists
 
@@ -121,7 +260,7 @@ had fixed something the others had not, and every one still had these bugs:
 - `export interface Empty {}` on one line swallowed the declaration after it.
 - A comment written `/*/` ended on the character that opened it.
 
-This package is the merge, with each fix pinned by a test. Two of those generators were rewritten
-on it and wrote every file byte for byte as before, 268 and 281 lines shorter.
+This package is the merge, with each fix pinned by a test. All five generators were then rewritten
+on it and wrote every file byte for byte as before, each 267 to 281 lines shorter.
 
 MIT

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { liftContract, type LiftOptions } from "./contract.ts";
+export { retrySource, sdkMethods, transportSource, type InjectedMember, type SdkMethods, type SdkMethodsOptions, type SdkOperation, type SdkPlacement, } from "./methods.ts";
 export { camelCase, docComment, fieldsOf, inputJsonSchema, paramsInterface, pascalCase, typeNames, typeOf, wrapLines, type JsonObject, type SchemaSource, type StandardJsonSchema, } from "./types.ts";
 export { writeGenerated, type GeneratedFiles, type WriteOptions, type WriteResult, } from "./write.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,MAAM,EACN,SAAS,EACT,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,WAAW,EACX,UAAU,EACV,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,MAAM,EACN,SAAS,EACT,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,4 +1,5 @@
 export { liftContract } from "./contract.js";
+export { retrySource, sdkMethods, transportSource, } from "./methods.js";
 export { camelCase, docComment, fieldsOf, inputJsonSchema, paramsInterface, pascalCase, typeNames, typeOf, wrapLines, } from "./types.js";
 export { writeGenerated, } from "./write.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAoB,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,MAAM,EACN,SAAS,GAIV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,GAIf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAoB,MAAM,eAAe,CAAC;AAC/D,OAAO,EACL,WAAW,EACX,UAAU,EACV,eAAe,GAMhB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,MAAM,EACN,SAAS,GAIV,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,GAIf,MAAM,YAAY,CAAC"}

package/dist/methods.d.ts

@@ -0,0 +1,105 @@
+import { type SchemaSource } from "./types.ts";
+/** Where the generated SDK puts an operation. */
+export interface SdkPlacement {
+    /** `sendMessage`, or `numbers.pair` in a namespace. One dot at most; unique. */
+    method: string;
+    /** What `data` holds, as the SDK names it: `MessageDto`, `NumberDto[]`; `void` for a 204. */
+    returns: string;
+    /**
+     * Safe to run twice with no key: a read sent as a POST, or a write the server dedupes on its
+     * own. Default: a GET only.
+     */
+    repeatable?: boolean;
+}
+/**
+ * The part of an operation the generator reads. It is a structural subset of `@gusnips/server`'s
+ * `OpenApiOperation`, so the list an API hands `buildOpenApi` fits here unchanged.
+ */
+export interface SdkOperation {
+    name: string;
+    method: "get" | "post" | "put" | "patch" | "delete";
+    /** The route as the router spells it: `/numbers/:id`. */
+    path: string;
+    summary: string;
+    description?: string;
+    /** Everything the operation reads. It becomes the method's params interface. */
+    input?: SchemaSource;
+    /** Input field → path slot, where the two names differ: `{ numberId: "id" }`. */
+    params?: Readonly<Record<string, string>>;
+    /** Fields the route fills in itself. The SDK leaves them out. */
+    fixed?: readonly string[];
+    /** Request headers the operation reads. An `Idempotency-Key` here makes the call keyed. */
+    headers?: readonly {
+        readonly name: string;
+    }[];
+    /** The success status. A 204, 205 or 304 has no body, so it returns `void`. */
+    status?: number;
+    extensions?: Readonly<Record<`x-${string}`, unknown>>;
+    /** Where the generated SDK puts this operation. Absent: no method. */
+    sdk?: SdkPlacement;
+}
+/** A member written by hand, placed beside the generated ones and held to the same names. */
+export interface InjectedMember {
+    /** `jobs.wait`, or `wait` at the top level. */
+    method: string;
+    /** Its parameters and return type: `(jobId: string, opts?: WaitOptions): Promise<JobDto>`. */
+    signature: string;
+    /** What it returns: `this.waitForJob(jobId, opts)`. */
+    call: string;
+    /** Its doc comment, one string per paragraph. */
+    doc?: readonly string[];
+}
+export interface SdkMethodsOptions {
+    /**
+     * The namespaces, in the order the client lists them. Given, a namespace not in it throws, so a
+     * typo cannot start a new one. Default: the order they first appear.
+     */
+    namespaces?: readonly string[];
+    /**
+     * A method's doc comment, one string per paragraph; `undefined` ones are skipped. Default: the
+     * summary, then the description.
+     */
+    doc?: (op: SdkOperation) => readonly (string | undefined)[];
+    /** Fields to add to the spec an operation hands `request`, such as its proxy block's fields. */
+    specExtra?: (op: SdkOperation) => Readonly<Record<string, unknown>> | undefined;
+    /** Members written by hand, each after the generated ones in its place. */
+    inject?: readonly InjectedMember[];
+}
+export interface SdkMethods {
+    /** An `export interface …Params` for each method that takes arguments: the body of `params.ts`. */
+    params: string;
+    /**
+     * The class members: top-level methods first, then one object per namespace. Each calls
+     * `this.request(spec, params, opts)`, which the class declares and the SDK implements.
+     */
+    members: string;
+    /** The params interfaces the members name, sorted, for their import line. */
+    paramTypes: string[];
+    /** The declared types the `returns` name, sorted, for their import from the contract. */
+    returnTypes: string[];
+}
+/**
+ * The SDK's methods for every operation that names an `sdk` place, with the params interfaces they
+ * take.
+ *
+ * ```ts
+ * const { params, members, paramTypes, returnTypes } = sdkMethods(operations);
+ * const file = `export abstract class GeneratedOperations {
+ *     protected abstract request<T>(spec: RequestSpec, params?: object, opts?: RequestOptions): Promise<T>;
+ * ${members}}\n`;
+ * ```
+ */
+export declare function sdkMethods(operations: readonly SdkOperation[], options?: SdkMethodsOptions): SdkMethods;
+/**
+ * `@gusnips/http`'s retry rule, its `src/retry.ts` whole, for an SDK to carry as
+ * `generated/retry.ts`. It is read from this package's own dependency, never the adopter's, so
+ * every SDK built with one sdkgen carries one rule. When an sdkgen release moves the rule, each
+ * SDK's `--check` fails, and that is the signal to release the SDK.
+ */
+export declare function retrySource(): string;
+/**
+ * The transport every generated method runs on, for an SDK to carry as `generated/transport.ts`
+ * beside `retry.ts`: this package's own `src/transport.ts`, importing the rule from `./retry.ts`.
+ */
+export declare function transportSource(): string;
+//# sourceMappingURL=methods.d.ts.map

package/dist/methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.d.ts","sourceRoot":"","sources":["../src/methods.ts"],"names":[],"mappings":"AAmBA,OAAO,EAOL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AAEpB,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,iFAAiF;IACjF,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1C,iEAAiE;IACjE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,2FAA2F;IAC3F,OAAO,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC/C,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,sEAAsE;IACtE,GAAG,CAAC,EAAE,YAAY,CAAC;CACpB;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAC;IAC5D,gGAAgG;IAChG,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,YAAY,KAAK,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAChF,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,mGAAmG;IACnG,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,yFAAyF;IACzF,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAuBD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,SAAS,YAAY,EAAE,EACnC,OAAO,GAAE,iBAAsB,GAC9B,UAAU,CA0EZ;AAgID;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAGxC"}

package/dist/methods.js

@@ -0,0 +1,237 @@
+/**
+ * The methods an SDK exposes, written from the operation list the API already mounts, and the two
+ * files they run on.
+ *
+ * Five generators each wrote this loop, and what they shared is here: one method per operation,
+ * grouped by namespace, taking the params interface its input schema gives and returning the type
+ * the operation says `data` holds; a path whose slots carry the argument's own name, so the
+ * transport can fill them; and the checks that stop a wrong SDK at generation rather than in the
+ * hands of whoever installs it. What differs by product comes in through options: the doc
+ * comment's paragraphs, what the spec carries beyond the route, and members written by hand.
+ *
+ * It reads the operation list in-process, never the published OpenAPI document. The document has
+ * lost the type names, the argument renames and the typed query params, and a type JSON cannot
+ * carry reaches it as `{}`, where the schema writer here would have stopped.
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { inputJsonSchema, paramsInterface, pascalCase, typeNames, wrapLines, } from "./types.js";
+/** Success statuses with no body (RFC 9110), the same three the server's reference documents so. */
+const NO_BODY = new Set([204, 205, 304]);
+/** Class members a method must not be named: the seam every method calls, and the constructor. */
+const RESERVED = new Set(["request", "constructor"]);
+/** The spec fields the generator writes, which `specExtra` must not overwrite. */
+const SPEC_FIELDS = new Set(["method", "path", "keyed", "repeatable"]);
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+/**
+ * The SDK's methods for every operation that names an `sdk` place, with the params interfaces they
+ * take.
+ *
+ * ```ts
+ * const { params, members, paramTypes, returnTypes } = sdkMethods(operations);
+ * const file = `export abstract class GeneratedOperations {
+ *     protected abstract request<T>(spec: RequestSpec, params?: object, opts?: RequestOptions): Promise<T>;
+ * ${members}}\n`;
+ * ```
+ */
+export function sdkMethods(operations, options = {}) {
+    const { doc = (op) => [op.summary, op.description], specExtra, inject = [] } = options;
+    const members = [];
+    const params = [];
+    const paramTypes = [];
+    const returnTypes = new Set();
+    for (const op of operations) {
+        const sdk = op.sdk;
+        if (sdk === undefined)
+            continue;
+        const where = `${op.method.toUpperCase()} ${op.path} (${op.name})`;
+        if (op.status !== undefined && NO_BODY.has(op.status) && sdk.returns !== "void") {
+            throw new Error(`${where} answers ${op.status}, which has no body, so \`sdk.returns\` must be "void".`);
+        }
+        const schema = op.input === undefined ? undefined : schemaOf(op.input, where);
+        const fixed = op.fixed ?? [];
+        const typeName = `${pascalCase(op.name)}Params`;
+        const iface = schema === undefined ? null : paramsInterface(typeName, schema, fixed);
+        if (iface !== null) {
+            params.push(`/** Arguments for \`${sdk.method}()\`. */\n${iface.source}`);
+            paramTypes.push(typeName);
+        }
+        for (const name of typeNames(sdk.returns))
+            returnTypes.add(name);
+        const listed = schema?.["required"];
+        const required = new Set(Array.isArray(listed)
+            ? listed.filter((f) => typeof f === "string" && !fixed.includes(f))
+            : []);
+        const fields = [
+            `method: "${op.method.toUpperCase()}"`,
+            `path: ${JSON.stringify(sdkPath(op, required, where))}`,
+        ];
+        if (op.headers?.some((h) => h.name.toLowerCase() === "idempotency-key"))
+            fields.push("keyed: true");
+        if (sdk.repeatable !== undefined)
+            fields.push(`repeatable: ${sdk.repeatable}`);
+        for (const [key, value] of Object.entries(specExtra?.(op) ?? {})) {
+            if (SPEC_FIELDS.has(key)) {
+                throw new Error(`${where}: \`specExtra\` sets "${key}", which the generator writes itself.`);
+            }
+            if (value !== undefined)
+                fields.push(`${propertyKey(key)}: ${JSON.stringify(value)}`);
+        }
+        const argument = iface === null ? "" : `params${iface.optional ? "?" : ""}: ${typeName}, `;
+        members.push({
+            where,
+            ...place(sdk.method, where),
+            doc: doc(op),
+            signature: `(${argument}opts?: RequestOptions): Promise<${sdk.returns}>`,
+            call: `this.request({ ${fields.join(", ")} }, ${iface === null ? "undefined" : "params"}, opts)`,
+        });
+    }
+    for (const member of inject) {
+        const where = `The hand-written ${member.method}`;
+        members.push({
+            where,
+            ...place(member.method, where),
+            doc: member.doc ?? [],
+            signature: member.signature,
+            call: member.call,
+        });
+    }
+    return {
+        params: params.join("\n"),
+        members: writeMembers(members, options.namespaces),
+        paramTypes: paramTypes.sort(),
+        returnTypes: [...returnTypes].sort(),
+    };
+}
+/** `numbers.pair` → its namespace and name, each checked to be a name a class member can have. */
+function place(method, where) {
+    const parts = method.split(".");
+    if (parts.length > 2 || !parts.every((part) => IDENTIFIER.test(part))) {
+        throw new Error(`${where}: \`${method}\` is not a method name. Write \`name\`, or \`namespace.name\` with one dot.`);
+    }
+    const [first = "", second] = parts;
+    return second === undefined
+        ? { namespace: undefined, name: first }
+        : { namespace: first, name: second };
+}
+/** Top-level methods first, then one `readonly namespace = { … }` per namespace. */
+function writeMembers(members, order) {
+    const seen = new Map();
+    const topLevel = new Set();
+    const namespaces = [];
+    for (const { where, namespace, name } of members) {
+        const full = namespace === undefined ? name : `${namespace}.${name}`;
+        const first = seen.get(full);
+        if (first !== undefined) {
+            throw new Error(`Two methods want to be \`${full}\`: ${first}, and ${where}. Rename one.`);
+        }
+        seen.set(full, where);
+        if (namespace === undefined)
+            topLevel.add(name);
+        else if (!namespaces.includes(namespace))
+            namespaces.push(namespace);
+    }
+    for (const name of [...topLevel, ...namespaces]) {
+        if (RESERVED.has(name)) {
+            throw new Error(`\`${name}\` is a class member every SDK already has. Pick another name.`);
+        }
+        if (topLevel.has(name) && namespaces.includes(name)) {
+            throw new Error(`\`${name}\` is both a method and a namespace. Rename one.`);
+        }
+    }
+    if (order !== undefined) {
+        const unknown = namespaces.find((namespace) => !order.includes(namespace));
+        if (unknown !== undefined) {
+            throw new Error(`The namespace \`${unknown}\` is not in \`namespaces\`. Add it there, or use one of: ${order.join(", ")}.`);
+        }
+    }
+    let out = "";
+    for (const member of members.filter((m) => m.namespace === undefined)) {
+        out += `\n${jsdoc(member.doc, "    ")}    ${member.name}${member.signature} {\n`;
+        out += `        return ${member.call};\n    }\n`;
+    }
+    for (const namespace of (order ?? namespaces).filter((ns) => namespaces.includes(ns))) {
+        out += `\n    readonly ${namespace} = {\n`;
+        for (const member of members.filter((m) => m.namespace === namespace)) {
+            out += `${jsdoc(member.doc, "        ")}        ${member.name}: ${member.signature} =>\n`;
+            out += `            ${member.call},\n`;
+        }
+        out += `    };\n`;
+    }
+    return out;
+}
+/**
+ * The route with each slot named for the argument that fills it: `/numbers/:id` with
+ * `{ numberId: "id" }` → `/numbers/:numberId`. A slot's argument must be required, or the SDK
+ * would let a caller leave out part of the address.
+ */
+function sdkPath(op, required, where) {
+    // A constraint such as `:id{[0-9]+}` is the router's business, and the SDK drops it.
+    const slot = /:(\w+)(\{[^}]*\})?(\?)?/g;
+    const slots = new Set([...op.path.matchAll(slot)].map((match) => match[1]));
+    const fieldIn = new Map();
+    for (const [field, name] of Object.entries(op.params ?? {})) {
+        if (!slots.has(name)) {
+            throw new Error(`${where}: \`params\` sends ${field} in ":${name}", which the path does not have.`);
+        }
+        fieldIn.set(name, field);
+    }
+    return op.path.replace(slot, (_match, name, _re, optional) => {
+        if (optional) {
+            throw new Error(`${where} has an optional slot ":${name}?". List it as two operations, with and without it.`);
+        }
+        const field = fieldIn.get(name) ?? name;
+        if (!/^\w+$/.test(field)) {
+            throw new Error(`${where}: the path's ":${name}" is filled from \`${field}\`, which a path cannot name. Rename the field.`);
+        }
+        if (!required.has(field)) {
+            throw new Error(`${where}: the path's ":${name}" is filled from \`${field}\`, which the input does not require. ` +
+                "Make it required, or map the slot to another field with `params`.");
+        }
+        return `:${field}`;
+    });
+}
+/** The input as JSON Schema, with the operation named when it cannot be written. */
+function schemaOf(input, where) {
+    try {
+        return inputJsonSchema(input);
+    }
+    catch (err) {
+        throw new Error(`${where}: ${err instanceof Error ? err.message : String(err)}`, {
+            cause: err,
+        });
+    }
+}
+/** `/**` over paragraphs, a blank ` *` line between them, each wrapped for its indent. */
+function jsdoc(paragraphs, indent) {
+    const blocks = paragraphs
+        .map((paragraph) => (paragraph === undefined ? [] : wrapLines(paragraph, indent)))
+        .filter((lines) => lines.length > 0);
+    if (blocks.length === 0)
+        return "";
+    const line = `\n${indent} * `;
+    return `${indent}/**${line}${blocks.map((lines) => lines.join(line)).join(`\n${indent} *${line}`)}\n${indent} */\n`;
+}
+/** A key that is not an identifier has to be quoted. */
+const propertyKey = (key) => (IDENTIFIER.test(key) ? key : JSON.stringify(key));
+/**
+ * `@gusnips/http`'s retry rule, its `src/retry.ts` whole, for an SDK to carry as
+ * `generated/retry.ts`. It is read from this package's own dependency, never the adopter's, so
+ * every SDK built with one sdkgen carries one rule. When an sdkgen release moves the rule, each
+ * SDK's `--check` fails, and that is the signal to release the SDK.
+ */
+export function retrySource() {
+    const entry = createRequire(import.meta.url).resolve("@gusnips/http/retry");
+    return readFileSync(join(dirname(entry), "../src/retry.ts"), "utf8");
+}
+/**
+ * The transport every generated method runs on, for an SDK to carry as `generated/transport.ts`
+ * beside `retry.ts`: this package's own `src/transport.ts`, importing the rule from `./retry.ts`.
+ */
+export function transportSource() {
+    const path = fileURLToPath(new URL("../src/transport.ts", import.meta.url));
+    return readFileSync(path, "utf8").replace(`from "@gusnips/http/retry";`, `from "./retry.ts";`);
+}
+//# sourceMappingURL=methods.js.map

package/dist/methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.js","sourceRoot":"","sources":["../src/methods.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,88 @@
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** What a generated method tells the transport about its operation. */
+export interface RequestSpec {
+    method: HttpMethod;
+    /** `/numbers/:numberId/pair`. Each `:name` is filled from the params field of that name. */
+    path: string;
+    /** The operation reads an `Idempotency-Key`, so the server answers a repeat from the first run. */
+    keyed?: boolean;
+    /** Safe to run twice with no key, such as a read sent as a POST. Absent: true for a GET only. */
+    repeatable?: boolean;
+}
+/** The last argument of every generated method. */
+export interface RequestOptions {
+    /**
+     * Your own key for a call that takes one, such as a UUID saved with the message you send.
+     * Every attempt sends the same key, and so can your own retry after a crash.
+     */
+    idempotencyKey?: string;
+    /** How long one attempt waits for an answer, in milliseconds. Overrides the SDK's. */
+    timeoutMs?: number;
+}
+/** The `error` of the envelope, as the answer carried it. */
+export interface EnvelopeError {
+    /** What went wrong, as a word a program can check. */
+    code: string;
+    message: string | undefined;
+    messageKey: string | undefined;
+    params: Record<string, string | number> | undefined;
+    /** As sent. `{ retryAfterSecs: null }` means waiting never helps. */
+    details: unknown;
+}
+/** A call that did not work, as `error` gets it to build the SDK's own error. */
+export interface Failure {
+    method: HttpMethod;
+    /** The path with its values filled in: `/numbers/n_1/pair`. */
+    path: string;
+    /** The HTTP status, or 0 when no answer came back: offline, a dropped connection, a timeout. */
+    status: number;
+    /** No answer within `timeoutMs`. The call may still have run. */
+    timedOut: boolean;
+    timeoutMs: number;
+    /** The envelope's `error`, when the answer carried one. */
+    error: EnvelopeError | undefined;
+    /** An answer that was not the envelope, such as a gateway's HTML page: its first 500 characters. */
+    text: string | undefined;
+    /** `Retry-After` in seconds, whichever of its two forms it came in. */
+    retryAfterSecs: number | undefined;
+    /** The `x-request-id` header, for the API's support to find the call. */
+    requestId: string | undefined;
+    /** The key the call was sent with. Retry with it, and a call that ran answers from its first run. */
+    idempotencyKey: string | undefined;
+    /** What fetch threw, when no answer came back. */
+    cause: unknown;
+}
+/** One SDK's settings. */
+export interface Transport {
+    /** Where the API lives, with its base path: `https://api.example.com/v1`. */
+    baseUrl: string;
+    /** Sent on every call, such as the credential and the SDK's version. */
+    headers?: Readonly<Record<string, string>>;
+    /** Default: the global `fetch`. */
+    fetch?: typeof fetch;
+    /** How long one attempt of this call waits for an answer, in milliseconds. Default 30,000. */
+    timeoutMs?: (spec: RequestSpec, params: object) => number;
+    /** Extra attempts after a failure the retry rule says is worth repeating. Default 2. */
+    maxRetries?: number;
+    /** Error codes that waiting does not clear, such as a spent monthly quota. */
+    durableCodes?: readonly string[];
+    /**
+     * Make up a key for a call that takes one when the caller sent none, so the call can be retried.
+     * Default false: without a key, a write that may have run is not sent again.
+     */
+    mintKeys?: boolean;
+    /** Builds the SDK's own error for a failed call. The transport throws what this returns. */
+    error: (failure: Failure) => Error;
+}
+/** A call that worked. `data` is `undefined` for a 204 or any other empty answer. */
+export interface Answer<T, M> {
+    data: T;
+    meta: M | undefined;
+}
+/**
+ * Sends one call, retries it while the rule says so, and returns `{ data, meta }` or throws
+ * `transport.error(failure)`. A value the path needs and did not get throws a TypeError before
+ * anything is sent.
+ */
+export declare function send<T = unknown, M = unknown>(transport: Transport, spec: RequestSpec, params?: object, opts?: RequestOptions): Promise<Answer<T, M>>;
+//# sourceMappingURL=transport.d.ts.map