@hasna/connectors 0.4.0 → 0.4.2

package/connectors/connect-sendgrid/src/index.ts

@@ -0,0 +1,21 @@
+// SendGrid Connector
+// Send emails, manage contacts, templates, and email marketing
+
+export { SendGrid, SendGridClient } from './api';
+export * from './types';
+
+// Export config utilities
+export {
+  getApiKey,
+  setApiKey,
+  getCurrentProfile,
+  setCurrentProfile,
+  listProfiles,
+  createProfile,
+  deleteProfile,
+  loadProfile,
+  saveProfile,
+  clearConfig,
+  getConfigDir,
+  getActiveProfileName,
+} from './utils/config';

package/connectors/connect-sendgrid/src/types/index.ts

@@ -0,0 +1,403 @@
+// SendGrid Connector Types
+
+// ============================================
+// Configuration
+// ============================================
+
+export interface SendGridConfig {
+  apiKey: string;
+}
+
+// ============================================
+// Common Types
+// ============================================
+
+export type OutputFormat = 'json' | 'pretty';
+
+// ============================================
+// Email Types
+// ============================================
+
+export interface EmailAddress {
+  email: string;
+  name?: string;
+}
+
+export interface Attachment {
+  content: string; // Base64 encoded
+  type?: string;
+  filename: string;
+  disposition?: 'inline' | 'attachment';
+  content_id?: string;
+}
+
+export interface Personalization {
+  to: EmailAddress[];
+  cc?: EmailAddress[];
+  bcc?: EmailAddress[];
+  subject?: string;
+  headers?: Record<string, string>;
+  substitutions?: Record<string, string>;
+  dynamic_template_data?: Record<string, unknown>;
+  custom_args?: Record<string, string>;
+  send_at?: number;
+}
+
+export interface MailContent {
+  type: string;
+  value: string;
+}
+
+export interface ASM {
+  group_id: number;
+  groups_to_display?: number[];
+}
+
+export interface MailSettings {
+  bypass_list_management?: { enable?: boolean };
+  bypass_spam_management?: { enable?: boolean };
+  bypass_bounce_management?: { enable?: boolean };
+  bypass_unsubscribe_management?: { enable?: boolean };
+  footer?: { enable?: boolean; text?: string; html?: string };
+  sandbox_mode?: { enable?: boolean };
+}
+
+export interface TrackingSettings {
+  click_tracking?: { enable?: boolean; enable_text?: boolean };
+  open_tracking?: { enable?: boolean; substitution_tag?: string };
+  subscription_tracking?: { enable?: boolean; text?: string; html?: string; substitution_tag?: string };
+  ganalytics?: {
+    enable?: boolean;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_term?: string;
+    utm_content?: string;
+    utm_campaign?: string;
+  };
+}
+
+export interface SendMailParams {
+  personalizations: Personalization[];
+  from: EmailAddress;
+  reply_to?: EmailAddress;
+  reply_to_list?: EmailAddress[];
+  subject?: string;
+  content?: MailContent[];
+  attachments?: Attachment[];
+  template_id?: string;
+  headers?: Record<string, string>;
+  categories?: string[];
+  custom_args?: Record<string, string>;
+  send_at?: number;
+  batch_id?: string;
+  asm?: ASM;
+  ip_pool_name?: string;
+  mail_settings?: MailSettings;
+  tracking_settings?: TrackingSettings;
+}
+
+// ============================================
+// Contact Types
+// ============================================
+
+export interface Contact {
+  id?: string;
+  email: string;
+  phone_number_id?: string;
+  external_id?: string;
+  anonymous_id?: string;
+  first_name?: string;
+  last_name?: string;
+  address_line_1?: string;
+  address_line_2?: string;
+  city?: string;
+  state_province_region?: string;
+  postal_code?: string;
+  country?: string;
+  alternate_emails?: string[];
+  custom_fields?: Record<string, string | number>;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface ContactListResponse {
+  result: Contact[];
+  _metadata?: {
+    self?: string;
+    count?: number;
+  };
+}
+
+export interface ContactImportJob {
+  id: string;
+  status: 'pending' | 'processing' | 'completed' | 'failed';
+  job_type: string;
+  results?: {
+    requested_count?: number;
+    created_count?: number;
+    updated_count?: number;
+    deleted_count?: number;
+    errored_count?: number;
+  };
+  started_at?: string;
+  finished_at?: string;
+}
+
+// ============================================
+// List Types
+// ============================================
+
+export interface ContactList {
+  id: string;
+  name: string;
+  contact_count: number;
+  _metadata?: {
+    self?: string;
+  };
+}
+
+export interface ListListResponse {
+  result: ContactList[];
+  _metadata?: {
+    self?: string;
+    count?: number;
+  };
+}
+
+// ============================================
+// Template Types
+// ============================================
+
+export type TemplateGeneration = 'legacy' | 'dynamic';
+
+export interface TemplateVersion {
+  id: string;
+  template_id: string;
+  active: number;
+  name: string;
+  html_content?: string;
+  plain_content?: string;
+  generate_plain_content?: boolean;
+  subject?: string;
+  editor?: 'code' | 'design';
+  test_data?: string;
+  updated_at?: string;
+}
+
+export interface Template {
+  id: string;
+  name: string;
+  generation: TemplateGeneration;
+  updated_at?: string;
+  versions?: TemplateVersion[];
+}
+
+export interface TemplateListResponse {
+  result?: Template[];
+  templates?: Template[];
+  _metadata?: {
+    self?: string;
+    count?: number;
+  };
+}
+
+export interface TemplateCreateParams {
+  name: string;
+  generation?: TemplateGeneration;
+}
+
+export interface TemplateVersionCreateParams {
+  template_id: string;
+  active?: number;
+  name: string;
+  html_content?: string;
+  plain_content?: string;
+  generate_plain_content?: boolean;
+  subject?: string;
+  editor?: 'code' | 'design';
+  test_data?: string;
+}
+
+// ============================================
+// Sender Types
+// ============================================
+
+export interface Sender {
+  id: number;
+  nickname: string;
+  from: {
+    email: string;
+    name?: string;
+  };
+  reply_to?: {
+    email: string;
+    name?: string;
+  };
+  address: string;
+  address_2?: string;
+  city: string;
+  state?: string;
+  zip?: string;
+  country: string;
+  verified: {
+    status: boolean;
+    reason?: string;
+  };
+  updated_at?: number;
+  created_at?: number;
+  locked?: boolean;
+}
+
+export interface SenderListResponse {
+  results: Sender[];
+}
+
+export interface SenderCreateParams {
+  nickname: string;
+  from: {
+    email: string;
+    name?: string;
+  };
+  reply_to?: {
+    email: string;
+    name?: string;
+  };
+  address: string;
+  address_2?: string;
+  city: string;
+  state?: string;
+  zip?: string;
+  country: string;
+}
+
+// ============================================
+// Stats Types
+// ============================================
+
+export interface Stats {
+  date: string;
+  stats: Array<{
+    metrics: {
+      blocks?: number;
+      bounce_drops?: number;
+      bounces?: number;
+      clicks?: number;
+      deferred?: number;
+      delivered?: number;
+      invalid_emails?: number;
+      opens?: number;
+      processed?: number;
+      requests?: number;
+      spam_report_drops?: number;
+      spam_reports?: number;
+      unique_clicks?: number;
+      unique_opens?: number;
+      unsubscribe_drops?: number;
+      unsubscribes?: number;
+    };
+    name?: string;
+    type?: string;
+  }>;
+}
+
+// ============================================
+// Suppression Types
+// ============================================
+
+export interface Bounce {
+  email: string;
+  created: number;
+  reason?: string;
+  status?: string;
+}
+
+export interface Block {
+  email: string;
+  created: number;
+  reason?: string;
+  status?: string;
+}
+
+export interface SpamReport {
+  email: string;
+  created: number;
+  ip?: string;
+}
+
+export interface InvalidEmail {
+  email: string;
+  created: number;
+  reason?: string;
+}
+
+export interface Unsubscribe {
+  email: string;
+  created: number;
+  group_id?: number;
+}
+
+// ============================================
+// Unsubscribe Group Types
+// ============================================
+
+export interface UnsubscribeGroup {
+  id: number;
+  name: string;
+  description?: string;
+  is_default?: boolean;
+  unsubscribes?: number;
+}
+
+export interface UnsubscribeGroupCreateParams {
+  name: string;
+  description?: string;
+  is_default?: boolean;
+}
+
+// ============================================
+// API Key Types
+// ============================================
+
+export interface ApiKey {
+  api_key_id: string;
+  name: string;
+  scopes?: string[];
+}
+
+export interface ApiKeyCreateParams {
+  name: string;
+  scopes?: string[];
+}
+
+export interface ApiKeyCreateResponse {
+  api_key: string;
+  api_key_id: string;
+  name: string;
+  scopes?: string[];
+}
+
+// ============================================
+// API Error Types
+// ============================================
+
+export interface SendGridErrorDetail {
+  field?: string;
+  message: string;
+  help?: unknown;
+}
+
+export interface SendGridErrorResponse {
+  errors: SendGridErrorDetail[];
+}
+
+export class SendGridApiError extends Error {
+  public readonly statusCode: number;
+  public readonly errors?: SendGridErrorDetail[];
+
+  constructor(message: string, statusCode: number, errors?: SendGridErrorDetail[]) {
+    super(message);
+    this.name = 'SendGridApiError';
+    this.statusCode = statusCode;
+    this.errors = errors;
+  }
+}

package/connectors/connect-sendgrid/src/utils/config.ts

@@ -0,0 +1,197 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+const CONNECTOR_NAME = 'connect-sendgrid';
+const DEFAULT_PROFILE = 'default';
+
+export interface ProfileConfig {
+  apiKey?: string;
+}
+
+// Store for --profile flag override (set by CLI before commands run)
+let profileOverride: string | undefined;
+
+// Config directory: ~/.connect/{connector-name}/
+const CONFIG_DIR = join(homedir(), '.connect', CONNECTOR_NAME);
+const PROFILES_DIR = join(CONFIG_DIR, 'profiles');
+const CURRENT_PROFILE_FILE = join(CONFIG_DIR, 'current_profile');
+
+// ============================================
+// Profile Management
+// ============================================
+
+export function setProfileOverride(profile: string | undefined): void {
+  profileOverride = profile;
+}
+
+export function ensureConfigDir(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+  if (!existsSync(PROFILES_DIR)) {
+    mkdirSync(PROFILES_DIR, { recursive: true });
+  }
+}
+
+function getProfilePath(profile: string): string {
+  return join(PROFILES_DIR, `${profile}.json`);
+}
+
+/**
+ * Get the current active profile name
+ */
+export function getCurrentProfile(): string {
+  if (profileOverride) {
+    return profileOverride;
+  }
+
+  ensureConfigDir();
+
+  if (existsSync(CURRENT_PROFILE_FILE)) {
+    try {
+      const profile = readFileSync(CURRENT_PROFILE_FILE, 'utf-8').trim();
+      if (profile && profileExists(profile)) {
+        return profile;
+      }
+    } catch {
+      // Fall through to default
+    }
+  }
+
+  return DEFAULT_PROFILE;
+}
+
+/**
+ * Set the current active profile
+ */
+export function setCurrentProfile(profile: string): void {
+  ensureConfigDir();
+
+  if (!profileExists(profile) && profile !== DEFAULT_PROFILE) {
+    throw new Error(`Profile "${profile}" does not exist`);
+  }
+
+  writeFileSync(CURRENT_PROFILE_FILE, profile);
+}
+
+/**
+ * Check if a profile exists
+ */
+export function profileExists(profile: string): boolean {
+  return existsSync(getProfilePath(profile));
+}
+
+/**
+ * List all available profiles
+ */
+export function listProfiles(): string[] {
+  ensureConfigDir();
+
+  if (!existsSync(PROFILES_DIR)) {
+    return [];
+  }
+
+  return readdirSync(PROFILES_DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace('.json', ''))
+    .sort();
+}
+
+/**
+ * Create a new profile
+ */
+export function createProfile(profile: string, config: ProfileConfig = {}): boolean {
+  ensureConfigDir();
+
+  if (profileExists(profile)) {
+    return false;
+  }
+
+  // Validate profile name
+  if (!/^[a-zA-Z0-9_-]+$/.test(profile)) {
+    throw new Error('Profile name can only contain letters, numbers, hyphens, and underscores');
+  }
+
+  writeFileSync(getProfilePath(profile), JSON.stringify(config, null, 2));
+  return true;
+}
+
+/**
+ * Delete a profile
+ */
+export function deleteProfile(profile: string): boolean {
+  if (profile === DEFAULT_PROFILE) {
+    return false;
+  }
+
+  if (!profileExists(profile)) {
+    return false;
+  }
+
+  // Switch to default if deleting current profile
+  if (getCurrentProfile() === profile) {
+    setCurrentProfile(DEFAULT_PROFILE);
+  }
+
+  rmSync(getProfilePath(profile));
+  return true;
+}
+
+/**
+ * Load profile config
+ */
+export function loadProfile(profile?: string): ProfileConfig {
+  ensureConfigDir();
+  const profileName = profile || getCurrentProfile();
+  const profilePath = getProfilePath(profileName);
+
+  if (!existsSync(profilePath)) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(readFileSync(profilePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Save profile config
+ */
+export function saveProfile(config: ProfileConfig, profile?: string): void {
+  ensureConfigDir();
+  const profileName = profile || getCurrentProfile();
+  writeFileSync(getProfilePath(profileName), JSON.stringify(config, null, 2));
+}
+
+// ============================================
+// API Key Management
+// ============================================
+
+export function getApiKey(): string | undefined {
+  return process.env.SENDGRID_API_KEY || loadProfile().apiKey;
+}
+
+export function setApiKey(apiKey: string): void {
+  const config = loadProfile();
+  config.apiKey = apiKey;
+  saveProfile(config);
+}
+
+// ============================================
+// Utility Functions
+// ============================================
+
+export function clearConfig(): void {
+  saveProfile({});
+}
+
+export function getConfigDir(): string {
+  return CONFIG_DIR;
+}
+
+export function getActiveProfileName(): string {
+  return getCurrentProfile();
+}