@develemail/sdk 0.1.0 → 0.4.0

package/dist/index.d.cts

@@ -1,34 +1,557 @@
 interface DevelEmailConfig {
     apiKey: string;
     baseUrl: string;
+    maxRetries?: number;
 }
+/**
+ * Wire-format attachment shape — what actually goes over HTTP (`content` is
+ * already base64). Mirrors `apps/api/src/domains/emails/types.ts`'s
+ * `AttachmentInput` field-for-field; kept as a distinct name from the
+ * ergonomic `AttachmentInput` below so the DTO contract test can assert the
+ * wire shape while `emails.send()`/`emails.batch()` callers get
+ * base64/Buffer ergonomics. Exported only for `apps/api`'s DTO contract
+ * test to import — not part of the ergonomic public surface callers build
+ * requests with.
+ */
+interface WireAttachmentInput {
+    filename: string;
+    content: string;
+    contentType: string;
+}
+/**
+ * Ergonomic attachment input for `emails.send()` / `emails.batch()`.
+ * `content` accepts a `Uint8Array` (covers Node `Buffer`) — the SDK
+ * base64-encodes it before the request goes out — or an already-base64
+ * `string`, matching the wire format directly.
+ *
+ * Server caps: max 10 attachments per email, 5 MiB per file (decoded),
+ * 7 MiB combined decoded size per email.
+ */
+interface AttachmentInput {
+    filename: string;
+    content: string | Uint8Array;
+    contentType: string;
+}
+/**
+ * Deliberately different from `apps/api/src/domains/emails/types.ts`'s
+ * `SendEmailInput` in `attachments` only: this is the ergonomic pre-request
+ * shape (`AttachmentInput.content: string | Uint8Array`) while the api's
+ * `z.infer`'d type is the post-parse wire shape (`content: string`,
+ * already base64). Every other field matches exactly — see
+ * `apps/api/src/sdk-dto-contract.test.ts`'s `Omit<..., 'attachments'>`
+ * assertion. See `apps/api/src/sdk-dto-contract-discovery.test.ts`'s
+ * registry for the enforcement.
+ */
 interface SendEmailInput {
     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[];
 }
+interface SendOptions {
+    idempotencyKey?: string;
+}
+/**
+ * Mirrors `apps/api/src/domains/emails/types.ts`'s server-side copy of this
+ * shape. Not imported from there: this package is published to npm for
+ * external consumers and can't depend on the private api app. Keep both
+ * copies in sync by hand when the wire shape changes; same for
+ * `BatchEmailResultItem` / `BatchEmailResponse` below.
+ */
 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;
