lumail 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,257 @@
+# Lumail
+
+TypeScript SDK and CLI for the [Lumail](https://lumail.io) email marketing platform.
+
+Manage subscribers, send campaigns, trigger transactional emails, and more — all from code.
+
+## Install
+
+```bash
+npm install lumail
+# or
+pnpm add lumail
+```
+
+## Quick Start
+
+```typescript
+import { Lumail } from "lumail";
+
+const lumail = new Lumail({
+  apiKey: "lum_your_api_key", // Get yours at lumail.io/settings
+});
+
+// Add a subscriber
+const { subscriber } = await lumail.subscribers.create({
+  email: "john@example.com",
+  name: "John Doe",
+  tags: ["newsletter", "welcome"],
+});
+
+// Send a transactional email
+await lumail.emails.send({
+  to: "john@example.com",
+  from: "hello@yourdomain.com",
+  subject: "Welcome!",
+  content: "Thanks for signing up.",
+  contentType: "MARKDOWN",
+});
+```
+
+## Authentication
+
+Get your API key from your [Lumail settings page](https://lumail.io/settings), then pass it to the constructor:
+
+```typescript
+const lumail = new Lumail({ apiKey: "lum_..." });
+```
+
+## Resources
+
+### Subscribers
+
+```typescript
+// List subscribers (with cursor pagination)
+const { subscribers, nextCursor } = await lumail.subscribers.list({
+  tag: "newsletter",
+  status: "SUBSCRIBED",
+  limit: 50,
+});
+
+// Get a subscriber by ID or email
+const { subscriber } = await lumail.subscribers.get("john@example.com");
+
+// Create a subscriber
+const { subscriber } = await lumail.subscribers.create({
+  email: "john@example.com",
+  name: "John Doe",
+  phone: "+1234567890",
+  tags: ["newsletter"],
+  fields: { company: "Acme" },
+  triggerWorkflows: true,
+});
+
+// Update a subscriber
+await lumail.subscribers.update("john@example.com", {
+  name: "John D.",
+  fields: { company: "New Corp" },
+});
+
+// Delete a subscriber
+await lumail.subscribers.delete("john@example.com");
+
+// Unsubscribe
+await lumail.subscribers.unsubscribe("john@example.com");
+
+// Manage tags
+await lumail.subscribers.addTags("john@example.com", ["vip", "early-adopter"]);
+await lumail.subscribers.removeTags("john@example.com", ["early-adopter"]);
+
+// List subscriber events
+const { events } = await lumail.subscribers.listEvents("john@example.com", {
+  eventTypes: ["EMAIL_OPENED", "EMAIL_CLICKED"],
+  order: "desc",
+  take: 20,
+});
+```
+
+### Campaigns
+
+```typescript
+// List campaigns
+const { campaigns } = await lumail.campaigns.list({
+  status: "DRAFT",
+  limit: 10,
+});
+
+// Create a campaign
+const { campaign } = await lumail.campaigns.create({
+  subject: "March Newsletter",
+  name: "march-2026",
+  preview: "What's new this month",
+  contentType: "MARKDOWN",
+  content: "# Hello\n\nHere's what's new...",
+});
+
+// Get a campaign
+const { campaign } = await lumail.campaigns.get("campaign_id");
+
+// Update a campaign
+await lumail.campaigns.update("campaign_id", {
+  subject: "Updated Subject",
+});
+
+// Send immediately
+await lumail.campaigns.send("campaign_id");
+
+// Schedule for later
+await lumail.campaigns.send("campaign_id", {
+  scheduledAt: "2026-04-10T09:00:00Z",
+  timezone: "Europe/Paris",
+});
+
+// Delete a campaign
+await lumail.campaigns.delete("campaign_id");
+```
+
+### Emails
+
+```typescript
+// Send a transactional email
+await lumail.emails.send({
+  to: "user@example.com",
+  from: "noreply@yourdomain.com",
+  subject: "Your invoice",
+  content: "<h1>Invoice #123</h1><p>Amount: $99</p>",
+  contentType: "HTML",
+  replyTo: "support@yourdomain.com",
+  transactional: true,
+  tracking: { open: true, links: true },
+});
+
+// Verify an email address
+const result = await lumail.emails.verify({
+  email: "check@example.com",
+});
+
+if (!result.success) {
+  console.log(result.code, result.error, result.suggestion);
+}
+```
+
+### Tags
+
+```typescript
+// List all tags
+const { tags } = await lumail.tags.list();
+
+// Create a tag
+const { tag } = await lumail.tags.create({ name: "vip" });
+
+// Get a tag (includes subscriber count)
+const { tag } = await lumail.tags.get("vip");
+
+// Update a tag
+await lumail.tags.update("vip", { name: "VIP Customers" });
+```
+
+### Events
+
+```typescript
+// Create a custom event
+await lumail.events.create({
+  eventType: "SUBSCRIBER_PAYMENT",
+  subscriber: "john@example.com",
+  data: { amount: 99, currency: "USD", plan: "pro" },
+});
+```
+
+### Tools (v2)
+
+AI-powered tools for email marketing.
+
+```typescript
+// List available tools
+const { tools } = await lumail.tools.list();
+
+// Get tool details
+const { tool } = await lumail.tools.get("generate-subject-line");
+
+// Run a tool
+const result = await lumail.tools.run("generate-subject-line", {
+  topic: "Spring sale announcement",
+  tone: "excited",
+});
+```
+
+## Error Handling
+
+The SDK throws typed errors you can catch individually:
+
+```typescript
+import {
+  Lumail,
+  LumailAuthenticationError,
+  LumailValidationError,
+  LumailNotFoundError,
+  LumailRateLimitError,
+  LumailPaymentRequiredError,
+} from "lumail";
+
+try {
+  await lumail.subscribers.get("unknown@example.com");
+} catch (error) {
+  if (error instanceof LumailNotFoundError) {
+    console.log("Subscriber not found");
+  } else if (error instanceof LumailAuthenticationError) {
+    console.log("Invalid API key");
+  } else if (error instanceof LumailRateLimitError) {
+    console.log(`Rate limited, retry after ${error.retryAfter}ms`);
+  } else if (error instanceof LumailValidationError) {
+    console.log(`Bad request: ${error.message}`);
+  } else if (error instanceof LumailPaymentRequiredError) {
+    console.log("Plan limit reached — upgrade at lumail.io/billing");
+  }
+}
+```
+
+All errors extend `LumailError` which includes `status` and `code` properties.
+
+The client automatically retries idempotent requests (GET, PUT, DELETE) on rate-limit (429) and network errors with exponential backoff.
+
+## CLI
+
+The package also ships a CLI:
+
+```bash
+npx lumail --help
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- An API key from [lumail.io](https://lumail.io)
+
+## License
+
+MIT

package/dist/cli.js

@@ -5,15 +5,29 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
@@ -991,8 +1005,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {
-          }
+          } else {}
         };
       }
       return this;
@@ -2260,6 +2273,19 @@ class LumailPaymentRequiredError extends LumailError {
   }
 }
 
+class LumailConfirmationRequiredError extends LumailError {
+  confirmationCode;
+  action;
+  instruction;
+  constructor(message, confirmationCode, action, instruction) {
+    super(message, 403, "CONFIRMATION_REQUIRED");
+    this.name = "LumailConfirmationRequiredError";
+    this.confirmationCode = confirmationCode;
+    this.action = action;
+    this.instruction = instruction;
+  }
+}
+
 // ../../src/lib/lumail-sdk/client.ts
 var DEFAULT_BASE_URL = "https://lumail.io/api";
 var DEFAULT_TIMEOUT = 30000;
@@ -2295,11 +2321,7 @@ class LumailClient {
           signal
         });
         if (response.ok) {
-          const data = await response.json();
-          if (data.success === false) {
-            throw new LumailError(data.message ?? "Request failed", response.status, data.code);
-          }
-          return data;
+          return await response.json();
         }
         if (response.status === 429 && isIdempotent && attempt < maxRetries) {
           await sleep(parseRetryAfter(response, RETRY_DELAYS[attempt]));
@@ -2336,8 +2358,7 @@ class LumailClient {
     let body = {};
     try {
       body = await response.json();
-    } catch {
-    }
+    } catch {}
     const message = body.message ?? body.error ?? response.statusText;
     const code = body.code;
     switch (response.status) {
@@ -2345,6 +2366,12 @@ class LumailClient {
         return new LumailAuthenticationError(message);
       case 402:
         return new LumailPaymentRequiredError(message);
+      case 403: {
+        if (body.error === "CONFIRMATION_REQUIRED") {
+          return new LumailConfirmationRequiredError(message, body.confirmationCode, body.action, body.instruction);
+        }
+        return new LumailValidationError(message);
+      }
       case 404:
         return new LumailNotFoundError(message);
       case 429: {
@@ -2444,6 +2471,11 @@ class Subscribers {
   constructor(client) {
     this.client = client;
   }
+  async list(params) {
+    return this.client.request("GET", "/v1/subscribers", {
+      params
+    });
+  }
   async create(params) {
     return this.client.request("POST", "/v1/subscribers", {
       body: params
@@ -2511,8 +2543,21 @@ class Tools {
   async get(toolName) {
     return this.client.request("GET", `/v2/tools/${encodeURIComponent(toolName)}`);
   }
-  async run(toolName, params) {
-    return this.client.request("POST", `/v2/tools/${encodeURIComponent(toolName)}`, { body: params ?? {} });
+  async run(toolName, params, options) {
+    const { autoConfirm = true } = options ?? {};
+    const endpoint = `/v2/tools/${encodeURIComponent(toolName)}`;
+    try {
+      return await this.client.request("POST", endpoint, {
+        body: params ?? {}
+      });
+    } catch (error) {
+      if (autoConfirm && error instanceof LumailConfirmationRequiredError) {
+        return this.client.request("POST", endpoint, {
+          body: { ...params, confirmationCode: error.confirmationCode }
+        });
+      }
+      throw error;
+    }
   }
 }
 
@@ -2664,7 +2709,7 @@ function fmtCell(v) {
   return s;
 }
 function stripAnsi(s) {
-  return s.replace(/\x1b\[[0-9;]*m/g, "");
+  return s.replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g"), "");
 }
 function printTable(rows) {
   const cols = Object.keys(rows[0] ?? {});
@@ -2753,6 +2798,26 @@ API key is valid.`));
 
 // ../../src/cli/commands/subscribers.ts
 var subscribersCommand = new Command("subscribers").description("Manage subscribers");
