@sendly/node 3.5.2 → 3.5.4

package/README.md

@@ -77,10 +77,17 @@ import Sendly from '@sendly/node';
 
 const sendly = new Sendly('sk_live_v1_xxx');
 
-// Basic usage
+// Basic usage (marketing message - default)
 const message = await sendly.messages.send({
   to: '+15551234567',
-  text: 'Your verification code is: 123456'
+  text: 'Check out our new features!'
+});
+
+// Transactional message (bypasses quiet hours)
+const message = await sendly.messages.send({
+  to: '+15551234567',
+  text: 'Your verification code is: 123456',
+  messageType: 'transactional'
 });
 
 // With custom sender ID (international)
@@ -115,6 +122,54 @@ console.log(`Status: ${message.status}`);
 console.log(`Delivered: ${message.deliveredAt}`);
 ```
 
+### Scheduling Messages
+
+```typescript
+// Schedule a message for future delivery
+const scheduled = await sendly.messages.schedule({
+  to: '+15551234567',
+  text: 'Your appointment is tomorrow!',
+  scheduledAt: '2025-01-15T10:00:00Z'
+});
+
+console.log(`Scheduled: ${scheduled.id}`);
+console.log(`Will send at: ${scheduled.scheduledAt}`);
+
+// List scheduled messages
+const { data: scheduledMessages } = await sendly.messages.listScheduled();
+
+// Get a specific scheduled message
+const msg = await sendly.messages.getScheduled('sched_xxx');
+
+// Cancel a scheduled message (refunds credits)
+const result = await sendly.messages.cancelScheduled('sched_xxx');
+console.log(`Refunded: ${result.creditsRefunded} credits`);
+```
+
+### Batch Messages
+
+```typescript
+// Send multiple messages in one API call (up to 1000)
+const batch = await sendly.messages.sendBatch({
+  messages: [
+    { to: '+15551234567', text: 'Hello User 1!' },
+    { to: '+15559876543', text: 'Hello User 2!' },
+    { to: '+15551112222', text: 'Hello User 3!' }
+  ]
+});
+
+console.log(`Batch ID: ${batch.batchId}`);
+console.log(`Queued: ${batch.queued}`);
+console.log(`Failed: ${batch.failed}`);
+console.log(`Credits used: ${batch.creditsUsed}`);
+
+// Get batch status
+const status = await sendly.messages.getBatch('batch_xxx');
+
+// List all batches
+const { data: batches } = await sendly.messages.listBatches();
+```
+
 ### Rate Limit Information
 
 ```typescript
