resend-cli 1.0.3 → 1.1.0

package/src/commands/contact-properties/create.ts

@@ -0,0 +1,118 @@
+import { Command, Option } from '@commander-js/extra-typings';
+import type { CreateContactPropertyOptions } from 'resend';
+import { runCreate } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { outputError } from '../../lib/output';
+import { requireSelect, requireText } from '../../lib/prompts';
+
+export const createContactPropertyCommand = new Command('create')
+  .description('Create a new contact property definition')
+  .addOption(
+    new Option(
+      '--key <key>',
+      'Property key name, used in broadcast template interpolation (e.g. company_name, department)',
+    ),
+  )
+  .addOption(
+    new Option(
+      '--type <type>',
+      "Property data type: 'string' for text values, 'number' for numeric values",
+    ).choices(['string', 'number'] as const),
+  )
+  .option(
+    '--fallback-value <value>',
+    'Default value used in broadcast templates when a contact has no value set for this property',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Property keys are used as identifiers in broadcast HTML template interpolation:
+  {{{PROPERTY_NAME|fallback}}}  — triple-brace syntax substitutes the contact's value
+  {{{company_name|Unknown}}}    — falls back to "Unknown" if the property is not set
+
+Reserved keys (cannot be used): FIRST_NAME, LAST_NAME, EMAIL, UNSUBSCRIBE_URL
+
+Non-interactive: --key and --type are required. --fallback-value is optional.
+Warning: do not create properties with reserved key names — they will conflict with
+built-in contact fields and may cause unexpected behavior in broadcasts.`,
+      output: `  {"object":"contact_property","id":"<id>"}`,
+      errorCodes: [
+        'auth_error',
+        'missing_key',
+        'missing_type',
+        'invalid_fallback_value',
+        'create_error',
+      ],
+      examples: [
+        'resend contact-properties create --key company_name --type string',
+        'resend contact-properties create --key company_name --type string --fallback-value "Unknown"',
+        'resend contact-properties create --key employee_count --type number --fallback-value 0',
+        'resend contact-properties create --key department --type string --json',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const key = await requireText(
+      opts.key,
+      { message: 'Property key', placeholder: 'company_name' },
+      { message: 'Missing --key flag.', code: 'missing_key' },
+      globalOpts,
+    );
+
+    const type = await requireSelect(
+      opts.type,
+      {
+        message: 'Property data type',
+        options: [
+          { value: 'string' as const, label: 'string — text values' },
+          { value: 'number' as const, label: 'number — numeric values' },
+        ],
+      },
+      { message: 'Missing --type flag.', code: 'missing_type' },
+      globalOpts,
+    );
+
+    let fallbackValue: string | number | undefined;
+    if (opts.fallbackValue !== undefined) {
+      if (type === 'number') {
+        const parsed = parseFloat(opts.fallbackValue);
+        if (Number.isNaN(parsed)) {
+          outputError(
+            {
+              message:
+                '--fallback-value must be a valid number for number-type properties.',
+              code: 'invalid_fallback_value',
+            },
+            { json: globalOpts.json },
+          );
+        }
+        fallbackValue = parsed;
+      } else {
+        fallbackValue = opts.fallbackValue;
+      }
+    }
+
+    const payload = {
+      key,
+      type,
+      ...(fallbackValue !== undefined && { fallbackValue }),
+    } as CreateContactPropertyOptions;
+
+    await runCreate(
+      {
+        spinner: {
+          loading: 'Creating contact property...',
+          success: 'Contact property created',
+          fail: 'Failed to create contact property',
+        },
+        sdkCall: (resend) => resend.contactProperties.create(payload),
+        onInteractive: (data) => {
+          console.log(`\nContact property created: ${data.id}`);
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/contact-properties/delete.ts

@@ -0,0 +1,48 @@
+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 deleteContactPropertyCommand = new Command('delete')
+  .alias('rm')
+  .description('Delete a contact property definition')
+  .argument('<id>', 'Contact property UUID')
+  .option(
+    '--yes',
+    'Skip the confirmation prompt (required in non-interactive mode)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `WARNING: Deleting a property definition removes that property value from ALL contacts
+permanently. This cannot be undone, and any broadcasts that reference this property key
+via {{{PROPERTY_NAME}}} will render an empty string or their inline fallback instead.
+
+Non-interactive: --yes is required to confirm deletion when stdin/stdout is not a TTY.`,
+      output: `  {"object":"contact_property","id":"<id>","deleted":true}`,
+      errorCodes: ['auth_error', 'confirmation_required', 'delete_error'],
+      examples: [
+        'resend contact-properties delete b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --yes',
+        'resend contact-properties delete b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --yes --json',
+      ],
+    }),
+  )
+  .action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runDelete(
+      id,
+      !!opts.yes,
+      {
+        confirmMessage: `Delete contact property "${id}"?\nThis will remove this property from ALL contacts permanently.`,
+        spinner: {
+          loading: 'Deleting contact property...',
+          success: 'Contact property deleted',
+          fail: 'Failed to delete contact property',
+        },
+        object: 'contact_property',
+        successMsg: 'Contact property deleted.',
+        sdkCall: (resend) => resend.contactProperties.remove(id),
+      },
+      globalOpts,
+    );
+  });

package/src/commands/contact-properties/get.ts

@@ -0,0 +1,46 @@
+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 getContactPropertyCommand = new Command('get')
+  .description('Retrieve a contact property definition by ID')
+  .argument('<id>', 'Contact property UUID')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      output: `  {
+    "object": "contact_property",
+    "id": "<uuid>",
+    "key": "company_name",
+    "type": "string",
+    "fallbackValue": null,
+    "createdAt": "2026-01-01T00:00:00.000Z"
+  }`,
+      errorCodes: ['auth_error', 'fetch_error'],
+      examples: [
+        'resend contact-properties get b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d',
+        'resend contact-properties get b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --json',
+      ],
+    }),
+  )
+  .action(async (id, _opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    await runGet(
+      {
+        spinner: {
+          loading: 'Fetching contact property...',
+          success: 'Contact property fetched',
+          fail: 'Failed to fetch contact property',
+        },
+        sdkCall: (resend) => resend.contactProperties.get(id),
+        onInteractive: (data) => {
+          console.log(`\n${data.key} (${data.type})`);
+          console.log(`ID: ${data.id}`);
+          console.log(`Created: ${data.createdAt}`);
+          console.log(`Fallback value: ${data.fallbackValue ?? '(none)'}`);
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/contact-properties/index.ts

@@ -0,0 +1,48 @@
+import { Command } from '@commander-js/extra-typings';
+import { buildHelpText } from '../../lib/help-text';
+import { createContactPropertyCommand } from './create';
+import { deleteContactPropertyCommand } from './delete';
+import { getContactPropertyCommand } from './get';
+import { listContactPropertiesCommand } from './list';
+import { updateContactPropertyCommand } from './update';
+
+export const contactPropertiesCommand = new Command('contact-properties')
+  .description(
+    'Manage contact property definitions — schema for custom data on contacts',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Contact properties define the schema for custom data stored on contacts.
+Think of them as column definitions — you create a property definition (e.g. company_name)
+and then set values for that property on individual contacts via "resend contacts update --properties".
+
+Property values are interpolated into broadcast HTML using triple-brace syntax:
+  {{{PROPERTY_NAME|fallback}}}      — inline fallback if property value is absent
+  {{{company_name|Unknown Company}}} — example: renders the company or "Unknown Company"
+
+Reserved property keys (built-in, cannot be created): FIRST_NAME, LAST_NAME, EMAIL, UNSUBSCRIBE_URL
+
+Supported types:
+  string  — text values (default for most properties)
+  number  — numeric values (useful for counts, scores, thresholds)
+
+Note: property keys and types are immutable after creation. Only the fallback value can
+be updated. Deleting a property removes it from all contacts.`,
+      examples: [
+        'resend contact-properties list',
+        'resend contact-properties create --key company_name --type string',
+        'resend contact-properties create --key plan --type string --fallback-value "free"',
+        'resend contact-properties create --key score --type number --fallback-value 0',
+        'resend contact-properties get b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d',
+        'resend contact-properties update b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --fallback-value "Unknown"',
+        'resend contact-properties update b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --clear-fallback-value',
+        'resend contact-properties delete b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --yes',
+      ],
+    }),
+  )
+  .addCommand(createContactPropertyCommand)
+  .addCommand(getContactPropertyCommand)
+  .addCommand(listContactPropertiesCommand, { isDefault: true })
+  .addCommand(updateContactPropertyCommand)
+  .addCommand(deleteContactPropertyCommand);

