@hasna/emails-sdk 0.4.26

package/dist/index.d.ts

@@ -0,0 +1,311 @@
+/**
+ * @hasna/emails-sdk
+ * Zero-dependency TypeScript client for the @hasna/emails REST API.
+ * Works in Node.js, Bun, Deno, and browser environments.
+ */
+export interface Provider {
+    id: string;
+    name: string;
+    type: string;
+    active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface Domain {
+    id: string;
+    provider_id: string;
+    domain: string;
+    dkim_status: string;
+    spf_status: string;
+    dmarc_status: string;
+    verified_at: string | null;
+    created_at: string;
+}
+export interface EmailAddress {
+    id: string;
+    provider_id: string;
+    email: string;
+    display_name: string | null;
+    verified: boolean;
+    created_at: string;
+}
+export interface Email {
+    id: string;
+    provider_id: string;
+    provider_message_id: string | null;
+    from_address: string;
+    to_addresses: string[];
+    subject: string;
+    status: string;
+    sent_at: string;
+}
+export interface EmailEvent {
+    id: string;
+    email_id: string | null;
+    provider_id: string;
+    type: string;
+    recipient: string | null;
+    occurred_at: string;
+}
+export interface Contact {
+    id: string;
+    email: string;
+    name: string | null;
+    send_count: number;
+    bounce_count: number;
+    suppressed: boolean;
+}
+export interface Template {
+    id: string;
+    name: string;
+    subject_template: string;
+    html_template: string | null;
+    text_template: string | null;
+    created_at: string;
+}
+export interface Group {
+    id: string;
+    name: string;
+    description: string | null;
+    created_at: string;
+}
+export interface GroupMember {
+    email: string;
+    name: string | null;
+}
+export interface ScheduledEmail {
+    id: string;
+    status: string;
+    scheduled_at: string;
+    subject: string;
+}
+export interface Sequence {
+    id: string;
+    name: string;
+    status: string;
+    created_at: string;
+}
+export interface SequenceStep {
+    id: string;
+    sequence_id: string;
+    step_number: number;
+    delay_hours: number;
+    template_name: string;
+}
+export interface Enrollment {
+    id: string;
+    sequence_id: string;
+    contact_email: string;
+    current_step: number;
+    status: string;
+}
+export interface SandboxEmail {
+    id: string;
+    from_address: string;
+    to_addresses: string[];
+    subject: string;
+    created_at: string;
+}
+export interface InboundEmail {
+    id: string;
+    from_address: string;
+    to_addresses: string[];
+    subject: string;
+    in_reply_to_email_id: string | null;
+    received_at: string;
+}
+export interface WarmingSchedule {
+    id: string;
+    domain: string;
+    target_daily_volume: number;
+    start_date: string;
+    status: string;
+}
+export interface Stats {
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    opened: number;
+    clicked: number;
+    delivery_rate: number;
+    bounce_rate: number;
+    open_rate: number;
+}
+export interface Analytics {
+    dailyVolume: {
+        date: string;
+        count: number;
+    }[];
+    topRecipients: {
+        email: string;
+        count: number;
+    }[];
+    busiestHours: {
+        hour: number;
+        count: number;
+    }[];
+    deliveryTrend: {
+        date: string;
+        sent: number;
+        delivered: number;
+        bounced: number;
+    }[];
+}
+export interface DnsRecord {
+    type: string;
+    name: string;
+    value: string;
+    purpose: string;
+}
+export interface DoctorCheck {
+    name: string;
+    status: string;
+    message: string;
+}
+export interface EmailsClientOptions {
+    /** Base URL of the emails server, e.g. "http://localhost:3900" */
+    serverUrl: string;
+}
+export declare class EmailsClient {
+    private readonly baseUrl;
+    constructor(options: EmailsClientOptions);
+    private request;
+    listProviders(): Promise<Provider[]>;
+    addProvider(body: {
+        name: string;
+        type: string;
+        api_key?: string;
+        region?: string;
+        access_key?: string;
+        secret_key?: string;
+        oauth_client_id?: string;
+        oauth_client_secret?: string;
+    }): Promise<Provider>;
+    updateProvider(id: string, body: Record<string, unknown>): Promise<Provider>;
+    removeProvider(id: string): Promise<void>;
+    reauthProvider(id: string): Promise<{
+        ok: boolean;
+        provider: Provider;
+    }>;
+    listDomains(providerId?: string): Promise<Domain[]>;
+    addDomain(body: {
+        provider_id: string;
+        domain: string;
+    }): Promise<Domain>;
+    getDnsRecords(id: string): Promise<DnsRecord[]>;
+    verifyDomain(id: string): Promise<unknown>;
+    removeDomain(id: string): Promise<void>;
+    listAddresses(): Promise<EmailAddress[]>;
+    addAddress(body: {
+        provider_id: string;
+        email: string;
+        display_name?: string;
+    }): Promise<EmailAddress>;
+    removeAddress(id: string): Promise<void>;
+    listEmails(params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+        provider_id?: string;
+    }): Promise<Email[]>;
+    getEmail(id: string): Promise<Email>;
+    searchEmails(query: string, params?: {
+        since?: string;
+        limit?: number;
+    }): Promise<Email[]>;
+    getEmailContent(id: string): Promise<{
+        html: string | null;
+        text_body: string | null;
+        headers: Record<string, string>;
+    }>;
+    listEvents(params?: {
+        type?: string;
+        limit?: number;
+    }): Promise<EmailEvent[]>;
+    getStats(period?: string): Promise<Stats>;
+    getAnalytics(params?: {
+        period?: string;
+        provider_id?: string;
+    }): Promise<Analytics>;
+    pull(providerId?: string): Promise<Record<string, number>>;
+    listContacts(suppressed?: boolean): Promise<Contact[]>;
+    suppressContact(email: string): Promise<void>;
+    unsuppressContact(email: string): Promise<void>;
+    listTemplates(): Promise<Template[]>;
+    addTemplate(body: {
+        name: string;
+        subject_template: string;
+        html_template?: string;
+        text_template?: string;
+    }): Promise<Template>;
+    removeTemplate(id: string): Promise<void>;
+    listGroups(): Promise<Group[]>;
+    createGroup(body: {
+        name: string;
+        description?: string;
+    }): Promise<Group>;
+    deleteGroup(id: string): Promise<void>;
+    listGroupMembers(id: string): Promise<GroupMember[]>;
+    addGroupMember(id: string, body: {
+        email: string;
+        name?: string;
+    }): Promise<void>;
+    removeGroupMember(id: string, email: string): Promise<void>;
+    listScheduled(status?: string): Promise<ScheduledEmail[]>;
+    cancelScheduled(id: string): Promise<void>;
+    listSequences(): Promise<Sequence[]>;
+    createSequence(body: {
+        name: string;
+        description?: string;
+    }): Promise<Sequence>;
+    deleteSequence(id: string): Promise<void>;
+    listSequenceSteps(id: string): Promise<SequenceStep[]>;
+    addSequenceStep(id: string, body: {
+        step_number: number;
+        delay_hours: number;
+        template_name: string;
+    }): Promise<SequenceStep>;
+    listEnrollments(id: string): Promise<Enrollment[]>;
+    enrollContact(id: string, body: {
+        contact_email: string;
+        provider_id?: string;
+    }): Promise<Enrollment>;
+    unenrollContact(id: string, email: string): Promise<void>;
+    listSandboxEmails(params?: {
+        provider_id?: string;
+        limit?: number;
+    }): Promise<SandboxEmail[]>;
+    getSandboxEmail(id: string): Promise<SandboxEmail>;
+    clearSandboxEmails(providerId?: string): Promise<{
+        deleted: number;
+    }>;
+    listInboundEmails(params?: {
+        provider_id?: string;
+        limit?: number;
+    }): Promise<InboundEmail[]>;
+    getInboundEmail(id: string): Promise<InboundEmail>;
+    clearInboundEmails(providerId?: string): Promise<void>;
+    listWarmingSchedules(): Promise<WarmingSchedule[]>;
+    createWarmingSchedule(body: {
+        domain: string;
+        target_daily_volume: number;
+        start_date?: string;
+    }): Promise<WarmingSchedule>;
+    getWarmingStatus(domain: string): Promise<WarmingSchedule & {
+        today_limit: number;
+        today_sent: number;
+        current_day: number;
+    }>;
+    updateWarmingStatus(domain: string, status: string): Promise<WarmingSchedule>;
+    deleteWarmingSchedule(domain: string): Promise<void>;
+    exportEmails(format?: "csv" | "json", params?: {
+        provider_id?: string;
+        since?: string;
+    }): Promise<string>;
+    exportEvents(format?: "csv" | "json", params?: {
+        provider_id?: string;
+        since?: string;
+    }): Promise<string>;
+    runDoctor(): Promise<DoctorCheck[]>;
+}