@@ -147,6 +202,113 @@ const sendly = new Sendly({
 });
 ```
 
+## Webhooks
+
+Manage webhook endpoints to receive real-time delivery status updates.
+
+```typescript
+// Create a webhook endpoint
+const webhook = await sendly.webhooks.create({
+  url: 'https://example.com/webhooks/sendly',
+  events: ['message.delivered', 'message.failed']
+});
+
+console.log(`Webhook ID: ${webhook.id}`);
+console.log(`Secret: ${webhook.secret}`); // Store this securely!
+
+// List all webhooks
+const webhooks = await sendly.webhooks.list();
+
+// Get a specific webhook
+const wh = await sendly.webhooks.get('whk_xxx');
+
+// Update a webhook
+await sendly.webhooks.update('whk_xxx', {
+  url: 'https://new-endpoint.example.com/webhook',
+  events: ['message.delivered', 'message.failed', 'message.sent']
+});
+
+// Test a webhook (sends a test event)
+const testResult = await sendly.webhooks.test('whk_xxx');
+console.log(`Test ${testResult.success ? 'passed' : 'failed'}`);
+
+// Rotate webhook secret
+const rotation = await sendly.webhooks.rotateSecret('whk_xxx');
+console.log(`New secret: ${rotation.secret}`);
+
+// View delivery history
+const deliveries = await sendly.webhooks.getDeliveries('whk_xxx');
+
+// Retry a failed delivery
+await sendly.webhooks.retryDelivery('whk_xxx', 'del_yyy');
+
+// Delete a webhook
+await sendly.webhooks.delete('whk_xxx');
+```
+
+### Verifying Webhook Signatures
+
+```typescript
+import { Webhooks } from '@sendly/node';
+
+const webhooks = new Webhooks('your_webhook_secret');
+
+// In your webhook handler
+app.post('/webhooks/sendly', (req, res) => {
+  const signature = req.headers['x-sendly-signature'];
+  const payload = req.body;
+
+  try {
+    const event = webhooks.verifyAndParse(payload, signature);
+    
+    switch (event.type) {
+      case 'message.delivered':
+        console.log(`Message ${event.data.id} delivered`);
+        break;
+      case 'message.failed':
+        console.log(`Message ${event.data.id} failed: ${event.data.errorCode}`);
+        break;
+    }
+    
+    res.status(200).send('OK');
+  } catch (error) {
+    console.error('Invalid signature');
+    res.status(400).send('Invalid signature');
+  }
+});
+```
+
+## Account & Credits
+
+```typescript
+// Get account information
+const account = await sendly.account.get();
+console.log(`Email: ${account.email}`);
+
+// Check credit balance
+const credits = await sendly.account.getCredits();
+console.log(`Available: ${credits.availableBalance} credits`);
+console.log(`Reserved (scheduled): ${credits.reservedBalance} credits`);
+console.log(`Total: ${credits.balance} credits`);
+
+// View credit transaction history
+const { data: transactions } = await sendly.account.getCreditTransactions();
+for (const tx of transactions) {
+  console.log(`${tx.type}: ${tx.amount} credits - ${tx.description}`);
+}
+
+// List API keys
+const { data: keys } = await sendly.account.listApiKeys();
+for (const key of keys) {
+  console.log(`${key.name}: ${key.prefix}*** (${key.type})`);
+}
+
+// Get API key usage stats
+const usage = await sendly.account.getApiKeyUsage('key_xxx');
+console.log(`Messages sent: ${usage.messagesSent}`);
+console.log(`Credits used: ${usage.creditsUsed}`);
+```
+
 ## Error Handling
 
 The SDK provides typed error classes for different error scenarios:
@@ -201,12 +363,12 @@ console.log(sendly.isTestMode()); // true
 
 // Use sandbox test numbers
 await sendly.messages.send({
-  to: SANDBOX_TEST_NUMBERS.SUCCESS,  // +15550001234 - Always succeeds
+  to: SANDBOX_TEST_NUMBERS.SUCCESS,  // +15005550000 - Always succeeds
   text: 'Test message'
 });
 
 await sendly.messages.send({
-  to: SANDBOX_TEST_NUMBERS.INVALID,  // +15550001001 - Returns invalid_number error
+  to: SANDBOX_TEST_NUMBERS.INVALID,  // +15005550001 - Returns invalid_number error
   text: 'Test message'
 });
 ```
