@vellumai/assistant 0.4.35 → 0.4.37

package/src/cli/contacts.ts

@@ -0,0 +1,471 @@
+import type { Command } from "commander";
+
+import {
+  getAssistantContactMetadata,
+  getContact,
+  listContacts,
+  mergeContacts,
+  searchContacts,
+} from "../contacts/contact-store.js";
+import type { ContactRole } from "../contacts/types.js";
+import { initializeDb } from "../memory/db.js";
+import {
+  createIngressInvite,
+  listIngressInvites,
+  redeemIngressInvite,
+  redeemVoiceInviteCode,
+  revokeIngressInvite,
+} from "../runtime/invite-service.js";
+import { writeOutput } from "./integrations.js";
+
+export function registerContactsCommand(program: Command): void {
+  const contacts = program
+    .command("contacts")
+    .description("Manage and query the contact graph")
+    .option("--json", "Machine-readable compact JSON output");
+
+  contacts.addHelpText(
+    "after",
+    `
+Contacts represent people and entities the assistant interacts with. Each
+contact is identified by a UUID, has a role (contact or guardian), and
+can be linked to external identifiers — phone numbers,
+Telegram IDs, email addresses — via channel memberships. The contact graph
+is the source of truth for identity resolution across all channels.
+
+Examples:
+  $ vellum contacts list
+  $ vellum contacts get abc-123
+  $ vellum contacts merge keep-id merge-id
+  $ vellum contacts invites list`,
+  );
+
+  contacts
+    .command("list")
+    .description("List contacts")
+    .option("--role <role>", "Filter by role (default: contact)", "contact")
+    .option("--limit <limit>", "Maximum number of contacts to return")
+    .option("--query <query>", "Search query to filter contacts")
+    .addHelpText(
+      "after",
+      `
+Lists contacts with optional filtering. The --role flag accepts: contact
+or guardian (defaults to contact). The --limit flag sets
+the maximum number of results (defaults to 50).
+
+When --query is provided, a full-text search is performed across contact
+names and linked external identifiers (phone numbers, emails, Telegram
+usernames). Without --query, returns all contacts matching the role filter.
+
+Examples:
+  $ vellum contacts list
+  $ vellum contacts list --role guardian
+  $ vellum contacts list --query "john" --limit 10
+  $ vellum contacts list --role guardian --json`,
+    )
+    .action(
+      async (
+        opts: {
+          role?: string;
+          limit?: string;
+          query?: string;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          initializeDb();
+          const role = opts.role as ContactRole | undefined;
+          const limit = opts.limit ? Number(opts.limit) : undefined;
+
+          const effectiveLimit = limit ?? 50;
+
+          const results = opts.query
+            ? searchContacts({ query: opts.query, role, limit: effectiveLimit })
+            : listContacts(effectiveLimit, role);
+
+          writeOutput(cmd, { ok: true, contacts: results });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  contacts
+    .command("get <id>")
+    .description("Get a contact by ID")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  id   UUID of the contact to retrieve
+
+Returns the full contact record including role, display name, and all
+channel memberships (phone numbers, Telegram IDs, email addresses, etc.).
+For assistant-type contacts, additional assistant metadata is included.
+
+Examples:
+  $ vellum contacts get 7a3b1c2d-4e5f-6789-abcd-ef0123456789
+  $ vellum contacts get abc-123 --json`,
+    )
+    .action(async (id: string, _opts: unknown, cmd: Command) => {
+      try {
+        initializeDb();
+        const contact = getContact(id);
+        if (!contact) {
+          writeOutput(cmd, { ok: false, error: "Contact not found" });
+          process.exitCode = 1;
+          return;
+        }
+        const assistantMeta =
+          contact.contactType === "assistant"
+            ? getAssistantContactMetadata(contact.id)
+            : undefined;
+        writeOutput(cmd, {
+          ok: true,
+          contact,
+          assistantMetadata: assistantMeta ?? undefined,
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  contacts
+    .command("merge <keepId> <mergeId>")
+    .description("Merge two contacts")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  keepId    UUID of the surviving contact that will absorb the other
+  mergeId   UUID of the contact to be merged and deleted
+
+All channel memberships, conversation history, and metadata from mergeId
+are transferred to keepId. After the merge, mergeId is permanently deleted.
+This operation is irreversible.
+
+Examples:
+  $ vellum contacts merge 7a3b1c2d-4e5f-6789-abcd-ef0123456789 9f8e7d6c-5b4a-3210-fedc-ba9876543210
+  $ vellum contacts merge keep-id merge-id --json`,
+    )
+    .action(
+      async (keepId: string, mergeId: string, _opts: unknown, cmd: Command) => {
+        try {
+          initializeDb();
+          const contact = mergeContacts(keepId, mergeId);
+          writeOutput(cmd, { ok: true, contact });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  const invites = contacts
+    .command("invites")
+    .description("Manage contact invites");
+
+  invites.addHelpText(
+    "after",
+    `
+Invites are tokens that grant channel access when redeemed. Each invite is
+tied to a source channel (telegram, voice, sms, email, whatsapp) and can
+optionally have usage limits, expiration, and notes. When redeemed, the
+invite creates a channel membership linking a contact to an external
+identifier on the source channel.
+
+Examples:
+  $ vellum contacts invites list
+  $ vellum contacts invites create --source-channel telegram
+  $ vellum contacts invites revoke abc-123
+  $ vellum contacts invites redeem --token xyz-789 --source-channel telegram --external-user-id 12345`,
+  );
+
+  invites
+    .command("list", { isDefault: true })
+    .description("List invites")
+    .option("--source-channel <sourceChannel>", "Filter by source channel")
+    .option("--status <status>", "Filter by invite status")
+    .addHelpText(
+      "after",
+      `
+Lists all invites with optional filtering by source channel or status.
+Returns invite tokens, their source channels, usage counts, and expiration.
+
+Examples:
+  $ vellum contacts invites list
+  $ vellum contacts invites list --source-channel telegram
+  $ vellum contacts invites list --status active
+  $ vellum contacts invites list --source-channel voice --json`,
+    )
+    .action(
+      async (
+        opts: { sourceChannel?: string; status?: string },
+        cmd: Command,
+      ) => {
+        try {
+          initializeDb();
+          const result = listIngressInvites({
+            sourceChannel: opts.sourceChannel,
+            status: opts.status,
+          });
+          if (result.ok) {
+            writeOutput(cmd, { ok: true, invites: result.data });
+          } else {
+            writeOutput(cmd, result);
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  invites
+    .command("create")
+    .description("Create a new invite")
+    .requiredOption(
+      "--source-channel <channel>",
+      "Source channel (e.g. telegram, voice, sms, email, whatsapp)",
+    )
+    .option("--note <note>", "Optional note")
+    .option("--max-uses <n>", "Max redemptions")
+    .option("--expires-in-ms <ms>", "Expiry duration in milliseconds")
+    .option(
+      "--contact-name <name>",
+      "Contact name for personalizing instructions",
+    )
+    .option(
+      "--expected-external-user-id <id>",
+      "E.164 phone number (required for voice invites)",
+    )
+    .option("--friend-name <name>", "Friend name (required for voice invites)")
+    .option(
+      "--guardian-name <name>",
+      "Guardian name (required for voice invites)",
+    )
+    .addHelpText(
+      "after",
+      `
+Creates a new invite token for the specified source channel. The --source-channel
+flag is required and must be one of: telegram, voice, sms, email, whatsapp.
+
+Optional fields:
+  --note                        Free-text note attached to the invite
+  --max-uses                    Maximum number of times the invite can be redeemed
+  --expires-in-ms               Expiry duration in milliseconds from creation
+  --contact-name                Name used to personalize invite instructions
+
+Voice invites require three additional fields:
+  --expected-external-user-id   E.164 phone number of the expected caller (e.g. +15551234567)
+  --friend-name                 Name the contact uses for the assistant's owner
+  --guardian-name                Name of the guardian associated with this invite
+
+Examples:
+  $ vellum contacts invites create --source-channel telegram --note "For Alice" --max-uses 1
+  $ vellum contacts invites create --source-channel voice --expected-external-user-id "+15551234567" --friend-name "Alice" --guardian-name "Bob" --contact-name "Alice Smith"`,
+    )
+    .action(
+      async (
+        opts: {
+          sourceChannel: string;
+          note?: string;
+          maxUses?: string;
+          expiresInMs?: string;
+          contactName?: string;
+          expectedExternalUserId?: string;
+          friendName?: string;
+          guardianName?: string;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          const maxUses = opts.maxUses ? Number(opts.maxUses) : undefined;
+          if (maxUses !== undefined && !Number.isFinite(maxUses)) {
+            writeOutput(cmd, {
+              ok: false,
+              error: `--max-uses must be a number, got: ${opts.maxUses}`,
+            });
+            process.exitCode = 1;
+            return;
+          }
+          const expiresInMs = opts.expiresInMs
+            ? Number(opts.expiresInMs)
+            : undefined;
+          if (expiresInMs !== undefined && !Number.isFinite(expiresInMs)) {
+            writeOutput(cmd, {
+              ok: false,
+              error: `--expires-in-ms must be a number, got: ${opts.expiresInMs}`,
+            });
+            process.exitCode = 1;
+            return;
+          }
+          initializeDb();
+          const result = await createIngressInvite({
+            sourceChannel: opts.sourceChannel,
+            note: opts.note,
+            maxUses,
+            expiresInMs,
+            contactName: opts.contactName,
+            expectedExternalUserId: opts.expectedExternalUserId,
+            friendName: opts.friendName,
+            guardianName: opts.guardianName,
+          });
+          if (result.ok) {
+            writeOutput(cmd, { ok: true, invite: result.data });
+          } else {
+            writeOutput(cmd, result);
+          }
+          if (!result.ok) {
+            process.exitCode = 1;
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+
+  invites
+    .command("revoke <inviteId>")
+    .description("Revoke an active invite")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  inviteId   UUID of the invite to revoke
+
+Revokes an active invite so it can no longer be redeemed. Already-redeemed
+channel memberships are not affected. Returns the updated invite record.
+
+Examples:
+  $ vellum contacts invites revoke 7a3b1c2d-4e5f-6789-abcd-ef0123456789
+  $ vellum contacts invites revoke abc-123 --json`,
+    )
+    .action(async (inviteId: string, _opts: unknown, cmd: Command) => {
+      try {
+        initializeDb();
+        const result = revokeIngressInvite(inviteId);
+        if (result.ok) {
+          writeOutput(cmd, { ok: true, invite: result.data });
+        } else {
+          writeOutput(cmd, result);
+        }
+        if (!result.ok) process.exitCode = 1;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  invites
+    .command("redeem")
+    .description("Redeem an invite via token or voice code")
+    .option("--token <token>", "Invite token")
+    .option("--source-channel <channel>", "Channel for redemption")
+    .option("--external-user-id <id>", "External user ID")
+    .option("--external-chat-id <id>", "External chat ID")
+    .option("--code <code>", "6-digit voice code")
+    .option(
+      "--caller-external-user-id <phone>",
+      "E.164 phone number for voice code redemption",
+    )
+    .option("--assistant-id <id>", "Assistant ID for voice code redemption")
+    .addHelpText(
+      "after",
+      `
+Two redemption modes:
+
+1. Token-based redemption: Provide --token, --source-channel, and at
+   least one of --external-user-id or --external-chat-id. Creates a
+   channel membership linking the contact to the external identifier.
+
+2. Voice-code-based redemption: Provide --code (6-digit code) and
+   --caller-external-user-id (E.164 phone number). Optionally include
+   --assistant-id to scope the redemption to a specific assistant.
+
+Examples:
+  $ vellum contacts invites redeem --token xyz-789 --source-channel telegram --external-user-id 12345
+  $ vellum contacts invites redeem --code 123456 --caller-external-user-id "+15551234567"
+  $ vellum contacts invites redeem --code 654321 --caller-external-user-id "+15559876543" --assistant-id asst-abc --json`,
+    )
+    .action(
+      async (
+        opts: {
+          token?: string;
+          sourceChannel?: string;
+          externalUserId?: string;
+          externalChatId?: string;
+          code?: string;
+          callerExternalUserId?: string;
+          assistantId?: string;
+        },
+        cmd: Command,
+      ) => {
+        try {
+          initializeDb();
+          if (opts.code) {
+            if (!opts.callerExternalUserId) {
+              writeOutput(cmd, {
+                ok: false,
+                error:
+                  "--caller-external-user-id is required for voice code redemption",
+              });
+              process.exitCode = 1;
+              return;
+            }
+            const result = redeemVoiceInviteCode({
+              code: opts.code,
+              callerExternalUserId: opts.callerExternalUserId,
+              sourceChannel: "voice",
+              ...(opts.assistantId ? { assistantId: opts.assistantId } : {}),
+            });
+            if (result.ok) {
+              writeOutput(cmd, {
+                ok: true,
+                type: result.type,
+                memberId: result.memberId,
+                ...(result.type === "redeemed"
+                  ? { inviteId: result.inviteId }
+                  : {}),
+              });
+            } else {
+              writeOutput(cmd, { ok: false, error: result.reason });
+              process.exitCode = 1;
+            }
+          } else {
+            const result = redeemIngressInvite({
+              token: opts.token,
+              sourceChannel: opts.sourceChannel,
+              ...(opts.externalUserId
+                ? { externalUserId: opts.externalUserId }
+                : {}),
+              ...(opts.externalChatId
+                ? { externalChatId: opts.externalChatId }
+                : {}),
+            });
+            if (result.ok) {
+              writeOutput(cmd, { ok: true, invite: result.data });
+            } else {
+              writeOutput(cmd, result);
+            }
+            if (!result.ok) {
+              process.exitCode = 1;
+            }
+          }
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(cmd, { ok: false, error: message });
+          process.exitCode = 1;
+        }
+      },
+    );
+}