digital-tools 2.0.1

package/src/providers/email/resend.ts

@@ -0,0 +1,301 @@
+/**
+ * Resend Email Provider
+ *
+ * Concrete implementation of EmailProvider using Resend API.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  EmailProvider,
+  ProviderConfig,
+  ProviderHealth,
+  ProviderInfo,
+  SendEmailOptions,
+  SendEmailResult,
+  EmailData,
+  EmailListOptions,
+  PaginatedResult,
+  DomainVerification,
+  DomainInfo,
+} from '../types.js'
+import { defineProvider } from '../registry.js'
+
+const RESEND_API_URL = 'https://api.resend.com'
+
+/**
+ * Resend provider info
+ */
+export const resendInfo: ProviderInfo = {
+  id: 'email.resend',
+  name: 'Resend',
+  description: 'Modern email API for developers',
+  category: 'email',
+  website: 'https://resend.com',
+  docsUrl: 'https://resend.com/docs',
+  requiredConfig: ['apiKey'],
+  optionalConfig: ['defaultFrom'],
+}
+
+/**
+ * Create Resend email provider
+ */
+export function createResendProvider(config: ProviderConfig): EmailProvider {
+  let apiKey: string
+  let defaultFrom: string | undefined
+
+  return {
+    info: resendInfo,
+
+    async initialize(cfg: ProviderConfig): Promise<void> {
+      apiKey = cfg.apiKey as string
+      defaultFrom = cfg.defaultFrom as string | undefined
+
+      if (!apiKey) {
+        throw new Error('Resend API key is required')
+      }
+    },
+
+    async healthCheck(): Promise<ProviderHealth> {
+      const start = Date.now()
+      try {
+        const response = await fetch(`${RESEND_API_URL}/domains`, {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+          },
+        })
+
+        return {
+          healthy: response.ok,
+          latencyMs: Date.now() - start,
+          message: response.ok ? 'Connected' : `HTTP ${response.status}`,
+          checkedAt: new Date(),
+        }
+      } catch (error) {
+        return {
+          healthy: false,
+          latencyMs: Date.now() - start,
+          message: error instanceof Error ? error.message : 'Unknown error',
+          checkedAt: new Date(),
+        }
+      }
+    },
+
+    async dispose(): Promise<void> {
+      // No cleanup needed
+    },
+
+    async send(options: SendEmailOptions): Promise<SendEmailResult> {
+      const from = options.from || defaultFrom
+      if (!from) {
+        return {
+          success: false,
+          error: { code: 'MISSING_FROM', message: 'From address is required' },
+        }
+      }
+
+      const body: Record<string, unknown> = {
+        from,
+        to: options.to,
+        subject: options.subject,
+        ...(options.cc && { cc: options.cc }),
+        ...(options.bcc && { bcc: options.bcc }),
+        ...(options.replyTo && { reply_to: options.replyTo }),
+        ...(options.text && { text: options.text }),
+        ...(options.html && { html: options.html }),
+        ...(options.headers && { headers: options.headers }),
+        ...(options.tags && { tags: options.tags.map((name) => ({ name })) }),
+      }
+
+      if (options.attachments?.length) {
+        body.attachments = options.attachments.map((att) => ({
+          filename: att.filename,
+          content: typeof att.content === 'string' ? att.content : att.content.toString('base64'),
+          content_type: att.contentType,
+        }))
+      }
+
+      if (options.sendAt) {
+        body.scheduled_at = options.sendAt.toISOString()
+      }
+
+      try {
+        const response = await fetch(`${RESEND_API_URL}/emails`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify(body),
+        })
+
+        const data = await response.json()
+
+        if (response.ok) {
+          return {
+            success: true,
+            messageId: (data as any).id,
+          }
+        }
+
+        return {
+          success: false,
+          error: {
+            code: (data as any).name || `HTTP_${response.status}`,
+            message: (data as any).message || response.statusText,
+          },
+        }
+      } catch (error) {
+        return {
+          success: false,
+          error: {
+            code: 'NETWORK_ERROR',
+            message: error instanceof Error ? error.message : 'Unknown error',
+          },
+        }
+      }
+    },
+
+    async sendBatch(emails: SendEmailOptions[]): Promise<SendEmailResult[]> {
+      // Resend has a batch endpoint
+      const from = defaultFrom
+      const batch = emails.map((options) => ({
+        from: options.from || from,
+        to: options.to,
+        subject: options.subject,
+        ...(options.cc && { cc: options.cc }),
+        ...(options.bcc && { bcc: options.bcc }),
+        ...(options.replyTo && { reply_to: options.replyTo }),
+        ...(options.text && { text: options.text }),
+        ...(options.html && { html: options.html }),
+      }))
+
+      try {
+        const response = await fetch(`${RESEND_API_URL}/emails/batch`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify(batch),
+        })
+
+        const data = await response.json()
+
+        if (response.ok) {
+          return (data as any).data.map((item: any) => ({
+            success: true,
+            messageId: item.id,
+          }))
+        }
+
+        // If batch fails, return error for all
+        return emails.map(() => ({
+          success: false,
+          error: {
+            code: (data as any).name || `HTTP_${response.status}`,
+            message: (data as any).message || response.statusText,
+          },
+        }))
+      } catch (error) {
+        return emails.map(() => ({
+          success: false,
+          error: {
+            code: 'NETWORK_ERROR',
+            message: error instanceof Error ? error.message : 'Unknown error',
+          },
+        }))
+      }
+    },
+
+    async get(messageId: string): Promise<EmailData | null> {
+      try {
+        const response = await fetch(`${RESEND_API_URL}/emails/${messageId}`, {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+          },
+        })
+
+        if (!response.ok) {
+          if (response.status === 404) return null
+          throw new Error(`HTTP ${response.status}`)
+        }
+
+        const data = (await response.json()) as any
+        return {
+          id: data.id,
+          from: data.from,
+          to: Array.isArray(data.to) ? data.to : [data.to],
+          cc: data.cc,
+          bcc: data.bcc,
+          subject: data.subject,
+          text: data.text,
+          html: data.html,
+          status: mapResendStatus(data.last_event),
+          sentAt: data.created_at ? new Date(data.created_at) : undefined,
+        }
+      } catch {
+        return null
+      }
+    },
+
+    async verifyDomain(domain: string): Promise<DomainVerification> {
+      const response = await fetch(`${RESEND_API_URL}/domains`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({ name: domain }),
+      })
+
+      const data = (await response.json()) as any
+
+      return {
+        domain: data.name,
+        verified: data.status === 'verified',
+        dnsRecords: data.records?.map((r: any) => ({
+          type: r.type,
+          name: r.name,
+          value: r.value,
+          verified: r.status === 'verified',
+        })) || [],
+      }
+    },
+
+    async listDomains(): Promise<DomainInfo[]> {
+      const response = await fetch(`${RESEND_API_URL}/domains`, {
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+        },
+      })
+
+      const data = (await response.json()) as any
+      return data.data?.map((d: any) => ({
+        domain: d.name,
+        verified: d.status === 'verified',
+        createdAt: new Date(d.created_at),
+      })) || []
+    },
+  }
+}
+
+function mapResendStatus(event: string): EmailData['status'] {
+  switch (event) {
+    case 'delivered':
+      return 'delivered'
+    case 'bounced':
+      return 'bounced'
+    case 'complained':
+      return 'failed'
+    default:
+      return 'sent'
+  }
+}
+
+/**
+ * Resend provider definition
+ */
+export const resendProvider = defineProvider(resendInfo, async (config) =>
+  createResendProvider(config)
+)

