diff --git a/packages/sms/lib/classes/Error/MessageSendAllFailure.ts b/packages/sms/lib/classes/Error/MessageSendAllFailure.ts index 0fec45ef..e69fd7ab 100644 --- a/packages/sms/lib/classes/Error/MessageSendAllFailure.ts +++ b/packages/sms/lib/classes/Error/MessageSendAllFailure.ts @@ -1,7 +1,21 @@ -import { SMSMessages } from '../../interfaces'; +import { SMSMessages } from '../../types'; import { SMSFailure } from './SMSFailure'; +/** + * Class representing a failure when sending all SMS messages. + * + * Extends the SMSFailure class and is used to indicate that all SMS messages failed to send. + * + * @class + * @extends {SMSFailure} + */ export class MessageSendAllFailure extends SMSFailure { + /** + * Creates an instance of MessageSendAllFailure. + * + * @constructor + * @param {SMSMessages} response - The response containing details about the failed SMS messages. + */ constructor(response: SMSMessages) { super('All SMS messages failed to send', response); } diff --git a/packages/sms/lib/classes/Error/MessageSendPartialFailure.ts b/packages/sms/lib/classes/Error/MessageSendPartialFailure.ts index 0277dee4..4cdd90bd 100644 --- a/packages/sms/lib/classes/Error/MessageSendPartialFailure.ts +++ b/packages/sms/lib/classes/Error/MessageSendPartialFailure.ts @@ -1,7 +1,21 @@ -import { SMSMessages } from '../../interfaces'; +import { SMSMessages } from '../../types'; import { SMSFailure } from './SMSFailure'; +/** + * Class representing a partial failure when sending SMS messages. + * + * Extends the SMSFailure class and is used to indicate that some SMS messages failed to send. + * + * @class + * @extends {SMSFailure} + */ export class MessageSendPartialFailure extends SMSFailure { + /** + * Creates an instance of MessageSendPartialFailure. + * + * @constructor + * @param {SMSMessages} response - The response containing details about the partially failed SMS messages. + */ constructor(response: SMSMessages) { super('Some SMS messages failed to send', response); } diff --git a/packages/sms/lib/classes/Error/SMSFailure.ts b/packages/sms/lib/classes/Error/SMSFailure.ts index 6dd0de70..e96015cb 100644 --- a/packages/sms/lib/classes/Error/SMSFailure.ts +++ b/packages/sms/lib/classes/Error/SMSFailure.ts @@ -1,28 +1,67 @@ import { SMSStatus } from '../../enums'; -import { SMSMessages, ErrorMessage, Message } from '../../interfaces/index'; +import { SMSMessages, ErrorMessage, Message } from '../../types'; +/** + * Class representing a failure response when sending SMS messages. + * + * Extends the built-in Error class and provides methods for accessing and handling failed SMS messages. + * + * @class + * @extends {Error} + */ export class SMSFailure extends Error { + /** + * The response containing details about the SMS messages. + * @protected + */ protected response: SMSMessages; + /** + * Creates an instance of SMSFailure. + * + * @constructor + * @param {string} message - The error message. + * @param {SMSMessages} response - The response containing details about the SMS messages. + */ constructor(message: string, response: SMSMessages) { super(message); this.response = response; } + /** + * Retrieves an array of all messages in the response. + * + * @return {Array} An array of all messages in the response. + */ public getMessages(): Array { return (this.response.messages as Array) || []; } + /** + * Retrieves an array of failed messages in the response. + * + * @return {Array} An array of failed messages in the response. + */ public getFailedMessages(): Array { return this.getMessages().filter( ({ status }: ErrorMessage) => status !== SMSStatus.SUCCESS, ); } + /** + * Retrieves the original response containing details about the SMS messages. + * + * @return {SMSMessages} The original response containing details about the SMS messages. + */ public getResponse(): SMSMessages { return this.response; } + /** + * Retrieves an array of successfully sent messages in the response. + * + * @return {Array} An array of successfully sent messages in the response. + */ public getSuccessfulMessages(): Array { return this.getMessages().filter( ({ status }: Message) => status === SMSStatus.SUCCESS, diff --git a/packages/sms/lib/enums/CollectionFormats.ts b/packages/sms/lib/enums/CollectionFormats.ts index d3599cf3..4b14879c 100644 --- a/packages/sms/lib/enums/CollectionFormats.ts +++ b/packages/sms/lib/enums/CollectionFormats.ts @@ -1,6 +1,30 @@ +/** + * Collection Formats for API Parameter Serialization. + * + * Defines various collection formats used for serializing API parameters. + * + * @constant + * @enum {string} + * @readonly + */ export const COLLECTION_FORMATS = { + /** + * Comma-separated values collection format. + */ csv: ',', + + /** + * Space-separated values collection format. + */ ssv: ' ', + + /** + * Tab-separated values collection format. + */ tsv: '\t', + + /** + * Pipe-separated values collection format. + */ pipes: '|', }; diff --git a/packages/sms/lib/enums/MessageClassEnum.ts b/packages/sms/lib/enums/MessageClassEnum.ts index b1426ec5..685584f3 100644 --- a/packages/sms/lib/enums/MessageClassEnum.ts +++ b/packages/sms/lib/enums/MessageClassEnum.ts @@ -1,6 +1,29 @@ +/** + * Enumeration representing the possible message classes. + * + * Defines different message classes that can be associated with SMS messages. + * + * @enum {number} + * @readonly + */ export enum MessageClassEnum { - NUMBER_0 = 0, - NUMBER_1 = 1, - NUMBER_2 = 2, - NUMBER_3 = 3, + /** + * Class 0: Flash SMS. + */ + NUMBER_0 = 0, + + /** + * Class 1: Immediate display (user should be able to read the message instantly). + */ + NUMBER_1 = 1, + + /** + * Class 2: Mobile equipment-to-mobile equipment (ME-to-ME) communication. + */ + NUMBER_2 = 2, + + /** + * Class 3: SIM card-based storage. + */ + NUMBER_3 = 3, } diff --git a/packages/sms/lib/enums/SMSErrors.ts b/packages/sms/lib/enums/SMSErrors.ts index 078165d9..a3be3e7f 100644 --- a/packages/sms/lib/enums/SMSErrors.ts +++ b/packages/sms/lib/enums/SMSErrors.ts @@ -1,22 +1,112 @@ -export enum SMSStatus { - SUCCESS = '0', - THROTTLED = '1', - MISSING_REQUIRED_PARAM = '2', - INVALID_PARAM = '3', - INVALID_CREDENTIALS = '4', - INTERNAL_ERROR = '5', - INVALID_MESSAGE = '6', - BARRED_NUMBER = '7', - PARTNER_ACCOUNT_BARRED = '7', - PARTNER_QUOTA_violation = '9', - TOO_MANY_EXISTING_BINDS = '10', - ACCOUNT_NOT_ENABLED = '11', - MESSAGE_TOO_LONG = '12', - INVALID_SIGNATURE = '14', - INVALID_SENDER_ADDRESS = '15', - INVALID_NETWORK_CODE = '22', - INVALID_CALLBACK_URL = '23', - NON_WHITELISTED_DESTINATION = '29', - SIGNATURE_AND_API_SECRET_DISALLOWED = '32', - NUMBER_DEACTIVATED = '33', +/** + * Enumeration representing possible SMS status codes. + * + * Defines different status codes that can be associated with SMS messages. + * + * @remarks This matches SMSStatus. Since Enums can't be joined, this is here + * to help check valid statuses + * + * @enum {string} + * @readonly + */ +export enum SMSErrors { + /** + * Success: The message was sent successfully. + */ + SUCCESS = '0', + + /** + * Throttled: Sending SMS faster than the account limit. + */ + THROTTLED = '1', + + /** + * Missing Required Parameter: One or more required parameters are missing. + */ + MISSING_REQUIRED_PARAM = '2', + + /** + * Invalid Parameter: The value of one or more parameters is invalid. + */ + INVALID_PARAM = '3', + + /** + * Invalid Credentials: API key and/or secret are incorrect, invalid, or disabled. + */ + INVALID_CREDENTIALS = '4', + + /** + * Internal Error: An error occurred while processing the message. + */ + INTERNAL_ERROR = '5', + + /** + * Invalid Message: The platform was unable to process the message. + */ + INVALID_MESSAGE = '6', + + /** + * Barred Number: The number you're trying to send messages to is blacklisted. + */ + BARRED_NUMBER = '7', + + /** + * Partner Account Barred: Your Vonage account has been suspended. + */ + PARTNER_ACCOUNT_BARRED = '7', + + /** + * Partner Quota Violation: Insufficient credit to send the message. + */ + PARTNER_QUOTA_VIOLATION = '9', + + /** + * Too Many Existing Binds: Number of simultaneous connections exceeds account allocation. + */ + TOO_MANY_EXISTING_BINDS = '10', + + /** + * Account Not Enabled For HTTP: Account is not provisioned for the SMS API. + */ + ACCOUNT_NOT_ENABLED = '11', + + /** + * Message Too Long: Message length exceeds the maximum allowed. + */ + MESSAGE_TOO_LONG = '12', + + /** + * Invalid Signature: The supplied signature could not be verified. + */ + INVALID_SIGNATURE = '14', + + /** + * Invalid Sender Address: Using a non-authorized sender ID in the 'from' field. + */ + INVALID_SENDER_ADDRESS = '15', + + /** + * Invalid Network Code: Network code is unrecognized or doesn't match the destination. + */ + INVALID_NETWORK_CODE = '22', + + /** + * Invalid Callback URL: Callback URL is too long or contains illegal characters. + */ + INVALID_CALLBACK_URL = '23', + + /** + * Non-Whitelisted Destination: Vonage account is in demo mode and requires whitelisted numbers. + */ + NON_WHITELISTED_DESTINATION = '29', + + /** + * Signature And API Secret Disallowed: A signed request may not present an API secret. + */ + SIGNATURE_AND_API_SECRET_DISALLOWED = '32', + + /** + * Number Deactivated: The number you're trying to send messages to is deactivated. + */ + NUMBER_DEACTIVATED = '33', } diff --git a/packages/sms/lib/enums/SMSStatus.ts b/packages/sms/lib/enums/SMSStatus.ts index 078165d9..6c100d70 100644 --- a/packages/sms/lib/enums/SMSStatus.ts +++ b/packages/sms/lib/enums/SMSStatus.ts @@ -1,22 +1,112 @@ +/** + * Enumeration representing possible SMS status codes. + * + * Defines different status codes that can be associated with SMS messages. + * + * @remarks This matches SMSErrors. Since Enums can't be joined, this is here + * to help check valid statuses + * + * @enum {string} + * @readonly + */ export enum SMSStatus { - SUCCESS = '0', - THROTTLED = '1', - MISSING_REQUIRED_PARAM = '2', - INVALID_PARAM = '3', - INVALID_CREDENTIALS = '4', - INTERNAL_ERROR = '5', - INVALID_MESSAGE = '6', - BARRED_NUMBER = '7', - PARTNER_ACCOUNT_BARRED = '7', - PARTNER_QUOTA_violation = '9', - TOO_MANY_EXISTING_BINDS = '10', - ACCOUNT_NOT_ENABLED = '11', - MESSAGE_TOO_LONG = '12', - INVALID_SIGNATURE = '14', - INVALID_SENDER_ADDRESS = '15', - INVALID_NETWORK_CODE = '22', - INVALID_CALLBACK_URL = '23', - NON_WHITELISTED_DESTINATION = '29', - SIGNATURE_AND_API_SECRET_DISALLOWED = '32', - NUMBER_DEACTIVATED = '33', + /** + * Success: The message was sent successfully. + */ + SUCCESS = '0', + + /** + * Throttled: Sending SMS faster than the account limit. + */ + THROTTLED = '1', + + /** + * Missing Required Parameter: One or more required parameters are missing. + */ + MISSING_REQUIRED_PARAM = '2', + + /** + * Invalid Parameter: The value of one or more parameters is invalid. + */ + INVALID_PARAM = '3', + + /** + * Invalid Credentials: API key and/or secret are incorrect, invalid, or disabled. + */ + INVALID_CREDENTIALS = '4', + + /** + * Internal Error: An error occurred while processing the message. + */ + INTERNAL_ERROR = '5', + + /** + * Invalid Message: The platform was unable to process the message. + */ + INVALID_MESSAGE = '6', + + /** + * Barred Number: The number you're trying to send messages to is blacklisted. + */ + BARRED_NUMBER = '7', + + /** + * Partner Account Barred: Your Vonage account has been suspended. + */ + PARTNER_ACCOUNT_BARRED = '7', + + /** + * Partner Quota Violation: Insufficient credit to send the message. + */ + PARTNER_QUOTA_VIOLATION = '9', + + /** + * Too Many Existing Binds: Number of simultaneous connections exceeds account allocation. + */ + TOO_MANY_EXISTING_BINDS = '10', + + /** + * Account Not Enabled For HTTP: Account is not provisioned for the SMS API. + */ + ACCOUNT_NOT_ENABLED = '11', + + /** + * Message Too Long: Message length exceeds the maximum allowed. + */ + MESSAGE_TOO_LONG = '12', + + /** + * Invalid Signature: The supplied signature could not be verified. + */ + INVALID_SIGNATURE = '14', + + /** + * Invalid Sender Address: Using a non-authorized sender ID in the 'from' field. + */ + INVALID_SENDER_ADDRESS = '15', + + /** + * Invalid Network Code: Network code is unrecognized or doesn't match the destination. + */ + INVALID_NETWORK_CODE = '22', + + /** + * Invalid Callback URL: Callback URL is too long or contains illegal characters. + */ + INVALID_CALLBACK_URL = '23', + + /** + * Non-Whitelisted Destination: Vonage account is in demo mode and requires whitelisted numbers. + */ + NON_WHITELISTED_DESTINATION = '29', + + /** + * Signature And API Secret Disallowed: A signed request may not present an API secret. + */ + SIGNATURE_AND_API_SECRET_DISALLOWED = '32', + + /** + * Number Deactivated: The number you're trying to send messages to is deactivated. + */ + NUMBER_DEACTIVATED = '33', } diff --git a/packages/sms/lib/enums/TypeEnum.ts b/packages/sms/lib/enums/TypeEnum.ts index 3f963223..6dde0167 100644 --- a/packages/sms/lib/enums/TypeEnum.ts +++ b/packages/sms/lib/enums/TypeEnum.ts @@ -1,5 +1,24 @@ +/** + * Enumeration representing possible message types for SMS. + * + * Defines different message types that can be associated with SMS messages. + * + * @enum {string} + * @readonly + */ export enum TypeEnum { - TEXT = 'text', - BINARY = 'binary', - UNICODE = 'unicode', + /** + * Text: The message body contains standard text. + */ + TEXT = 'text', + + /** + * Binary: The message body is in binary format. + */ + BINARY = 'binary', + + /** + * Unicode: The message body is URL-encoded Unicode, valid for various character sets. + */ + UNICODE = 'unicode', } diff --git a/packages/sms/lib/index.ts b/packages/sms/lib/index.ts index 60c2d556..3ce601d6 100644 --- a/packages/sms/lib/index.ts +++ b/packages/sms/lib/index.ts @@ -1,5 +1,4 @@ -export * from './classes/index'; -export * from './enums/index'; -export * from './interfaces/index'; +export * from './classes'; +export * from './enums'; export * from './sms'; -export * from './types/index'; +export * from './types'; diff --git a/packages/sms/lib/interfaces/ErrorMessage.ts b/packages/sms/lib/interfaces/ErrorMessage.ts deleted file mode 100644 index a2c4ee2e..00000000 --- a/packages/sms/lib/interfaces/ErrorMessage.ts +++ /dev/null @@ -1,4 +0,0 @@ -export interface ErrorMessage { - status?: string - errorText?: string -} diff --git a/packages/sms/lib/interfaces/InboundMessage.ts b/packages/sms/lib/interfaces/InboundMessage.ts deleted file mode 100644 index e393c6c7..00000000 --- a/packages/sms/lib/interfaces/InboundMessage.ts +++ /dev/null @@ -1,18 +0,0 @@ -export interface InboundMessage { - 'api-key': string - msisdn: string - to: string - messageId: string - text: string - type: string - keyword: string - 'message-timestamp': string - timestamp: string - nonce: string - concat: string - 'concat-ref': string - 'concat-total': string - 'concat-part': string - data: string - udh: string -} diff --git a/packages/sms/lib/interfaces/Message.ts b/packages/sms/lib/interfaces/Message.ts deleted file mode 100644 index d6ac58b0..00000000 --- a/packages/sms/lib/interfaces/Message.ts +++ /dev/null @@ -1,9 +0,0 @@ -import { SMSMessageResponse } from './Response/index'; - -export interface Message extends SMSMessageResponse { - messageId?: string - remainingBalance?: string - messagePrice?: string - clientRef?: string - accountRef?: string -} diff --git a/packages/sms/lib/interfaces/Request/SMSRequestBody.ts b/packages/sms/lib/interfaces/Request/SMSRequestBody.ts deleted file mode 100644 index 33b5c67d..00000000 --- a/packages/sms/lib/interfaces/Request/SMSRequestBody.ts +++ /dev/null @@ -1,20 +0,0 @@ -import { MessageClassEnum, TypeEnum } from '../../enums/index'; - -export interface SMSRequestBody { - to: string - from: string - text?: string - body?: string - 'type?': TypeEnum - 'ttl?': number - 'client_ref?': string - 'callback?': string - 'message_class?': number - 'udh?': string - 'protocol-id'?: number - 'status-report-req'?: boolean - 'message-class'?: MessageClassEnum - 'client-ref'?: string - 'entity-id'?: string - 'content-id'?: string -} diff --git a/packages/sms/lib/interfaces/Response/DeliveryReceipt.ts b/packages/sms/lib/interfaces/Response/DeliveryReceipt.ts deleted file mode 100644 index 8e51894b..00000000 --- a/packages/sms/lib/interfaces/Response/DeliveryReceipt.ts +++ /dev/null @@ -1,16 +0,0 @@ -export interface DeliveryReceipt { - msisdn?: string - to?: string - networkCode?: string - messageId?: string - price?: string - status?: string - scts?: string - errCode?: string - apiKey?: string - clientRef?: string - messageTimestamp?: string - timestamp?: string - nonce?: string - sig?: string -} diff --git a/packages/sms/lib/interfaces/Response/SMSEmptyResponse.ts b/packages/sms/lib/interfaces/Response/SMSEmptyResponse.ts deleted file mode 100644 index 765ef6d8..00000000 --- a/packages/sms/lib/interfaces/Response/SMSEmptyResponse.ts +++ /dev/null @@ -1,7 +0,0 @@ -/** - * @deprecated there is no subsistution for this - */ -export interface SMSEmptyResponse { - errorCode?: string - errorCodeLabel?: string -} diff --git a/packages/sms/lib/interfaces/Response/SMSErrorMessageResponse.ts b/packages/sms/lib/interfaces/Response/SMSErrorMessageResponse.ts deleted file mode 100644 index 9044a620..00000000 --- a/packages/sms/lib/interfaces/Response/SMSErrorMessageResponse.ts +++ /dev/null @@ -1,6 +0,0 @@ -import { SMSStatus } from '../../enums/SMSErrors'; - -export interface SMSErrorMessageResponse { - status: SMSStatus - 'error-text': string -} diff --git a/packages/sms/lib/interfaces/Response/SMSGeneralResponse.ts b/packages/sms/lib/interfaces/Response/SMSGeneralResponse.ts deleted file mode 100644 index a0f45bb6..00000000 --- a/packages/sms/lib/interfaces/Response/SMSGeneralResponse.ts +++ /dev/null @@ -1,6 +0,0 @@ -import { SMSResponse } from './SMSResponse'; - -/** - * @deprecated please use SMSResponse - */ -export type SMSGeneralResponse = SMSResponse diff --git a/packages/sms/lib/interfaces/Response/SMSMessageResponse.ts b/packages/sms/lib/interfaces/Response/SMSMessageResponse.ts deleted file mode 100644 index f7ced1f7..00000000 --- a/packages/sms/lib/interfaces/Response/SMSMessageResponse.ts +++ /dev/null @@ -1,12 +0,0 @@ -import { SMSStatus } from '../../enums/SMSErrors'; - -export interface SMSMessageResponse { - to: string - 'message-id': string - status: SMSStatus - 'remaining-balance': string - 'message-price': string - network: string - 'client-ref'?: string - 'account-ref'?: string -} diff --git a/packages/sms/lib/interfaces/Response/SMSResponse.ts b/packages/sms/lib/interfaces/Response/SMSResponse.ts deleted file mode 100644 index 4908cbee..00000000 --- a/packages/sms/lib/interfaces/Response/SMSResponse.ts +++ /dev/null @@ -1,7 +0,0 @@ -import { SMSErrorMessageResponse } from './SMSErrorMessageResponse'; -import { SMSMessageResponse } from './SMSMessageResponse'; - -export interface SMSResponse { - 'message-count': number - messages: SMSMessageResponse[] | SMSErrorMessageResponse[] -} diff --git a/packages/sms/lib/interfaces/Response/SendSMSResponse.ts b/packages/sms/lib/interfaces/Response/SendSMSResponse.ts deleted file mode 100644 index b4ccfd2d..00000000 --- a/packages/sms/lib/interfaces/Response/SendSMSResponse.ts +++ /dev/null @@ -1,6 +0,0 @@ -import { SMSResponse } from './SMSResponse'; - -/** - * @deprecated please use SMSResponse - */ -export type SendSMSResponse = SMSResponse diff --git a/packages/sms/lib/interfaces/SMSMessages.ts b/packages/sms/lib/interfaces/SMSMessages.ts deleted file mode 100644 index 52e97b8b..00000000 --- a/packages/sms/lib/interfaces/SMSMessages.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { ErrorMessage } from './ErrorMessage'; -import { Message } from './Message'; -import { SMSResponse } from './Response/index'; - -export interface SMSMessages extends SMSResponse { - messageCount: number - messages: Array -} diff --git a/packages/sms/lib/interfaces/index.ts b/packages/sms/lib/interfaces/index.ts deleted file mode 100644 index b51011f4..00000000 --- a/packages/sms/lib/interfaces/index.ts +++ /dev/null @@ -1,6 +0,0 @@ -export * from './ErrorMessage'; -export * from './InboundMessage'; -export * from './Message'; -export * from './Response/index'; -export * from './Response/index'; -export * from './SMSMessages'; diff --git a/packages/sms/lib/sms.ts b/packages/sms/lib/sms.ts index b6c80e49..cf8c823d 100644 --- a/packages/sms/lib/sms.ts +++ b/packages/sms/lib/sms.ts @@ -2,14 +2,36 @@ import { Client } from '@vonage/server-client'; import { MessageSendAllFailure, MessageSendPartialFailure, -} from './classes/index'; -import { SMSMessages, SMSResponse, Message } from './interfaces/index'; -import { SMSParams } from './types/index'; -import { SMSStatus } from './enums/index'; +} from './classes'; +import { + SMSMessages, + SMSResponse, + Message, + SMSParams, + SMSMessageResponse, +} from './types'; +import { SMSStatus } from './enums'; import crypto from 'crypto'; import { AlgorithmTypes } from '@vonage/auth'; +/** + * Class representing an SMS client for sending SMS messages using the Vonage API. + * + * Extends the Vonage Client class and provides methods for sending SMS messages and verifying signatures. + * + * @class + * @extends {Client} + */ export class SMS extends Client { + /** + * Sends an SMS message using the Vonage API. + * + * @async + * @param {SMSParams} [params] - The parameters for the SMS message. + * @return {Promise} A Promise that resolves to the response containing details about the sent SMS messages. + * @throws {MessageSendAllFailure} If all SMS messages fail to send. + * @throws {MessageSendPartialFailure} If some SMS messages fail to send. + */ public async send(params?: SMSParams): Promise { const resp = await this.sendPostRequest( `${this.config.restHost}/sms/json`, @@ -20,7 +42,7 @@ export class SMS extends Client { resp.data, true, true, - ); + ) as SMSMessages; const totalMessages = messageData.messageCount || 0; const messages = (messageData.messages as Array) || []; @@ -41,6 +63,16 @@ export class SMS extends Client { throw new MessageSendPartialFailure(messageData); } + /** + * Verifies the signature of a request using the specified algorithm and signature secret. + * + * @param {string} signature - The signature to be verified. + * @param {string | { [key: string]: string }} params - The request parameters used to generate the signature. + * @param {string} signatureSecret - The secret key used for generating the signature. + * @param {AlgorithmTypes} algorithm - The algorithm used for generating the signature. + * @return {boolean} `true` if the signature is valid, `false` otherwise. + * @throws {Error} If the provided signature algorithm is not supported. + */ public verifySignature( signature: string, params: string | { [key: string]: string }, diff --git a/packages/sms/lib/types.ts b/packages/sms/lib/types.ts deleted file mode 100644 index 134057a7..00000000 --- a/packages/sms/lib/types.ts +++ /dev/null @@ -1,34 +0,0 @@ -export * from './classes/index'; -export * from './enums/index'; -export * from './interfaces/index'; -export * from './types/index'; - -import { ErrorMessage } from './interfaces/ErrorMessage'; -import { Message } from './interfaces/Message'; -import debug from 'debug'; - -const log = debug('vonage:sms'); - -log('Importing from the types.ts is depreacted and will be removed'); - -/** - * @deprecated no replacement for this - */ -export interface ErrorXml { - messages?: ErrorMessage[] -} - -/** - * @deprecated no replacement for this - */ -export interface ModelError { - messageCount?: string - messages?: ErrorMessage[] -} - -/** - * @deprecated no replacement for this - */ -export interface SMSXml { - messages?: Message[] -} diff --git a/packages/sms/lib/types/ErrorMessage.ts b/packages/sms/lib/types/ErrorMessage.ts new file mode 100644 index 00000000..db15535e --- /dev/null +++ b/packages/sms/lib/types/ErrorMessage.ts @@ -0,0 +1,16 @@ +/** + * Interface representing an error message. + * + * Describes the structure of an error message containing status and error text. + */ +export type ErrorMessage = { + /** + * The status code indicating the error (optional). + */ + status?: string; + + /** + * The error text providing details about the error (optional). + */ + errorText?: string; +} diff --git a/packages/sms/lib/types/InboundMessage.ts b/packages/sms/lib/types/InboundMessage.ts new file mode 100644 index 00000000..680ac024 --- /dev/null +++ b/packages/sms/lib/types/InboundMessage.ts @@ -0,0 +1,86 @@ +/** + * Interface representing an inbound SMS message. + * + * Describes the structure of an inbound SMS message, including its properties and details. + */ +export type InboundMessage = { + /** + * The Vonage API Key of the receiving account. + */ + 'api-key': string; + + /** + * The phone number that this inbound message was sent from in E.164 format. + */ + msisdn: string; + + /** + * The phone number the message was sent to (virtual number) in E.164 format. + */ + to: string; + + /** + * The unique ID of the inbound message. + */ + messageId: string; + + /** + * The message body for this inbound message. + */ + text: string; + + /** + * The format of the message body. + */ + type: string; + + /** + * The first word in the message body, converted to uppercase. + */ + keyword: string; + + /** + * The time when Vonage started to push this Delivery Receipt to your webhook endpoint. + */ + 'message-timestamp': string; + + /** + * A Unix timestamp representation of 'message-timestamp'. + */ + timestamp: string; + + /** + * A random string that forms part of the signed set of parameters for validation. + */ + nonce: string; + + /** + * Indicates whether this is a concatenated message. + */ + concat: string; + + /** + * The transaction reference for concatenated messages. + */ + 'concat-ref': string; + + /** + * The total number of parts in this concatenated message. + */ + 'concat-total': string; + + /** + * The number of this part in the concatenated message. + */ + 'concat-part': string; + + /** + * The content of this message, if the type is binary. + */ + data: string; + + /** + * The hex encoded User Data Header, if the type is binary. + */ + udh: string; +} diff --git a/packages/sms/lib/types/Message.ts b/packages/sms/lib/types/Message.ts new file mode 100644 index 00000000..71a3e149 --- /dev/null +++ b/packages/sms/lib/types/Message.ts @@ -0,0 +1,35 @@ +import { SMSMessageResponse } from './Responses'; + +/** + * Interface representing an SMS message. + * + * Extends the structure of an SMS message response and includes additional optional properties. + * + * @extends {SMSMessageResponse} + */ +export type Message = SMSMessageResponse & { + /** + * The unique ID of the SMS message (optional). + */ + messageId?: string; + + /** + * Your estimated remaining balance after sending the SMS (optional). + */ + remainingBalance?: string; + + /** + * The estimated cost of the SMS message (optional). + */ + messagePrice?: string; + + /** + * Your client reference for the message (optional). + */ + clientRef?: string; + + /** + * An optional string used to identify separate accounts using the SMS endpoint for billing purposes (optional). + */ + accountRef?: string; +} diff --git a/packages/sms/lib/types/Requests/SMSRequestBody.ts b/packages/sms/lib/types/Requests/SMSRequestBody.ts new file mode 100644 index 00000000..f197b8b7 --- /dev/null +++ b/packages/sms/lib/types/Requests/SMSRequestBody.ts @@ -0,0 +1,88 @@ +import { MessageClassEnum, TypeEnum } from '../../enums'; + +/** + * Interface representing the request body for sending an SMS. + * + * Describes the structure of the request body used when sending an SMS message. + */ +export type SMSRequestBody = { + /** + * The recipient's phone number in E.164 format. + */ + to: string; + + /** + * The sender's name or number, specified in E.164 format. + */ + from: string; + + /** + * The body of the message being sent (optional). + */ + text?: string; + + /** + * Hex-encoded binary data (optional). + */ + body?: string; + + /** + * The format of the message body (optional). + */ + 'type?': TypeEnum; + + /** + * The duration in milliseconds for delivery attempts (optional). + */ + 'ttl?': number; + + /** + * Your own reference for the message (optional). + */ + 'client_ref?': string; + + /** + * The webhook endpoint for the delivery receipt (optional). + */ + 'callback?': string; + + /** + * The Data Coding Scheme value of the message (optional). + */ + 'message_class?': number; + + /** + * Custom Hex-encoded User Data Header (optional). + */ + 'udh?': string; + + /** + * The value of the protocol identifier to use (optional). + */ + 'protocol-id'?: number; + + /** + * Boolean indicating if a Delivery Receipt is requested (optional). + */ + 'status-report-req'?: boolean; + + /** + * The Data Coding Scheme value of the message (optional). + */ + 'message-class'?: MessageClassEnum; + + /** + * Your own reference for the message (optional). + */ + 'client-ref'?: string; + + /** + * A string parameter for regulatory requirements (optional). + */ + 'entity-id'?: string; + + /** + * A string parameter for regulatory requirements (optional). + */ + 'content-id'?: string; +} diff --git a/packages/sms/lib/interfaces/Request/index.ts b/packages/sms/lib/types/Requests/index.ts similarity index 100% rename from packages/sms/lib/interfaces/Request/index.ts rename to packages/sms/lib/types/Requests/index.ts diff --git a/packages/sms/lib/types/Responses/DeliveryReceipt.ts b/packages/sms/lib/types/Responses/DeliveryReceipt.ts new file mode 100644 index 00000000..d6504e23 --- /dev/null +++ b/packages/sms/lib/types/Responses/DeliveryReceipt.ts @@ -0,0 +1,76 @@ +/** + * Interface representing a delivery receipt for an SMS message. + * + * Describes the structure of a delivery receipt containing information about the message's delivery status. + */ +export type DeliveryReceipt = { + /** + * The recipient's phone number in E.164 format (optional). + */ + msisdn?: string; + + /** + * The SenderID set in the 'from' field of the request (optional). + */ + to?: string; + + /** + * The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier (optional). + */ + networkCode?: string; + + /** + * The Vonage ID for this message (optional). + */ + messageId?: string; + + /** + * The cost of the message (optional). + */ + price?: string; + + /** + * A code explaining the message's delivery status (optional). + */ + status?: string; + + /** + * When the Delivery Receipt was received from the carrier in YYMMDDHHMM format (optional). + */ + scts?: string; + + /** + * The status of the request (optional). + */ + errCode?: string; + + /** + * The API key that sent the SMS (optional). + */ + apiKey?: string; + + /** + * Your client reference for the message (optional). + */ + clientRef?: string; + + /** + * The time when Vonage started to push this Delivery Receipt to your webhook endpoint (optional). + */ + messageTimestamp?: string; + + /** + * A Unix timestamp representation of 'messageTimestamp' (optional). + */ + timestamp?: string; + + /** + * A random string forming part of the signed set of parameters for validation (optional). + */ + nonce?: string; + + /** + * The hash of the request parameters, a timestamp, and the signature secret (optional). + */ + sig?: string; +} diff --git a/packages/sms/lib/types/Responses/SMSEmptyResponse.ts b/packages/sms/lib/types/Responses/SMSEmptyResponse.ts new file mode 100644 index 00000000..ab0d8dc7 --- /dev/null +++ b/packages/sms/lib/types/Responses/SMSEmptyResponse.ts @@ -0,0 +1,16 @@ +/** + * Deprecated interface for an empty SMS response. + * + * @deprecated There is no substitution for this interface. + */ +export type SMSEmptyResponse = { + /** + * The error code, if applicable (optional). + */ + errorCode?: string; + + /** + * A label for the error code, if provided (optional). + */ + errorCodeLabel?: string; +} diff --git a/packages/sms/lib/types/Responses/SMSErrorMessageResponse.ts b/packages/sms/lib/types/Responses/SMSErrorMessageResponse.ts new file mode 100644 index 00000000..81f52269 --- /dev/null +++ b/packages/sms/lib/types/Responses/SMSErrorMessageResponse.ts @@ -0,0 +1,18 @@ +import { SMSStatus } from '../../enums'; + +/** + * Interface representing an SMS error message response. + * + * Describes the structure of a response containing an SMS status and error text. + */ +export type SMSErrorMessageResponse = { + /** + * The SMS status code indicating the error. + */ + status: SMSStatus; + + /** + * The error text providing details about the error. + */ + 'error-text': string; +} diff --git a/packages/sms/lib/types/Responses/SMSGeneralResponse.ts b/packages/sms/lib/types/Responses/SMSGeneralResponse.ts new file mode 100644 index 00000000..f2548ab4 --- /dev/null +++ b/packages/sms/lib/types/Responses/SMSGeneralResponse.ts @@ -0,0 +1,11 @@ +import { SMSResponse } from './SMSResponse'; + +/** + * Deprecated type alias for `SMSResponse`. + * + * Please use `SMSResponse` instead. + * + * @deprecated Use `SMSResponse` instead. + * @type {SMSResponse} + */ +export type SMSGeneralResponse = SMSResponse; diff --git a/packages/sms/lib/types/Responses/SMSMessageResponse.ts b/packages/sms/lib/types/Responses/SMSMessageResponse.ts new file mode 100644 index 00000000..2fb8b282 --- /dev/null +++ b/packages/sms/lib/types/Responses/SMSMessageResponse.ts @@ -0,0 +1,47 @@ +import { SMSStatus } from '../../enums/SMSErrors'; +/** + * Interface representing an SMS message response. + * + * Describes the structure of a response containing information about an SMS message's status and details. + */ +export type SMSMessageResponse = { + /** + * The recipient's phone number in E.164 format. + */ + to: string; + + /** + * The unique ID of the SMS message. + */ + 'message-id': string; + + /** + * The status of the SMS message. + */ + status: SMSStatus; + + /** + * Your estimated remaining balance after sending the SMS. + */ + 'remaining-balance': string; + + /** + * The estimated cost of the SMS message. + */ + 'message-price': string; + + /** + * The estimated ID of the network of the recipient. + */ + network: string; + + /** + * Your client reference for the message (optional). + */ + 'client-ref'?: string; + + /** + * An optional string used to identify separate accounts using the SMS endpoint for billing purposes (optional). + */ + 'account-ref'?: string; +} diff --git a/packages/sms/lib/types/Responses/SMSResponse.ts b/packages/sms/lib/types/Responses/SMSResponse.ts new file mode 100644 index 00000000..0168ed57 --- /dev/null +++ b/packages/sms/lib/types/Responses/SMSResponse.ts @@ -0,0 +1,19 @@ +import { SMSErrorMessageResponse } from './SMSErrorMessageResponse'; +import { SMSMessageResponse } from './SMSMessageResponse'; + +/** + * Interface representing an SMS response. + * + * Describes the structure of a response containing information about SMS messages or error messages. + */ +export type SMSResponse = { + /** + * The count of messages included in the response. + */ + 'message-count': number; + + /** + * An array of SMS message responses or SMS error message responses. + */ + messages: (SMSMessageResponse[] | SMSErrorMessageResponse[]); +} diff --git a/packages/sms/lib/types/Responses/SendSMSResponse.ts b/packages/sms/lib/types/Responses/SendSMSResponse.ts new file mode 100644 index 00000000..e41d082e --- /dev/null +++ b/packages/sms/lib/types/Responses/SendSMSResponse.ts @@ -0,0 +1,11 @@ +import { SMSResponse } from './SMSResponse'; + +/** + * Deprecated type alias for `SMSResponse`. + * + * Please use `SMSResponse` instead. + * + * @deprecated Use `SMSResponse` instead. + * @type {SMSResponse} + */ +export type SendSMSResponse = SMSResponse; diff --git a/packages/sms/lib/interfaces/Response/index.ts b/packages/sms/lib/types/Responses/index.ts similarity index 100% rename from packages/sms/lib/interfaces/Response/index.ts rename to packages/sms/lib/types/Responses/index.ts diff --git a/packages/sms/lib/types/SMSMessages.ts b/packages/sms/lib/types/SMSMessages.ts new file mode 100644 index 00000000..8d9de3a2 --- /dev/null +++ b/packages/sms/lib/types/SMSMessages.ts @@ -0,0 +1,23 @@ +import { ErrorMessage } from './ErrorMessage'; +import { Message } from './Message'; +import { SMSResponse } from './Responses'; + +/** + * Interface representing an SMS response containing multiple messages, including errors. + * + * Extends the structure of an SMS response and includes additional properties for message count + * and an array of messages, which can include both valid messages and error messages. + * + * @extends {SMSResponse} + */ +export type SMSMessages = SMSResponse &{ + /** + * The count of messages included in the response. + */ + messageCount: number; + + /** + * An array of messages, which can include both valid messages and error messages. + */ + messages: Array; +} diff --git a/packages/sms/lib/types/SMSParams.ts b/packages/sms/lib/types/SMSParams.ts index 1aa3a094..c98b9801 100644 --- a/packages/sms/lib/types/SMSParams.ts +++ b/packages/sms/lib/types/SMSParams.ts @@ -1,23 +1,99 @@ -import { MessageClassEnum } from '../enums/MessageClassEnum'; -import { TypeEnum } from '../enums/TypeEnum'; - -export interface SMSParams { - from: string - to: string - text?: string - ttl?: number - statusReportReq?: boolean - callback?: string - messageClass?: MessageClassEnum - type?: TypeEnum - body?: string - udh?: string - protocolId?: number - title?: string - url?: string - validity?: string - clientRef?: string - accountRef?: string - entityId?: string - contentId?: string +import { MessageClassEnum, TypeEnum } from '../enums'; + +/** + * Type representing parameters for sending an SMS. + * + * Describes the structure of parameters that can be used when sending an SMS, including sender, recipient, + * message content, and additional options. + */ +export type SMSParams = { + /** + * The sender's phone number or name. + */ + from: string; + + /** + * The recipient's phone number in E.164 format. + */ + to: string; + + /** + * The text content of the SMS message (optional). + */ + text?: string; + + /** + * The time-to-live (TTL) duration in milliseconds for delivery attempts (optional). + */ + ttl?: number; + + /** + * Indicates if a delivery receipt is requested (optional). + */ + statusReportReq?: boolean; + + /** + * The webhook callback URL for receiving delivery receipts (optional). + */ + callback?: string; + + /** + * The message class (optional). + */ + messageClass?: MessageClassEnum; + + /** + * The format of the message body (optional). + */ + type?: TypeEnum; + + /** + * The binary body of the message (optional). + */ + body?: string; + + /** + * The User Data Header (UDH) for binary messages (optional). + */ + udh?: string; + + /** + * The protocol identifier for binary messages (optional). + */ + protocolId?: number; + + /** + * The title of the message (optional). + */ + title?: string; + + /** + * The URL for WAP Push messages (optional). + */ + url?: string; + + /** + * The validity period of the message (optional). + */ + validity?: string; + + /** + * Your client reference for the message (optional). + */ + clientRef?: string; + + /** + * An optional string used to identify separate accounts using the SMS endpoint for billing purposes (optional). + */ + accountRef?: string; + + /** + * An optional entity ID for regulatory requirements (optional). + */ + entityId?: string; + + /** + * An optional content ID for regulatory requirements (optional). + */ + contentId?: string; } diff --git a/packages/sms/lib/types/index.ts b/packages/sms/lib/types/index.ts index a56b229f..10dd1c9e 100644 --- a/packages/sms/lib/types/index.ts +++ b/packages/sms/lib/types/index.ts @@ -1 +1,7 @@ export * from './SMSParams'; +export * from './ErrorMessage'; +export * from './InboundMessage'; +export * from './Message'; +export * from './Responses'; +export * from './Requests'; +export * from './SMSMessages'; diff --git a/packages/sms/package.json b/packages/sms/package.json index 29f0aa86..88ccb448 100644 --- a/packages/sms/package.json +++ b/packages/sms/package.json @@ -1,4 +1,5 @@ { + "$schema": "https://json.schemastore.org/package.json", "name": "@vonage/sms", "version": "1.9.0", "description": "Vonage SMS API SDK package", @@ -11,7 +12,20 @@ "url": "git+https://github.com/Vonage/vonage-node-sdk.git" }, "license": "Apache-2.0", - "author": "Kelly J Andrews ", + "contributors": [ + { + "name": "Kelly J Andrews", + "email": "kelly@kellyjandrews.com" + }, + { + "name": "Chris Tankersley", + "email": "chris@ctankersley.com" + }, + { + "name": "Chuck MANCHUCK Reeves", + "email": "chuck@manchuck.com" + } + ], "main": "dist/index.js", "types": "dist/index.d.ts", "directories": { @@ -22,6 +36,7 @@ "/dist" ], "scripts": { + "prepublishOnly": "npm run build", "build": "npm run clean && npm run compile", "clean": "npx shx rm -rf dist tsconfig.tsbuildinfo", "compile": "npx tsc --build --verbose" @@ -36,6 +51,5 @@ }, "publishConfig": { "directory": "dist" - }, - "gitHead": "328f18e5c8a458cb4d06d7955ec2399a6ce6f5d8" + } } diff --git a/packages/sms/tsconfig.json b/packages/sms/tsconfig.json index 6791c6b6..4365c435 100644 --- a/packages/sms/tsconfig.json +++ b/packages/sms/tsconfig.json @@ -1,24 +1,25 @@ { - "extends": "../../tsconfig.json", + "$schema": "https://json.schemastore.org/tsconfig", - "compilerOptions": { - "rootDir": "lib", - "outDir": "dist" - }, + "extends": "../../tsconfig.json", - "exclude": [ - "__tests__", - "jest.config.js", - "dist" - ], + "compilerOptions": { + "rootDir": "lib", + "outDir": "dist" + }, - "references": [ - { "path": "../server-client" }, - { "path": "../auth" }, - { "path": "../vetch" } - ], + "exclude": [ + "__tests__", + "dist" + ], - "ts-node": { - "esm": true - } + "references": [ + { "path": "../server-client" }, + { "path": "../auth" }, + { "path": "../vetch" } + ], + + "ts-node": { + "esm": true + } } diff --git a/packages/sms/typedoc.json b/packages/sms/typedoc.json new file mode 100644 index 00000000..cf46ce53 --- /dev/null +++ b/packages/sms/typedoc.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "extends": ["../../typedoc.base.json"], + "entryPoints": ["lib/index.ts"], + "name": "Vonage SMS" +}