+}
+interface BatchEmailResponse {
+    results: BatchEmailResultItem[];
+    created: number;
+    errors: number;
+    limitReached?: boolean;
+}
+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 Template {
+    id: string;
+    organizationId: string;
+    name: string;
+    subject: string;
+    html: string;
+    text?: string | null;
+    variables?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface DomainCreateInput {
+    name: string;
+    dkimSelector?: 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[];
+}
+/**
+ * Every status an email can be in. `delivered` means the recipient's mail
+ * gateway accepted the message with a 2xx response — it does not mean the
+ * message reached the inbox; it can still be filtered or quarantined
+ * afterward.
+ */
+declare const EMAIL_STATUSES: readonly ["queued", "rendering", "submitted_to_postfix", "deferred", "sent", "delivered", "bounced", "rejected", "failed", "suppressed", "cancelled", "scheduled", "quarantined"];
+type EmailStatus = (typeof EMAIL_STATUSES)[number];
+/**
+ * Every event type the server currently emits, including as a webhook's
+ * `event` field. `WebhookEvent.event` stays typed as `string` (not this
+ * union) because the server may add new event types over time — treat an
+ * unrecognized value as informational, not an error. See
+ * `docs/webhooks.md`: a project's webhook receives every event type below
+ * automatically, with no per-type opt-in.
+ */
+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 `delivered` / `deferred` / `bounced` webhook events
+ * and lifecycle-timeline entries — written by the Postfix log follower.
+ */
+interface DeliveryEventData {
+    queueId: string;
+    relay: string;
+    response: string;
+    timestamp: string;
+}
+/**
+ * Mirrors `apps/api/src/domains/webhooks/types.ts`'s `WebhookPayload`
+ * (different name, same shape) — see that file for why this isn't a shared
+ * import.
+ */
+interface WebhookEvent {
+    event: string;
+    emailId: string | null;
+    status: string | null;
+    recipient: string | null;
+    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;
+        unsubscribed?: number;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Deliberately different from `apps/api/src/domains/campaigns/types.ts`'s
+ * `CampaignListQuery` in `limit`/`offset` optionality, not a bug: this type
+ * describes what a caller may omit before the request is sent, while the
+ * api's `z.infer`'d type describes the post-parse shape after `.default()`
+ * has filled those fields in. Both are correct for what they represent — see
+ * `apps/api/src/sdk-dto-contract-discovery.test.ts`'s registry for the
+ * enforcement.
+ */
+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 of
+ * this shape (and `CampaignProviderStats` below) — see that file for why
+ * this isn't a shared import.
+ */
+interface CampaignStats {
+    campaignId: string;
+    totalRecipients: number;
+    delivered: number;
+    deliveryUnknown: number;
+    opened: number;
+    clicked: number;
+    bounced: 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 List {
+    id: string;
+    projectId: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Deliberately different from `apps/api/src/domains/lists/types.ts`'s
+ * `ListWithCount` in `createdAt`/`updatedAt` (inherited from `List` above),
+ * not a bug: this describes what a client receives after the wire
+ * round-trip (`string`), while the api's type is the server-side shape held
+ * before JSON serialization (`Date`, via drizzle's `$inferSelect`). See
+ * `apps/api/src/sdk-dto-contract-discovery.test.ts`'s registry for the
+ * enforcement.
+ */
+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;
+}
+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;
+}
+/**
+ * Deliberately different from `apps/api/src/domains/contacts/types.ts`'s
+ * `ContactListQuery` in `tags`/`tagMode`, not a bug: the api type is
+ * `z.infer<typeof ContactListQuerySchema>` — `tags` is post-transform
+ * `string[]` and `tagMode` is post-`.default()` required — while this is the
+ * pre-request shape callers build, where both stay optional. See
+ * `apps/api/src/sdk-dto-contract-discovery.test.ts`'s registry for the
+ * enforcement.
+ */
+interface ContactListQuery {
+    projectId: string;
+    search?: string;
+    tags?: string[];
+    tagMode?: 'and' | 'or';
+    limit?: number;
+    offset?: number;
 }
-declare class EmailsNamespace {
-    private readonly config;
+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;
+}
+/**
+ * Deliberately different from `apps/api/src/domains/contacts/types.ts`'s
+ * `ContactListItem` in `addedAt`, not a bug: this describes what a client
+ * receives after the wire round-trip (`string`), while the api's type is
+ * the server-side shape held before JSON serialization (`Date`). See
+ * `apps/api/src/sdk-dto-contract-discovery.test.ts`'s registry for the
+ * enforcement.
+ */
+interface ContactListItem {
+    id: string;
+    name: string;
+    memberCount: number;
+    addedAt: string;
+}
+/**
+ * Mirrors `apps/api/src/domains/sms/repo.types.ts`'s `smsStatusEnum` values
+ * (`packages/db/src/schema/enums.ts`). Kept as a local literal union rather
+ * than an import — this package can't depend on `@develemail/db`, same
+ * reason `EMAIL_STATUSES` above is hand-copied instead of imported.
+ */
+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 `z.infer`'d `SendSmsInput`
+ * field-for-field — unlike `SendEmailInput`, there's no ergonomic wire
+ * conversion needed here, so this is asserted equal (not
+ * `DELIBERATELY_DIFFERENT`) in `apps/api/src/sdk-dto-contract.test.ts`.
+ * Provide exactly one of `body` or `templateName` — the server 400s
+ * otherwise; that XOR is a runtime `.refine()`, not expressible in the type.
+ */
+interface SendSmsInput {
+    to: string;
+    from?: string;
+    body?: string;
+    templateName?: string;
+    variables?: Record<string, string>;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Mirrors `apps/api/src/domains/sms/types.ts`'s server-side copy of this
+ * shape field-for-field. Not imported from there: this package is published
+ * to npm for external consumers and can't depend on the private api app.
+ * Keep both copies in sync by hand when the wire shape changes; same for
+ * `SmsListResponse` below.
+ */
+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;
+}
+
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly maxRetries;
     constructor(config: DevelEmailConfig);
-    send(input: SendEmailInput): Promise<EmailResponse>;
-    get(id: string): Promise<EmailResponse>;
+    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): Promise<SmsMessageResponse>;
+    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>;
+
 declare class DevelEmail {
-    readonly emails: EmailsNamespace;
+    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 { DevelEmail, type DevelEmailConfig, DevelEmailError, type EmailResponse, type SendEmailInput };
+export { type AttachmentInput, type BatchEmailResponse, type BatchEmailResultItem, 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 };