@clickup/rest-client 2.10.292

package/docs/interfaces/RestLogEvent.md

@@ -0,0 +1,95 @@
+[@clickup/rest-client](../README.md) / [Exports](../modules.md) / RestLogEvent
+
+# Interface: RestLogEvent
+
+An event which is passed to an external logger (see RestOptions).
+
+## Properties
+
+### attempt
+
+• **attempt**: `number`
+
+#### Defined in
+
+[src/RestOptions.ts:12](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L12)
+
+___
+
+### req
+
+• **req**: [`RestRequest`](../classes/RestRequest.md)<`any`\>
+
+#### Defined in
+
+[src/RestOptions.ts:13](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L13)
+
+___
+
+### res
+
+• **res**: ``null`` \| [`RestResponse`](../classes/RestResponse.md) \| ``"backoff_delay"``
+
+#### Defined in
+
+[src/RestOptions.ts:14](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L14)
+
+___
+
+### exception
+
+• **exception**: `any`
+
+#### Defined in
+
+[src/RestOptions.ts:15](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L15)
+
+___
+
+### timestamp
+
+• **timestamp**: `number`
+
+#### Defined in
+
+[src/RestOptions.ts:16](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L16)
+
+___
+
+### elapsed
+
+• **elapsed**: `number`
+
+#### Defined in
+
+[src/RestOptions.ts:17](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L17)
+
+___
+
+### isFinalAttempt
+
+• **isFinalAttempt**: `boolean`
+
+#### Defined in
+
+[src/RestOptions.ts:18](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L18)
+
+___
+
+### privateDataInResponse
+
+• **privateDataInResponse**: `boolean`
+
+#### Defined in
+
+[src/RestOptions.ts:19](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L19)
+
+___
+
+### comment
+
+• **comment**: `string`
+
+#### Defined in
+
+[src/RestOptions.ts:20](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L20)

package/docs/interfaces/RestOptions.md