@@ -215,11 +377,12 @@ await sendly.messages.send({
 
 | Number | Behavior |
 |--------|----------|
-| `+15550001234` | Instant success |
-| `+15550001010` | Success after 10s delay |
-| `+15550001001` | Fails: invalid_number |
-| `+15550001002` | Fails: carrier_rejected (2s delay) |
-| `+15550001003` | Fails: rate_limit_exceeded |
+| `+15005550000` | Success (instant) |
+| `+15005550001` | Fails: invalid_number |
+| `+15005550002` | Fails: unroutable_destination |
+| `+15005550003` | Fails: queue_full |
+| `+15005550004` | Fails: rate_limit_exceeded |
+| `+15005550006` | Fails: carrier_violation |
 
 ## Pricing Tiers
 
@@ -297,6 +460,8 @@ new Sendly(config: SendlyConfig)
 #### Properties
 
 - `messages` - Messages resource
+- `webhooks` - Webhooks resource
+- `account` - Account resource
 
 #### Methods
 
@@ -318,6 +483,98 @@ List sent messages.
 
 Get a specific message by ID.
 
+#### `schedule(request: ScheduleMessageRequest): Promise<ScheduledMessage>`
+
+Schedule a message for future delivery.
+
+#### `listScheduled(options?: ListScheduledMessagesOptions): Promise<ScheduledMessageListResponse>`
+
+List scheduled messages.
+
+#### `getScheduled(id: string): Promise<ScheduledMessage>`
+
+Get a scheduled message by ID.
+
+#### `cancelScheduled(id: string): Promise<CancelScheduledMessageResponse>`
+
+Cancel a scheduled message and refund credits.
+
+#### `sendBatch(request: SendBatchRequest): Promise<BatchMessageResponse>`
+
+Send multiple messages in one API call.
+
+#### `getBatch(batchId: string): Promise<BatchMessageResponse>`
+
+Get batch status by ID.
+
+#### `listBatches(options?: ListBatchesOptions): Promise<BatchListResponse>`
+
+List all batches.
+
+### `sendly.webhooks`
+
+#### `create(request: CreateWebhookRequest): Promise<Webhook>`
+
+Create a new webhook endpoint.
+
+#### `list(): Promise<Webhook[]>`
+
+List all webhooks.
+
+#### `get(id: string): Promise<Webhook>`
+
+Get a webhook by ID.
+
+#### `update(id: string, request: UpdateWebhookRequest): Promise<Webhook>`
+
+Update a webhook.
+
+#### `delete(id: string): Promise<void>`
+
+Delete a webhook.
+
+#### `test(id: string): Promise<WebhookTestResult>`
+
+Send a test event to a webhook.
+
+#### `rotateSecret(id: string): Promise<WebhookSecretRotation>`
+
+Rotate webhook secret.
+
+#### `getDeliveries(id: string): Promise<WebhookDelivery[]>`
+
+Get delivery history for a webhook.
+
+#### `retryDelivery(webhookId: string, deliveryId: string): Promise<void>`
+
+Retry a failed delivery.
+
+### `sendly.account`
+
+#### `get(): Promise<Account>`
+
+Get account information.
+
+#### `getCredits(): Promise<Credits>`
+
+Get credit balance.
+
+#### `getCreditTransactions(): Promise<CreditTransactionListResponse>`
+
+Get credit transaction history.
+
+#### `listApiKeys(): Promise<ApiKeyListResponse>`
+
+List API keys.
+
+#### `getApiKey(id: string): Promise<ApiKey>`
+
+Get an API key by ID.
+
+#### `getApiKeyUsage(id: string): Promise<ApiKeyUsage>`
+
+Get usage statistics for an API key.
+
 ## Support
 
 - 📚 [Documentation](https://sendly.live/docs)

package/dist/index.d.mts

@@ -755,19 +755,22 @@ interface ApiKey {
     isRevoked: boolean;
 }
 /**
- * Test phone numbers for sandbox mode
+ * Test phone numbers for sandbox mode.
+ * Use these with test API keys (sk_test_*) to simulate different scenarios.
  */
 declare const SANDBOX_TEST_NUMBERS: {
-    /** Always succeeds instantly */
-    readonly SUCCESS: "+15550001234";
-    /** Succeeds after 10 second delay */
-    readonly DELAYED: "+15550001010";
+    /** Always succeeds - any number not in error list succeeds */
+    readonly SUCCESS: "+15005550000";
     /** Fails with invalid_number error */
-    readonly INVALID: "+15550001001";
-    /** Fails with carrier_rejected error after 2 seconds */
-    readonly REJECTED: "+15550001002";
+    readonly INVALID: "+15005550001";
+    /** Fails with unroutable destination error */
+    readonly UNROUTABLE: "+15005550002";
+    /** Fails with queue_full error */
+    readonly QUEUE_FULL: "+15005550003";
     /** Fails with rate_limit_exceeded error */
-    readonly RATE_LIMITED: "+15550001003";
+    readonly RATE_LIMITED: "+15005550004";
+    /** Fails with carrier_violation error */
+    readonly CARRIER_VIOLATION: "+15005550006";
 };
 
 /**

package/dist/index.d.ts

@@ -755,19 +755,22 @@ interface ApiKey {
     isRevoked: boolean;
 }
 /**
- * Test phone numbers for sandbox mode
+ * Test phone numbers for sandbox mode.
+ * Use these with test API keys (sk_test_*) to simulate different scenarios.
  */
 declare const SANDBOX_TEST_NUMBERS: {
-    /** Always succeeds instantly */
-    readonly SUCCESS: "+15550001234";
-    /** Succeeds after 10 second delay */
-    readonly DELAYED: "+15550001010";
+    /** Always succeeds - any number not in error list succeeds */
+    readonly SUCCESS: "+15005550000";
     /** Fails with invalid_number error */
-    readonly INVALID: "+15550001001";
-    /** Fails with carrier_rejected error after 2 seconds */
-    readonly REJECTED: "+15550001002";
+    readonly INVALID: "+15005550001";
+    /** Fails with unroutable destination error */
+    readonly UNROUTABLE: "+15005550002";
+    /** Fails with queue_full error */
+    readonly QUEUE_FULL: "+15005550003";
     /** Fails with rate_limit_exceeded error */
-    readonly RATE_LIMITED: "+15550001003";
+    readonly RATE_LIMITED: "+15005550004";
+    /** Fails with carrier_violation error */
+    readonly CARRIER_VIOLATION: "+15005550006";
 };
 
 /**

package/dist/index.js

@@ -441,16 +441,18 @@ var SUPPORTED_COUNTRIES = {
 };
 var ALL_SUPPORTED_COUNTRIES = Object.values(SUPPORTED_COUNTRIES).flat();
 var SANDBOX_TEST_NUMBERS = {
-  /** Always succeeds instantly */
-  SUCCESS: "+15550001234",
-  /** Succeeds after 10 second delay */
-  DELAYED: "+15550001010",
+  /** Always succeeds - any number not in error list succeeds */
+  SUCCESS: "+15005550000",
   /** Fails with invalid_number error */
-  INVALID: "+15550001001",
-  /** Fails with carrier_rejected error after 2 seconds */
-  REJECTED: "+15550001002",
+  INVALID: "+15005550001",
+  /** Fails with unroutable destination error */
+  UNROUTABLE: "+15005550002",
+  /** Fails with queue_full error */
+  QUEUE_FULL: "+15005550003",
   /** Fails with rate_limit_exceeded error */
-  RATE_LIMITED: "+15550001003"
+  RATE_LIMITED: "+15005550004",
+  /** Fails with carrier_violation error */
+  CARRIER_VIOLATION: "+15005550006"
 };
 
 // src/utils/validation.ts
@@ -636,7 +638,8 @@ var MessagesResource = class {
       body: {
         to: request.to,
         text: request.text,
-        ...request.from && { from: request.from }
+        ...request.from && { from: request.from },
+        ...request.messageType && { messageType: request.messageType }
       }
     });
     return message;
@@ -800,7 +803,8 @@ var MessagesResource = class {
         to: request.to,
         text: request.text,
         scheduledAt: request.scheduledAt,
-        ...request.from && { from: request.from }
+        ...request.from && { from: request.from },
+        ...request.messageType && { messageType: request.messageType }
       }
     });
     return scheduled;
