@getdial/cli 0.40.1 → 0.42.0

package/dist/cli.js

@@ -18,6 +18,7 @@ import { runNumberPurchase } from "./commands/number/purchase.js";
 import { runNumberSet } from "./commands/number/set.js";
 import { runNumberWhatsapp } from "./commands/number/whatsapp.js";
 import { runGroupList } from "./commands/group/list.js";
+import { runContactsList } from "./commands/contacts/list.js";
 import { runMessageSend } from "./commands/message/send.js";
 import { runMessageReply } from "./commands/message/reply.js";
 import { runMessageList } from "./commands/message/list.js";
@@ -216,6 +217,8 @@ number
     return n;
 })
     .option("--clear-max-call-duration", "remove the per-number call duration cap")
+    .option("--channel <imessage|whatsapp|both>", 'which display profile(s) --name and --avatar are written to; "both" sets one identity on every channel the number has, in a single call. Cannot be combined with --first-name/--last-name/--whatsapp-name/--whatsapp-avatar')
+    .option("--name <text>", 'display name for --channel (required alongside it); WhatsApp stores it verbatim (1-25 chars), iMessage splits it on the first space ("Maya Chen" -> Maya / Chen)')
     .option("--first-name <text>", 'iMessage display first name shown beside this number\'s messages (iMessage numbers only); pass "" to clear')
     .option("--last-name <text>", 'iMessage display last name (iMessage numbers only); pass "" to clear')
     .option("--avatar <path-or-url>", "iMessage avatar photo (iMessage numbers only): a local image file (jpeg/png/gif/webp, max 5 MB) to upload, or a public image URL to fetch. Replaces the current photo; photos can't be removed")
@@ -238,6 +241,8 @@ number
         inboundLanguage: opts.inboundLanguage,
         nickname: opts.nickname,
         maxCallDurationSeconds,
+        channel: opts.channel,
+        name: opts.name,
         firstName: opts.firstName,
         lastName: opts.lastName,
         avatar: opts.avatar,
@@ -305,15 +310,31 @@ message
     .command("list")
     .description("List recent messages on your account. GET /api/v1/messages.")
     .option("--number-id <id>", "filter to a single phone number")
+    .option("--contact <e164>", "one contact's conversation, both directions, across every line")
     .option("--group <id>", "filter to one group conversation (see `dial group list`)")
     .option("--direction <dir>", "inbound or outbound")
     .option("--since <iso8601>", "only messages created after this timestamp")
+    .option("--search <text>", "match message bodies containing this text (case-insensitive)")
     .option("--json", "machine-readable output")
     .action(async (opts) => process.exit(await runMessageList({
     numberId: opts.numberId,
+    contact: opts.contact,
     group: opts.group,
     direction: opts.direction,
     since: opts.since,
+    search: opts.search,
+    json: !!opts.json,
+})));
+program
+    .command("contacts")
+    .description("Every number your lines have texted or called, newest activity first. Walks every page " +
+    "unless you pass --limit. GET /api/v1/contacts.")
+    .option("--limit <n>", "return one page of at most n contacts (1-1000) instead of all", (v) => Number.parseInt(v, 10))
+    .option("--starting-after <iso8601>", "page cursor: the lastAt of the last contact you received")
+    .option("--json", "machine-readable output")
+    .action(async (opts) => process.exit(await runContactsList({
+    limit: opts.limit,
+    startingAfter: opts.startingAfter,
     json: !!opts.json,
 })));
 const group = program
@@ -407,11 +428,13 @@ call
     .command("list")
     .description("List recent calls on your account. GET /api/v1/calls.")
     .option("--number-id <id>", "filter to a single phone number")
