feat: options paramater, supporting { validParams: false }

See Note 3 about in README about "additionalProperties in params"
and the example for discourse.updateUser({ title: "X" }).

Author: gadicc

README.md

@@ -168,17 +168,31 @@ following APIs were supported: (link is to official docs, in same order).
    spec) but not provided, we'll try the call anyway and let the endpoint
    decide.
 
+1. By default, **additionalProperties in params** are disallowed. This is to
+   help prevent typos. However, often there are undocumented parameters that
+   still work, in which case, you can disable param validation. e.g.
+
+   ```ts
+   await discourse.updateUser({
+     username: "user to update",
+     // @ts-expect-error: not in spec    <-- disable type check
+     title: "a new title",
+   }, {
+     validateParams: false, //           <-- disable runtime validation
+   });
+   ```
+
 1. Currently, **the response is not validated**, because unfortunately, the
    returned data often does not validate against the OpenAPI schema
    (`additionalProperties`, missing `required` props, wrong types).
 
-   I'm still deciding what to do with about this, feedback (in an issue) would
-   be greatly appreciated. In theory I'd like to make this a configurable
-   option, but if we don't validate, we really should be returning the data as
-   an `unknown` type so the user performs their own validation, which is a pain,
-   and you'll lose typescript completion. However, on the flip side, what we do
-   now is return a type that is wrong, and TypeScript won't warn about missing
-   (but now required) checks.
+I'm still deciding what to do with about this, feedback (in an issue) would be
+greatly appreciated. In theory I'd like to make this a configurable option, but
+if we don't validate, we really should be returning the data as an `unknown`
+type so the user performs their own validation, which is a pain, and you'll lose
+typescript completion. However, on the flip side, what we do now is return a
+type that is wrong, and TypeScript won't warn about missing (but now required)
+checks.
 
 1. Installed Discourse extensions / plugins may affect the result! It can add
    additional properties, etc. Likewise, running older versions of Discourse may
@@ -194,3 +208,6 @@ following APIs were supported: (link is to official docs, in same order).
 ## Development
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+```
+```

deno.lock