@@ -923,7 +927,8 @@ var MessagesResource = class {
       path: "/messages/batch",
       body: {
         messages: request.messages,
-        ...request.from && { from: request.from }
+        ...request.from && { from: request.from },
+        ...request.messageType && { messageType: request.messageType }
       }
     });
     return batch;

package/dist/index.mjs

@@ -381,16 +381,18 @@ var SUPPORTED_COUNTRIES = {
 };
 var ALL_SUPPORTED_COUNTRIES = Object.values(SUPPORTED_COUNTRIES).flat();
 var SANDBOX_TEST_NUMBERS = {
-  /** Always succeeds instantly */
-  SUCCESS: "+15550001234",
-  /** Succeeds after 10 second delay */
-  DELAYED: "+15550001010",
+  /** Always succeeds - any number not in error list succeeds */
+  SUCCESS: "+15005550000",
   /** Fails with invalid_number error */
-  INVALID: "+15550001001",
-  /** Fails with carrier_rejected error after 2 seconds */
-  REJECTED: "+15550001002",
+  INVALID: "+15005550001",
+  /** Fails with unroutable destination error */
+  UNROUTABLE: "+15005550002",
+  /** Fails with queue_full error */
+  QUEUE_FULL: "+15005550003",
   /** Fails with rate_limit_exceeded error */
-  RATE_LIMITED: "+15550001003"
+  RATE_LIMITED: "+15005550004",
+  /** Fails with carrier_violation error */
+  CARRIER_VIOLATION: "+15005550006"
 };
 
 // src/utils/validation.ts
@@ -576,7 +578,8 @@ var MessagesResource = class {
       body: {
         to: request.to,
         text: request.text,
-        ...request.from && { from: request.from }
+        ...request.from && { from: request.from },
+        ...request.messageType && { messageType: request.messageType }
       }
     });
     return message;
@@ -740,7 +743,8 @@ var MessagesResource = class {
         to: request.to,
         text: request.text,
         scheduledAt: request.scheduledAt,
-        ...request.from && { from: request.from }
+        ...request.from && { from: request.from },
+        ...request.messageType && { messageType: request.messageType }
       }
     });
     return scheduled;
@@ -863,7 +867,8 @@ var MessagesResource = class {
       path: "/messages/batch",
       body: {
         messages: request.messages,
-        ...request.from && { from: request.from }
+        ...request.from && { from: request.from },
+        ...request.messageType && { messageType: request.messageType }
       }
     });
     return batch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendly/node",
-  "version": "3.5.2",
+  "version": "3.5.4",
   "description": "Official Sendly Node.js SDK for SMS messaging",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",