+    .option("--contact <e164>", "one contact's calls, both directions, across every line")
     .option("--direction <dir>", "inbound or outbound")
     .option("--since <iso8601>", "only calls created after this timestamp")
     .option("--json", "machine-readable output")
     .action(async (opts) => process.exit(await runCallList({
     numberId: opts.numberId,
+    contact: opts.contact,
     direction: opts.direction,
     since: opts.since,
     json: !!opts.json,

package/dist/commands/call/list.js

@@ -5,6 +5,7 @@ export async function runCallList(opts) {
     try {
         const calls = await listCalls({
             numberId: opts.numberId,
+            contact: opts.contact,
             direction: opts.direction,
             since: opts.since,
         });

package/dist/commands/contacts/list.js

@@ -0,0 +1,59 @@
+import { listContacts, listAllContacts } from "../../lib/ops/contacts.js";
+import { isDialError } from "../../lib/ops/errors.js";
+import { printDialError } from "../../lib/cli-error.js";
+/**
+ * The preview line for one contact.
+ *
+ * The API reports facts, not a sentence, so the wording is chosen here — which also means the
+ * terminal and the dashboard can each say it their own way without the server picking for them.
+ */
+function preview(c) {
+    if (c.lastKind === "call") {
+        const direction = c.lastDirection === "inbound" ? "incoming" : "outgoing";
+        // 0 seconds means it never connected, so a duration is only worth printing above it.
+        return c.lastCallDuration ? `${direction} call, ${c.lastCallDuration}s` : `${direction} call`;
+    }
+    if (c.lastRedacted)
+        return "(deleted by retention)";
+    if (!c.lastBody)
+        return c.lastMediaCount > 0 ? `(${c.lastMediaCount} media)` : "";
+    const prefix = c.lastDirection === "inbound" ? "" : "you: ";
+    return `${prefix}${c.lastBody}`;
+}
+export async function runContactsList(opts) {
+    try {
+        // `--limit` asks for one page and gets exactly that, cursor included. Without it the command
+        // answers the question it is named for — who have I talked to — by walking every page.
+        const paged = opts.limit !== undefined || opts.startingAfter !== undefined;
+        const page = paged
+            ? await listContacts({ limit: opts.limit, startingAfter: opts.startingAfter })
+            : { contacts: await listAllContacts(), hasMore: false };
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: true, contacts: page.contacts, hasMore: page.hasMore }));
+            return 0;
+        }
+        if (page.contacts.length === 0) {
+            console.log("no contacts. a number appears here once one of your lines texts or calls it.");
+            return 0;
+        }
+        for (const c of page.contacts) {
+            const counts = [
+                c.messageCount > 0 ? `${c.messageCount} msg` : null,
+                c.callCount > 0 ? `${c.callCount} call` : null,
+            ]
+                .filter(Boolean)
+                .join(", ");
+            console.log(`${c.number.padEnd(16)}  ${c.lastAt}  ${counts.padEnd(18)}  ${preview(c)}`);
+        }
+        if (page.hasMore) {
+            const cursor = page.contacts[page.contacts.length - 1].lastAt;
+            console.log(`\nmore contacts. next page: dial contacts --starting-after ${cursor}`);
+        }
+        return 0;
+    }
+    catch (e) {
+        if (isDialError(e))
+            return printDialError(opts.json, e);
+        throw e;
+    }
+}

package/dist/commands/message/list.js

@@ -6,8 +6,10 @@ export async function runMessageList(opts) {
         const messages = await listMessages({
             numberId: opts.numberId,
             groupId: opts.group,
+            contact: opts.contact,
             direction: opts.direction,
             since: opts.since,
+            search: opts.search,
         });
         if (opts.json) {
             console.log(JSON.stringify({ ok: true, messages }));

package/dist/commands/number/set.js

@@ -14,6 +14,8 @@ export async function runNumberSet(opts) {
             ...(opts.maxCallDurationSeconds !== undefined
                 ? { maxCallDurationSeconds: opts.maxCallDurationSeconds }
                 : {}),
+            ...(opts.channel !== undefined ? { channel: opts.channel } : {}),
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
             ...(opts.firstName !== undefined ? { firstName: opts.firstName } : {}),
             ...(opts.lastName !== undefined ? { lastName: opts.lastName } : {}),
             ...(opts.avatar !== undefined ? { avatar: opts.avatar } : {}),

package/dist/lib/ops/calls.js

@@ -29,6 +29,8 @@ export async function listCalls(opts) {
         params.set("direction", opts.direction);
     if (opts.since)
         params.set("since", opts.since);
+    if (opts.contact)
+        params.set("contact", opts.contact);
     const qs = params.toString();
     const res = await apiGet(qs ? `/api/v1/calls?${qs}` : "/api/v1/calls", auth?.apiKey);
     if (!res.ok)

package/dist/lib/ops/contacts.js

@@ -0,0 +1,42 @@
+import { apiGet } from "../api.js";
+import { maybeAuth } from "./auth.js";
+import { DialError } from "./errors.js";
+/**
+ * One page of contacts — every number the account's lines have messaged or called.
+ *
+ * Shared by `dial contacts` and the local MCP `list_contacts` tool, so both speak to the API
+ * through one place and inherit the saved key the same way.
+ */
+export async function listContacts(opts = {}) {
+    const auth = maybeAuth();
+    const params = new URLSearchParams();
+    if (opts.limit !== undefined)
+        params.set("limit", String(opts.limit));
+    if (opts.startingAfter)
+        params.set("starting_after", opts.startingAfter);
+    const qs = params.toString();
+    const res = await apiGet(qs ? `/api/v1/contacts?${qs}` : "/api/v1/contacts", auth?.apiKey);
+    if (!res.ok)
+        throw new DialError("list_failed", res.error, res.status);
+    return { contacts: res.data.contacts ?? [], hasMore: res.data.hasMore ?? false };
+}
+/**
+ * Every contact, following the cursor until the API says there are no more.
+ *
+ * `dial contacts` answers "who have I talked to", and a first page is not an answer to that — so
+ * the default walks the pages. `--limit` opts back into a single page for a caller that wants one.
+ */
+export async function listAllContacts(pageSize = 1000) {
+    const all = [];
+    let startingAfter;
+    // Bounded rather than `while (hasMore)`: a bug at either end that always answered `hasMore:
+    // true` would otherwise loop forever against the network. 25 pages is 25,000 contacts.
+    for (let page = 0; page < 25; page++) {
+        const { contacts, hasMore } = await listContacts({ limit: pageSize, startingAfter });
+        all.push(...contacts);
+        if (!hasMore || contacts.length === 0)
+            break;
+        startingAfter = contacts[contacts.length - 1].lastAt;
+    }
+    return all;
+}

package/dist/lib/ops/messages.js

@@ -117,6 +117,10 @@ export async function listMessages(opts) {
         params.set("direction", opts.direction);
     if (opts.since)
         params.set("since", opts.since);
+    if (opts.search)
+        params.set("search", opts.search);
+    if (opts.contact)
+        params.set("contact", opts.contact);
     const qs = params.toString();
     const res = await apiGet(qs ? `/api/v1/messages?${qs}` : "/api/v1/messages", auth?.apiKey);
     if (!res.ok)

package/dist/lib/ops/numbers.js

@@ -117,6 +117,10 @@ export async function setNumberProperties(opts) {
         body.nickname = opts.nickname;
     if (opts.maxCallDurationSeconds !== undefined)
         body.maxCallDurationSeconds = opts.maxCallDurationSeconds;
+    if (opts.channel !== undefined)
+        body.channel = opts.channel;
+    if (opts.name !== undefined)
+        body.name = opts.name;
     if (opts.firstName !== undefined)
         body.firstName = opts.firstName;
     if (opts.lastName !== undefined)
@@ -137,7 +141,7 @@ export async function setNumberProperties(opts) {
     if (opts.whatsappAvatar !== undefined && !whatsappAvatarFile)
         body.whatsappAvatarUrl = opts.whatsappAvatar;
     if (Object.keys(body).length === 0 && !avatarFile && !whatsappAvatarFile) {
-        throw new DialError("bad_request", "Provide at least one property to update (inboundInstruction, inboundVoiceGender, inboundLanguage, nickname, maxCallDurationSeconds, calling, firstName, lastName, avatar, whatsappName, or whatsappAvatar).");
+        throw new DialError("bad_request", "Provide at least one property to update (inboundInstruction, inboundVoiceGender, inboundLanguage, nickname, maxCallDurationSeconds, calling, channel with name/avatar, firstName, lastName, avatar, whatsappName, or whatsappAvatar).");
     }
     const auth = maybeAuth();
     // The REST API keys numbers by id; the CLI/tool takes the E.164 number for ergonomics,

package/dist/mcp/schemas.js

@@ -85,6 +85,40 @@ export const groupSchema = z.object({
         .optional()
         .describe("ISO-8601: when Dial first learned of this group (a join, or its first message)"),
 });
+/**
+ * One derived contact. Mirrors the hosted server's `contactSchema`.
+ *
+ * The preview fields report facts rather than a sentence — `lastKind` selects whether `lastBody`
+ * or `lastCallDuration` means anything, and `lastRedacted` / `lastMediaCount` explain an empty
+ * `lastBody` — so an agent can word the summary itself.
+ */
+export const contactSchema = z.object({
+    number: z.string().describe("The contact's number, E.164 — pass as `contact` to list_messages"),
+    messageCount: z
+        .number()
+        .describe("One-to-one messages with this contact across every line on the account, both directions"),
+    callCount: z
+        .number()
+        .describe("Calls with this contact across every line on the account, both directions"),
+    lastAt: z.string().describe("ISO-8601 timestamp of the most recent message or call"),
+    lastDirection: z
+        .enum(["inbound", "outbound"])
+        .describe("Whether the most recent interaction came from them or you"),
+    lastKind: z.enum(["message", "call"]).describe("What the most recent interaction was"),
+    lastBody: z
+        .string()
+        .describe("The most recent message's text. Empty for a call, a media-only message, or a redacted one"),
+    lastMediaCount: z
+        .number()
+        .describe("Attachments on the most recent message; 0 for a call or a text-only message"),
+    lastRedacted: z
+        .boolean()
+        .describe("True when data retention cleared the most recent message's content"),
+    lastCallDuration: z
+        .number()
+        .nullable()
+        .describe("The most recent call's duration in seconds, or null when the most recent interaction was a message"),
+});
 export const messageSchema = z
     .object({
     id: z.string(),

package/dist/mcp/tools/index.js

@@ -7,6 +7,7 @@ import { startTypingTool } from "./start-typing.js";
 import { stopTypingTool } from "./stop-typing.js";
 import { listMessagesTool } from "./list-messages.js";
 import { listGroupsTool } from "./list-groups.js";
+import { listContactsTool } from "./list-contacts.js";
 import { placeCallTool } from "./place-call.js";
 import { listCallsTool } from "./list-calls.js";
 import { getCallTool } from "./get-call.js";
@@ -33,6 +34,7 @@ export const tools = [
     stopTypingTool,
     listMessagesTool,
     listGroupsTool,
+    listContactsTool,
     placeCallTool,
     listCallsTool,
     getCallTool,

package/dist/mcp/tools/list-calls.js

@@ -3,6 +3,10 @@ import { jsonResult } from "../result.js";
 import { listCalls } from "../../lib/ops/calls.js";
 import { callSchema } from "../schemas.js";
 const inputSchema = {
+    contact: z
+        .string()
+        .optional()
+        .describe("One conversation: calls exchanged with this number (E.164), both directions, across every line"),
     numberId: z.string().optional().describe("Filter to a single phone number id"),
     direction: z.enum(["inbound", "outbound"]).optional().describe("Filter by direction"),
     since: z.string().optional().describe("Only calls created after this ISO-8601 timestamp"),
@@ -11,7 +15,7 @@ export const listCallsTool = {
     name: "list_calls",
     config: {
         title: "List Calls",
-        description: "List recent calls on your account, newest first.",
+        description: "List recent calls on your account, newest first. Pass `contact` to read one person's call history.",
         inputSchema,
         outputSchema: { calls: z.array(callSchema) },
         annotations: { readOnlyHint: true, openWorldHint: true },
@@ -21,6 +25,7 @@ export const listCallsTool = {
             numberId: args.numberId,
             direction: args.direction,
             since: args.since,
+            contact: args.contact,
         }),
     }),
 };

package/dist/mcp/tools/list-contacts.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { jsonResult } from "../result.js";
+import { listContacts } from "../../lib/ops/contacts.js";
+import { contactSchema } from "../schemas.js";
+const inputSchema = {
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(1000)
+        .optional()
+        .describe("Max contacts to return (1-1000; default 100)"),
+    startingAfter: z
+        .string()
+        .optional()
+        .describe("ISO-8601 cursor — the lastAt of the last contact you received; returns only older ones"),
+};
+export const listContactsTool = {
+    name: "list_contacts",
+    config: {
+        title: "List Contacts",
+        description: "List every number your lines have exchanged a message or a call with, newest activity first, with " +
+            "per-contact counts and a summary of the most recent interaction. Derived from history — there is no " +
+            "address book to add anyone to. Counts span every line on the account, so one person reached on two of " +
+            "your numbers is one contact. Group conversations are not contacts; use list_groups for those. Pass a " +
+            "contact's `number` to list_messages as `contact` to read that one conversation.",
+        inputSchema,
+        outputSchema: { contacts: z.array(contactSchema), hasMore: z.boolean() },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    run: async (args) => jsonResult(await listContacts({
+        limit: args.limit,
+        startingAfter: args.startingAfter,
+    })),
+};

package/dist/mcp/tools/list-messages.js

@@ -3,6 +3,15 @@ import { jsonResult } from "../result.js";
 import { listMessages } from "../../lib/ops/messages.js";
 import { messageSchema } from "../schemas.js";
 const inputSchema = {
+    search: z
+        .string()
+        .optional()
+        .describe("Case-insensitive substring match on the message body; searches your whole history"),
+    contact: z
+        .string()
+        .optional()
+        .describe("One conversation: messages exchanged with this number (E.164), both directions, across " +
+        "every line. Group messages are never included — use groupId for those"),
     numberId: z.string().optional().describe("Filter to a single phone number id"),
     groupId: z
         .string()
@@ -15,9 +24,11 @@ export const listMessagesTool = {
     name: "list_messages",
     config: {
         title: "List Messages",
-        description: "List recent messages on your account, newest first. Pass groupId to read one group " +
-            "conversation. On a group message `to` is null and the destination is groupId; which of your " +
-            "numbers the conversation is on is phoneNumberId.",
+        description: "List recent messages on your account, newest first. Pass `contact` to read one person's " +
+            "whole conversation, or `groupId` to read one group's. Pass `search` to find messages by " +
+            "their text — that searches all of your history, then returns the 100 most recent matches. " +
+            "On a group message `to` is null and the destination is groupId; which of your numbers the " +
+            "conversation is on is phoneNumberId.",
         inputSchema,
         outputSchema: { messages: z.array(messageSchema) },
         annotations: { readOnlyHint: true, openWorldHint: true },
@@ -28,6 +39,8 @@ export const listMessagesTool = {
             groupId: args.groupId,
             direction: args.direction,
             since: args.since,
+            search: args.search,
+            contact: args.contact,
         }),
     }),
 };

package/dist/mcp/tools/set-number-properties.js

@@ -29,6 +29,15 @@ const inputSchema = {
         .nullable()
         .optional()
         .describe("Call duration cap for this number, in seconds, applied as a hard ceiling to both inbound and outbound calls (the smallest of the per-number, account, and per-call caps wins). On a free account (no top-up or subscription yet) a value above 300 is rejected with 400. Pass null to clear the cap; omit to leave it unchanged."),
+    channel: z
+        .enum(["imessage", "whatsapp", "both"])
+        .optional()
+        .describe('Which display profile(s) `name` and `avatarUrl` are written to: "imessage", "whatsapp", or "both". Use this when the number should present the same identity everywhere — one call instead of two, validated against every targeted channel before any of them is written, so the profiles cannot drift apart. Cannot be combined with firstName/lastName/whatsappName/whatsappAvatarUrl.'),
+    name: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The display name to set on the channel(s) `channel` names; requires `channel`. WhatsApp stores it verbatim (1-25 chars); iMessage has no single-name field, so it is split on the first space — "Ana Lee" becomes firstName "Ana", lastName "Lee".'),
     firstName: z
         .string()
         .max(30)
@@ -62,7 +71,7 @@ export const setNumberPropertiesTool = {
     name: "set_number_properties",
     config: {
         title: "Set Number Properties",
-        description: "Update a phone number's properties: its inbound instruction (the system prompt for inbound calls), inbound voice gender, inbound language, nickname, whether calling is switched on at all (callingEnabled), and — for iMessage numbers — its display identity (firstName, lastName, avatarUrl), and for WhatsApp-ready numbers its WhatsApp identity (whatsappName, whatsappAvatarUrl). Provide at least one.",
+        description: 'Update a phone number\'s properties: its inbound instruction (the system prompt for inbound calls), inbound voice gender, inbound language, nickname, whether calling is switched on at all (callingEnabled), and its display identity. For the display identity prefer `channel` ("imessage", "whatsapp", or "both") with `name`/`avatarUrl` — one call that keeps every channel\'s profile identical. The per-channel fields remain for when the profiles differ: firstName/lastName/avatarUrl for iMessage, whatsappName/whatsappAvatarUrl for WhatsApp-ready numbers. Provide at least one property, and don\'t mix `channel` with the per-channel fields.',
         inputSchema,
         outputSchema: { number: phoneNumberSchema },
         annotations: { openWorldHint: true },
@@ -81,6 +90,8 @@ export const setNumberPropertiesTool = {
             ...(args.maxCallDurationSeconds !== undefined
                 ? { maxCallDurationSeconds: args.maxCallDurationSeconds }
                 : {}),
+            ...(args.channel !== undefined ? { channel: args.channel } : {}),
+            ...(args.name !== undefined ? { name: args.name } : {}),
             ...(args.firstName !== undefined ? { firstName: args.firstName } : {}),
             ...(args.whatsappName !== undefined ? { whatsappName: args.whatsappName } : {}),
             ...(args.callingEnabled !== undefined

package/dist/mcp/tools/tool-names.js

@@ -30,6 +30,7 @@ export const OPERATIONAL_TOOL_NAMES = [
     "stop_typing",
     "list_messages",
     "list_groups",
+    "list_contacts",
     "place_call",
     "list_calls",
     "get_call",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getdial/cli",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "description": "Dial CLI — install, sign up, and run the local listen service.",
   "license": "MIT",
   "repository": {