resend-cli 1.1.0 → 1.2.0

package/.claude/worktrees/emails-list/src/commands/contacts/delete.ts

@@ -0,0 +1,49 @@
+import { Command } from '@commander-js/extra-typings';
+import { runDelete } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+
+export const deleteContactCommand = new Command('delete')
+  .alias('rm')
+  .description('Delete a contact')
+  .argument(
+    '<id>',
+    'Contact UUID or email address — both are accepted by the API',
+  )
+  .option(
+    '--yes',
+    'Skip the confirmation prompt (required in non-interactive mode)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `The <id> argument accepts either a UUID or an email address.
+
+Non-interactive: --yes is required to confirm deletion when stdin/stdout is not a TTY.`,
+      output: `  {"object":"contact","id":"<id>","deleted":true}`,
+      errorCodes: ['auth_error', 'confirmation_required', 'delete_error'],
+      examples: [
+        'resend contacts delete 479e3145-dd38-4932-8c0c-e58b548c9e76 --yes',
+        'resend contacts delete user@example.com --yes --json',
+      ],
+    }),
+  )
+  .action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runDelete(
+      id,
+      !!opts.yes,
+      {
+        confirmMessage: `Delete contact ${id}?\nThis cannot be undone.`,
+        spinner: {
+          loading: 'Deleting contact...',
+          success: 'Contact deleted',
+          fail: 'Failed to delete contact',
+        },
+        object: 'contact',
+        successMsg: 'Contact deleted.',
+        sdkCall: (resend) => resend.contacts.remove(id),
+      },
+      globalOpts,
+    );
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/get.ts

@@ -0,0 +1,53 @@
+import { Command } from '@commander-js/extra-typings';
+import { runGet } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+
+export const getContactCommand = new Command('get')
+  .description('Retrieve a contact by ID or email address')
+  .argument(
+    '<id>',
+    'Contact UUID or email address — both are accepted by the API',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      output: `  {\n    "object": "contact",\n    "id": "<uuid>",\n    "email": "user@example.com",\n    "first_name": "Jane",\n    "last_name": "Smith",\n    "created_at": "2026-01-01T00:00:00.000Z",\n    "unsubscribed": false,\n    "properties": {}\n  }`,
+      errorCodes: ['auth_error', 'fetch_error'],
+      examples: [
+        'resend contacts get 479e3145-dd38-4932-8c0c-e58b548c9e76',
+        'resend contacts get user@example.com',
+        'resend contacts get 479e3145-dd38-4932-8c0c-e58b548c9e76 --json',
+      ],
+    }),
+  )
+  .action(async (id, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runGet(
+      {
+        spinner: {
+          loading: 'Fetching contact...',
+          success: 'Contact fetched',
+          fail: 'Failed to fetch contact',
+        },
+        sdkCall: (resend) => resend.contacts.get(id),
+        onInteractive: (data) => {
+          const name = [data.first_name, data.last_name]
+            .filter(Boolean)
+            .join(' ');
+          console.log(`\n${data.email}${name ? ` (${name})` : ''}`);
+          console.log(`ID: ${data.id}`);
+          console.log(`Created: ${data.created_at}`);
+          console.log(`Unsubscribed: ${data.unsubscribed ? 'yes' : 'no'}`);
+          const propEntries = Object.entries(data.properties ?? {});
+          if (propEntries.length > 0) {
+            console.log('Properties:');
+            for (const [key, val] of propEntries) {
+              console.log(`  ${key}: ${val.value}`);
+            }
+          }
+        },
+      },
+      globalOpts,
+    );
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/index.ts

@@ -0,0 +1,58 @@
+import { Command } from '@commander-js/extra-typings';
+import { buildHelpText } from '../../lib/help-text';
+import { addContactSegmentCommand } from './add-segment';
+import { createContactCommand } from './create';
+import { deleteContactCommand } from './delete';
+import { getContactCommand } from './get';
+import { listContactsCommand } from './list';
+import { removeContactSegmentCommand } from './remove-segment';
+import { listContactSegmentsCommand } from './segments';
+import { listContactTopicsCommand } from './topics';
+import { updateContactCommand } from './update';
+import { updateContactTopicsCommand } from './update-topics';
+
+export const contactsCommand = new Command('contacts')
+  .description('Manage contacts — the global list of people you send email to')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Contacts are global entities (not audience-scoped since the 2025 migration).
+Each contact is identified by a UUID or email address — both are accepted in all subcommands.
+
+Properties:
+  Contacts carry custom key-value properties (e.g. plan, company) accessible in broadcast templates
+  via {{{PROPERTY_NAME|fallback}}} triple-brace interpolation.
+  firstName/lastName are convenience aliases stored as FIRST_NAME/LAST_NAME properties.
+
+Subscription:
+  --unsubscribed is a team-wide opt-out from all broadcasts.
+  Fine-grained control is available via topic subscriptions (see "resend contacts topics").
+
+Segments:
+  Contacts can belong to multiple segments. Segments determine which contacts receive a broadcast.
+  Manage membership with "resend contacts add-segment" and "resend contacts remove-segment".`,
+      examples: [
+        'resend contacts list',
+        'resend contacts create --email jane@example.com --first-name Jane',
+        'resend contacts get 479e3145-dd38-4932-8c0c-e58b548c9e76',
+        'resend contacts get user@example.com',
+        'resend contacts update user@example.com --unsubscribed',
+        'resend contacts delete 479e3145-dd38-4932-8c0c-e58b548c9e76 --yes',
+        'resend contacts segments user@example.com',
+        'resend contacts add-segment user@example.com --segment-id 7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d',
+        'resend contacts remove-segment user@example.com 7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d',
+        'resend contacts topics user@example.com',
+        `resend contacts update-topics user@example.com --topics '[{"id":"topic-uuid","subscription":"opt_in"}]'`,
+      ],
+    }),
+  )
+  .addCommand(createContactCommand)
+  .addCommand(getContactCommand)
+  .addCommand(listContactsCommand, { isDefault: true })
+  .addCommand(updateContactCommand)
+  .addCommand(deleteContactCommand)
+  .addCommand(listContactSegmentsCommand)
+  .addCommand(addContactSegmentCommand)
+  .addCommand(removeContactSegmentCommand)
+  .addCommand(listContactTopicsCommand)
+  .addCommand(updateContactTopicsCommand);