package/src/commands/contact-properties/list.ts

@@ -0,0 +1,68 @@
+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 { renderContactPropertiesTable } from './utils';
+
+export const listContactPropertiesCommand = new Command('list')
+  .alias('ls')
+  .description('List all contact property definitions')
+  .option(
+    '--limit <n>',
+    'Maximum number of contact properties to return (1-100)',
+    '10',
+  )
+  .option(
+    '--after <cursor>',
+    'Return contact properties after this cursor (next page)',
+  )
+  .option(
+    '--before <cursor>',
+    'Return contact properties before this cursor (previous page)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Pagination: use --after or --before with a contact property 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",
+    "has_more": false,
+    "data": [
+      { "id": "<uuid>", "key": "company_name", "type": "string", "fallbackValue": null, "createdAt": "..." }
+    ]
+  }`,
+      errorCodes: ['auth_error', 'invalid_limit', 'list_error'],
+      examples: [
+        'resend contact-properties list',
+        'resend contact-properties list --limit 25 --json',
+        'resend contact-properties list --after b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --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 contact properties...',
+          success: 'Contact properties fetched',
+          fail: 'Failed to list contact properties',
+        },
+        sdkCall: (resend) => resend.contactProperties.list(paginationOpts),
+        onInteractive: (list) => {
+          console.log(renderContactPropertiesTable(list.data));
+          printPaginationHint(list);
+        },
+      },
+      globalOpts,
+    );
+  });

package/src/commands/contact-properties/update.ts

@@ -0,0 +1,88 @@
+import { Command } from '@commander-js/extra-typings';
+import { runWrite } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { outputError } from '../../lib/output';
+
+export const updateContactPropertyCommand = new Command('update')
+  .description('Update a contact property definition')
+  .argument('<id>', 'Contact property UUID')
+  .option(
+    '--fallback-value <value>',
+    'New fallback value used in broadcast templates when a contact has no value set for this property',
+  )
+  .option(
+    '--clear-fallback-value',
+    'Remove the fallback value (sets it to null)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Note: the property key and type cannot be changed after creation. Only the fallback value
+is updatable. Renaming a property would break existing broadcasts that reference the old key.
+
+--fallback-value and --clear-fallback-value are mutually exclusive.
+
+The fallback value is used in broadcast template interpolation when a contact has no value:
+  {{{company_name|Unknown}}}  — inline fallback (takes precedence over the property's fallback)
+  {{{company_name}}}          — uses the property's stored fallback value if set`,
+      output: `  {"object":"contact_property","id":"<id>"}`,
+      errorCodes: [
+        'auth_error',
+        'no_changes',
+        'conflicting_flags',
+        'update_error',
+      ],
+      examples: [
+        'resend contact-properties update b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --fallback-value "Acme Corp"',
+        'resend contact-properties update b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --fallback-value 42',
+        'resend contact-properties update b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --clear-fallback-value',
+        'resend contact-properties update b4a3c2d1-6e5f-8a7b-0c9d-2e1f4a3b6c5d --fallback-value "Unknown" --json',
+      ],
+    }),
+  )
+  .action(async (id, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    if (opts.fallbackValue === undefined && !opts.clearFallbackValue) {
+      outputError(
+        {
+          message:
+            'Provide at least one option to update: --fallback-value or --clear-fallback-value.',
+          code: 'no_changes',
+        },
+        { json: globalOpts.json },
+      );
+    }
+
+    if (opts.fallbackValue !== undefined && opts.clearFallbackValue) {
+      outputError(
+        {
+          message:
+            '--fallback-value and --clear-fallback-value are mutually exclusive.',
+          code: 'conflicting_flags',
+        },
+        { json: globalOpts.json },
+      );
+    }
+
+    const fallbackValue = opts.clearFallbackValue ? null : opts.fallbackValue;
+
+    await runWrite(
+      {
+        spinner: {
+          loading: 'Updating contact property...',
+          success: 'Contact property updated',
+          fail: 'Failed to update contact property',
+        },
+        sdkCall: (resend) =>
+          resend.contactProperties.update({
+            id,
+            ...(fallbackValue !== undefined && { fallbackValue }),
+          }),
+        errorCode: 'update_error',
+        successMsg: `Contact property updated: ${id}`,
+      },
+      globalOpts,
+    );
+  });

