@inkbox/sdk 0.1.0

package/README.md

@@ -0,0 +1,369 @@
+# @inkbox/sdk
+
+TypeScript SDK for the [Inkbox API](https://www.inkbox.ai/docs) — API-first communication infrastructure for AI agents (email, phone, identities).
+
+## Install
+
+```bash
+npm install @inkbox/sdk
+```
+
+Requires Node.js ≥ 18.
+
+## Authentication
+
+You'll need an API key to use this SDK. Get one at [console.inkbox.ai](https://console.inkbox.ai/).
+
+## Quick start
+
+```ts
+import { Inkbox } from "@inkbox/sdk";
+
+const inkbox = new Inkbox({ apiKey: process.env.INKBOX_API_KEY! });
+
+// Create an agent identity
+const identity = await inkbox.createIdentity("support-bot");
+
+// Create and link new channels
+const mailbox = await identity.createMailbox({ displayName: "Support Bot" });
+const phone   = await identity.provisionPhoneNumber({ type: "toll_free" });
+
+// Send email directly from the identity
+await identity.sendEmail({
+  to: ["customer@example.com"],
+  subject: "Your order has shipped",
+  bodyText: "Tracking number: 1Z999AA10123456784",
+});
+
+// Place an outbound call
+await identity.placeCall({
+  toNumber: "+18005559999",
+  clientWebsocketUrl: "wss://my-app.com/voice",
+});
+
+// Read inbox
+for await (const message of identity.iterEmails()) {
+  console.log(message.subject);
+}
+
+// List calls
+const calls = await identity.listCalls();
+```
+
+## Authentication
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | required | Your `ApiKey_...` token |
+| `baseUrl` | `string` | API default | Override for self-hosting or testing |
+| `timeoutMs` | `number` | `30000` | Request timeout in milliseconds |
+
+---
+
+## Identities
+
+`inkbox.createIdentity()` and `inkbox.getIdentity()` return an `AgentIdentity` object that holds the identity's channels and exposes convenience methods scoped to those channels.
+
+```ts
+// Create and fully provision an identity
+const identity = await inkbox.createIdentity("sales-bot");
+const mailbox  = await identity.createMailbox({ displayName: "Sales Bot" });      // creates + links
+const phone    = await identity.provisionPhoneNumber({ type: "toll_free" });      // provisions + links
+
+console.log(mailbox.emailAddress);
+console.log(phone.number);
+
+// Link an existing mailbox or phone number instead of creating new ones
+await identity.assignMailbox("mailbox-uuid-here");
+await identity.assignPhoneNumber("phone-number-uuid-here");
+
+// Get an existing identity (returned with current channel state)
+const identity2 = await inkbox.getIdentity("sales-bot");
+await identity2.refresh();  // re-fetch channels from API
+
+// List all identities for your org
+const allIdentities = await inkbox.listIdentities();
+
+// Update status or handle
+await identity.update({ status: "paused" });
+await identity.update({ newHandle: "sales-bot-v2" });
+
+// Unlink channels (without deleting them)
+await identity.unlinkMailbox();
+await identity.unlinkPhoneNumber();
+
+// Delete
+await identity.delete();
+```
+
+---
+
+## Mail
+
+```ts
+// Send an email (plain text and/or HTML)
+const sent = await identity.sendEmail({
+  to: ["user@example.com"],
+  subject: "Hello from Inkbox",
+  bodyText: "Hi there!",
+  bodyHtml: "<p>Hi there!</p>",
+  cc: ["manager@example.com"],
+  bcc: ["archive@example.com"],
+});
+
+// Send a threaded reply
+await identity.sendEmail({
+  to: ["user@example.com"],
+  subject: `Re: ${sent.subject}`,
+  bodyText: "Following up!",
+  inReplyToMessageId: sent.id,
+});
+
+// Send with attachments
+await identity.sendEmail({
+  to: ["user@example.com"],
+  subject: "See attached",
+  bodyText: "Please find the file attached.",
+  attachments: [{
+    filename: "report.pdf",
+    contentType: "application/pdf",
+    contentBase64: "<base64-encoded-content>",
+  }],
+});
+
+// Iterate inbox (paginated automatically)
+for await (const msg of identity.iterEmails()) {
+  console.log(msg.subject, msg.fromAddress, msg.isRead);
+}
+
+// Filter by direction: "inbound" or "outbound"
+for await (const msg of identity.iterEmails({ direction: "inbound" })) {
+  console.log(msg.subject);
+}
+
+// Iterate only unread emails
+for await (const msg of identity.iterUnreadEmails()) {
+  console.log(msg.subject);
+}
+
+// Mark messages as read
+const unread: string[] = [];
+for await (const msg of identity.iterUnreadEmails()) unread.push(msg.id);
+await identity.markEmailsRead(unread);
+
+// Get all emails in a thread (threadId comes from msg.threadId)
+const thread = await identity.getThread(msg.threadId!);
+for (const m of thread.messages) {
+  console.log(m.subject, m.fromAddress);
+}
+```
+
+---
+
+## Phone
+
+```ts
+// Place an outbound call — stream audio over WebSocket
+const call = await identity.placeCall({
+  toNumber: "+15167251294",
+  clientWebsocketUrl: "wss://your-agent.example.com/ws",
+});
+console.log(call.status, call.rateLimit.callsRemaining);
+
+// Or receive call events via webhook instead
+const call2 = await identity.placeCall({
+  toNumber: "+15167251294",
+  webhookUrl: "https://your-agent.example.com/call-events",
+});
+
+// List calls (paginated)
+const calls = await identity.listCalls({ limit: 10, offset: 0 });
+for (const c of calls) {
+  console.log(c.id, c.direction, c.remotePhoneNumber, c.status);
+}
+
+// Fetch transcript segments for a call
+const segments = await identity.listTranscripts(calls[0].id);
+for (const t of segments) {
+  console.log(`[${t.party}] ${t.text}`);  // party: "local" or "remote"
+}
+
+// Read transcripts across all recent calls
+const recentCalls = await identity.listCalls({ limit: 10 });
+for (const call of recentCalls) {
+  const segs = await identity.listTranscripts(call.id);
+  if (!segs.length) continue;
+  console.log(`\n--- Call ${call.id} (${call.direction}) ---`);
+  for (const t of segs) {
+    console.log(`  [${t.party.padEnd(6)}] ${t.text}`);
+  }
+}
+
+// Filter to only the remote party's speech
+const remoteOnly = segments.filter(t => t.party === "remote");
+for (const t of remoteOnly) console.log(t.text);
+
+// Search transcripts across a phone number (org-level)
+const hits = await inkbox.phoneNumbers.searchTranscripts(phone.id, { q: "refund", party: "remote" });
+for (const t of hits) {
+  console.log(`[${t.party}] ${t.text}`);
+}
+```
+
+---
+
+## Org-level Mailboxes
+
+Manage mailboxes directly without going through an identity. Access via `inkbox.mailboxes`.
+
+```ts
+// List all mailboxes in the organisation
+const mailboxes = await inkbox.mailboxes.list();
+
+// Get a specific mailbox
+const mailbox = await inkbox.mailboxes.get("abc-xyz@inkboxmail.com");
+
+// Create a standalone mailbox
+const mb = await inkbox.mailboxes.create({ displayName: "Support Inbox" });
+console.log(mb.emailAddress);
+
+// Update display name or webhook URL
+await inkbox.mailboxes.update(mb.emailAddress, { displayName: "New Name" });
+await inkbox.mailboxes.update(mb.emailAddress, { webhookUrl: "https://example.com/hook" });
+await inkbox.mailboxes.update(mb.emailAddress, { webhookUrl: null }); // remove webhook
+
+// Full-text search across messages in a mailbox
+const results = await inkbox.mailboxes.search(mb.emailAddress, { q: "invoice", limit: 20 });
+for (const msg of results) {
+  console.log(msg.subject, msg.fromAddress);
+}
+
+// Delete a mailbox
+await inkbox.mailboxes.delete(mb.emailAddress);
+```
+
+---
+
+## Org-level Phone Numbers
+
+Manage phone numbers directly without going through an identity. Access via `inkbox.phoneNumbers`.
+
+```ts
+// List all phone numbers in the organisation
+const numbers = await inkbox.phoneNumbers.list();
+
+// Get a specific phone number by ID
+const number = await inkbox.phoneNumbers.get("phone-number-uuid");
+
+// Provision a new number
+const num   = await inkbox.phoneNumbers.provision({ type: "toll_free" });
+const local = await inkbox.phoneNumbers.provision({ type: "local", state: "NY" });
+
+// Update incoming call behaviour
+await inkbox.phoneNumbers.update(num.id, {
+  incomingCallAction: "webhook",
+  incomingCallWebhookUrl: "https://example.com/calls",
+});
+await inkbox.phoneNumbers.update(num.id, {
+  incomingCallAction: "auto_accept",
+  clientWebsocketUrl: "wss://example.com/ws",
+});
+
+// Full-text search across transcripts
+const hits = await inkbox.phoneNumbers.searchTranscripts(num.id, { q: "refund", party: "remote" });
+for (const t of hits) {
+  console.log(`[${t.party}] ${t.text}`);
+}
+
+// Release a number
+await inkbox.phoneNumbers.release({ number: num.number });
+```
+
+---
+
+## Webhooks
+
+Webhooks are configured on the mailbox or phone number resource — no separate registration step.
+
+### Mailbox webhooks
+
+Set a URL on a mailbox to receive `message.received` and `message.sent` events.
+
+```ts
+// Set webhook
+await inkbox.mailboxes.update("abc@inkboxmail.com", { webhookUrl: "https://example.com/hook" });
+
+// Remove webhook
+await inkbox.mailboxes.update("abc@inkboxmail.com", { webhookUrl: null });
+```
+
+### Phone webhooks
+
+Set an incoming call webhook URL and action on a phone number.
+
+```ts
+// Route incoming calls to a webhook
+await inkbox.phoneNumbers.update(number.id, {
+  incomingCallAction: "webhook",
+  incomingCallWebhookUrl: "https://example.com/calls",
+});
+```
+
+You can also supply a per-call webhook URL when placing a call:
+
+```ts
+await identity.placeCall({ toNumber: "+15005550006", webhookUrl: "https://example.com/call-events" });
+```
+
+---
+
+## Signing Keys
+
+```ts
+// Create or rotate the org-level webhook signing key (plaintext returned once)
+const key = await inkbox.createSigningKey();
+console.log(key.signingKey); // save this immediately
+```
+
+---
+
+## Verifying Webhook Signatures
+
+Use `verifyWebhook` to confirm that an incoming request was sent by Inkbox.
+
+```typescript
+import { verifyWebhook } from "@inkbox/sdk";
+
+// Express — use express.raw() to get the raw body Buffer
+app.post("/hooks/mail", express.raw({ type: "*/*" }), (req, res) => {
+  const valid = verifyWebhook({
+    payload: req.body,
+    headers: req.headers,
+    secret: "whsec_...",
+  });
+  if (!valid) return res.status(403).end();
+  // handle event ...
+});
+```
+
+---
+
+## Examples
+
+Runnable example scripts are available in the [examples/typescript](https://github.com/vectorlyapp/inkbox/tree/main/inkbox/examples/typescript) directory:
+
+| Script | What it demonstrates |
+|---|---|
+| `register-agent-identity.ts` | Create an identity, assign mailbox + phone number |
+| `agent-send-email.ts` | Send an email and a threaded reply |
+| `read-agent-messages.ts` | List messages and threads |
+| `create-agent-mailbox.ts` | Create, update, search, and delete a mailbox |
+| `create-agent-phone-number.ts` | Provision, update, and release a number |
+| `list-agent-phone-numbers.ts` | List all phone numbers in the org |
+| `read-agent-calls.ts` | List calls and print transcripts |
+| `receive-agent-email-webhook.ts` | Register and delete a mailbox webhook |
+| `receive-agent-call-webhook.ts` | Register, update, and delete a phone webhook |
+
+## License
+
+MIT

package/dist/_http.d.ts

@@ -0,0 +1,24 @@
+/**
+ * inkbox-mail/_http.ts
+ *
+ * Async HTTP transport (internal). Zero runtime dependencies — uses native fetch.
+ */
+export declare class InkboxAPIError extends Error {
+    readonly statusCode: number;
+    readonly detail: string;
+    constructor(statusCode: number, detail: string);
+}
+type Params = Record<string, string | number | boolean | undefined | null>;
+export declare class HttpTransport {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(apiKey: string, baseUrl: string, timeoutMs?: number);
+    get<T>(path: string, params?: Params): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete(path: string): Promise<void>;
+    private request;
+}
+export {};
+//# sourceMappingURL=_http.d.ts.map

package/dist/_http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_http.d.ts","sourceRoot":"","sources":["../src/_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM/C;AAED,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;AAE3E,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,GAAE,MAAe;IAGvC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjD,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjD,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAI3B,OAAO;CA6DtB"}

package/dist/_http.js

@@ -0,0 +1,90 @@
+/**
+ * inkbox-mail/_http.ts
+ *
+ * Async HTTP transport (internal). Zero runtime dependencies — uses native fetch.
+ */
+export class InkboxAPIError extends Error {
+    statusCode;
+    detail;
+    constructor(statusCode, detail) {
+        super(`HTTP ${statusCode}: ${detail}`);
+        this.name = "InkboxAPIError";
+        this.statusCode = statusCode;
+        this.detail = detail;
+    }
+}
+export class HttpTransport {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    constructor(apiKey, baseUrl, timeoutMs = 30_000) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.timeoutMs = timeoutMs;
+    }
+    async get(path, params) {
+        return this.request("GET", path, { params });
+    }
+    async post(path, body) {
+        return this.request("POST", path, { body });
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, { body });
+    }
+    async delete(path) {
+        await this.request("DELETE", path);
+    }
+    async request(method, path, opts = {}) {
+        let url = `${this.baseUrl}${path}`;
+        if (opts.params) {
+            const qs = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.params)) {
+                if (v !== undefined && v !== null) {
+                    qs.set(k, String(v));
+                }
+            }
+            const s = qs.toString();
+            if (s)
+                url += `?${s}`;
+        }
+        const headers = {
+            "X-Service-Token": this.apiKey,
+            Accept: "application/json",
+        };
+        let bodyStr;
+        if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            bodyStr = JSON.stringify(opts.body);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method,
+                headers,
+                body: bodyStr,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!resp.ok) {
+            let detail;
+            try {
+                const err = (await resp.json());
+                detail = err.detail ?? resp.statusText;
+            }
+            catch {
+                detail = resp.statusText;
+            }
+            throw new InkboxAPIError(resp.status, detail);
+        }
+        if (resp.status === 204) {
+            return undefined;
+        }
+        return resp.json();
+    }
+}
+//# sourceMappingURL=_http.js.map

