@develemail/sdk 0.4.0 → 0.4.1

package/dist/index.d.ts

@@ -3,46 +3,31 @@ interface DevelEmailConfig {
     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.
- */
+
+/** 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()`.
- * `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.
- */
+/** Ergonomic attachment input for `emails.send()` / `emails.batch()`. */
 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.
+ * 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;
@@ -54,17 +39,15 @@ interface SendEmailInput {
     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 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.
- */
+/** Mirrors `apps/api/src/domains/emails/types.ts`'s server-side copy. */
 interface EmailResponse {
     id: string;
     status: string;
@@ -76,6 +59,7 @@ interface BatchEmailResultItem {
     status?: string;
     duplicate?: boolean;
     error?: string;
+    code?: string;
 }
 interface BatchEmailResponse {
     results: BatchEmailResultItem[];
@@ -83,6 +67,20 @@ interface BatchEmailResponse {
     errors: number;
     limitReached?: boolean;
 }
+/** 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;
@@ -100,6 +98,11 @@ interface Domain {
     createdAt: string;
     updatedAt: string;
 }
+interface DomainCreateInput {
+    name: string;
+    dkimSelector?: string;
+}
+
 interface Template {
     id: string;
     organizationId: string;
@@ -111,10 +114,6 @@ interface Template {
     createdAt: string;
     updatedAt: string;
 }
-interface DomainCreateInput {
-    name: string;
-    dkimSelector?: string;
-}
 interface TemplateCreateInput {
     name: string;
     subject: string;
@@ -129,39 +128,8 @@ interface TemplateUpdateInput {
     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.
- */
+
+/** Mirrors `apps/api/src/domains/webhooks/types.ts`'s `WebhookPayload`. */
 interface WebhookEvent {
     event: string;
     emailId: string | null;
@@ -170,6 +138,7 @@ interface WebhookEvent {
     timestamp: string;
     metadata: Record<string, unknown>;
 }
+
 type CampaignStatus = 'draft' | 'scheduled' | 'sending' | 'paused' | 'sent' | 'cancelled';
 interface Campaign {
     id: string;
@@ -194,20 +163,13 @@ interface Campaign {
         opened?: number;
         clicked?: number;
         bounced?: number;
+        configurationBounced?: 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.
- */
+/** The SDK accepts optional pagination before the API applies defaults. */
 interface CampaignListQuery {
     projectId: string;
     status?: CampaignStatus;
@@ -241,11 +203,7 @@ interface CampaignUpdateInput {
     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.
- */
+/** Mirrors `apps/api/src/domains/campaigns/types.ts`'s server-side copy. */
 interface CampaignStats {
     campaignId: string;
     totalRecipients: number;
@@ -253,7 +211,9 @@ interface CampaignStats {
     deliveryUnknown: number;
     opened: number;
     clicked: number;
+    /** Reputation bounces only; configuration bounces are in `configurationBounced`. */
     bounced: number;
+    configurationBounced: number;
     unsubscribed: number;
     openRate: number;
     clickRate: number;
@@ -269,44 +229,7 @@ interface CampaignProviderStats {
     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;
@@ -319,15 +242,7 @@ interface Contact {
     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.
- */
+/** The SDK preserves optional filters before API parsing/defaulting. */
 interface ContactListQuery {
     projectId: string;
     search?: string;
@@ -366,36 +281,49 @@ interface ContactBulkResponse {
     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.
- */
+/** `addedAt` is serialized to string for SDK consumers. */
 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.
- */
+
+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 `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.
- */
+/** Mirrors `apps/api/src/domains/sms/types.ts`'s `SendSmsInput`. */
 interface SendSmsInput {
     to: string;
     from?: string;
@@ -405,13 +333,6 @@ interface SendSmsInput {
     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;
@@ -432,6 +353,18 @@ interface SmsListQuery {
     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;
@@ -529,7 +462,8 @@ declare class Lists {
 declare class Sms {
     private readonly http;
     constructor(http: HttpClient);
-    send(input: SendSmsInput): Promise<SmsMessageResponse>;
+    send(input: SendSmsInput, options?: SendOptions): Promise<SmsMessageResponse>;
+    sendBatch(messages: SendSmsInput[], options?: SendOptions): Promise<BatchSmsResponse>;
     get(id: string): Promise<SmsMessageResponse>;
     list(query?: SmsListQuery): Promise<SmsListResponse>;
 }
@@ -554,4 +488,4 @@ declare class DevelEmail {
     constructor(config: DevelEmailConfig);
 }
 
-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 };
+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 };

package/dist/index.js

@@ -16,19 +16,31 @@ var DevelEmailError = class extends Error {
 var DEFAULT_MAX_RETRIES = 3;
 var BASE_DELAY_MS = 500;
 var MAX_DELAY_MS = 3e4;
+var MAX_RETRY_AFTER_MS = 1e4;
+var CONFLICT_RETRY_DELAY_MS = 1e3;
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function isRetryable(status) {
   return status >= 500 || status === 429;
 }
+function isIdempotencyConflict(status, code) {
+  return status === 409 && code === "idempotency_conflict";
+}
+function parseRetryAfterMs(header) {
+  if (!header) return null;
+  const seconds = Number(header);
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(seconds * 1e3, MAX_RETRY_AFTER_MS);
+}
 function parseErrorBody(body) {
   if (typeof body === "object" && body !== null) {
     const b = body;
     const { message, error, statusCode, ...rest } = b;
+    const code = typeof b.code === "string" ? b.code : typeof error === "string" ? error : void 0;
     return {
       message: typeof message === "string" ? message : "Unknown error",
-      code: typeof error === "string" ? error : void 0,
+      code,
       details: Object.keys(rest).length > 0 ? rest : void 0
     };
   }
@@ -71,6 +83,7 @@ var HttpClient = class {
       body: body !== void 0 ? JSON.stringify(body) : void 0
     };
     let lastError;
+    let retriedConflict = false;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       let res;
       try {
@@ -93,9 +106,11 @@ var HttpClient = class {
       }
       const errorBody = await res.json().catch(() => ({}));
       const parsed = parseErrorBody(errorBody);
-      if (isRetryable(res.status) && attempt < this.maxRetries) {
-        const retryAfter = res.headers.get("Retry-After");
-        const delay = retryAfter ? parseInt(retryAfter, 10) * 1e3 : this.backoff(attempt);
+      const conflictRetry = isIdempotencyConflict(res.status, parsed.code) && !retriedConflict;
+      if ((isRetryable(res.status) || conflictRetry) && attempt < this.maxRetries) {
+        if (conflictRetry) retriedConflict = true;
+        const retryAfterMs = parseRetryAfterMs(res.headers.get("Retry-After"));
+        const delay = retryAfterMs ?? (conflictRetry ? CONFLICT_RETRY_DELAY_MS : this.backoff(attempt));
         await sleep(delay);
         lastError = new DevelEmailError(
           res.status,
@@ -128,7 +143,13 @@ var HttpClient = class {
 
 // ../core/src/reserved-domains.ts
 var RESERVED_DOMAINS = ["example.com", "example.net", "example.org"];
-var RESERVED_TLDS = ["test", "example", "invalid", "localhost"];
+var RESERVED_TLDS = [
+  "test",
+  "example",
+  "invalid",
+  "localhost",
+  "local"
+];
 function isReservedDomain(domain) {
   const normalized = domain.trim().toLowerCase().replace(/\.$/, "");
   if (!normalized) return false;
@@ -194,7 +215,8 @@ var Emails = class {
       if (reserved) {
         rejections.set(index, {
           index,
-          error: reservedRecipientError(reserved).message
+          error: reservedRecipientError(reserved).message,
+          code: "reserved_recipient_domain"
         });
       }
     });
@@ -484,8 +506,19 @@ var Sms = class {
     this.http = http;
   }
   http;
-  async send(input) {
-    return this.http.post("/v1/sms", input);
+  async send(input, options) {
+    const key = options?.idempotencyKey ?? crypto.randomUUID();
+    return this.http.post("/v1/sms", input, {
+      "Idempotency-Key": key
+    });
+  }
+  async sendBatch(messages, options) {
+    const key = options?.idempotencyKey ?? crypto.randomUUID();
+    return this.http.post(
+      "/v1/sms/batch",
+      { messages },
+      { "Idempotency-Key": key }
+    );
   }
   async get(id) {
     return this.http.get(
@@ -523,7 +556,7 @@ async function verifyWebhookSignature(payload, signature, secret) {
   return diff === 0;
 }
 
-// src/types.ts
+// src/types/emails.ts
 var EMAIL_STATUSES = [
   "queued",
   "rendering",
@@ -537,7 +570,8 @@ var EMAIL_STATUSES = [
   "suppressed",
   "cancelled",
   "scheduled",
-  "quarantined"
+  "quarantined",
+  "sandboxed"
 ];
 var EMAIL_EVENT_TYPES = [
   "queued",
@@ -557,6 +591,8 @@ var EMAIL_EVENT_TYPES = [
   "click",
   "quarantined"
 ];
+
+// src/types/sms.ts
 var SMS_STATUSES = [
   "queued",
   "sending",