@loftbox/sdk 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# LoftBox TypeScript SDK
+
+AI 에이전트를 위한 이메일 인프라 SDK. 의존성 없음(Node 18+ 내장 `fetch` 사용).
+
+## 설치
+
+```bash
+npm install @loftbox/sdk
+```
+
+## 빠른 시작
+
+```typescript
+import { LoftBox } from '@loftbox/sdk';
+
+const client = new LoftBox({ apiKey: 'lb_live_xxx' });
+
+// 에이전트 + 메일박스
+const agent = await client.agents.create({ name: 'Support Bot', slug: 'support-bot' });
+const mailbox = await client.mailboxes.create(agent.id, { localPart: 'support' });
+
+// 발송 (멱등 키로 중복 방지)
+const msg = await client.messages.send({
+  mailboxId: mailbox.id,
+  to: ['recipient@example.com'],
+  subject: 'Hello',
+  bodyText: 'World',
+  idempotencyKey: 'welcome-42',
+});
+
+// 수신 폴링 → ack
+const inbox = await client.mailboxes.listInbox(mailbox.id);
+await client.mailboxes.ackInbox(
+  mailbox.id,
+  inbox.data.map((m) => m.id),
+);
+```
+
+## 기능
+
+- **발송** `messages.send(...)` — 텍스트/HTML/Markdown, 첨부, cc, 답장 헤더
+- **예약 발송** `send({ ..., sendAt: '2030-01-01T09:00:00Z' })`
+- **멱등 발송** `send({ ..., idempotencyKey })`
+- **수신** `mailboxes.listInbox()` + `ackInbox()`, `message.extracted_text`(인용 제거 본문)
+- **라벨** `messages.addLabels()`, `removeLabel()`, `list({ label })`
+- **전문검색** `messages.list({ q })`, `threads.list({ q })`
+- **스레드** `threads.list()`, `listMessages()`
+- **승인** `messages.approve(id, reason)`, `reject(...)`
+- **웹훅** `webhooks.create(agentId, url, eventTypes)`
+- **도메인 / suppression** `domains.*`, `suppressions.*`
+
+## 오류 처리
+
+```typescript
+import { RateLimitError, NotFoundError } from '@loftbox/sdk';
+
+try {
+  await client.messages.send({
+    /* ... */
+  });
+} catch (e) {
+  if (e instanceof RateLimitError) {
+    console.log(`${e.retryAfterSecs}s 후 재시도`);
+  } else if (e instanceof NotFoundError) {
+    console.log(e.statusCode, e.message);
+  }
+}
+```
+
+## 페이지네이션
+
+목록 메서드는 `{ data, next_cursor }` 를 반환합니다:
+
+```typescript
+let page = await client.messages.list({ mailboxId: mailbox.id, limit: 50 });
+while (true) {
+  for (const m of page.data) {
+    /* ... */
+  }
+  if (!page.next_cursor) break;
+  page = await client.messages.list({
+    mailboxId: mailbox.id,
+    limit: 50,
+    cursor: page.next_cursor,
+  });
+}
+```
+
+## 예제
+
+`examples/quickstart.ts` 참고.
+
+## 라이선스
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,103 @@
+import type { Agent, Attachment, Domain, DomainStatus, ListMessagesParams, LoftBoxConfig, Mailbox, Message, Page, SendMessageParams, Suppression, Thread, Webhook } from "./types.js";
+type Query = Record<string, string | number | undefined | null>;
+/** LoftBox API 클라이언트 (fetch 기반, 의존성 없음). */
+export declare class LoftBox {
+    readonly auth: AuthResource;
+    readonly agents: AgentsResource;
+    readonly mailboxes: MailboxesResource;
+    readonly messages: MessagesResource;
+    readonly threads: ThreadsResource;
+    readonly webhooks: WebhooksResource;
+    readonly domains: DomainsResource;
+    readonly suppressions: SuppressionsResource;
+    readonly attachments: AttachmentsResource;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(config: LoftBoxConfig);
+    /** @internal */
+    request<T>(method: string, path: string, opts?: {
+        json?: unknown;
+        query?: Query;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+declare class Resource {
+    protected readonly c: LoftBox;
+    constructor(c: LoftBox);
+}
+declare class AuthResource extends Resource {
+    signup(email: string, organizationName: string, slug?: string): Promise<Record<string, unknown>>;
+    verifySignup(email: string, verificationToken: string): Promise<Record<string, unknown>>;
+}
+declare class AgentsResource extends Resource {
+    create(params: {
+        name: string;
+        slug: string;
+        description?: string;
+        purpose?: string;
+        externalId?: string;
+        ownerLabel?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<Agent>;
+    get(agentId: string): Promise<Agent>;
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Agent>>;
+}
+declare class MailboxesResource extends Resource {
+    create(agentId: string, params: {
+        localPart: string;
+        domainId?: string;
+        displayName?: string;
+        webhookUrl?: string;
+        retentionDays?: number;
+    }): Promise<Mailbox>;
+    listByAgent(agentId: string): Promise<Page<Mailbox>>;
+    listInbox(mailboxId: string, params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Message>>;
+    ackInbox(mailboxId: string, messageIds: string[]): Promise<unknown>;
+}
+declare class MessagesResource extends Resource {
+    send(params: SendMessageParams): Promise<Message>;
+    get(messageId: string): Promise<Message>;
+    list(params?: ListMessagesParams): Promise<Page<Message>>;
+    addLabels(messageId: string, labels: string[]): Promise<Message>;
+    removeLabel(messageId: string, label: string): Promise<Message>;
+    approve(messageId: string, reason: string): Promise<Message>;
+    reject(messageId: string, reason: string): Promise<Message>;
+}
+declare class ThreadsResource extends Resource {
+    list(params?: {
+        mailboxId?: string;
+        q?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<Page<Thread>>;
+    listMessages(threadId: string): Promise<Page<Message>>;
+}
+declare class WebhooksResource extends Resource {
+    create(agentId: string, url: string, eventTypes: string[]): Promise<Webhook>;
+}
+declare class DomainsResource extends Resource {
+    create(domain: string): Promise<Domain>;
+    list(): Promise<Page<Domain>>;
+    status(domainId: string): Promise<DomainStatus>;
+}
+declare class SuppressionsResource extends Resource {
+    list(params?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Page<Suppression>>;
+    create(address: string): Promise<Suppression>;
+    remove(suppressionId: string): Promise<void>;
+}
+declare class AttachmentsResource extends Resource {
+    listForMessage(messageId: string): Promise<Page<Attachment>>;
+    presignedUrl(attachmentId: string): Promise<Record<string, unknown>>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,310 @@
+import { LoftBoxError, errorForStatus } from "./errors.js";
+const DEFAULT_BASE_URL = "https://api.loftbox.net";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const USER_AGENT = "loftbox-ts/0.1.0";
+/** LoftBox API 클라이언트 (fetch 기반, 의존성 없음). */
+export class LoftBox {
+    auth;
+    agents;
+    mailboxes;
+    messages;
+    threads;
+    webhooks;
+    domains;
+    suppressions;
+    attachments;
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(config) {
+        if (!config?.apiKey)
+            throw new Error("apiKey 는 필수입니다");
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const f = config.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error("fetch 를 사용할 수 없습니다 (Node 18+ 또는 config.fetch 제공)");
+        this.fetchImpl = f;
+        this.auth = new AuthResource(this);
+        this.agents = new AgentsResource(this);
+        this.mailboxes = new MailboxesResource(this);
+        this.messages = new MessagesResource(this);
+        this.threads = new ThreadsResource(this);
+        this.webhooks = new WebhooksResource(this);
+        this.domains = new DomainsResource(this);
+        this.suppressions = new SuppressionsResource(this);
+        this.attachments = new AttachmentsResource(this);
+    }
+    /** @internal */
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": USER_AGENT,
+            ...opts.headers,
+        };
+        if (opts.json !== undefined)
+            headers["Content-Type"] = "application/json";
+        // 타임아웃은 fetch + 본문 읽기 전체를 덮는다 — 헤더만 보내고 body 를 멈추는
+        // 서버/프록시에도 timeoutMs 가 적용되도록(codex 리뷰 Major).
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let resp;
+        let text;
+        try {
+            resp = await this.fetchImpl(url.toString(), {
+                method,
+                headers,
+                body: opts.json !== undefined ? JSON.stringify(opts.json) : undefined,
+                signal: controller.signal,
+            });
+            text = await resp.text();
+        }
+        catch (e) {
+            throw new LoftBoxError(`요청 실패: ${e.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const requestId = resp.headers.get("x-request-id") ?? undefined;
+        let body = undefined;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+        }
+        if (!resp.ok) {
+            let message = `HTTP ${resp.status}`;
+            let retryAfterSecs;
+            if (body && typeof body === "object") {
+                const b = body;
+                const err = b.error;
+                if (err && typeof err === "object") {
+                    const eo = err;
+                    if (typeof eo.message === "string")
+                        message = eo.message;
+                    if (typeof eo.retry_after === "number")
+                        retryAfterSecs = eo.retry_after;
+                }
+                else if (typeof b.message === "string") {
+                    message = b.message;
+                }
+                else if (typeof err === "string") {
+                    message = err;
+                }
+                else if (typeof b.detail === "string") {
+                    message = b.detail;
+                }
+            }
+            else if (typeof body === "string" && body) {
+                message = body;
+            }
+            const headerRa = resp.headers.get("retry-after");
+            if (headerRa && /^\d+$/.test(headerRa))
+                retryAfterSecs = Number(headerRa);
+            throw errorForStatus(resp.status, message, {
+                body,
+                requestId,
+                retryAfterSecs,
+            });
+        }
+        return body;
+    }
+}
+function page(raw) {
+    if (Array.isArray(raw))
+        return { data: raw, next_cursor: null };
+    const src = (raw ?? {});
+    return { data: src.data ?? [], next_cursor: src.next_cursor ?? null };
+}
+class Resource {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+}
+class AuthResource extends Resource {
+    signup(email, organizationName, slug) {
+        return this.c.request("POST", "/v1/auth/signup", {
+            json: { email, organization_name: organizationName, slug: slug ?? null },
+        });
+    }
+    verifySignup(email, verificationToken) {
+        return this.c.request("POST", "/v1/auth/signup/verify", {
+            json: { email, verification_token: verificationToken },
+        });
+    }
+}
+class AgentsResource extends Resource {
+    create(params) {
+        return this.c.request("POST", "/v1/agents", {
+            json: {
+                name: params.name,
+                slug: params.slug,
+                description: params.description ?? null,
+                purpose: params.purpose ?? null,
+                external_id: params.externalId ?? null,
+                owner_label: params.ownerLabel ?? null,
+                metadata: params.metadata ?? null,
+            },
+        });
+    }
+    get(agentId) {
+        return this.c.request("GET", `/v1/agents/${encodeURIComponent(agentId)}`);
+    }
+    async list(params = {}) {
+        return page(await this.c.request("GET", "/v1/agents", {
+            query: { limit: params.limit, cursor: params.cursor },
+        }));
+    }
+}
+class MailboxesResource extends Resource {
+    create(agentId, params) {
+        return this.c.request("POST", `/v1/agents/${encodeURIComponent(agentId)}/mailboxes`, {
+            json: {
+                local_part: params.localPart,
+                domain_id: params.domainId ?? null,
+                display_name: params.displayName ?? null,
+                webhook_url: params.webhookUrl ?? null,
+                retention_days: params.retentionDays ?? null,
+            },
+        });
+    }
+    async listByAgent(agentId) {
+        return page(await this.c.request("GET", `/v1/agents/${encodeURIComponent(agentId)}/mailboxes`));
+    }
+    async listInbox(mailboxId, params = {}) {
+        return page(await this.c.request("GET", `/v1/mailboxes/${encodeURIComponent(mailboxId)}/inbox`, {
+            query: { limit: params.limit, cursor: params.cursor },
+        }));
+    }
+    ackInbox(mailboxId, messageIds) {
+        return this.c.request("POST", `/v1/mailboxes/${encodeURIComponent(mailboxId)}/inbox/ack`, {
+            json: { message_ids: messageIds },
+        });
+    }
+}
+class MessagesResource extends Resource {
+    send(params) {
+        const headers = params.idempotencyKey
+            ? { "Idempotency-Key": params.idempotencyKey }
+            : undefined;
+        return this.c.request("POST", "/v1/messages", {
+            json: {
+                mailbox_id: params.mailboxId,
+                to: params.to,
+                subject: params.subject,
+                body_text: params.bodyText ?? null,
+                body_html: params.bodyHtml ?? null,
+                body_markdown: params.bodyMarkdown ?? null,
+                cc: params.cc ?? [],
+                in_reply_to: params.inReplyTo ?? null,
+                references: params.references ?? [],
+                metadata: params.metadata ?? null,
+                attachments: params.attachments ?? [],
+                send_at: params.sendAt ?? null,
+            },
+            headers,
+        });
+    }
+    get(messageId) {
+        return this.c.request("GET", `/v1/messages/${encodeURIComponent(messageId)}`);
+    }
+    async list(params = {}) {
+        return page(await this.c.request("GET", "/v1/messages", {
+            query: {
+                mailbox_id: params.mailboxId,
+                direction: params.direction,
+                status: params.status,
+                label: params.label,
+                q: params.q,
+                limit: params.limit,
+                cursor: params.cursor,
+            },
+        }));
+    }
+    addLabels(messageId, labels) {
+        return this.c.request("POST", `/v1/messages/${encodeURIComponent(messageId)}/labels`, {
+            json: { labels },
+        });
+    }
+    removeLabel(messageId, label) {
+        return this.c.request("DELETE", `/v1/messages/${encodeURIComponent(messageId)}/labels/${encodeURIComponent(label)}`);
+    }
+    approve(messageId, reason) {
+        return this.c.request("POST", `/v1/messages/${encodeURIComponent(messageId)}/approve`, {
+            json: { reason },
+        });
+    }
+    reject(messageId, reason) {
+        return this.c.request("POST", `/v1/messages/${encodeURIComponent(messageId)}/reject`, {
+            json: { reason },
+        });
+    }
+}
+class ThreadsResource extends Resource {
+    async list(params = {}) {
+        return page(await this.c.request("GET", "/v1/threads", {
+            query: {
+                mailbox_id: params.mailboxId,
+                q: params.q,
+                limit: params.limit,
+                cursor: params.cursor,
+            },
+        }));
+    }
+    async listMessages(threadId) {
+        return page(await this.c.request("GET", `/v1/threads/${encodeURIComponent(threadId)}/messages`));
+    }
+}
+class WebhooksResource extends Resource {
+    create(agentId, url, eventTypes) {
+        return this.c.request("POST", `/v1/agents/${encodeURIComponent(agentId)}/webhooks`, {
+            json: { url, event_types: eventTypes },
+        });
+    }
+}
+class DomainsResource extends Resource {
+    create(domain) {
+        return this.c.request("POST", "/v1/domains", { json: { domain } });
+    }
+    async list() {
+        return page(await this.c.request("GET", "/v1/domains"));
+    }
+    status(domainId) {
+        return this.c.request("GET", `/v1/domains/${encodeURIComponent(domainId)}/status`);
+    }
+}
+class SuppressionsResource extends Resource {
+    async list(params = {}) {
+        return page(await this.c.request("GET", "/v1/suppressions", {
+            query: { limit: params.limit, before: params.before },
+        }));
+    }
+    create(address) {
+        return this.c.request("POST", "/v1/suppressions", { json: { address } });
+    }
+    async remove(suppressionId) {
+        await this.c.request("DELETE", `/v1/suppressions/${encodeURIComponent(suppressionId)}`);
+    }
+}
+class AttachmentsResource extends Resource {
+    async listForMessage(messageId) {
+        return page(await this.c.request("GET", `/v1/messages/${encodeURIComponent(messageId)}/attachments`));
+    }
+    presignedUrl(attachmentId) {
+        return this.c.request("GET", `/v1/attachments/${encodeURIComponent(attachmentId)}/url`);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+/** LoftBox SDK 예외. */
+export declare class LoftBoxError extends Error {
+    readonly statusCode?: number;
+    readonly body?: unknown;
+    readonly requestId?: string;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        body?: unknown;
+        requestId?: string;
+    });
+}
+/** 401 — API 키 없음/유효하지 않음. */
+export declare class AuthenticationError extends LoftBoxError {
+    constructor(...args: ConstructorParameters<typeof LoftBoxError>);
+}
+/** 403 — scope 부족. */
+export declare class PermissionError extends LoftBoxError {
+    constructor(...args: ConstructorParameters<typeof LoftBoxError>);
+}
+/** 404 — 리소스 없음. */
+export declare class NotFoundError extends LoftBoxError {
+    constructor(...args: ConstructorParameters<typeof LoftBoxError>);
+}
+/** 409 — 멱등/상태 충돌. */
+export declare class ConflictError extends LoftBoxError {
+    constructor(...args: ConstructorParameters<typeof LoftBoxError>);
+}
+/** 400 / 422 — 요청 검증 실패. */
+export declare class ValidationError extends LoftBoxError {
+    constructor(...args: ConstructorParameters<typeof LoftBoxError>);
+}
+/** 429 — rate limit 초과. retryAfterSecs 만큼 대기 후 재시도. */
+export declare class RateLimitError extends LoftBoxError {
+    readonly retryAfterSecs?: number;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        body?: unknown;
+        requestId?: string;
+        retryAfterSecs?: number;
+    });
+}
+export declare function errorForStatus(statusCode: number, message: string, opts?: {
+    body?: unknown;
+    requestId?: string;
+    retryAfterSecs?: number;
+}): LoftBoxError;

package/dist/errors.js

@@ -0,0 +1,82 @@
+/** LoftBox SDK 예외. */
+export class LoftBoxError extends Error {
+    statusCode;
+    body;
+    requestId;
+    constructor(message, opts = {}) {
+        super(message);
+        // 하위 타깃 트랜스파일에서도 instanceof 가 동작하도록 prototype 복원.
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = "LoftBoxError";
+        this.statusCode = opts.statusCode;
+        this.body = opts.body;
+        this.requestId = opts.requestId;
+    }
+}
+/** 401 — API 키 없음/유효하지 않음. */
+export class AuthenticationError extends LoftBoxError {
+    constructor(...args) {
+        super(...args);
+        this.name = "AuthenticationError";
+    }
+}
+/** 403 — scope 부족. */
+export class PermissionError extends LoftBoxError {
+    constructor(...args) {
+        super(...args);
+        this.name = "PermissionError";
+    }
+}
+/** 404 — 리소스 없음. */
+export class NotFoundError extends LoftBoxError {
+    constructor(...args) {
+        super(...args);
+        this.name = "NotFoundError";
+    }
+}
+/** 409 — 멱등/상태 충돌. */
+export class ConflictError extends LoftBoxError {
+    constructor(...args) {
+        super(...args);
+        this.name = "ConflictError";
+    }
+}
+/** 400 / 422 — 요청 검증 실패. */
+export class ValidationError extends LoftBoxError {
+    constructor(...args) {
+        super(...args);
+        this.name = "ValidationError";
+    }
+}
+/** 429 — rate limit 초과. retryAfterSecs 만큼 대기 후 재시도. */
+export class RateLimitError extends LoftBoxError {
+    retryAfterSecs;
+    constructor(message, opts = {}) {
+        super(message, opts);
+        this.name = "RateLimitError";
+        this.retryAfterSecs = opts.retryAfterSecs;
+    }
+}
+export function errorForStatus(statusCode, message, opts = {}) {
+    const base = { statusCode, body: opts.body, requestId: opts.requestId };
+    switch (statusCode) {
+        case 400:
+        case 422:
+            return new ValidationError(message, base);
+        case 401:
+            return new AuthenticationError(message, base);
+        case 403:
+            return new PermissionError(message, base);
+        case 404:
+            return new NotFoundError(message, base);
+        case 409:
+            return new ConflictError(message, base);
+        case 429:
+            return new RateLimitError(message, {
+                ...base,
+                retryAfterSecs: opts.retryAfterSecs,
+            });
+        default:
+            return new LoftBoxError(message, base);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { LoftBox } from "./client.js";
+export { LoftBoxError, AuthenticationError, PermissionError, NotFoundError, ConflictError, ValidationError, RateLimitError, } from "./errors.js";
+export type { LoftBoxConfig, Agent, Attachment, Domain, DomainStatus, Mailbox, Message, Page, Suppression, Thread, Webhook, SendMessageParams, ListMessagesParams, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { LoftBox } from "./client.js";
+export { LoftBoxError, AuthenticationError, PermissionError, NotFoundError, ConflictError, ValidationError, RateLimitError, } from "./errors.js";

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+/** LoftBox SDK 타입.
+ *
+ * 응답 모델은 서버가 필드를 추가해도 깨지지 않도록 인덱스 시그니처를 둔다.
+ * 필드명은 API wire(snake_case)를 그대로 따른다.
+ */
+export interface LoftBoxConfig {
+    apiKey: string;
+    baseUrl?: string;
+    /** 요청 타임아웃(ms). 기본 30000. */
+    timeoutMs?: number;
+    /** 테스트/프록시용 커스텀 fetch. 기본 globalThis.fetch. */
+    fetch?: typeof fetch;
+}
+interface Extensible {
+    [key: string]: unknown;
+}
+export interface Agent extends Extensible {
+    id: string;
+    slug?: string;
+    name: string;
+    description?: string | null;
+    created_at?: string | null;
+}
+export interface Mailbox extends Extensible {
+    id: string;
+    agent_id?: string;
+    address: string;
+    display_name?: string | null;
+    active?: boolean;
+    created_at?: string | null;
+}
+export interface Attachment extends Extensible {
+    id: string;
+    filename?: string;
+    content_type?: string;
+    size_bytes?: number;
+}
+export interface Message extends Extensible {
+    id: string;
+    public_id?: string | null;
+    mailbox_id?: string;
+    thread_id?: string | null;
+    direction?: string;
+    status?: string;
+    subject?: string | null;
+    body_text?: string | null;
+    body_html?: string | null;
+    body_markdown?: string | null;
+    /** #229 인용 제거된 수신 답장 본문. */
+    extracted_text?: string | null;
+    /** #236 라벨. */
+    labels?: string[];
+    /** #241 예약발송 시각(RFC3339). */
+    scheduled_at?: string | null;
+    sent_at?: string | null;
+    received_at?: string | null;
+    created_at?: string | null;
+}
+export interface Thread extends Extensible {
+    id: string;
+    mailbox_id?: string;
+    subject?: string | null;
+    last_message_at?: string | null;
+}
+export interface Webhook extends Extensible {
+    id: string;
+    url: string;
+    event_types?: string[];
+    /** 생성 응답에서 1회만 반환되는 서명 시크릿 — 즉시 저장, 로그 금지. */
+    secret?: string | null;
+}
+export interface Domain extends Extensible {
+    id: string;
+    domain?: string;
+    status?: string;
+}
+export interface DomainStatus extends Extensible {
+    domain?: string;
+    status?: string;
+    inbound?: unknown;
+    outbound?: unknown;
+    next_actions?: unknown;
+}
+export interface Suppression extends Extensible {
+    id: string;
+    address: string;
+    reason?: string | null;
+    created_at?: string | null;
+}
+/** cursor 페이지네이션 응답. */
+export interface Page<T> {
+    data: T[];
+    next_cursor: string | null;
+}
+/** messages.send 옵션. */
+export interface SendMessageParams {
+    mailboxId: string;
+    to: string[];
+    subject: string;
+    bodyText?: string;
+    bodyHtml?: string;
+    bodyMarkdown?: string;
+    cc?: string[];
+    inReplyTo?: string;
+    references?: string[];
+    metadata?: Record<string, unknown>;
+    attachments?: Array<Record<string, unknown>>;
+    /** RFC3339 미래 시각 — 예약발송. */
+    sendAt?: string;
+    /** 중복 발송 방지 멱등 키. */
+    idempotencyKey?: string;
+}
+export interface ListMessagesParams {
+    mailboxId?: string;
+    direction?: string;
+    status?: string;
+    label?: string;
+    q?: string;
+    limit?: number;
+    cursor?: string;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,6 @@
+/** LoftBox SDK 타입.
+ *
+ * 응답 모델은 서버가 필드를 추가해도 깨지지 않도록 인덱스 시그니처를 둔다.
+ * 필드명은 API wire(snake_case)를 그대로 따른다.
+ */
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@loftbox/sdk",
+  "version": "0.1.0",
+  "description": "LoftBox TypeScript SDK - Email infrastructure for AI agents",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheMagicTower/loftbox-sdk-ts.git"
+  },
+  "homepage": "https://loftbox.net",
+  "keywords": ["email", "ai-agents", "smtp", "inbox", "loftbox"],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20",
+    "prettier": "^3",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}