@bentonow/bento-node-sdk 1.0.4 → 1.0.5

package/README.md

@@ -1,4 +1,5 @@
 # Bento Node SDK
+
 <img align="right" src="https://app.bentonow.com/brand/logoanim.gif">
 
 > [!TIP]
@@ -16,30 +17,27 @@ Get started with our [📚 integration guides](https://docs.bentonow.com), or [
 
 [![Tests](https://github.com/bentonow/bento-node-sdk/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/bentonow/bento-node-sdk/actions/workflows/main.yml)
 
-Table of contents
-=================
-
-
-* [Features](#features)
-* [Requirements](#requirements)
-* [Getting started](#getting-started)
-  * [Installation](#installation)
-  * [Integration](#integration)
-* [Modules](#modules)
-* [Type Reference](#types-reference)
-* [Things to know](#things-to-know)
-* [Contributing](#contributing)
-* [License](#license)
+# Table of contents
 
+- [Features](#features)
+- [Requirements](#requirements)
+- [Getting started](#getting-started)
+  - [Installation](#installation)
+  - [Integration](#integration)
+- [Modules](#modules)
+- [Type Reference](#types-reference)
+- [Things to know](#things-to-know)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Features
 
-* **Simple event tracking**: We make it easy for you to track user events and behavior in your application.
-* **Subscriber management**: Easily add, update, and remove subscribers from your Bento account.
-* **Custom fields**: Track and update custom fields for your subscribers to store additional data.
-* **Purchase tracking**: Monitor customer purchases and calculate lifetime value (LTV) for your subscribers.
-* **Batch operations**: Perform bulk imports of subscribers and events for efficient data management.
-* **TypeScript support**: The SDK is written in TypeScript and provides type definitions for a better development experience.
+- **Simple event tracking**: We make it easy for you to track user events and behavior in your application.
+- **Subscriber management**: Easily add, update, and remove subscribers from your Bento account.
+- **Custom fields**: Track and update custom fields for your subscribers to store additional data.
+- **Purchase tracking**: Monitor customer purchases and calculate lifetime value (LTV) for your subscribers.
+- **Batch operations**: Perform bulk imports of subscribers and events for efficient data management.
+- **TypeScript support**: The SDK is written in TypeScript and provides type definitions for a better development experience.
 
 ## Requirements
 
@@ -63,6 +61,7 @@ bun add @bentonow/bento-node-sdk
 ```
 
 ### Using Bun (Recommended)
+
 ```bash
 # Install dependencies
 bun install
@@ -84,6 +83,7 @@ bun run format
 ```
 
 ### Using npm
+
 ```bash
 # Install dependencies
 npm install
@@ -114,9 +114,13 @@ import { Analytics } from '@bentonow/bento-node-sdk';
 const bento = new Analytics({
   authentication: {
     publishableKey: 'bento-publishable-key',
-    secretKey: 'bento-secret-key', 
+    secretKey: 'bento-secret-key',
   },
   siteUuid: 'bento-site-uuid',
+  // Optional: Configure request timeout (default: 30000ms)
+  clientOptions: {
+    timeout: 30000,
+  },
 });
 
 bento.V1.track({
@@ -129,11 +133,11 @@ bento.V1.track({
   details: {
     fromCustomEvent: true,
   },
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
-
 ## Modules
+
 The Bento SDK provides several modules for different operations:
 
 ### Analytics (Base Module)
@@ -141,17 +145,20 @@ The Bento SDK provides several modules for different operations:
 Core functionality for tracking events and managing subscribers.
 
 ### Convenience Helpers
+
 #### tagSubscriber
+
 Tags a subscriber with a specific tag.
 
 ```javascript
 bento.V1.tagSubscriber({
   email: 'user@example.com',
   tagName: 'New Customer',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### addSubscriber
+
 Adds a new subscriber to your Bento account.
 
 ```javascript
@@ -161,37 +168,42 @@ bento.V1.addSubscriber({
     firstName: 'John',
     lastName: 'Doe',
   },
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### removeSubscriber
+
 Removes a subscriber from your Bento account.
 
 ```javascript
 bento.V1.removeSubscriber({
   email: 'user@example.com',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### upsertSubscriber
-Updates existing subscriber or creates a new one if they don't exist:
+
+Creates or updates a subscriber. The SDK queues the import job and then attempts to fetch
+the subscriber record once the job has been accepted.
 
 ```javascript
-await analytics.V1.upsertSubscriber({
+const subscriber = await analytics.V1.upsertSubscriber({
   email: 'user@example.com',
   fields: {
     firstName: 'John',
     lastName: 'Doe',
-    company: 'Acme Inc'
+    company: 'Acme Inc',
   },
   tags: 'lead,mql',
-  remove_tags: 'customer'
+  remove_tags: 'customer',
 });
 ```
 
-
+> **Note:** Imports are processed asynchronously by Bento and may take 1-5 minutes to
+> complete. If the subscriber is not yet available, the method will return `null`.
 
 #### updateFields
+
 Updates custom fields for a subscriber.
 
 ```javascript
@@ -200,10 +212,11 @@ bento.V1.updateFields({
   fields: {
     lastPurchaseDate: new Date(),
   },
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### track
+
 Tracks a custom event for a subscriber.
 
 ```javascript
@@ -213,10 +226,11 @@ bento.V1.track({
   details: {
     url: '/products',
   },
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### trackPurchase
+
 Tracks a purchase event for a subscriber.
 
 ```javascript
@@ -226,15 +240,17 @@ bento.V1.trackPurchase({
     unique: { key: 'order-123' },
     value: { amount: 9999, currency: 'USD' },
   },
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 ### Low Level API calls
+
 ### Batch
 
 Perform bulk operations for importing subscribers and events.
 
 #### importSubscribers
+
 Imports multiple subscribers in a single operation.
 
 ```javascript
@@ -243,10 +259,11 @@ bento.V1.Batch.importSubscribers({
     { email: 'user1@example.com', firstName: 'Alice' },
     { email: 'user2@example.com', firstName: 'Bob' },
   ],
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### importEvents
+
 Imports multiple events in a single operation.
 
 ```javascript
@@ -255,13 +272,13 @@ bento.V1.Batch.importEvents({
     { email: 'user@example.com', type: '$login' },
     { email: 'user@example.com', type: '$pageView', details: { url: '/home' } },
   ],
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
-
 ### Broadcast Management
 
 #### getBroadcasts
+
 Retrieves all broadcasts:
 
 ```javascript
@@ -269,45 +286,53 @@ const broadcasts = await analytics.V1.Broadcasts.getBroadcasts();
 ```
 
 #### createBroadcast
+
 Creates new broadcast campaigns:
 
 ```javascript
-const broadcasts = await analytics.V1.Broadcasts.createBroadcast([{
-  name: 'Weekly Newsletter',
-  subject: 'Your Weekly Update',
-  content: '<p>Hi {{ name }},</p>...',
-  type: 'html',
-  from: {
-    name: 'John Doe',
-    email: 'john@example.com'
+const broadcasts = await analytics.V1.Broadcasts.createBroadcast([
+  {
+    name: 'Weekly Newsletter',
+    subject: 'Your Weekly Update',
+    content: '<p>Hi {{ name }},</p>...',
+    type: 'html',
+    from: {
+      name: 'John Doe',
+      email: 'john@example.com',
+    },
+    inclusive_tags: 'lead,mql',
+    exclusive_tags: 'unsubscribed',
+    segment_id: 'segment_123',
+    batch_size_per_hour: 1000,
   },
-  inclusive_tags: 'lead,mql',
-  exclusive_tags: 'unsubscribed',
-  segment_id: 'segment_123',
-  batch_size_per_hour: 1000
-}]);
+]);
 ```
 
 ### Transactional Emails
 
 #### createEmails
+
 Creates a new transactional email:
 
 ```javascript
 const result = await bento.V1.Batch.sendTransactionalEmails({
-  emails: [{
-    to: 'recipient@example.com', // just the email, recipient name is ignored.
-    from: 'sender@example.com', // MUST be an existing Author in your account (Emails -> Authors)
-    subject: 'Welcome {{ name }}',
-    html_body: '<p>Hello {{ name }}, welcome to our service!</p>',
-    transactional: false, // Set to true to send as a transactional email IF you want to ignore if the user has unsubscribed. USE WITH CAUTION!
-    personalizations: {
-      name: 'John Doe',
-    }
-  }]
+  emails: [
+    {
+      to: 'recipient@example.com', // just the email, recipient name is ignored.
+      from: 'sender@example.com', // MUST be an existing Author in your account (Emails -> Authors)
+      subject: 'Welcome {{ name }}',
+      html_body: '<p>Hello {{ name }}, welcome to our service!</p>',
+      transactional: false, // Set to true to send as a transactional email IF you want to ignore if the user has unsubscribed. USE WITH CAUTION!
+      personalizations: {
+        name: 'John Doe',
+      },
+    },
+  ],
 });
 ```
+
 ### Email Structure
+
 Each email object requires:
 
 - **to:** Recipient email address
@@ -323,10 +348,10 @@ Each email object requires:
 - **Errors:** Throws TooFewEmailsError or TooManyEmailsError for invalid counts
 - **Returns:** Number of emails successfully queued
 
-
 ### Statistics
 
 #### getSiteStats
+
 Retrieves overall site statistics:
 
 ```javascript
@@ -343,6 +368,7 @@ const stats = await analytics.V1.Stats.getSiteStats();
 ```
 
 #### getSegmentStats
+
 Retrieves statistics for a specific segment:
 
 ```javascript
@@ -358,6 +384,7 @@ const segmentStats = await analytics.V1.Stats.getSegmentStats('segment_123');
 ```
 
 #### getReportStats
+
 Retrieves statistics for a specific report:
 
 ```javascript
@@ -375,32 +402,34 @@ const reportStats = await analytics.V1.Stats.getReportStats('report_123');
 // }
 ```
 
-
 ### Commands
 
 Execute specific commands for subscriber management.
 
 #### addTag
+
 Adds a tag to a subscriber.
 
 ```javascript
 bento.V1.Commands.addTag({
   email: 'user@example.com',
   tagName: 'VIP',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### removeTag
+
 Removes a tag from a subscriber.
 
 ```javascript
 bento.V1.Commands.removeTag({
   email: 'user@example.com',
   tagName: 'VIP',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### addField
+
 Adds a custom field to a subscriber.
 
 ```javascript
@@ -410,17 +439,18 @@ bento.V1.Commands.addField({
     key: 'favoriteColor',
     value: 'blue',
   },
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### removeField
+
 Removes a custom field from a subscriber.
 
 ```javascript
 bento.V1.Commands.removeField({
   email: 'user@example.com',
   fieldName: 'favoriteColor',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 ### Experimental
@@ -428,39 +458,41 @@ bento.V1.Commands.removeField({
 Access experimental features (use with caution).
 
 #### validateEmail
+
 Attempts to validate an email address.
 
 ```javascript
 bento.V1.Experimental.validateEmail({
   email: 'user@example.com',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 #### guessGender
+
 Attempts to guess the gender based on a given name.
 
 ```javascript
 bento.V1.Experimental.guessGender({
   name: 'Alex',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 is blacklisted:
 
 ```javascript
 const blacklistStatus = await analytics.V1.Experimental.getBlacklistStatus({
-  domain: 'example.com'
+  domain: 'example.com',
   // or ipAddress: '192.168.1.1'
 });
 ```
 
 #### getContentModeration
+
 Performs content moderation on text:
 
 ```javascript
-const moderationResult = await analytics.V1.Experimental.getContentModeration(
-  'Content to moderate'
-);
+const moderationResult =
+  await analytics.V1.Experimental.getContentModeration('Content to moderate');
 // Returns:
 // {
 //   flagged: boolean,
@@ -479,6 +511,7 @@ const moderationResult = await analytics.V1.Experimental.getContentModeration(
 ```
 
 #### geoLocateIP
+
 Gets detailed geolocation information for an IP address:
 
 ```javascript
@@ -498,19 +531,21 @@ const location = await analytics.V1.Experimental.geoLocateIP('192.168.1.1');
 Manage custom fields for your subscribers.
 
 #### getFields
+
 Retrieves all custom fields defined in your Bento account.
 
 ```javascript
-bento.V1.Fields.getFields().then(fields => console.log(fields));
+bento.V1.Fields.getFields().then((fields) => console.log(fields));
 ```
 
 #### createField
+
 Creates a new custom field in your Bento account.
 
 ```javascript
 bento.V1.Fields.createField({
   key: 'loyaltyPoints',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 ### Forms
@@ -518,10 +553,11 @@ bento.V1.Fields.createField({
 Retrieve form responses.
 
 #### getResponses
+
 Retrieves responses for a specific form.
 
 ```javascript
-bento.V1.Forms.getResponses('form-id-123').then(responses => console.log(responses));
+bento.V1.Forms.getResponses('form-id-123').then((responses) => console.log(responses));
 ```
 
 ### Subscribers
@@ -529,21 +565,23 @@ bento.V1.Forms.getResponses('form-id-123').then(responses => console.log(respons
 Manage individual subscribers.
 
 #### getSubscribers
+
 Retrieves subscriber information.
 
 ```javascript
 bento.V1.Subscribers.getSubscribers({
   email: 'user@example.com',
-}).then(subscriber => console.log(subscriber));
+}).then((subscriber) => console.log(subscriber));
 ```
 
 #### createSubscriber
+
 Creates a new subscriber in your Bento account.
 
 ```javascript
 bento.V1.Subscribers.createSubscriber({
   email: 'newuser@example.com',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
 ```
 
 ### Tags
@@ -551,19 +589,111 @@ bento.V1.Subscribers.createSubscriber({
 Create and manage tags for subscriber segmentation.
 
 #### getTags
+
 Retrieves all tags defined in your Bento account.
 
 ```javascript
-bento.V1.Tags.getTags().then(tags => console.log(tags));
+bento.V1.Tags.getTags().then((tags) => console.log(tags));
 ```
 
 #### createTag
+
 Creates a new tag in your Bento account.
 
 ```javascript
 bento.V1.Tags.createTag({
   name: 'Premium Customer',
-}).then(result => console.log(result));
+}).then((result) => console.log(result));
+```
+
+### Sequences
+
+Retrieve sequences and their associated email templates.
+
+#### getSequences
+
+Retrieves all sequences for the site, including their email templates.
+
+```javascript
+const sequences = await bento.V1.Sequences.getSequences();
+// Returns:
+// [
+//   {
+//     id: '123',
+//     type: 'sequence',
+//     attributes: {
+//       name: 'Welcome Sequence',
+//       created_at: '2024-01-01T00:00:00Z',
+//       email_templates: [
+//         { id: 1, subject: 'Welcome!', stats: null },
+//         { id: 2, subject: 'Getting Started', stats: null }
+//       ]
+//     }
+//   }
+// ]
+```
+
+### Workflows
+
+Retrieve workflows and their associated email templates.
+
+#### getWorkflows
+
+Retrieves all workflows for the site, including their email templates.
+
+```javascript
+const workflows = await bento.V1.Workflows.getWorkflows();
+// Returns:
+// [
+//   {
+//     id: '456',
+//     type: 'workflow',
+//     attributes: {
+//       name: 'Onboarding Workflow',
+//       created_at: '2024-01-01T00:00:00Z',
+//       email_templates: [
+//         { id: 3, subject: 'Step 1', stats: null },
+//         { id: 4, subject: 'Step 2', stats: null }
+//       ]
+//     }
+//   }
+// ]
+```
+
+### Email Templates
+
+Retrieve and update email templates used in sequences and workflows.
+
+#### getEmailTemplate
+
+Retrieves a single email template by ID.
+
+```javascript
+const template = await bento.V1.EmailTemplates.getEmailTemplate({ id: 123 });
+// Returns:
+// {
+//   id: '123',
+//   type: 'email_template',
+//   attributes: {
+//     name: 'Welcome Email',
+//     subject: 'Welcome to our service!',
+//     html: '<p>Hello {{ name }}, welcome!</p>',
+//     created_at: '2024-01-01T00:00:00Z',
+//     stats: null
+//   }
+// }
+```
+
+#### updateEmailTemplate
+
+Updates an email template's subject and/or HTML content.
+
+```javascript
+const updatedTemplate = await bento.V1.EmailTemplates.updateEmailTemplate({
+  id: 123,
+  subject: 'Updated Subject Line',
+  html: '<p>Updated HTML content with {{ name }}</p>',
+});
 ```
 
 For detailed information on each module, refer to the [SDK Documentation](https://docs.bentonow.com/subscribers).
@@ -576,7 +706,7 @@ AddFieldParameters `<S>`
 Parameters for adding a field to a subscriber.
 
 | Property | Type                         | Required | Description                |
-|----------|------------------------------|----------|----------------------------|
+| -------- | ---------------------------- | -------- | -------------------------- |
 | email    | string                       | ✔️       | Subscriber's email address |
 | field    | { key: keyof S; value: any } | ✔️       | Field to add               |
 
@@ -585,17 +715,17 @@ Parameters for adding a field to a subscriber.
 Parameters for adding a new subscriber.
 
 | Property | Type          | Required | Description                          |
-|----------|---------------|----------|--------------------------------------|
-| date     | Date          | ❌        | Date of subscription                 |
+| -------- | ------------- | -------- | ------------------------------------ |
+| date     | Date          | ❌       | Date of subscription                 |
 | email    | string        | ✔️       | Subscriber's email address           |
-| fields   | Partial `<S>` | ❌        | Additional fields for the subscriber |
+| fields   | Partial `<S>` | ❌       | Additional fields for the subscriber |
 
 ### AddTagParameters
 
 Parameters for adding a tag to a subscriber.
 
 | Property | Type   | Required | Description                |
-|----------|--------|----------|----------------------------|
+| -------- | ------ | -------- | -------------------------- |
 | email    | string | ✔️       | Subscriber's email address |
 | tagName  | string | ✔️       | Name of the tag to add     |
 
@@ -604,7 +734,7 @@ Parameters for adding a tag to a subscriber.
 Parameters for batch importing events.
 
 | Property | Type                    | Required | Description               |
-|----------|-------------------------|----------|---------------------------|
+| -------- | ----------------------- | -------- | ------------------------- |
 | events   | BentoEvent `<S>`, `<E>` | ✔️       | Array of events to import |
 
 ### BatchImportSubscribersParameter `<S>`
@@ -612,10 +742,11 @@ Parameters for batch importing events.
 Parameters for batch importing subscribers.
 
 | Property    | Type                                  | Required | Description                    |
-|-------------|---------------------------------------|----------|--------------------------------|
+| ----------- | ------------------------------------- | -------- | ------------------------------ |
 | subscribers | ({ email: string } & Partial `<S>`)[] | ✔️       | Array of subscribers to import |
 
 ### BentoEvent `<S>`, `<E>`
+
 Represents different types of events in Bento. It's a union of the following event types:
 
 - BaseEvent `<E>`
@@ -630,17 +761,17 @@ Represents different types of events in Bento. It's a union of the following eve
 Details of a purchase event.
 
 | Property | Type                                 | Required | Description                        |
-|----------|--------------------------------------|----------|------------------------------------|
+| -------- | ------------------------------------ | -------- | ---------------------------------- |
 | unique   | { key: string \| number }            | ✔️       | Unique identifier for the purchase |
 | value    | { currency: string; amount: number } | ✔️       | Value of the purchase              |
-| cart     | PurchaseCart                         | ❌        | Additional cart details            |
+| cart     | PurchaseCart                         | ❌       | Additional cart details            |
 
 ### ChangeEmailParameters
 
 Parameters for changing a subscriber's email.
 
 | Property | Type   | Required | Description           |
-|----------|--------|----------|-----------------------|
+| -------- | ------ | -------- | --------------------- |
 | oldEmail | string | ✔️       | Current email address |
 | newEmail | string | ✔️       | New email address     |
 
@@ -649,7 +780,7 @@ Parameters for changing a subscriber's email.
 Parameters for creating a new field.
 
 | Property | Type   | Required | Description          |
-|----------|--------|----------|----------------------|
+| -------- | ------ | -------- | -------------------- |
 | key      | string | ✔️       | Key of the new field |
 
 ### CreateTagParameters
@@ -657,7 +788,7 @@ Parameters for creating a new field.
 Parameters for creating a new tag.
 
 | Property | Type   | Required | Description         |
-|----------|--------|----------|---------------------|
+| -------- | ------ | -------- | ------------------- |
 | name     | string | ✔️       | Name of the new tag |
 
 ### Subscriber `<S>`
@@ -665,7 +796,7 @@ Parameters for creating a new tag.
 Represents a subscriber in Bento.
 
 | Property   | Type                       | Required | Description                  |
-|------------|----------------------------|----------|------------------------------|
+| ---------- | -------------------------- | -------- | ---------------------------- |
 | attributes | SubscriberAttributes `<S>` | ✔️       | Attributes of the subscriber |
 | id         | string                     | ✔️       | Unique identifier            |
 | type       | EntityType.VISITOR         | ✔️       | Type of the entity           |
@@ -675,26 +806,25 @@ Represents a subscriber in Bento.
 Parameters for tracking an event.
 
 | Property | Type                   | Required | Description                         |
-|----------|------------------------|----------|-------------------------------------|
+| -------- | ---------------------- | -------- | ----------------------------------- |
 | email    | string                 | ✔️       | Subscriber's email address          |
 | type     | string                 | ✔️       | Type of the event                   |
-| details  | { [key: string]: any } | ❌        | Additional details of the event     |
-| fields   | Partial `<S>`          | ❌        | Fields to update for the subscriber |
+| details  | { [key: string]: any } | ❌       | Additional details of the event     |
+| fields   | Partial `<S>`          | ❌       | Fields to update for the subscriber |
 
 ### ValidateEmailParameters
 
 Parameters for validating an email address.
 
 | Property  | Type   | Required | Description                    |
-|-----------|--------|----------|--------------------------------|
+| --------- | ------ | -------- | ------------------------------ |
 | email     | string | ✔️       | Email address to validate      |
-| ip        | string | ❌        | IP address of the user         |
-| name      | string | ❌        | Name associated with the email |
-| userAgent | string | ❌        | User agent string              |
+| ip        | string | ❌       | IP address of the user         |
+| name      | string | ❌       | Name associated with the email |
+| userAgent | string | ❌       | User agent string              |
 
 Note: The `S` and `E` generic types are used for TypeScript support. `S` represents the type of your subscriber's custom fields, and `E` represents the prefix used for custom events. For more details, refer to the TypeScript section of the documentation.
 
-
 ## Things to know
 
 - All events must be identified with an email address.
@@ -702,6 +832,32 @@ Note: The `S` and `E` generic types are used for TypeScript support. `S` represe
 - The SDK supports TypeScript with generics for custom fields and events.
 - Batch operations are available for importing subscribers and events efficiently.
 - The SDK doesn't currently support anonymous events (coming soon).
+- Requests have a default timeout of 30 seconds, configurable via `clientOptions.timeout`.
+
+## Error Handling
+
+The SDK exports several error types for specific error conditions:
+
+```javascript
+import {
+  NotAuthorizedError, // 401 - Invalid credentials
+  RateLimitedError, // 429 - Too many requests
+  AuthorNotAuthorizedError, // Author not permitted to send emails
+  RequestTimeoutError, // Request exceeded timeout
+} from '@bentonow/bento-node-sdk';
+
+try {
+  await bento.V1.Tags.getTags();
+} catch (error) {
+  if (error instanceof RequestTimeoutError) {
+    // Handle timeout - maybe retry
+  } else if (error instanceof RateLimitedError) {
+    // Handle rate limiting - back off and retry
+  } else if (error instanceof NotAuthorizedError) {
+    // Handle auth error - check credentials
+  }
+}
+```
 
 ## Contributing