@clickup/rest-client 2.10.294 → 2.11.0

package/docs/interfaces/TokenGetter.md

@@ -1,6 +1,6 @@
 [@clickup/rest-client](../README.md) / [Exports](../modules.md) / TokenGetter
 
-# Interface: TokenGetter<TData\>
+# Interface: TokenGetter\<TData\>
 
 A callback which returns access token, possibly after refreshing it, and also
 possibly before a retry on "invalid token" condition. I.e. it can be called
@@ -17,7 +17,7 @@ will be passed as a parameter).
 
 ### TokenGetter
 
-▸ **TokenGetter**(`prevError`): `Promise`<`TData`\>
+▸ **TokenGetter**(`prevError`): `Promise`\<`TData`\>
 
 #### Parameters
 
@@ -27,7 +27,7 @@ will be passed as a parameter).
 
 #### Returns
 
-`Promise`<`TData`\>
+`Promise`\<`TData`\>
 
 #### Defined in
 

package/docs/modules.md

@@ -15,8 +15,6 @@
 - [RestRetriableError](classes/RestRetriableError.md)
 - [RestTimeoutError](classes/RestTimeoutError.md)
 - [RestTokenInvalidError](classes/RestTokenInvalidError.md)
-- [PacerComposite](classes/PacerComposite.md)
-- [PacerQPS](classes/PacerQPS.md)
 
 ## Interfaces
 
@@ -24,16 +22,14 @@
 - [RestLogEvent](interfaces/RestLogEvent.md)
 - [Middleware](interfaces/Middleware.md)
 - [RestOptions](interfaces/RestOptions.md)
-- [PacerDelay](interfaces/PacerDelay.md)
 - [Pacer](interfaces/Pacer.md)
-- [PacerQPSBackend](interfaces/PacerQPSBackend.md)
-- [PacerQPSOptions](interfaces/PacerQPSOptions.md)
+- [PacerOutcome](interfaces/PacerOutcome.md)
 
 ## Functions
 
 ### depaginate
 
-▸ **depaginate**<`TItem`, `TCursor`\>(`readFunc`): `AsyncGenerator`<`TItem`, `void`, `undefined`\>
+▸ **depaginate**\<`TItem`, `TCursor`\>(`readFunc`): `AsyncGenerator`\<`TItem`, `void`, `undefined`\>
 
 Keeps calling a function with an updating cursor, and depaginates all the
 results until the cursor returned is null or undefined.
@@ -53,11 +49,11 @@ On each call, the inner function needs to return an array with two elements:
 
 | Name | Type |
 | :------ | :------ |
-| `readFunc` | (`cursor`: `undefined` \| `TCursor`) => `Promise`<readonly [`TItem`[], `undefined` \| ``null`` \| `TCursor`]\> |
+| `readFunc` | (`cursor`: `undefined` \| `TCursor`) => `Promise`\<readonly [`TItem`[], `undefined` \| ``null`` \| `TCursor`]\> |
 
 #### Returns
 
-`AsyncGenerator`<`TItem`, `void`, `undefined`\>
+`AsyncGenerator`\<`TItem`, `void`, `undefined`\>
 
 #### Defined in
 
@@ -67,7 +63,7 @@ ___
 
 ### paceRequests
 
-▸ **paceRequests**(`pacer`): [`Middleware`](interfaces/Middleware.md)
+▸ **paceRequests**(`pacer`, `delayMetric?`): [`Middleware`](interfaces/Middleware.md)
 
 Rest Client middleware that adds some delay between requests using one of
 Pacer implementations.
@@ -76,7 +72,8 @@ Pacer implementations.
 
 | Name | Type |
 | :------ | :------ |
