Minor Improvements

README.md

@@ -117,6 +117,10 @@ const bento = new Analytics({
     secretKey: 'bento-secret-key',
   },
   siteUuid: 'bento-site-uuid',
+  // Optional: Configure request timeout (default: 30000ms)
+  clientOptions: {
+    timeout: 30000,
+  },
 });
 
 bento.V1.track({
@@ -179,10 +183,11 @@ bento.V1.removeSubscriber({
 
 #### 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',
@@ -194,6 +199,9 @@ await analytics.V1.upsertSubscriber({
 });
 ```
 
+> **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.
@@ -824,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
 

__tests__/batch/events.test.ts

@@ -1,14 +1,17 @@
-import { expect, test, describe, beforeEach } from 'bun:test';
+import { expect, test, describe, beforeEach, afterEach } from 'bun:test';
 import { Analytics } from '../../src';
 import { mockOptions } from '../helpers/mockClient';
-import { setupMockFetch } from '../helpers/mockFetch';
+import { setupMockFetch, lastFetchSignal, resetMockFetchTracking } from '../helpers/mockFetch';
 import { BentoEvents } from '../../src/sdk/batch/enums';
 describe('BentoBatch - importEvents', () => {
   let analytics: Analytics;
 
   beforeEach(() => {
     analytics = new Analytics(mockOptions);
   });
+  afterEach(() => {
+    resetMockFetchTracking();
+  });
 
   test('successfully imports purchase event', async () => {
     setupMockFetch({ results: 1 });
@@ -310,4 +313,20 @@ describe('BentoBatch - importEvents', () => {
 
     expect(result).toBe(3);
   });
-});
+
+  test('uses unlimited timeout for imports', async () => {
+    setupMockFetch({ results: 1 });
+
+    await analytics.V1.Batch.importEvents({
+      events: [{
+        type: BentoEvents.TAG,
+        email: 'signal@example.com',
+        details: {
+          tag: 'VIP'
+        }
+      }]
+    });
+
+    expect(lastFetchSignal).toBeNull();
+  });
+});

__tests__/batch/subscribers.test.ts

@@ -0,0 +1,31 @@
+import { expect, test, describe, beforeEach, afterEach } from 'bun:test';
+import { Analytics } from '../../src';
+import { mockOptions } from '../helpers/mockClient';
+import { setupMockFetch, lastFetchSignal, resetMockFetchTracking } from '../helpers/mockFetch';
+
+describe('BentoBatch - importSubscribers', () => {
+  let analytics: Analytics;
+
+  beforeEach(() => {
+    analytics = new Analytics(mockOptions);
+  });
+  afterEach(() => {
+    resetMockFetchTracking();
+  });
+
+  test('successfully imports subscribers without timeout signal', async () => {
+    setupMockFetch({ results: 1 });
+
+    const result = await analytics.V1.Batch.importSubscribers({
+      subscribers: [
+        {
+          email: 'test@example.com',
+          firstName: 'Test',
+        },
+      ],
+    });
+
+    expect(result).toBe(1);
+    expect(lastFetchSignal).toBeNull();
+  });
+});