package/dist/_http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_http.js","sourceRoot":"","sources":["../src/_http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,UAAU,CAAS;IACnB,MAAM,CAAS;IAExB,YAAY,UAAkB,EAAE,MAAc;QAC5C,KAAK,CAAC,QAAQ,UAAU,KAAK,MAAM,EAAE,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAID,MAAM,OAAO,aAAa;IAEL;IACA;IACA;IAHnB,YACmB,MAAc,EACd,OAAe,EACf,YAAoB,MAAM;QAF1B,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAQ;QACf,cAAS,GAAT,SAAS,CAAiB;IAC1C,CAAC;IAEJ,KAAK,CAAC,GAAG,CAAI,IAAY,EAAE,MAAe;QACxC,OAAO,IAAI,CAAC,OAAO,CAAI,KAAK,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAc;QACxC,OAAO,IAAI,CAAC,OAAO,CAAI,MAAM,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,KAAK,CAAI,IAAY,EAAE,IAAa;QACxC,OAAO,IAAI,CAAC,OAAO,CAAI,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY;QACvB,MAAM,IAAI,CAAC,OAAO,CAAO,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC3C,CAAC;IAEO,KAAK,CAAC,OAAO,CACnB,MAAc,EACd,IAAY,EACZ,OAA4C,EAAE;QAE9C,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QAEnC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;YACjC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjD,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;oBAClC,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;gBACvB,CAAC;YACH,CAAC;YACD,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;YACxB,IAAI,CAAC;gBAAE,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;QACxB,CAAC;QAED,MAAM,OAAO,GAA2B;YACtC,iBAAiB,EAAE,IAAI,CAAC,MAAM;YAC9B,MAAM,EAAE,kBAAkB;SAC3B,CAAC;QAEF,IAAI,OAA2B,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YAC7C,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAEnE,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBACtB,MAAM;gBACN,OAAO;gBACP,IAAI,EAAE,OAAO;gBACb,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,IAAI,MAAc,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAwB,CAAC;gBACvD,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC;YACzC,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;YAC3B,CAAC;YACD,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChD,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACxB,OAAO,SAAc,CAAC;QACxB,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,EAAgB,CAAC;IACnC,CAAC;CACF"}

