@hasna/connectors 0.0.1

package/connectors/connect-twilio/src/api/conversations.ts

@@ -0,0 +1,313 @@
+import type { TwilioClient } from './client';
+import type {
+  Conversation,
+  ConversationListResponse,
+  ConversationMessage,
+  ConversationParticipant,
+  CreateConversationParams,
+  UpdateConversationParams,
+  AddParticipantParams,
+  SendConversationMessageParams,
+} from '../types';
+
+const CONVERSATIONS_BASE_URL = 'https://conversations.twilio.com/v1';
+
+/**
+ * Twilio Conversations API
+ * Create and manage conversations, participants, and messages
+ */
+export class ConversationsApi {
+  private readonly baseUrl = CONVERSATIONS_BASE_URL;
+
+  constructor(private readonly client: TwilioClient) {}
+
+  /**
+   * Make a request to the Conversations API (different base URL)
+   */
+  private async conversationsRequest<T>(method: string, path: string, body?: Record<string, unknown>, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    let url = `${this.baseUrl}${path}`;
+
+    if (params) {
+      const searchParams = new URLSearchParams();
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          searchParams.append(key, String(value));
+        }
+      });
+      const queryString = searchParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+
+    const credentials = Buffer.from(`${this.client.getAccountSid()}:${(this.client as unknown as { authToken: string }).authToken}`).toString('base64');
+
+    const headers: Record<string, string> = {
+      'Authorization': `Basic ${credentials}`,
+      'Accept': 'application/json',
+    };
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      headers['Content-Type'] = 'application/x-www-form-urlencoded';
+      const formParams = new URLSearchParams();
+      Object.entries(body).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          if (typeof value === 'object') {
+            formParams.append(key, JSON.stringify(value));
+          } else {
+            formParams.append(key, String(value));
+          }
+        }
+      });
+      fetchOptions.body = formParams.toString();
+      fetchOptions.headers = headers;
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new Error(data.message || response.statusText);
+    }
+
+    return data as T;
+  }
+
+  // ============================================
+  // Conversations
+  // ============================================
+
+  /**
+   * Create a new conversation
+   */
+  async create(params?: CreateConversationParams): Promise<Conversation> {
+    return this.conversationsRequest<Conversation>(
+      'POST',
+      '/Conversations',
+      params as unknown as Record<string, unknown>
+    );
+  }
+
+  /**
+   * List all conversations
+   */
+  async list(params?: { PageSize?: number; Page?: number; State?: string }): Promise<ConversationListResponse> {
+    return this.conversationsRequest<ConversationListResponse>(
+      'GET',
+      '/Conversations',
+      undefined,
+      params as unknown as Record<string, string | number | boolean | undefined>
+    );
+  }
+
+  /**
+   * Get a conversation by SID or UniqueName
+   */
+  async get(conversationSid: string): Promise<Conversation> {
+    return this.conversationsRequest<Conversation>(
+      'GET',
+      `/Conversations/${conversationSid}`
+    );
+  }
+
+  /**
+   * Update a conversation
+   */
+  async update(conversationSid: string, params: UpdateConversationParams): Promise<Conversation> {
+    return this.conversationsRequest<Conversation>(
+      'POST',
+      `/Conversations/${conversationSid}`,
+      params as unknown as Record<string, unknown>
+    );
+  }
+
+  /**
+   * Delete a conversation
+   */
+  async delete(conversationSid: string): Promise<void> {
+    await this.conversationsRequest<void>(
+      'DELETE',
+      `/Conversations/${conversationSid}`
+    );
+  }
+
+  /**
+   * Close a conversation
+   */
+  async close(conversationSid: string): Promise<Conversation> {
+    return this.update(conversationSid, { State: 'closed' });
+  }
+
+  // ============================================
+  // Participants
+  // ============================================
+
+  /**
+   * Add a participant to a conversation
+   */
+  async addParticipant(conversationSid: string, params: AddParticipantParams): Promise<ConversationParticipant> {
+    return this.conversationsRequest<ConversationParticipant>(
+      'POST',
+      `/Conversations/${conversationSid}/Participants`,
+      params as unknown as Record<string, unknown>
+    );
+  }
+
+  /**
+   * List participants in a conversation
+   */
+  async listParticipants(conversationSid: string, params?: { PageSize?: number; Page?: number }): Promise<{ participants: ConversationParticipant[]; meta: { page: number; page_size: number } }> {
+    return this.conversationsRequest(
+      'GET',
+      `/Conversations/${conversationSid}/Participants`,
+      undefined,
+      params as unknown as Record<string, string | number | boolean | undefined>
+    );
+  }
+
+  /**
+   * Get a participant by SID
+   */
+  async getParticipant(conversationSid: string, participantSid: string): Promise<ConversationParticipant> {
+    return this.conversationsRequest<ConversationParticipant>(
+      'GET',
+      `/Conversations/${conversationSid}/Participants/${participantSid}`
+    );
+  }
+
+  /**
+   * Update a participant
+   */
+  async updateParticipant(conversationSid: string, participantSid: string, params: {
+    DateCreated?: string;
+    DateUpdated?: string;
+    Attributes?: string;
+    RoleSid?: string;
+    'MessagingBinding.ProxyAddress'?: string;
+    'MessagingBinding.ProjectedAddress'?: string;
+    LastReadMessageIndex?: number;
+    LastReadTimestamp?: string;
+  }): Promise<ConversationParticipant> {
+    return this.conversationsRequest<ConversationParticipant>(
+      'POST',
+      `/Conversations/${conversationSid}/Participants/${participantSid}`,
+      params as unknown as Record<string, unknown>
+    );
+  }
+
+  /**
+   * Remove a participant from a conversation
+   */
+  async removeParticipant(conversationSid: string, participantSid: string): Promise<void> {
+    await this.conversationsRequest<void>(
+      'DELETE',
+      `/Conversations/${conversationSid}/Participants/${participantSid}`
+    );
+  }
+
+  // ============================================
+  // Messages
+  // ============================================
+
+  /**
+   * Send a message to a conversation
+   */
+  async sendMessage(conversationSid: string, params: SendConversationMessageParams): Promise<ConversationMessage> {
+    return this.conversationsRequest<ConversationMessage>(
+      'POST',
+      `/Conversations/${conversationSid}/Messages`,
+      params as unknown as Record<string, unknown>
+    );
+  }
+
+  /**
+   * List messages in a conversation
+   */
+  async listMessages(conversationSid: string, params?: { PageSize?: number; Page?: number; Order?: 'asc' | 'desc' }): Promise<{ messages: ConversationMessage[]; meta: { page: number; page_size: number } }> {
+    return this.conversationsRequest(
+      'GET',
+      `/Conversations/${conversationSid}/Messages`,
+      undefined,
+      params as unknown as Record<string, string | number | boolean | undefined>
+    );
+  }
+
+  /**
+   * Get a message by SID
+   */
+  async getMessage(conversationSid: string, messageSid: string): Promise<ConversationMessage> {
+    return this.conversationsRequest<ConversationMessage>(
+      'GET',
+      `/Conversations/${conversationSid}/Messages/${messageSid}`
+    );
+  }
+
+  /**
+   * Update a message
+   */
+  async updateMessage(conversationSid: string, messageSid: string, params: {
+    Author?: string;
+    Body?: string;
+    DateCreated?: string;
+    DateUpdated?: string;
+    Attributes?: string;
+  }): Promise<ConversationMessage> {
+    return this.conversationsRequest<ConversationMessage>(
+      'POST',
+      `/Conversations/${conversationSid}/Messages/${messageSid}`,
+      params as unknown as Record<string, unknown>
+    );
+  }
+
+  /**
+   * Delete a message
+   */
+  async deleteMessage(conversationSid: string, messageSid: string): Promise<void> {
+    await this.conversationsRequest<void>(
+      'DELETE',
+      `/Conversations/${conversationSid}/Messages/${messageSid}`
+    );
+  }
+
+  // ============================================
+  // Convenience Methods
+  // ============================================
+
+  /**
+   * Add a chat user to a conversation by identity
+   */
+  async addChatParticipant(conversationSid: string, identity: string, attributes?: string): Promise<ConversationParticipant> {
+    return this.addParticipant(conversationSid, {
+      Identity: identity,
+      Attributes: attributes,
+    });
+  }
+
+  /**
+   * Add an SMS participant to a conversation
+   */
+  async addSmsParticipant(conversationSid: string, address: string, proxyAddress: string, attributes?: string): Promise<ConversationParticipant> {
+    return this.addParticipant(conversationSid, {
+      'MessagingBinding.Address': address,
+      'MessagingBinding.ProxyAddress': proxyAddress,
+      Attributes: attributes,
+    });
+  }
+
+  /**
+   * Send a text message to a conversation
+   */
+  async sendText(conversationSid: string, body: string, author?: string): Promise<ConversationMessage> {
+    return this.sendMessage(conversationSid, { Body: body, Author: author });
+  }
+}