package/src/commands/contact-properties/utils.ts

@@ -0,0 +1,17 @@
+import type { ContactProperty } from 'resend';
+import { renderTable } from '../../lib/table';
+
+export function renderContactPropertiesTable(props: ContactProperty[]): string {
+  const rows = props.map((prop) => [
+    prop.key,
+    prop.type,
+    prop.fallbackValue != null ? String(prop.fallbackValue) : '',
+    prop.id,
+    prop.createdAt,
+  ]);
+  return renderTable(
+    ['Key', 'Type', 'Fallback Value', 'ID', 'Created'],
+    rows,
+    '(no contact properties)',
+  );
+}

package/src/commands/contacts/add-segment.ts

@@ -0,0 +1,78 @@
+import * as p from '@clack/prompts';
+import { Command } from '@commander-js/extra-typings';
+import type { AddContactSegmentOptions } from 'resend';
+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 { segmentContactIdentifier } from './utils';
+
+export const addContactSegmentCommand = new Command('add-segment')
+  .description('Add a contact to a segment')
+  .argument('<contactId>', 'Contact UUID or email address')
+  .option('--segment-id <id>', 'Segment ID to add the contact to (required)')
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `The <contactId> argument accepts either a UUID or an email address.
+
+Non-interactive: --segment-id is required.`,
+      output: `  {"id":"<segment-membership-id>"}`,
+      errorCodes: ['auth_error', 'missing_segment_id', 'add_segment_error'],
+      examples: [
+        'resend contacts add-segment 479e3145-dd38-4932-8c0c-e58b548c9e76 --segment-id 7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d',
+        'resend contacts add-segment user@example.com --segment-id 7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d --json',
+      ],
+    }),
+  )
+  .action(async (contactId, opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+    const resend = requireClient(globalOpts);
+
+    let segmentId = opts.segmentId;
+
+    if (!segmentId) {
+      if (!isInteractive()) {
+        outputError(
+          { message: 'Missing --segment-id flag.', code: 'missing_segment_id' },
+          { json: globalOpts.json },
+        );
+      }
+      const result = await p.text({
+        message: 'Segment ID',
+        placeholder: '7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d',
+        validate: (v) => (!v ? 'Required' : undefined),
+      });
+      if (p.isCancel(result)) {
+        cancelAndExit('Cancelled.');
+      }
+      segmentId = result;
+    }
+
+    // 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 AddContactSegmentOptions;
+
+    const data = await withSpinner(
+      {
+        loading: 'Adding contact to segment...',
+        success: 'Contact added to segment',
+        fail: 'Failed to add contact to segment',
+      },
+      () => resend.contacts.segments.add(payload),
+      'add_segment_error',
+      globalOpts,
+    );
+
+    if (!globalOpts.json && isInteractive()) {
+      console.log(`Contact added to segment: ${segmentId}`);
+    } else {
+      outputResult(data, { json: globalOpts.json });
+    }
+  });