-| `pacer` | ``null`` \| [`Pacer`](interfaces/Pacer.md) \| (`req`: [`RestRequest`](classes/RestRequest.md)<`any`\>) => `Promise`<``null`` \| [`Pacer`](interfaces/Pacer.md)\> |
+| `pacer` | ``null`` \| [`Pacer`](interfaces/Pacer.md) \| (`req`: [`RestRequest`](classes/RestRequest.md)\<`any`\>) => `Promise`\<``null`` \| [`Pacer`](interfaces/Pacer.md)\> |
+| `delayMetric?` | (`delay`: `number`, `reason`: `string`) => `void` |
 
 #### Returns
 
@@ -84,4 +81,4 @@ Pacer implementations.
 
 #### Defined in
 
-[src/middlewares/paceRequests.ts:11](https://github.com/clickup/rest-client/blob/master/src/middlewares/paceRequests.ts#L11)
+[src/middlewares/paceRequests.ts:33](https://github.com/clickup/rest-client/blob/master/src/middlewares/paceRequests.ts#L33)

package/internal/clean.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -e
+
+rm -rf dist yarn.lock package-lock.json pnpm-lock.yaml node_modules ./*.log

package/internal/deploy.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -e
+
+npm run build
+npm run lint
+npm run test
+npm publish --access=public

package/internal/docs.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -e
+
+rm -rf docs
+typedoc --plugin typedoc-plugin-markdown --plugin typedoc-plugin-merge-modules
+sed -i '' -E 's#packages/[^/]+/##g' $(find docs -type f -name '*.md')

package/internal/lint.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -e
+
+eslint . --ext .ts --cache --cache-location dist/.eslintcache

package/jest.config.base.js

@@ -0,0 +1,13 @@
+"use strict";
+module.exports = {
+  roots: ["<rootDir>/src"],
+  testMatch: ["**/*.test.ts"],
+  clearMocks: true,
+  restoreMocks: true,
+  ...(process.env.IN_JEST_PROJECT
+    ? {}
+    : { forceExit: true, testTimeout: 30000 }),
+  transform: {
+    "\\.ts$": "ts-jest",
+  },
+};

package/jest.config.js

@@ -1,11 +1,2 @@
 "use strict";
-module.exports = {
-  roots: ["<rootDir>/src"],
-  testMatch: ["**/*.test.ts"],
-  clearMocks: true,
-  restoreMocks: true,
-  ...(process.env.IN_JEST_PROJECT ? {} : { forceExit: true }),
-  transform: {
-    "\\.ts$": "ts-jest",
-  },
-};
+module.exports = { ...require("./jest.config.base") };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@clickup/rest-client",
   "description": "A syntax sugar tool around Node fetch() API, tailored to work with TypeScript and response validators",
-  "version": "2.10.294",
+  "version": "2.11.0",
   "license": "MIT",
   "keywords": [
     "rest-client",
@@ -24,18 +24,18 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch --preserveWatchOutput",
-    "lint": "eslint . --ext .ts --cache --cache-location dist/.eslintcache",
+    "lint": "bash internal/lint.sh",
     "test": "jest",
-    "docs": "rm -rf docs && typedoc --plugin typedoc-plugin-markdown --plugin typedoc-plugin-merge-modules && sed -i '' -E 's#packages/[^/]+/##g' $(find docs -type f -name '*.md')",
-    "clean": "rm -rf dist node_modules yarn.lock package-lock.json",
+    "docs": "bash internal/docs.sh",
+    "clean": "bash internal/clean.sh",
     "copy-package-to-public-dir": "copy-package-to-public-dir.sh",
     "backport-package-from-public-dir": "backport-package-from-public-dir.sh",
-    "deploy": "npm run build && npm run lint && npm run test && npm publish --access=public"
+    "deploy": "bash internal/deploy.sh"
   },
   "dependencies": {
     "abort-controller": "^3.0.0",
     "delay": "^4.4.1",
-    "fast-typescript-memoize": "^1.0.2",
+    "fast-typescript-memoize": "^1.1.1",
     "ipaddr.js": "^1.9.1",
     "lodash": "^4.17.21",
     "node-fetch": "^2.6.11",
@@ -45,11 +45,13 @@
     "@types/jest": "^29.5.5",
     "@types/lodash": "^4.14.175",
     "@types/node-fetch": "^2.6.4",
+    "@types/node": "^20.4.1",
     "@typescript-eslint/eslint-plugin": "^5.59.6",
     "@typescript-eslint/parser": "^5.59.6",
     "eslint-import-resolver-typescript": "^3.5.5",
     "eslint-plugin-import": "^2.27.5",
     "eslint-plugin-lodash": "^7.4.0",
+    "eslint-plugin-no-only-tests": "^3.1.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react": "^7.32.2",
@@ -57,6 +59,8 @@
     "eslint-plugin-typescript-sort-keys": "^2.3.0",
     "eslint-plugin-unused-imports": "^2.0.0",
     "eslint": "^8.40.0",
+    "jest": "^29.7.0",
+    "prettier": "3.2.1",
     "superstruct": "^1.0.3",
     "ts-jest": "^29.1.1",
     "typedoc-plugin-markdown": "^3.16.0",

package/src/RestClient.ts

@@ -54,7 +54,7 @@ export default class RestClient {
    */
   withMiddleware(
     middleware: RestOptions["middlewares"][0],
-    method: "unshift" | "push" = "push"
+    method: "unshift" | "push" = "push",
   ) {
     const clone = new RestClient(this._options);
     clone._options.middlewares[method](middleware);
@@ -156,7 +156,7 @@ export default class RestClient {
    */
   withOAuth1(
     consumer: { consumerKey: string; consumerSecret: string },
-    token: TokenGetter<{ token: string; tokenSecret: string }>
+    token: TokenGetter<{ token: string; tokenSecret: string }>,
   ) {
     const oauth = new OAuth1({
       consumer: { key: consumer.consumerKey, secret: consumer.consumerSecret },
@@ -176,7 +176,7 @@ export default class RestClient {
           oauth.authorize(requestData, {
             key: tokenData.token,
             secret: tokenData.tokenSecret,
-          })
+          }),
         );
         for (const [name, value] of Object.entries(addHeaders)) {
           req.headers.set(name, value);
@@ -196,7 +196,7 @@ export default class RestClient {
         const unencodedHeader = name + ":" + password;
         req.headers.set(
           "Authorization",
-          "Basic " + Buffer.from(unencodedHeader).toString("base64")
+          "Basic " + Buffer.from(unencodedHeader).toString("base64"),
         );
         return next(req);
       });
@@ -211,7 +211,7 @@ export default class RestClient {
   get(
     path: string,
     args: Partial<Record<string, string | number | string[]>> = {},
-    accept: string = "application/json"
+    accept: string = "application/json",
   ) {
     return this._noBodyRequest(path, args, "GET", accept);
   }
@@ -224,7 +224,7 @@ export default class RestClient {
     body: string | Buffer | NodeJS.ReadableStream,
     contentType: string,
     method: "POST" | "PUT" | "PATCH" = "POST",
-    accept?: string
+    accept?: string,
   ) {
     const origShape = simpleShape(path);
     return new RestRequest(
@@ -236,7 +236,7 @@ export default class RestClient {
         "Content-Type": contentType,
       }),
       body,
-      origShape
+      origShape,
     );
   }
 
@@ -247,7 +247,7 @@ export default class RestClient {
     path: string,
     body: any,
     method: "POST" | "PUT" | "PATCH" | "DELETE" = "POST",
-    accept: string = "application/json"
+    accept: string = "application/json",
   ) {
     const origShape = simpleShape(path, body);
     [path, body] = substituteParams(path, body);
@@ -260,7 +260,7 @@ export default class RestClient {
         "Content-Type": "application/json",
       }),
       JSON.stringify(body),
-      origShape
+      origShape,
     );
   }
 
@@ -271,7 +271,7 @@ export default class RestClient {
     path: string,
     body: Partial<Record<string, string>> | string,
     method: "POST" | "PUT" | "PATCH" = "POST",
-    accept: string = "application/json"
+    accept: string = "application/json",
   ) {
     const origShape = simpleShape(path, body);
     [path, body] = substituteParams(path, body);
@@ -286,9 +286,9 @@ export default class RestClient {
       typeof body === "string"
         ? body
         : new URLSearchParams(
-            omitBy(body, isUndefined) as Record<string, string>
+            omitBy(body, isUndefined) as Record<string, string>,
           ).toString(),
-      origShape
+      origShape,
     );
   }
 
@@ -298,7 +298,7 @@ export default class RestClient {
   writeDelete(
     path: string,
     args: Partial<Record<string, string>> = {},
-    accept: string = "application/json"
+    accept: string = "application/json",
   ) {
     return this._noBodyRequest(path, args, "DELETE", accept);
   }
@@ -355,14 +355,14 @@ export default class RestClient {
     mimeType: string,
     stream: AsyncIterable<Buffer>,
     method: "POST" | "PUT" = "POST",
-    chunkSize: number
+    chunkSize: number,
   ) {
     return new RestRangeUploader(
       this,
       chunkSize,
       method,
       path,
-      mimeType
+      mimeType,
     ).upload(stream);
   }
 
@@ -381,7 +381,7 @@ export default class RestClient {
       "",
       new Headers({ "Content-Type": "application/json" }),
       JSON.stringify({ variables, query }), // variables first - for truncation in logs,
-      origShape
+      origShape,
     );
   }
 
@@ -392,7 +392,7 @@ export default class RestClient {
     path: string,
     args: Partial<Record<string, string | number | string[]>> = {},
     method: "GET" | "DELETE",
-    accept: string = "application/json"
+    accept: string = "application/json",
   ) {
     const origShape = simpleShape(path, args);
     [path, args] = substituteParams(path, args);
@@ -418,7 +418,7 @@ export default class RestClient {
       path,
       new Headers({ Accept: accept }),
       "",
-      origShape
+      origShape,
     );
   }
 }
@@ -431,7 +431,7 @@ export default class RestClient {
  */
 export async function tokenRetryStrategy<TData>(
   token: TokenGetter<TData>,
-  body: (tokenData: TData) => Promise<RestResponse>
+  body: (tokenData: TData) => Promise<RestResponse>,
 ) {
   let tokenData = await token(null);
   try {
@@ -480,8 +480,8 @@ function simpleShape(path: string, args?: any) {
     args && typeof args === "object"
       ? Object.keys(args)
           // Filter out args that are already mentioned in the path, e.g.
-          // /pages/:pageID/blocks.
-          .filter((arg) => !argsInPath.includes(arg))
+          // /pages/:pageID/blocks. Also filter out undefined args.
+          .filter((arg) => !argsInPath.includes(arg) && args[arg] !== undefined)
           .sort()
           .join(",")
       : "";

package/src/RestOptions.ts

@@ -27,7 +27,7 @@ export interface RestLogEvent {
 export interface Middleware {
   (
     req: RestRequest,
-    next: (req: RestRequest) => Promise<RestResponse>
+    next: (req: RestRequest) => Promise<RestResponse>,
   ): Promise<RestResponse>;
 }
 
@@ -96,6 +96,8 @@ export default interface RestOptions {
   /** If true, non-public IP addresses are allowed too; otherwise, only unicast
    * addresses are allowed. */
   allowInternalIPs: boolean;
+  /** Overrides the default encoding heuristics for responses. */
+  responseEncoding: NodeJS.BufferEncoding | undefined;
   /** If true, logs request-response pairs to console. */
   isDebug: boolean;
   /** @ignore Holds HttpsAgent/HttpAgent instances; used internally only. */
@@ -140,7 +142,7 @@ export default interface RestOptions {
    * isRateLimitError and isRetriableError handlers set up, and they return
    * contradictory information; then isRateLimitError wins. */
   isRateLimitError: (
-    res: RestResponse
+    res: RestResponse,
   ) => "SOMETHING_ELSE" | "RATE_LIMIT" | "BEST_EFFORT" | number;
   /** Decides whether the response is a token-invalid error or not. In case it's
    * not, the response ought to be either success or some other error. */
@@ -154,7 +156,7 @@ export default interface RestOptions {
    * retry will happen in not less than this number of milliseconds. */
   isRetriableError: (
     res: RestResponse,
-    _error: any
+    _error: any,
   ) => "NEVER_RETRY" | "RETRY" | "BEST_EFFORT" | number;
 }
 
@@ -172,6 +174,7 @@ export const DEFAULT_OPTIONS: RestOptions = {
   throwIfResIsBigger: undefined,
   privateDataInResponse: false,
   allowInternalIPs: false,
+  responseEncoding: undefined,
   isDebug: false,
   agents: new Agents(),
   keepAlive: { timeoutMs: 10000 },

package/src/RestRequest.ts

@@ -33,7 +33,7 @@ export default class RestRequest<TAssertShape = any> {
     public url: string,
     public readonly headers: Headers,
     public readonly body: string | Buffer | NodeJS.ReadableStream,
-    public readonly shape?: string
+    public readonly shape?: string,
   ) {
     this.options = { ...options };
   }
@@ -120,7 +120,7 @@ export default class RestRequest<TAssertShape = any> {
       // By passing Number.MAX_SAFE_INTEGER to stream(), we ensure that the
       // entire data will be preloaded, or the loading will fail due to
       // throwIfResIsBigger limitation, whichever will happen faster.
-      Number.MAX_SAFE_INTEGER
+      Number.MAX_SAFE_INTEGER,
     );
     await stream.close();
     return stream.res;
@@ -182,7 +182,7 @@ export default class RestRequest<TAssertShape = any> {
               await reader?.close();
               throw e;
             }
-          }
+          },
         );
 
         // The only place where we return the response. Otherwise we retry or
@@ -215,7 +215,7 @@ export default class RestRequest<TAssertShape = any> {
           error,
           this.options,
           res,
-          retryDelayMs
+          retryDelayMs,
         );
         if (newRetryDelay === "no_retry") {
           throw error;
@@ -228,7 +228,7 @@ export default class RestRequest<TAssertShape = any> {
       retryDelayMs *= random(
         1 - this.options.retryDelayJitter,
         1 + this.options.retryDelayJitter,
-        true
+        true,
       );
       await this.options.heartbeater.delay(retryDelayMs);
 
@@ -279,7 +279,7 @@ export default class RestRequest<TAssertShape = any> {
       const isInternal = range !== "unicast";
       if (isInternal) {
         throw new RestError(
-          `Domain ${hostname} resolves to a non-public (${range}) IP address ${addr.address}`
+          `Domain ${hostname} resolves to a non-public (${range}) IP address ${addr.address}`,
         );
       }
 
@@ -333,7 +333,7 @@ export default class RestRequest<TAssertShape = any> {
       onTimeout: (reader) => {
         throw new RestTimeoutError(
           `Timed out while reading response body (${this.options.timeoutMs} ms)`,
-          this._createRestResponse(reader)!
+          this._createRestResponse(reader)!,
         );
       },
       onAfterRead: (reader) => {
@@ -343,10 +343,11 @@ export default class RestRequest<TAssertShape = any> {
         ) {
           throw new RestContentSizeOverLimitError(
             `Content size is over limit of ${this.options.throwIfResIsBigger} characters`,
-            this._createRestResponse(reader)!
+            this._createRestResponse(reader)!,
           );
         }
       },
+      responseEncoding: this.options.responseEncoding,
     });
   }
 
@@ -361,7 +362,7 @@ export default class RestRequest<TAssertShape = any> {
       reader.status,
       reader.headers,
       reader.textFetched,
-      reader.textIsPartial
+      reader.textIsPartial,
     );
   }
 
@@ -405,7 +406,7 @@ export default class RestRequest<TAssertShape = any> {
             inspectPossibleJSON(
               event.res.headers,
               event.res.text,
-              MAX_DEBUG_LEN
+              MAX_DEBUG_LEN,
             );
         }
       } else if (event.exception) {
@@ -430,7 +431,7 @@ export default class RestRequest<TAssertShape = any> {
 async function runMiddlewares(
   req: RestRequest,
   middlewares: RestOptions["middlewares"],
-  last: (req: RestRequest) => Promise<RestResponse>
+  last: (req: RestRequest) => Promise<RestResponse>,
 ): Promise<RestResponse> {
   if (middlewares.length > 0) {
     const [head, ...tail] = middlewares;

package/src/RestResponse.ts

@@ -21,7 +21,7 @@ export default class RestResponse {
     public readonly status: number,
     public readonly headers: Headers,
     public readonly text: string,
-    public readonly textIsPartial: boolean
+    public readonly textIsPartial: boolean,
   ) {}
 
   /**

package/src/RestStream.ts

@@ -18,7 +18,7 @@ export default class RestStream {
     public readonly res: RestResponse,
     readerIterable: {
       [Symbol.asyncIterator]: () => AsyncGenerator<string, void>;
-    }
+    },
   ) {
     this._generator = readerIterable[Symbol.asyncIterator]();
   }

package/src/__tests__/RestClient.test.ts

@@ -0,0 +1,53 @@
+import { RestClient } from "..";
+import substituteParams from "../internal/substituteParams";
+
+test("fetch_plain_url", async () => {
+  const client = new RestClient();
+  const res = await client.get("http://example.com", undefined, "*/*").text();
+  expect(res.length).toBeGreaterThan(10);
+});
+
+test("fetch_loopback_url_fails", async () => {
+  const client = new RestClient();
+  await expect(client.get("http://localhost/abc").response()).rejects.toThrow(
+    new RegExp(
+      "^Domain localhost resolves to a non-public \\(loopback\\) IP address (127\\.0\\.0\\.1)|(\\:\\:1)",
+    ),
+  );
+});
+
+test("fetch_private_url_fails", async () => {
+  const client = new RestClient();
+  await expect(client.get("http://10.0.0.1/abc").response()).rejects.toThrow(
+    "Domain 10.0.0.1 resolves to a non-public (private) IP address 10.0.0.1",
+  );
+});
+
+test("fetch_url_with_redirect_fails", async () => {
+  const client = new RestClient();
+  await expect(client.get("http://google.com").response()).rejects.toThrow(
+    /redirect mode is set to error:/,
+  );
+});
+
+test("fetch_relative_url_fails", async () => {
+  const client = new RestClient();
+  await expect(client.get("/test").text()).rejects.toThrow(/Invalid URL/);
+  await expect(client.get("zzz").text()).rejects.toThrow(/Invalid URL/);
+});
+
+test("substituteParams", async () => {
+  const body = { aa: "aaa", b: 42, x: "y" };
+  expect(substituteParams("/some/:aa/other/:b/ccc/:ddd/eee", body)).toEqual([
+    "/some/aaa/other/42/ccc/:ddd/eee",
+    { x: "y" },
+  ]);
+  expect(body).toEqual({ aa: "aaa", b: 42, x: "y" });
+});
+
+test("withOptions ignores undefined", async () => {
+  const request = new RestClient({ timeoutMs: 1234 })
+    .withOptions({ timeoutMs: undefined })
+    .writeJson("/", "");
+  expect(request.options.timeoutMs).toEqual(1234);
+});