@stacksjs/ts-cloud 0.1.2 → 0.1.5

package/dist/aws/sms.d.ts

@@ -0,0 +1,304 @@
+import { S3Client } from './s3';
+import { SchedulerClient } from './scheduler';
+import { SNSClient } from './sns';
+/**
+ * Create a Lambda handler for processing incoming SMS from SNS
+ * Use this with an SNS topic that receives two-way SMS messages
+ *
+ * @example
+ * ```typescript
+ * // lambda.ts
+ * import { createSmsInboxHandler } from 'ts-cloud/aws/sms'
+ *
+ * export const handler = createSmsInboxHandler({
+ *   bucket: 'my-sms-bucket',
+ *   prefix: 'sms/inbox/',
+ *   region: 'us-east-1',
+ * })
+ * ```
+ */
+export declare function createSmsInboxHandler(config: {
+  bucket: string
+  prefix?: string
+  region?: string
+  onMessage?: (message: SmsMessage) => Promise<void>
+}): void;
+/**
+ * Create a Lambda handler for sending scheduled SMS messages
+ * This is invoked by EventBridge Scheduler at the scheduled time
+ *
+ * @example
+ * ```typescript
+ * // lambda.ts
+ * import { createScheduledSmsHandler } from 'ts-cloud/aws/sms'
+ *
+ * export const handler = createScheduledSmsHandler({
+ *   bucket: 'my-sms-bucket',
+ *   region: 'us-east-1',
+ * })
+ * ```
+ */
+export declare function createScheduledSmsHandler(config: {
+  bucket: string
+  scheduledPrefix?: string
+  region?: string
+  onSent?: (sms: ScheduledSms) => Promise<void>
+  onError?: (sms: ScheduledSms, error: Error) => Promise<void>
+}): void;
+/**
+ * Convenience function to create an SMS client
+ */
+export declare function createSmsClient(config?: SmsClientConfig): SmsClient;
+/**
+ * Create a Lambda handler for processing SMS delivery receipts
+ * This handles SNS notifications for SMS delivery status events
+ *
+ * @example
+ * ```typescript
+ * // lambda.ts
+ * import { createDeliveryReceiptHandler } from 'ts-cloud/aws/sms'
+ *
+ * export const handler = createDeliveryReceiptHandler({
+ *   bucket: 'my-sms-bucket',
+ *   region: 'us-east-1',
+ *   onDelivered: async (receipt) => {
+ *     console.log(`SMS ${receipt.messageId} delivered to ${receipt.to}`)
+ *   },
+ *   onFailed: async (receipt) => {
+ *     console.error(`SMS ${receipt.messageId} failed: ${receipt.errorMessage}`)
+ *   },
+ * })
+ * ```
+ */
+export declare function createDeliveryReceiptHandler(config: {
+  bucket: string
+  receiptPrefix?: string
+  region?: string
+  onDelivered?: (receipt: DeliveryReceipt) => Promise<void>
+  onFailed?: (receipt: DeliveryReceipt) => Promise<void>
+  onReceipt?: (receipt: DeliveryReceipt) => Promise<void>
+  // Optional: webhook URL to forward receipts to
+  webhookUrl?: string
+  webhookSecret?: string
+}): void;
+/**
+ * Normalize a phone number to E.164 format
+ * Removes all non-numeric characters except leading +
+ */
+export declare function normalizePhoneNumber(phone: string): string;
+/**
+ * Format a phone number for display
+ */
+export declare function formatPhoneNumber(phone: string, format?: 'national' | 'international' | 'e164'): string;
+/**
+ * Validate a phone number
+ */
+export declare function isValidPhoneNumber(phone: string): boolean;
+/**
+ * Get the country code from a phone number
+ */
+export declare function getCountryCode(phone: string): string | null;
+/**
+ * Check if two phone numbers are the same (ignoring formatting)
+ */
+export declare function isSamePhoneNumber(phone1: string, phone2: string): boolean;
+export declare interface SmsClientConfig {
+  region?: string
+  inboxBucket?: string
+  inboxPrefix?: string
+  defaultSender?: string
+  schedulerLambdaArn?: string
+  schedulerRoleArn?: string
+  scheduledBucket?: string
+  scheduledPrefix?: string
+  receiptBucket?: string
+  receiptPrefix?: string
+  trackDelivery?: boolean
+}
+export declare interface SmsMessage {
+  key: string
+  from: string
+  to: string
+  body: string
+  timestamp: Date
+  messageId?: string
+  originationNumber?: string
+  destinationNumber?: string
+  read?: boolean
+  readAt?: Date
+  conversationId?: string
+  status?: 'pending' | 'sent' | 'delivered' | 'failed'
+  deliveredAt?: Date
+  raw?: any
+}
+export declare interface SendSmsOptions {
+  to: string
+  body: string
+  from?: string
+  type?: 'Promotional' | 'Transactional'
+  scheduledAt?: Date
+  templateId?: string
+  templateVariables?: Record<string, string>
+}
+export declare interface ScheduledSms {
+  id: string
+  to: string
+  body: string
+  from?: string
+  scheduledAt: Date
+  status: 'pending' | 'sent' | 'failed' | 'cancelled'
+  createdAt: Date
+  sentAt?: Date
+  messageId?: string
+  error?: string
+  templateId?: string
+  templateVariables?: Record<string, string>
+}
+export declare interface SmsTemplate {
+  id: string
+  name: string
+  body: string
+  description?: string
+  variables?: string[]
+  createdAt: Date
+  updatedAt?: Date
+}
+export declare interface InboxOptions {
+  prefix?: string
+  maxResults?: number
+  startAfter?: string
+}
+export declare interface DeliveryReceipt {
+  messageId: string
+  status: 'pending' | 'sent' | 'delivered' | 'failed' | 'unknown'
+  timestamp: Date
+  to: string
+  from?: string
+  errorCode?: string
+  errorMessage?: string
+  carrierName?: string
+  priceInUsd?: number
+  messagePartCount?: number
+  raw?: any
+}
+export declare interface DeliveryReceiptWebhookConfig {
+  snsTopicArn?: string
+  receiptBucket?: string
+  receiptPrefix?: string
+  webhookUrl?: string
+  webhookSecret?: string
+}
+/**
+ * SMS Client with S3 inbox storage
+ */
+export declare class SmsClient {
+  private config: SmsClientConfig;
+  private sns: SNSClient;
+  private s3?: S3Client;
+  private scheduler?: SchedulerClient;
+  constructor(config?: SmsClientConfig);
+  send(options: SendSmsOptions): Promise<{ messageId: string; scheduledId?: string }>;
+  sendText(to: string, message: string, from?: string): Promise<{ messageId: string }>;
+  getInbox(options?: InboxOptions): Promise<SmsMessage[]>;
+  getMessage(key: string): Promise<SmsMessage | null>;
+  deleteMessage(key: string): Promise<void>;
+  moveMessage(key: string, destinationPrefix: string): Promise<string>;
+  archiveMessage(key: string): Promise<string>;
+  markAsRead(key: string): Promise<void>;
+  markAsUnread(key: string): Promise<void>;
+  getUnreadCount(): Promise<number>;
+  markManyAsRead(keys: string[]): Promise<void>;
+  deleteMany(keys: string[]): Promise<void>;
+  getInboxCount(): Promise<number>;
+  getConversationId(phone1: string, phone2: string): string;
+  getConversation(phoneNumber: string, myNumber?: string): Promise<SmsMessage[]>;
+  getConversations(): Promise<Array<{
+    phoneNumber: string
+    lastMessage: SmsMessage
+    messageCount: number
+    unreadCount: number
+  }>>;
+  storeIncomingSms(message: {
+    from: string
+    to: string
+    body: string
+    messageId?: string
+    timestamp?: Date
+    raw?: any
+  }): Promise<string>;
+  isOptedOut(phoneNumber: string): Promise<boolean>;
+  getOptedOutNumbers(): Promise<string[]>;
+  optIn(phoneNumber: string): Promise<void>;
+  isInSandbox(): Promise<boolean>;
+  addSandboxNumber(phoneNumber: string): Promise<void>;
+  verifySandboxNumber(phoneNumber: string, otp: string): Promise<void>;
+  listSandboxNumbers(): Promise<Array<{ PhoneNumber: string; Status: string }>>;
+  scheduleMessage(options: {
+    to: string
+    body: string
+    from?: string
+    scheduledAt: Date
+    templateId?: string
+    templateVariables?: Record<string, string>
+  }): Promise<ScheduledSms>;
+  getScheduledMessages(): Promise<ScheduledSms[]>;
+  getScheduledMessage(id: string): Promise<ScheduledSms | null>;
+  cancelScheduledMessage(id: string): Promise<void>;
+  sendScheduledMessage(id: string): Promise<{ messageId: string }>;
+  sendAt(to: string, body: string, scheduledAt: Date, from?: string): Promise<ScheduledSms>;
+  sendAfter(to: string, body: string, delayMinutes: number, from?: string): Promise<ScheduledSms>;
+  createTemplate(template: {
+    name: string
+    body: string
+    description?: string
+  }): Promise<SmsTemplate>;
+  getTemplates(): Promise<SmsTemplate[]>;
+  getTemplate(id: string): Promise<SmsTemplate | null>;
+  getTemplateByName(name: string): Promise<SmsTemplate | null>;
+  updateTemplate(id: string, updates: { name?: string; body?: string; description?: string }): Promise<SmsTemplate>;
+  deleteTemplate(id: string): Promise<void>;
+  sendTemplate(to: string, templateId: string, variables: Record<string, string>, from?: string): Promise<{ messageId: string }>;
+  private applyTemplate(template: string, variables: Record<string, string>): string;
+  storeDeliveryReceipt(receipt: {
+    messageId: string
+    status: DeliveryReceipt['status']
+    to: string
+    from?: string
+    errorCode?: string
+    errorMessage?: string
+    carrierName?: string
+    priceInUsd?: number
+    messagePartCount?: number
+    timestamp?: Date
+    raw?: any
+  }): Promise<string>;
+  getDeliveryReceipt(messageId: string): Promise<DeliveryReceipt | null>;
+  getDeliveryReceipts(options?: {
+    maxResults?: number
+    status?: DeliveryReceipt['status']
+  }): Promise<DeliveryReceipt[]>;
+  getDeliveryStatus(messageId: string): Promise<DeliveryReceipt['status']>;
+  waitForDelivery(messageId: string, options?: {
+      timeoutMs?: number
+      pollIntervalMs?: number
+    }): Promise<DeliveryReceipt | null>;
+  getFailedMessages(maxResults?: number): Promise<DeliveryReceipt[]>;
+  getDeliveryStats(options?: {
+    since?: Date
+    maxMessages?: number
+  }): Promise<{
+    total: number
+    delivered: number
+    failed: number
+    pending: number
+    deliveryRate: number
+    averagePriceUsd: number
+  }>;
+  sendAndTrack(options: SendSmsOptions): Promise<{
+    messageId: string
+    trackDelivery: () => Promise<DeliveryReceipt | null>
+    waitForDelivery: (timeoutMs?: number) => Promise<DeliveryReceipt | null>
+  }>;
+  private parseIncomingSms(content: string, key: string): SmsMessage | null;
+  private extractSmsFields(data: any, key: string, timestamp?: string): SmsMessage;
+}

