@novu/api 0.0.1-alpha.99 → 0.0.2

package/README.md

@@ -135,9 +135,7 @@ async function run() {
       },
       {
         name: "workflow_identifier",
-        to: [
-          "SUBSCRIBER_ID",
-        ],
+        to: [],
       },
       {
         name: "workflow_identifier",
@@ -218,6 +216,11 @@ run();
 <details open>
 <summary>Available methods</summary>
 
+### [admin](docs/sdks/admin/README.md)
+
+* [healthControllerHealthCheck](docs/sdks/admin/README.md#healthcontrollerhealthcheck)
+* [testIdempotency](docs/sdks/admin/README.md#testidempotency)
+
 ### [integrations](docs/sdks/integrations/README.md)
 
 * [list](docs/sdks/integrations/README.md#list) - Get integrations
@@ -299,7 +302,7 @@ run();
 ### [topics](docs/sdks/topics/README.md)
 
 * [create](docs/sdks/topics/README.md#create) - Topic creation
-* [list](docs/sdks/topics/README.md#list) - Filter topics
+* [list](docs/sdks/topics/README.md#list) - Get topic list filtered 
 * [delete](docs/sdks/topics/README.md#delete) - Delete topic
 * [retrieve](docs/sdks/topics/README.md#retrieve) - Get topic
 * [rename](docs/sdks/topics/README.md#rename) - Rename a topic
@@ -328,6 +331,8 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 
 <summary>Available standalone functions</summary>
 
+- [`adminHealthControllerHealthCheck`](docs/sdks/admin/README.md#healthcontrollerhealthcheck)
+- [`adminTestIdempotency`](docs/sdks/admin/README.md#testidempotency)
 - [`cancel`](docs/sdks/novu/README.md#cancel) - Cancel triggered event
 - [`integrationsCreate`](docs/sdks/integrations/README.md#create) - Create integration
 - [`integrationsDelete`](docs/sdks/integrations/README.md#delete) - Delete integration
@@ -366,7 +371,7 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`subscribersUpdate`](docs/sdks/subscribers/README.md#update) - Update subscriber
 - [`topicsCreate`](docs/sdks/topics/README.md#create) - Topic creation
 - [`topicsDelete`](docs/sdks/topics/README.md#delete) - Delete topic
-- [`topicsList`](docs/sdks/topics/README.md#list) - Filter topics
+- [`topicsList`](docs/sdks/topics/README.md#list) - Get topic list filtered 
 - [`topicsRename`](docs/sdks/topics/README.md#rename) - Rename a topic
 - [`topicsRetrieve`](docs/sdks/topics/README.md#retrieve) - Get topic
 - [`topicsSubscribersAssign`](docs/sdks/novusubscribers/README.md#assign) - Subscribers addition
@@ -415,28 +420,25 @@ run();
 <!-- Start Error Handling [errors] -->
 ## Error Handling
 
-All SDK methods return a response object or throw an error. By default, an API error will throw a `errors.SDKError`.
-
-If a HTTP request fails, an operation my also throw an error from the `models/errors/httpclienterrors.ts` module:
-
-| HTTP Client Error                                    | Description                                          |
-| ---------------------------------------------------- | ---------------------------------------------------- |
-| RequestAbortedError                                  | HTTP request was aborted by the client               |
-| RequestTimeoutError                                  | HTTP request timed out due to an AbortSignal signal  |
-| ConnectionError                                      | HTTP client was unable to make a request to a server |
-| InvalidRequestError                                  | Any input used to create a request is invalid        |
-| UnexpectedClientError                                | Unrecognised or unexpected error                     |
+Some methods specify known errors which can be thrown. All the known errors are enumerated in the `models/errors/errors.ts` module. The known errors for a method are documented under the *Errors* tables in SDK docs. For example, the `trigger` method may throw the following errors:
 
-In addition, when custom error responses are specified for an operation, the SDK may throw their associated Error type. You can refer to respective *Errors* tables in SDK docs for more details on possible error types for each operation. For example, the `trigger` method may throw the following errors:
+| Error Type                | Status Code                            | Content Type     |
+| ------------------------- | -------------------------------------- | ---------------- |
+| errors.ErrorDto           | 400, 401, 403, 404, 405, 409, 413, 415 | application/json |
+| errors.ErrorDto           | 414                                    | application/json |
+| errors.ValidationErrorDto | 422                                    | application/json |
+| errors.ErrorDto           | 500                                    | application/json |
+| errors.SDKError           | 4XX, 5XX                               | \*/\*            |
 
-| Error Type      | Status Code | Content Type     |
-| --------------- | ----------- | ---------------- |
-| errors.ErrorDto | 400, 404    | application/json |
-| errors.SDKError | 4XX, 5XX    | \*/\*            |
+If the method throws an error and it is not captured by the known errors, it will default to throwing a `SDKError`.
 
 ```typescript
 import { Novu } from "@novu/api";
-import { ErrorDto, SDKValidationError } from "@novu/api/models/errors";
+import {
+  ErrorDto,
+  SDKValidationError,
+  ValidationErrorDto,
+} from "@novu/api/models/errors";
 
 const novu = new Novu({
   apiKey: "<YOUR_API_KEY_HERE>",
@@ -463,8 +465,9 @@ async function run() {
     console.log(result);
   } catch (err) {
     switch (true) {
+      // The server response does not match the expected SDK schema
       case (err instanceof SDKValidationError): {
-        // Validation errors can be pretty-printed
+        // Pretty-print will provide a human-readable multi-line error message
         console.error(err.pretty());
         // Raw value may also be inspected
         console.error(err.rawValue);
@@ -475,7 +478,23 @@ async function run() {
         console.error(err);
         return;
       }
+      case (err instanceof ErrorDto): {
+        // Handle err.data$: ErrorDtoData
+        console.error(err);
+        return;
+      }
+      case (err instanceof ValidationErrorDto): {
+        // Handle err.data$: ValidationErrorDtoData
+        console.error(err);
+        return;
+      }
+      case (err instanceof ErrorDto): {
+        // Handle err.data$: ErrorDtoData
+        console.error(err);
+        return;
+      }
       default: {
+        // Other errors such as network errors, see HTTPClientErrors for more details
         throw err;
       }
     }
@@ -486,7 +505,17 @@ run();
 
 ```
 
-Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The `SDKValidationError` that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.
+Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The `SDKValidationError` that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted multi-line string since validation errors can list many issues and the plain error string may be difficult read when debugging.
+
+In some rare cases, the SDK can fail to get a response from the server or even make the request due to unexpected circumstances such as network conditions. These types of errors are captured in the `models/errors/httpclienterrors.ts` module:
+
+| HTTP Client Error                                    | Description                                          |
+| ---------------------------------------------------- | ---------------------------------------------------- |
+| RequestAbortedError                                  | HTTP request was aborted by the client               |
+| RequestTimeoutError                                  | HTTP request timed out due to an AbortSignal signal  |
+| ConnectionError                                      | HTTP client was unable to make a request to a server |
+| InvalidRequestError                                  | Any input used to create a request is invalid        |
+| UnexpectedClientError                                | Unrecognised or unexpected error                     |
 <!-- End Error Handling [errors] -->
 
 <!-- Start Server Selection [server] -->

package/RUNTIMES.md

@@ -1,6 +1,6 @@
 # Supported JavaScript runtimes
 
-This SDK is intended to be used in JavaScript runtimes that support the following features:
+This SDK is intended to be used in JavaScript runtimes that support ECMAScript 2020 or newer. The SDK uses the following features:
 
 * [Web Fetch API][web-fetch]
 * [Web Streams API][web-streams] and in particular `ReadableStream`
@@ -20,3 +20,29 @@ Runtime environments that are explicitly supported are:
   - Note that Deno does not currently have native support for streaming file uploads backed by the filesystem ([issue link][deno-file-streaming])
 
 [deno-file-streaming]: https://github.com/denoland/deno/issues/11018
+
+## Recommended TypeScript compiler options
+
+The following `tsconfig.json` options are recommended for projects using this
+SDK in order to get static type support for features like async iterables,
+streams and `fetch`-related APIs ([`for await...of`][for-await-of], 
+[`AbortSignal`][abort-signal], [`Request`][request], [`Response`][response] and
+so on):
+
+[for-await-of]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
+[abort-signal]: https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
+[request]: https://developer.mozilla.org/en-US/docs/Web/API/Request
+[response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "es2020", // or higher
+    "lib": ["es2020", "dom", "dom.iterable"],
+  }
+}
+```
+
+While `target` can be set to older ECMAScript versions, it may result in extra,
+unnecessary compatibility code being generated if you are not targeting old
+runtimes.