fix(js-client): add type definitions for operation method opts argu…

…ment (#6021)

* fix(js-client): handle type definitions for requestBody

Handling type definitions for requestBody in API schema while still
taking into consideration optional / void params if all path, query, and
requestBody keys are optional.

* fix(js-client): add types for request body json and octet stream

- combined the request body type with the Params type
- handle cases where request body properties are optional
- handle cases where all params and request body are optional
- allow 'application/json' body to be a JSON object or a function
returning one
- allow 'application/octet-stream' body to be a Node.js ReadStream or a
function returning one
- simplify by extracting repetitive logic to helper types like
`IsParamsOrRequestBodyRequired` and `IsRequestBodyOptional` etc.

* refactor(js-client): rename RequestBodyDecorator to DetailedRequestBody for clarity

These types are responsible for adding detailed annotations to the
`body` parameter of API methods, such as describing its usage and
examples for `application/json` and `application/octet-stream`. The new
names make their purpose more explicit and improve readability for
future maintenance and usage.

* fix(js-client): add method opts type definition

All dynamic operation methods can have a second arg `opts` to pass any
additional properties to `node-fetch` RequestInit. This adds the type
definition for the `opts` argument.

* fix(js-client): remove export for type OperationParams

added this export by accident, just removing it

packages/js-client/src/types.ts

@@ -1,6 +1,7 @@
 import type { ReadStream } from 'node:fs'
 
 import type { operations } from '@netlify/open-api'
+import type { RequestInit } from 'node-fetch'
 
 /**
  * Determines whether all keys in T are optional.
@@ -182,7 +183,7 @@ type CombinedParamsAndRequestBody<K extends keyof operations> =
 
 type OperationParams<K extends keyof operations> =
   IsParamsOrRequestBodyRequired<K> extends false
-    ? CombinedParamsAndRequestBody<K> | void
+    ? CombinedParamsAndRequestBody<K> | void | undefined
     : CombinedParamsAndRequestBody<K>
 
 type SuccessHttpStatusCodes = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226
@@ -202,5 +203,31 @@ type OperationResponse<K extends keyof operations> = 'responses' extends keyof o
   : never
 
 export type DynamicMethods = {
-  [K in keyof operations]: (params: OperationParams<K>) => Promise<OperationResponse<K>>
+  [K in keyof operations]: (
+    params: OperationParams<K>,
+    /**
+     * Any properties you want passed to `node-fetch`.
+     *
+     * The `headers` property is merged with some `defaultHeaders`:
+     * ```ts
+     * {
+     *  'User-agent': 'netlify-js-client',
+     *  'accept': 'application/json',
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * const site = await client.getSite(
+     *  { site_id: 'YOUR_SITE_ID' },
+     *  {
+     *    headers: {
+     *      'X-Example-Header': 'Example Value',
+     *    },
+     *  },
+     * )
+     * ```
+     */
+    opts?: RequestInit | void | undefined,
+  ) => Promise<OperationResponse<K>>
 }