shiply-cli 0.14.5 → 0.16.0

package/dist/contract.js

@@ -0,0 +1,143 @@
+/** B14 — `shiply contract <subcommand>` — CLI parity with the contract REST
+ *  + MCP surface shipped in B1-B13. The 7 subcommands cover the full contract
+ *  lifecycle: list / draft / show / send / pdf / amend / retract.
+ *
+ *  Every endpoint here is dev-only (Bearer auth via `~/.shiply/credentials`).
+ *  Customer-side reads happen through the intake portal cookie, not the CLI. */
+import { writeFile } from 'node:fs/promises';
+import { api, ApiError, resolveBase } from './publish.js';
+const headers = (apiKey) => ({
+    'content-type': 'application/json',
+    authorization: `Bearer ${apiKey}`,
+});
+function fmtMoney(cents, currency) {
+    if (cents === null || cents === undefined)
+        return '—';
+    const cur = currency ?? 'USD';
+    const sign = cents < 0 ? '-' : '';
+    const abs = Math.abs(cents);
+    const whole = Math.floor(abs / 100);
+    const frac = String(abs % 100).padStart(2, '0');
+    return `${sign}${cur} ${whole}.${frac}`;
+}
+function kind(c) {
+    return c.parentContractId ? 'amendment' : 'parent';
+}
+export async function contractList(ctx, projectId) {
+    if (!projectId)
+        throw new Error('usage: shiply contract list <project-id>');
+    const base = resolveBase(ctx.base);
+    const r = await api(`${base}/api/v1/projects/${encodeURIComponent(projectId)}/contracts`, { headers: headers(ctx.apiKey) });
+    if (!r.parent) {
+        console.log('No contract yet for this project. Draft one: shiply contract draft ' + projectId);
+        return;
+    }
+    const p = r.parent;
+    console.log(`Parent  ${p.id}  [${p.status}]  ${fmtMoney(p.feeCents, p.currency)}  scope="${(p.scopeSummary ?? '').slice(0, 60)}${(p.scopeSummary ?? '').length > 60 ? '…' : ''}"`);
+    if (p.sentAt)
+        console.log(`  sent     ${p.sentAt}`);
+    if (p.signedAt)
+        console.log(`  signed   ${p.signedAt}`);
+    for (const a of r.amendments) {
+        console.log(`Amend   ${a.id}  [${a.status}]  Δ${fmtMoney(a.feeDeltaCents, a.currency ?? p.currency)}  scope="${(a.scopeDelta ?? '').slice(0, 60)}${(a.scopeDelta ?? '').length > 60 ? '…' : ''}"`);
+        if (a.sentAt)
+            console.log(`  sent     ${a.sentAt}`);
+        if (a.signedAt)
+            console.log(`  signed   ${a.signedAt}`);
+    }
+}
+export async function contractDraft(ctx, projectId) {
+    if (!projectId)
+        throw new Error('usage: shiply contract draft <project-id>');
+    const base = resolveBase(ctx.base);
+    const r = await api(`${base}/api/v1/projects/${encodeURIComponent(projectId)}/contract`, { method: 'POST', headers: headers(ctx.apiKey), body: '{}' });
+    console.log(`✔ draft contract ${r.contract.id} created`);
+    console.log('  edit fields via the dashboard, then: shiply contract send ' + r.contract.id);
+}
+export async function contractShow(ctx, contractId) {
+    if (!contractId)
+        throw new Error('usage: shiply contract show <contract-id>');
+    const base = resolveBase(ctx.base);
+    const r = await api(`${base}/api/v1/contracts/${encodeURIComponent(contractId)}`, { headers: headers(ctx.apiKey) });
+    console.log(JSON.stringify(r.contract, null, 2));
+}
+export async function contractSend(ctx, contractId) {
+    if (!contractId)
+        throw new Error('usage: shiply contract send <contract-id>');
+    const base = resolveBase(ctx.base);
+    const r = await api(`${base}/api/v1/contracts/${encodeURIComponent(contractId)}/send`, { method: 'POST', headers: headers(ctx.apiKey), body: '{}' });
+    const k = kind(r.contract);
+    console.log(`✔ ${k} ${r.contract.id} sent — status=${r.contract.status}`);
+    if (r.contract.sentAt)
+        console.log(`  sent at ${r.contract.sentAt}`);
+    console.log('  customer receives an email + sees it on the intake portal');
+}
+export async function contractPdf(ctx, contractId, outPath) {
+    if (!contractId)
+        throw new Error('usage: shiply contract pdf <contract-id> -o file.pdf');
+    if (!outPath)
+        throw new Error('--out / -o <file.pdf> is required for shiply contract pdf');
+    const base = resolveBase(ctx.base);
+    const url = `${base}/api/v1/contracts/${encodeURIComponent(contractId)}/pdf`;
+    const res = await fetch(url, { headers: { authorization: `Bearer ${ctx.apiKey}` } });
+    if (!res.ok) {
+        // Use the same ApiError envelope the rest of the CLI does so 409
+        // contract_not_signed surfaces with a useful message + exit 1.
+        const body = await res.json().catch(() => ({}));
+        const err = body.error;
+        throw new ApiError(err?.code ?? 'http_error', err?.message ?? `HTTP ${res.status}`, res.status);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    await writeFile(outPath, bytes);
+    // Quick magic-bytes sanity check — `%PDF-` at the start of a real PDF.
+    const head = String.fromCharCode(...bytes.subarray(0, 5));
+    const looksLikePdf = head === '%PDF-';
+    console.log(`✔ wrote ${outPath} (${bytes.byteLength} bytes${looksLikePdf ? ', %PDF- header' : ', WARNING: not a PDF header'})`);
+}
+export async function contractAmend(ctx, contractId, opts) {
+    if (!contractId)
+        throw new Error('usage: shiply contract amend <contract-id> --scope "…" [--fee-delta N] [--target-date YYYY-MM-DD]');
+    if (!opts.scope)
+        throw new Error('--scope "<change description>" is required');
+    const base = resolveBase(ctx.base);
+    const body = { scopeDelta: opts.scope };
+    if (opts.feeDelta !== undefined) {
+        const n = Number(opts.feeDelta);
+        if (!Number.isFinite(n) || !Number.isInteger(n)) {
+            throw new Error('--fee-delta must be an integer (cents — use a negative number to discount)');
+        }
+        body.feeDeltaCents = n;
+    }
+    if (opts.targetDate)
+        body.targetCompletionDate = opts.targetDate;
+    const r = await api(`${base}/api/v1/contracts/${encodeURIComponent(contractId)}/amend`, { method: 'POST', headers: headers(ctx.apiKey), body: JSON.stringify(body) });
+    console.log(`✔ amendment ${r.contract.id} drafted against parent ${contractId}`);
+    console.log(`  Δscope    : ${r.contract.scopeDelta ?? '—'}`);
+    console.log(`  Δfee      : ${fmtMoney(r.contract.feeDeltaCents, null)}`);
+    if (r.contract.targetCompletionDate)
+        console.log(`  new target: ${r.contract.targetCompletionDate}`);
+    // Spec says: amend auto-sends unless the dev wants a beat. The default is
+    // to send immediately so the contract reaches the customer in one command;
+    // pass --keep-as-draft on `shiply contract retract` style usage if the dev
+    // wants to hold. Here we send unconditionally — amendments are a quick fix
+    // path, and the customer-portal preview is non-binding until signed.
+    const sent = await api(`${base}/api/v1/contracts/${encodeURIComponent(r.contract.id)}/send`, { method: 'POST', headers: headers(ctx.apiKey), body: '{}' });
+    console.log(`✔ amendment ${sent.contract.id} sent — status=${sent.contract.status}`);
+}
+export async function contractRetract(ctx, contractId, opts) {
+    if (!contractId)
+        throw new Error('usage: shiply contract retract <contract-id> [--keep-as-draft]');
+    const base = resolveBase(ctx.base);
+    const r = await api(`${base}/api/v1/contracts/${encodeURIComponent(contractId)}/retract`, {
+        method: 'POST',
+        headers: headers(ctx.apiKey),
+        body: JSON.stringify({ recoverAsDraft: Boolean(opts.keepAsDraft) }),
+    });
+    if (opts.keepAsDraft) {
+        console.log(`✔ contract ${contractId} retracted to draft — edit + re-send when ready`);
+    }
+    else {
+        console.log(`✔ contract ${contractId} retracted (status=${r.contract.status})`);
+    }
+    console.log('  project state reverted to brief_ready');
+}

package/dist/email.js

@@ -0,0 +1,147 @@
+/** `shiply email <subcommand>` — agent email send + inbox.
+ *
+ *  Pattern mirrors functions.ts: readFlags helper, exported runEmail
+ *  entry point, individual async command functions. Top-level flags
+ *  (--base / --key) are forwarded from index.ts via InheritedFlags. */
+import { loadApiKey } from './config.js';
+import { api, resolveBase } from './publish.js';
+function readFlags(argv, inherited = {}) {
+    const raw = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            if (eq >= 0) {
+                raw[a.slice(2, eq)] = a.slice(eq + 1);
+            }
+            else {
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    raw[a.slice(2)] = next;
+                    i++;
+                }
+                else {
+                    raw[a.slice(2)] = true;
+                }
+            }
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    // For each field: local argv flag takes precedence, then fall back to the
+    // value forwarded from index.ts parseArgs via inherited (the top-level
+    // parseArgs consumed these flags before argv reached us).
+    const flags = {
+        base: (typeof raw.base === 'string' ? raw.base : undefined) ?? inherited.base,
+        key: (typeof raw.key === 'string' ? raw.key : undefined) ?? inherited.key,
+        site: (typeof raw.site === 'string' ? raw.site : undefined) ?? inherited.site,
+        to: (typeof raw.to === 'string' ? raw.to : undefined) ?? inherited.to,
+        subject: (typeof raw.subject === 'string' ? raw.subject : undefined) ?? inherited.subject,
+        html: (typeof raw.html === 'string' ? raw.html : undefined) ?? inherited.html,
+        text: (typeof raw.text === 'string' ? raw.text : undefined) ?? inherited.text,
+    };
+    return { rest, flags };
+}
+const headers = (apiKey) => ({
+    'content-type': 'application/json',
+    authorization: `Bearer ${apiKey}`,
+});
+async function getApiKey(flags, what) {
+    const k = flags.key ?? (await loadApiKey());
+    if (!k)
+        throw new Error(`${what} commands need an API key — run \`shiply login\` first`);
+    return k;
+}
+const EMAIL_USAGE = [
+    'Usage: shiply email <send|inbox>',
+    '       shiply email send --site <slug> --to <addr> --subject <s> --html <h> [--text <t>]',
+    '       shiply email inbox [--site <slug>]',
+].join('\n');
+export async function runEmail(argv, inherited = {}) {
+    const action = argv[0];
+    const rest = argv.slice(1);
+    switch (action) {
+        case 'send':
+            return emailSendCmd(rest, inherited);
+        case 'inbox':
+            return emailInboxCmd(rest, inherited);
+        default:
+            console.error(EMAIL_USAGE);
+            process.exit(1);
+    }
+}
+async function emailSendCmd(argv, inherited) {
+    const { flags } = readFlags(argv, inherited);
+    if (!flags.site) {
+        console.error('--site <slug> is required');
+        console.error(EMAIL_USAGE);
+        process.exit(1);
+    }
+    if (!flags.to) {
+        console.error('--to <addr> is required');
+        console.error(EMAIL_USAGE);
+        process.exit(1);
+    }
+    if (!flags.subject) {
+        console.error('--subject <s> is required');
+        console.error(EMAIL_USAGE);
+        process.exit(1);
+    }
+    if (!flags.html) {
+        console.error('--html <h> is required');
+        console.error(EMAIL_USAGE);
+        process.exit(1);
+    }
+    const apiKey = await getApiKey(flags, 'email');
+    const base = resolveBase(flags.base);
+    const body = {
+        slug: flags.site,
+        to: flags.to,
+        subject: flags.subject,
+        html: flags.html,
+    };
+    if (flags.text)
+        body.text = flags.text;
+    const r = await api(`${base}/api/v1/email/send`, {
+        method: 'POST',
+        headers: headers(apiKey),
+        body: JSON.stringify(body),
+    });
+    console.log(`✔ sent`);
+    console.log(`  messageId: ${r.messageId}`);
+}
+async function emailInboxCmd(argv, inherited) {
+    const { flags } = readFlags(argv, inherited);
+    const apiKey = await getApiKey(flags, 'email');
+    const base = resolveBase(flags.base);
+    const qs = flags.site ? `?slug=${encodeURIComponent(flags.site)}` : '';
+    const r = await api(`${base}/api/v1/email/inbox${qs}`, {
+        headers: headers(apiKey),
+    });
+    if (!r.threads.length) {
+        console.log('No threads yet.');
+        return;
+    }
+    // Compact table: ID | SITE | FROM | SUBJECT | LAST
+    const cols = r.threads.map((t) => ({
+        id: t.id,
+        site: t.siteSlug ?? '',
+        from: t.from ?? '',
+        subject: t.subject ?? '',
+        last: t.lastAt ?? '',
+        count: String(t.messageCount ?? 1),
+    }));
+    const w = {
+        id: Math.max('ID'.length, ...cols.map((c) => c.id.length)),
+        site: Math.max('SITE'.length, ...cols.map((c) => c.site.length)),
+        from: Math.max('FROM'.length, ...cols.map((c) => c.from.length)),
+        subject: Math.max('SUBJECT'.length, ...cols.map((c) => c.subject.length)),
+        count: Math.max('#'.length, ...cols.map((c) => c.count.length)),
+    };
+    console.log(`${'ID'.padEnd(w.id)}  ${'SITE'.padEnd(w.site)}  ${'FROM'.padEnd(w.from)}  ${'SUBJECT'.padEnd(w.subject)}  ${'#'.padEnd(w.count)}  LAST`);
+    for (const c of cols) {
+        console.log(`${c.id.padEnd(w.id)}  ${c.site.padEnd(w.site)}  ${c.from.padEnd(w.from)}  ${c.subject.padEnd(w.subject)}  ${c.count.padEnd(w.count)}  ${c.last}`);
+    }
+}

package/dist/index.js

@@ -14,7 +14,10 @@ import { domainAdd, domainConnect, domainLs, domainPrimary, domainSubAdd, domain
 import { runProject } from './projects.js';
 import { runListing } from './listings.js';
 import { runSendingDomain } from './sending-domains.js';
+import { contractAmend, contractDraft, contractList, contractPdf, contractRetract, contractSend, contractShow, } from './contract.js';
 import { runCron, runFunction, runSecret } from './functions.js';
+import { runEmail } from './email.js';
+import { runMailbox } from './mailbox.js';
 import { loadApiKey, saveApiKey } from './config.js';
 import { loginViaDeviceFlow } from './login.js';
 import { api, ApiError, DEFAULT_BASE, publish, resolveBase } from './publish.js';
@@ -84,6 +87,25 @@ Usage:
                                               in your worker on next deploy/restart.
   shiply cron <ls|set|rm> <slug>              Manage cron triggers on the deployed worker
                                               shiply cron set <slug> /api/cron/foo "0 9 * * *"
+  shiply contract <list|draft|show|send|pdf|amend|retract>
+                                              Customer contracts — full lifecycle CLI (B14).
+                                              list <project-id> — parent + amendments table
+                                              draft <project-id> — creates a draft you can edit
+                                              show <contract-id> — prints the full row as JSON
+                                              send <contract-id> — emails it to the customer
+                                              pdf <contract-id> -o file.pdf — signed PDF download
+                                              amend <id> --scope "…" [--fee-delta N] [--target-date YYYY-MM-DD]
+                                              retract <id> [--keep-as-draft] — undo a sent contract
+  shiply email send --site <slug> --to <addr> --subject <s> --html <h> [--text <t>]
+                                              Send a transactional email from a site's inbox address
+  shiply email inbox [--site <slug>]          List email threads (optionally filtered by site)
+  shiply mailbox set <slug> <collection> [--confirm] [--no-confirm] [--notify] [--no-notify]
+                            [--notify-to <email>] [--from <sendingDomainId>]
+                                              Update mailbox settings (double-opt-in, owner notifications…)
+  shiply mailbox broadcast <slug> <collection> --subject <s> --html <h> [--text <t>]
+                                              Send a broadcast to all contacts in a mailbox collection
+  shiply mailbox contacts <slug> <collection> [--status <signed_up|confirmed|unsubscribed>]
+                                              List contacts in a mailbox collection
   shiply data init [dir]                      Scaffold a starter .shiply/data.json in <dir> (default cwd)
   shiply data list <slug>                     List collections on a site with counts
   shiply data query <slug> <coll> [--limit N] [--cursor C] [--where '<json>']
@@ -197,6 +219,21 @@ async function main() {
             limit: { type: 'string' },
             cursor: { type: 'string' },
             where: { type: 'string' },
+            scope: { type: 'string' },
+            'fee-delta': { type: 'string' },
+            'target-date': { type: 'string' },
+            'keep-as-draft': { type: 'boolean' },
+            to: { type: 'string' },
+            subject: { type: 'string' },
+            html: { type: 'string' },
+            text: { type: 'string' },
+            status: { type: 'string' },
+            confirm: { type: 'boolean' },
+            'no-confirm': { type: 'boolean' },
+            notify: { type: 'boolean' },
+            'no-notify': { type: 'boolean' },
+            'notify-to': { type: 'string' },
+            from: { type: 'string' },
             help: { type: 'boolean', short: 'h' },
             version: { type: 'boolean', short: 'v' },
         },
@@ -601,6 +638,95 @@ async function main() {
             });
             break;
         }
+        case 'contract': {
+            const apiKey = values.key ?? (await loadApiKey());
+            if (!apiKey)
+                throw new Error('contract commands need an API key — run `shiply login` first');
+            const cctx = { base: values.base, apiKey };
+            const sub = dir; // positionals[1]
+            const arg = positionals[2]; // contract or project id
+            switch (sub) {
+                case 'list':
+                    if (!arg)
+                        throw new Error('usage: shiply contract list <project-id>');
+                    await contractList(cctx, arg);
+                    return;
+                case 'draft':
+                    if (!arg)
+                        throw new Error('usage: shiply contract draft <project-id>');
+                    await contractDraft(cctx, arg);
+                    return;
+                case 'show':
+                    if (!arg)
+                        throw new Error('usage: shiply contract show <contract-id>');
+                    await contractShow(cctx, arg);
+                    return;
+                case 'send':
+                    if (!arg)
+                        throw new Error('usage: shiply contract send <contract-id>');
+                    await contractSend(cctx, arg);
+                    return;
+                case 'pdf':
+                    if (!arg)
+                        throw new Error('usage: shiply contract pdf <contract-id> -o file.pdf');
+                    await contractPdf(cctx, arg, values.out);
+                    return;
+                case 'amend':
+                    if (!arg)
+                        throw new Error('usage: shiply contract amend <contract-id> --scope "…" [--fee-delta N] [--target-date YYYY-MM-DD]');
+                    await contractAmend(cctx, arg, {
+                        scope: values.scope,
+                        feeDelta: values['fee-delta'],
+                        targetDate: values['target-date'],
+                    });
+                    return;
+                case 'retract':
+                    if (!arg)
+                        throw new Error('usage: shiply contract retract <contract-id> [--keep-as-draft]');
+                    await contractRetract(cctx, arg, { keepAsDraft: Boolean(values['keep-as-draft']) });
+                    return;
+                default:
+                    throw new Error('usage: shiply contract <list|draft|show|send|pdf|amend|retract>');
+            }
+        }
+        case 'email': {
+            await runEmail(positionals.slice(1), {
+                base: values.base,
+                key: values.key,
+                site: values.site,
+                to: values.to,
+                subject: values.subject,
+                html: values.html,
+                text: values.text,
+            });
+            break;
+        }
+        case 'mailbox': {
+            // Resolve tri-state for confirm/notify:
+            //   --confirm        → true   (values.confirm === true)
+            //   --no-confirm     → false  (values['no-confirm'] === true)
+            //   neither provided → undefined (omit from PATCH body)
+            const confirmValue = values.confirm === true ? true :
+                values['no-confirm'] === true ? false :
+                    undefined;
+            const notifyValue = values.notify === true ? true :
+                values['no-notify'] === true ? false :
+                    undefined;
+            await runMailbox(positionals.slice(1), {
+                base: values.base,
+                key: values.key,
+                site: values.site,
+                subject: values.subject,
+                html: values.html,
+                text: values.text,
+                status: values.status,
+                ...(confirmValue !== undefined ? { confirm: confirmValue } : {}),
+                ...(notifyValue !== undefined ? { notify: notifyValue } : {}),
+                'notify-to': values['notify-to'],
+                from: values.from,
+            });
+            break;
+        }
         case 'claim': {
             if (dir !== 'verify') {
                 console.error('Usage: shiply claim verify <SHIPLY-XXXXXXXX>');

package/dist/mailbox.js

@@ -0,0 +1,199 @@
+/** `shiply mailbox <subcommand>` — mailbox settings, broadcasts, contacts.
+ *
+ *  Pattern mirrors functions.ts: readFlags helper, exported runMailbox
+ *  entry point, individual async command functions. Top-level flags
+ *  (--base / --key) are forwarded from index.ts via InheritedFlags. */
+import { loadApiKey } from './config.js';
+import { api, resolveBase } from './publish.js';
+function readFlags(argv, inherited = {}) {
+    const raw = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--no-')) {
+            // --no-confirm, --no-notify → store as false
+            raw[a.slice(5)] = false;
+        }
+        else if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            if (eq >= 0) {
+                raw[a.slice(2, eq)] = a.slice(eq + 1);
+            }
+            else {
+                const next = argv[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    raw[a.slice(2)] = next;
+                    i++;
+                }
+                else {
+                    raw[a.slice(2)] = true;
+                }
+            }
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    // For each field: local argv flag takes precedence, then fall back to the
+    // value forwarded from index.ts parseArgs via inherited (the top-level
+    // parseArgs consumed these flags before argv reached us).
+    const flags = {
+        base: (typeof raw.base === 'string' ? raw.base : undefined) ?? inherited.base,
+        key: (typeof raw.key === 'string' ? raw.key : undefined) ?? inherited.key,
+        from: (typeof raw.from === 'string' ? raw.from : undefined) ?? inherited.from,
+        'notify-to': (typeof raw['notify-to'] === 'string' ? raw['notify-to'] : undefined) ?? inherited['notify-to'],
+        subject: (typeof raw.subject === 'string' ? raw.subject : undefined) ?? inherited.subject,
+        html: (typeof raw.html === 'string' ? raw.html : undefined) ?? inherited.html,
+        text: (typeof raw.text === 'string' ? raw.text : undefined) ?? inherited.text,
+        status: (typeof raw.status === 'string' ? raw.status : undefined) ?? inherited.status,
+    };
+    // Boolean toggles — only set when the flag was explicitly provided (local
+    // argv), or when index.ts forwarded a parsed value via inherited.
+    if ('confirm' in raw) {
+        flags.confirm = Boolean(raw.confirm);
+    }
+    else if (inherited.confirm !== undefined) {
+        flags.confirm = inherited.confirm;
+    }
+    if ('notify' in raw) {
+        flags.notify = Boolean(raw.notify);
+    }
+    else if (inherited.notify !== undefined) {
+        flags.notify = inherited.notify;
+    }
+    return { rest, flags };
+}
+const headers = (apiKey) => ({
+    'content-type': 'application/json',
+    authorization: `Bearer ${apiKey}`,
+});
+async function getApiKey(flags, what) {
+    const k = flags.key ?? (await loadApiKey());
+    if (!k)
+        throw new Error(`${what} commands need an API key — run \`shiply login\` first`);
+    return k;
+}
+const MAILBOX_USAGE = [
+    'Usage: shiply mailbox <set|broadcast|contacts>',
+    '       shiply mailbox set <slug> <collection> [--confirm] [--no-confirm] [--notify] [--no-notify] [--notify-to <email>] [--from <sendingDomainId>]',
+    '       shiply mailbox broadcast <slug> <collection> --subject <s> --html <h> [--text <t>]',
+    '       shiply mailbox contacts <slug> <collection> [--status <signed_up|confirmed|unsubscribed>]',
+].join('\n');
+export async function runMailbox(argv, inherited = {}) {
+    const action = argv[0];
+    const rest = argv.slice(1);
+    switch (action) {
+        case 'set':
+            return mailboxSetCmd(rest, inherited);
+        case 'broadcast':
+            return mailboxBroadcastCmd(rest, inherited);
+        case 'contacts':
+            return mailboxContactsCmd(rest, inherited);
+        default:
+            console.error(MAILBOX_USAGE);
+            process.exit(1);
+    }
+}
+async function mailboxSetCmd(argv, inherited) {
+    const { rest, flags } = readFlags(argv, inherited);
+    const [slug, collection] = rest;
+    if (!slug || !collection) {
+        console.error('usage: shiply mailbox set <slug> <collection> [options]');
+        console.error(MAILBOX_USAGE);
+        process.exit(1);
+    }
+    const apiKey = await getApiKey(flags, 'mailbox');
+    const base = resolveBase(flags.base);
+    // Only include fields that were explicitly provided
+    const body = {};
+    if (flags.confirm !== undefined)
+        body.doubleOptIn = flags.confirm;
+    if (flags.notify !== undefined)
+        body.notifyOwner = flags.notify;
+    if (flags['notify-to'] !== undefined)
+        body.notifyTo = flags['notify-to'];
+    if (flags.from !== undefined)
+        body.sendingDomainId = flags.from;
+    const r = await api(`${base}/api/v1/publishes/${encodeURIComponent(slug)}/mailboxes/${encodeURIComponent(collection)}`, {
+        method: 'PATCH',
+        headers: headers(apiKey),
+        body: JSON.stringify(body),
+    });
+    console.log(`✔ mailbox updated for ${slug}/${collection}`);
+    if (r.doubleOptIn !== undefined)
+        console.log(`  doubleOptIn: ${r.doubleOptIn}`);
+    if (r.notifyOwner !== undefined)
+        console.log(`  notifyOwner: ${r.notifyOwner}`);
+    if (r.notifyTo !== undefined && r.notifyTo !== null)
+        console.log(`  notifyTo: ${r.notifyTo}`);
+    if (r.sendingDomainId !== undefined && r.sendingDomainId !== null)
+        console.log(`  sendingDomainId: ${r.sendingDomainId}`);
+}
+async function mailboxBroadcastCmd(argv, inherited) {
+    const { rest, flags } = readFlags(argv, inherited);
+    const [slug, collection] = rest;
+    if (!slug || !collection) {
+        console.error('usage: shiply mailbox broadcast <slug> <collection> --subject <s> --html <h>');
+        console.error(MAILBOX_USAGE);
+        process.exit(1);
+    }
+    if (!flags.subject) {
+        console.error('--subject <s> is required');
+        console.error(MAILBOX_USAGE);
+        process.exit(1);
+    }
+    if (!flags.html) {
+        console.error('--html <h> is required');
+        console.error(MAILBOX_USAGE);
+        process.exit(1);
+    }
+    const apiKey = await getApiKey(flags, 'mailbox');
+    const base = resolveBase(flags.base);
+    const body = {
+        subject: flags.subject,
+        html: flags.html,
+    };
+    if (flags.text)
+        body.text = flags.text;
+    const r = await api(`${base}/api/v1/publishes/${encodeURIComponent(slug)}/mailboxes/${encodeURIComponent(collection)}/broadcast`, {
+        method: 'POST',
+        headers: headers(apiKey),
+        body: JSON.stringify(body),
+    });
+    console.log(`✔ broadcast queued`);
+    console.log(`  broadcastId: ${r.broadcastId}`);
+    console.log(`  recipientCount: ${r.recipientCount}`);
+}
+async function mailboxContactsCmd(argv, inherited) {
+    const { rest, flags } = readFlags(argv, inherited);
+    const [slug, collection] = rest;
+    if (!slug || !collection) {
+        console.error('usage: shiply mailbox contacts <slug> <collection> [--status <...>]');
+        console.error(MAILBOX_USAGE);
+        process.exit(1);
+    }
+    const apiKey = await getApiKey(flags, 'mailbox');
+    const base = resolveBase(flags.base);
+    const qs = flags.status ? `?status=${encodeURIComponent(flags.status)}` : '';
+    const r = await api(`${base}/api/v1/publishes/${encodeURIComponent(slug)}/mailboxes/${encodeURIComponent(collection)}/contacts${qs}`, { headers: headers(apiKey) });
+    if (!r.contacts.length) {
+        console.log(`No contacts in ${slug}/${collection}${flags.status ? ` (status: ${flags.status})` : ''} yet.`);
+        return;
+    }
+    // Compact table: EMAIL | STATUS | CONFIRMED | CREATED
+    const cols = r.contacts.map((c) => ({
+        email: c.email,
+        status: c.status ?? '',
+        confirmed: c.confirmedAt ?? '',
+        created: c.createdAt ?? '',
+    }));
+    const w = {
+        email: Math.max('EMAIL'.length, ...cols.map((c) => c.email.length)),
+        status: Math.max('STATUS'.length, ...cols.map((c) => c.status.length)),
+        confirmed: Math.max('CONFIRMED'.length, ...cols.map((c) => c.confirmed.length)),
+    };
+    console.log(`${'EMAIL'.padEnd(w.email)}  ${'STATUS'.padEnd(w.status)}  ${'CONFIRMED'.padEnd(w.confirmed)}  CREATED`);
+    for (const c of cols) {
+        console.log(`${c.email.padEnd(w.email)}  ${c.status.padEnd(w.status)}  ${c.confirmed.padEnd(w.confirmed)}  ${c.created}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shiply-cli",
-  "version": "0.14.5",
+  "version": "0.16.0",
   "description": "Publish static sites to shiply.now from the command line — instant web hosting for agents.",
   "license": "MIT",
   "type": "module",

package/skill/SKILL.md

@@ -18,7 +18,7 @@ description: Publish static sites to the web instantly with shiply.now and manag
 > fresh — your cached copy may be missing features like databases, projects,
 > marketplace, or sending domains.
 >
-> **Last updated: 2026-06-20**
+> **Last updated: 2026-06-22**
 
 ---
 
@@ -154,6 +154,8 @@ lines for automation; exit code 0 = ready.
    (+ "Authorization: Bearer shp_…" for permanent owned sites)
 2. PUT each file's bytes to response upload.uploads[].url
 3. POST upload.finalizeUrl with {"versionId":"..."}
+   → both the publish and finalize responses include a "toUpdate" string: the
+     exact call to update THIS site next time. Follow it — never create a new one.
 ```
 
 **ALWAYS include `agentName` on anonymous publishes.** The response then
@@ -164,9 +166,11 @@ poll `poll_url` every `interval` seconds with the `device_code`, and on
 is claimed in the same Allow click. Without `agentName` the user has to
 do a separate manual claim step every time.
 
-**Updates:** anonymous → include `"claimToken":"..."` (returned ONCE by the
-first publish — save it); owned → include `"slug":"..."`. Hashes make updates
-cheap: unchanged files are skipped server-side.
+**Updates (the response tells you how):** every publish/finalize response
+includes a `toUpdate` string with the exact call — follow it verbatim. In short:
+anonymous → include `"claimToken":"..."` (returned ONCE by the first publish —
+save it); owned → include `"slug":"..."`. Hashes make updates cheap: unchanged
+files are skipped server-side.
 
 ## The lifecycle to explain to users
 - Anonymous site: live instantly, expires in 24 h. Give the user the
@@ -265,6 +269,98 @@ validated server-side; the owner reads them in the dashboard (Data section,
 CSV export) or GET /api/v1/publishes/<slug>/data/<collection> with a Bearer
 key. Owned sites only. Docs: /docs/site-data
 
+## Agent Email — inbox, send, capture, broadcast (built into every owned site)
+
+Every owned site has a real email address and can send, receive, capture signups,
+and broadcast — in one line. Like AgentMail, built into the site.
+
+### Capture (public, zero-config)
+```
+POST /.shiply/email  { "email": "user@example.com", ...anyExtraFields }
+```
+No manifest needed. Works on the **relative path** from the published page.
+On success: record lands in the site inbox + owner gets a notification ping +
+a double-opt-in confirmation email goes to the visitor (all on by default).
+**Owned sites only** — anonymous sites get `403 email_requires_account` (claim
+the site first). A non-empty `company` field is treated as a honeypot (bot
+submissions are silently dropped). Caps: 16 KB body, 30 fields max.
+
+### Send (authenticated — Bearer key only)
+The public page can NEVER send; only authenticated calls can.
+```
+POST https://shiply.now/api/v1/email/send
+Authorization: Bearer shp_…
+{ "slug": "my-site", "to": "user@example.com", "subject": "Hi", "html": "<p>Hi</p>", "text": "Hi" }
+→ { "messageId": "..." }
+```
+
+### Read inbox
+```
+GET https://shiply.now/api/v1/email/inbox          # all sites
+GET https://shiply.now/api/v1/email/inbox?slug=my-site
+Authorization: Bearer shp_…
+```
+
+### Typed upgrade (optional)
+Declare an `email` block on a `.shiply/data.json` collection for typed fields +
+fine-grained control:
+```json
+{
+  "collections": {
+    "signups": {
+      "fields": { "email": { "type": "email", "required": true } },
+      "email": {
+        "emailField": "email",
+        "confirm": true,
+        "notify": true,
+        "audience": true
+      }
+    }
+  }
+}
+```
+All three flags default to `true`. With this manifest, POST to
+`/.shiply/data/signups` as usual — the `email` block activates the email
+layer on that collection.
+
+### Confirm / unsubscribe (public — in the confirmation email)
+```
+GET /api/email/<slug>/<collection>/confirm?token=<token>
+GET /api/email/<slug>/<collection>/unsubscribe?email=<address>
+```
+
+### Audience + broadcast
+Confirmed (double-opt-in) signups form a list. Broadcast to them:
+```
+POST /api/v1/publishes/<slug>/mailboxes/<collection>/broadcast
+Authorization: Bearer shp_…
+{ "subject": "Launch day", "html": "<p>We're live!</p>" }
+```
+Spam-checked before send; unsubscribe footer is auto-added; requires ≥1
+confirmed subscriber.
+
+Configure a mailbox: `GET/PATCH /api/v1/publishes/<slug>/mailboxes/<collection>`
+List contacts: `GET /api/v1/publishes/<slug>/mailboxes/<collection>/contacts?status=confirmed`
+
+### MCP tools
+| Tool | Purpose |
+|---|---|
+| `send_email` | Send transactional email from a site (Bearer) |
+| `list_site_inbox` | Read the inbox (all threads or filter by slug) |
+| `set_mailbox` | Configure a collection's mailbox settings |
+| `list_mailbox_contacts` | List audience contacts (filter by status) |
+| `send_mailbox_broadcast` | Broadcast to confirmed audience (spam-checked) |
+
+### CLI
+```bash
+shiply email send --site <slug> --to <address> --subject <subject> --html <html>
+shiply email inbox [--site <slug>]
+shiply mailbox set <slug> <collection> [--confirm] [--notify] [--from <domain>]
+shiply mailbox broadcast <slug> <collection> --subject <subject> --html <html>
+```
+
+Docs: https://shiply.now/docs/agent-email
+
 ## SQL databases (Cloudflare D1 + Neon Postgres)
 Two engines, same CLI/REST/MCP surface. **D1 (SQLite at the edge)** is
 free on every plan and queryable from the browser via a built-in fetch
@@ -493,6 +589,56 @@ CLI: `shiply project ls · shiply project create <label> [--customer-email <e>]
 
 Docs: https://shiply.now/docs/projects
 
+## Contracts — draft, sign, amend (extends Projects)
+
+Once a project reaches `brief_ready`, the dev drafts a signed contract from
+the brief, the customer e-signs in the portal (typed-name + checkbox), and
+the dev amends it later as scope evolves. A signed contract is immutable
+— any change is a new amendment row chained off the parent. The portal
+sends the customer; the dev can resend / remind / retract. A 7-day
+reminder cron nudges unsigned contracts automatically.
+
+MCP tools:
+```
+contract_draft   — draft a contract from a brief_ready project (returns the new contract id)
+contract_send    — flip status='sent', fire customer email (parent OR amendment)
+contract_amend   — create an amendment draft on a SIGNED parent (scopeDelta required, fee + date optional)
+contract_status  — read state + amendments (poll this to see status='signed')
+contract_pdf     — base64-encoded signed PDF (parent + cert + signed amendments)
+```
+
+Edit-before-send today is REST-only: `PATCH /api/v1/contracts/{id}` lets
+the dev tweak the 8 fields (scopeSummary, feeCents, currency, dates,
+revisionCount, revisionOverageCents, jurisdiction). After PATCH, call
+`contract_send` to fire it. Amendments are sent the same way (call
+`contract_send` with the amendment id returned by `contract_amend`).
+
+Example agent flow (draft → tweak fee → send → poll → amend):
+1. `contract_draft({projectId})` → returns `{id, scopeSummary, feeCents:null, ...}`
+2. `PATCH /api/v1/contracts/{id}` `{feeCents: 450000}` (Bearer key)
+3. `contract_send({contractId: id})` → project flips to `contract_sent`
+4. Poll `contract_status({contractId: id})` until `contract.status === 'signed'`
+5. `contract_amend({parentContractId: id, scopeDelta: "Add login flow", feeDeltaCents: 50000})` → returns the amendment row
+6. `contract_send({contractId: amendment.id})` (no PATCH needed if the amend fields are right)
+
+REST (Bearer for dev, portal cookie for customer):
+`POST /api/v1/projects/{id}/contracts` (draft) ·
+`GET/PATCH /api/v1/contracts/{id}` (read either-party / dev edit) ·
+`POST /api/v1/contracts/{id}/send` (dev) ·
+`POST /api/v1/contracts/{id}/view` (customer ping) ·
+`POST /api/v1/contracts/{id}/sign` (customer e-sign) ·
+`POST /api/v1/contracts/{id}/retract` (dev; `?recoverAsDraft=true` to
+recover the draft instead of voiding) ·
+`POST /api/v1/contracts/{id}/amend` (dev; signed parents only) ·
+`POST /api/v1/contracts/{id}/remind` ·
+`POST /api/v1/contracts/{id}/resend` (manual nudges, rate-limited 3/24h) ·
+`GET /api/v1/contracts/{id}/pdf` (binary, signed only).
+
+`contract_pdf` returns `{filename, contentType:"application/pdf", base64,
+byteLength}` so the MCP client can decode and save the bytes.
+
+Docs: https://shiply.now/docs/contracts
+
 ## Marketplace — sell built sites
 
 Devs can list any owned site for sale: set a price + short pitch, choose