@develemail/sdk 0.1.1 → 0.4.1

package/dist/index.d.ts

@@ -1,35 +1,135 @@
 interface DevelEmailConfig {
     apiKey: string;
     baseUrl: string;
+    maxRetries?: number;
 }
+
+/** Wire-format attachment shape — what actually goes over HTTP. */
+interface WireAttachmentInput {
+    filename: string;
+    content: string;
+    contentType: string;
+}
+/** Ergonomic attachment input for `emails.send()` / `emails.batch()`. */
+interface AttachmentInput {
+    filename: string;
+    content: string | Uint8Array;
+    contentType: string;
+}
+/**
+ * Deliberately different from the API's `SendEmailInput` in `attachments`
+ * only: this is the ergonomic pre-request shape while the API type is the
+ * post-parse wire shape. Every other field matches exactly.
+ */
 interface SendEmailInput {
+    /**
+     * Sender. Either a bare address (`noreply@example.com`) or a display-name
+     * mailbox (`Acme <noreply@example.com>`). Names containing commas or
+     * specials must be quoted (`"Acme, Inc." <noreply@example.com>`); non-ASCII
+     * names are encoded for you. The address domain must be verified.
+     */
     from: string;
     to: string | string[];
-    subject: string;
+    subject?: string;
     html?: string;
     text?: string;
     tags?: string[];
     metadata?: Record<string, unknown>;
+    template?: string;
+    variables?: Record<string, string>;
+    send_at?: string;
+    attachments?: AttachmentInput[];
+    /** RFC 5322 Message-ID (angle brackets included, e.g. `<id@host>`). */
+    inReplyTo?: string;
+    /** Same Message-ID format as `inReplyTo`, oldest first. */
+    references?: string[];
 }
+interface SendOptions {
+    idempotencyKey?: string;
+}
+/** Mirrors `apps/api/src/domains/emails/types.ts`'s server-side copy. */
 interface EmailResponse {
     id: string;
     status: string;
+    duplicate?: boolean;
 }
