@tratto/email 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,562 @@
+declare class TrattoError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly docs?: string | undefined;
+    constructor(message: string, code: string, statusCode: number, docs?: string | undefined);
+}
+
+interface FetchOptions {
+    body?: unknown;
+    contentType?: string;
+    headers?: Record<string, string>;
+}
+declare abstract class BaseResource {
+    protected readonly apiKey: string;
+    protected readonly baseUrl: string;
+    constructor(apiKey: string, baseUrl: string);
+    protected fetch<T>(method: string, path: string, options?: FetchOptions): Promise<T>;
+    protected fetchData<T>(method: string, path: string, options?: FetchOptions): Promise<T>;
+    protected buildQuery(params: Record<string, string | number | boolean | Date | null | undefined>): string;
+}
+
+interface Pagination {
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: Pagination;
+}
+interface SendEmailParams {
+    from: string;
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    cc?: string[];
+    bcc?: string[];
+    replyTo?: string;
+    templateId?: string;
+    variables?: Record<string, unknown>;
+    tags?: string[];
+    scheduledAt?: Date | string;
+    headers?: Record<string, string>;
+}
+interface ListEmailsParams {
+    after?: string;
+    limit?: number;
+    status?: string;
+    domainId?: string;
+    tags?: string;
+    dateFrom?: Date | string;
+    dateTo?: Date | string;
+}
+interface EmailSummary {
+    id: string;
+    from: string;
+    to: string[];
+    subject: string;
+    status: string;
+    createdAt: string;
+    sentAt: string | null;
+    scheduledAt: string | null;
+    tags?: string[];
+}
+interface EmailEvent {
+    type: string;
+    occurredAt: string;
+    data?: Record<string, unknown>;
+}
+interface EmailDetail extends EmailSummary {
+    html?: string;
+    text?: string;
+    cc?: string[];
+    bcc?: string[];
+    replyTo?: string;
+    templateId?: string;
+    headers?: Record<string, string>;
+    events: EmailEvent[];
+}
+type ContactStatus = 'subscribed' | 'unsubscribed' | 'bounced' | 'complained';
+interface Contact {
+    id: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    status: ContactStatus;
+    tags: string[];
+    customFields: Record<string, unknown>;
+    createdAt: string;
+}
+interface CreateContactParams {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    status?: ContactStatus;
+    tags?: string[];
+    customFields?: Record<string, unknown>;
+}
+interface UpdateContactParams {
+    firstName?: string;
+    lastName?: string;
+    status?: ContactStatus;
+    tags?: string[];
+    customFields?: Record<string, unknown>;
+}
+interface ListContactsParams {
+    status?: ContactStatus;
+    audienceId?: string;
+    tag?: string;
+    after?: string;
+    limit?: number;
+}
+interface ImportJobStatus {
+    jobId: string;
+    status: 'processing' | 'completed' | 'failed';
+    totalRows: number;
+    processedRows: number;
+    failedRows: number;
+    errors: string[];
+    completedAt: string | null;
+}
+type AudienceRuleOperator = 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'array_contains';
+interface AudienceRule {
+    field: string;
+    operator: AudienceRuleOperator;
+    value: string | number | boolean;
+}
+interface Audience {
+    id: string;
+    name: string;
+    description: string;
+    contactCount: number;
+    rules: AudienceRule[];
+    createdAt: string;
+}
+interface CreateAudienceParams {
+    name: string;
+    description?: string;
+    rules?: AudienceRule[];
+}
+interface ListAudiencesParams {
+    after?: string;
+    limit?: number;
+}
+interface AddContactsToAudienceResult {
+    added: number;
+    alreadyInAudience: number;
+    notFound: number;
+}
+type CampaignStatus = 'draft' | 'sending' | 'scheduled' | 'paused' | 'completed';
+interface CampaignStats {
+    total: number;
+    sent: number;
+    delivered: number;
+    opened: number;
+    clicked: number;
+    bounced: number;
+}
+interface Campaign {
+    id: string;
+    name: string;
+    status: CampaignStatus;
+    templateId: string;
+    audienceId: string;
+    fromName: string;
+    fromEmail: string;
+    subjectA: string;
+    subjectB: string | null;
+    scheduledAt: string | null;
+    sentAt: string | null;
+    stats: CampaignStats;
+    createdAt: string;
+}
+interface CampaignStatsDetail {
+    campaignId: string;
+    status: CampaignStatus;
+    stats: CampaignStats;
+    rates: {
+        deliveryRate: number;
+        openRate: number;
+        clickRate: number;
+        bounceRate: number;
+    };
+}
+interface CreateCampaignParams {
+    name: string;
+    templateId: string;
+    audienceId: string;
+    fromName: string;
+    fromEmail: string;
+    subjectA: string;
+    subjectB?: string;
+}
+interface ListCampaignsParams {
+    status?: CampaignStatus;
+    after?: string;
+    limit?: number;
+}
+interface SendCampaignParams {
+    scheduledAt?: Date | string;
+}
+type TemplateStatus = 'draft' | 'published';
+interface TemplateSummary {
+    id: string;
+    name: string;
+    status: TemplateStatus;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Template extends TemplateSummary {
+    html: string;
+}
+interface CreateTemplateParams {
+    name: string;
+    html?: string;
+}
+interface UpdateTemplateParams {
+    name?: string;
+    html?: string;
+    status?: TemplateStatus;
+}
+interface ListTemplatesParams {
+    limit?: number;
+    after?: string;
+    status?: TemplateStatus;
+}
+interface TemplateVersionSummary {
+    version: number;
+    savedAt: string;
+}
+interface TemplateVersion extends TemplateVersionSummary {
+    html: string;
+}
+type WebhookEventType = 'sent' | 'delivered' | 'opened' | 'clicked' | 'bounced' | 'complained' | 'unsubscribed';
+type WebhookStatus = 'active' | 'disabled';
+type WebhookDeliveryStatus = 'success' | 'failed' | 'scheduled';
+interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEventType[];
+    status: WebhookStatus;
+    secretPrefix: string;
+    failureCount: number;
+    createdAt: string;
+}
+interface WebhookDelivery {
+    id: string;
+    webhookId: string;
+    eventType: string;
+    status: WebhookDeliveryStatus;
+    httpStatus: number | null;
+    responseBody: string | null;
+    retryCount: number;
+    attemptedAt: string;
+}
+interface CreateWebhookParams {
+    url: string;
+    events: WebhookEventType[];
+}
+interface ListWebhookDeliveriesParams {
+    after?: string;
+    limit?: number;
+}
+type DomainStatus = 'pending' | 'verified' | 'failed';
+interface DomainRecord {
+    type: string;
+    host: string;
+    value: string;
+    verified: boolean;
+}
+interface DomainSummary {
+    id: string;
+    domain: string;
+    status: DomainStatus;
+    dkimSelector: string;
+    createdAt: string;
+    updatedAt: string;
+    verifiedAt: string | null;
+}
+interface Domain extends DomainSummary {
+    records: DomainRecord[];
+}
+interface ListDomainsParams {
+    after?: string;
+    limit?: number;
+}
+type ApiKeyEnv = 'live' | 'test';
+interface ApiKey {
+    id: string;
+    name: string;
+    prefix: string;
+    env: ApiKeyEnv;
+    permissions: string[];
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}
+interface ApiKeyCreated extends ApiKey {
+    key: string;
+}
+interface CreateApiKeyParams {
+    name: string;
+    env: ApiKeyEnv;
+    permissions: string[];
+}
+interface ListApiKeysParams {
+    after?: string;
+    limit?: number;
+}
+type AnalyticsPeriod = '7d' | '30d' | '90d';
+interface AnalyticsSummary {
+    period: AnalyticsPeriod;
+    totalSent: number;
+    delivered: number;
+    opened: number;
+    clicked: number;
+    bounced: number;
+    complained: number;
+    deliveryRate: number;
+    openRate: number;
+    clickRate: number;
+    bounceRate: number;
+}
+interface TimeseriesPoint {
+    date: string;
+    sent: number;
+    delivered: number;
+    opened: number;
+    bounced: number;
+}
+type FlowStatus = 'draft' | 'active' | 'inactive';
+type FlowTriggerType = 'contact_joins_audience' | 'contact_tag_added' | 'contact_tag_removed' | 'email_event' | 'manual';
+type FlowStepType = 'send_email' | 'wait' | 'branch' | 'update_contact' | 'webhook_call';
+interface FlowTrigger {
+    type: FlowTriggerType;
+    config: Record<string, string>;
+}
+interface FlowStep {
+    id: string;
+    type: FlowStepType;
+    config: Record<string, string>;
+}
+interface Flow {
+    id: string;
+    name: string;
+    status: FlowStatus;
+    trigger: FlowTrigger;
+    steps: FlowStep[];
+    enrollments: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateFlowParams {
+    name: string;
+}
+interface UpdateFlowParams {
+    name?: string;
+    trigger?: FlowTrigger;
+    steps?: FlowStep[];
+}
+interface ListFlowsParams {
+    after?: string;
+    limit?: number;
+}
+type WorkspacePlan = 'free' | 'starter' | 'growth';
+type WorkspaceMemberRole = 'owner' | 'admin' | 'member';
+type WorkspaceLocale = 'it' | 'en';
+interface Workspace {
+    id: string;
+    name: string;
+    slug: string;
+    timezone: string;
+    locale: WorkspaceLocale;
+    plan: WorkspacePlan;
+    createdAt: string;
+}
+interface WorkspaceMember {
+    userId: string;
+    email: string;
+    displayName: string | null;
+    role: WorkspaceMemberRole;
+    joinedAt: string;
+}
+interface WorkspacePreferences {
+    locale: WorkspaceLocale;
+    emailNotifications: {
+        bounces: boolean;
+        weeklyReport: boolean;
+        billingAlerts: boolean;
+    };
+}
+interface UpdateWorkspaceParams {
+    name?: string;
+    slug?: string;
+    timezone?: string;
+    locale?: WorkspaceLocale;
+}
+interface UpdateWorkspacePreferencesParams {
+    locale?: WorkspaceLocale;
+    emailNotifications?: {
+        bounces?: boolean;
+        weeklyReport?: boolean;
+        billingAlerts?: boolean;
+    };
+}
+interface InviteMemberParams {
+    email: string;
+    role: 'admin' | 'member';
+}
+interface UpdateMemberParams {
+    role: WorkspaceMemberRole;
+}
+
+declare class EmailsResource extends BaseResource {
+    send(params: SendEmailParams, idempotencyKey?: string): Promise<{
+        id: string;
+    }>;
+    list(params?: ListEmailsParams): Promise<PaginatedResponse<EmailSummary>>;
+    get(id: string): Promise<EmailDetail>;
+    listEvents(id: string): Promise<EmailEvent[]>;
+}
+
+declare class ContactsResource extends BaseResource {
+    create(params: CreateContactParams): Promise<{
+        id: string;
+    }>;
+    list(params?: ListContactsParams): Promise<PaginatedResponse<Contact>>;
+    update(id: string, params: UpdateContactParams): Promise<{
+        id: string;
+    }>;
+    importCsv(csvText: string): Promise<{
+        jobId: string;
+        totalRows: number;
+    }>;
+    getImportJob(jobId: string): Promise<ImportJobStatus>;
+}
+
+declare class AudiencesResource extends BaseResource {
+    create(params: CreateAudienceParams): Promise<{
+        id: string;
+    }>;
+    list(params?: ListAudiencesParams): Promise<PaginatedResponse<Audience>>;
+    get(id: string): Promise<Audience>;
+    addContacts(audienceId: string, contactIds: string[]): Promise<AddContactsToAudienceResult>;
+}
+
+declare class CampaignsResource extends BaseResource {
+    create(params: CreateCampaignParams): Promise<{
+        id: string;
+    }>;
+    list(params?: ListCampaignsParams): Promise<PaginatedResponse<Campaign>>;
+    get(id: string): Promise<Campaign>;
+    getStats(id: string): Promise<CampaignStatsDetail>;
+    send(id: string, params?: SendCampaignParams): Promise<{
+        status: string;
+    }>;
+    pause(id: string): Promise<{
+        status: string;
+    }>;
+    testSend(id: string, to: string): Promise<{
+        emailId: string;
+    }>;
+}
+
+declare class TemplatesResource extends BaseResource {
+    list(params?: ListTemplatesParams): Promise<PaginatedResponse<TemplateSummary>>;
+    create(params: CreateTemplateParams): Promise<Template>;
+    get(id: string): Promise<Template>;
+    update(id: string, params: UpdateTemplateParams): Promise<Template>;
+    delete(id: string): Promise<void>;
+    listVersions(id: string): Promise<TemplateVersionSummary[]>;
+    getVersion(id: string, version: number): Promise<TemplateVersion>;
+    testSend(id: string, to: string, variables?: Record<string, string>): Promise<{
+        queued: boolean;
+    }>;
+}
+
+declare class WebhooksResource extends BaseResource {
+    create(params: CreateWebhookParams): Promise<{
+        id: string;
+        secret: string;
+    }>;
+    list(): Promise<Webhook[]>;
+    delete(id: string): Promise<void>;
+    listDeliveries(id: string, params?: ListWebhookDeliveriesParams): Promise<PaginatedResponse<WebhookDelivery>>;
+    test(id: string): Promise<{
+        queued: boolean;
+    }>;
+    rotateSecret(id: string): Promise<{
+        secret: string;
+    }>;
+}
+
+declare class DomainsResource extends BaseResource {
+    add(domain: string): Promise<Domain>;
+    list(params?: ListDomainsParams): Promise<PaginatedResponse<DomainSummary>>;
+    get(id: string): Promise<Domain>;
+    verify(id: string): Promise<Domain>;
+    delete(id: string): Promise<{
+        id: string;
+        deletedAt: string;
+    }>;
+}
+
+declare class ApiKeysResource extends BaseResource {
+    create(params: CreateApiKeyParams, idempotencyKey?: string): Promise<ApiKeyCreated>;
+    list(params?: ListApiKeysParams): Promise<PaginatedResponse<ApiKey>>;
+    revoke(id: string): Promise<{
+        id: string;
+        revokedAt: string;
+    }>;
+}
+
+declare class AnalyticsResource extends BaseResource {
+    getSummary(period?: AnalyticsPeriod): Promise<AnalyticsSummary>;
+    getTimeseries(period?: AnalyticsPeriod): Promise<TimeseriesPoint[]>;
+}
+
+declare class FlowsResource extends BaseResource {
+    list(params?: ListFlowsParams): Promise<PaginatedResponse<Flow>>;
+    create(params: CreateFlowParams): Promise<{
+        id: string;
+    }>;
+    get(id: string): Promise<Flow>;
+    update(id: string, params: UpdateFlowParams): Promise<Flow>;
+    delete(id: string): Promise<{
+        id: string;
+    }>;
+    activate(id: string): Promise<Flow>;
+    deactivate(id: string): Promise<Flow>;
+}
+
+declare class WorkspaceResource extends BaseResource {
+    get(): Promise<Workspace>;
+    update(params: UpdateWorkspaceParams): Promise<Workspace>;
+    delete(): Promise<void>;
+    updatePreferences(params: UpdateWorkspacePreferencesParams): Promise<WorkspacePreferences>;
+    inviteMember(params: InviteMemberParams): Promise<WorkspaceMember>;
+    updateMember(userId: string, params: UpdateMemberParams): Promise<WorkspaceMember>;
+    removeMember(userId: string): Promise<void>;
+}
+
+interface TrattoOptions {
+    baseUrl?: string;
+}
+declare class Tratto {
+    readonly emails: EmailsResource;
+    readonly contacts: ContactsResource;
+    readonly audiences: AudiencesResource;
+    readonly campaigns: CampaignsResource;
+    readonly templates: TemplatesResource;
+    readonly webhooks: WebhooksResource;
+    readonly domains: DomainsResource;
+    readonly apiKeys: ApiKeysResource;
+    readonly analytics: AnalyticsResource;
+    readonly flows: FlowsResource;
+    readonly workspace: WorkspaceResource;
+    constructor(apiKey: string, options?: TrattoOptions);
+}
+
+export { type AddContactsToAudienceResult, type AnalyticsPeriod, type AnalyticsSummary, type ApiKey, type ApiKeyCreated, type ApiKeyEnv, type Audience, type AudienceRule, type AudienceRuleOperator, type Campaign, type CampaignStats, type CampaignStatsDetail, type CampaignStatus, type Contact, type ContactStatus, type CreateApiKeyParams, type CreateAudienceParams, type CreateCampaignParams, type CreateContactParams, type CreateFlowParams, type CreateTemplateParams, type CreateWebhookParams, type Domain, type DomainRecord, type DomainStatus, type DomainSummary, type EmailDetail, type EmailEvent, type EmailSummary, type Flow, type FlowStatus, type FlowStep, type FlowStepType, type FlowTrigger, type FlowTriggerType, type ImportJobStatus, type InviteMemberParams, type ListApiKeysParams, type ListAudiencesParams, type ListCampaignsParams, type ListContactsParams, type ListDomainsParams, type ListEmailsParams, type ListFlowsParams, type ListTemplatesParams, type ListWebhookDeliveriesParams, type PaginatedResponse, type Pagination, type SendCampaignParams, type SendEmailParams, type Template, type TemplateStatus, type TemplateSummary, type TemplateVersion, type TemplateVersionSummary, type TimeseriesPoint, Tratto, TrattoError, type TrattoOptions, type UpdateContactParams, type UpdateFlowParams, type UpdateMemberParams, type UpdateTemplateParams, type UpdateWorkspaceParams, type UpdateWorkspacePreferencesParams, type Webhook, type WebhookDelivery, type WebhookDeliveryStatus, type WebhookEventType, type WebhookStatus, type Workspace, type WorkspaceLocale, type WorkspaceMember, type WorkspaceMemberRole, type WorkspacePlan, type WorkspacePreferences };