+subscribersCommand.command("list").description("List subscribers with optional filters").option("--tag <tag>", "Filter by tag name").option("--status <status>", "Filter by status (all, SUBSCRIBED, UNSUBSCRIBED, etc.)", "all").option("--limit <n>", "Max number of subscribers to return", "50").option("--cursor <id>", "Cursor for pagination (subscriber ID)").option("--query <q>", "Search by name or email").action(async (opts) => {
+  try {
+    const limit = Number(opts.limit);
+    if (!Number.isFinite(limit) || limit < 1) {
+      console.error("Error: --limit must be a positive integer");
+      process.exit(1);
+    }
+    const lumail = getLumail();
+    const result = await lumail.subscribers.list({
+      tag: opts.tag,
+      status: opts.status,
+      limit,
+      cursor: opts.cursor,
+      query: opts.query
+    });
+    output(result);
+  } catch (error) {
+    handleError(error);
+  }
+});
 subscribersCommand.command("create").description("Create or update a subscriber").requiredOption("--email <email>", "Email address").option("--name <name>", "Subscriber name").option("--tags <tags...>", "Tags to add").action(async (opts) => {
   try {
     const lumail = getLumail();
@@ -3041,7 +3106,7 @@ import { homedir as homedir2 } from "os";
 import { join as join2 } from "path";
 var SKILL_URL = "https://raw.githubusercontent.com/Melvynx/lumail-opensource/main/skills/lumail/SKILL.md";
 var SKILLS_DIR = join2(homedir2(), ".claude", "skills", "lumail");
-function prompt(question) {
+async function prompt(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
     rl.question(question, (answer) => {
@@ -3097,7 +3162,7 @@ Installing Lumail skill...`));
     console.log(import_picocolors3.default.green("Skill installed to ~/.claude/skills/lumail/"));
   } catch {
     console.log(import_picocolors3.default.yellow("Could not download skill from GitHub."));
-    console.log(import_picocolors3.default.dim("Manual install: curl -o ~/.claude/skills/lumail/SKILL.md --create-dirs " + SKILL_URL));
+    console.log(import_picocolors3.default.dim(`Manual install: curl -o ~/.claude/skills/lumail/SKILL.md --create-dirs ${SKILL_URL}`));
   }
   setToken(token);
   console.log(import_picocolors3.default.green("API key saved."));

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import type { RequestOptions } from "./types";
+export declare class LumailClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(apiKey: string, baseUrl?: string);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private buildUrl;
+    private handleErrorResponse;
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+export declare class LumailError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(message: string, status: number, code?: string);
+}
+export declare class LumailAuthenticationError extends LumailError {
+    constructor(message?: string);
+}
+export declare class LumailRateLimitError extends LumailError {
+    readonly retryAfter: number | null;
+    constructor(message?: string, retryAfter?: number | null);
+}
+export declare class LumailValidationError extends LumailError {
+    constructor(message: string);
+}
+export declare class LumailNotFoundError extends LumailError {
+    constructor(message?: string);
+}
+export declare class LumailPaymentRequiredError extends LumailError {
+    constructor(message?: string);
+}
+export declare class LumailConfirmationRequiredError extends LumailError {
+    readonly confirmationCode: number;
+    readonly action: string;
+    readonly instruction: string;
+    constructor(message: string, confirmationCode: number, action: string, instruction: string);
+}

package/dist/index.cjs

@@ -2,27 +2,37 @@ var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __moduleCache = /* @__PURE__ */ new WeakMap;
+function __accessProp(key) {
+  return this[key];
+}
 var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
   if (entry)
     return entry;
   entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
   __moduleCache.set(from, entry);
   return entry;
 };
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 
@@ -34,6 +44,7 @@ __export(exports_lumail_sdk, {
   LumailPaymentRequiredError: () => LumailPaymentRequiredError,
   LumailNotFoundError: () => LumailNotFoundError,
   LumailError: () => LumailError,
+  LumailConfirmationRequiredError: () => LumailConfirmationRequiredError,
   LumailAuthenticationError: () => LumailAuthenticationError,
   Lumail: () => Lumail
 });
@@ -88,6 +99,19 @@ class LumailPaymentRequiredError extends LumailError {
   }
 }
 
+class LumailConfirmationRequiredError extends LumailError {
+  confirmationCode;
+  action;
+  instruction;
+  constructor(message, confirmationCode, action, instruction) {
+    super(message, 403, "CONFIRMATION_REQUIRED");
+    this.name = "LumailConfirmationRequiredError";
+    this.confirmationCode = confirmationCode;
+    this.action = action;
+    this.instruction = instruction;
+  }
+}
+
 // ../../src/lib/lumail-sdk/client.ts
 var DEFAULT_BASE_URL = "https://lumail.io/api";
 var DEFAULT_TIMEOUT = 30000;
@@ -123,11 +147,7 @@ class LumailClient {
           signal
         });
         if (response.ok) {
-          const data = await response.json();
-          if (data.success === false) {
-            throw new LumailError(data.message ?? "Request failed", response.status, data.code);
-          }
-          return data;
+          return await response.json();
         }
         if (response.status === 429 && isIdempotent && attempt < maxRetries) {
           await sleep(parseRetryAfter(response, RETRY_DELAYS[attempt]));
@@ -164,8 +184,7 @@ class LumailClient {
     let body = {};
     try {
       body = await response.json();
-    } catch {
-    }
+    } catch {}
     const message = body.message ?? body.error ?? response.statusText;
     const code = body.code;
     switch (response.status) {
@@ -173,6 +192,12 @@ class LumailClient {
         return new LumailAuthenticationError(message);
       case 402:
         return new LumailPaymentRequiredError(message);
+      case 403: {
+        if (body.error === "CONFIRMATION_REQUIRED") {
+          return new LumailConfirmationRequiredError(message, body.confirmationCode, body.action, body.instruction);
+        }
+        return new LumailValidationError(message);
+      }
       case 404:
         return new LumailNotFoundError(message);
       case 429: {
@@ -272,6 +297,11 @@ class Subscribers {
   constructor(client) {
     this.client = client;
   }
+  async list(params) {
+    return this.client.request("GET", "/v1/subscribers", {
+      params
+    });
+  }
   async create(params) {
     return this.client.request("POST", "/v1/subscribers", {
       body: params
@@ -339,8 +369,21 @@ class Tools {
   async get(toolName) {
     return this.client.request("GET", `/v2/tools/${encodeURIComponent(toolName)}`);
   }
-  async run(toolName, params) {
-    return this.client.request("POST", `/v2/tools/${encodeURIComponent(toolName)}`, { body: params ?? {} });
+  async run(toolName, params, options) {
+    const { autoConfirm = true } = options ?? {};
+    const endpoint = `/v2/tools/${encodeURIComponent(toolName)}`;
+    try {
+      return await this.client.request("POST", endpoint, {
+        body: params ?? {}
+      });
+    } catch (error) {
+      if (autoConfirm && error instanceof LumailConfirmationRequiredError) {
+        return this.client.request("POST", endpoint, {
+          body: { ...params, confirmationCode: error.confirmationCode }
+        });
+      }
+      throw error;
+    }
   }
 }
 

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { Campaigns } from "./resources/campaigns";
+import { Emails } from "./resources/emails";
+import { Events } from "./resources/events";
+import { Subscribers } from "./resources/subscribers";
+import { Tags } from "./resources/tags";
+import { Tools } from "./resources/tools";
+import type { LumailOptions } from "./types";
+export declare class Lumail {
+    readonly subscribers: Subscribers;
+    readonly campaigns: Campaigns;
+    readonly emails: Emails;
+    readonly tags: Tags;
+    readonly events: Events;
+    readonly tools: Tools;
+    constructor(options: LumailOptions);
+}
+export { LumailAuthenticationError, LumailConfirmationRequiredError, LumailError, LumailNotFoundError, LumailPaymentRequiredError, LumailRateLimitError, LumailValidationError, } from "./errors";
+export type { AddTagsResponse, Campaign, CampaignSender, CampaignStatus, CampaignSummary, ContentType, CreateCampaignParams, CreateCampaignResponse, CreateEventParams, CreateEventResponse, CreateSubscriberParams, CreateSubscriberResponse, CreateTagParams, CreateTagResponse, DeleteCampaignResponse, DeleteSubscriberResponse, EmailContentType, GetCampaignResponse, GetSubscriberResponse, GetTagResponse, ConfirmationRequiredResponse, GetToolResponse, ListCampaignsParams, ListCampaignsResponse, ListEventsParams, ListEventsResponse, ListSubscriberEntry, ListSubscribersParams, ListSubscribersResponse, ListTagsResponse, ListToolsResponse, LumailOptions, RemoveTagsResponse, RunToolResponse, SendCampaignParams, SendCampaignResponse, SendEmailParams, SendEmailResponse, Subscriber, SubscriberEvent, SubscriberEventType, SubscriberStatus, SubscriberTag, Tag, TagWithCount, ToolDefinition, UnsubscribeResponse, UpdateCampaignParams, UpdateCampaignResponse, UpdateSubscriberParams, UpdateSubscriberResponse, UpdateTagParams, UpdateTagResponse, VerifyEmailParams, VerifyEmailResponse, } from "./types";
+export type { RunToolOptions } from "./resources/tools";

package/dist/index.js

@@ -47,6 +47,19 @@ class LumailPaymentRequiredError extends LumailError {
   }
 }
 
+class LumailConfirmationRequiredError extends LumailError {
+  confirmationCode;
+  action;
+  instruction;
+  constructor(message, confirmationCode, action, instruction) {
+    super(message, 403, "CONFIRMATION_REQUIRED");
+    this.name = "LumailConfirmationRequiredError";
+    this.confirmationCode = confirmationCode;
+    this.action = action;
+    this.instruction = instruction;
+  }
+}
+
 // ../../src/lib/lumail-sdk/client.ts
 var DEFAULT_BASE_URL = "https://lumail.io/api";
 var DEFAULT_TIMEOUT = 30000;
@@ -82,11 +95,7 @@ class LumailClient {
           signal
         });
         if (response.ok) {
-          const data = await response.json();
-          if (data.success === false) {
-            throw new LumailError(data.message ?? "Request failed", response.status, data.code);
-          }
-          return data;
+          return await response.json();
         }
         if (response.status === 429 && isIdempotent && attempt < maxRetries) {
           await sleep(parseRetryAfter(response, RETRY_DELAYS[attempt]));
@@ -123,8 +132,7 @@ class LumailClient {
     let body = {};
     try {
       body = await response.json();
-    } catch {
-    }
+    } catch {}
     const message = body.message ?? body.error ?? response.statusText;
     const code = body.code;
     switch (response.status) {
@@ -132,6 +140,12 @@ class LumailClient {
         return new LumailAuthenticationError(message);
       case 402:
         return new LumailPaymentRequiredError(message);
+      case 403: {
+        if (body.error === "CONFIRMATION_REQUIRED") {
+          return new LumailConfirmationRequiredError(message, body.confirmationCode, body.action, body.instruction);
+        }
+        return new LumailValidationError(message);
+      }
       case 404:
         return new LumailNotFoundError(message);
       case 429: {
@@ -231,6 +245,11 @@ class Subscribers {
   constructor(client) {
     this.client = client;
   }
+  async list(params) {
+    return this.client.request("GET", "/v1/subscribers", {
+      params
+    });
+  }
   async create(params) {
     return this.client.request("POST", "/v1/subscribers", {
       body: params
@@ -298,8 +317,21 @@ class Tools {
   async get(toolName) {
     return this.client.request("GET", `/v2/tools/${encodeURIComponent(toolName)}`);
   }
-  async run(toolName, params) {
-    return this.client.request("POST", `/v2/tools/${encodeURIComponent(toolName)}`, { body: params ?? {} });
+  async run(toolName, params, options) {
+    const { autoConfirm = true } = options ?? {};
+    const endpoint = `/v2/tools/${encodeURIComponent(toolName)}`;
+    try {
+      return await this.client.request("POST", endpoint, {
+        body: params ?? {}
+      });
+    } catch (error) {
+      if (autoConfirm && error instanceof LumailConfirmationRequiredError) {
+        return this.client.request("POST", endpoint, {
+          body: { ...params, confirmationCode: error.confirmationCode }
+        });
+      }
+      throw error;
+    }
   }
 }
 
@@ -327,6 +359,7 @@ export {
   LumailPaymentRequiredError,
   LumailNotFoundError,
   LumailError,
+  LumailConfirmationRequiredError,
   LumailAuthenticationError,
   Lumail
 };

package/dist/resources/campaigns.d.ts

@@ -0,0 +1,12 @@
+import type { LumailClient } from "../client";
+import type { CreateCampaignParams, CreateCampaignResponse, DeleteCampaignResponse, GetCampaignResponse, ListCampaignsParams, ListCampaignsResponse, SendCampaignParams, SendCampaignResponse, UpdateCampaignParams, UpdateCampaignResponse } from "../types";
+export declare class Campaigns {
+    private readonly client;
+    constructor(client: LumailClient);
+    list(params?: ListCampaignsParams): Promise<ListCampaignsResponse>;
+    create(params: CreateCampaignParams): Promise<CreateCampaignResponse>;
+    get(campaignId: string): Promise<GetCampaignResponse>;
+    update(campaignId: string, params: UpdateCampaignParams): Promise<UpdateCampaignResponse>;
+    delete(campaignId: string): Promise<DeleteCampaignResponse>;
+    send(campaignId: string, params?: SendCampaignParams): Promise<SendCampaignResponse>;
+}

package/dist/resources/emails.d.ts

@@ -0,0 +1,8 @@
+import type { LumailClient } from "../client";
+import type { SendEmailParams, SendEmailResponse, VerifyEmailParams, VerifyEmailResponse } from "../types";
+export declare class Emails {
+    private readonly client;
+    constructor(client: LumailClient);
+    send(params: SendEmailParams): Promise<SendEmailResponse>;
+    verify(params: VerifyEmailParams): Promise<VerifyEmailResponse>;
+}

package/dist/resources/events.d.ts

@@ -0,0 +1,7 @@
+import type { LumailClient } from "../client";
+import type { CreateEventParams, CreateEventResponse } from "../types";
+export declare class Events {
+    private readonly client;
+    constructor(client: LumailClient);
+    create(params: CreateEventParams): Promise<CreateEventResponse>;
+}

package/dist/resources/subscribers.d.ts

@@ -0,0 +1,15 @@
+import type { LumailClient } from "../client";
+import type { AddTagsResponse, CreateSubscriberParams, CreateSubscriberResponse, DeleteSubscriberResponse, GetSubscriberResponse, ListEventsParams, ListEventsResponse, ListSubscribersParams, ListSubscribersResponse, RemoveTagsResponse, UnsubscribeResponse, UpdateSubscriberParams, UpdateSubscriberResponse } from "../types";
+export declare class Subscribers {
+    private readonly client;
+    constructor(client: LumailClient);
+    list(params?: ListSubscribersParams): Promise<ListSubscribersResponse>;
+    create(params: CreateSubscriberParams): Promise<CreateSubscriberResponse>;
+    get(idOrEmail: string): Promise<GetSubscriberResponse>;
+    update(idOrEmail: string, params: UpdateSubscriberParams): Promise<UpdateSubscriberResponse>;
+    delete(idOrEmail: string): Promise<DeleteSubscriberResponse>;
+    unsubscribe(idOrEmail: string): Promise<UnsubscribeResponse>;
+    addTags(idOrEmail: string, tags: string[]): Promise<AddTagsResponse>;
+    removeTags(idOrEmail: string, tags: string[]): Promise<RemoveTagsResponse>;
+    listEvents(idOrEmail: string, params?: ListEventsParams): Promise<ListEventsResponse>;
+}

package/dist/resources/tags.d.ts

@@ -0,0 +1,10 @@
+import type { LumailClient } from "../client";
+import type { CreateTagParams, CreateTagResponse, GetTagResponse, ListTagsResponse, UpdateTagParams, UpdateTagResponse } from "../types";
+export declare class Tags {
+    private readonly client;
+    constructor(client: LumailClient);
+    list(): Promise<ListTagsResponse>;
+    create(params: CreateTagParams): Promise<CreateTagResponse>;
+    get(idOrName: string): Promise<GetTagResponse>;
+    update(idOrName: string, params: UpdateTagParams): Promise<UpdateTagResponse>;
+}

package/dist/resources/tools.d.ts

@@ -0,0 +1,12 @@
+import type { LumailClient } from "../client";
+import type { GetToolResponse, ListToolsResponse, RunToolResponse } from "../types";
+export type RunToolOptions = {
+    autoConfirm?: boolean;
+};
+export declare class Tools {
+    private readonly client;
+    constructor(client: LumailClient);
+    list(): Promise<ListToolsResponse>;
+    get(toolName: string): Promise<GetToolResponse>;
+    run<T = unknown>(toolName: string, params?: Record<string, unknown>, options?: RunToolOptions): Promise<RunToolResponse<T>>;
+}

package/dist/types.d.ts

@@ -0,0 +1,327 @@
+export type LumailOptions = {
+    apiKey: string;
+    baseUrl?: string;
+};
+export type RequestOptions = {
+    params?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    signal?: AbortSignal;
+};
+export type SubscriberStatus = "PENDING_CONFIRMATION" | "SUBSCRIBED" | "UNSUBSCRIBED" | "BOUNCED" | "BANNED" | "COMPLAINED";
+export type SubscriberTag = {
+    id: string;
+    name: string;
+};
+export type Subscriber = {
+    id: string;
+    email: string;
+    name: string | null;
+    phone: string | null;
+    status: SubscriberStatus;
+    tags: SubscriberTag[];
+    fields: Record<string, string>;
+    createdAt?: string;
+    updatedAt?: string;
+};
+export type ListSubscribersParams = {
+    tag?: string;
+    status?: SubscriberStatus | "all";
+    limit?: number;
+    cursor?: string;
+    query?: string;
+};
+export type ListSubscriberEntry = {
+    id: string;
+    email: string;
+    name: string | null;
+    status: SubscriberStatus;
+    createdAt: string;
+    tags: SubscriberTag[];
+};
+export type ListSubscribersResponse = {
+    success: true;
+    subscribers: ListSubscriberEntry[];
+    total: number;
+    limit: number;
+    nextCursor: string | null;
+};
+export type CreateSubscriberParams = {
+    email: string;
+    name?: string | null;
+    phone?: string | null;
+    tags?: string[];
+    fields?: Record<string, string | null>;
+    replaceTags?: boolean;
+    resubscribe?: boolean;
+    triggerWorkflows?: boolean;
+    ipAddress?: string;
+    country?: string;
+};
+export type UpdateSubscriberParams = Omit<CreateSubscriberParams, "email"> & {
+    email?: string;
+};
+export type CreateSubscriberResponse = {
+    success: true;
+    subscriber: Subscriber;
+    warnings?: string[];
+};
+export type GetSubscriberResponse = {
+    success: true;
+    subscriber: Subscriber;
+};
+export type UpdateSubscriberResponse = {
+    success: true;
+    subscriber: Subscriber;
+    warnings?: string[];
+};
+export type DeleteSubscriberResponse = {
+    success: true;
+    message: string;
+};
+export type UnsubscribeResponse = {
+    success: true;
+    message: string;
+    subscriber: {
+        id: string;
+        email: string;
+        status: SubscriberStatus;
+    };
+};
+export type AddTagsResponse = {
+    success: true;
+    added: number;
+    tags: SubscriberTag[];
+};
+export type RemoveTagsResponse = {
+    success: true;
+    removed: number;
+    tags?: SubscriberTag[];
+    message?: string;
+};
+export type SubscriberEventType = "SUBSCRIBED" | "UNSUBSCRIBED" | "TAG_ADDED" | "TAG_REMOVED" | "EMAIL_OPENED" | "EMAIL_CLICKED" | "EMAIL_SENT" | "EMAIL_RECEIVED" | "WORKFLOW_STARTED" | "WORKFLOW_COMPLETED" | "WORKFLOW_CANCELED" | "FIELD_UPDATED" | "EMAIL_BOUNCED" | "EMAIL_COMPLAINED" | "WEBHOOK_EXECUTED" | "SUBSCRIBER_PAYMENT" | "SUBSCRIBER_REFUND";
+export type SubscriberEvent = {
+    id: string;
+    eventType: SubscriberEventType;
+    data: Record<string, unknown> | null;
+    subscriberId: string;
+    createdAt: string;
+    subscriber: {
+        id: string;
+        email: string;
+        name: string | null;
+    };
+};
+export type ListEventsParams = {
+    cursor?: string;
+    take?: number;
+    eventTypes?: SubscriberEventType[];
+    order?: "asc" | "desc";
+    startDate?: string;
+    endDate?: string;
+    search?: string;
+};
+export type ListEventsResponse = {
+    events: SubscriberEvent[];
+    nextCursor: string | null;
+};
+export type CampaignStatus = "DRAFT" | "ARCHIVED" | "SCHEDULED" | "SENDING" | "SENT" | "FAILED";
+export type ContentType = "MAILY" | "PLATE" | "MARKDOWN";
+export type CampaignSummary = {
+    id: string;
+    campaignId: string;
+    name: string;
+    subject: string;
+    preview: string | null;
+    status: CampaignStatus;
+    contentType: ContentType;
+    sendAt: string | null;
+    scheduledAt: string | null;
+    recipientCount: number;
+    emailsSentCount: number;
+    emailsOpenedCount: number;
+    emailsClickedCount: number;
+    createdAt: string;
+    updatedAt: string;
+};
+export type CampaignSender = {
+    id: string;
+    name: string;
+    displayName: string;
+    localPart: string;
+    replyTo: string | null;
+    domain: {
+        domain: string;
+    };
+};
+export type Campaign = CampaignSummary & {
+    content: unknown;
+    replyTo: string | null;
+    senderId: string;
+    timezone: string | null;
+    recipientFilters: unknown[];
+    sender: CampaignSender;
+};
+export type ListCampaignsParams = {
+    status?: "all" | "DRAFT" | "ARCHIVED" | "SCHEDULED" | "SENT";
+    page?: number;
+    limit?: number;
+    query?: string;
+    sortBy?: "name" | "name_desc";
+};
+export type ListCampaignsResponse = {
+    success: true;
+    campaigns: CampaignSummary[];
+    total: number;
+    page: number;
+    limit: number;
+    pageCount: number;
+};
+export type CreateCampaignParams = {
+    subject: string;
+    name?: string;
+    preview?: string | null;
+    content?: unknown;
+    contentType?: ContentType;
+    senderId?: string;
+    replyTo?: string | null;
+};
+export type CreateCampaignResponse = {
+    success: true;
+    campaign: CampaignSummary & {
+        content: unknown;
+        replyTo: string | null;
+        senderId: string;
+    };
+    campaignId: string;
+};
+export type GetCampaignResponse = {
+    success: true;
+    campaign: Campaign;
+    campaignId: string;
+};
+export type UpdateCampaignParams = Partial<CreateCampaignParams>;
+export type UpdateCampaignResponse = CreateCampaignResponse;
+export type DeleteCampaignResponse = {
+    success: true;
+    deleted: true;
+    campaignId: string;
+};
+export type SendCampaignParams = {
+    scheduledAt?: string;
+    timezone?: string;
+};
+export type SendCampaignResponse = {
+    success: true;
+    campaign: {
+        id: string;
+        campaignId: string;
+        status: "SCHEDULED" | "SENDING";
+        scheduledAt: string;
+        timezone: string;
+    };
+    campaignId: string;
+};
+export type EmailContentType = "MARKDOWN" | "HTML" | "TIPTAP";
+export type SendEmailParams = {
+    to: string;
+    from: string;
+    subject: string;
+    content: string;
+    contentType?: EmailContentType;
+    preview?: string;
+    replyTo?: string;
+    transactional?: boolean;
+    tracking?: {
+        links?: boolean;
+        open?: boolean;
+    };
+};
+export type SendEmailResponse = {
+    success: true;
+    message: string;
+    qstashMessageId: string;
+};
+export type VerifyEmailParams = {
+    email: string;
+};
+export type VerifyEmailResponse = {
+    success: boolean;
+    error?: string;
+    code?: string;
+    suggestion?: string;
+    warnings?: string[];
+};
+export type Tag = {
+    id: string;
+    name: string;
+};
+export type TagWithCount = Tag & {
+    subscribersCount: number;
+};
+export type ListTagsResponse = {
+    success: true;
+    tags: Tag[];
+};
+export type CreateTagParams = {
+    name: string;
+};
+export type CreateTagResponse = {
+    success: true;
+    tag: Tag;
+};
+export type GetTagResponse = {
+    tag: TagWithCount;
+};
+export type UpdateTagParams = {
+    name: string;
+};
+export type UpdateTagResponse = {
+    success: true;
+    tag: Tag;
+};
+export type CreateEventParams = {
+    eventType: SubscriberEventType;
+    subscriber: string;
+    data: Record<string, unknown>;
+};
+export type CreateEventResponse = {
+    success: true;
+    event: {
+        id: string;
+        eventType: SubscriberEventType;
+        data: Record<string, unknown>;
+        subscriberId: string;
+        organizationId: string;
+        createdAt: string;
+    };
+};
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    category?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+};
+export type ListToolsResponse = {
+    success: true;
+    total: number;
+    tools: ToolDefinition[];
+    grouped: Record<string, ToolDefinition[]>;
+    docs: string;
+};
+export type GetToolResponse = {
+    success: true;
+    tool: ToolDefinition;
+};
+export type RunToolResponse<T = unknown> = {
+    success: true;
+    data: T;
+};
+export type ConfirmationRequiredResponse = {
+    success: false;
+    error: "CONFIRMATION_REQUIRED";
+    message: string;
+    action: string;
+    confirmationCode: number;
+    instruction: string;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumail",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lumail SDK and CLI - email marketing platform",
   "author": "Melvyn",
   "license": "MIT",
@@ -9,6 +9,10 @@
     "url": "https://github.com/Melvynx/lumail.io.git",
     "directory": "packages/lumail"
   },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
   "type": "module",
   "bin": {
     "lumail": "./dist/cli.js"
@@ -23,7 +27,7 @@
     }
   },
   "scripts": {
-    "build": "bun run build.ts",
+    "build": "rm -rf dist && bun run build.ts && tsc -p tsconfig.build.json",
     "release": "release-it",
     "prepublishOnly": "bun run build"
   },