package/dist/index.js

@@ -0,0 +1,221 @@
+// src/index.ts
+async function checkResponse(res) {
+  if (!res.ok) {
+    let message = `HTTP ${res.status}`;
+    try {
+      const body = await res.json();
+      if (body.error)
+        message = body.error;
+    } catch {}
+    throw new Error(message);
+  }
+}
+function qs(params) {
+  if (!params)
+    return "";
+  const entries = Object.entries(params).filter(([, v]) => v !== undefined && v !== null);
+  if (entries.length === 0)
+    return "";
+  const sp = new URLSearchParams;
+  for (const [k, v] of entries)
+    sp.set(k, String(v));
+  return "?" + sp.toString();
+}
+
+class EmailsClient {
+  baseUrl;
+  constructor(options) {
+    this.baseUrl = options.serverUrl.replace(/\/$/, "");
+  }
+  async request(path, init = {}) {
+    const res = await fetch(this.baseUrl + path, {
+      ...init,
+      headers: { "Content-Type": "application/json", ...init.headers }
+    });
+    await checkResponse(res);
+    return res.json();
+  }
+  async listProviders() {
+    return this.request("/api/providers");
+  }
+  async addProvider(body) {
+    return this.request("/api/providers", { method: "POST", body: JSON.stringify(body) });
+  }
+  async updateProvider(id, body) {
+    return this.request(`/api/providers/${id}`, { method: "PUT", body: JSON.stringify(body) });
+  }
+  async removeProvider(id) {
+    await this.request(`/api/providers/${id}`, { method: "DELETE" });
+  }
+  async reauthProvider(id) {
+    return this.request(`/api/providers/${id}/auth`, { method: "POST" });
+  }
+  async listDomains(providerId) {
+    return this.request(`/api/domains${qs({ provider_id: providerId })}`);
+  }
+  async addDomain(body) {
+    return this.request("/api/domains", { method: "POST", body: JSON.stringify(body) });
+  }
+  async getDnsRecords(id) {
+    return this.request(`/api/domains/${id}/dns`);
+  }
+  async verifyDomain(id) {
+    return this.request(`/api/domains/${id}/verify`, { method: "POST" });
+  }
+  async removeDomain(id) {
+    await this.request(`/api/domains/${id}`, { method: "DELETE" });
+  }
+  async listAddresses() {
+    return this.request("/api/addresses");
+  }
+  async addAddress(body) {
+    return this.request("/api/addresses", { method: "POST", body: JSON.stringify(body) });
+  }
+  async removeAddress(id) {
+    await this.request(`/api/addresses/${id}`, { method: "DELETE" });
+  }
+  async listEmails(params) {
+    return this.request(`/api/emails${qs(params)}`);
+  }
+  async getEmail(id) {
+    return this.request(`/api/emails/${id}`);
+  }
+  async searchEmails(query, params) {
+    return this.request(`/api/emails/search${qs({ q: query, ...params })}`);
+  }
+  async getEmailContent(id) {
+    return this.request(`/api/email-content/${id}`);
+  }
+  async listEvents(params) {
+    return this.request(`/api/events${qs(params)}`);
+  }
+  async getStats(period) {
+    return this.request(`/api/stats${qs({ period })}`);
+  }
+  async getAnalytics(params) {
+    return this.request(`/api/analytics${qs(params)}`);
+  }
+  async pull(providerId) {
+    return this.request("/api/pull", {
+      method: "POST",
+      body: providerId ? JSON.stringify({ provider_id: providerId }) : "{}"
+    });
+  }
+  async listContacts(suppressed) {
+    return this.request(`/api/contacts${qs({ suppressed: suppressed !== undefined ? String(suppressed) : undefined })}`);
+  }
+  async suppressContact(email) {
+    await this.request(`/api/contacts/${encodeURIComponent(email)}/suppress`, { method: "POST" });
+  }
+  async unsuppressContact(email) {
+    await this.request(`/api/contacts/${encodeURIComponent(email)}/unsuppress`, { method: "POST" });
+  }
+  async listTemplates() {
+    return this.request("/api/templates");
+  }
+  async addTemplate(body) {
+    return this.request("/api/templates", { method: "POST", body: JSON.stringify(body) });
+  }
+  async removeTemplate(id) {
+    await this.request(`/api/templates/${id}`, { method: "DELETE" });
+  }
+  async listGroups() {
+    return this.request("/api/groups");
+  }
+  async createGroup(body) {
+    return this.request("/api/groups", { method: "POST", body: JSON.stringify(body) });
+  }
+  async deleteGroup(id) {
+    await this.request(`/api/groups/${id}`, { method: "DELETE" });
+  }
+  async listGroupMembers(id) {
+    return this.request(`/api/groups/${id}/members`);
+  }
+  async addGroupMember(id, body) {
+    await this.request(`/api/groups/${id}/members`, { method: "POST", body: JSON.stringify(body) });
+  }
+  async removeGroupMember(id, email) {
+    await this.request(`/api/groups/${id}/members/${encodeURIComponent(email)}`, { method: "DELETE" });
+  }
+  async listScheduled(status) {
+    return this.request(`/api/scheduled${qs({ status })}`);
+  }
+  async cancelScheduled(id) {
+    await this.request(`/api/scheduled/${id}`, { method: "DELETE" });
+  }
+  async listSequences() {
+    return this.request("/api/sequences");
+  }
+  async createSequence(body) {
+    return this.request("/api/sequences", { method: "POST", body: JSON.stringify(body) });
+  }
+  async deleteSequence(id) {
+    await this.request(`/api/sequences/${id}`, { method: "DELETE" });
+  }
+  async listSequenceSteps(id) {
+    return this.request(`/api/sequences/${id}/steps`);
+  }
+  async addSequenceStep(id, body) {
+    return this.request(`/api/sequences/${id}/steps`, { method: "POST", body: JSON.stringify(body) });
+  }
+  async listEnrollments(id) {
+    return this.request(`/api/sequences/${id}/enrollments`);
+  }
+  async enrollContact(id, body) {
+    return this.request(`/api/sequences/${id}/enroll`, { method: "POST", body: JSON.stringify(body) });
+  }
+  async unenrollContact(id, email) {
+    await this.request(`/api/sequences/${id}/enrollments/${encodeURIComponent(email)}`, {
+      method: "DELETE"
+    });
+  }
+  async listSandboxEmails(params) {
+    return this.request(`/api/sandbox${qs(params)}`);
+  }
+  async getSandboxEmail(id) {
+    return this.request(`/api/sandbox/${id}`);
+  }
+  async clearSandboxEmails(providerId) {
+    return this.request(`/api/sandbox${qs({ provider_id: providerId })}`, { method: "DELETE" });
+  }
+  async listInboundEmails(params) {
+    return this.request(`/api/inbound${qs(params)}`);
+  }
+  async getInboundEmail(id) {
+    return this.request(`/api/inbound/${id}`);
+  }
+  async clearInboundEmails(providerId) {
+    await this.request(`/api/inbound${qs({ provider_id: providerId })}`, { method: "DELETE" });
+  }
+  async listWarmingSchedules() {
+    return this.request("/api/warming");
+  }
+  async createWarmingSchedule(body) {
+    return this.request("/api/warming", { method: "POST", body: JSON.stringify(body) });
+  }
+  async getWarmingStatus(domain) {
+    return this.request(`/api/warming/${domain}`);
+  }
+  async updateWarmingStatus(domain, status) {
+    return this.request(`/api/warming/${domain}`, { method: "PUT", body: JSON.stringify({ status }) });
+  }
+  async deleteWarmingSchedule(domain) {
+    await this.request(`/api/warming/${domain}`, { method: "DELETE" });
+  }
+  async exportEmails(format, params) {
+    const res = await fetch(this.baseUrl + `/api/export/emails${qs({ format: format || "json", ...params })}`);
+    await checkResponse(res);
+    return res.text();
+  }
+  async exportEvents(format, params) {
+    const res = await fetch(this.baseUrl + `/api/export/events${qs({ format: format || "json", ...params })}`);
+    await checkResponse(res);
+    return res.text();
+  }
+  async runDoctor() {
+    return this.request("/api/doctor");
+  }
+}
+export {
+  EmailsClient
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hasna/emails-sdk",
+  "version": "0.4.26",
+  "description": "Zero-dependency TypeScript client for @hasna/emails REST API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+    "types": "./dist/index.d.ts",
+    "import": "./dist/index.js"
+  }
+},
+"files": ["dist"],
+"publishConfig": {
+"access": "public"
+},
+"license": "Apache-2.0",
+"author": "Andrei Hasna <andrei@hasna.com>",
+"scripts": {
+  "build": "bun build src/index.ts --outdir dist --target browser && tsc --emitDeclarationOnly --outDir dist",
+  "test": "bun test"
+},
+"devDependencies": {
+  "typescript": "^5.7.3"
+}
+}