@getdial/cli 0.41.0 → 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";
@@ -309,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
@@ -411,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/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/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/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.41.0",
+  "version": "0.42.0",
   "description": "Dial CLI — install, sign up, and run the local listen service.",
   "license": "MIT",
   "repository": {