mailtea-sdk 0.1.1

package/dist/index.js

@@ -0,0 +1,671 @@
+// src/resource.ts
+function query(params) {
+  const entries = Object.entries(params).filter(
+    ([, v]) => v !== void 0 && v !== null && v !== ""
+  );
+  if (entries.length === 0) return "";
+  return "?" + entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+}
+
+// src/inbound.ts
+var InboundAttachments = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /** List an inbound email's attachments, each with a signed download URL. */
+  list(id) {
+    return this.request(
+      "GET",
+      `/v1/emails/inbound/${encodeURIComponent(id)}/attachments`
+    );
+  }
+  /** Retrieve a single inbound attachment with a signed download URL. */
+  get(id, attachmentId) {
+    return this.request(
+      "GET",
+      `/v1/emails/inbound/${encodeURIComponent(id)}/attachments/${encodeURIComponent(attachmentId)}`
+    );
+  }
+};
+var InboundEmails = class {
+  constructor(request) {
+    this.request = request;
+    this.attachments = new InboundAttachments(request);
+  }
+  /** Attachments on a received email. */
+  attachments;
+  /** List received emails in a publication (most recent first), cursor-paginated. */
+  list(params) {
+    return this.request(
+      "GET",
+      `/v1/emails/inbound${query({ ...params })}`
+    );
+  }
+  /** Retrieve a single received email, including its body, headers, and attachments. */
+  get(id) {
+    return this.request(
+      "GET",
+      `/v1/emails/inbound/${encodeURIComponent(id)}`
+    );
+  }
+  /**
+   * Reply to a received email. The reply target, threading headers, and the
+   * `Re: ` subject default are all server-derived — pass only the content.
+   *
+   * @returns the resulting transactional email's `id` and `status` (HTTP 202).
+   */
+  reply(id, input) {
+    return this.request(
+      "POST",
+      `/v1/emails/inbound/${encodeURIComponent(id)}/reply`,
+      input
+    );
+  }
+};
+
+// src/emails.ts
+var Emails = class {
+  constructor(request) {
+    this.request = request;
+    this.inbound = new InboundEmails(request);
+  }
+  /** Inbound (received) emails: list, get, reply, and attachments. */
+  inbound;
+  /**
+   * Send a transactional email.
+   *
+   * Provide either inline content (`html` and/or `text`) **or** a `template`
+   * reference — not both. `to`, `cc`, `bcc`, and `reply_to` each accept a single
+   * address or an array.
+   *
+   * @returns the new email's `id`.
+   */
+  async send(payload) {
+    return this.request("POST", "/v1/emails", payload);
+  }
+  /**
+   * Send up to 100 emails in a single request. Batch items do not support
+   * `attachments` or `scheduled_at`.
+   *
+   * @returns `{ data: [{ id }, ...] }` in request order.
+   */
+  async batch(payload) {
+    return this.request(
+      "POST",
+      "/v1/emails/batch",
+      payload
+    );
+  }
+  /**
+   * List transactional emails (most recent first), optionally filtered by
+   * status, tags, or a `created_at` date range, and offset-paginated.
+   *
+   * @returns `{ data, total, limit, offset, has_more }`.
+   */
+  async list(params = {}) {
+    return this.request("GET", `/v1/emails${query({ ...params })}`);
+  }
+  /**
+   * Aggregate transactional metrics over an optional date window: totals,
+   * delivered/bounced/open/click counts, per-status counts, and rates.
+   */
+  async analytics(params = {}) {
+    return this.request("GET", `/v1/emails/analytics${query({ ...params })}`);
+  }
+  /**
+   * Retrieve a single email with its current delivery status and tracking
+   * counters. The returned object exposes both `last_event` (the raw wire field)
+   * and a friendly `status` alias.
+   */
+  async get(id) {
+    const email = await this.request(
+      "GET",
+      `/v1/emails/${encodeURIComponent(id)}`
+    );
+    return { ...email, status: email.status ?? email.last_event ?? null };
+  }
+  /**
+   * Update a scheduled email — currently only its `scheduled_at`. Only emails
+   * still in the `scheduled` state can be updated.
+   */
+  async update(id, payload) {
+    return this.request(
+      "PATCH",
+      `/v1/emails/${encodeURIComponent(id)}`,
+      payload
+    );
+  }
+  /**
+   * Convenience wrapper over {@link Emails.update} for the common reschedule
+   * case.
+   *
+   * @param scheduledAt ISO 8601 datetime string.
+   */
+  async reschedule(id, scheduledAt) {
+    return this.update(id, { scheduled_at: scheduledAt });
+  }
+  /** Cancel a scheduled email before it sends. */
+  async cancel(id) {
+    return this.request(
+      "POST",
+      `/v1/emails/${encodeURIComponent(id)}/cancel`
+    );
+  }
+};
+
+// src/contacts.ts
+var Contacts = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /** Create (or upsert) a contact in a publication. */
+  create(input) {
+    return this.request("POST", "/v1/contacts", input);
+  }
+  /** List contacts in a publication. Supports cursor pagination via `after`. */
+  list(params) {
+    return this.request(
+      "GET",
+      `/v1/contacts${query({ ...params })}`
+    );
+  }
+  /** Retrieve a single contact by id or email. */
+  get(idOrEmail, params) {
+    return this.request(
+      "GET",
+      `/v1/contacts/${encodeURIComponent(idOrEmail)}${query({ ...params })}`
+    );
+  }
+  /** Update a contact's status. */
+  update(idOrEmail, input) {
+    return this.request(
+      "PATCH",
+      `/v1/contacts/${encodeURIComponent(idOrEmail)}${query({ publication_id: input.publication_id })}`,
+      input
+    );
+  }
+  /** Delete a contact by id or email. */
+  delete(idOrEmail, params) {
+    return this.request(
+      "DELETE",
+      `/v1/contacts/${encodeURIComponent(idOrEmail)}${query({ ...params })}`
+    );
+  }
+};
+
+// src/segments.ts
+var Segments = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /** Create a segment. */
+  create(input) {
+    return this.request("POST", "/v1/segments", input);
+  }
+  /** List segments in a publication. */
+  list(params) {
+    return this.request(
+      "GET",
+      `/v1/segments${query({ ...params })}`
+    );
+  }
+  /** Retrieve a single segment. */
+  get(id, params) {
+    return this.request(
+      "GET",
+      `/v1/segments/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+  /** Update a segment. */
+  update(id, input) {
+    return this.request(
+      "PATCH",
+      `/v1/segments/${encodeURIComponent(id)}${query({ publication_id: input.publication_id })}`,
+      input
+    );
+  }
+  /** Delete a segment. */
+  delete(id, params) {
+    return this.request(
+      "DELETE",
+      `/v1/segments/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+};
+
+// src/tags.ts
+var Tags = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /** Create a tag. */
+  create(input) {
+    return this.request("POST", "/v1/tags", input);
+  }
+  /** List tags in a publication. */
+  list(params) {
+    return this.request(
+      "GET",
+      `/v1/tags${query({ ...params })}`
+    );
+  }
+  /** Retrieve a single tag. */
+  get(id, params) {
+    return this.request(
+      "GET",
+      `/v1/tags/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+  /** Update a tag. */
+  update(id, input) {
+    return this.request(
+      "PATCH",
+      `/v1/tags/${encodeURIComponent(id)}${query({ publication_id: input.publication_id })}`,
+      input
+    );
+  }
+  /** Delete a tag. */
+  delete(id, params) {
+    return this.request(
+      "DELETE",
+      `/v1/tags/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+};
+
+// src/posts.ts
+var Posts = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Create a newsletter post (draft by default). Seed it from a published
+   * server template with `template_id` + `variables`, or pass inline `html`.
+   * Set `send: true` to deliver immediately (or with `scheduled_at` to
+   * schedule) — that requires the `issues:send` scope. Returns `{ id }`.
+   */
+  create(input) {
+    return this.request("POST", "/v1/posts", input);
+  }
+  /**
+   * Send a TEST copy of a post to specific recipients to check it before
+   * subscribers see it. Renders the post exactly as a subscriber would receive
+   * it and delivers a one-shot `[TEST]` email — it does NOT send to the
+   * audience. Returns `{ sent_to, failed_to }`.
+   */
+  sendTest(id, input) {
+    return this.request(
+      "POST",
+      `/v1/posts/${encodeURIComponent(id)}/test`,
+      input
+    );
+  }
+};
+
+// src/domains.ts
+var TrackingDomains = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /** Add a tracking sub-domain. The response `records` lists the CNAME to add. */
+  create(domainId, input) {
+    return this.request(
+      "POST",
+      `/v1/domains/${encodeURIComponent(domainId)}/tracking-domains${query({ publication_id: input.publication_id })}`,
+      { subdomain: input.subdomain }
+    );
+  }
+  /** List tracking sub-domains for a domain. */
+  list(domainId, params) {
+    return this.request(
+      "GET",
+      `/v1/domains/${encodeURIComponent(domainId)}/tracking-domains${query({ ...params })}`
+    );
+  }
+  /** Verify a tracking sub-domain by checking its CNAME record. */
+  verify(domainId, trackingDomainId, params) {
+    return this.request(
+      "POST",
+      `/v1/domains/${encodeURIComponent(domainId)}/tracking-domains/${encodeURIComponent(trackingDomainId)}/verify${query({ ...params })}`
+    );
+  }
+  /** Delete a tracking sub-domain. */
+  delete(domainId, trackingDomainId, params) {
+    return this.request(
+      "DELETE",
+      `/v1/domains/${encodeURIComponent(domainId)}/tracking-domains/${encodeURIComponent(trackingDomainId)}${query({ ...params })}`
+    );
+  }
+};
+var Domains = class {
+  constructor(request) {
+    this.request = request;
+    this.tracking = new TrackingDomains(request);
+  }
+  /** Tracking sub-domains (CNAME) under a domain. */
+  tracking;
+  /** Register a domain. The response `records` lists the DNS records to add. */
+  create(input) {
+    return this.request("POST", "/v1/domains", input);
+  }
+  /** List domains in a publication. */
+  list(params) {
+    return this.request(
+      "GET",
+      `/v1/domains${query({ ...params })}`
+    );
+  }
+  /** Retrieve a single domain, including its DNS `records`. */
+  get(id, params) {
+    return this.request(
+      "GET",
+      `/v1/domains/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+  /** Verify a domain by checking its DNS records; `status` becomes `verified`. */
+  verify(id, params) {
+    return this.request(
+      "POST",
+      `/v1/domains/${encodeURIComponent(id)}/verify${query({ ...params })}`
+    );
+  }
+  /** Update a domain's purpose, primary flag, or proxy target. */
+  update(id, input) {
+    return this.request(
+      "PATCH",
+      `/v1/domains/${encodeURIComponent(id)}${query({ publication_id: input.publication_id })}`,
+      input
+    );
+  }
+  /** Delete a domain. */
+  delete(id, params) {
+    return this.request(
+      "DELETE",
+      `/v1/domains/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+};
+
+// src/webhooks.ts
+var BASE = "/v1/webhooks/endpoints";
+var Webhooks = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /** Create a webhook. The response `signing_secret` is returned only once. */
+  create(input) {
+    return this.request("POST", BASE, input);
+  }
+  /** List webhooks in a publication (signing secrets omitted). */
+  list(params) {
+    return this.request(
+      "GET",
+      `${BASE}${query({ ...params })}`
+    );
+  }
+  /** Retrieve a single webhook. */
+  get(id, params) {
+    return this.request(
+      "GET",
+      `${BASE}/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+  /** Update a webhook's endpoint, events, or enabled/disabled status. */
+  update(id, input) {
+    return this.request(
+      "PATCH",
+      `${BASE}/${encodeURIComponent(id)}${query({ publication_id: input.publication_id })}`,
+      input
+    );
+  }
+  /** Delete a webhook. */
+  delete(id, params) {
+    return this.request(
+      "DELETE",
+      `${BASE}/${encodeURIComponent(id)}${query({ ...params })}`
+    );
+  }
+};
+
+// src/contact-properties.ts
+var ContactProperties = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /** Define a custom contact property. */
+  create(input) {
+    return this.request("POST", "/v1/contact-properties", input);
+  }
+  /** List the team's custom contact property definitions. */
+  list(params = {}) {
+    return this.request(
+      "GET",
+      `/v1/contact-properties${query({ ...params })}`
+    );
+  }
+  /** Update a property's fallback value or description. */
+  update(id, input) {
+    return this.request(
+      "PATCH",
+      `/v1/contact-properties/${encodeURIComponent(id)}`,
+      input
+    );
+  }
+  /** Delete a custom contact property. */
+  delete(id) {
+    return this.request(
+      "DELETE",
+      `/v1/contact-properties/${encodeURIComponent(id)}`
+    );
+  }
+};
+
+// src/api-keys.ts
+var ApiKeys = class {
+  constructor(request) {
+    this.request = request;
+  }
+  /**
+   * Create an API key. The `token` is returned ONCE — store it securely. The
+   * calling token must already hold every scope the new key would grant.
+   */
+  create(input) {
+    return this.request("POST", "/v1/api-keys", input);
+  }
+  /** List API keys (token values are never returned). */
+  list() {
+    return this.request("GET", "/v1/api-keys");
+  }
+  /** Revoke (delete) an API key by id. */
+  revoke(id) {
+    return this.request("DELETE", `/v1/api-keys/${encodeURIComponent(id)}`);
+  }
+};
+
+// src/errors.ts
+var MailteaError = class _MailteaError extends Error {
+  status;
+  code;
+  details;
+  requestId;
+  constructor(message, init) {
+    super(message);
+    this.name = "MailteaError";
+    this.status = init.status;
+    this.code = init.code;
+    this.details = init.details;
+    this.requestId = init.requestId;
+    Object.setPrototypeOf(this, _MailteaError.prototype);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.mailtea.app";
+function readEnvApiKey() {
+  if (typeof process !== "undefined" && process.env) {
+    return process.env.MAILTEA_API_KEY;
+  }
+  return void 0;
+}
+var Mailtea = class {
+  /** The `emails` resource: send, batch, get, update, reschedule, cancel. */
+  emails;
+  /** The `contacts` resource: create, list, get, update, delete. */
+  contacts;
+  /** The `segments` resource: create, list, get, update, delete. */
+  segments;
+  /** The `tags` resource: create, list, get, update, delete. */
+  tags;
+  /** The `posts` resource: sendTest (newsletter posts). */
+  posts;
+  /** The `domains` resource: create, list, get, verify, update, delete. */
+  domains;
+  /** The `webhooks` resource: create, list, get, update, delete. */
+  webhooks;
+  /** The `contactProperties` resource: create, list, update, delete. */
+  contactProperties;
+  /** The `apiKeys` resource: create, list, revoke. */
+  apiKeys;
+  apiKey;
+  baseUrl;
+  fetchImpl;
+  constructor(apiKeyOrOptions, maybeOptions) {
+    const options = typeof apiKeyOrOptions === "string" ? { ...maybeOptions, apiKey: apiKeyOrOptions } : apiKeyOrOptions ?? maybeOptions ?? {};
+    const apiKey = options.apiKey ?? readEnvApiKey();
+    if (!apiKey) {
+      throw new MailteaError(
+        "Missing Mailtea API key. Pass it to `new Mailtea(apiKey)` or set the MAILTEA_API_KEY environment variable.",
+        { status: 0, code: "missing_api_key" }
+      );
+    }
+    const resolvedFetch = options.fetch ?? globalThis.fetch;
+    if (typeof resolvedFetch !== "function") {
+      throw new MailteaError(
+        "No global `fetch` is available. Use Node.js 18+ (or Bun/Deno), or pass a `fetch` implementation in the Mailtea options.",
+        { status: 0, code: "missing_fetch" }
+      );
+    }
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchImpl = resolvedFetch;
+    const request = this.request.bind(this);
+    this.emails = new Emails(request);
+    this.contacts = new Contacts(request);
+    this.segments = new Segments(request);
+    this.tags = new Tags(request);
+    this.posts = new Posts(request);
+    this.domains = new Domains(request);
+    this.webhooks = new Webhooks(request);
+    this.contactProperties = new ContactProperties(request);
+    this.apiKeys = new ApiKeys(request);
+  }
+  /** @internal Issue an authenticated request and map errors to MailteaError. */
+  async request(method, path, body) {
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    });
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    if (!response.ok) {
+      let message = `${response.status} ${response.statusText}`.trim();
+      let details;
+      try {
+        const errorBody = await response.json();
+        if (errorBody?.error) message = errorBody.error;
+        details = errorBody?.details;
+      } catch {
+      }
+      throw new MailteaError(message, {
+        status: response.status,
+        details,
+        requestId
+      });
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : void 0;
+  }
+};
+
+// src/webhook-signing.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var SECRET_PREFIX = "whsec_";
+var SIGNATURE_VERSION = "v1";
+function decodeSigningKey(secret) {
+  const raw = secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret;
+  return Buffer.from(raw, "base64");
+}
+function computeSignature(input) {
+  const timestampSeconds = Math.floor(input.timestamp);
+  const signedContent = `${input.msgId}.${timestampSeconds}.${input.payload}`;
+  const key = decodeSigningKey(input.secret);
+  const digest = createHmac("sha256", key).update(signedContent, "utf8").digest("base64");
+  return digest;
+}
+function signWebhook(input) {
+  return `${SIGNATURE_VERSION},${computeSignature(input)}`;
+}
+function safeEqual(a, b) {
+  const bufA = Buffer.from(a, "utf8");
+  const bufB = Buffer.from(b, "utf8");
+  if (bufA.length !== bufB.length) {
+    return false;
+  }
+  return timingSafeEqual(bufA, bufB);
+}
+function verifyWebhookSignature(input) {
+  const tolerance = input.toleranceSeconds ?? 300;
+  const nowSeconds = input.now ?? Math.floor(Date.now() / 1e3);
+  const timestampSeconds = Math.floor(input.timestamp);
+  if (!Number.isFinite(timestampSeconds)) {
+    return false;
+  }
+  if (Math.abs(nowSeconds - timestampSeconds) > tolerance) {
+    return false;
+  }
+  const expected = computeSignature({
+    secret: input.secret,
+    msgId: input.msgId,
+    timestamp: timestampSeconds,
+    payload: input.payload
+  });
+  const tokens = input.signatureHeader.split(" ").filter(Boolean);
+  for (const token of tokens) {
+    const commaIndex = token.indexOf(",");
+    if (commaIndex === -1) {
+      continue;
+    }
+    const version = token.slice(0, commaIndex);
+    const signature = token.slice(commaIndex + 1);
+    if (version === SIGNATURE_VERSION && safeEqual(signature, expected)) {
+      return true;
+    }
+  }
+  return false;
+}
+export {
+  ApiKeys,
+  ContactProperties,
+  Contacts,
+  Domains,
+  Emails,
+  InboundAttachments,
+  InboundEmails,
+  Mailtea,
+  MailteaError,
+  Posts,
+  Segments,
+  Tags,
+  Webhooks,
+  signWebhook,
+  verifyWebhookSignature
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mailtea-sdk",
+  "version": "0.1.1",
+  "description": "Mailtea Node.js SDK — send, schedule, and manage email, contacts, and segments from your app or AI agent.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "mailtea",
+    "email",
+    "newsletter",
+    "transactional-email",
+    "sdk",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mailtea-app/mailtea-node.git"
+  },
+  "homepage": "https://mailtea.app",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.8.2",
+    "@mailtea/contracts": "0.1.0"
+  },
+  "scripts": {
+    "dev": "tsup src/index.ts --watch --format esm --dts",
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"No lint for mailtea yet\"",
+    "test": "tsx --test src/*.test.ts"
+  }
+}