@nanbon/fetan 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @nanbon/fetan
+
+Official Node.js SDK for the [Fetan](https://fetan.et) transactional email API. Zero dependencies, full TypeScript types, automatic retries.
+
+## Install
+
+```bash
+npm install @nanbon/fetan
+```
+
+## Quickstart
+
+```ts
+import { Mailer } from "@nanbon/fetan";
+
+const mailer = new Mailer("em_live_xxxxxxxx", {
+  baseUrl: "https://mail.example.com", // your Fetan deployment
+});
+
+const { id, status } = await mailer.emails.send({
+  from: "hello@yourdomain.com",
+  to: "customer@example.com",
+  subject: "ሰላም from Fetan",
+  html: "<strong>It works!</strong>",
+});
+```
+
+## Emails
+
+```ts
+// Send with everything
+await mailer.emails.send({
+  from: "billing@yourdomain.com",
+  to: ["a@example.com", "b@example.com"],
+  cc: "manager@example.com",
+  reply_to: "support@yourdomain.com",
+  subject: "Your invoice",
+  html: "<p>…</p>",
+  text: "…",
+  tags: { kind: "invoice" },
+  scheduled_at: "2026-10-15T09:00:00Z",
+  attachments: [{ filename: "invoice.pdf", content: "<base64>" }],
+}, { idempotencyKey: "invoice-1234" }); // safe to retry
+
+// Templates
+await mailer.emails.send({
+  from: "hello@yourdomain.com",
+  to: "user@example.com",
+  subject: "Welcome",
+  template_id: "tpl_...",
+  variables: { name: "Abebe" },
+});
+
+// Read & manage
+const email = await mailer.emails.get(id);
+const { emails, total } = await mailer.emails.list({ status: "bounced", limit: 50 });
+await mailer.emails.cancel(id); // only while still queued
+
+// Batch (up to 100)
+await mailer.batch.send([{ from, to, subject, html }, ...]);
+```
+
+## Domains, keys, templates, webhooks
+
+```ts
+const domain = await mailer.domains.create("yourdomain.com");
+const checked = await mailer.domains.verify(domain.id); // live DNS check
+
+const key = await mailer.apiKeys.create({ name: "prod", permission: "sending_only" });
+console.log(key.key); // shown once — store it
+
+const tpl = await mailer.templates.create({ name: "OTP", subject: "Your code", html: "<p>{{code}}</p>" });
+
+const hook = await mailer.webhooks.create({
+  url: "https://yourapp.com/hooks/fetan",
+  events: ["email.delivered", "email.bounced"],
+});
+```
+
+## Errors
+
+All failures throw `FetanError` with a machine-readable `code`:
+
+```ts
+import { FetanError } from "@nanbon/fetan";
+
+try {
+  await mailer.emails.send({ from: "a@unverified.com", to: "b@c.com", subject: "x", html: "x" });
+} catch (err) {
+  if (err instanceof FetanError && err.code === "domain_not_verified") {
+    // err.message → "The domain unverified.com is not verified yet"
+  }
+}
+```
+
+Codes: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `domain_not_verified`, `rate_limited`, `conflict`, `server_error`, `network_error`.
+
+Network errors and 5xx responses are retried automatically (exponential backoff, 3 attempts by default — configurable via `maxRetries`).
+
+## Build
+
+```bash
+npm install
+npm run build   # outputs dist/
+```

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Fetan — official Node.js SDK for the Fetan transactional email API.
+ * Zero dependencies; uses the global fetch (Node 18+).
+ */
+export interface FetanOptions {
+    /** Base URL of your Fetan deployment, e.g. https://mail.example.com */
+    baseUrl?: string;
+    /** Max automatic retries for network errors and 5xx responses. Default 3. */
+    maxRetries?: number;
+    /** Request timeout in milliseconds. Default 15000. */
+    timeoutMs?: number;
+}
+export type EmailStatus = "queued" | "sent" | "delivered" | "bounced" | "failed" | "complained" | "cancelled";
+export interface Attachment {
+    filename: string;
+    /** Base64-encoded file content */
+    content: string;
+    content_type?: string;
+}
+export interface SendEmailParams {
+    from: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    reply_to?: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    headers?: Record<string, string>;
+    attachments?: Attachment[];
+    /** ISO 8601 datetime to schedule the email for later */
+    scheduled_at?: string;
+    tags?: Record<string, string>;
+    template_id?: string;
+    variables?: Record<string, string>;
+}
+export interface Email {
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    reply_to: string[];
+    subject: string;
+    html: string | null;
+    text: string | null;
+    status: EmailStatus;
+    scheduled_at: string | null;
+    tags: Record<string, string>;
+    template_id: string | null;
+    variables: Record<string, string>;
+    bounce_reason: string | null;
+    attempts: number;
+    last_error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface SendEmailResponse {
+    id: string;
+    status: EmailStatus;
+}
+export interface BatchSendResponse {
+    ids: string[];
+    count: number;
+}
+export interface ListEmailsParams {
+    status?: EmailStatus;
+    domain?: string;
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface Domain {
+    id: string;
+    name: string;
+    status: "pending" | "verified" | "failed";
+    records: {
+        type: string;
+        name: string;
+        value: string;
+        status: string;
+    }[];
+    created_at: string;
+}
+export interface ApiKey {
+    id: string;
+    name: string;
+    prefix: string;
+    permission: "full_access" | "sending_only";
+    domain_id: string | null;
+    last_used_at: string | null;
+    created_at: string;
+}
+export interface Template {
+    id: string;
+    name: string;
+    subject: string;
+    html: string;
+    variables: string[];
+    version: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface Webhook {
+    id: string;
+    url: string;
+    events: string[];
+    active: boolean;
+    created_at: string;
+}
+export interface WebhookDelivery {
+    id: string;
+    event: string;
+    status: "success" | "failed" | "pending";
+    response_code: number | null;
+    attempted_at: string;
+}
+export type FetanErrorCode = "unauthorized" | "forbidden" | "not_found" | "validation_error" | "domain_not_verified" | "rate_limited" | "conflict" | "server_error" | "network_error";
+export declare class FetanError extends Error {
+    readonly code: FetanErrorCode;
+    readonly status: number;
+    constructor(message: string, code: FetanErrorCode, status: number);
+}
+export declare class Mailer {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    readonly emails: EmailsResource;
+    readonly batch: BatchResource;
+    readonly domains: DomainsResource;
+    readonly apiKeys: ApiKeysResource;
+    readonly templates: TemplatesResource;
+    readonly webhooks: WebhooksResource;
+    constructor(apiKey: string, options?: FetanOptions);
+    /** @internal */
+    request<T>(method: string, path: string, body?: unknown, extraHeaders?: Record<string, string>): Promise<T>;
+}
+declare class EmailsResource {
+    private readonly m;
+    constructor(m: Mailer);
+    /** Send an email. Returns 202-style { id, status: "queued" }. */
+    send(params: SendEmailParams, opts?: {
+        idempotencyKey?: string;
+    }): Promise<SendEmailResponse>;
+    get(id: string): Promise<Email>;
+    list(params?: ListEmailsParams): Promise<{
+        emails: Email[];
+        total: number;
+        limit: number;
+        offset: number;
+    }>;
+    cancel(id: string): Promise<{
+        id: string;
+        status: "cancelled";
+    }>;
+}
+declare class BatchResource {
+    private readonly m;
+    constructor(m: Mailer);
+    /** Send up to 100 emails in one request. */
+    send(emails: SendEmailParams[]): Promise<BatchSendResponse>;
+}
+declare class DomainsResource {
+    private readonly m;
+    constructor(m: Mailer);
+    list(): Promise<{
+        domains: Domain[];
+    }>;
+    get(id: string): Promise<Domain>;
+    create(name: string): Promise<Domain>;
+    /** Trigger a DNS verification check; returns the domain with per-record status. */
+    verify(id: string): Promise<Domain>;
+    delete(id: string): Promise<{
+        deleted: true;
+    }>;
+}
+declare class ApiKeysResource {
+    private readonly m;
+    constructor(m: Mailer);
+    list(): Promise<{
+        api_keys: ApiKey[];
+    }>;
+    /** Creates a key. The full key is returned once, in `key` — store it immediately. */
+    create(params: {
+        name: string;
+        permission?: "full_access" | "sending_only";
+        domain_id?: string;
+    }): Promise<ApiKey & {
+        key: string;
+    }>;
+    revoke(id: string): Promise<{
+        revoked: true;
+    }>;
+}
+declare class TemplatesResource {
+    private readonly m;
+    constructor(m: Mailer);
+    list(): Promise<{
+        templates: Template[];
+    }>;
+    get(id: string): Promise<Template>;
+    create(params: {
+        name: string;
+        subject: string;
+        html: string;
+    }): Promise<Template>;
+    update(id: string, params: Partial<{
+        name: string;
+        subject: string;
+        html: string;
+    }>): Promise<Template>;
+    delete(id: string): Promise<{
+        deleted: true;
+    }>;
+}
+declare class WebhooksResource {
+    private readonly m;
+    constructor(m: Mailer);
+    list(): Promise<{
+        webhooks: Webhook[];
+    }>;
+    create(params: {
+        url: string;
+        events: string[];
+    }): Promise<Webhook & {
+        secret: string;
+    }>;
+    update(id: string, params: Partial<{
+        url: string;
+        events: string[];
+        active: boolean;
+    }>): Promise<Webhook>;
+    delete(id: string): Promise<{
+        deleted: true;
+    }>;
+    deliveries(id: string): Promise<{
+        deliveries: WebhookDelivery[];
+    }>;
+}
+export default Mailer;

package/dist/index.js

@@ -0,0 +1,251 @@
+/**
+ * Fetan — official Node.js SDK for the Fetan transactional email API.
+ * Zero dependencies; uses the global fetch (Node 18+).
+ */
+export class FetanError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = "FetanError";
+        this.code = code;
+        this.status = status;
+    }
+}
+function codeFor(status, message) {
+    if (status === 401)
+        return "unauthorized";
+    if (status === 403)
+        return "forbidden";
+    if (status === 404)
+        return "not_found";
+    if (status === 409)
+        return "conflict";
+    if (status === 429)
+        return "rate_limited";
+    if (status === 400) {
+        return /not verified|not added/i.test(message) ? "domain_not_verified" : "validation_error";
+    }
+    return "server_error";
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Mailer {
+    apiKey;
+    baseUrl;
+    maxRetries;
+    timeoutMs;
+    emails;
+    batch;
+    domains;
+    apiKeys;
+    templates;
+    webhooks;
+    constructor(apiKey, options = {}) {
+        if (!apiKey)
+            throw new FetanError("An API key is required: new Mailer('em_live_...')", "validation_error", 0);
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://api.fetan.et").replace(/\/+$/, "");
+        this.maxRetries = options.maxRetries ?? 3;
+        this.timeoutMs = options.timeoutMs ?? 15000;
+        this.emails = new EmailsResource(this);
+        this.batch = new BatchResource(this);
+        this.domains = new DomainsResource(this);
+        this.apiKeys = new ApiKeysResource(this);
+        this.templates = new TemplatesResource(this);
+        this.webhooks = new WebhooksResource(this);
+    }
+    /** @internal */
+    async request(method, path, body, extraHeaders = {}) {
+        const base = this.baseUrl.replace(/\/+$/, "");
+        let url;
+        if (base.endsWith("/api/v1") || base.endsWith("/api/public/v1")) {
+            url = `${base}${path}`;
+        }
+        else if (base.endsWith("/api")) {
+            url = `${base}/v1${path}`;
+        }
+        else {
+            url = `${base}/api/v1${path}`;
+        }
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const res = await fetch(url, {
+                    method,
+                    signal: controller.signal,
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        "Content-Type": "application/json",
+                        ...extraHeaders,
+                    },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                });
+                clearTimeout(timer);
+                const text = await res.text();
+                let data = null;
+                try {
+                    data = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    data = null;
+                }
+                if (!res.ok) {
+                    const rawError = data?.error;
+                    let message = `Request failed with status ${res.status}`;
+                    if (typeof rawError === "string") {
+                        message = rawError;
+                    }
+                    else if (typeof rawError?.message === "string") {
+                        message = rawError.message;
+                    }
+                    else if (typeof data?.message === "string") {
+                        message = data.message;
+                    }
+                    // Retry only on server errors; client errors fail immediately.
+                    if (res.status >= 500 && attempt < this.maxRetries) {
+                        lastError = new FetanError(message, "server_error", res.status);
+                        await sleep(2 ** attempt * 300);
+                        continue;
+                    }
+                    throw new FetanError(message, codeFor(res.status, message), res.status);
+                }
+                return data;
+            }
+            catch (err) {
+                clearTimeout(timer);
+                if (err instanceof FetanError)
+                    throw err;
+                lastError = new FetanError(err instanceof Error ? err.message : "Network error", "network_error", 0);
+                if (attempt < this.maxRetries) {
+                    await sleep(2 ** attempt * 300);
+                    continue;
+                }
+            }
+        }
+        throw lastError ?? new FetanError("Request failed", "network_error", 0);
+    }
+}
+class EmailsResource {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    /** Send an email. Returns 202-style { id, status: "queued" }. */
+    send(params, opts) {
+        return this.m.request("POST", "/emails", params, opts?.idempotencyKey ? { "Idempotency-Key": opts.idempotencyKey } : {});
+    }
+    get(id) {
+        return this.m.request("GET", `/emails/${encodeURIComponent(id)}`);
+    }
+    list(params = {}) {
+        const qs = new URLSearchParams();
+        if (params.status)
+            qs.set("status", params.status);
+        if (params.domain)
+            qs.set("domain", params.domain);
+        if (params.search)
+            qs.set("search", params.search);
+        if (params.limit !== undefined)
+            qs.set("limit", String(params.limit));
+        if (params.offset !== undefined)
+            qs.set("offset", String(params.offset));
+        const suffix = qs.size ? `?${qs.toString()}` : "";
+        return this.m.request("GET", `/emails${suffix}`);
+    }
+    cancel(id) {
+        return this.m.request("POST", `/emails/${encodeURIComponent(id)}/cancel`);
+    }
+}
+class BatchResource {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    /** Send up to 100 emails in one request. */
+    send(emails) {
+        return this.m.request("POST", "/emails/batch", { emails });
+    }
+}
+class DomainsResource {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    list() {
+        return this.m.request("GET", "/domains");
+    }
+    get(id) {
+        return this.m.request("GET", `/domains/${encodeURIComponent(id)}`);
+    }
+    create(name) {
+        return this.m.request("POST", "/domains", { name });
+    }
+    /** Trigger a DNS verification check; returns the domain with per-record status. */
+    verify(id) {
+        return this.m.request("POST", `/domains/${encodeURIComponent(id)}/verify`);
+    }
+    delete(id) {
+        return this.m.request("DELETE", `/domains/${encodeURIComponent(id)}`);
+    }
+}
+class ApiKeysResource {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    list() {
+        return this.m.request("GET", "/api-keys");
+    }
+    /** Creates a key. The full key is returned once, in `key` — store it immediately. */
+    create(params) {
+        return this.m.request("POST", "/api-keys", params);
+    }
+    revoke(id) {
+        return this.m.request("DELETE", `/api-keys/${encodeURIComponent(id)}`);
+    }
+}
+class TemplatesResource {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    list() {
+        return this.m.request("GET", "/templates");
+    }
+    get(id) {
+        return this.m.request("GET", `/templates/${encodeURIComponent(id)}`);
+    }
+    create(params) {
+        return this.m.request("POST", "/templates", params);
+    }
+    update(id, params) {
+        return this.m.request("PATCH", `/templates/${encodeURIComponent(id)}`, params);
+    }
+    delete(id) {
+        return this.m.request("DELETE", `/templates/${encodeURIComponent(id)}`);
+    }
+}
+class WebhooksResource {
+    m;
+    constructor(m) {
+        this.m = m;
+    }
+    list() {
+        return this.m.request("GET", "/webhooks");
+    }
+    create(params) {
+        return this.m.request("POST", "/webhooks", params);
+    }
+    update(id, params) {
+        return this.m.request("PATCH", `/webhooks/${encodeURIComponent(id)}`, params);
+    }
+    delete(id) {
+        return this.m.request("DELETE", `/webhooks/${encodeURIComponent(id)}`);
+    }
+    deliveries(id) {
+        return this.m.request("GET", `/webhooks/${encodeURIComponent(id)}/deliveries`);
+    }
+}
+export default Mailer;

package/package.json

@@ -1,6 +1,30 @@
-{
-  "name": "@nanbon/fetan",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@nanbon/fetan",
+  "version": "0.1.0",
+  "description": "Official Node.js SDK for the Fetan transactional email API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": { "node": ">=18" },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "keywords": ["email", "transactional", "smtp", "mailer", "fetan", "ethiopia"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nanbon/fetan-email"
+  },
+  "homepage": "https://fetan.et",
+  "license": "MIT"
+}