package/dist/aws/smtp-server.d.ts

@@ -0,0 +1,61 @@
+import { S3Client } from './s3';
+import { SESClient } from './ses';
+/**
+ * Start an SMTP server with the given configuration
+ */
+export declare function startSmtpServer(config: SmtpServerConfig): Promise<SmtpServer>;
+export declare interface SmtpServerConfig {
+  port?: number
+  tlsPort?: number
+  host?: string
+  region?: string
+  domain: string
+  users: Record<string, { password: string; email: string }>
+  tls?: {
+    key: string
+    cert: string
+  }
+  sentBucket?: string
+  sentPrefix?: string
+}
+declare interface SmtpSession {
+  id: string
+  socket: net.Socket
+  secure: boolean
+  state: 'greeting' | 'ready' | 'mail' | 'rcpt' | 'data' | 'quit'
+  authenticated: boolean
+  username?: string
+  email?: string
+  mailFrom?: string
+  rcptTo: string[]
+  dataBuffer: string
+  tlsUpgraded: boolean
+}
+/**
+ * SMTP Server that relays emails through AWS SES
+ */
+export declare class SmtpServer {
+  private config: SmtpServerConfig;
+  private ses: SESClient;
+  private s3?: S3Client;
+  private server?: net.Server;
+  private tlsServer?: tls.Server;
+  private sessions: Map<string, SmtpSession>;
+  constructor(config: SmtpServerConfig);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  private handleConnection(socket: net.Socket, secure: boolean): void;
+  private send(session: SmtpSession, message: string): void;
+  private handleCommand(session: SmtpSession, line: string): Promise<void>;
+  private handleEhlo(session: SmtpSession, clientDomain: string): Promise<void>;
+  private handleStartTls(session: SmtpSession): Promise<void>;
+  private handleAuth(session: SmtpSession, args: string): Promise<void>;
+  private handleAuthPlain(session: SmtpSession, credentials: string): Promise<void>;
+  private authenticateUser(session: SmtpSession, username: string, password: string): Promise<void>;
+  private handleMailFrom(session: SmtpSession, args: string): Promise<void>;
+  private handleRcptTo(session: SmtpSession, args: string): Promise<void>;
+  private handleData(session: SmtpSession): Promise<void>;
+  private handleDataLine(session: SmtpSession, line: string): Promise<void>;
+  private sendEmail(session: SmtpSession): Promise<void>;
+  private resetSession(session: SmtpSession): void;
+}