package/src/providers/email/sendgrid.ts

@@ -0,0 +1,196 @@
+/**
+ * SendGrid Email Provider
+ *
+ * Concrete implementation of EmailProvider using SendGrid API.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  EmailProvider,
+  ProviderConfig,
+  ProviderHealth,
+  ProviderInfo,
+  SendEmailOptions,
+  SendEmailResult,
+  EmailData,
+  EmailListOptions,
+  PaginatedResult,
+} from '../types.js'
+import { defineProvider } from '../registry.js'
+
+const SENDGRID_API_URL = 'https://api.sendgrid.com/v3'
+
+/**
+ * SendGrid provider info
+ */
+export const sendgridInfo: ProviderInfo = {
+  id: 'email.sendgrid',
+  name: 'SendGrid',
+  description: 'SendGrid email delivery service by Twilio',
+  category: 'email',
+  website: 'https://sendgrid.com',
+  docsUrl: 'https://docs.sendgrid.com',
+  requiredConfig: ['apiKey'],
+  optionalConfig: ['defaultFrom', 'sandboxMode'],
+}
+
+/**
+ * Create SendGrid email provider
+ */
+export function createSendGridProvider(config: ProviderConfig): EmailProvider {
+  let apiKey: string
+  let defaultFrom: string | undefined
+
+  return {
+    info: sendgridInfo,
+
+    async initialize(cfg: ProviderConfig): Promise<void> {
+      apiKey = cfg.apiKey as string
+      defaultFrom = cfg.defaultFrom as string | undefined
+
+      if (!apiKey) {
+        throw new Error('SendGrid API key is required')
+      }
+    },
+
+    async healthCheck(): Promise<ProviderHealth> {
+      const start = Date.now()
+      try {
+        const response = await fetch(`${SENDGRID_API_URL}/scopes`, {
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+          },
+        })
+
+        return {
+          healthy: response.ok,
+          latencyMs: Date.now() - start,
+          message: response.ok ? 'Connected' : `HTTP ${response.status}`,
+          checkedAt: new Date(),
+        }
+      } catch (error) {
+        return {
+          healthy: false,
+          latencyMs: Date.now() - start,
+          message: error instanceof Error ? error.message : 'Unknown error',
+          checkedAt: new Date(),
+        }
+      }
+    },
+
+    async dispose(): Promise<void> {
+      // No cleanup needed
+    },
+
+    async send(options: SendEmailOptions): Promise<SendEmailResult> {
+      const from = options.from || defaultFrom
+      if (!from) {
+        return {
+          success: false,
+          error: { code: 'MISSING_FROM', message: 'From address is required' },
+        }
+      }
+
+      const personalizations = [
+        {
+          to: options.to.map((email) => ({ email })),
+          ...(options.cc && { cc: options.cc.map((email) => ({ email })) }),
+          ...(options.bcc && { bcc: options.bcc.map((email) => ({ email })) }),
+        },
+      ]
+
+      const body: Record<string, unknown> = {
+        personalizations,
+        from: { email: from },
+        subject: options.subject,
+        content: [
+          ...(options.text ? [{ type: 'text/plain', value: options.text }] : []),
+          ...(options.html ? [{ type: 'text/html', value: options.html }] : []),
+        ],
+      }
+
+      if (options.replyTo) {
+        body.reply_to = { email: options.replyTo }
+      }
+
+      if (options.attachments?.length) {
+        body.attachments = options.attachments.map((att) => ({
+          content: typeof att.content === 'string' ? att.content : att.content.toString('base64'),
+          filename: att.filename,
+          type: att.contentType,
+          content_id: att.contentId,
+          disposition: att.contentId ? 'inline' : 'attachment',
+        }))
+      }
+
+      if (options.sendAt) {
+        body.send_at = Math.floor(options.sendAt.getTime() / 1000)
+      }
+
+      if (options.trackOpens !== undefined || options.trackClicks !== undefined) {
+        body.tracking_settings = {
+          ...(options.trackOpens !== undefined && {
+            open_tracking: { enable: options.trackOpens },
+          }),
+          ...(options.trackClicks !== undefined && {
+            click_tracking: { enable: options.trackClicks },
+          }),
+        }
+      }
+
+      if (options.tags?.length) {
+        body.categories = options.tags
+      }
+
+      if (options.metadata) {
+        body.custom_args = options.metadata
+      }
+
+      try {
+        const response = await fetch(`${SENDGRID_API_URL}/mail/send`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify(body),
+        })
+
+        if (response.ok || response.status === 202) {
+          const messageId = response.headers.get('X-Message-Id') || undefined
+          return { success: true, messageId }
+        }
+
+        const errorData = await response.json().catch(() => ({}))
+        return {
+          success: false,
+          error: {
+            code: `HTTP_${response.status}`,
+            message: (errorData as any)?.errors?.[0]?.message || response.statusText,
+          },
+        }
+      } catch (error) {
+        return {
+          success: false,
+          error: {
+            code: 'NETWORK_ERROR',
+            message: error instanceof Error ? error.message : 'Unknown error',
+          },
+        }
+      }
+    },
+
+    async sendBatch(emails: SendEmailOptions[]): Promise<SendEmailResult[]> {
+      // SendGrid doesn't have a true batch endpoint, so we send in parallel
+      return Promise.all(emails.map((email) => this.send(email)))
+    },
+  }
+}
+
+/**
+ * SendGrid provider definition
+ */
+export const sendgridProvider = defineProvider(sendgridInfo, async (config) =>
+  createSendGridProvider(config)
+)

package/src/providers/finance/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Finance Providers
+ *
+ * @packageDocumentation
+ */
+
+export { stripeInfo, stripeProvider, createStripeProvider } from './stripe.js'
+
+import { stripeProvider } from './stripe.js'
+
+/**
+ * Register all finance providers
+ */
+export function registerFinanceProviders(): void {
+  stripeProvider.register()
+}
+
+/**
+ * All finance providers
+ */
+export const financeProviders = [stripeProvider]