@novu/api 1.2.0 → 1.4.0

package/FUNCTIONS.md

@@ -21,7 +21,6 @@ specific category of applications.
 ```typescript
 import { NovuCore } from "@novu/api/core.js";
 import { trigger } from "@novu/api/funcs/trigger.js";
-import { SDKValidationError } from "@novu/api/models/errors/sdkvalidationerror.js";
 
 // Use `NovuCore` for best tree-shaking performance.
 // You can create one instance of it to use across an application.
@@ -41,28 +40,12 @@ async function run() {
     overrides: {},
     to: "SUBSCRIBER_ID",
   });
-
-  switch (true) {
-    case res.ok:
-      // The success case will be handled outside of the switch block
-      break;
-    case res.error instanceof SDKValidationError:
-      // Pretty-print validation errors.
-      return console.log(res.error.pretty());
-    case res.error instanceof Error:
-      return console.log(res.error);
-    default:
-      // TypeScript's type checking will fail on the following line if the above
-      // cases were not exhaustive.
-      res.error satisfies never;
-      throw new Error("Assertion failed: expected error checks to be exhaustive: " + res.error);
+  if (res.ok) {
+    const { value: result } = res;
+    console.log(result);
+  } else {
+    console.log("trigger failed:", res.error);
   }
-
-
-  const { value: result } = res;
-
-  // Handle the result
-  console.log(result);
 }
 
 run();

package/README.md

@@ -206,7 +206,6 @@ async function run() {
     to: "SUBSCRIBER_ID",
   });
 
-  // Handle the result
   console.log(result);
 }
 
@@ -226,7 +225,6 @@ const novu = new Novu({
 async function run() {
   const result = await novu.cancel("<id>");
 
-  // Handle the result
   console.log(result);
 }
 
@@ -263,7 +261,6 @@ async function run() {
     },
   });
 
-  // Handle the result
   console.log(result);
 }
 
@@ -319,7 +316,6 @@ async function run() {
     ],
   });
 
-  // Handle the result
   console.log(result);
 }
 
@@ -334,6 +330,13 @@ run();
 <details open>
 <summary>Available methods</summary>
 
+### [environments](docs/sdks/environments/README.md)
+
+* [create](docs/sdks/environments/README.md#create) - Create an environment
+* [list](docs/sdks/environments/README.md#list) - List all environments
+* [update](docs/sdks/environments/README.md#update) - Update an environment
+* [delete](docs/sdks/environments/README.md#delete) - Delete an environment
+
 ### [integrations](docs/sdks/integrations/README.md)
 
 * [list](docs/sdks/integrations/README.md#list) - List all integrations
@@ -367,7 +370,7 @@ run();
 * [create](docs/sdks/subscribers/README.md#create) - Create a subscriber
 * [retrieve](docs/sdks/subscribers/README.md#retrieve) - Retrieve a subscriber
 * [patch](docs/sdks/subscribers/README.md#patch) - Update a subscriber
-* [delete](docs/sdks/subscribers/README.md#delete) - Delete subscriber
+* [delete](docs/sdks/subscribers/README.md#delete) - Delete a subscriber
 * [createBulk](docs/sdks/subscribers/README.md#createbulk) - Bulk create subscribers
 
 #### [subscribers.credentials](docs/sdks/credentials/README.md)
@@ -418,6 +421,20 @@ run();
 * [create](docs/sdks/subscriptions/README.md#create) - Create topic subscriptions
 * [delete](docs/sdks/subscriptions/README.md#delete) - Delete topic subscriptions
 
+### [workflows](docs/sdks/workflows/README.md)
+
+* [create](docs/sdks/workflows/README.md#create) - Create a workflow
+* [list](docs/sdks/workflows/README.md#list) - List all workflows
+* [update](docs/sdks/workflows/README.md#update) - Update a workflow
+* [get](docs/sdks/workflows/README.md#get) - Retrieve a workflow
+* [delete](docs/sdks/workflows/README.md#delete) - Delete a workflow
+* [patch](docs/sdks/workflows/README.md#patch) - Update a workflow
+* [sync](docs/sdks/workflows/README.md#sync) - Sync a workflow
+
+#### [workflows.steps](docs/sdks/steps/README.md)
+
+* [retrieve](docs/sdks/steps/README.md#retrieve) - Retrieve workflow step
+
 </details>
 <!-- End Available Resources and Operations [operations] -->
 
@@ -437,6 +454,10 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 <summary>Available standalone functions</summary>
 
 - [`cancel`](docs/sdks/novu/README.md#cancel) - Cancel triggered event
+- [`environmentsCreate`](docs/sdks/environments/README.md#create) - Create an environment
+- [`environmentsDelete`](docs/sdks/environments/README.md#delete) - Delete an environment
+- [`environmentsList`](docs/sdks/environments/README.md#list) - List all environments
+- [`environmentsUpdate`](docs/sdks/environments/README.md#update) - Update an environment
 - [`integrationsCreate`](docs/sdks/integrations/README.md#create) - Create an integration
 - [`integrationsDelete`](docs/sdks/integrations/README.md#delete) - Delete an integration
 - [`integrationsList`](docs/sdks/integrations/README.md#list) - List all integrations
@@ -453,7 +474,7 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`subscribersCredentialsAppend`](docs/sdks/credentials/README.md#append) - Upsert provider credentials
 - [`subscribersCredentialsDelete`](docs/sdks/credentials/README.md#delete) - Delete provider credentials
 - [`subscribersCredentialsUpdate`](docs/sdks/credentials/README.md#update) - Update provider credentials
-- [`subscribersDelete`](docs/sdks/subscribers/README.md#delete) - Delete subscriber
+- [`subscribersDelete`](docs/sdks/subscribers/README.md#delete) - Delete a subscriber
 - [`subscribersMessagesMarkAll`](docs/sdks/novumessages/README.md#markall) - Update all notifications state
 - [`subscribersMessagesMarkAllAs`](docs/sdks/novumessages/README.md#markallas) - Update notifications state
 - [`subscribersMessagesUpdateAsSeen`](docs/sdks/novumessages/README.md#updateasseen) - Update notification action status
@@ -478,6 +499,14 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 - [`trigger`](docs/sdks/novu/README.md#trigger) - Trigger event
 - [`triggerBroadcast`](docs/sdks/novu/README.md#triggerbroadcast) - Broadcast event to all
 - [`triggerBulk`](docs/sdks/novu/README.md#triggerbulk) - Bulk trigger event
+- [`workflowsCreate`](docs/sdks/workflows/README.md#create) - Create a workflow
+- [`workflowsDelete`](docs/sdks/workflows/README.md#delete) - Delete a workflow
+- [`workflowsGet`](docs/sdks/workflows/README.md#get) - Retrieve a workflow
+- [`workflowsList`](docs/sdks/workflows/README.md#list) - List all workflows
+- [`workflowsPatch`](docs/sdks/workflows/README.md#patch) - Update a workflow
+- [`workflowsStepsRetrieve`](docs/sdks/steps/README.md#retrieve) - Retrieve workflow step
+- [`workflowsSync`](docs/sdks/workflows/README.md#sync) - Sync a workflow
+- [`workflowsUpdate`](docs/sdks/workflows/README.md#update) - Update a workflow
 
 </details>
 <!-- End Standalone functions [standalone-funcs] -->
@@ -485,34 +514,29 @@ To read more about standalone functions, check [FUNCTIONS.md](./FUNCTIONS.md).
 <!-- Start Error Handling [errors] -->
 ## Error Handling
 
-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:
-
-| Error Type                | Status Code                            | Content Type     |
-| ------------------------- | -------------------------------------- | ---------------- |
-| errors.ErrorDto           | 414                                    | application/json |
-| errors.ErrorDto           | 400, 401, 403, 404, 405, 409, 413, 415 | application/json |
-| errors.ValidationErrorDto | 422                                    | application/json |
-| errors.ErrorDto           | 500                                    | application/json |
-| errors.SDKError           | 4XX, 5XX                               | \*/\*            |
+[`NovuError`](./src/models/errors/novuerror.ts) is the base class for all HTTP error responses. It has the following properties:
 
-If the method throws an error and it is not captured by the known errors, it will default to throwing a `SDKError`.
+| Property            | Type       | Description                                                                             |
+| ------------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `error.message`     | `string`   | Error message                                                                           |
+| `error.statusCode`  | `number`   | HTTP response status code eg `404`                                                      |
+| `error.headers`     | `Headers`  | HTTP response headers                                                                   |
+| `error.body`        | `string`   | HTTP body. Can be empty string if no body is returned.                                  |
+| `error.rawResponse` | `Response` | Raw HTTP response                                                                       |
+| `error.data$`       |            | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |
 
+### Example
 ```typescript
 import { Novu } from "@novu/api";