package/dist/aws/sns.d.ts

@@ -0,0 +1,117 @@
+import { AWSClient } from './client';
+export declare interface SNSTopicAttributes {
+  TopicArn?: string
+  DisplayName?: string
+  Policy?: string
+  Owner?: string
+  SubscriptionsPending?: string
+  SubscriptionsConfirmed?: string
+  SubscriptionsDeleted?: string
+  DeliveryPolicy?: string
+  EffectiveDeliveryPolicy?: string
+  KmsMasterKeyId?: string
+}
+export declare interface SNSSubscriptionAttributes {
+  SubscriptionArn?: string
+  TopicArn?: string
+  Protocol?: string
+  Endpoint?: string
+  Owner?: string
+  ConfirmationWasAuthenticated?: string
+  RawMessageDelivery?: string
+  FilterPolicy?: string
+}
+export type SNSProtocol = 'http' | 'https' | 'email' | 'email-json' | 'sms' | 'sqs' | 'application' | 'lambda'
+/**
+ * SNS service management using direct API calls
+ */
+export declare class SNSClient {
+  private client: AWSClient;
+  private region: string;
+  constructor(region?: string);
+  private buildFormBody(params: Record<string, string | undefined>): string;
+  createTopic(params: {
+    Name: string
+    DisplayName?: string
+    Tags?: Array<{ Key: string, Value: string }>
+    Attributes?: Record<string, string>
+  }): Promise<{ TopicArn?: string }>;
+  deleteTopic(topicArn: string): Promise<void>;
+  listTopics(nextToken?: string): Promise<{
+    Topics?: Array<{ TopicArn?: string }>
+    NextToken?: string
+  }>;
+  getTopicAttributes(topicArn: string): Promise<SNSTopicAttributes>;
+  setTopicAttributes(params: {
+    TopicArn: string
+    AttributeName: string
+    AttributeValue: string
+  }): Promise<void>;
+  subscribe(params: {
+    TopicArn: string
+    Protocol: SNSProtocol
+    Endpoint: string
+    Attributes?: Record<string, string>
+    ReturnSubscriptionArn?: boolean
+  }): Promise<{ SubscriptionArn?: string }>;
+  unsubscribe(subscriptionArn: string): Promise<void>;
+  listSubscriptionsByTopic(topicArn: string, nextToken?: string): Promise<{
+    Subscriptions?: SNSSubscriptionAttributes[]
+    NextToken?: string
+  }>;
+  publish(params: {
+    TopicArn?: string
+    TargetArn?: string
+    PhoneNumber?: string
+    Message: string
+    Subject?: string
+    MessageStructure?: 'json'
+    MessageAttributes?: Record<string, {
+      DataType: 'String' | 'Number' | 'Binary'
+      StringValue?: string
+      BinaryValue?: string
+    }>
+  }): Promise<{ MessageId?: string }>;
+  publishSMS(phoneNumber: string, message: string, senderId?: string): Promise<{ MessageId?: string }>;
+  subscribeEmail(topicArn: string, email: string): Promise<{ SubscriptionArn?: string }>;
+  subscribeLambda(topicArn: string, lambdaArn: string): Promise<{ SubscriptionArn?: string }>;
+  subscribeSqs(topicArn: string, queueArn: string, rawMessageDelivery?: boolean): Promise<{ SubscriptionArn?: string }>;
+  subscribeHttp(topicArn: string, url: string, rawMessageDelivery?: boolean): Promise<{ SubscriptionArn?: string }>;
+  subscribeSms(topicArn: string, phoneNumber: string): Promise<{ SubscriptionArn?: string }>;
+  topicExists(topicArn: string): Promise<boolean>;
+  getSMSAttributes(): Promise<{
+    MonthlySpendLimit?: string
+    DeliveryStatusIAMRole?: string
+    DeliveryStatusSuccessSamplingRate?: string
+    DefaultSenderID?: string
+    DefaultSMSType?: 'Promotional' | 'Transactional'
+    UsageReportS3Bucket?: string
+  }>;
+  setSMSAttributes(attributes: {
+    MonthlySpendLimit?: string
+    DeliveryStatusIAMRole?: string
+    DeliveryStatusSuccessSamplingRate?: string
+    DefaultSenderID?: string
+    DefaultSMSType?: 'Promotional' | 'Transactional'
+    UsageReportS3Bucket?: string
+  }): Promise<void>;
+  checkIfPhoneNumberIsOptedOut(phoneNumber: string): Promise<boolean>;
+  listPhoneNumbersOptedOut(nextToken?: string): Promise<{
+    phoneNumbers?: string[]
+    nextToken?: string
+  }>;
+  optInPhoneNumber(phoneNumber: string): Promise<void>;
+  listSMSSandboxPhoneNumbers(nextToken?: string): Promise<{
+    PhoneNumbers?: Array<{
+      PhoneNumber?: string
+      Status?: 'Pending' | 'Verified'
+    }>
+    NextToken?: string
+  }>;
+  createSMSSandboxPhoneNumber(phoneNumber: string, languageCode?: string): Promise<void>;
+  verifySMSSandboxPhoneNumber(phoneNumber: string, oneTimePassword: string): Promise<void>;
+  deleteSMSSandboxPhoneNumber(phoneNumber: string): Promise<void>;
+  getSMSSandboxAccountStatus(): Promise<{
+    IsInSandbox: boolean
+  }>;
+}