@@ -40,12 +40,14 @@ const methods = [
 ] as Method[];
 
 (async () => {
-  let out = 'import type { operations } from "./schema.d.ts";' + "\n\n";
+  let out = 'import type { operations } from "./schema.d.ts";' + "\n" +
+    'import type { DiscourseExecOptions } from "./types.ts";' + "\n\n";
+
   out +=
     "type Prettify<T> = {\n  [K in keyof T]: T[K];\n// deno-lint-ignore ban-types\n} & {}\n\n";
   out += "export default class DiscourseAPIGenerated {\n";
   out +=
-    "  _exec<T>(_operationName: string, _params?: unknown) { throw new Error('Not implemented'); }\n\n";
+    "  _exec<T>(_operationName: string, _params?: unknown, options?: unknown) { throw new Error('Not implemented'); }\n\n";
 
   for (const [path, pathData] of objectEntries(spec.paths)) {
     for (const method of methods) {
@@ -156,6 +158,10 @@ const methods = [
         }
       }
 
+      const hasParams = types.length || methodData.requestBody;
+      methodString += (hasParams ? "," : "") +
+        "options?: Prettify<DiscourseExecOptions>";
+
       methodString += ")";
 
       let returnType = null;
@@ -204,8 +210,8 @@ const methods = [
           "']>('" +
           operationId +
           "'" +
-          (types.length || methodData.requestBody ? ", params" : "") +
-          ")" +
+          (hasParams ? ", params" : "") +
+          ", options)" +
           (returnType ? " as unknown as " + returnType : "") +
           ";\n",
       );

scripts/generate.ts

@@ -22,9 +22,18 @@ import _ajvErrors from "ajv-errors";
 import _ajvFormats from "ajv-formats";
 import type { OpenAPIV3_1 } from "openapi-types";
 
+import type { DiscourseExecOptions } from "./types.ts";
+export * from "./types.ts";
+
 import spec from "./openapi.json" with { type: "json" };
 import DiscourseAPIGenerated from "./generated.ts";
 
+const execOptionDefaults: DiscourseExecOptions = {
+  fetchOptions: {},
+  validateParams: true,
+  // validateResponse: true,
+};
+
 // Previously we imported this from ./generated.ts, but, exporting it
 // from there breaks the unwrapping.
 type Prettify<T> =
@@ -181,9 +190,21 @@ export class HTTPError extends Error {
     url: string,
     requestInit: RequestInit,
   ) {
+    const ri = {
+      ...requestInit,
+      headers: requestInit.headers instanceof Headers
+        ? Object.fromEntries(requestInit.headers.entries())
+        : requestInit.headers as
+          | Record<string, string | string[] | undefined>
+          | undefined,
+    };
+    if (ri.headers?.["api-key"]) {
+      ri.headers["api-key"] = ri.headers["api-key"].slice(0, 7) + "...";
+    }
+
     super(
       `An error occured calling "${operationName}" at ${url}\n` +
-        `RequestInit: ${JSON.stringify(requestInit)}\n` +
+        `RequestInit: ${JSON.stringify(ri)}\n` +
         `Returned HTTP ${status}: ${body}`,
     );
     this.status = status;
@@ -251,10 +272,13 @@ export default class DiscourseAPI extends DiscourseAPIGenerated {
   override async _exec<T>(
     operationName: string,
     params = {} as Record<string, string>,
+    options: DiscourseExecOptions = {},
   ): Promise<unknown> {
     const operation = byOperationId[operationName];
     if (!operation) throw new Error("Unknown operation: " + operationName);
 
+    const opts = { ...execOptionDefaults, ...options };
+
     // console.log(operationName, params);
 
     const header: { [key: string]: string } = {};
@@ -352,22 +376,40 @@ export default class DiscourseAPI extends DiscourseAPIGenerated {
 
     const additionalProperties = Object.keys(params);
     if (additionalProperties.length) {
-      throw new Error(
-        "Unknown parameter(s) for " +
-          operationName +
-          ": " +
-          additionalProperties.join(", "),
-      );
+      if (opts.validateParams) {
+        throw new Error(
+          "Unknown parameter(s) for " +
+            operationName +
+            ": " +
+            additionalProperties.join(", "),
+        );
+      } else {
+        if (formData) {
+          for (const key of additionalProperties) {
+            formData.append(key, params[key] as string | Blob);
+          }
+        } else if (contentType === "application/json") {
+          for (const key of additionalProperties) {
+            body[key] = params[key];
+          }
+        } else {
+          throw new Error(
+            "additionalProperties but not sure where to put them",
+          );
+        }
+      }
     }
 
-    const validate = getValidator(operationSchema(operation.data));
-    const valid = validate({ header, path, query, body });
-    if (!valid) {
-      const errors = validate.errors;
-      // console.log("errors", errors);
-      const message = ajv.errorsText(errors);
-      const error = new ParamaterValidationError(message, errors);
-      throw error;
+    if (opts.validateParams) {
+      const validate = getValidator(operationSchema(operation.data));
+      const valid = validate({ header, path, query, body });
+      if (!valid) {
+        const errors = validate.errors;
+        // console.log("errors", errors);
+        const message = ajv.errorsText(errors);
+        const error = new ParamaterValidationError(message, errors);
+        throw error;
+      }
     }
 
     // Do this after validation (of user headers)
@@ -396,6 +438,7 @@ export default class DiscourseAPI extends DiscourseAPIGenerated {
       method: operation.method,
       headers: new Headers(header),
       redirect: "manual",
+      ...opts.fetchOptions,
     };
 
     if (operation.data.requestBody && "content" in operation.data.requestBody) {
@@ -481,30 +524,33 @@ export default class DiscourseAPI extends DiscourseAPIGenerated {
         file?: File | Blob;
       }
     >,
+    options?: Prettify<DiscourseExecOptions>,
   ): Prettify<ReturnType<DiscourseAPIGenerated["createUpload"]>> {
     const file = params.file;
     if (file && !(file instanceof File || file instanceof Blob)) {
       throw new Error("file must be a File or Blob, not " + typeof file);
     }
 
     // @ts-expect-error: intentional break of types
-    return super.createUpload(params);
+    return super.createUpload(params, options);
   }
 
   override updateTopic(
     params: Parameters<DiscourseAPIGenerated["updateTopic"]>[0],
+    options?: Prettify<DiscourseExecOptions>,
   ): ReturnType<DiscourseAPIGenerated["updateTopic"]> {
     console.warn(
       "At time of writing, updateTopic() is broken on the discourse side, see https://meta.discourse.org/t/stumped-on-api-update-of-topic/145330.",
     );
-    return super.updateTopic(params);
+    return super.updateTopic(params, options);
   }
 
   override async getTopicByExternalId(
     params: Parameters<DiscourseAPIGenerated["getTopicByExternalId"]>[0],
+    options?: Prettify<DiscourseExecOptions>,
   ): ReturnType<DiscourseAPIGenerated["getTopic"]> {
     try {
-      await super.getTopicByExternalId(params);
+      await super.getTopicByExternalId(params, options);
     } catch (error) {
       if (error instanceof HTTPError && error.status === 301) {
         const location = error.response.headers.get("location");
@@ -525,6 +571,7 @@ export default class DiscourseAPI extends DiscourseAPIGenerated {
 
   override getSpecificPostsFromTopic(
     params: Parameters<DiscourseAPIGenerated["getSpecificPostsFromTopic"]>[0],
+    options?: Prettify<DiscourseExecOptions>,
   ): ReturnType<DiscourseAPIGenerated["getSpecificPostsFromTopic"]> {
     const operation = byOperationId.getSpecificPostsFromTopic.data;
 
@@ -555,7 +602,7 @@ export default class DiscourseAPI extends DiscourseAPIGenerated {
       delete operation.requestBody;
     }
 
-    return super.getSpecificPostsFromTopic(params);
+    return super.getSpecificPostsFromTopic(params, options);
   }
 
   /*

src/generated.ts

@@ -0,0 +1,5 @@
+export interface DiscourseExecOptions {
+  fetchOptions?: RequestInit;
+  validateParams?: boolean;
+  // validateResponse?: boolean;
+}

src/index.ts

@@ -3,6 +3,7 @@ import {
   describe,
   discourse,
   expect,
+  setNextCacheId,
   skipCacheOnce,
   test,
   useCache,
@@ -91,6 +92,36 @@ describe("users", () => {
     await discourse.deleteUser({ id: user.user.id });
   });
 
+  test("updateUser with custom fields", async () => {
+    setNextCacheId("updateUserCustom-1-createUser");
+    const createUserResult = await discourse.createUser({
+      name: "Test user to update",
+      email: "test-update@example.com",
+      password: "teSt1ngIsFuN",
+      username: "test-update-custom",
+      active: true,
+    });
+    expect(createUserResult).toMatchObject({ success: true });
+
+    setNextCacheId("updateUserCustom-2-updateUser");
+    const result = await discourse.updateUser({
+      username: "test-update-custom",
+      // @ts-expect-error: not in spec
+      title: "a new title",
+    }, { validateParams: false });
+    expect(result).toMatchObject({
+      success: "OK",
+      user: {
+        title: "a new title",
+      },
+    });
+
+    setNextCacheId("updateUserCustom-3-getUser");
+    const user = await discourse.getUser({ username: "test-update-custom" });
+    setNextCacheId("updateUserCustom-4-deleteUser");
+    await discourse.deleteUser({ id: user.user.id });
+  });
+
   test("getUserExternalId", async () => {
     /*
     const updateResult = await discourse.updateUser({

src/types.ts

@@ -0,0 +1,50 @@
+{
+  "request": {
+    "url": "http://localhost/users.json",
+    "method": "POST",
+    "bodyJson": {
+      "name": "Test user to update",
+      "email": "test-update@example.com",
+      "password": "teSt1ngIsFuN",
+      "username": "test-update-custom",
+      "active": true
+    },
+    "headers": {
+      "api-key": "eb2a2de8f93102c896aff8a55eec4672bdbd2be123f02c4900ad6d0f6483703b",
+      "api-username": "system",
+      "content-type": "application/json"
+    }
+  },
+  "response": {
+    "ok": true,
+    "status": 200,
+    "statusText": "OK",
+    "headers": {
+      "cache-control": "no-cache, no-store",
+      "connection": "keep-alive",
+      "content-type": "application/json; charset=utf-8",
+      "date": "Sat, 11 Oct 2025 11:48:34 GMT",
+      "referrer-policy": "strict-origin-when-cross-origin",
+      "server": "nginx",
+      "set-cookie": [
+        "_t=CI%2B0OHDxymX15daiQu8cZ%2BGJKN7vT%2BQ3WNME7AAp3dHsDhfBb0TFwRptkSVUGqSC8UG7J5XqdxTxfqNjboY1vOcZnZJRA2Uh5cr17PV4cEnyMeWdtYGSi%2BN%2BhXD9m%2BGLUYI%2FC2Ioy6pp%2FnbjvR%2F%2FCTl75dF3U1euQoTPj2AhHMJ0Q592OTaYkFwLIroCkxs6FhOQxihZIlOKONo9r9uewr%2FCD2FTG0%2Bkfpw%2BD9Q2QTpbRsYWHIhS0pHaz0qdFfdJV%2Fdvb9dJTMCX6gIcHfz6L1xS0jTq1oYupL9C5jfayPFrRaNONf1f9fRLVbtml4vwKGT0C2z9jNA%3D--mhqNB5x%2BBFzuv4nQ--VzaV2LzzllUSzCBI%2BEKTow%3D%3D; path=/; expires=Wed, 10 Dec 2025 11:48:34 GMT; HttpOnly; SameSite=Lax",
+        "_forum_session=eqDe2O2RkPpgl9ge2dqa12YoMr2PzOOylBMIwRGlnHWB%2FLLVVkDMeGmTBRHnz9EJPhS535Qe2iFdv9s2cdK716LENPoUfhtvitd4VwJM5bpQuyngagOqOlhk4Syt6ocFzJ4ZMdf832jehvXQ2eiB5aiYIUh5%2FZF99HXkQ6fXaRfaWsQYdijw6GlCtHBJy38midzpJiXZdKLShDn9YL8%2BqDXcnYaiRV%2BzRbposhr5chWxMnSo%2BidLFwwgkMbjasrMmK2MCHCB6kDUFbXjyKaoBAIpGNmnOGSmVeR9DYTYYJbgF5DQ8TZ%2BaRjWMsYxvRt6rryk6qXYz0AQlSUueKDWOlDuA53QoY84oP%2FPnDcfNijW0lWzS5h3fjXZANah%2F2fJ8G%2FpZUPIY9BHSs57l6jA4l5yp99I5uX9DADzvR89D7H9Lw%3D%3D--nt3X283MxcULdFue--mHmFyiPm0kGfDl7Z6dKokA%3D%3D; path=/; HttpOnly; SameSite=Lax"
+      ],
+      "transfer-encoding": "chunked",
+      "vary": "Accept-Encoding",
+      "x-content-type-options": "nosniff",
+      "x-discourse-route": "users/create",
+      "x-discourse-username": "system",
+      "x-frame-options": "SAMEORIGIN",
+      "x-permitted-cross-domain-policies": "none",
+      "x-request-id": "94206191-aac1-4781-bf0d-e97700770616",
+      "x-runtime": "0.421281",
+      "x-xss-protection": "0"
+    },
+    "bodyJson": {
+      "success": true,
+      "active": true,
+      "message": "Your account is activated and ready to use."
+    }
+  }
+}