package/src/commands/contacts/create.ts

@@ -0,0 +1,122 @@
+import * as p from '@clack/prompts';
+import { Command } from '@commander-js/extra-typings';
+import { runCreate } from '../../lib/actions';
+import type { GlobalOpts } from '../../lib/client';
+import { buildHelpText } from '../../lib/help-text';
+import { cancelAndExit, requireText } from '../../lib/prompts';
+import { isInteractive } from '../../lib/tty';
+import { parsePropertiesJson } from './utils';
+
+export const createContactCommand = new Command('create')
+  .description('Create a new contact')
+  .option('--email <email>', 'Contact email address (required)')
+  .option('--first-name <name>', 'First name')
+  .option('--last-name <name>', 'Last name')
+  .option(
+    '--unsubscribed',
+    'Globally unsubscribe the contact from all broadcasts',
+  )
+  .option(
+    '--properties <json>',
+    'Custom properties as a JSON string (e.g. \'{"company":"Acme"}\')',
+  )
+  .option(
+    '--segment-id <id...>',
+    'Segment ID to add the contact to on creation (repeatable: --segment-id abc --segment-id def)',
+  )
+  .addHelpText(
+    'after',
+    buildHelpText({
+      context: `Non-interactive: --email is required. All other flags are optional.
+
+Properties: pass a JSON object string to --properties (e.g. '{"plan":"pro","company":"Acme"}').
+  Properties are stored as custom contact attributes. To clear a property, set it to null.
+  firstName and lastName are convenience aliases — they map to FIRST_NAME/LAST_NAME properties internally.
+
+Segments: use --segment-id once per segment to add the contact to one or more segments on creation.
+
+Unsubscribed: setting --unsubscribed is a team-wide opt-out from all broadcasts, regardless of segments/topics.`,
+      output: `  {"object":"contact","id":"<id>"}`,
+      errorCodes: [
+        'auth_error',
+        'missing_email',
+        'invalid_properties',
+        'create_error',
+      ],
+      examples: [
+        'resend contacts create --email jane@example.com',
+        'resend contacts create --email jane@example.com --first-name Jane --last-name Smith',
+        'resend contacts create --email jane@example.com --unsubscribed',
+        `resend contacts create --email jane@example.com --properties '{"company":"Acme","plan":"pro"}'`,
+        'resend contacts create --email jane@example.com --segment-id 7b1e0a3d-4c5f-4e8a-9b2d-1a3c5e7f9b2d --segment-id a2f4c6e8-1b3d-5f7a-9c2e-4d6f8a1b3c5e',
+        'resend contacts create --email jane@example.com --first-name Jane --json',
+      ],
+    }),
+  )
+  .action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals() as GlobalOpts;
+
+    const email = await requireText(
+      opts.email,
+      { message: 'Email address', placeholder: 'user@example.com' },
+      { message: 'Missing --email flag.', code: 'missing_email' },
+      globalOpts,
+    );
+
+    let firstName = opts.firstName;
+    let lastName = opts.lastName;
+
+    if (isInteractive() && !opts.firstName) {
+      const result = await p.text({
+        message: 'First name (optional)',
+        placeholder: 'Jane',
+      });
+      if (p.isCancel(result)) {
+        cancelAndExit('Cancelled.');
+      }
+      if (result) {
+        firstName = result;
+      }
+    }
+
+    if (isInteractive() && !opts.lastName) {
+      const result = await p.text({
+        message: 'Last name (optional)',
+        placeholder: 'Smith',
+      });
+      if (p.isCancel(result)) {
+        cancelAndExit('Cancelled.');
+      }
+      if (result) {
+        lastName = result;
+      }
+    }
+
+    const properties = parsePropertiesJson(opts.properties, globalOpts);
+    const segments = opts.segmentId ?? [];
+
+    await runCreate(
+      {
+        spinner: {
+          loading: 'Creating contact...',
+          success: 'Contact created',
+          fail: 'Failed to create contact',
+        },
+        sdkCall: (resend) =>
+          resend.contacts.create({
+            email,
+            ...(firstName && { firstName }),
+            ...(lastName && { lastName }),
+            ...(opts.unsubscribed && { unsubscribed: true }),
+            ...(properties && { properties }),
+            ...(segments.length > 0 && {
+              segments: segments.map((id) => ({ id })),
+            }),
+          }),
+        onInteractive: (data) => {
+          console.log(`\nContact created: ${data.id}`);
+        },
+      },
+      globalOpts,
+    );
+  });