-import {
-  ErrorDto,
-  SDKValidationError,
-  ValidationErrorDto,
-} from "@novu/api/models/errors";
+import * as errors from "@novu/api/models/errors";
 
 const novu = new Novu({
   secretKey: "YOUR_SECRET_KEY_HERE",
 });
 
 async function run() {
-  let result;
   try {
-    result = await novu.trigger({
+    const result = await novu.trigger({
       workflowId: "workflow_identifier",
       payload: {
         "comment_id": "string",
@@ -524,41 +548,22 @@ async function run() {
       to: "SUBSCRIBER_ID",
     });
 
-    // Handle the result
     console.log(result);
-  } catch (err) {
-    switch (true) {
-      // The server response does not match the expected SDK schema
-      case (err instanceof SDKValidationError): {
-        // 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);
-        return;
-      }
-      case (err instanceof ErrorDto): {
-        // Handle err.data$: ErrorDtoData
-        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;
+  } catch (error) {
+    // The base class for HTTP error responses
+    if (error instanceof errors.NovuError) {
+      console.log(error.message);
+      console.log(error.statusCode);
+      console.log(error.body);
+      console.log(error.headers);
+
+      // Depending on the method different errors may be thrown
+      if (error instanceof errors.PayloadValidationExceptionDto) {
+        console.log(error.data$.statusCode); // number
+        console.log(error.data$.timestamp); // string
+        console.log(error.data$.path); // string
+        console.log(error.data$.message); // errors.PayloadValidationExceptionDtoMessage
+        console.log(error.data$.ctx); // { [k: string]: any }
       }
     }
   }
@@ -568,17 +573,31 @@ 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 multi-line string since validation errors can list many issues and the plain error string may be difficult read when debugging.
+### Error Classes
+**Primary errors:**
+* [`NovuError`](./src/models/errors/novuerror.ts): The base class for HTTP error responses.
+  * [`ErrorDto`](docs/models/errors/errordto.md): Generic error.
+  * [`ValidationErrorDto`](docs/models/errors/validationerrordto.md): Unprocessable Entity. Status code `422`.
+
+<details><summary>Less common errors (7)</summary>
+
+<br />
 
-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:
+**Network errors:**
+* [`ConnectionError`](./src/models/errors/httpclienterrors.ts): HTTP client was unable to make a request to a server.
+* [`RequestTimeoutError`](./src/models/errors/httpclienterrors.ts): HTTP request timed out due to an AbortSignal signal.
+* [`RequestAbortedError`](./src/models/errors/httpclienterrors.ts): HTTP request was aborted by the client.
+* [`InvalidRequestError`](./src/models/errors/httpclienterrors.ts): Any input used to create a request is invalid.
+* [`UnexpectedClientError`](./src/models/errors/httpclienterrors.ts): Unrecognised or unexpected error.
+
+
+**Inherit from [`NovuError`](./src/models/errors/novuerror.ts)**:
+* [`PayloadValidationExceptionDto`](docs/models/errors/payloadvalidationexceptiondto.md): Status code `400`. Applicable to 3 of 54 methods.*
+* [`ResponseValidationError`](./src/models/errors/responsevalidationerror.ts): Type mismatch between the data returned from the server and the structure expected by the SDK. See `error.rawValue` for the raw value and `error.pretty()` for a nicely formatted multi-line string.
+
+</details>
 
-| 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                     |
+\* Check [the method documentation](#available-resources-and-operations) to see if the error is applicable.
 <!-- End Error Handling [errors] -->
 
 <!-- Start Server Selection [server] -->
@@ -616,7 +635,6 @@ async function run() {
     to: "SUBSCRIBER_ID",
   });
 
-  // Handle the result
   console.log(result);
 }
 
@@ -648,7 +666,6 @@ async function run() {
     to: "SUBSCRIBER_ID",
   });
 
-  // Handle the result
   console.log(result);
 }
 
@@ -738,7 +755,6 @@ async function run() {
     to: "SUBSCRIBER_ID",
   });
 
-  // Handle the result
   console.log(result);
 }
 
@@ -784,7 +800,6 @@ async function run() {
     },
   });
 
-  // Handle the result
   console.log(result);
 }
 
@@ -823,7 +838,6 @@ async function run() {
     to: "SUBSCRIBER_ID",
   });
 
-  // Handle the result
   console.log(result);
 }