@topmail/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,640 @@
+interface ClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    maxRetries?: number;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly maxRetries;
+    constructor(options: ClientOptions);
+    get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, body?: unknown): Promise<T>;
+    private buildUrl;
+    private request;
+    private createError;
+    private getRetryDelay;
+    private parseRetryAfter;
+    private sleep;
+}
+
+interface PaginationParams {
+    limit?: number;
+    offset?: number;
+}
+interface Pagination {
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+interface ListResponse<T> {
+    data: T[];
+    pagination: Pagination;
+}
+interface SingleResponse<T> {
+    data: T;
+}
+interface ErrorResponse {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+interface Contact {
+    id: string;
+    email: string;
+    first_name: string | null;
+    last_name: string | null;
+    attributes: Record<string, unknown> | null;
+    subscribed: boolean;
+    engagement_score: number | null;
+    churn_risk_score: number | null;
+    revenue_potential_score: number | null;
+    created_at: string;
+    updated_at: string;
+}
+interface ContactListParams extends PaginationParams {
+    search?: string;
+    subscribed?: boolean;
+}
+interface ContactCreateParams {
+    email: string;
+    first_name?: string;
+    last_name?: string;
+    attributes?: Record<string, unknown>;
+    subscribed?: boolean;
+    list_id?: string;
+}
+interface ContactUpdateParams {
+    email?: string;
+    first_name?: string;
+    last_name?: string;
+    attributes?: Record<string, unknown>;
+    subscribed?: boolean;
+}
+interface ContactList {
+    id: string;
+    name: string;
+    description: string | null;
+    type: 'static' | 'dynamic';
+    conditions: unknown | null;
+    member_count: number;
+    created_at: string;
+    updated_at: string;
+}
+interface ListCreateParams {
+    name: string;
+    description?: string;
+    type?: 'static' | 'dynamic';
+    conditions?: unknown;
+}
+interface ListUpdateParams {
+    name?: string;
+    description?: string;
+    type?: 'static' | 'dynamic';
+    conditions?: unknown;
+}
+interface ListMember {
+    id: string;
+    contact_id: string;
+    email: string;
+    first_name: string | null;
+    last_name: string | null;
+    added_at: string;
+}
+interface ListMembersParams extends PaginationParams {
+}
+type CampaignStatus = 'draft' | 'scheduled' | 'sending' | 'sent' | 'paused';
+interface Campaign {
+    id: string;
+    name: string;
+    subject: string | null;
+    status: CampaignStatus;
+    sent_count: number | null;
+    open_count: number | null;
+    click_count: number | null;
+    created_at: string;
+    updated_at: string;
+}
+interface CampaignListParams extends PaginationParams {
+    status?: CampaignStatus;
+}
+interface Template {
+    id: string;
+    name: string;
+    subject: string | null;
+    html: string | null;
+    text: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface TemplateListParams extends PaginationParams {
+    search?: string;
+}
+interface TemplateCreateParams {
+    name: string;
+    html: string;
+    description?: string;
+}
+interface EmailSendParams {
+    to: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    template_id?: string;
+    template_data?: Record<string, unknown>;
+    from_email?: string;
+    from_name?: string;
+    reply_to?: string;
+    track_opens?: boolean;
+    track_clicks?: boolean;
+    send_at?: string;
+}
+interface EmailSendResponse {
+    id: string;
+    status: string;
+}
+interface EmailBatchParams {
+    messages: EmailSendParams[];
+    from_email?: string;
+    from_name?: string;
+}
+interface EmailBatchResponse {
+    batch_id: string;
+    total: number;
+    status: string;
+}
+interface EmailBatchStatus {
+    batch_id: string;
+    total: number;
+    sent: number;
+    failed: number;
+    status: string;
+}
+interface EmailMessageStatus {
+    id: string;
+    status: string;
+    to: string;
+    subject: string;
+    sent_at: string | null;
+    opened_at: string | null;
+    clicked_at: string | null;
+}
+type SuppressionType = 'bounce' | 'complaint' | 'manual' | 'unsubscribe';
+interface Suppression {
+    id: string;
+    email: string;
+    type: SuppressionType;
+    reason: string | null;
+    created_at: string;
+}
+interface SuppressionListParams extends PaginationParams {
+    type?: SuppressionType;
+}
+interface SuppressionAddParams {
+    email: string;
+    type?: SuppressionType;
+    reason?: string;
+}
+interface Webhook {
+    id: string;
+    targetUrl: string;
+    event: string;
+    createdAt: string;
+}
+interface WebhookSubscribeParams {
+    targetUrl: string;
+    event: string;
+}
+interface WebhookTestResponse {
+    success: boolean;
+    status_code: number;
+}
+interface ProductViewParams {
+    email?: string;
+    contact_id?: string;
+    product_id: string;
+    product_name?: string;
+    product_url?: string;
+    product_image_url?: string;
+    product_price?: number;
+    product_currency?: string;
+    category?: string;
+}
+interface ProductViewResponse {
+    success: boolean;
+}
+interface Conversion {
+    id: string;
+    email: string | null;
+    contact_id: string | null;
+    type: string | null;
+    revenue: number | null;
+    currency: string | null;
+    order_id: string | null;
+    campaign_id: string | null;
+    flow_id: string | null;
+    attribution_model: string | null;
+    attribution_window: string | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+interface ConversionCreateParams {
+    email?: string;
+    contact_id?: string;
+    type?: string;
+    revenue?: number;
+    currency?: string;
+    order_id?: string;
+    campaign_id?: string;
+    flow_id?: string;
+    attribution_model?: string;
+    attribution_window?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ConversionListParams extends PaginationParams {
+}
+interface Segment {
+    id: string;
+    name: string;
+    conditions: SegmentCondition[] | SegmentConditions | null;
+    created_at: string;
+    updated_at: string;
+}
+interface SegmentCondition {
+    field: string;
+    operator: string;
+    value?: string | number | boolean;
+}
+interface SegmentConditionGroup {
+    logic: 'and' | 'or';
+    conditions: SegmentCondition[];
+}
+interface SegmentConditions {
+    logic: 'and' | 'or';
+    groups: SegmentConditionGroup[];
+}
+interface SegmentListParams extends PaginationParams {
+    search?: string;
+}
+interface SegmentCreateParams {
+    name: string;
+    description?: string;
+    conditions?: SegmentCondition[] | SegmentConditions;
+}
+interface SegmentUpdateParams {
+    name?: string;
+    conditions?: SegmentCondition[] | SegmentConditions;
+}
+interface SegmentEstimate {
+    estimated_count: number;
+}
+interface Tag {
+    id: string;
+    name: string;
+    color: string;
+    description: string | null;
+    contact_count: number;
+    created_at: string;
+    updated_at: string;
+}
+interface TagListParams extends PaginationParams {
+    search?: string;
+}
+interface TagCreateParams {
+    name: string;
+    color?: string;
+    description?: string;
+}
+interface TagUpdateParams {
+    name?: string;
+    color?: string;
+    description?: string;
+}
+interface TagAssignResult {
+    assigned: number;
+    already_assigned?: number;
+    invalid_ids?: string[];
+}
+interface TagRemoveResult {
+    removed: number;
+}
+type AutomationStatus = 'draft' | 'active' | 'paused';
+type AutomationRunStatus = 'active' | 'completed' | 'failed' | 'paused' | 'cancelled';
+interface Automation {
+    id: string;
+    name: string;
+    trigger_type: string;
+    status: AutomationStatus;
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+interface AutomationStep {
+    id: string;
+    step_type: string;
+    config: Record<string, unknown>;
+    position: number;
+    created_at: string;
+}
+interface AutomationWithSteps extends Automation {
+    trigger_config: Record<string, unknown>;
+    steps: AutomationStep[];
+    run_count: number;
+}
+type AutomationStepType = 'email' | 'sms' | 'push' | 'delay' | 'condition' | 'action' | 'tag' | 'trigger_split' | 'add_to_list' | 'remove_from_list' | 'update_attribute' | 'webhook' | 'wait_for_event' | 'move_to_flow';
+interface AutomationListParams extends PaginationParams {
+    status?: AutomationStatus;
+}
+interface AutomationCreateParams {
+    name: string;
+    trigger_type: string;
+    trigger_config?: Record<string, unknown>;
+    steps?: Array<{
+        step_type: AutomationStepType;
+        config?: Record<string, unknown>;
+        position?: number;
+    }>;
+}
+interface AutomationUpdateParams {
+    name?: string;
+    status?: AutomationStatus;
+}
+interface AutomationAddStepParams {
+    step_type: AutomationStepType;
+    config?: Record<string, unknown>;
+    position?: number;
+}
+interface AutomationUpdateStepParams {
+    step_type?: AutomationStepType;
+    config?: Record<string, unknown>;
+}
+interface AutomationBatchUpdateStepsParams {
+    steps: Array<{
+        id: string;
+        position?: number;
+        config?: Record<string, unknown>;
+    }>;
+}
+interface AutomationTriggerParams {
+    contact_id?: string;
+    email?: string;
+    trigger_data?: Record<string, unknown>;
+}
+interface AutomationTriggerResult {
+    success: boolean;
+    flow_run_id?: string;
+    error?: string;
+}
+interface AutomationRun {
+    id: string;
+    contact_id: string;
+    contact_email: string;
+    status: AutomationRunStatus;
+    trigger_data: Record<string, unknown>;
+    current_step_position: number;
+    started_at: string;
+    completed_at: string | null;
+    created_at: string;
+}
+interface AutomationRunListParams extends PaginationParams {
+    status?: AutomationRunStatus;
+}
+interface Domain {
+    id: string;
+    domain: string;
+    status: string;
+    verified: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface DnsRecord {
+    type: string;
+    name: string;
+    value: string;
+    ttl: number;
+    priority?: number;
+}
+interface DomainWithDnsRecords extends Domain {
+    dns_records: DnsRecord[];
+}
+interface DomainCreateParams {
+    domain: string;
+}
+interface DomainVerifyResult {
+    verified: boolean;
+    dns_records: DnsRecord[];
+}
+interface HealthResponse {
+    status: string;
+}
+
+declare class Contacts {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: ContactListParams): Promise<ListResponse<Contact>>;
+    get(id: string): Promise<SingleResponse<Contact>>;
+    create(data: ContactCreateParams): Promise<SingleResponse<Contact>>;
+    update(id: string, data: ContactUpdateParams): Promise<SingleResponse<Contact>>;
+    delete(id: string): Promise<void>;
+}
+
+declare class ListMembers {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(listId: string, params?: ListMembersParams): Promise<ListResponse<ListMember>>;
+    add(listId: string, contactIds: string[]): Promise<SingleResponse<{
+        added: number;
+    }>>;
+    remove(listId: string, contactIds: string[]): Promise<void>;
+}
+declare class Lists {
+    private readonly client;
+    readonly members: ListMembers;
+    constructor(client: HttpClient);
+    list(params?: PaginationParams): Promise<ListResponse<ContactList>>;
+    get(id: string): Promise<SingleResponse<ContactList>>;
+    create(data: ListCreateParams): Promise<SingleResponse<ContactList>>;
+    update(id: string, data: ListUpdateParams): Promise<SingleResponse<ContactList>>;
+    delete(id: string): Promise<void>;
+}
+
+declare class Campaigns {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: CampaignListParams): Promise<ListResponse<Campaign>>;
+    get(id: string): Promise<SingleResponse<Campaign>>;
+}
+
+declare class Templates {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: TemplateListParams): Promise<ListResponse<Template>>;
+    get(id: string): Promise<SingleResponse<Template>>;
+    create(data: TemplateCreateParams): Promise<SingleResponse<Template>>;
+}
+
+declare class Email {
+    private readonly client;
+    constructor(client: HttpClient);
+    send(data: EmailSendParams): Promise<SingleResponse<EmailSendResponse>>;
+    batch(data: EmailBatchParams): Promise<SingleResponse<EmailBatchResponse>>;
+    batchStatus(batchId: string): Promise<SingleResponse<EmailBatchStatus>>;
+    messageStatus(messageId: string): Promise<SingleResponse<EmailMessageStatus>>;
+}
+
+declare class Suppressions {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: SuppressionListParams): Promise<ListResponse<Suppression>>;
+    add(data: SuppressionAddParams): Promise<SingleResponse<Suppression>>;
+    remove(email: string): Promise<void>;
+}
+
+declare class Webhooks {
+    private readonly client;
+    constructor(client: HttpClient);
+    subscribe(data: WebhookSubscribeParams): Promise<SingleResponse<Webhook>>;
+    unsubscribe(id: string): Promise<void>;
+    test(id: string): Promise<SingleResponse<WebhookTestResponse>>;
+}
+
+declare class Tracking {
+    private readonly client;
+    constructor(client: HttpClient);
+    productView(data: ProductViewParams): Promise<SingleResponse<ProductViewResponse>>;
+}
+
+declare class Conversions {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: ConversionListParams): Promise<ListResponse<Conversion>>;
+    create(data: ConversionCreateParams): Promise<SingleResponse<Conversion>>;
+}
+
+declare class Segments {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: SegmentListParams): Promise<ListResponse<Segment>>;
+    get(id: string): Promise<SingleResponse<Segment>>;
+    create(data: SegmentCreateParams): Promise<SingleResponse<Segment>>;
+    update(id: string, data: SegmentUpdateParams): Promise<SingleResponse<Segment>>;
+    delete(id: string): Promise<void>;
+    estimateCount(id: string): Promise<SingleResponse<SegmentEstimate>>;
+    listContacts(id: string, params?: PaginationParams): Promise<ListResponse<Contact>>;
+}
+
+declare class TagContacts {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(tagId: string, params?: PaginationParams): Promise<ListResponse<Contact>>;
+    assign(tagId: string, contactIds: string[]): Promise<SingleResponse<TagAssignResult>>;
+    remove(tagId: string, contactIds: string[]): Promise<SingleResponse<TagRemoveResult>>;
+}
+declare class Tags {
+    private readonly client;
+    readonly contacts: TagContacts;
+    constructor(client: HttpClient);
+    list(params?: TagListParams): Promise<ListResponse<Tag>>;
+    get(id: string): Promise<SingleResponse<Tag>>;
+    create(data: TagCreateParams): Promise<SingleResponse<Tag>>;
+    update(id: string, data: TagUpdateParams): Promise<SingleResponse<Tag>>;
+    delete(id: string): Promise<void>;
+}
+
+declare class Automations {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(data: AutomationCreateParams): Promise<SingleResponse<AutomationWithSteps>>;
+    list(params?: AutomationListParams): Promise<ListResponse<Automation>>;
+    get(id: string): Promise<SingleResponse<AutomationWithSteps>>;
+    update(id: string, data: AutomationUpdateParams): Promise<SingleResponse<Automation>>;
+    activate(id: string): Promise<SingleResponse<Automation>>;
+    pause(id: string): Promise<SingleResponse<Automation>>;
+    delete(id: string): Promise<void>;
+    addStep(id: string, data: AutomationAddStepParams): Promise<SingleResponse<AutomationStep>>;
+    updateStep(automationId: string, stepId: string, data: AutomationUpdateStepParams): Promise<SingleResponse<AutomationStep>>;
+    deleteStep(automationId: string, stepId: string): Promise<void>;
+    batchUpdateSteps(id: string, data: AutomationBatchUpdateStepsParams): Promise<SingleResponse<{
+        success: boolean;
+    }>>;
+    trigger(id: string, data: AutomationTriggerParams): Promise<SingleResponse<AutomationTriggerResult>>;
+    listRuns(id: string, params?: AutomationRunListParams): Promise<ListResponse<AutomationRun>>;
+    cancelRun(automationId: string, runId: string): Promise<SingleResponse<{
+        id: string;
+        status: string;
+        completed_at: string | null;
+    }>>;
+}
+
+declare class Domains {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(): Promise<ListResponse<Domain>>;
+    get(id: string): Promise<SingleResponse<DomainWithDnsRecords>>;
+    create(data: DomainCreateParams): Promise<SingleResponse<DomainWithDnsRecords>>;
+    delete(id: string): Promise<void>;
+    verify(id: string): Promise<SingleResponse<DomainVerifyResult>>;
+}
+
+declare class Health {
+    private readonly client;
+    constructor(client: HttpClient);
+    check(): Promise<HealthResponse>;
+}
+
+declare class TopMailError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(message: string, code: string, statusCode: number);
+}
+declare class ValidationError extends TopMailError {
+    constructor(message: string, code?: string);
+}
+declare class AuthenticationError extends TopMailError {
+    constructor(message: string, code?: string);
+}
+declare class ForbiddenError extends TopMailError {
+    constructor(message: string, code?: string);
+}
+declare class NotFoundError extends TopMailError {
+    constructor(message: string, code?: string);
+}
+declare class RateLimitError extends TopMailError {
+    readonly retryAfter: number | null;
+    constructor(message: string, retryAfter?: number | null, code?: string);
+}
+declare class ServerError extends TopMailError {
+    constructor(message: string, statusCode?: number, code?: string);
+}
+
+interface TopMailOptions {
+    baseUrl?: string;
+}
+declare class TopMail {
+    readonly contacts: Contacts;
+    readonly lists: Lists;
+    readonly campaigns: Campaigns;
+    readonly templates: Templates;
+    readonly email: Email;
+    readonly suppressions: Suppressions;
+    readonly webhooks: Webhooks;
+    readonly tracking: Tracking;
+    readonly conversions: Conversions;
+    readonly segments: Segments;
+    readonly tags: Tags;
+    readonly automations: Automations;
+    readonly domains: Domains;
+    readonly health: Health;
+    /**
+     * True if the API key starts with `tm_test_`, indicating sandbox mode.
+     */
+    readonly isSandbox: boolean;
+    constructor(apiKey: string, options?: TopMailOptions);
+}
+
+export { AuthenticationError, type Automation, type AutomationAddStepParams, type AutomationBatchUpdateStepsParams, type AutomationCreateParams, type AutomationListParams, type AutomationRun, type AutomationRunListParams, type AutomationRunStatus, type AutomationStatus, type AutomationStep, type AutomationStepType, type AutomationTriggerParams, type AutomationTriggerResult, type AutomationUpdateParams, type AutomationUpdateStepParams, type AutomationWithSteps, Automations, type Campaign, type CampaignListParams, type CampaignStatus, Campaigns, type ClientOptions, type Contact, type ContactCreateParams, type ContactList, type ContactListParams, type ContactUpdateParams, Contacts, type Conversion, type ConversionCreateParams, type ConversionListParams, Conversions, type DnsRecord, type Domain, type DomainCreateParams, type DomainVerifyResult, type DomainWithDnsRecords, Domains, Email, type EmailBatchParams, type EmailBatchResponse, type EmailBatchStatus, type EmailMessageStatus, type EmailSendParams, type EmailSendResponse, type ErrorResponse, ForbiddenError, Health, type HealthResponse, HttpClient, type ListCreateParams, type ListMember, type ListMembersParams, type ListResponse, type ListUpdateParams, Lists, NotFoundError, type Pagination, type PaginationParams, type ProductViewParams, type ProductViewResponse, RateLimitError, type Segment, type SegmentCondition, type SegmentConditionGroup, type SegmentConditions, type SegmentCreateParams, type SegmentEstimate, type SegmentListParams, type SegmentUpdateParams, Segments, ServerError, type SingleResponse, type Suppression, type SuppressionAddParams, type SuppressionListParams, type SuppressionType, Suppressions, type Tag, type TagAssignResult, type TagCreateParams, type TagListParams, type TagRemoveResult, type TagUpdateParams, Tags, type Template, type TemplateCreateParams, type TemplateListParams, Templates, TopMail, TopMailError, type TopMailOptions, Tracking, ValidationError, type Webhook, type WebhookSubscribeParams, type WebhookTestResponse, Webhooks };