package/dist/aws/sqs.d.ts

@@ -0,0 +1,65 @@
+import { AWSClient } from './client';
+export declare interface QueueAttributes {
+  QueueUrl: string
+  QueueArn?: string
+  ApproximateNumberOfMessages?: string
+  ApproximateNumberOfMessagesNotVisible?: string
+  ApproximateNumberOfMessagesDelayed?: string
+  CreatedTimestamp?: string
+  LastModifiedTimestamp?: string
+  VisibilityTimeout?: string
+  MaximumMessageSize?: string
+  MessageRetentionPeriod?: string
+  DelaySeconds?: string
+  ReceiveMessageWaitTimeSeconds?: string
+  FifoQueue?: string
+  ContentBasedDeduplication?: string
+}
+export declare interface CreateQueueOptions {
+  queueName: string
+  fifo?: boolean
+  visibilityTimeout?: number
+  messageRetentionPeriod?: number
+  delaySeconds?: number
+  maxMessageSize?: number
+  receiveMessageWaitTime?: number
+  deadLetterTargetArn?: string
+  maxReceiveCount?: number
+  contentBasedDeduplication?: boolean
+  tags?: Record<string, string>
+}
+export declare interface Message {
+  MessageId: string
+  ReceiptHandle: string
+  Body: string
+  Attributes?: Record<string, string>
+  MessageAttributes?: Record<string, any>
+}
+/**
+ * SQS queue management using direct API calls
+ */
+export declare class SQSClient {
+  private client: AWSClient;
+  private region: string;
+  constructor(region?: string, profile?: string);
+  createQueue(options: CreateQueueOptions): Promise<{ QueueUrl: string }>;
+  listQueues(prefix?: string): Promise<{ QueueUrls: string[] }>;
+  getQueueAttributes(queueUrl: string): Promise<{ Attributes: Record<string, string> }>;
+  getQueueUrl(queueName: string): Promise<{ QueueUrl: string }>;
+  deleteQueue(queueUrl: string): Promise<void>;
+  purgeQueue(queueUrl: string): Promise<void>;
+  sendMessage(options: {
+    queueUrl: string
+    messageBody: string
+    delaySeconds?: number
+    messageGroupId?: string
+    messageDeduplicationId?: string
+  }): Promise<{ MessageId: string }>;
+  receiveMessages(options: {
+    queueUrl: string
+    maxMessages?: number
+    visibilityTimeout?: number
+    waitTimeSeconds?: number
+  }): Promise<{ Messages: Message[] }>;
+  deleteMessage(queueUrl: string, receiptHandle: string): Promise<void>;
+}