@xmtp/convos-cli 0.1.0

package/dist/commands/conversation/update-profile.js

@@ -0,0 +1,97 @@
+import { Args, Flags } from "@oclif/core";
+import { requireGroup } from "../../utils/xmtp.js";
+import { ConvosBaseCommand } from "../../baseCommand.js";
+import { createClientForIdentity } from "../../utils/client.js";
+import { createIdentityStore } from "../../utils/identities.js";
+import { parseAppData, serializeAppData, upsertProfile, } from "../../utils/metadata.js";
+export default class UpdateProfile extends ConvosBaseCommand {
+    static description = `Set your display name and avatar in a conversation.
+
+Profiles are stored in the group's metadata (appData) and visible
+to all members. Each conversation has independent profiles — you
+can be a different person in each conversation (ADR 005).
+
+Updates are synced to all members via XMTP's group metadata.
+The profile is stored as a compressed protobuf in the group's
+appData field (max 8KB shared across all profiles and metadata).`;
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %> <conversation-id> --name "Alice"',
+            description: "Set your display name",
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> <conversation-id> --name "Alice" --image "https://example.com/avatar.jpg"',
+            description: "Set display name and avatar",
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> <conversation-id> --name "" --image ""',
+            description: "Clear your profile (go anonymous)",
+        },
+    ];
+    static args = {
+        id: Args.string({
+            description: "The conversation ID",
+            required: true,
+        }),
+    };
+    static flags = {
+        ...ConvosBaseCommand.baseFlags,
+        name: Flags.string({
+            description: "Display name (empty string to clear)",
+            helpValue: "<name>",
+        }),
+        image: Flags.string({
+            description: "Avatar image URL (empty string to clear)",
+            helpValue: "<url>",
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(UpdateProfile);
+        const config = this.getConvosConfig();
+        const store = createIdentityStore();
+        if (flags.name === undefined && flags.image === undefined) {
+            this.error("At least one of --name or --image must be provided");
+        }
+        const identity = store.getByConversationId(args.id);
+        if (!identity) {
+            this.error(`No identity found for conversation ${args.id}`);
+        }
+        const client = await createClientForIdentity(identity, config);
+        await client.conversations.sync();
+        const conversation = await client.conversations.getConversationById(args.id);
+        if (!conversation) {
+            this.error(`Conversation ${args.id} not found`);
+        }
+        const group = requireGroup(conversation);
+        // Parse current metadata
+        let appData = "";
+        try {
+            appData = group.appData ?? "";
+        }
+        catch {
+            // No appData yet
+        }
+        let metadata = parseAppData(appData);
+        // Build profile update
+        const profile = {
+            inboxId: client.inboxId,
+            ...(flags.name !== undefined ? { name: flags.name || undefined } : {}),
+            ...(flags.image !== undefined ? { image: flags.image || undefined } : {}),
+        };
+        metadata = upsertProfile(metadata, profile);
+        // Serialize and push
+        const newAppData = serializeAppData(metadata);
+        await group.updateAppData(newAppData);
+        // Also update local identity store
+        if (flags.name !== undefined) {
+            store.update(identity.id, { profileName: flags.name || undefined });
+        }
+        this.output({
+            conversationId: args.id,
+            inboxId: client.inboxId,
+            name: flags.name ?? "(unchanged)",
+            image: flags.image ?? "(unchanged)",
+            message: "Profile updated",
+        });
+    }
+}

package/dist/commands/conversations/create.d.ts

@@ -0,0 +1,26 @@
+import { ConvosBaseCommand } from "../../baseCommand.js";
+export default class ConversationsCreate extends ConvosBaseCommand {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "image-url": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        permissions: import("@oclif/core/interfaces").OptionFlag<"all-members" | "admin-only", import("@oclif/core/interfaces").CustomOptions>;
+        identity: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "profile-name": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "log-level": import("@oclif/core/interfaces").OptionFlag<"off" | "error" | "warn" | "info" | "debug" | "trace" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "structured-logging": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "app-version": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "env-file": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<"local" | "dev" | "production" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "gateway-host": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/conversations/create.js

@@ -0,0 +1,165 @@
+import { Flags } from "@oclif/core";
+import { getAccountAddress } from "../../utils/xmtp.js";
+import qrcode from "qrcode-terminal";
+import { ConvosBaseCommand } from "../../baseCommand.js";
+import { createClientForIdentity } from "../../utils/client.js";
+import { createIdentityStore } from "../../utils/identities.js";
+import { createInviteSlug } from "../../utils/invite.js";
+import { serializeAppData, upsertProfile } from "../../utils/metadata.js";
+import { randomAlphanumeric } from "../../utils/random.js";
+export default class ConversationsCreate extends ConvosBaseCommand {
+    static description = `Create a new Convos conversation.
+
+Creates a new conversation with a fresh per-conversation identity.
+Each conversation gets its own XMTP inbox for privacy isolation
+(per ADR 002).
+
+This command:
+1. Creates a new identity (or uses an existing unlinked one)
+2. Initializes the XMTP client for that identity
+3. Creates a group conversation
+4. Links the identity to the conversation
+
+The creator becomes super admin. Others join via invite links.`;
+    static examples = [
+        {
+            command: '<%= config.bin %> <%= command.id %> --name "Project Team"',
+            description: "Create a named conversation",
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> --name "Team" --description "Team discussion"',
+            description: "Create with metadata",
+        },
+        {
+            command: "<%= config.bin %> <%= command.id %> --identity <identity-id>",
+            description: "Use a pre-created identity",
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> --name "Private" --permissions admin-only --json',
+            description: "Create admin-only group with JSON output",
+        },
+    ];
+    static flags = {
+        ...ConvosBaseCommand.baseFlags,
+        name: Flags.string({
+            description: "Conversation name",
+            helpValue: "<name>",
+        }),
+        description: Flags.string({
+            description: "Conversation description",
+            helpValue: "<description>",
+        }),
+        "image-url": Flags.string({
+            description: "Conversation image URL",
+            helpValue: "<url>",
+        }),
+        permissions: Flags.option({
+            options: ["all-members", "admin-only"],
+            description: "Permission preset",
+            default: "all-members",
+        })(),
+        identity: Flags.string({
+            description: "Use an existing unlinked identity ID",
+            helpValue: "<id>",
+        }),
+        label: Flags.string({
+            description: "Local label for the identity",
+            helpValue: "<label>",
+        }),
+        "profile-name": Flags.string({
+            description: "Profile display name for this conversation",
+            helpValue: "<name>",
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(ConversationsCreate);
+        const config = this.getConvosConfig();
+        const store = createIdentityStore();
+        // Get or create identity
+        let identity;
+        if (flags.identity) {
+            identity = store.get(flags.identity);
+            if (!identity) {
+                this.error(`Identity not found: ${flags.identity}`);
+            }
+            if (identity.conversationId) {
+                this.error(`Identity ${flags.identity} is already linked to conversation ${identity.conversationId}`);
+            }
+        }
+        else {
+            identity = store.create({
+                label: flags.label ?? flags.name,
+                profileName: flags["profile-name"],
+            });
+        }
+        const client = await createClientForIdentity(identity, config);
+        const permissionsMap = {
+            "all-members": 0 /* GroupPermissionsOptions.Default */,
+            "admin-only": 1 /* GroupPermissionsOptions.AdminOnly */,
+        };
+        const options = {
+            groupName: flags.name,
+            groupDescription: flags.description,
+            groupImageUrlSquare: flags["image-url"],
+            permissions: permissionsMap[flags.permissions],
+        };
+        // Convos conversations start with just the creator
+        const group = await client.conversations.createGroup([], options);
+        // Generate invite tag
+        const inviteTag = randomAlphanumeric(10);
+        store.update(identity.id, {
+            conversationId: group.id,
+            inboxId: client.inboxId,
+            inviteTag,
+            label: flags.label ?? flags.name ?? identity.label,
+            profileName: flags["profile-name"] ?? identity.profileName,
+        });
+        // Store invite tag in appData
+        let metadata = { tag: inviteTag, profiles: [] };
+        // Write creator's profile to shared metadata so other members can see it
+        const profileName = flags["profile-name"];
+        if (profileName) {
+            metadata = upsertProfile(metadata, {
+                inboxId: client.inboxId,
+                name: profileName,
+            });
+        }
+        await group.updateAppData(serializeAppData(metadata));
+        // Generate invite slug and URL
+        const slug = await createInviteSlug(group.id, client.inboxId, inviteTag, identity.walletKey, {
+            name: flags.name || undefined,
+            description: flags.description || undefined,
+        });
+        const env = config.env ?? "dev";
+        const baseUrl = env === "production"
+            ? "https://popup.convos.org/v2"
+            : "https://dev.convos.org/v2";
+        const inviteUrl = `${baseUrl}?i=${encodeURIComponent(slug)}`;
+        // Display QR code unless --json
+        if (!flags.json) {
+            this.log(""); // blank line before QR
+            await new Promise((resolve) => {
+                qrcode.generate(inviteUrl, { small: true }, (code) => {
+                    this.log(code);
+                    resolve();
+                });
+            });
+            this.log(`  ${inviteUrl}\n`);
+        }
+        this.output({
+            conversationId: group.id,
+            identityId: identity.id,
+            address: getAccountAddress(identity.walletKey),
+            inboxId: client.inboxId,
+            name: flags.name ?? "",
+            description: flags.description ?? "",
+            permissions: flags.permissions,
+            createdAt: group.createdAt.toISOString(),
+            invite: {
+                slug,
+                url: inviteUrl,
+                tag: inviteTag,
+            },
+        });
+    }
+}

package/dist/commands/conversations/join.d.ts

@@ -0,0 +1,27 @@
+import { ConvosBaseCommand } from "../../baseCommand.js";
+export default class ConversationsJoin extends ConvosBaseCommand {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static args: {
+        invite: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        "no-wait": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        timeout: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        label: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "profile-name": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        identity: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "log-level": import("@oclif/core/interfaces").OptionFlag<"off" | "error" | "warn" | "info" | "debug" | "trace" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "structured-logging": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "app-version": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "env-file": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<"local" | "dev" | "production" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "gateway-host": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/conversations/join.js

@@ -0,0 +1,232 @@
+import { Args, Flags } from "@oclif/core";
+import { getAccountAddress, isGroup } from "../../utils/xmtp.js";
+import { ConvosBaseCommand } from "../../baseCommand.js";
+import { createClientForIdentity } from "../../utils/client.js";
+import { createIdentityStore } from "../../utils/identities.js";
+import { parseInvite, verifyInvite, inviteToSlug } from "../../utils/invite.js";
+import { parseAppData, serializeAppData, upsertProfile, } from "../../utils/metadata.js";
+export default class ConversationsJoin extends ConvosBaseCommand {
+    static description = `Join a conversation using an invite slug or URL.
+
+Implements the Convos join flow (per ADR 001):
+
+1. Parse and validate the invite (verify signature, check expiration)
+2. Create a new per-conversation identity for this conversation
+3. Send the invite slug as a DM to the creator's inbox
+4. Wait for the creator's client to process the join request and
+   add this identity to the conversation
+5. Link the identity to the conversation once joined
+
+The creator's client (iOS app or another CLI instance running
+'convos conversations process-join-requests') must be online to
+process the join request.
+
+Accepts either a raw invite slug or a full URL containing the
+slug as query parameter 'i'.`;
+    static examples = [
+        {
+            command: "<%= config.bin %> <%= command.id %> <invite-slug>",
+            description: "Join using a raw invite slug",
+        },
+        {
+            command: '<%= config.bin %> <%= command.id %> "https://popup.convos.org/v2?i=<slug>"',
+            description: "Join using a full invite URL",
+        },
+        {
+            command: "<%= config.bin %> <%= command.id %> <slug> --no-wait",
+            description: "Send join request without waiting for acceptance",
+        },
+        {
+            command: "<%= config.bin %> <%= command.id %> <slug> --timeout 120 --json",
+            description: "Wait up to 2 minutes for acceptance",
+        },
+    ];
+    static args = {
+        invite: Args.string({
+            description: "Invite slug or URL",
+            required: true,
+        }),
+    };
+    static flags = {
+        ...ConvosBaseCommand.baseFlags,
+        "no-wait": Flags.boolean({
+            description: "Send the join request but don't wait for the creator to accept",
+            default: false,
+        }),
+        timeout: Flags.integer({
+            description: "Seconds to wait for acceptance (default: 60)",
+            helpValue: "<seconds>",
+            default: 60,
+        }),
+        label: Flags.string({
+            description: "Local label for the new identity",
+            helpValue: "<label>",
+        }),
+        "profile-name": Flags.string({
+            description: "Profile display name for this conversation",
+            helpValue: "<name>",
+        }),
+        identity: Flags.string({
+            description: "Use an existing unlinked identity instead of creating one",
+            helpValue: "<id>",
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(ConversationsJoin);
+        const config = this.getConvosConfig();
+        const store = createIdentityStore();
+        // Step 1: Parse invite
+        const invite = parseInvite(args.invite);
+        // Validate
+        if (!(await verifyInvite(invite))) {
+            this.error("Invalid invite signature");
+        }
+        if (invite.expiresAt && invite.expiresAt < new Date()) {
+            this.error("Invite has expired");
+        }
+        if (invite.conversationExpiresAt && invite.conversationExpiresAt < new Date()) {
+            this.error("Conversation has expired");
+        }
+        this.log(`Invite parsed: tag=${invite.tag}` +
+            (invite.name ? ` name="${invite.name}"` : "") +
+            ` creator=${invite.creatorInboxId.slice(0, 12)}...`);
+        // Check if we've already joined this conversation (same invite tag)
+        const existingIdentity = store.getByInviteTag(invite.tag);
+        if (existingIdentity) {
+            this.error(`Already joined this conversation.\n` +
+                `  Identity: ${existingIdentity.id}\n` +
+                `  Conversation: ${existingIdentity.conversationId ?? "(pending)"}\n` +
+                `  Label: ${existingIdentity.label ?? ""}\n\n` +
+                `Use 'convos conversation send-text ${existingIdentity.conversationId ?? "<id>"}' to send messages.`);
+        }
+        // Step 2: Get or create identity
+        let identity;
+        if (flags.identity) {
+            identity = store.get(flags.identity);
+            if (!identity)
+                this.error(`Identity not found: ${flags.identity}`);
+            if (identity.conversationId) {
+                this.error(`Identity already linked to conversation ${identity.conversationId}`);
+            }
+        }
+        else {
+            identity = store.create({
+                label: flags.label ?? invite.name,
+                profileName: flags["profile-name"],
+            });
+        }
+        // Store invite tag immediately so duplicate detection works even if we exit early
+        store.update(identity.id, { inviteTag: invite.tag });
+        // Step 3: Create XMTP client and send DM to creator
+        const client = await createClientForIdentity(identity, config);
+        this.log(`Created identity ${identity.id.slice(0, 12)}... (${getAccountAddress(identity.walletKey)})`);
+        this.log(`Sending join request to creator inbox ${invite.creatorInboxId.slice(0, 12)}...`);
+        // Create DM with creator using their XMTP inbox ID
+        const dm = await client.conversations.createDm(invite.creatorInboxId);
+        // Send the invite slug as the join request
+        const slug = inviteToSlug(invite);
+        await dm.sendText(slug);
+        this.log("Join request sent.");
+        if (flags["no-wait"]) {
+            this.output({
+                status: "request_sent",
+                identityId: identity.id,
+                address: getAccountAddress(identity.walletKey),
+                inboxId: client.inboxId,
+                creatorInboxId: invite.creatorInboxId,
+                tag: invite.tag,
+                name: invite.name ?? null,
+                message: "Join request sent. The creator must accept it. " +
+                    "Run 'convos conversations list --sync' to check if you've been added.",
+            });
+            return;
+        }
+        // Step 4: Wait for acceptance (poll for new group conversations)
+        this.log(`Waiting for acceptance (timeout: ${flags.timeout}s)...`);
+        const startTime = Date.now();
+        const timeoutMs = flags.timeout * 1000;
+        let conversationId;
+        while (Date.now() - startTime < timeoutMs) {
+            await client.conversations.sync();
+            const conversations = await client.conversations.list();
+            // Look for a new group conversation (not the DM we created)
+            for (const conv of conversations) {
+                if (conv.id !== dm.id) {
+                    conversationId = conv.id;
+                    break;
+                }
+            }
+            if (conversationId)
+                break;
+            // Poll every 2 seconds
+            await new Promise((resolve) => setTimeout(resolve, 2000));
+        }
+        if (!conversationId) {
+            this.log("Timed out waiting for acceptance.");
+            this.output({
+                status: "timeout",
+                identityId: identity.id,
+                address: getAccountAddress(identity.walletKey),
+                inboxId: client.inboxId,
+                tag: invite.tag,
+                message: "The creator has not yet accepted the join request. " +
+                    "Run 'convos conversations list --sync' later to check.",
+            });
+            return;
+        }
+        // Step 5: Verify the group's invite tag matches the invite we used (ADR 001)
+        // This protects against being added to a different conversation than requested.
+        try {
+            const conv = await client.conversations.getConversationById(conversationId);
+            if (conv && isGroup(conv)) {
+                const appData = conv.appData ?? "";
+                const metadata = parseAppData(appData);
+                if (metadata.tag && metadata.tag !== invite.tag) {
+                    this.warn(`Invite tag mismatch: expected "${invite.tag}" but group has "${metadata.tag}". ` +
+                        "You may have been added to a different conversation than expected.");
+                }
+            }
+        }
+        catch {
+            // Non-fatal: tag verification is a safety check, don't block joining
+        }
+        // Step 6: Write joiner's profile to shared metadata
+        const profileName = flags["profile-name"];
+        if (profileName) {
+            try {
+                await client.conversations.sync();
+                const conv = await client.conversations.getConversationById(conversationId);
+                if (conv && isGroup(conv)) {
+                    await conv.sync();
+                    const appData = conv.appData ?? "";
+                    const metadata = parseAppData(appData);
+                    const updated = upsertProfile(metadata, {
+                        inboxId: client.inboxId,
+                        name: profileName,
+                    });
+                    await conv.updateAppData(serializeAppData(updated));
+                }
+            }
+            catch (error) {
+                this.warn(`Could not write profile to group metadata: ${error instanceof Error ? error.message : "unknown"}`);
+            }
+        }
+        // Step 7: Link identity to conversation
+        store.update(identity.id, {
+            conversationId,
+            inboxId: client.inboxId,
+            inviteTag: invite.tag,
+            label: flags.label ?? invite.name ?? identity.label,
+            profileName: flags["profile-name"] ?? identity.profileName,
+        });
+        this.output({
+            status: "joined",
+            conversationId,
+            identityId: identity.id,
+            address: getAccountAddress(identity.walletKey),
+            inboxId: client.inboxId,
+            tag: invite.tag,
+            name: invite.name ?? null,
+        });
+    }
+}

package/dist/commands/conversations/list.d.ts

@@ -0,0 +1,20 @@
+import { ConvosBaseCommand } from "../../baseCommand.js";
+export default class ConversationsList extends ConvosBaseCommand {
+    static description: string;
+    static examples: {
+        command: string;
+        description: string;
+    }[];
+    static flags: {
+        sync: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "log-level": import("@oclif/core/interfaces").OptionFlag<"off" | "error" | "warn" | "info" | "debug" | "trace" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "structured-logging": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "app-version": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "env-file": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").OptionFlag<"local" | "dev" | "production" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        "gateway-host": import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}