mailerbot 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,737 @@
+interface RequestOptions {
+    method?: string;
+    path: string;
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+    headers?: Record<string, string>;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeout;
+    constructor(baseUrl: string, headers: Record<string, string>, timeout: number);
+    request<T>(options: RequestOptions): Promise<T>;
+    requestRaw(options: RequestOptions & {
+        rawBody?: FormData | string;
+        rawHeaders?: Record<string, string>;
+    }): Promise<Response>;
+}
+
+interface Page<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    pages: number;
+}
+
+interface Contact {
+    id: string;
+    firstName: string;
+    lastName: string;
+    company?: string | null;
+    addressLine1: string;
+    addressLine2?: string | null;
+    city: string;
+    state: string;
+    zip: string;
+    countryCode: string;
+    countryName: string;
+    email?: string | null;
+    phone?: string | null;
+    validationStatus?: string | null;
+    correctedAddress?: Record<string, unknown> | null;
+}
+interface ContactList {
+    id: string;
+    name: string;
+    contactIds: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface AddressValidation {
+    contactId: string;
+    name: string;
+    status: string;
+    original: string;
+    corrected?: string | null;
+}
+interface CsvImportResult {
+    importedCount: number;
+    listId?: string | null;
+}
+interface CreateContactParams {
+    firstName: string;
+    lastName: string;
+    addressLine1: string;
+    city: string;
+    state: string;
+    zip: string;
+    countryCode?: string;
+    company?: string;
+    addressLine2?: string;
+    email?: string;
+    phone?: string;
+}
+interface UpdateContactParams {
+    firstName?: string;
+    lastName?: string;
+    addressLine1?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    countryCode?: string;
+    company?: string;
+    addressLine2?: string;
+    email?: string;
+    phone?: string;
+}
+
+/**
+ * Async auto-paginating iterator. Yields individual items across all pages.
+ *
+ * @example
+ * ```ts
+ * for await (const contact of client.contacts.iterAll()) {
+ *   console.log(contact.firstName);
+ * }
+ * ```
+ */
+declare class PageIterator<T> implements AsyncIterable<T> {
+    private readonly fetch;
+    private readonly pageSize;
+    constructor(fetch: (page: number, pageSize: number) => Promise<Page<T>>, pageSize?: number);
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+
+declare class ContactsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+        search?: string;
+    }): Promise<Page<Contact>>;
+    iterAll(options?: {
+        pageSize?: number;
+        search?: string;
+    }): PageIterator<Contact>;
+    get(contactId: string): Promise<Contact>;
+    create(params: CreateContactParams): Promise<Contact>;
+    update(contactId: string, params: UpdateContactParams): Promise<Contact>;
+    delete(contactId: string): Promise<void>;
+    importCsv(contacts: Record<string, unknown>[], options?: {
+        listName?: string;
+    }): Promise<CsvImportResult>;
+    validateAddresses(contactIds: string[]): Promise<AddressValidation[]>;
+}
+
+declare class ContactListsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<ContactList[]>;
+    get(listId: string): Promise<ContactList>;
+    create(name: string, options?: {
+        contactIds?: string[];
+    }): Promise<ContactList>;
+    update(listId: string, name: string): Promise<ContactList>;
+    delete(listId: string): Promise<void>;
+    addContacts(listId: string, contactIds: string[]): Promise<void>;
+    removeContacts(listId: string, contactIds: string[]): Promise<void>;
+}
+
+interface Document {
+    id: string;
+    title: string;
+    content?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    type: string;
+    pdfUrl?: string | null;
+    thumbnailUrl?: string | null;
+    pageCount?: number | null;
+    fileSize?: number | null;
+}
+interface CreateDocumentParams {
+    title?: string;
+    content?: string;
+}
+interface UpdateDocumentParams {
+    title?: string;
+    content?: string;
+}
+
+declare class DocumentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+        type?: string;
+    }): Promise<Page<Document>>;
+    iterAll(options?: {
+        pageSize?: number;
+    }): PageIterator<Document>;
+    get(documentId: string): Promise<Document>;
+    create(params?: CreateDocumentParams): Promise<Document>;
+    update(documentId: string, params: UpdateDocumentParams): Promise<Document>;
+    delete(documentId: string): Promise<void>;
+    upload(file: Blob | ArrayBuffer | Uint8Array<ArrayBuffer>, filename: string): Promise<Document>;
+}
+
+interface PostcardSide {
+    elements: Record<string, unknown>[];
+    backgroundColor: string;
+    backgroundImage?: string | null;
+    backgroundImageOpacity?: number | null;
+}
+interface Postcard {
+    id: string;
+    title: string;
+    front?: PostcardSide | null;
+    back?: PostcardSide | null;
+    width: number;
+    height: number;
+    createdAt: string;
+    updatedAt: string;
+    templateId?: string | null;
+}
+interface PostcardTemplate {
+    id: string;
+    name: string;
+    description?: string | null;
+    category: string;
+    thumbnailUrl?: string | null;
+    front?: PostcardSide | null;
+    back?: PostcardSide | null;
+}
+interface CreatePostcardParams {
+    title?: string;
+    front?: Record<string, unknown>;
+    back?: Record<string, unknown>;
+}
+interface UpdatePostcardParams {
+    title?: string;
+    front?: Record<string, unknown>;
+    back?: Record<string, unknown>;
+}
+
+declare class PostcardsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    listTemplates(): Promise<PostcardTemplate[]>;
+    getTemplate(templateId: string): Promise<PostcardTemplate>;
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<Page<Postcard>>;
+    iterAll(options?: {
+        pageSize?: number;
+    }): PageIterator<Postcard>;
+    get(postcardId: string): Promise<Postcard>;
+    create(params?: CreatePostcardParams): Promise<Postcard>;
+    update(postcardId: string, params: UpdatePostcardParams): Promise<Postcard>;
+    delete(postcardId: string): Promise<void>;
+}
+
+interface MailingPostage {
+    postageZoneId: string;
+    postageZoneName: string;
+    postageZoneSlug: string;
+    postageRateId: string;
+    postageRateLabel: string;
+    postageRateSlug: string;
+    recipientCount: number;
+    costPerPiece: number;
+    subtotal: number;
+}
+interface Mailing {
+    id: string;
+    name: string;
+    type: string;
+    productTypeId?: string | null;
+    documentId?: string | null;
+    postcardId?: string | null;
+    contactListId: string;
+    couponListId?: string | null;
+    status: string;
+    recipientCount: number;
+    createdAt: string;
+    scheduledDate?: string | null;
+    printColor: boolean;
+    productCostPerPiece: number;
+    totalCost: number;
+    taxAmount: number;
+    taxRate: number;
+    paymentStatus: string;
+    stripePaymentIntentId?: string | null;
+    isTest: boolean;
+    postage: MailingPostage[];
+    itemCount: number;
+    itemsMailed: number;
+    itemsDelivered: number;
+    itemsReturned: number;
+    deliveredAt?: string | null;
+}
+type MailingItemTrackingStatus = "in_transit" | "out_for_delivery" | "forwarded" | "delivered" | "returned";
+interface MailingItemTracking {
+    id: string;
+    mailingId: string;
+    contactId?: string | null;
+    recipientName?: string | null;
+    recipientCompany?: string | null;
+    recipientCity?: string | null;
+    recipientState?: string | null;
+    recipientZip?: string | null;
+    status: "pending" | "printed" | "mailed";
+    trackingStatus: MailingItemTrackingStatus | null;
+    printedAt?: string | null;
+    mailedAt?: string | null;
+    firstScanAt?: string | null;
+    lastScanAt?: string | null;
+    lastScanEventCode?: string | null;
+    lastScanLabel?: string | null;
+    lastScanLocation?: string | null;
+    anticipatedDeliveryDate?: string | null;
+    expectedDeliveryDate?: string | null;
+    deliveredAt?: string | null;
+    returnedAt?: string | null;
+    /** True when delivered was inferred from the final USPS sort plus the predicted delivery day. */
+    deliveryInferred: boolean;
+    deliveryDate: string | null;
+}
+interface MailingItemScan {
+    id: string;
+    scanDatetime: string;
+    scanEventCode: string;
+    handlingEventType: "A" | "AA" | "L" | "AL";
+    label: string;
+    facilityName?: string | null;
+    facilityCity?: string | null;
+    facilityState?: string | null;
+    facilityZip?: string | null;
+    mailPhase?: string | null;
+    imb: string;
+}
+interface ListMailingItemsOptions {
+    page?: number;
+    pageSize?: number;
+    /** Filter by tracking state; "none" selects pieces not yet scanned. */
+    trackingStatus?: MailingItemTrackingStatus | "none";
+}
+interface ZoneRecipientCount {
+    postageZoneId: string;
+    postageZoneName: string;
+    postageZoneSlug: string;
+    recipientCount: number;
+}
+interface UnavailableRecipients {
+    countryName: string;
+    recipientCount: number;
+    reason: string;
+}
+interface CostCalculation {
+    type: string;
+    productTypeCode: string;
+    recipientCount: number;
+    productCostPerPiece: number;
+    totalProductCost: number;
+    zoneCounts: ZoneRecipientCount[];
+    unavailable: UnavailableRecipients[];
+    totalCost?: number | null;
+    pageCount?: number | null;
+    printColor: boolean;
+    basePrice?: number | null;
+    perPagePrice?: number | null;
+    colorSurchargePerPage?: number | null;
+}
+interface PostageSelection {
+    postageZoneSlug: string;
+    postageRateSlug: string;
+}
+interface CreateMailingParams {
+    name: string;
+    type: string;
+    contactListId: string;
+    documentId?: string;
+    postcardId?: string;
+    couponListId?: string;
+    scheduledDate?: string | Date;
+    printColor?: boolean;
+    postageSelections?: PostageSelection[];
+}
+interface UpdateMailingParams {
+    name?: string;
+    scheduledDate?: string | Date;
+}
+interface EstimateCostParams {
+    type: string;
+    contactListId?: string;
+    contactIds?: string[];
+    documentId?: string;
+    printColor?: boolean;
+}
+
+declare class MailingsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<Page<Mailing>>;
+    iterAll(options?: {
+        pageSize?: number;
+    }): PageIterator<Mailing>;
+    get(mailingId: string): Promise<Mailing>;
+    create(params: CreateMailingParams): Promise<Mailing>;
+    update(mailingId: string, params: UpdateMailingParams): Promise<Mailing>;
+    delete(mailingId: string): Promise<void>;
+    validateAddresses(mailingId: string): Promise<Record<string, unknown>[]>;
+    estimateCost(params: EstimateCostParams): Promise<CostCalculation>;
+    calculateCost(mailingId: string): Promise<CostCalculation>;
+    send(mailingId: string): Promise<Mailing>;
+    listItems(mailingId: string, options?: ListMailingItemsOptions): Promise<Page<MailingItemTracking>>;
+    iterItems(mailingId: string, options?: Omit<ListMailingItemsOptions, "page">): PageIterator<MailingItemTracking>;
+    listItemScans(mailingId: string, itemId: string): Promise<MailingItemScan[]>;
+}
+
+interface Campaign {
+    id: string;
+    name: string;
+    mailingIds: string[];
+    status: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+declare class CampaignsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<Page<Campaign>>;
+    iterAll(options?: {
+        pageSize?: number;
+    }): PageIterator<Campaign>;
+    get(campaignId: string): Promise<Campaign>;
+    create(name: string, options?: {
+        mailingIds?: string[];
+    }): Promise<Campaign>;
+    update(campaignId: string, params: {
+        name?: string;
+        status?: string;
+    }): Promise<Campaign>;
+    delete(campaignId: string): Promise<void>;
+    addMailing(campaignId: string, mailingId: string): Promise<Campaign>;
+    removeMailing(campaignId: string, mailingId: string): Promise<Campaign>;
+}
+
+interface DashboardStats {
+    totalDocuments: number;
+    totalMailings: number;
+    lettersSent: number;
+    postcardsSent: number;
+    totalContacts: number;
+    totalSpent: number;
+    totalQrScans: number;
+}
+interface StateCount {
+    state: string;
+    count: number;
+}
+interface ReportingData {
+    totalPieces: number;
+    totalSpent: number;
+    lettersCount: number;
+    postcardsCount: number;
+    destinationsByState: StateCount[];
+}
+
+declare class DashboardResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    stats(): Promise<DashboardStats>;
+    reporting(options?: {
+        startDate?: string;
+        endDate?: string;
+    }): Promise<ReportingData>;
+}
+
+interface PaymentIntent {
+    clientSecret: string;
+    paymentIntentId: string;
+    amount: number;
+    subtotal: number;
+    taxAmount: number;
+    taxRate: number;
+    currency: string;
+}
+interface SavedCard {
+    id: string;
+    brand: string;
+    last4: string;
+    expMonth: number;
+    expYear: number;
+}
+
+declare class PaymentsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    createPaymentIntent(mailingId: string, options?: {
+        paymentMethodId?: string;
+    }): Promise<PaymentIntent>;
+    getStripeKey(): Promise<string>;
+    listCards(): Promise<SavedCard[]>;
+    deleteCard(paymentMethodId: string): Promise<void>;
+}
+
+interface QrLink {
+    id: string;
+    slug: string;
+    destinationUrl: string;
+    postcardId?: string | null;
+    mailingId?: string | null;
+    recipientId?: string | null;
+    qrElementId?: string | null;
+    scanCount: number;
+    createdAt: string;
+    updatedAt: string;
+    shortUrl: string;
+}
+interface ScansByDay {
+    date: string;
+    count: number;
+}
+interface TopLink {
+    slug: string;
+    destinationUrl: string;
+    scanCount: number;
+    shortUrl: string;
+}
+interface QrAnalytics {
+    totalScans: number;
+    uniqueLinks: number;
+    scansByDay: ScansByDay[];
+    topLinks: TopLink[];
+    recentScans: Record<string, unknown>[];
+}
+interface CreateQrLinkParams {
+    destinationUrl: string;
+    postcardId?: string;
+    mailingId?: string;
+    recipientId?: string;
+    qrElementId?: string;
+}
+
+declare class QrResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<Page<QrLink>>;
+    iterAll(options?: {
+        pageSize?: number;
+    }): PageIterator<QrLink>;
+    create(params: CreateQrLinkParams): Promise<QrLink>;
+    delete(linkId: string): Promise<void>;
+    analytics(options?: {
+        days?: number;
+    }): Promise<QrAnalytics>;
+}
+
+interface MergeTag {
+    key: string;
+    label: string;
+    category: string;
+    sampleValue: string;
+}
+
+declare class MergeTagsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<MergeTag[]>;
+}
+
+declare class PricingResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    catalog(): Promise<Record<string, unknown>[]>;
+    countries(): Promise<Record<string, unknown>[]>;
+    postageZones(): Promise<Record<string, unknown>[]>;
+    postageRates(options?: {
+        productType?: string;
+        zone?: string;
+    }): Promise<Record<string, unknown>[]>;
+}
+
+interface CouponList {
+    id: string;
+    name: string;
+    description?: string | null;
+    totalCodes: number;
+    usedCodes: number;
+    availableCodes: number;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CouponCode {
+    id: string;
+    code: string;
+    used: boolean;
+    usedAt?: string | null;
+    assignedToContactId?: string | null;
+    mailingId?: string | null;
+    createdAt: string;
+}
+interface CouponImportResult {
+    importedCount: number;
+    duplicateCount: number;
+}
+interface CouponAvailability {
+    couponListId: string;
+    totalCodes: number;
+    usedCodes: number;
+    availableCodes: number;
+    sufficient: boolean;
+    requestedCount: number;
+}
+
+declare class CouponsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(): Promise<CouponList[]>;
+    get(listId: string): Promise<CouponList>;
+    create(name: string, options?: {
+        description?: string;
+    }): Promise<CouponList>;
+    update(listId: string, params: {
+        name?: string;
+        description?: string;
+    }): Promise<CouponList>;
+    delete(listId: string): Promise<void>;
+    listCodes(listId: string, options?: {
+        page?: number;
+        pageSize?: number;
+        used?: boolean;
+    }): Promise<Page<CouponCode>>;
+    importCodes(listId: string, codes: string[]): Promise<CouponImportResult>;
+    deleteCode(listId: string, codeId: string): Promise<void>;
+    checkAvailability(listId: string, count: number): Promise<CouponAvailability>;
+}
+
+interface Asset {
+    id: string;
+    filename: string;
+    originalFilename: string;
+    url: string;
+    mimeType: string;
+    fileSize: number;
+    createdAt: string;
+}
+
+declare class AssetsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(options?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<Page<Asset>>;
+    iterAll(options?: {
+        pageSize?: number;
+    }): PageIterator<Asset>;
+    upload(file: Blob | ArrayBuffer | Uint8Array<ArrayBuffer>, filename: string, mimeType?: string): Promise<Asset>;
+    delete(assetId: string): Promise<void>;
+}
+
+interface MailerBotOptions {
+    /** Base URL for the API. Defaults to `https://api.mailerbot.com/api/v1`. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000. */
+    timeout?: number;
+}
+/**
+ * MailerBot API client.
+ *
+ * @example
+ * ```ts
+ * import { MailerBot } from "mailerbot";
+ *
+ * const client = new MailerBot("mb_live_...");
+ * const page = await client.contacts.list();
+ * console.log(page.total, "contacts");
+ * ```
+ */
+declare class MailerBot {
+    readonly contacts: ContactsResource;
+    readonly contactLists: ContactListsResource;
+    readonly documents: DocumentsResource;
+    readonly postcards: PostcardsResource;
+    readonly mailings: MailingsResource;
+    readonly campaigns: CampaignsResource;
+    readonly dashboard: DashboardResource;
+    readonly payments: PaymentsResource;
+    readonly qr: QrResource;
+    readonly mergeTags: MergeTagsResource;
+    readonly pricing: PricingResource;
+    readonly coupons: CouponsResource;
+    readonly assets: AssetsResource;
+    constructor(apiKey: string, options?: MailerBotOptions);
+}
+
+/**
+ * Base error class for all MailerBot SDK errors.
+ */
+declare class MailerBotError extends Error {
+    readonly statusCode: number | undefined;
+    readonly response: Record<string, unknown> | undefined;
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: Record<string, unknown>;
+    });
+}
+/** Raised when the API key is missing or invalid (401). */
+declare class AuthenticationError extends MailerBotError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: Record<string, unknown>;
+    });
+}
+/** Raised when the API key lacks permission for the requested resource (403). */
+declare class PermissionError extends MailerBotError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: Record<string, unknown>;
+    });
+}
+/** Raised when the requested resource does not exist (404). */
+declare class NotFoundError extends MailerBotError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: Record<string, unknown>;
+    });
+}
+/** Raised when the request body fails validation (422). */
+declare class ValidationError extends MailerBotError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: Record<string, unknown>;
+    });
+}
+/** Raised when the rate limit is exceeded (429). */
+declare class RateLimitError extends MailerBotError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: Record<string, unknown>;
+    });
+}
+/** Raised for unexpected server-side errors (5xx). */
+declare class ServerError extends MailerBotError {
+    constructor(message: string, options?: {
+        statusCode?: number;
+        response?: Record<string, unknown>;
+    });
+}
+
+export { type AddressValidation, type Asset, AuthenticationError, type Campaign, type Contact, type ContactList, type CostCalculation, type CouponAvailability, type CouponCode, type CouponImportResult, type CouponList, type CreateContactParams, type CreateDocumentParams, type CreateMailingParams, type CreatePostcardParams, type CreateQrLinkParams, type CsvImportResult, type DashboardStats, type Document, type ListMailingItemsOptions, MailerBot, MailerBotError, type MailerBotOptions, type Mailing, type MailingItemScan, type MailingItemTracking, type MailingItemTrackingStatus, type MergeTag, NotFoundError, type Page, PageIterator, type PaymentIntent, PermissionError, type Postcard, type PostcardSide, type PostcardTemplate, type QrAnalytics, type QrLink, RateLimitError, type ReportingData, type SavedCard, type ScansByDay, ServerError, type StateCount, type TopLink, type UpdateContactParams, type UpdateDocumentParams, type UpdateMailingParams, type UpdatePostcardParams, ValidationError };