@sendly/node 3.8.1 → 3.9.0

package/README.md

@@ -1,3 +1,12 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SendlyHQ/sendly-node/main/.github/header.svg" alt="Sendly Node.js SDK" />
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sendly/node"><img src="https://img.shields.io/npm/v/@sendly/node.svg?style=flat-square" alt="npm version" /></a>
+  <a href="https://github.com/SendlyHQ/sendly-node/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@sendly/node.svg?style=flat-square" alt="license" /></a>
+</p>
+
 # @sendly/node
 
 Official Node.js SDK for the [Sendly](https://sendly.live) SMS API.

package/dist/index.d.mts

@@ -842,6 +842,206 @@ declare const SANDBOX_TEST_NUMBERS: {
     /** Fails with carrier_violation error */
     readonly CARRIER_VIOLATION: "+15005550006";
 };
+/**
+ * Verification status
+ */
+type VerificationStatus = "pending" | "verified" | "invalid" | "expired" | "failed";
+/**
+ * Verification delivery status
+ */
+type VerificationDeliveryStatus = "queued" | "sent" | "delivered" | "failed";
+/**
+ * Request to send a verification code
+ */
+interface SendVerificationRequest {
+    /** Destination phone number in E.164 format */
+    to: string;
+    /** Template ID to use (defaults to preset OTP template) */
+    templateId?: string;
+    /** Verify profile ID for custom settings */
+    profileId?: string;
+    /** App name to display in message (defaults to business name) */
+    appName?: string;
+    /** Code validity in seconds (60-3600, default: 300) */
+    timeoutSecs?: number;
+    /** OTP code length (4-10, default: 6) */
+    codeLength?: number;
+}
+/**
+ * Response from sending a verification
+ */
+interface SendVerificationResponse {
+    /** Verification ID */
+    id: string;
+    /** Status (always "pending" initially) */
+    status: VerificationStatus;
+    /** Phone number */
+    phone: string;
+    /** When the code expires (ISO 8601) */
+    expiresAt: string;
+    /** Whether sent in sandbox mode */
+    sandbox: boolean;
+    /** OTP code (only in sandbox mode for testing) */
+    sandboxCode?: string;
+    /** Message about sandbox mode */
+    message?: string;
+}
+/**
+ * Request to check a verification code
+ */
+interface CheckVerificationRequest {
+    /** The OTP code entered by the user */
+    code: string;
+}
+/**
+ * Response from checking a verification
+ */
+interface CheckVerificationResponse {
+    /** Verification ID */
+    id: string;
+    /** Status after check */
+    status: VerificationStatus;
+    /** Phone number */
+    phone: string;
+    /** When verified (ISO 8601) */
+    verifiedAt?: string;
+    /** Remaining attempts (if invalid) */
+    remainingAttempts?: number;
+}
+/**
+ * A verification record
+ */
+interface Verification {
+    /** Verification ID */
+    id: string;
+    /** Status */
+    status: VerificationStatus;
+    /** Phone number */
+    phone: string;
+    /** Delivery status */
+    deliveryStatus: VerificationDeliveryStatus;
+    /** Number of check attempts */
+    attempts: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+    /** When the code expires (ISO 8601) */
+    expiresAt: string;
+    /** When verified (ISO 8601) */
+    verifiedAt?: string | null;
+    /** When created (ISO 8601) */
+    createdAt: string;
+    /** Whether sandbox mode */
+    sandbox: boolean;
+    /** App name used */
+    appName?: string;
+    /** Template ID used */
+    templateId?: string;
+    /** Profile ID used */
+    profileId?: string;
+}
+/**
+ * Options for listing verifications
+ */
+interface ListVerificationsOptions {
+    /** Maximum number to return (1-100, default: 20) */
+    limit?: number;
+    /** Filter by status */
+    status?: VerificationStatus;
+}
+/**
+ * Response from listing verifications
+ */
+interface VerificationListResponse {
+    /** Array of verifications */
+    verifications: Verification[];
+    /** Pagination info */
+    pagination: {
+        limit: number;
+        hasMore: boolean;
+    };
+}
+/**
+ * Template variable definition
+ */
+interface TemplateVariable {
+    /** Variable key (e.g., "code", "app_name") */
+    key: string;
+    /** Variable type */
+    type: "string" | "number";
+    /** Default fallback value */
+    fallback?: string;
+}
+/**
+ * Template status
+ */
+type TemplateStatus = "draft" | "published";
+/**
+ * An SMS template
+ */
+interface Template {
+    /** Template ID */
+    id: string;
+    /** Template name */
+    name: string;
+    /** Message text with {{variables}} */
+    text: string;
+    /** Variables detected in the template */
+    variables: TemplateVariable[];
+    /** Whether this is a preset template */
+    isPreset: boolean;
+    /** Preset slug (e.g., "otp", "2fa") */
+    presetSlug?: string | null;
+    /** Template status */
+    status: TemplateStatus;
+    /** Version number */
+    version: number;
+    /** When published (ISO 8601) */
+    publishedAt?: string | null;
+    /** When created (ISO 8601) */
+    createdAt: string;
+    /** When updated (ISO 8601) */
+    updatedAt: string;
+}
+/**
+ * Request to create a template
+ */
+interface CreateTemplateRequest {
+    /** Template name */
+    name: string;
+    /** Message text (use {{code}} and {{app_name}} variables) */
+    text: string;
+}
+/**
+ * Request to update a template
+ */
+interface UpdateTemplateRequest {
+    /** New template name */
+    name?: string;
+    /** New message text */
+    text?: string;
+}
+/**
+ * Response from listing templates
+ */
+interface TemplateListResponse {
+    /** Array of templates */
+    templates: Template[];
+}
+/**
+ * Template preview with interpolated text
+ */
+interface TemplatePreview {
+    /** Template ID */
+    id: string;
+    /** Template name */
+    name: string;
+    /** Original text with variables */
+    originalText: string;
+    /** Interpolated text with sample values */
+    previewText: string;
+    /** Variables detected */
+    variables: TemplateVariable[];
+}
 
 /**
  * HTTP Client Utility
@@ -1534,6 +1734,266 @@ declare class AccountResource {
     revokeApiKey(id: string): Promise<void>;
 }
 
+/**
+ * Verify Resource - OTP Verification API
+ * @packageDocumentation
+ */
+
+/**
+ * Verify API resource for OTP verification
+ *
+ * @example
+ * ```typescript
+ * // Send an OTP
+ * const verification = await sendly.verify.send({
+ *   to: '+15551234567',
+ *   appName: 'MyApp'
+ * });
+ *
+ * // Check the OTP
+ * const result = await sendly.verify.check(verification.id, {
+ *   code: '123456'
+ * });
+ *
+ * if (result.status === 'verified') {
+ *   console.log('Phone verified!');
+ * }
+ * ```
+ */
+declare class VerifyResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Send an OTP verification code
+     *
+     * @param request - Verification request details
+     * @returns The created verification with ID and expiry
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const verification = await sendly.verify.send({
+     *   to: '+15551234567'
+     * });
+     *
+     * // With custom options
+     * const verification = await sendly.verify.send({
+     *   to: '+15551234567',
+     *   appName: 'MyApp',
+     *   codeLength: 8,
+     *   timeoutSecs: 600
+     * });
+     *
+     * // In sandbox mode, the code is returned for testing
+     * if (verification.sandboxCode) {
+     *   console.log('Test code:', verification.sandboxCode);
+     * }
+     * ```
+     */
+    send(request: SendVerificationRequest): Promise<SendVerificationResponse>;
+    /**
+     * Check/verify an OTP code
+     *
+     * @param id - Verification ID
+     * @param request - The code to verify
+     * @returns Verification result
+     *
+     * @example
+     * ```typescript
+     * const result = await sendly.verify.check('ver_xxx', {
+     *   code: '123456'
+     * });
+     *
+     * if (result.status === 'verified') {
+     *   // User is verified
+     * } else if (result.remainingAttempts !== undefined) {
+     *   console.log(`Wrong code. ${result.remainingAttempts} attempts remaining`);
+     * }
+     * ```
+     */
+    check(id: string, request: CheckVerificationRequest): Promise<CheckVerificationResponse>;
+    /**
+     * Get a verification by ID
+     *
+     * @param id - Verification ID
+     * @returns The verification record
+     *
+     * @example
+     * ```typescript
+     * const verification = await sendly.verify.get('ver_xxx');
+     * console.log(verification.status); // 'pending', 'verified', 'expired', etc.
+     * ```
+     */
+    get(id: string): Promise<Verification>;
+    /**
+     * List recent verifications
+     *
+     * @param options - Filter and pagination options
+     * @returns List of verifications
+     *
+     * @example
+     * ```typescript
+     * // List recent verifications
+     * const { verifications } = await sendly.verify.list({ limit: 10 });
+     *
+     * // Filter by status
+     * const { verifications } = await sendly.verify.list({
+     *   status: 'verified'
+     * });
+     * ```
+     */
+    list(options?: ListVerificationsOptions): Promise<VerificationListResponse>;
+}
+
+/**
+ * Templates Resource - SMS Template Management
+ * @packageDocumentation
+ */
+
+/**
+ * Templates API resource for managing SMS templates
+ *
+ * @example
+ * ```typescript
+ * // List available templates
+ * const { templates } = await sendly.templates.list();
+ *
+ * // Create a custom template
+ * const template = await sendly.templates.create({
+ *   name: 'My OTP',
+ *   text: 'Your {{app_name}} code is {{code}}'
+ * });
+ *
+ * // Publish for use
+ * await sendly.templates.publish(template.id);
+ * ```
+ */
+declare class TemplatesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all templates (presets + custom)
+     *
+     * @returns List of templates
+     *
+     * @example
+     * ```typescript
+     * const { templates } = await sendly.templates.list();
+     * templates.forEach(t => {
+     *   console.log(`${t.name}: ${t.isPreset ? 'preset' : t.status}`);
+     * });
+     * ```
+     */
+    list(): Promise<TemplateListResponse>;
+    /**
+     * List preset templates only (no auth required)
+     *
+     * @returns List of preset templates
+     *
+     * @example
+     * ```typescript
+     * const { templates } = await sendly.templates.presets();
+     * // Returns: otp, 2fa, login, signup, reset, generic
+     * ```
+     */
+    presets(): Promise<TemplateListResponse>;
+    /**
+     * Get a template by ID
+     *
+     * @param id - Template ID
+     * @returns The template
+     *
+     * @example
+     * ```typescript
+     * const template = await sendly.templates.get('tpl_preset_otp');
+     * console.log(template.text); // "Your {{app_name}} code is {{code}}"
+     * ```
+     */
+    get(id: string): Promise<Template>;
+    /**
+     * Create a new template
+     *
+     * @param request - Template details
+     * @returns The created template (as draft)
+     *
+     * @example
+     * ```typescript
+     * const template = await sendly.templates.create({
+     *   name: 'Password Reset',
+     *   text: '{{app_name}}: Your password reset code is {{code}}. Valid for 10 minutes.'
+     * });
+     *
+     * // Template is created as draft, publish when ready
+     * await sendly.templates.publish(template.id);
+     * ```
+     */
+    create(request: CreateTemplateRequest): Promise<Template>;
+    /**
+     * Update a template
+     *
+     * Note: Updating a published template creates a new draft version.
+     *
+     * @param id - Template ID
+     * @param request - Fields to update
+     * @returns The updated template
+     *
+     * @example
+     * ```typescript
+     * const template = await sendly.templates.update('tpl_xxx', {
+     *   text: 'New message text with {{code}}'
+     * });
+     * ```
+     */
+    update(id: string, request: UpdateTemplateRequest): Promise<Template>;
+    /**
+     * Publish a draft template
+     *
+     * Published templates are locked and can be used with the Verify API.
+     *
+     * @param id - Template ID
+     * @returns The published template
+     *
+     * @example
+     * ```typescript
+     * const template = await sendly.templates.publish('tpl_xxx');
+     * console.log(template.status); // 'published'
+     * ```
+     */
+    publish(id: string): Promise<Template>;
+    /**
+     * Preview a template with sample values
+     *
+     * @param id - Template ID
+     * @param variables - Optional custom variable values
+     * @returns Template with interpolated preview text
+     *
+     * @example
+     * ```typescript
+     * const preview = await sendly.templates.preview('tpl_preset_otp', {
+     *   app_name: 'MyApp',
+     *   code: '123456'
+     * });
+     * console.log(preview.previewText);
+     * // "Your MyApp code is 123456"
+     * ```
+     */
+    preview(id: string, variables?: Record<string, string>): Promise<TemplatePreview>;
+    /**
+     * Delete a template
+     *
+     * Note: Preset templates cannot be deleted.
+     *
+     * @param id - Template ID
+     *
+     * @example
+     * ```typescript
+     * await sendly.templates.delete('tpl_xxx');
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    private transformTemplate;
+}
+
 /**
  * Sendly Client
  * @packageDocumentation
@@ -1622,6 +2082,47 @@ declare class Sendly {
      * ```
      */
     readonly account: AccountResource;