package/.claude/worktrees/emails-list/src/commands/contacts/list.ts

@@ -0,0 +1,57 @@
+import { Command } from '@commander-js/extra-typings';
+import { runList } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import {
+  buildPaginationOpts,
+  parseLimitOpt,
+  printPaginationHint,
+} from '../../lib/pagination';
+import { renderContactsTable } from './utils';
+
+export const listContactsCommand = new Command('list')
+  .alias('ls')
+  .description('List all contacts')
+  .option('--limit <n>', 'Maximum number of contacts to return (1-100)', '10')
+  .option('--after <cursor>', 'Return contacts after this cursor (next page)')
+  .option(
+    '--before <cursor>',
+    'Return contacts before this cursor (previous page)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Contacts are global — they are not scoped to audiences or segments since the 2025 migration.
+
+Pagination: use --after or --before with a contact ID as the cursor.
+  Only one of --after or --before may be used at a time.
+  The response includes has_more: true when additional pages exist.`,
+      output: `  {"object":"list","data":[{"id":"...","email":"...","first_name":"...","last_name":"...","unsubscribed":false}],"has_more":false}`,
+      errorCodes: ['auth_error', 'invalid_limit', 'list_error'],
+      examples: [
+        'resend contacts list',
+        'resend contacts list --limit 25 --json',
+        'resend contacts list --after 479e3145-dd38-4932-8c0c-e58b548c9e76 --json',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    const limit = parseLimitOpt(opts.limit, globalOpts);
+    const paginationOpts = buildPaginationOpts(limit, opts.after, opts.before);
+    await runList(
+      {
+        spinner: {
+          loading: 'Fetching contacts...',
+          success: 'Contacts fetched',
+          fail: 'Failed to list contacts',
+        },
+        sdkCall: (resend) => resend.contacts.list(paginationOpts),
+        onInteractive: (list) => {
+          console.log(renderContactsTable(list.data));
+          printPaginationHint(list);
+        },
+      },
+      globalOpts,
+    );
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/remove-segment.ts

@@ -0,0 +1,48 @@
+import { Command } from '@commander-js/extra-typings';
+import type { RemoveContactSegmentOptions } from 'resend';
+import { runWrite } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { segmentContactIdentifier } from './utils';
+
+export const removeContactSegmentCommand = new Command('remove-segment')
+  .description('Remove a contact from a segment')
+  .argument('<contactId>', 'Contact UUID or email address')
+  .argument('<segmentId>', 'Segment ID to remove the contact from')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `The <contactId> argument accepts either a UUID or an email address.
+The <segmentId> argument must be a segment UUID (not an email).`,
+      output: `  {"id":"<segment-id>","deleted":true}`,
+      errorCodes: ['auth_error', 'remove_segment_error'],
+      examples: [
+        'resend contacts remove-segment 479e3145-dd38-4932-8c0c-e58b548c9e76 7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d',
+        'resend contacts remove-segment user@example.com 7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d --json',
+      ],
+    }),
+  )
+  .action(async (contactId, segmentId, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    // segmentContactIdentifier resolves UUID vs email for the ContactSegmentsBaseOptions
+    // discriminated union. The spread of that union requires an explicit cast.
+    const payload = {
+      ...segmentContactIdentifier(contactId),
+      segmentId,
+    } as RemoveContactSegmentOptions;
+
+    await runWrite(
+      {
+        spinner: {
+          loading: 'Removing contact from segment...',
+          success: 'Contact removed from segment',
+          fail: 'Failed to remove contact from segment',
+        },
+        sdkCall: (resend) => resend.contacts.segments.remove(payload),
+        errorCode: 'remove_segment_error',
+        successMsg: `Contact removed from segment: ${segmentId}`,
+      },
+      globalOpts,
+    );
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/segments.ts

@@ -0,0 +1,39 @@
+import { Command } from '@commander-js/extra-typings';
+import { runList } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { renderSegmentsTable } from '../segments/utils';
+import { segmentContactIdentifier } from './utils';
+
+export const listContactSegmentsCommand = new Command('segments')
+  .description('List the segments a contact belongs to')
+  .argument('<id>', 'Contact UUID or email address')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `The <id> argument accepts either a UUID or an email address.`,
+      output: `  {"object":"list","data":[{"id":"<segment-uuid>","name":"Newsletter Subscribers","created_at":"..."}],"has_more":false}`,
+      errorCodes: ['auth_error', 'list_error'],
+      examples: [
+        'resend contacts segments 479e3145-dd38-4932-8c0c-e58b548c9e76',
+        'resend contacts segments user@example.com',
+        'resend contacts segments 479e3145-dd38-4932-8c0c-e58b548c9e76 --json',
+      ],
+    }),
+  )
+  .action(async (id, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runList(
+      {
+        spinner: {
+          loading: 'Fetching segments...',
+          success: 'Segments fetched',
+          fail: 'Failed to list segments',
+        },
+        sdkCall: (resend) =>
+          resend.contacts.segments.list(segmentContactIdentifier(id)),
+        onInteractive: (list) => console.log(renderSegmentsTable(list.data)),
+      },
+      globalOpts,
+    );
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/topics.ts

@@ -0,0 +1,45 @@
+import { Command } from '@commander-js/extra-typings';
+import { runList } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { contactIdentifier, renderContactTopicsTable } from './utils';
+
+export const listContactTopicsCommand = new Command('topics')
+  .description("List a contact's topic subscriptions")
+  .argument('<id>', 'Contact UUID or email address')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `The <id> argument accepts either a UUID or an email address.
+
+Topics control which broadcast email types a contact receives.
+  subscription values: "opt_in" (receiving) | "opt_out" (not receiving)
+
+Use "resend contacts update-topics <id>" to change subscription statuses.`,
+      output: `  {"object":"list","data":[{"id":"...","name":"Product Updates","description":"...","subscription":"opt_in"}],"has_more":false}`,
+      errorCodes: ['auth_error', 'list_error'],
+      examples: [
+        'resend contacts topics 479e3145-dd38-4932-8c0c-e58b548c9e76',
+        'resend contacts topics user@example.com',
+        'resend contacts topics 479e3145-dd38-4932-8c0c-e58b548c9e76 --json',
+      ],
+    }),
+  )
+  .action(async (id, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    // ListContactTopicsBaseOptions uses optional { id?, email? } (not a discriminated
+    // union), so contactIdentifier's result is directly assignable without a cast.
+    await runList(
+      {
+        spinner: {
+          loading: 'Fetching topic subscriptions...',
+          success: 'Topic subscriptions fetched',
+          fail: 'Failed to list topic subscriptions',
+        },
+        sdkCall: (resend) => resend.contacts.topics.list(contactIdentifier(id)),
+        onInteractive: (list) =>
+          console.log(renderContactTopicsTable(list.data)),
+      },
+      globalOpts,
+    );
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/update-topics.ts

@@ -0,0 +1,90 @@
+import * as p from '@clack/prompts';
+import { Command } from '@commander-js/extra-typings';
+import type { GlobalOpts } from '../../lib/client';
+import { requireClient } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { outputError, outputResult } from '../../lib/output';
+import { cancelAndExit } from '../../lib/prompts';
+import { withSpinner } from '../../lib/spinner';
+import { isInteractive } from '../../lib/tty';
+import { contactIdentifier, parseTopicsJson } from './utils';
+
+export const updateContactTopicsCommand = new Command('update-topics')
+  .description("Update a contact's topic subscription statuses")
+  .argument('<id>', 'Contact UUID or email address')
+  .option(
+    '--topics <json>',
+    'JSON array of topic subscriptions (required) — e.g. \'[{"id":"topic-uuid","subscription":"opt_in"}]\'',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `The <id> argument accepts either a UUID or an email address.
+
+Non-interactive: --topics is required.
+
+Topics JSON format:
+  '[{"id":"<topic-uuid>","subscription":"opt_in"}]'
+  subscription values: "opt_in" | "opt_out"
+
+This operation replaces all topic subscriptions for the specified topics.
+Topics not included in the array are left unchanged.`,
+      output: `  {"id":"<contact-id>"}`,
+      errorCodes: [
+        'auth_error',
+        'missing_topics',
+        'invalid_topics',
+        'update_topics_error',
+      ],
+      examples: [
+        `resend contacts update-topics 479e3145-dd38-4932-8c0c-e58b548c9e76 --topics '[{"id":"topic-uuid","subscription":"opt_in"}]'`,
+        `resend contacts update-topics user@example.com --topics '[{"id":"t1","subscription":"opt_out"},{"id":"t2","subscription":"opt_in"}]' --json`,
+      ],
+    }),
+  )
+  .action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    const resend = requireClient(globalOpts);
+
+    let topicsJson = opts.topics;
+
+    if (!topicsJson) {
+      if (!isInteractive()) {
+        outputError(
+          { message: 'Missing --topics flag.', code: 'missing_topics' },
+          { json: globalOpts.json },
+        );
+      }
+      const result = await p.text({
+        message:
+          'Topics JSON (e.g. \'[{"id":"topic-uuid","subscription":"opt_in"}]\')',
+        placeholder: '[{"id":"topic-uuid","subscription":"opt_in"}]',
+        validate: (v) => (!v ? 'Required' : undefined),
+      });
+      if (p.isCancel(result)) {
+        cancelAndExit('Cancelled.');
+      }
+      topicsJson = result;
+    }
+
+    const topics = parseTopicsJson(topicsJson, globalOpts);
+
+    // contactIdentifier's result is directly assignable: UpdateContactTopicsBaseOptions
+    // uses optional { id?, email? } (not a discriminated union).
+    const data = await withSpinner(
+      {
+        loading: 'Updating topic subscriptions...',
+        success: 'Topic subscriptions updated',
+        fail: 'Failed to update topic subscriptions',
+      },
+      () => resend.contacts.topics.update({ ...contactIdentifier(id), topics }),
+      'update_topics_error',
+      globalOpts,
+    );
+
+    if (!globalOpts.json && isInteractive()) {
+      console.log(`Topic subscriptions updated for contact: ${id}`);
+    } else {
+      outputResult(data, { json: globalOpts.json });
+    }
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/update.ts

@@ -0,0 +1,77 @@
+import { Command } from '@commander-js/extra-typings';
+import type { UpdateContactOptions } from 'resend';
+import { runWrite } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { contactIdentifier, parsePropertiesJson } from './utils';
+
+export const updateContactCommand = new Command('update')
+  .description("Update a contact's subscription status or custom properties")
+  .argument(
+    '<id>',
+    'Contact UUID or email address — both are accepted by the API',
+  )
+  .option(
+    '--unsubscribed',
+    'Globally unsubscribe the contact from all broadcasts',
+  )
+  .option(
+    '--no-unsubscribed',
+    'Re-subscribe the contact (clears the global unsubscribe flag)',
+  )
+  .option(
+    '--properties <json>',
+    'JSON object of properties to merge (e.g. \'{"company":"Acme"}\'); set a key to null to clear it',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `The <id> argument accepts either a UUID or an email address.
+
+Subscription toggle:
+  --unsubscribed   Sets unsubscribed: true  — contact will not receive any broadcasts.
+  --no-unsubscribed Sets unsubscribed: false — re-enables broadcast delivery.
+  Omitting both flags leaves the subscription status unchanged.
+
+Properties: --properties merges the given JSON object with existing properties.
+  Set a key to null to clear it: '{"company":null}'.`,
+      output: `  {"object":"contact","id":"<id>"}`,
+      errorCodes: ['auth_error', 'invalid_properties', 'update_error'],
+      examples: [
+        'resend contacts update 479e3145-dd38-4932-8c0c-e58b548c9e76 --unsubscribed',
+        'resend contacts update user@example.com --no-unsubscribed',
+        `resend contacts update 479e3145-dd38-4932-8c0c-e58b548c9e76 --properties '{"plan":"pro"}'`,
+        'resend contacts update user@example.com --unsubscribed --json',
+      ],
+    }),
+  )
+  .action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const properties = parsePropertiesJson(opts.properties, globalOpts);
+
+    // contactIdentifier resolves UUID vs email. The spread of a discriminated
+    // union requires an explicit cast because TypeScript cannot narrow it
+    // through a spread at the call site.
+    const payload = {
+      ...contactIdentifier(id),
+      ...(opts.unsubscribed !== undefined && {
+        unsubscribed: opts.unsubscribed,
+      }),
+      ...(properties && { properties }),
+    } as UpdateContactOptions;
+
+    await runWrite(
+      {
+        spinner: {
+          loading: 'Updating contact...',
+          success: 'Contact updated',
+          fail: 'Failed to update contact',
+        },
+        sdkCall: (resend) => resend.contacts.update(payload),
+        errorCode: 'update_error',
+        successMsg: `Contact updated: ${id}`,
+      },
+      globalOpts,
+    );
+  });

package/.claude/worktrees/emails-list/src/commands/contacts/utils.ts

@@ -0,0 +1,119 @@
+import type { ContactSegmentsBaseOptions, ContactTopic } from 'resend';
+import type { GlobalOpts } from '../../lib/client';
+import { outputError } from '../../lib/output';
+import { renderTable } from '../../lib/table';
+
+// ─── Table renderers ─────────────────────────────────────────────────────────
+
+export function renderContactsTable(
+  contacts: Array<{
+    id: string;
+    email: string;
+    first_name: string | null;
+    last_name: string | null;
+    unsubscribed: boolean;
+  }>,
+): string {
+  const rows = contacts.map((c) => [
+    c.email,
+    c.first_name ?? '',
+    c.last_name ?? '',
+    c.unsubscribed ? 'yes' : 'no',
+    c.id,
+  ]);
+  return renderTable(
+    ['Email', 'First Name', 'Last Name', 'Unsubscribed', 'ID'],
+    rows,
+    '(no contacts)',
+  );
+}
+
+export function renderContactTopicsTable(topics: ContactTopic[]): string {
+  const rows = topics.map((t) => [
+    t.name,
+    t.subscription,
+    t.id,
+    t.description ?? '',
+  ]);
+  return renderTable(
+    ['Name', 'Subscription', 'ID', 'Description'],
+    rows,
+    '(no topic subscriptions)',
+  );
+}
+
+// ─── Contact identifier helpers ───────────────────────────────────────────────
+//
+// The Resend SDK uses two different discriminated-union shapes depending on
+// the API surface:
+//
+//   • contactIdentifier  — produces { id } | { email } for endpoints that
+//     accept SelectingField (update, get, remove) or { id?, email? }
+//     (topics list/update).
+//
+//   • segmentContactIdentifier — produces { contactId } | { email } for the
+//     contacts.segments.* endpoints, which use ContactSegmentsBaseOptions.
+//
+// Centralising the `str.includes('@')` check here prevents it from drifting
+// across six separate command files.
+
+export function contactIdentifier(
+  id: string,
+): { id: string } | { email: string } {
+  return id.includes('@') ? { email: id } : { id };
+}
+
+export function segmentContactIdentifier(
+  id: string,
+): ContactSegmentsBaseOptions {
+  return id.includes('@') ? { email: id } : { contactId: id };
+}
+
+// ─── JSON flag helpers ────────────────────────────────────────────────────────
+
+export function parseTopicsJson(
+  raw: string,
+  globalOpts: GlobalOpts,
+): Array<{ id: string; subscription: 'opt_in' | 'opt_out' }> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    outputError(
+      {
+        message:
+          'Invalid --topics JSON. Expected an array of {id, subscription} objects.',
+        code: 'invalid_topics',
+      },
+      { json: globalOpts.json },
+    );
+  }
+  if (!Array.isArray(parsed)) {
+    outputError(
+      {
+        message:
+          'Invalid --topics JSON. Expected an array of {id, subscription} objects.',
+        code: 'invalid_topics',
+      },
+      { json: globalOpts.json },
+    );
+  }
+  return parsed as Array<{ id: string; subscription: 'opt_in' | 'opt_out' }>;
+}
+
+export function parsePropertiesJson(
+  raw: string | undefined,
+  globalOpts: GlobalOpts,
+): Record<string, string | number | null> | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(raw) as Record<string, string | number | null>;
+  } catch {
+    outputError(
+      { message: 'Invalid --properties JSON.', code: 'invalid_properties' },
+      { json: globalOpts.json },
+    );
+  }
+}