@@ -0,0 +1,351 @@
+[@clickup/rest-client](../README.md) / [Exports](../modules.md) / RestOptions
+
+# Interface: RestOptions
+
+Options passed to RestClient. More options can be added by cloning an
+instance of RestClient, withOption() method.
+
+## Properties
+
+### retries
+
+• **retries**: `number`
+
+Max number of retries. Default is 0, because some requests are from the
+web app, and we don't want to retry them.
+
+#### Defined in
+
+[src/RestOptions.ts:69](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L69)
+
+___
+
+### retryDelayFirstMs
+
+• **retryDelayFirstMs**: `number`
+
+How much time to wait by default on the 1st retry attempt.
+
+#### Defined in
+
+[src/RestOptions.ts:71](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L71)
+
+___
+
+### retryDelayFactor
+
+• **retryDelayFactor**: `number`
+
+How much to increase the retry delay on each retry.
+
+#### Defined in
+
+[src/RestOptions.ts:73](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L73)
+
+___
+
+### retryDelayJitter
+
+• **retryDelayJitter**: `number`
+
+Use this fraction (random) of the current retry delay to jitter both ways
+(e.g. 0.1 means 90%...110% of the delay to be actually applied).
+
+#### Defined in
+
+[src/RestOptions.ts:76](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L76)
+
+___
+
+### retryDelayMaxMs
+
+• **retryDelayMaxMs**: `number`
+
+Maximum delay between each retry.
+
+#### Defined in
+
+[src/RestOptions.ts:78](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L78)
+
+___
+
+### heartbeater
+
+• **heartbeater**: `Object`
+
+A logic which runs on different IO stages (delay and heartbeats).
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `heartbeat` | () => `Promise`<`void`\> |
+| `delay` | (`ms`: `number`) => `Promise`<`void`\> |
+
+#### Defined in
+
+[src/RestOptions.ts:80](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L80)
+
+___
+
+### throwIfResIsBigger
+
+• **throwIfResIsBigger**: `undefined` \| `number`
+
+Allows to limit huge requests and throw instead.
+
+#### Defined in
+
+[src/RestOptions.ts:91](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L91)
+
+___
+
+### privateDataInResponse
+
+• **privateDataInResponse**: `boolean`
+
+Passed to the logger which may decide, should it log details of the
+response or not.
+
+#### Defined in
+
+[src/RestOptions.ts:94](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L94)
+
+___
+
+### allowInternalIPs
+
+• **allowInternalIPs**: `boolean`
+
+If true, non-public IP addresses are allowed too; otherwise, only unicast
+addresses are allowed.
+
+#### Defined in
+
+[src/RestOptions.ts:97](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L97)
+
+___
+
+### isDebug
+
+• **isDebug**: `boolean`
+
+If true, logs request-response pairs to console.
+
+#### Defined in
+
+[src/RestOptions.ts:99](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L99)
+
+___
+
+### keepAlive
+
+• **keepAlive**: `Object`
+
+Sets Keep-Alive parameters (persistent connections).
+
+#### Type declaration
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `timeout` | `number` | A hint to the server, how much time to keep the connection alive. Not all the servers respect it though (e.g. nginx and express do not). |
+| `max` | `number` | How many requests are allowed to be processed in one connection. |
+| `maxSockets?` | `number` | How many sockets at maximum will be kept open. |
+
+#### Defined in
+
+[src/RestOptions.ts:103](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L103)
+
+___
+
+### family
+
+• **family**: ``0`` \| ``4`` \| ``6``
+
+When resolving DNS, use IPv4, IPv6 or both (see dns.lookup() docs).
+
+#### Defined in
+
+[src/RestOptions.ts:113](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L113)
+
+___
+
+### timeoutMs
+
+• **timeoutMs**: `number`
+
+Max timeout to wait for a response.
+
+#### Defined in
+
+[src/RestOptions.ts:115](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L115)
+
+___
+
+### logger
+
+• **logger**: (`event`: [`RestLogEvent`](RestLogEvent.md)) => `void`
+
+#### Type declaration
+
+▸ (`event`): `void`
+
+Logger to be used for each responses (including retried) plus for backoff
+delay events logging.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `event` | [`RestLogEvent`](RestLogEvent.md) |
+
+##### Returns
+
+`void`
+
+#### Defined in
+
+[src/RestOptions.ts:118](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L118)
+
+___
+
+### middlewares
+
+• **middlewares**: [`Middleware`](Middleware.md)[]
+
+Middlewares to wrap requests. May alter both request and response.
+
+#### Defined in
+
+[src/RestOptions.ts:120](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L120)
+
+___
+
+### isSuccessResponse
+
+• **isSuccessResponse**: (`res`: [`RestResponse`](../classes/RestResponse.md)) => ``"SUCCESS"`` \| ``"THROW"`` \| ``"BEST_EFFORT"``
+
+#### Type declaration
+
+▸ (`res`): ``"SUCCESS"`` \| ``"THROW"`` \| ``"BEST_EFFORT"``
+
+If set, makes decision whether the response is successful or not. The
+response will either be returned to the client, or an error will be thrown.
+This allows to treat some non-successful HTTP statuses as success if the
+remote API is that weird. Return values:
+* "SUCCESS" - the request will be considered successful, no further checks
+  will be performed;
+* "BEST_EFFORT" - inconclusive, the request may be either successful or
+  unsuccessful, additional tests (e.g. will check HTTP status code) will be
+  performed;
+* "THROW" - the request resulted in error. Additional tests will be
+  performed to determine is the error is retriable, is OAuth token good,
+  and etc.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `res` | [`RestResponse`](../classes/RestResponse.md) |
+
+##### Returns
+
+``"SUCCESS"`` \| ``"THROW"`` \| ``"BEST_EFFORT"``
+
+#### Defined in
+
+[src/RestOptions.ts:134](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L134)
+
+___
+
+### isRateLimitError
+
+• **isRateLimitError**: (`res`: [`RestResponse`](../classes/RestResponse.md)) => `number` \| ``"BEST_EFFORT"`` \| ``"SOMETHING_ELSE"`` \| ``"RATE_LIMIT"``
+
+#### Type declaration
+
+▸ (`res`): `number` \| ``"BEST_EFFORT"`` \| ``"SOMETHING_ELSE"`` \| ``"RATE_LIMIT"``
+
+Decides whether the response is a rate-limit error or not. Returning
+non-zero value is treated as retry delay (if retries are set up). In case
+the returned value is "SOMETHING_ELSE", the response ought to be either
+success or some other error. Returning "BEST_EFFORT" turns on built-in
+heuristic (e.g. relying on HTTP status code and Retry-After header). In
+case we've made a decision that it's a rate limited error, the request is
+always retried; this covers a very common case when we have both
+isRateLimitError and isRetriableError handlers set up, and they return
+contradictory information; then isRateLimitError wins.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `res` | [`RestResponse`](../classes/RestResponse.md) |
+
+##### Returns
+
+`number` \| ``"BEST_EFFORT"`` \| ``"SOMETHING_ELSE"`` \| ``"RATE_LIMIT"``
+
+#### Defined in
+
+[src/RestOptions.ts:144](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L144)
+
+___
+
+### isTokenInvalidError
+
+• **isTokenInvalidError**: (`res`: [`RestResponse`](../classes/RestResponse.md)) => `boolean`
+
+#### Type declaration
+
+▸ (`res`): `boolean`
+
+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.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `res` | [`RestResponse`](../classes/RestResponse.md) |
+
+##### Returns
+
+`boolean`
+
+#### Defined in
+
+[src/RestOptions.ts:149](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L149)
+
+___
+
+### isRetriableError
+
+• **isRetriableError**: (`res`: [`RestResponse`](../classes/RestResponse.md), `_error`: `any`) => `number` \| ``"BEST_EFFORT"`` \| ``"NEVER_RETRY"`` \| ``"RETRY"``
+
+#### Type declaration
+
+▸ (`res`, `_error`): `number` \| ``"BEST_EFFORT"`` \| ``"NEVER_RETRY"`` \| ``"RETRY"``
+
+Called only if we haven't decided earlier that it's a rate limit error.
+Decides whether the response is a retriable error or not. In case the
+returned value is "NEVER_RETRY", the response ought to be either success or
+some other error, but it's guaranteed that the request won't be retried.
+Returning "BEST_EFFORT" turns on built-in heuristics (e.g. never retry "not
+found" errors). Returning a number is treated as "RETRY", and the next
+retry will happen in not less than this number of milliseconds.
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `res` | [`RestResponse`](../classes/RestResponse.md) |
+| `_error` | `any` |
+
+##### Returns
+
+`number` \| ``"BEST_EFFORT"`` \| ``"NEVER_RETRY"`` \| ``"RETRY"``
+
+#### Defined in
+
+[src/RestOptions.ts:157](https://github.com/clickup/rest-client/blob/master/src/RestOptions.ts#L157)

package/docs/interfaces/TokenGetter.md

@@ -0,0 +1,34 @@
+[@clickup/rest-client](../README.md) / [Exports](../modules.md) / TokenGetter
+
+# 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
+once or twice (the 2nd time after the previous request error, and that error
+will be passed as a parameter).
+
+## Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `TData` | `string` |
+
+## Callable
+
+### TokenGetter
+
+▸ **TokenGetter**(`prevError`): `Promise`<`TData`\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `prevError` | ``null`` \| `Error` |
+
+#### Returns
+
+`Promise`<`TData`\>
+
+#### Defined in
+
+[src/RestClient.ts:21](https://github.com/clickup/rest-client/blob/master/src/RestClient.ts#L21)

package/docs/modules.md

@@ -0,0 +1,87 @@
+[@clickup/rest-client](README.md) / Exports
+
+# @clickup/rest-client
+
+## Classes
+
+- [RestClient](classes/RestClient.md)
+- [RestRequest](classes/RestRequest.md)
+- [RestResponse](classes/RestResponse.md)
+- [RestStream](classes/RestStream.md)
+- [RestContentSizeOverLimitError](classes/RestContentSizeOverLimitError.md)
+- [RestError](classes/RestError.md)
+- [RestRateLimitError](classes/RestRateLimitError.md)
+- [RestResponseError](classes/RestResponseError.md)
+- [RestRetriableError](classes/RestRetriableError.md)
+- [RestTimeoutError](classes/RestTimeoutError.md)
+- [RestTokenInvalidError](classes/RestTokenInvalidError.md)
+- [PacerComposite](classes/PacerComposite.md)
+- [PacerQPS](classes/PacerQPS.md)
+
+## Interfaces
+
+- [TokenGetter](interfaces/TokenGetter.md)
+- [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)
+
+## Functions
+
+### depaginate
+
+▸ **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.
+
+On each call, the inner function needs to return an array with two elements:
+1. Array or results, which could be empty, but not null or undefined.
+2. A new cursor.
+
+#### Type parameters
+
+| Name | Type |
+| :------ | :------ |
+| `TItem` | `TItem` |
+| `TCursor` | `string` |
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `readFunc` | (`cursor`: `undefined` \| `TCursor`) => `Promise`<[`TItem`[], `undefined` \| ``null`` \| `TCursor`]\> |
+
+#### Returns
+
+`AsyncGenerator`<`TItem`, `void`, `undefined`\>
+
+#### Defined in
+
+[src/helpers/depaginate.ts:9](https://github.com/clickup/rest-client/blob/master/src/helpers/depaginate.ts#L9)
+
+___
+
+### paceRequests
+
+▸ **paceRequests**(`pacer`): [`Middleware`](interfaces/Middleware.md)
+
+Rest Client middleware that adds some delay between requests using one of
+Pacer implementations.
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `pacer` | ``null`` \| [`Pacer`](interfaces/Pacer.md) \| (`req`: [`RestRequest`](classes/RestRequest.md)<`any`\>) => `Promise`<``null`` \| [`Pacer`](interfaces/Pacer.md)\> |
+
+#### Returns
+
+[`Middleware`](interfaces/Middleware.md)
+
+#### Defined in
+
+[src/middlewares/paceRequests.ts:11](https://github.com/clickup/rest-client/blob/master/src/middlewares/paceRequests.ts#L11)

package/jest.config.js

@@ -0,0 +1,8 @@
+"use strict";
+module.exports = {
+  roots: ["<rootDir>/src"],
+  testMatch: ["**/*.test.ts"],
+  transform: {
+    "\\.ts$": "ts-jest",
+  },
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@clickup/rest-client",
+  "description": "A syntax sugar tool around Node fetch() API, tailored to work with TypeScript and response validators",
+  "version": "2.10.292",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint . --ext .ts --cache --cache-location dist/.eslintcache",
+    "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",
+    "copy-package-to-public-dir": "copy-package-to-public-dir.sh",
+    "deploy": "npm run build && npm test && npm publish --access=public"
+  },
+  "dependencies": {
+    "abort-controller": "^3.0.0",
+    "delay": "^4.4.1",
+    "fast-typescript-memoize": "^1.0.2",
+    "ipaddr.js": "^1.9.1",
+    "lodash": "^4.17.21",
+    "node-fetch": "^2.6.11",
+    "oauth-1.0a": "^2.2.6"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.5",
+    "@types/lodash": "^4.14.175",
+    "@types/node-fetch": "^2.6.4",
+    "superstruct": "^0.15.3",
+    "ts-jest": "^29.1.1",
+    "typedoc": "^0.25.2",
+    "typedoc-plugin-markdown": "^3.16.0",
+    "typedoc-plugin-merge-modules": "^5.1.0",
+    "typescript": "^5.2.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/clickup/rest-client"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "include": [
+    "src/**/*"
+  ],
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "declarationMap": true,
+    "disableReferencedProjectLoad": true,
+    "disableSourceOfProjectReferenceRedirect": true,
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "incremental": true,
+    "lib": [
+      "es2019"
+    ],
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "noEmitOnError": true,
+    "noErrorTruncation": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "outDir": "dist",
+    "pretty": true,
+    "removeComments": false,
+    "resolveJsonModule": true,
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2019",
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo",
+    "types": [
+      "node",
+      "jest"
+    ],
+  }
+}

package/typedoc.json

@@ -0,0 +1,17 @@
+{
+  "entryPoints": ["src"],
+  "exclude": ["src/internal/**", "src/__tests__/**", "**/node-fetch/**", "**/node_modules/**"],
+  "entryPointStrategy": "expand",
+  "mergeModulesMergeMode": "project",
+  "sort": ["source-order"],
+  "out": "docs",
+  "logLevel": "Warn",
+  "hideGenerator": true,
+  "excludeInternal": true,
+  "excludePrivate": true,
+  "categorizeByGroup": true,
+  "hideInPageTOC": true,
+  "gitRevision": "master",
+  "sourceLinkTemplate": "https://github.com/clickup/rest-client/blob/master/{path}#L{line}",
+  "basePath": "."
+}