-declare class DevelEmailError extends Error {
-    readonly status: number;
-    constructor(status: number, message: string);
+interface BatchEmailResultItem {
+    index: number;
+    id?: string;
+    status?: string;
+    duplicate?: boolean;
+    error?: string;
+    code?: string;
 }
-declare class EmailsNamespace {
-    private readonly config;
-    constructor(config: DevelEmailConfig);
-    send(input: SendEmailInput): Promise<EmailResponse>;
-    get(id: string): Promise<EmailResponse>;
-    private request;
+interface BatchEmailResponse {
+    results: BatchEmailResultItem[];
+    created: number;
+    errors: number;
+    limitReached?: boolean;
 }
-declare class DevelEmail {
-    readonly emails: EmailsNamespace;
-    constructor(config: DevelEmailConfig);
+/** Every status an email can be in. */
+declare const EMAIL_STATUSES: readonly ["queued", "rendering", "submitted_to_postfix", "deferred", "sent", "delivered", "bounced", "rejected", "failed", "suppressed", "cancelled", "scheduled", "quarantined", "sandboxed"];
+type EmailStatus = (typeof EMAIL_STATUSES)[number];
+/** Every event type the server currently emits. */
+declare const EMAIL_EVENT_TYPES: readonly ["queued", "rendering_started", "rendering_completed", "submitted_to_postfix", "deferred", "sent", "delivered", "bounced", "rejected", "failed", "suppressed", "cancelled", "retry_scheduled", "open", "click", "quarantined"];
+type EmailEventType = (typeof EMAIL_EVENT_TYPES)[number];
+/** `metadata` shape for Postfix-derived lifecycle events. */
+interface DeliveryEventData {
+    queueId: string;
+    relay: string;
+    response: string;
+    timestamp: string;
 }
+
+interface Domain {
+    id: string;
+    organizationId: string;
+    name: string;
+    verificationStatus: string;
+    spfStatus: string | null;
+    dkimStatus: string | null;
+    dmarcStatus: string | null;
+    ptrStatus: string | null;
+    mxStatus: string | null;
+    returnPathStatus: string | null;
+    dmarcPolicy: string | null;
+    dkimPublicKey: string;
+    dkimSelector: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface DomainCreateInput {
+    name: string;
+    dkimSelector?: string;
+}
+
+interface Template {
+    id: string;
+    organizationId: string;
+    name: string;
+    subject: string;
+    html: string;
+    text?: string | null;
+    variables?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface TemplateCreateInput {
+    name: string;
+    subject: string;
+    html: string;
+    text?: string;
+    variables?: string[];
+}
+interface TemplateUpdateInput {
+    name?: string;
+    subject?: string;
+    html?: string;
+    text?: string;
+    variables?: string[];
+}
+
+/** Mirrors `apps/api/src/domains/webhooks/types.ts`'s `WebhookPayload`. */
 interface WebhookEvent {
     event: string;
     emailId: string | null;
@@ -38,6 +138,354 @@ interface WebhookEvent {
     timestamp: string;
     metadata: Record<string, unknown>;
 }
+
+type CampaignStatus = 'draft' | 'scheduled' | 'sending' | 'paused' | 'sent' | 'cancelled';
+interface Campaign {
+    id: string;
+    projectId: string;
+    listId: string | null;
+    tagFilters: string[] | null;
+    tagFilterMode: 'and' | 'or' | null;
+    templateId: string | null;
+    name: string;
+    subject: string;
+    fromAddress: string;
+    fromName: string | null;
+    rawHtml: string | null;
+    rawText: string | null;
+    status: CampaignStatus;
+    scheduledFor: string | null;
+    sentAt: string | null;
+    totalRecipients: number | null;
+    summarizedStats: {
+        delivered?: number;
+        deliveryUnknown?: number;
+        opened?: number;
+        clicked?: number;
+        bounced?: number;
+        configurationBounced?: number;
+        unsubscribed?: number;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** The SDK accepts optional pagination before the API applies defaults. */
+interface CampaignListQuery {
+    projectId: string;
+    status?: CampaignStatus;
+    limit?: number;
+    offset?: number;
+}
+interface CampaignCreateInput {
+    projectId: string;
+    listId?: string;
+    tagFilters?: string[];
+    tagFilterMode?: 'and' | 'or';
+    templateId?: string;
+    name: string;
+    subject: string;
+    fromAddress: string;
+    fromName?: string;
+    rawHtml?: string;
+    rawText?: string;
+    scheduledFor?: string;
+}
+interface CampaignUpdateInput {
+    listId?: string | null;
+    tagFilters?: string[] | null;
+    tagFilterMode?: 'and' | 'or';
+    templateId?: string | null;
+    name?: string;
+    subject?: string;
+    fromAddress?: string;
+    fromName?: string;
+    rawHtml?: string;
+    rawText?: string;
+    scheduledFor?: string;
+}
+/** Mirrors `apps/api/src/domains/campaigns/types.ts`'s server-side copy. */
+interface CampaignStats {
+    campaignId: string;
+    totalRecipients: number;
+    delivered: number;
+    deliveryUnknown: number;
+    opened: number;
+    clicked: number;
+    /** Reputation bounces only; configuration bounces are in `configurationBounced`. */
+    bounced: number;
+    configurationBounced: number;
+    unsubscribed: number;
+    openRate: number;
+    clickRate: number;
+    bounceRate: number;
+    links: Array<{
+        url: string;
+        clicks: number;
+    }>;
+}
+interface CampaignProviderStats {
+    provider: string;
+    opens: number;
+    clicks: number;
+    total: number;
+}
+
+interface Contact {
+    id: string;
+    projectId: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    country: string | null;
+    tags: string[];
+    unsubscribedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** The SDK preserves optional filters before API parsing/defaulting. */
+interface ContactListQuery {
+    projectId: string;
+    search?: string;
+    tags?: string[];
+    tagMode?: 'and' | 'or';
+    limit?: number;
+    offset?: number;
+}
+interface ContactListResponse {
+    data: Contact[];
+    total: number;
+}
+interface ContactCreateInput {
+    projectId: string;
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    tags?: string[];
+}
+interface ContactUpdateInput {
+    unsubscribe: boolean;
+}
+interface ContactBulkContactInput {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    country?: string;
+    tags?: string[];
+}
+interface ContactBulkInput {
+    projectId: string;
+    contacts: ContactBulkContactInput[];
+}
+interface ContactBulkResponse {
+    inserted: number;
+    updated: number;
+    skipped: number;
+}
+/** `addedAt` is serialized to string for SDK consumers. */
+interface ContactListItem {
+    id: string;
+    name: string;
+    memberCount: number;
+    addedAt: string;
+}
+
+interface List {
+    id: string;
+    projectId: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** API dates are serialized to strings for SDK consumers. */
+interface ListWithCount extends List {
+    memberCount: number;
+}
+interface ListCreateInput {
+    projectId: string;
+    name: string;
+    description?: string;
+}
+interface ListUpdateInput {
+    name?: string;
+    description?: string;
+}
+interface ListMembersQuery {
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+interface ListMembersResponse {
+    data: Contact[];
+    total: number;
+}
+
+/** Mirrors `apps/api/src/domains/sms/repo.types.ts`'s status values. */
+declare const SMS_STATUSES: readonly ["queued", "sending", "sent", "delivered", "deferred", "failed", "suppressed"];
+type SmsStatus = (typeof SMS_STATUSES)[number];
+/** Mirrors `apps/api/src/domains/sms/types.ts`'s `SendSmsInput`. */
+interface SendSmsInput {
+    to: string;
+    from?: string;
+    body?: string;
+    templateName?: string;
+    variables?: Record<string, string>;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface SmsMessageResponse {
+    id: string;
+    to: string;
+    from: string | null;
+    body: string;
+    status: string;
+    tags: string[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface SmsListResponse {
+    data: SmsMessageResponse[];
+    nextCursor: string | null;
+}
+interface SmsListQuery {
+    status?: SmsStatus;
+    limit?: number;
+    cursor?: string;
+}
+interface BatchSmsResultItem {
+    index: number;
+    id?: string;
+    status?: string;
+    error?: string;
+    code?: string;
+}
+interface BatchSmsResponse {
+    results: BatchSmsResultItem[];
+    created: number;
+    errors: number;
+}
+
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly maxRetries;
+    constructor(config: DevelEmailConfig);
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    put<T>(path: string, body: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    patch<T>(path: string, body: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+    delete<T>(path: string, extraHeaders?: Record<string, string>): Promise<T>;
+    private request;
+    private backoff;
+}
+
+declare class Emails {
+    private readonly http;
+    constructor(http: HttpClient);
+    send(input: SendEmailInput, options?: SendOptions): Promise<EmailResponse>;
+    batch(emails: SendEmailInput[], options?: SendOptions): Promise<BatchEmailResponse>;
+    get(id: string): Promise<EmailResponse>;
+}
+
+declare class Domains {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<Domain[]>;
+    get(id: string): Promise<Domain>;
+    create(input: DomainCreateInput): Promise<Domain>;
+    delete(id: string): Promise<void>;
+    verify(id: string): Promise<Domain>;
+}
+
+declare class Templates {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<Template[]>;
+    get(id: string): Promise<Template>;
+    create(input: TemplateCreateInput): Promise<Template>;
+    update(id: string, input: TemplateUpdateInput): Promise<Template>;
+    delete(id: string): Promise<void>;
+}
+
+declare class Campaigns {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(query: CampaignListQuery): Promise<Campaign[]>;
+    get(id: string): Promise<Campaign>;
+    create(input: CampaignCreateInput): Promise<Campaign>;
+    update(id: string, input: CampaignUpdateInput): Promise<Campaign>;
+    send(id: string): Promise<Campaign>;
+    pause(id: string): Promise<Campaign>;
+    resume(id: string): Promise<Campaign>;
+    cancel(id: string): Promise<Campaign & {
+        note: string;
+    }>;
+    duplicate(id: string): Promise<Campaign>;
+    delete(id: string): Promise<void>;
+    stats(id: string): Promise<CampaignStats>;
+    providerStats(id: string): Promise<CampaignProviderStats[]>;
+}
+
+declare class Contacts {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(query: ContactListQuery): Promise<ContactListResponse>;
+    get(id: string): Promise<Contact>;
+    create(input: ContactCreateInput): Promise<Contact>;
+    update(id: string, input: ContactUpdateInput): Promise<Contact>;
+    delete(id: string): Promise<void>;
+    bulkCreate(input: ContactBulkInput): Promise<ContactBulkResponse>;
+    tags(projectId: string): Promise<string[]>;
+    lists(contactId: string): Promise<ContactListItem[]>;
+    /** @deprecated Use `lists.addContacts` instead. */
+    addToList(contactId: string, listId: string): Promise<void>;
+    /** @deprecated Use `lists.removeContact` instead. */
+    removeFromList(contactId: string, listId: string): Promise<void>;
+}
+
+declare class Lists {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(projectId: string): Promise<ListWithCount[]>;
+    get(id: string): Promise<List>;
+    create(input: ListCreateInput): Promise<List>;
+    update(id: string, input: ListUpdateInput): Promise<List>;
+    delete(id: string): Promise<void>;
+    listContacts(id: string, query?: ListMembersQuery): Promise<ListMembersResponse>;
+    addContacts(id: string, contactIds: string[]): Promise<{
+        added: number;
+    }>;
+    removeContact(id: string, contactId: string): Promise<void>;
+}
+
+declare class Sms {
+    private readonly http;
+    constructor(http: HttpClient);
+    send(input: SendSmsInput, options?: SendOptions): Promise<SmsMessageResponse>;
+    sendBatch(messages: SendSmsInput[], options?: SendOptions): Promise<BatchSmsResponse>;
+    get(id: string): Promise<SmsMessageResponse>;
+    list(query?: SmsListQuery): Promise<SmsListResponse>;
+}
+
+declare class DevelEmailError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(status: number, message: string, code?: string | undefined, details?: Record<string, unknown> | undefined);
+}
+
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): Promise<boolean>;
 
-export { DevelEmail, type DevelEmailConfig, DevelEmailError, type EmailResponse, type SendEmailInput, type WebhookEvent, verifyWebhookSignature };
+declare class DevelEmail {
+    readonly emails: Emails;
+    readonly domains: Domains;
+    readonly templates: Templates;
+    readonly campaigns: Campaigns;
+    readonly contacts: Contacts;
+    readonly lists: Lists;
+    readonly sms: Sms;
+    constructor(config: DevelEmailConfig);
+}
+
+export { type AttachmentInput, type BatchEmailResponse, type BatchEmailResultItem, type BatchSmsResponse, type BatchSmsResultItem, type Campaign, type CampaignCreateInput, type CampaignListQuery, type CampaignProviderStats, type CampaignStats, type CampaignStatus, type CampaignUpdateInput, type Contact, type ContactBulkContactInput, type ContactBulkInput, type ContactBulkResponse, type ContactCreateInput, type ContactListItem, type ContactListQuery, type ContactListResponse, type ContactUpdateInput, type DeliveryEventData, DevelEmail, type DevelEmailConfig, DevelEmailError, type Domain, type DomainCreateInput, EMAIL_EVENT_TYPES, EMAIL_STATUSES, type EmailEventType, type EmailResponse, type EmailStatus, type List, type ListCreateInput, type ListMembersQuery, type ListMembersResponse, type ListUpdateInput, type ListWithCount, SMS_STATUSES, type SendEmailInput, type SendOptions, type SendSmsInput, type SmsListQuery, type SmsListResponse, type SmsMessageResponse, type SmsStatus, type Template, type TemplateCreateInput, type TemplateUpdateInput, type WebhookEvent, type WireAttachmentInput, verifyWebhookSignature };