package/connectors/connect-twilio/src/api/index.ts

@@ -0,0 +1,91 @@
+import type { TwilioConfig } from '../types';
+import { TwilioClient } from './client';
+import { MessagesApi } from './messages';
+import { CallsApi } from './calls';
+import { NumbersApi } from './numbers';
+import { VerifyApi } from './verify';
+import { ConversationsApi } from './conversations';
+import { VideoApi } from './video';
+import { LookupApi } from './lookup';
+import { AccountsApi } from './accounts';
+
+/**
+ * Main Twilio connector class
+ * Provides access to all Twilio API modules
+ */
+export class Twilio {
+  private readonly client: TwilioClient;
+
+  // API modules
+  public readonly messages: MessagesApi;
+  public readonly calls: CallsApi;
+  public readonly numbers: NumbersApi;
+  public readonly verify: VerifyApi;
+  public readonly conversations: ConversationsApi;
+  public readonly video: VideoApi;
+  public readonly lookup: LookupApi;
+  public readonly accounts: AccountsApi;
+
+  constructor(config: TwilioConfig) {
+    this.client = new TwilioClient(config);
+
+    // Initialize API modules
+    this.messages = new MessagesApi(this.client);
+    this.calls = new CallsApi(this.client);
+    this.numbers = new NumbersApi(this.client);
+    this.verify = new VerifyApi(this.client);
+    this.conversations = new ConversationsApi(this.client);
+    this.video = new VideoApi(this.client);
+    this.lookup = new LookupApi(this.client);
+    this.accounts = new AccountsApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN
+   */
+  static fromEnv(): Twilio {
+    const accountSid = process.env.TWILIO_ACCOUNT_SID;
+    const authToken = process.env.TWILIO_AUTH_TOKEN;
+
+    if (!accountSid) {
+      throw new Error('TWILIO_ACCOUNT_SID environment variable is required');
+    }
+    if (!authToken) {
+      throw new Error('TWILIO_AUTH_TOKEN environment variable is required');
+    }
+
+    return new Twilio({ accountSid, authToken });
+  }
+
+  /**
+   * Get a preview of the Account SID (for debugging)
+   */
+  getAccountSidPreview(): string {
+    return this.client.getAccountSidPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): TwilioClient {
+    return this.client;
+  }
+
+  /**
+   * Get the Account SID
+   */
+  getAccountSid(): string {
+    return this.client.getAccountSid();
+  }
+}
+
+export { TwilioClient } from './client';
+export { MessagesApi } from './messages';
+export { CallsApi } from './calls';
+export { NumbersApi } from './numbers';
+export { VerifyApi } from './verify';
+export { ConversationsApi } from './conversations';
+export { VideoApi } from './video';
+export { LookupApi } from './lookup';
+export { AccountsApi } from './accounts';

package/connectors/connect-twilio/src/api/lookup.ts

@@ -0,0 +1,271 @@
+import type { TwilioClient } from './client';
+import type { LookupResult, LookupParams } from '../types';
+
+const LOOKUP_BASE_URL = 'https://lookups.twilio.com/v2';
+
+/**
+ * Twilio Lookup API
+ * Get information about phone numbers
+ */
+export class LookupApi {
+  private readonly baseUrl = LOOKUP_BASE_URL;
+
+  constructor(private readonly client: TwilioClient) {}
+
+  /**
+   * Make a request to the Lookup API (different base URL)
+   */
+  private async lookupRequest<T>(method: string, path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    let url = `${this.baseUrl}${path}`;
+
+    if (params) {
+      const searchParams = new URLSearchParams();
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          searchParams.append(key, String(value));
+        }
+      });
+      const queryString = searchParams.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+    }
+
+    const credentials = Buffer.from(`${this.client.getAccountSid()}:${(this.client as unknown as { authToken: string }).authToken}`).toString('base64');
+
+    const headers: Record<string, string> = {
+      'Authorization': `Basic ${credentials}`,
+      'Accept': 'application/json',
+    };
+
+    const response = await fetch(url, { method, headers });
+
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      throw new Error(data.message || response.statusText);
+    }
+
+    return data as T;
+  }
+
+  /**
+   * Look up a phone number with specified fields
+   *
+   * Available fields:
+   * - caller_name: Caller ID name
+   * - carrier: Carrier information (removed - see line_type_intelligence)
+   * - line_type_intelligence: Line type and carrier info
+   * - live_activity: Real-time line activity
+   * - sim_swap: SIM swap detection
+   * - call_forwarding: Call forwarding status
+   * - identity_match: Identity verification
+   * - reassigned_number: Number reassignment detection
+   * - sms_pumping_risk: SMS fraud risk score
+   * - phone_number_quality_score: Number quality score
+   * - pre_fill: Pre-populated identity data
+   */
+  async lookup(phoneNumber: string, params?: LookupParams): Promise<LookupResult> {
+    // Ensure phone number is URL-encoded
+    const encodedNumber = encodeURIComponent(phoneNumber);
+    return this.lookupRequest<LookupResult>(
+      'GET',
+      `/PhoneNumbers/${encodedNumber}`,
+      params as unknown as Record<string, string | number | boolean | undefined>
+    );
+  }
+
+  // ============================================
+  // Convenience Methods
+  // ============================================
+
+  /**
+   * Get basic phone number validation
+   */
+  async validate(phoneNumber: string, countryCode?: string): Promise<{
+    valid: boolean;
+    calling_country_code: string;
+    country_code: string;
+    phone_number: string;
+    national_format: string;
+  }> {
+    const result = await this.lookup(phoneNumber, { CountryCode: countryCode });
+    return {
+      valid: result.valid,
+      calling_country_code: result.calling_country_code,
+      country_code: result.country_code,
+      phone_number: result.phone_number,
+      national_format: result.national_format,
+    };
+  }
+
+  /**
+   * Get line type information (carrier and type)
+   */
+  async getLineType(phoneNumber: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    line_type: string | null;
+    carrier_name: string | null;
+    mobile_country_code: string | null;
+    mobile_network_code: string | null;
+  }> {
+    const result = await this.lookup(phoneNumber, { Fields: 'line_type_intelligence' });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      line_type: result.line_type_intelligence?.type || null,
+      carrier_name: result.line_type_intelligence?.carrier_name || null,
+      mobile_country_code: result.line_type_intelligence?.mobile_country_code || null,
+      mobile_network_code: result.line_type_intelligence?.mobile_network_code || null,
+    };
+  }
+
+  /**
+   * Get caller name (CNAM) information
+   */
+  async getCallerName(phoneNumber: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    caller_name: string | null;
+    caller_type: 'CONSUMER' | 'BUSINESS' | null;
+  }> {
+    const result = await this.lookup(phoneNumber, { Fields: 'caller_name' });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      caller_name: result.caller_name?.caller_name || null,
+      caller_type: result.caller_name?.caller_type || null,
+    };
+  }
+
+  /**
+   * Get SIM swap information
+   */
+  async getSimSwap(phoneNumber: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    last_sim_swap_date: string | null;
+    swapped_period: string | null;
+    swapped_in_period: boolean | null;
+  }> {
+    const result = await this.lookup(phoneNumber, { Fields: 'sim_swap' });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      last_sim_swap_date: result.sim_swap?.last_sim_swap?.last_sim_swap_date || null,
+      swapped_period: result.sim_swap?.last_sim_swap?.swapped_period || null,
+      swapped_in_period: result.sim_swap?.last_sim_swap?.swapped_in_period || null,
+    };
+  }
+
+  /**
+   * Get call forwarding status
+   */
+  async getCallForwarding(phoneNumber: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    call_forwarding_status: boolean | null;
+  }> {
+    const result = await this.lookup(phoneNumber, { Fields: 'call_forwarding' });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      call_forwarding_status: result.call_forwarding?.call_forwarding_status || null,
+    };
+  }
+
+  /**
+   * Get live activity (connectivity and roaming)
+   */
+  async getLiveActivity(phoneNumber: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    connectivity: string | null;
+    ported: boolean | null;
+    roaming_status: string | null;
+    roaming_country: string | null;
+  }> {
+    const result = await this.lookup(phoneNumber, { Fields: 'live_activity' });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      connectivity: result.live_activity?.connectivity || null,
+      ported: result.live_activity?.ported || null,
+      roaming_status: result.live_activity?.roaming?.status || null,
+      roaming_country: result.live_activity?.roaming?.roaming_country_code || null,
+    };
+  }
+
+  /**
+   * Check if number has been reassigned
+   */
+  async getReassignedNumber(phoneNumber: string, lastVerifiedDate?: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    last_verified_date: string | null;
+    is_reassigned: boolean | null;
+  }> {
+    const result = await this.lookup(phoneNumber, {
+      Fields: 'reassigned_number',
+      LastVerifiedDate: lastVerifiedDate,
+    });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      last_verified_date: result.reassigned_number?.last_verified_date || null,
+      is_reassigned: result.reassigned_number?.is_reassigned || null,
+    };
+  }
+
+  /**
+   * Get SMS pumping risk score
+   */
+  async getSmsPumpingRisk(phoneNumber: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    sms_pumping_risk_score: number | null;
+    carrier_risk_score: number | null;
+    carrier_risk_category: string | null;
+    number_blocked: boolean | null;
+  }> {
+    const result = await this.lookup(phoneNumber, { Fields: 'sms_pumping_risk' });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      sms_pumping_risk_score: result.sms_pumping_risk?.sms_pumping_risk_score || null,
+      carrier_risk_score: result.sms_pumping_risk?.carrier_risk_score || null,
+      carrier_risk_category: result.sms_pumping_risk?.carrier_risk_category || null,
+      number_blocked: result.sms_pumping_risk?.number_blocked || null,
+    };
+  }
+
+  /**
+   * Get phone number quality score
+   */
+  async getQualityScore(phoneNumber: string): Promise<{
+    phone_number: string;
+    valid: boolean;
+    quality_score: number | null;
+  }> {
+    const result = await this.lookup(phoneNumber, { Fields: 'phone_number_quality_score' });
+    return {
+      phone_number: result.phone_number,
+      valid: result.valid,
+      quality_score: result.phone_number_quality_score?.quality_score || null,
+    };
+  }
+
+  /**
+   * Get comprehensive lookup with multiple fields
+   */
+  async getComprehensive(phoneNumber: string): Promise<LookupResult> {
+    return this.lookup(phoneNumber, {
+      Fields: 'line_type_intelligence,caller_name,sim_swap,call_forwarding,sms_pumping_risk,phone_number_quality_score',
+    });
+  }
+}