+    /**
+     * Verify API resource - OTP verification
+     *
+     * @example
+     * ```typescript
+     * // Send an OTP
+     * const verification = await sendly.verify.send({
+     *   to: '+15551234567',
+     *   appName: 'MyApp'
+     * });
+     *
+     * // Check the OTP (user enters code)
+     * const result = await sendly.verify.check(verification.id, {
+     *   code: '123456'
+     * });
+     *
+     * if (result.status === 'verified') {
+     *   console.log('Phone verified!');
+     * }
+     * ```
+     */
+    readonly verify: VerifyResource;
+    /**
+     * Templates API resource - SMS template management
+     *
+     * @example
+     * ```typescript
+     * // List preset templates
+     * const { templates } = await sendly.templates.presets();
+     *
+     * // Create a custom template
+     * const template = await sendly.templates.create({
+     *   name: 'My OTP',
+     *   text: 'Your {{app_name}} code is {{code}}'
+     * });
+     *
+     * // Publish for use
+     * await sendly.templates.publish(template.id);
+     * ```
+     */
+    readonly templates: TemplatesResource;
     private readonly http;
     private readonly config;
     /**
@@ -2072,4 +2573,4 @@ declare class Webhooks {
  */
 type WebhookMessageData = WebhookMessageObject;
 
