@sendly/node 1.0.8 → 1.1.0

package/dist/index.js

@@ -978,6 +978,443 @@ var MessagesResource = class {
   }
 };
 
+// src/utils/transform.ts
+function snakeToCamel(str) {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function transformKeys(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => transformKeys(item));
+  }
+  if (typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const camelKey = snakeToCamel(key);
+      result[camelKey] = transformKeys(value);
+    }
+    return result;
+  }
+  return obj;
+}
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new webhook endpoint
+   *
+   * @param options - Webhook configuration
+   * @returns The created webhook with signing secret (shown only once!)
+   *
+   * @example
+   * ```typescript
+   * const webhook = await sendly.webhooks.create({
+   *   url: 'https://example.com/webhooks/sendly',
+   *   events: ['message.delivered', 'message.failed'],
+   *   description: 'Production webhook'
+   * });
+   *
+   * // IMPORTANT: Save this secret securely - it's only shown once!
+   * console.log('Webhook secret:', webhook.secret);
+   * ```
+   *
+   * @throws {ValidationError} If the URL is invalid or events are empty
+   * @throws {AuthenticationError} If the API key is invalid
+   */
+  async create(options) {
+    if (!options.url || !options.url.startsWith("https://")) {
+      throw new Error("Webhook URL must be HTTPS");
+    }
+    if (!options.events || options.events.length === 0) {
+      throw new Error("At least one event type is required");
+    }
+    const response = await this.http.request({
+      method: "POST",
+      path: "/webhooks",
+      body: {
+        url: options.url,
+        events: options.events,
+        ...options.description && { description: options.description },
+        ...options.metadata && { metadata: options.metadata }
+      }
+    });
+    return transformKeys(response);
+  }
+  /**
+   * List all webhooks
+   *
+   * @returns Array of webhook configurations
+   *
+   * @example
+   * ```typescript
+   * const webhooks = await sendly.webhooks.list();
+   *
+   * for (const webhook of webhooks) {
+   *   console.log(`${webhook.id}: ${webhook.url} (${webhook.isActive ? 'active' : 'inactive'})`);
+   * }
+   * ```
+   */
+  async list() {
+    const response = await this.http.request({
+      method: "GET",
+      path: "/webhooks"
+    });
+    return response.map((item) => transformKeys(item));
+  }
+  /**
+   * Get a specific webhook by ID
+   *
+   * @param id - Webhook ID (whk_xxx)
+   * @returns The webhook details
+   *
+   * @example
+   * ```typescript
+   * const webhook = await sendly.webhooks.get('whk_xxx');
+   * console.log(`Success rate: ${webhook.successRate}%`);
+   * ```
+   *
+   * @throws {NotFoundError} If the webhook doesn't exist
+   */
+  async get(id) {
+    if (!id || !id.startsWith("whk_")) {
+      throw new Error("Invalid webhook ID format");
+    }
+    const response = await this.http.request({
+      method: "GET",
+      path: `/webhooks/${encodeURIComponent(id)}`
+    });
+    return transformKeys(response);
+  }
+  /**
+   * Update a webhook configuration
+   *
+   * @param id - Webhook ID
+   * @param options - Fields to update
+   * @returns The updated webhook
+   *
+   * @example
+   * ```typescript
+   * // Update URL
+   * await sendly.webhooks.update('whk_xxx', {
+   *   url: 'https://new-endpoint.example.com/webhooks'
+   * });
+   *
+   * // Disable webhook
+   * await sendly.webhooks.update('whk_xxx', { isActive: false });
+   *
+   * // Change event subscriptions
+   * await sendly.webhooks.update('whk_xxx', {
+   *   events: ['message.delivered']
+   * });
+   * ```
+   */
+  async update(id, options) {
+    if (!id || !id.startsWith("whk_")) {
+      throw new Error("Invalid webhook ID format");
+    }
+    if (options.url && !options.url.startsWith("https://")) {
+      throw new Error("Webhook URL must be HTTPS");
+    }
+    const response = await this.http.request({
+      method: "PATCH",
+      path: `/webhooks/${encodeURIComponent(id)}`,
+      body: {
+        ...options.url !== void 0 && { url: options.url },
+        ...options.events !== void 0 && { events: options.events },
+        ...options.description !== void 0 && {
+          description: options.description
+        },
+        ...options.isActive !== void 0 && { is_active: options.isActive },
+        ...options.metadata !== void 0 && { metadata: options.metadata }
+      }
+    });
+    return transformKeys(response);
+  }
+  /**
+   * Delete a webhook
+   *
+   * @param id - Webhook ID
+   *
+   * @example
+   * ```typescript
+   * await sendly.webhooks.delete('whk_xxx');
+   * ```
+   *
+   * @throws {NotFoundError} If the webhook doesn't exist
+   */
+  async delete(id) {
+    if (!id || !id.startsWith("whk_")) {
+      throw new Error("Invalid webhook ID format");
+    }
+    await this.http.request({
+      method: "DELETE",
+      path: `/webhooks/${encodeURIComponent(id)}`
+    });
+  }
+  /**
+   * Send a test event to a webhook endpoint
+   *
+   * @param id - Webhook ID
+   * @returns Test result with response details
+   *
+   * @example
+   * ```typescript
+   * const result = await sendly.webhooks.test('whk_xxx');
+   *
+   * if (result.success) {
+   *   console.log(`Test passed! Response time: ${result.responseTimeMs}ms`);
+   * } else {
+   *   console.log(`Test failed: ${result.error}`);
+   * }
+   * ```
+   */
+  async test(id) {
+    if (!id || !id.startsWith("whk_")) {
+      throw new Error("Invalid webhook ID format");
+    }
+    const response = await this.http.request({
+      method: "POST",
+      path: `/webhooks/${encodeURIComponent(id)}/test`
+    });
+    return transformKeys(response);
+  }
+  /**
+   * Rotate the webhook signing secret
+   *
+   * The old secret remains valid for 24 hours to allow for graceful migration.
+   *
+   * @param id - Webhook ID
+   * @returns New secret and expiration info
+   *
+   * @example
+   * ```typescript
+   * const rotation = await sendly.webhooks.rotateSecret('whk_xxx');
+   *
+   * // Update your webhook handler with the new secret
+   * console.log('New secret:', rotation.newSecret);
+   * console.log('Old secret expires:', rotation.oldSecretExpiresAt);
+   * ```
+   */
+  async rotateSecret(id) {
+    if (!id || !id.startsWith("whk_")) {
+      throw new Error("Invalid webhook ID format");
+    }
+    const response = await this.http.request({
+      method: "POST",
+      path: `/webhooks/${encodeURIComponent(id)}/rotate-secret`
+    });
+    return transformKeys(response);
+  }
+  /**
+   * Get delivery history for a webhook
+   *
+   * @param id - Webhook ID
+   * @returns Array of delivery attempts
+   *
+   * @example
+   * ```typescript
+   * const deliveries = await sendly.webhooks.getDeliveries('whk_xxx');
+   *
+   * for (const delivery of deliveries) {
+   *   console.log(`${delivery.eventType}: ${delivery.status} (${delivery.responseTimeMs}ms)`);
+   * }
+   * ```
+   */
+  async getDeliveries(id) {
+    if (!id || !id.startsWith("whk_")) {
+      throw new Error("Invalid webhook ID format");
+    }
+    const response = await this.http.request({
+      method: "GET",
+      path: `/webhooks/${encodeURIComponent(id)}/deliveries`
+    });
+    return response.map((item) => transformKeys(item));
+  }
+  /**
+   * Retry a failed delivery
+   *
+   * @param webhookId - Webhook ID
+   * @param deliveryId - Delivery ID
+   *
+   * @example
+   * ```typescript
+   * await sendly.webhooks.retryDelivery('whk_xxx', 'del_yyy');
+   * ```
+   */
+  async retryDelivery(webhookId, deliveryId) {
+    if (!webhookId || !webhookId.startsWith("whk_")) {
+      throw new Error("Invalid webhook ID format");
+    }
+    if (!deliveryId || !deliveryId.startsWith("del_")) {
+      throw new Error("Invalid delivery ID format");
+    }
+    await this.http.request({
+      method: "POST",
+      path: `/webhooks/${encodeURIComponent(webhookId)}/deliveries/${encodeURIComponent(deliveryId)}/retry`
+    });
+  }
+  /**
+   * List available event types
+   *
+   * @returns Array of event type strings
+   *
+   * @example
+   * ```typescript
+   * const eventTypes = await sendly.webhooks.listEventTypes();
+   * console.log('Available events:', eventTypes);
+   * // ['message.sent', 'message.delivered', 'message.failed', 'message.bounced']
+   * ```
+   */
+  async listEventTypes() {
+    const eventTypes = await this.http.request({
+      method: "GET",
+      path: "/webhooks/event-types"
+    });
+    return eventTypes;
+  }
+};
+
+// src/resources/account.ts
+var AccountResource = class {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get account information
+   *
+   * @returns Account details
+   *
+   * @example
+   * ```typescript
+   * const account = await sendly.account.get();
+   * console.log(`Account: ${account.email}`);
+   * ```
+   */
+  async get() {
+    const account = await this.http.request({
+      method: "GET",
+      path: "/account"
+    });
+    return account;
+  }
+  /**
+   * Get credit balance
+   *
+   * @returns Current credit balance and reserved credits
+   *
+   * @example
+   * ```typescript
+   * const credits = await sendly.account.getCredits();
+   *
+   * console.log(`Total balance: ${credits.balance}`);
+   * console.log(`Reserved (scheduled): ${credits.reservedBalance}`);
+   * console.log(`Available to use: ${credits.availableBalance}`);
+   * ```
+   */
+  async getCredits() {
+    const credits = await this.http.request({
+      method: "GET",
+      path: "/credits"
+    });
+    return credits;
+  }
+  /**
+   * Get credit transaction history
+   *
+   * @param options - Pagination options
+   * @returns Array of credit transactions
+   *
+   * @example
+   * ```typescript
+   * const transactions = await sendly.account.getCreditTransactions();
+   *
+   * for (const tx of transactions) {
+   *   const sign = tx.amount > 0 ? '+' : '';
+   *   console.log(`${tx.type}: ${sign}${tx.amount} credits - ${tx.description}`);
+   * }
+   * ```
+   */
+  async getCreditTransactions(options) {
+    const transactions = await this.http.request({
+      method: "GET",
+      path: "/credits/transactions",
+      query: {
+        limit: options?.limit,
+        offset: options?.offset
+      }
+    });
+    return transactions;
+  }
+  /**
+   * List API keys for the account
+   *
+   * Note: This returns key metadata, not the actual secret keys.
+   *
+   * @returns Array of API keys
+   *
+   * @example
+   * ```typescript
+   * const keys = await sendly.account.listApiKeys();
+   *
+   * for (const key of keys) {
+   *   console.log(`${key.name}: ${key.prefix}...${key.lastFour} (${key.type})`);
+   * }
+   * ```
+   */
+  async listApiKeys() {
+    const keys = await this.http.request({
+      method: "GET",
+      path: "/keys"
+    });
+    return keys;
+  }
+  /**
+   * Get a specific API key by ID
+   *
+   * @param id - API key ID
+   * @returns API key details
+   *
+   * @example
+   * ```typescript
+   * const key = await sendly.account.getApiKey('key_xxx');
+   * console.log(`Last used: ${key.lastUsedAt}`);
+   * ```
+   */
+  async getApiKey(id) {
+    const key = await this.http.request({
+      method: "GET",
+      path: `/keys/${encodeURIComponent(id)}`
+    });
+    return key;
+  }
+  /**
+   * Get usage statistics for an API key
+   *
+   * @param id - API key ID
+   * @returns Usage statistics
+   *
+   * @example
+   * ```typescript
+   * const usage = await sendly.account.getApiKeyUsage('key_xxx');
+   * console.log(`Messages sent: ${usage.messagesSent}`);
+   * ```
+   */
+  async getApiKeyUsage(id) {
+    const usage = await this.http.request({
+      method: "GET",
+      path: `/keys/${encodeURIComponent(id)}/usage`
+    });
+    return usage;
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL2 = "https://sendly.live/api/v1";
 var DEFAULT_TIMEOUT2 = 3e4;
@@ -999,6 +1436,41 @@ var Sendly = class {
    * ```
    */
   messages;
+  /**
+   * Webhooks API resource
+   *
+   * @example
+   * ```typescript
+   * // Create a webhook
+   * const webhook = await sendly.webhooks.create({
+   *   url: 'https://example.com/webhooks',
+   *   events: ['message.delivered', 'message.failed']
+   * });
+   *
+   * // List webhooks
+   * const webhooks = await sendly.webhooks.list();
+   *
+   * // Test a webhook
+   * await sendly.webhooks.test('whk_xxx');
+   * ```
+   */
+  webhooks;
+  /**
+   * Account API resource
+   *
+   * @example
+   * ```typescript
+   * // Get credit balance
+   * const credits = await sendly.account.getCredits();
+   *
+   * // Get transaction history
+   * const transactions = await sendly.account.getCreditTransactions();
+   *
+   * // List API keys
+   * const keys = await sendly.account.listApiKeys();
+   * ```
+   */
+  account;
   http;
   config;
   /**
@@ -1029,6 +1501,8 @@ var Sendly = class {
       maxRetries: this.config.maxRetries
     });
     this.messages = new MessagesResource(this.http);
+    this.webhooks = new WebhooksResource(this.http);
+    this.account = new AccountResource(this.http);
   }
   /**
    * Check if the client is using a test API key
@@ -1082,11 +1556,22 @@ var WebhookSignatureError = class extends Error {
     this.name = "WebhookSignatureError";
   }
 };
-function verifyWebhookSignature(payload, signature, secret) {
+function verifyWebhookSignature(payload, signature, secret, timestamp, toleranceSeconds = 300) {
   if (!payload || !signature || !secret) {
     return false;
   }
-  const expectedSignature = generateWebhookSignature(payload, secret);
+  if (timestamp) {
+    const timestampNum = parseInt(timestamp, 10);
+    if (isNaN(timestampNum)) {
+      return false;
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    if (Math.abs(now - timestampNum) > toleranceSeconds) {
+      return false;
+    }
+  }
+  const signedPayload = timestamp ? `${timestamp}.${payload}` : payload;
+  const expectedSignature = generateWebhookSignature(signedPayload, secret);
   try {
     return crypto.timingSafeEqual(
       Buffer.from(signature),
@@ -1096,8 +1581,8 @@ function verifyWebhookSignature(payload, signature, secret) {
     return false;
   }
 }
-function parseWebhookEvent(payload, signature, secret) {
-  if (!verifyWebhookSignature(payload, signature, secret)) {
+function parseWebhookEvent(payload, signature, secret, timestamp) {
+  if (!verifyWebhookSignature(payload, signature, secret, timestamp)) {
     throw new WebhookSignatureError();
   }
   let event;
@@ -1106,7 +1591,7 @@ function parseWebhookEvent(payload, signature, secret) {
   } catch {
     throw new Error("Failed to parse webhook payload");
   }
-  if (!event.id || !event.type || !event.createdAt) {
+  if (!event.id || !event.type || !event.created || !event.data?.object) {
     throw new Error("Invalid webhook event structure");
   }
   return event;
@@ -1132,25 +1617,78 @@ var Webhooks = class {
    * Verify a webhook signature
    * @param payload - Raw request body
    * @param signature - X-Sendly-Signature header
+   * @param timestamp - X-Sendly-Timestamp header (optional)
    */
-  verify(payload, signature) {
-    return verifyWebhookSignature(payload, signature, this.secret);
+  verify(payload, signature, timestamp) {
+    return verifyWebhookSignature(payload, signature, this.secret, timestamp);
   }
   /**
    * Parse and verify a webhook event
    * @param payload - Raw request body
    * @param signature - X-Sendly-Signature header
+   * @param timestamp - X-Sendly-Timestamp header (optional)
    */
-  parse(payload, signature) {
-    return parseWebhookEvent(payload, signature, this.secret);
+  parse(payload, signature, timestamp) {
+    return parseWebhookEvent(payload, signature, this.secret, timestamp);
   }
   /**
    * Generate a signature for testing
-   * @param payload - Payload to sign
+   * @param payload - Payload to sign (should include timestamp prefix if using timestamps)
    */
   sign(payload) {
     return generateWebhookSignature(payload, this.secret);
   }
+  // ============================================================================
+  // Static methods for backwards compatibility with existing code/tests
+  // ============================================================================
+  /**
+   * Verify a webhook signature (static method for backwards compatibility)
+   * @param payload - Raw request body
+   * @param signature - X-Sendly-Signature header
+   * @param secret - Your webhook secret
+   */
+  static verifySignature(payload, signature, secret) {
+    return verifyWebhookSignature(payload, signature, secret);
+  }
+  /**
+   * Parse and verify a webhook event (static method for backwards compatibility)
+   * @param payload - Raw request body
+   * @param signature - X-Sendly-Signature header
+   * @param secret - Your webhook secret
+   */
+  static parseEvent(payload, signature, secret) {
+    if (!verifyWebhookSignature(payload, signature, secret)) {
+      throw new WebhookSignatureError("Invalid webhook signature");
+    }
+    let event;
+    try {
+      event = JSON.parse(payload);
+    } catch {
+      throw new WebhookSignatureError("Failed to parse webhook payload");
+    }
+    const parsed = event;
+    if (!parsed.id || !parsed.type || !parsed.created_at) {
+      throw new WebhookSignatureError("Invalid event structure");
+    }
+    if (parsed.data && typeof parsed.data === "object" && "message_id" in parsed.data) {
+      return event;
+    }
+    if (parsed.data && typeof parsed.data === "object" && "object" in parsed.data) {
+      return event;
+    }
+    if (!parsed.data) {
+      throw new WebhookSignatureError("Invalid event structure");
+    }
+    return event;
+  }
+  /**
+   * Generate a webhook signature (static method for backwards compatibility)
+   * @param payload - Payload to sign
+   * @param secret - Secret to use for signing
+   */
+  static generateSignature(payload, secret) {
+    return generateWebhookSignature(payload, secret);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {