@myapihq/cli 2.22.0 → 2.23.0

package/dist/commands/container.d.ts

@@ -8,6 +8,7 @@ export declare const NAME_RE: RegExp;
 export declare const RESERVED_NAMES: Set<string>;
 export declare function _validateName(name: string): string | null;
 export declare function _parseEnv(raw: string): Record<string, string> | string;
+export declare function splitEnvEntries(raw: string): string[];
 export declare function create(nameArg: string | undefined, flags: Flags): Promise<void>;
 export declare function list(flags: Flags): Promise<void>;
 export declare function get(id: string, flags: Flags): Promise<void>;

package/dist/commands/container.js

@@ -28,7 +28,7 @@ export const SCHEMA = {
     'min-instances': 'number',
     'max-instances': 'number',
     port: 'number',
-    env: 'string',
+    env: 'list',
     unset: 'string',
     tail: 'number',
     scope: 'string',
@@ -60,15 +60,45 @@ export function _validateName(name) {
 // message string (pure form, for tests).
 export function _parseEnv(raw) {
     const env = {};
-    for (const pair of raw.split(',').map(s => s.trim()).filter(Boolean)) {
+    for (const pair of splitEnvEntries(raw)) {
         const eq = pair.indexOf('=');
         if (eq < 1) {
-            return `Invalid --env entry "${pair}". Use KEY=VALUE, comma-separated.`;
+            return `Invalid --env entry "${pair}". Use KEY=VALUE. ` +
+                `A value containing commas needs its own --env: --env A=1 --env "B=x,y".`;
         }
         env[pair.slice(0, eq)] = pair.slice(eq + 1);
     }
     return env;
 }
+/* Split one --env occurrence into entries.
+ *
+ * A comma means "next variable" only when every segment looks like KEY=VALUE.
+ * Otherwise the commas belong to the value — the case that mattered. An origin
+ * list is ONE variable whose value contains commas, and splitting it produced
+ * `Invalid --env entry "https://dev.example.com"`: the command refused the exact
+ * shape it was added to let people set. Three of one customer's variables are
+ * lists like that, and the same defect at `create` is what sent them through
+ * three container generations in a week.
+ *
+ * The heuristic does not have to be perfect, because --env is now repeatable:
+ * given on its own, `--env "A=x?a=1,b=2"` is unambiguous and always right. The
+ * splitting stays so `--env A=1,B=2` keeps working for everyone already writing
+ * it that way.
+ */
+export function splitEnvEntries(raw) {
+    const parts = raw.split(',').map(s => s.trim()).filter(Boolean);
+    // One entry after dropping empties: a plain pair, or a pair with a trailing
+    // comma. Returning the raw string here would fold that stray comma into the
+    // value — caught by an existing test, which is what it was for.
+    if (parts.length <= 1) {
+        return parts;
+    }
+    if (parts.every(p => p.indexOf('=') > 0)) {
+        return parts;
+    }
+    const whole = raw.trim();
+    return whole ? [whole] : [];
+}
 function summarizeContainer(c) {
     return {
         id: c.id,
@@ -127,11 +157,20 @@ export async function create(nameArg, flags) {
             error(`--health-check must be a path starting with "/" — got "${hc}".`);
         payload.health_check = hc;
     }
-    if (typeof flags.env === 'string') {
-        const env = _parseEnv(flags.env);
-        if (typeof env === 'string')
-            error(env);
-        payload.env = env;
+    // Repeatable, and create must agree with `container env` on what --env means.
+    // If they disagree, a variable settable at creation cannot be changed
+    // afterwards — which is how a customer ended up recreating containers.
+    const createEnvArgs = Array.isArray(flags.env) ? flags.env
+        : typeof flags.env === 'string' ? [flags.env] : [];
+    if (createEnvArgs.length > 0) {
+        const merged = {};
+        for (const occurrence of createEnvArgs) {
+            const parsed = _parseEnv(occurrence);
+            if (typeof parsed === 'string')
+                error(parsed);
+            Object.assign(merged, parsed);
+        }
+        payload.env = merged;
     }
     const result = await sdkContainer.createContainer(config.api_key, orgId, payload);
     success(`Container created: ${result.container.id}`);
@@ -721,10 +760,15 @@ All commands accept --org <id> (or set default: myapi config set-org <id>).`);
         const config = requireConfig();
         const orgId = requireOrg(flags, config, 'myapi container env <id> --env K=V [--unset K2]');
         if (!id)
-            error('Missing id.\nUsage: myapi container env <id> --env KEY=VALUE[,K2=V2] [--unset KEY3[,KEY4]]');
+            error('Missing id.\nUsage: myapi container env <id> --env KEY=VALUE [--env K2=V2] [--unset KEY3]\n' +
+                'A value containing commas needs its own --env: --env "ORIGINS=http://a,https://b"');
         const env = {};
-        if (typeof flags.env === 'string') {
-            const parsed = _parseEnv(flags.env);
+        // Each occurrence parsed on its own, so a value containing commas can be
+        // given unambiguously as its own --env.
+        const envArgs = Array.isArray(flags.env) ? flags.env
+            : typeof flags.env === 'string' ? [flags.env] : [];
+        for (const occurrence of envArgs) {
+            const parsed = _parseEnv(occurrence);
             if (typeof parsed === 'string')
                 error(parsed);
             Object.assign(env, parsed);

package/dist/commands/crm/contacts.js

@@ -1,12 +1,16 @@
 // `myapi crm contacts <subcommand>` — the engaged-people half of CRM.
+import * as fs from 'fs';
 import { crm } from '@myapihq/sdk';
 import { requireConfig } from '../../config.js';
 import { success, error, info, printTable, printJson } from '../../output.js';
 import { requireOrg, requireArg } from '../../helpers.js';
+import { retryFunds } from '../../utils.js';
 import { pageLine, originFlag } from './pagination.js';
 export const EXPOSES = [
     'POST /crm/orgs/{org_id}/contacts',
     'POST /crm/orgs/{org_id}/contacts/promote',
+    'POST /crm/orgs/{org_id}/contacts/promote-audience',
+    'POST /crm/orgs/{org_id}/contacts/import',
     'POST /crm/orgs/{org_id}/contacts/search',
     'GET /crm/orgs/{org_id}/contacts/{id}',
     'PATCH /crm/orgs/{org_id}/contacts/{id}',
@@ -152,6 +156,71 @@ async function promote(personId, flags) {
     }
     success(`Promoted to ${c.id} (${c.email})`);
 }
+// Walks every page rather than promoting the first 500 and stopping. A bulk
+// import that quietly covers part of an audience is the same failure as a list
+// that truncates: the caller gets a number that looks like an answer.
+async function promoteAudience(audienceId, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi crm contacts promote-audience <audience_id> [--org <id>]');
+    requireArg(audienceId, 'audience_id', 'myapi crm contacts promote-audience <audience_id>');
+    const totals = { created: 0, matched: 0, skipped_no_email: 0, failed: 0, processed: 0 };
+    let offset = 0;
+    let audienceTotal = 0;
+    // A page at a time, resuming from the server's own next_offset — the same
+    // cursor discipline the paged list commands use.
+    for (let page = 0; page < 200; page++) {
+        const r = await retryFunds(() => crm.promoteAudience(config.api_key, orgId, audienceId, { offset }));
+        totals.created += r.created;
+        totals.matched += r.matched;
+        totals.skipped_no_email += r.skipped_no_email;
+        totals.failed += r.failed;
+        totals.processed += r.processed;
+        audienceTotal = r.total;
+        if (!r.has_more || r.processed === 0)
+            break;
+        offset = r.next_offset;
+        if (!flags.json)
+            info(`… ${totals.processed}/${r.total}`);
+    }
+    if (flags.json) {
+        printJson({ audience_id: audienceId, total: audienceTotal, ...totals });
+        return;
+    }
+    success(`${totals.created} new contact(s), ${totals.matched} already known`);
+    if (totals.skipped_no_email > 0) {
+        // Named rather than folded into a total: this is almost always why an
+        // audience of 400 becomes 260 contacts.
+        info(`${totals.skipped_no_email} skipped — the Goldfox row has no email address.`);
+    }
+    if (totals.failed > 0)
+        info(`${totals.failed} failed.`);
+    info(`Reach them from a campaign with: --crm-origin goldfox`);
+}
+async function importCsv(path, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi crm contacts import <file.csv> [--org <id>]');
+    requireArg(path, 'file.csv', 'myapi crm contacts import <file.csv>');
+    if (!fs.existsSync(path))
+        error(`No such file: ${path}`);
+    const csv = fs.readFileSync(path, 'utf-8');
+    const r = await crm.importContacts(config.api_key, orgId, csv, path.split('/').pop());
+    if (flags.json) {
+        printJson(r);
+        return;
+    }
+    success(`${r.created} new contact(s), ${r.matched} already known`);
+    if (r.skipped > 0) {
+        // Every skipped row, with its line number — a count on its own is what
+        // sends somebody back to the spreadsheet to work out which twenty.
+        info(`${r.skipped} row(s) skipped:`);
+        for (const row of r.skipped_rows.slice(0, 20)) {
+            info(`  line ${row.line}: ${row.reason}${row.email ? ` (${row.email})` : ''}`);
+        }
+        if (r.skipped_rows.length > 20)
+            info(`  … and ${r.skipped_rows.length - 20} more (--json for all)`);
+    }
+    info('Reach them from a campaign with: --crm-origin import');
+}
 async function events(id, flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi crm contacts events <id> [--kind <k>] [--limit N] [--cursor <c>] [--org <id>]');
@@ -211,8 +280,10 @@ Subcommands:
   delete <id>                 Soft-delete (events retained)
   events <id>                 Timeline of events on a contact (newest first)
   get <id>                    Fetch one contact (with embedded Goldfox enrichment, when available)
+  import <file.csv>           Import contacts from CSV (header row; email column required)
   list                        Most-recently-engaged contacts (no filter)
   promote <goldfox_person_id> Promote a Goldfox lead → CRM contact (idempotent)
+  promote-audience <audience_id> Promote a whole saved people-audience (idempotent, resumable)
   restore <id>                Undo a soft-delete
   search                      Filter by stage / source / email / engagement window
   update <id>                 Patch stage, names, company_id, custom JSON
@@ -237,6 +308,8 @@ All commands accept --org <id> (or set default: myapi config set-org <id>).`);
         case 'delete': return del(args[0], flags);
         case 'restore': return restore(args[0], flags);
         case 'promote': return promote(args[0], flags);
+        case 'promote-audience': return promoteAudience(args[0], flags);
+        case 'import': return importCsv(args[0], flags);
         case 'events': return events(args[0], flags);
         default: error(`Unknown subcommand: ${subcommand}. Run "myapi crm contacts --help" for valid subcommands.`);
     }

package/dist/commands/crm/index.js

@@ -54,6 +54,7 @@ Each namespace shares the same subcommands:
   delete <id>                Soft delete (events retained)
   restore <id>               Restore a soft-deleted row
   promote <goldfox_id>       Promote a Goldfox lead into your CRM
+  promote-audience <id>     Promote a saved people-audience in bulk (idempotent, resumable)
 
 Contacts also have:
   events <id> [--kind <k>]   Inspect the contact's engagement timeline

package/dist/commands/email/campaign.d.ts

@@ -1,5 +1,5 @@
 import { type Flags } from '../../helpers.js';
 import type { Exposes } from '../../exposes.js';
 export declare const EXPOSES: Exposes;
-export declare const HELP = "Usage: myapi email campaign <subcommand>\n\n  create      Create a draft (--template, --from, and a source)\n  list        Campaigns in this org\n  get <id>    One campaign\n  update <id> Edit a DRAFT's name or source\n  resolve <id>  Freeze who it reaches; reports the count and cost, sends nothing\n  start <id>  Begin sending a resolved campaign\n  pause <id>  Stop after the message in flight\n  resume <id> Continue a paused campaign\n  cancel <id> End it for good; queued recipients are dropped\n  recipients <id>  Who it resolved to, and what happened to each\n  stats <id>  Counts by state, sent today, and the daily limit\n\nA campaign drains at its per-day limit rather than sending at once, so it is\ncommonly still active tomorrow \u2014 that is the design, not a stall.\n\nRecipients come from a SOURCE, not a list you upload:\n  --crm-stage / --crm-origin / --crm-max-days   filter CRM contacts\n  --addresses a@x.com,b@y.com                   an explicit short list";
+export declare const HELP = "Usage: myapi email campaign <subcommand>\n\n  create      Create a draft (--template, --from, and a source)\n  list        Campaigns in this org\n  get <id>    One campaign\n  update <id> Edit a DRAFT's name or source\n  resolve <id>  Freeze who it reaches; reports the count and cost, sends nothing\n  start <id>  Begin sending a resolved campaign\n  pause <id>  Stop after the message in flight\n  resume <id> Continue a paused campaign\n  cancel <id> End it for good; queued recipients are dropped\n  recipients <id>  Who it resolved to, and what happened to each\n  stats <id>  Counts by state, sent today, and the daily limit\n\nA campaign drains at its per-day limit rather than sending at once, so it is\ncommonly still active tomorrow \u2014 that is the design, not a stall.\n\nRecipients come from a SOURCE, not a list you upload:\n  --crm-stage / --crm-origin / --crm-max-days   filter CRM contacts\n  --crm-audience <id>                           only people promoted from it\n  --addresses a@x.com,b@y.com                   an explicit short list";
 export declare function run(sub: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/email/campaign.js

@@ -35,6 +35,7 @@ commonly still active tomorrow — that is the design, not a stall.
 
 Recipients come from a SOURCE, not a list you upload:
   --crm-stage / --crm-origin / --crm-max-days   filter CRM contacts
+  --crm-audience <id>                           only people promoted from it
   --addresses a@x.com,b@y.com                   an explicit short list`;
 // Building the source from flags is the one place the CLI has an opinion: a
 // campaign names where its people come from, and mixing two sources in one
@@ -50,6 +51,10 @@ function sourceFromFlags(flags) {
         crm.origin = flags['crm-origin'];
     if (typeof flags['crm-company'] === 'string' && flags['crm-company'])
         crm.company_id = flags['crm-company'];
+    // The people promoted from ONE saved audience, rather than every lead ever
+    // promoted — which is rarely the campaign anybody means.
+    if (typeof flags['crm-audience'] === 'string' && flags['crm-audience'])
+        crm.audience_id = flags['crm-audience'];
     if (typeof flags['crm-max-days'] === 'number')
         crm.max_last_engagement_days = flags['crm-max-days'];
     if (typeof flags['crm-min-days'] === 'number')
@@ -132,7 +137,8 @@ async function update(id, flags) {
     if (typeof flags.name === 'string' && flags.name)
         patch.name = flags.name;
     const wantsSource = flags.addresses || flags['crm-stage'] || flags['crm-origin']
-        || flags['crm-company'] || flags['crm-max-days'] || flags['crm-min-days'] || flags['all-contacts'];
+        || flags['crm-company'] || flags['crm-audience'] || flags['crm-max-days']
+        || flags['crm-min-days'] || flags['all-contacts'];
     if (wantsSource)
         Object.assign(patch, sourceFromFlags(flags));
     if (Object.keys(patch).length === 0)

package/dist/commands/email/index.js

@@ -19,6 +19,7 @@ export const SCHEMA = {
     'crm-stage': 'string',
     'crm-origin': 'string',
     'crm-company': 'string',
+    'crm-audience': 'string',
     'crm-max-days': 'number',
     'crm-min-days': 'number',
     'all-contacts': 'boolean',

package/dist/commands/env-commas.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/env-commas.test.js

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { _parseEnv, splitEnvEntries } from './container.js';
+// A container variable whose VALUE contains commas could not be set.
+//
+// `myapi container env <id> --env "ORIGINS=http://localhost:5173,https://dev.example.com"`
+// was refused with `Invalid --env entry "https://dev.example.com"` — the parser
+// split on every comma, so an origin list became two entries and the second had
+// no `=`. Three of one customer's variables are lists like that, and the same
+// defect at `create` is what sent them through three container generations in a
+// week. The command added to free them from the HTTP API reproduced it.
+describe('splitEnvEntries', () => {
+    it('keeps commas that belong to the value', () => {
+        expect(splitEnvEntries('ORIGINS=http://localhost:5173,https://dev.example.com'))
+            .toEqual(['ORIGINS=http://localhost:5173,https://dev.example.com']);
+    });
+    it('still splits several plain pairs, which is how people already write it', () => {
+        expect(splitEnvEntries('A=1,B=2')).toEqual(['A=1', 'B=2']);
+    });
+    it('treats a single pair as a single pair', () => {
+        expect(splitEnvEntries('A=1')).toEqual(['A=1']);
+    });
+    it('does not split when one segment is not a pair', () => {
+        // "A=1,B" is a value containing a comma, not a pair plus a malformed one.
+        expect(splitEnvEntries('A=1,B')).toEqual(['A=1,B']);
+    });
+});
+describe('_parseEnv', () => {
+    it('sets an origin list as one variable', () => {
+        const got = _parseEnv('ORIGINS=http://localhost:5173,https://dev.example.com');
+        expect(got).toEqual({ ORIGINS: 'http://localhost:5173,https://dev.example.com' });
+    });
+    it('keeps the multi-pair form working', () => {
+        expect(_parseEnv('A=1,B=2')).toEqual({ A: '1', B: '2' });
+    });
+    it('keeps = inside a value', () => {
+        expect(_parseEnv('URL=https://x?a=1')).toEqual({ URL: 'https://x?a=1' });
+    });
+    it('names the unambiguous form when it cannot parse', () => {
+        const got = _parseEnv('novalue');
+        expect(typeof got).toBe('string');
+        // The refusal must say how to succeed, not only that this failed.
+        expect(got).toContain('--env');
+    });
+});

package/dist/flag-schema-collisions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/flag-schema-collisions.test.js

@@ -0,0 +1,112 @@
+// Flags that mean different things in different commands must not be typed by
+// whichever command happens to be spread last.
+//
+// COMBINED_SCHEMA merges every command's SCHEMA to find the command name. A
+// merge resolves duplicate keys by declaration order, silently: `ttl` is
+// `number` in domain and llm and `string` in storage, and because storage
+// merges last, EVERY --ttl in the CLI parsed as a string. `domain records
+// create --ttl 3600` sent "3600", and `llm cache create --ttl 600` dropped the
+// value on a `typeof === 'number'` check — a flag documented in --help, parsed
+// without complaint, and discarded before the request.
+//
+// The dispatcher now re-parses under the command's own schema. This file has
+// two jobs: prove that per-command typing holds, and list the collisions so a
+// new one is a visible decision rather than an accident.
+//
+// It lives in src/ rather than test/smoke/ because it reads the schemas
+// directly and never drives the built binary. Filed under smoke originally, it
+// ran only in the push gate — so `npm test`, the command anyone reaches for,
+// could not catch a new collision. It caught one in CI instead, which is later
+// and more expensive than it needed to be.
+import { describe, it, expect } from 'vitest';
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { parseFlags } from './flags.js';
+import * as domainCmd from './commands/domain.js';
+import * as storageCmd from './commands/storage.js';
+import * as llmCmd from './commands/llm.js';
+import * as fnCmd from './commands/fn.js';
+import * as containerCmd from './commands/container.js';
+describe('per-command flag typing', () => {
+    it('types --ttl by the command, not by merge order', () => {
+        expect(parseFlags(['--ttl', '3600'], domainCmd.SCHEMA).flags.ttl).toBe(3600);
+        expect(parseFlags(['--ttl', '600'], llmCmd.SCHEMA).flags.ttl).toBe(600);
+        // storage's --ttl is a duration string ("1h"), which is why it is declared
+        // 'string' — the collision is legitimate, the silent resolution was not.
+        expect(parseFlags(['--ttl', '1h'], storageCmd.SCHEMA).flags.ttl).toBe('1h');
+    });
+    it('keeps repeated --scope accumulating for fn', () => {
+        // fn.ts documents that `--scope email --scope storage` accumulates. Under
+        // the merged schema container's 'string' won and this THREW instead.
+        expect(parseFlags(['--scope', 'email', '--scope', 'storage'], fnCmd.SCHEMA).flags.scope)
+            .toBe('email,storage');
+        expect(parseFlags(['--scope', 'all'], containerCmd.SCHEMA).flags.scope).toBe('all');
+    });
+    it('a merge still loses — which is why the dispatcher must not rely on one', () => {
+        // Pinning the old behaviour so the reason for the two-pass parse stays
+        // legible: this is what every command used to get.
+        const merged = { ...domainCmd.SCHEMA, ...storageCmd.SCHEMA };
+        expect(parseFlags(['--ttl', '3600'], merged).flags.ttl).toBe('3600');
+        const merged2 = { ...fnCmd.SCHEMA, ...containerCmd.SCHEMA };
+        expect(() => parseFlags(['--scope', 'a', '--scope', 'b'], merged2)).toThrow(/more than once/);
+    });
+});
+describe('collision inventory', () => {
+    it('every flag declared with two different types is listed here', async () => {
+        // Read every command module and collect flag → types. Plain fs rather than
+        // import.meta.glob: the tests are type-checked by tsc, which does not know
+        // Vite's glob helper.
+        const dir = fileURLToPath(new URL('./commands/', import.meta.url));
+        const files = readdirSync(dir)
+            // Some command modules have a colocated *.test.ts; importing one from
+            // inside a test makes vitest refuse the nested suite.
+            .filter(f => f.endsWith('.ts') && !f.endsWith('.test.ts') && !f.endsWith('.d.ts'));
+        const types = new Map();
+        let schemasSeen = 0;
+        for (const file of files) {
+            const mod = await import(pathToFileURL(join(dir, file)).href);
+            const schema = mod.SCHEMA;
+            if (!schema || typeof schema !== 'object')
+                continue;
+            schemasSeen++;
+            const name = file.replace(/\.ts$/, '');
+            for (const [flag, type] of Object.entries(schema)) {
+                if (!types.has(flag))
+                    types.set(flag, new Map());
+                const byType = types.get(flag);
+                if (!byType.has(type))
+                    byType.set(type, []);
+                byType.get(type).push(name);
+            }
+        }
+        // The scan must have found the command modules; an empty glob would make
+        // "no collisions" a statement about nothing.
+        expect(schemasSeen).toBeGreaterThan(20);
+        const collisions = [...types.entries()]
+            .filter(([, byType]) => byType.size > 1)
+            .map(([flag, byType]) => `${flag}: ` + [...byType.entries()]
+            .map(([t, cmds]) => `${t} (${cmds.sort().join(', ')})`).sort().join(' vs '))
+            .sort();
+        // Known and deliberate. Each is safe ONLY because the dispatcher types
+        // flags per command — adding one here means confirming that still holds.
+        expect(collisions).toEqual([
+            // fn accumulates repeated --scope into a list; container's --scope is a
+            // single value ("all"). Under the old merge, container won and
+            // `fn create --scope email --scope storage` threw "given more than once"
+            // — refusing the exact form fn.ts documents as supported.
+            // container's --env is repeatable so a value containing commas can be
+            // given on its own (`--env "ORIGINS=http://a,https://b"`), which is the
+            // shape an origin list actually has and which the single-string form
+            // refused. funnel's --env names a deploy channel (dev|prod) and is one
+            // value. Safe for the same reason as the others: the dispatcher types
+            // flags per command, so funnel never sees container's 'list'.
+            'env: list (container) vs string (funnel)',
+            'scope: list (fn) vs string (container)',
+            // domain's --ttl is DNS seconds and llm's is cache seconds; storage's is
+            // a duration string ("1h"). Under the old merge, storage won and both
+            // numeric ones silently became strings.
+            'ttl: number (domain, llm) vs string (storage)',
+        ]);
+    });
+});

package/dist/skills/my-crm-api/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-crm-api
-version: 1.0.2
+version: 1.2.0
 description: >
   The canonical store of engaged contacts + companies for an org. Auto-ingests from inbound webhooks via a configurable dot-path. Fixed lifecycle_stage enum (cold | warm | qualified | customer | churned). Append-only event timeline with reserved kinds. Soft delete + restore. Promote-from-Goldfox closes the discovery → engagement loop.
 triggers: [crm, contact, company, lead, engagement, pipeline, lifecycle, qualified, customer, webhook ingest, promote]
-checksum: sha256-ac33bd091d64089bf1d43b20431eff5361e018406bb5046f3c27fd628f7082fb
+checksum: sha256-fab860f3f7592640ab15b4f91670cba8217330617d7c9e96dd8e9e5f76abb657
 ---
 
 # MyCRMAPI
@@ -21,7 +21,7 @@ The store that closes the funnel. Without CRM the loop ends nowhere: discover pe
 - **mycrmapi** — engaged contacts + companies, *private to your org*, with engagement history
 
 A Goldfox row becomes a CRM contact when:
-1. You explicitly **promote** it (`myapi crm contacts promote <goldfox_person_id>`)
+1. You **promote** it (`myapi crm contacts promote <goldfox_person_id>`)
 2. *Or* a downstream service receives engagement for that email and auto-upserts the contact
 
 ### Lifecycle stages (fixed enum — same for contacts and companies)
@@ -48,22 +48,21 @@ email_sent | email_opened | email_clicked | email_replied
 pixel_visit | webhook_received | payment
 ```
 
-Agents cannot write events directly — the closed enum is intentional. For custom state use **mydatabaseapi** (KV) keyed on the contact id; the curated timeline stays authoritative.
+Agents cannot write events directly — the enum is closed on purpose. For custom state use **mydatabaseapi** keyed on the contact id.
 
 **Engagement kinds bump `last_engagement_at`**: email_*, pixel_visit, webhook_received. Admin kinds (created, promoted, stage_changed) don't — promoting a lead isn't engagement.
 
 ### Auto-ingest
 
-Today (v1):
-- **Webhook**: set per endpoint via `crm_email_path`, a JSON dot-path. Default `"email"` ingests `{"email":"x@y.com"}`. For Stripe, set `data.object.customer_email`; for GitHub, `sender.email`. Empty string disables ingest.
+- **Webhook** (live): set per endpoint via `crm_email_path`, a JSON dot-path. Default `"email"` ingests `{"email":"x@y.com"}`. For Stripe, set `data.object.customer_email`; for GitHub, `sender.email`. Empty string disables ingest.
 
-Coming next (backend wiring in progress):
+Coming next:
 - **Email**: every `myapi email message send` writes `email_sent`; opens/clicks fire `email_opened`/`email_clicked`
 - **Pixel**: `identify` calls with an email write `pixel_visit`
 
-If a contact doesn't exist for the matched email, it's auto-created with `source=` matching the originating service. The contact's company is auto-linked by email domain (creates the company on first sight).
+An unknown email auto-creates the contact with `source=` the originating service, and links its company by email domain.
 
-**Missing lead? Check `myapi webhook deliveries` before concluding it never arrived.** Raw payloads are always stored, so the delivery is there even when the contact isn't.
+**Missing lead? Check `myapi webhook deliveries` first.** Raw payloads are always stored, so the delivery is there even when the contact isn't.
 
 ### Soft delete + restore
 
@@ -71,11 +70,11 @@ If a contact doesn't exist for the matched email, it's auto-created with `source
 
 ### Goldfox enrichment (deferred)
 
-A contact promoted from Goldfox carries a `goldfox_person_id`; the embedded `goldfox_person` is null today, and Goldfox-only fields are not searchable.
+A promoted contact carries a `goldfox_person_id`; the embedded `goldfox_person` is null and Goldfox-only fields are not searchable.
 
 ### Search filter — re-engagement semantics
 
-`--max-last-engagement-days N` returns contacts last engaged *more than* N days ago, and intentionally **includes contacts with no engagement at all** (promoted-but-never-emailed Goldfox leads) — the natural targets of a re-engagement campaign. `--min-last-engagement-days N` is its complement: engaged *within* N days. `--company-id <id>` narrows to one company. To separate "never tried" from "tried and went cold," layer `--origin goldfox`.
+`--max-last-engagement-days N` returns contacts last engaged *more than* N days ago and intentionally **includes contacts never engaged at all** — promoted-but-never-emailed leads are the point of a re-engagement campaign. `--min-last-engagement-days N` is its complement; `--company-id` narrows to one company. Layer `--origin goldfox` to separate "never tried" from "went cold".
 
 ### Failure modes
 
@@ -99,6 +98,8 @@ A contact promoted from Goldfox carries a `goldfox_person_id`; the embedded `gol
 | `myapi crm contacts delete <id>` | Soft delete (events retained) |
 | `myapi crm contacts restore <id>` | Restore a soft-deleted contact |
 | `myapi crm contacts promote <goldfox_person_id>` | Idempotent Goldfox → CRM promote |
+| `myapi crm contacts promote-audience <audience_id>` | Bulk-promote a saved people-audience; idempotent, resumable |
+| `myapi crm contacts import <file.csv>` | CSV import; header row, `email` column required. Existing addresses are matched, never overwritten |
 | `myapi crm contacts events <id> [--kind ...]` | Timeline (newest first), filter by kind |
 
 ### Companies
@@ -114,10 +115,10 @@ All commands accept `--org <id>` (or set default: `myapi config set-org <id>`) a
 ## Examples
 <!-- llm:start -->
 ```bash
-# Discover → promote → engage workflow
-myapi people search --keyword saas --has-c-level --country US --limit 5 --json \
-  | jq -r '.people[].id' \
-  | while read pid; do myapi crm contacts promote "$pid"; done
+# Discover → promote → engage. Bulk resumes and cannot double-create.
+myapi audience list                                # saved Goldfox filters
+myapi crm contacts promote-audience <audience_id>  # whole audience
+myapi crm contacts promote <goldfox_person_id>     # or one lead
 
 # Find everyone in 'qualified' for a follow-up email
 myapi crm contacts search --stage qualified --json | jq -r '.contacts[].email'

package/dist/skills/my-email-api/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-email-api
-version: 1.1.0
+version: 1.2.0
 description: >
   Send transactional and bulk email from your own domain. Create mailboxes, send/receive messages, generate AI templates, and manage warmup.
 triggers: [email, mailbox, send email, transactional email, template, warmup, inbox, outbox, ses, sender reputation]
-checksum: sha256-17c2dfb50676262f2fe38688f5e7d9cfce3504354c17c06c3dd1dd1b8e39fa5e
+checksum: sha256-897cf3dbc843ca06d02aecf298151e8635890852a5db8ab4035ee59df8db0aa9
 ---
 
 # MyEmailAPI
@@ -75,6 +75,7 @@ myapi email warmup stats --address hello@yourdomain.com
 
 | `--addresses <csv>` | `campaign create` | An explicit short recipient list |
 | `--crm-stage`, `--crm-origin`, `--crm-company` | `campaign create` | Draw recipients from CRM instead |
+| `--crm-audience <id>` | `campaign create` | Only the people promoted from that saved audience |
 | `--crm-max-days`, `--crm-min-days` | `campaign create` | Engaged more than / within N days ago |
 | `--all-contacts` | `campaign create` | Every CRM contact — the unfiltered query, asked for by name |
 | `--state` | `campaign recipients` | Filter by `queued`, `sent`, `failed` or `excluded` |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "MyAPI command-line interface",
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.22.0"
+    "@myapihq/sdk": "^2.23.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",