-export { ALL_SUPPORTED_COUNTRIES, type Account, type ApiErrorResponse, type ApiKey, AuthenticationError, type BatchListResponse, type BatchMessageItem, type BatchMessageRequest, type BatchMessageResponse, type BatchMessageResult, type BatchStatus, CREDITS_PER_SMS, type CancelledMessageResponse, type CircuitState, type CreateWebhookOptions, type CreditTransaction, type Credits, type DeliveryStatus, InsufficientCreditsError, type ListBatchesOptions, type ListMessagesOptions, type ListScheduledMessagesOptions, type Message, type MessageListResponse, type MessageStatus, type MessageType, NetworkError, NotFoundError, type PricingTier, RateLimitError, type RateLimitInfo, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type ScheduleMessageRequest, type ScheduledMessage, type ScheduledMessageListResponse, type ScheduledMessageStatus, type SendMessageRequest, type SenderType, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, TimeoutError, type UpdateWebhookOptions, ValidationError, type Webhook, type WebhookCreatedResponse, type WebhookDelivery, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, type WebhookSecretRotation, WebhookSignatureError, type WebhookTestResult, Webhooks, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };
+export { ALL_SUPPORTED_COUNTRIES, type Account, type ApiErrorResponse, type ApiKey, AuthenticationError, type BatchListResponse, type BatchMessageItem, type BatchMessageRequest, type BatchMessageResponse, type BatchMessageResult, type BatchStatus, CREDITS_PER_SMS, type CancelledMessageResponse, type CheckVerificationRequest, type CheckVerificationResponse, type CircuitState, type CreateTemplateRequest, type CreateWebhookOptions, type CreditTransaction, type Credits, type DeliveryStatus, InsufficientCreditsError, type ListBatchesOptions, type ListMessagesOptions, type ListScheduledMessagesOptions, type ListVerificationsOptions, type Message, type MessageListResponse, type MessageStatus, type MessageType, NetworkError, NotFoundError, type PricingTier, RateLimitError, type RateLimitInfo, SANDBOX_TEST_NUMBERS, SUPPORTED_COUNTRIES, type ScheduleMessageRequest, type ScheduledMessage, type ScheduledMessageListResponse, type ScheduledMessageStatus, type SendMessageRequest, type SendVerificationRequest, type SendVerificationResponse, type SenderType, Sendly, type SendlyConfig, SendlyError, type SendlyErrorCode, type Template, type TemplateListResponse, type TemplatePreview, type TemplateStatus, type TemplateVariable, TimeoutError, type UpdateTemplateRequest, type UpdateWebhookOptions, ValidationError, type Verification, type VerificationDeliveryStatus, type VerificationListResponse, type VerificationStatus, type Webhook, type WebhookCreatedResponse, type WebhookDelivery, type WebhookEvent, type WebhookEventType, type WebhookMessageData, type WebhookMessageStatus, type WebhookSecretRotation, WebhookSignatureError, type WebhookTestResult, Webhooks, calculateSegments, Sendly as default, generateWebhookSignature, getCountryFromPhone, isCountrySupported, parseWebhookEvent, validateMessageText, validatePhoneNumber, validateSenderId, verifyWebhookSignature };