package/dist/agent_identity.d.ts

@@ -0,0 +1,184 @@
+/**
+ * inkbox/src/agent.ts
+ *
+ * AgentIdentity — a domain object representing one agent identity.
+ * Returned by inkbox.createIdentity() and inkbox.getIdentity().
+ *
+ * Convenience methods (sendEmail, placeCall, etc.) are scoped to this
+ * identity's assigned channels so callers never need to pass an email
+ * address or phone number ID explicitly.
+ */
+import type { Message, ThreadDetail } from "./mail/types.js";
+import type { PhoneCall, PhoneCallWithRateLimit, PhoneTranscript } from "./phone/types.js";
+import type { _AgentIdentityData, IdentityMailbox, IdentityPhoneNumber } from "./identities/types.js";
+import type { Inkbox } from "./inkbox.js";
+export declare class AgentIdentity {
+    private _data;
+    private readonly _inkbox;
+    private _mailbox;
+    private _phoneNumber;
+    constructor(data: _AgentIdentityData, inkbox: Inkbox);
+    get agentHandle(): string;
+    get id(): string;
+    get status(): string;
+    /** The mailbox currently assigned to this identity, or `null` if none. */
+    get mailbox(): IdentityMailbox | null;
+    /** The phone number currently assigned to this identity, or `null` if none. */
+    get phoneNumber(): IdentityPhoneNumber | null;
+    /**
+     * Create a new mailbox and link it to this identity.
+     *
+     * @param options.displayName - Optional human-readable sender name.
+     * @returns The newly created and linked {@link IdentityMailbox}.
+     */
+    createMailbox(options?: {
+        displayName?: string;
+    }): Promise<IdentityMailbox>;
+    /**
+     * Link an existing mailbox to this identity.
+     *
+     * @param mailboxId - UUID of the mailbox to link. Obtain via
+     *   `inkbox.mailboxes.list()` or `inkbox.mailboxes.get()`.
+     * @returns The linked {@link IdentityMailbox}.
+     */
+    assignMailbox(mailboxId: string): Promise<IdentityMailbox>;
+    /**
+     * Unlink this identity's mailbox (does not delete the mailbox).
+     */
+    unlinkMailbox(): Promise<void>;
+    /**
+     * Provision a new phone number and link it to this identity.
+     *
+     * @param options.type - `"toll_free"` (default) or `"local"`.
+     * @param options.state - US state abbreviation (e.g. `"NY"`), valid for local numbers only.
+     * @returns The newly provisioned and linked {@link IdentityPhoneNumber}.
+     */
+    provisionPhoneNumber(options?: {
+        type?: string;
+        state?: string;
+    }): Promise<IdentityPhoneNumber>;
+    /**
+     * Link an existing phone number to this identity.
+     *
+     * @param phoneNumberId - UUID of the phone number to link. Obtain via
+     *   `inkbox.phoneNumbers.list()` or `inkbox.phoneNumbers.get()`.
+     * @returns The linked {@link IdentityPhoneNumber}.
+     */
+    assignPhoneNumber(phoneNumberId: string): Promise<IdentityPhoneNumber>;
+    /**
+     * Unlink this identity's phone number (does not release the number).
+     */
+    unlinkPhoneNumber(): Promise<void>;
+    /**
+     * Send an email from this identity's mailbox.
+     *
+     * @param options.to - Primary recipient addresses (at least one required).
+     * @param options.subject - Email subject line.
+     * @param options.bodyText - Plain-text body.
+     * @param options.bodyHtml - HTML body.
+     * @param options.cc - Carbon-copy recipients.
+     * @param options.bcc - Blind carbon-copy recipients.
+     * @param options.inReplyToMessageId - RFC 5322 Message-ID to thread a reply.
+     * @param options.attachments - File attachments.
+     */
+    sendEmail(options: {
+        to: string[];
+        subject: string;
+        bodyText?: string;
+        bodyHtml?: string;
+        cc?: string[];
+        bcc?: string[];
+        inReplyToMessageId?: string;
+        attachments?: Array<{
+            filename: string;
+            contentType: string;
+            contentBase64: string;
+        }>;
+    }): Promise<Message>;
+    /**
+     * Iterate over emails in this identity's inbox, newest first.
+     *
+     * Pagination is handled automatically.
+     *
+     * @param options.pageSize - Messages fetched per API call (1–100). Defaults to 50.
+     * @param options.direction - Filter by `"inbound"` or `"outbound"`.
+     */
+    iterEmails(options?: {
+        pageSize?: number;
+        direction?: "inbound" | "outbound";
+    }): AsyncGenerator<Message>;
+    /**
+     * Iterate over unread emails in this identity's inbox, newest first.
+     *
+     * Fetches all messages and filters client-side. Pagination is handled automatically.
+     *
+     * @param options.pageSize - Messages fetched per API call (1–100). Defaults to 50.
+     * @param options.direction - Filter by `"inbound"` or `"outbound"`.
+     */
+    iterUnreadEmails(options?: {
+        pageSize?: number;
+        direction?: "inbound" | "outbound";
+    }): AsyncGenerator<Message>;
+    /**
+     * Mark a list of messages as read.
+     *
+     * @param messageIds - IDs of the messages to mark as read.
+     */
+    markEmailsRead(messageIds: string[]): Promise<void>;
+    /**
+     * Get a thread with all its messages inlined (oldest-first).
+     *
+     * @param threadId - UUID of the thread to fetch. Obtain via `msg.threadId`
+     *   on any {@link Message}.
+     */
+    getThread(threadId: string): Promise<ThreadDetail>;
+    /**
+     * Place an outbound call from this identity's phone number.
+     *
+     * @param options.toNumber - E.164 destination number.
+     * @param options.clientWebsocketUrl - WebSocket URL (wss://) for audio bridging.
+     * @param options.webhookUrl - Custom webhook URL for call lifecycle events.
+     */
+    placeCall(options: {
+        toNumber: string;
+        clientWebsocketUrl?: string;
+        webhookUrl?: string;
+    }): Promise<PhoneCallWithRateLimit>;
+    /**
+     * List calls made to/from this identity's phone number.
+     *
+     * @param options.limit - Maximum number of results. Defaults to 50.
+     * @param options.offset - Pagination offset. Defaults to 0.
+     */
+    listCalls(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PhoneCall[]>;
+    /**
+     * List transcript segments for a specific call.
+     *
+     * @param callId - ID of the call to fetch transcripts for.
+     */
+    listTranscripts(callId: string): Promise<PhoneTranscript[]>;
+    /**
+     * Update this identity's handle or status.
+     *
+     * @param options.newHandle - New agent handle.
+     * @param options.status - New lifecycle status: `"active"` or `"paused"`.
+     */
+    update(options: {
+        newHandle?: string;
+        status?: string;
+    }): Promise<void>;
+    /**
+     * Re-fetch this identity from the API and update cached channels.
+     *
+     * @returns `this` for chaining.
+     */
+    refresh(): Promise<AgentIdentity>;
+    /** Soft-delete this identity (unlinks channels without deleting them). */
+    delete(): Promise<void>;
+    private _requireMailbox;
+    private _requirePhone;
+}
+//# sourceMappingURL=agent_identity.d.ts.map

package/dist/agent_identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_identity.d.ts","sourceRoot":"","sources":["../src/agent_identity.ts"],"names":[],"mappings":"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"}