sizmo 0.4.0

package/commands/receivables.mjs

@@ -0,0 +1,119 @@
+// commands/receivables.mjs — A/R: who owes, how much, how old.
+// Trust-fix #1: LOC from ctx.cfg.loc.
+// Trust-fix #2: invoices paginate to completion (was offset-capped at 2000).
+// Trust-fix #3: per-currency totals (never cross-sum).
+// READ-ONLY. Agent can send/void one at a time, L2 confirm. NEVER charges.
+import { paginate } from '../lib/paginate.mjs';
+
+export const meta = {
+  name: 'receivables',
+  summary: 'A/R — who owes, how much, how old',
+  flags: [
+    { name: '--top', type: 'int', default: 20, desc: 'max rows to display' },
+  ],
+  readOnly: true,
+};
+
+const SYM = { PHP: '₱', USD: '$', EUR: '€', GBP: '£' };
+const money = (n, c = 'PHP') => (SYM[c] || c + ' ') + Number(n || 0).toLocaleString('en-PH', { maximumFractionDigits: 0 });
+const UNPAID = new Set(['sent', 'overdue', 'partially_paid', 'partially paid', 'payment_processing', 'viewed', 'due']);
+
+export async function collect(args, ctx) {
+  const TOP = args.top ?? 20;
+  const LOC = ctx.cfg.loc;
+  const NOW = ctx.now;
+  const ageDays = (t) => t ? Math.floor((NOW - t) / 86400000) : null;
+
+  let firstErr = null;
+  const inv = [];
+  for await (const item of paginate({
+    fetchPage: async (offset = 0) => {
+      const r = await ctx.http.get('/invoices/', {
+        query: { altId: LOC, altType: 'location', limit: 100, offset },
+      });
+      if (!r.ok) return { _err: r.code, invoices: [] };
+      return r.j;
+    },
+    getItems: (resp) => {
+      if (resp._err) { firstErr = resp._err; return []; }
+      return resp.invoices || resp.data || [];
+    },
+    nextCursor: (resp, items, offset = 0) => {
+      if (resp._err || items.length < 100) return null;
+      return offset + 100;
+    },
+    maxPages: 500,
+    startCursor: 0,
+  })) {
+    inv.push(item);
+  }
+
+  if (firstErr && inv.length === 0) {
+    ctx.out.warn(`can't see invoices → HTTP ${firstErr}`, { degraded: true });
+    return { location: LOC, scanned: 0, outstanding: 0, totalOwed: 0, currency: 'PHP', list: [] };
+  }
+
+  const owed = inv
+    .filter(i => UNPAID.has(String(i.status || '').toLowerCase()))
+    .map(i => {
+      const total = Number(i.total ?? i.amount ?? i.invoiceTotal ?? 0);
+      const paid = Number(i.amountPaid ?? i.totalPaid ?? 0);
+      const due = total - paid;
+      const dt = Date.parse(i.dueDate || i.issueDate || i.createdAt) || 0;
+      return {
+        name: i.contactDetails?.name || i.name || i.invoiceNumber || '(unknown)',
+        num: i.invoiceNumber || i._id || i.id,
+        due, total,
+        cur: (i.currency || 'PHP').toUpperCase(),
+        status: i.status,
+        age: ageDays(dt),
+        id: i._id || i.id,
+      };
+    })
+    .filter(x => x.due > 0.0001)
+    .sort((a, b) => (b.age || 0) - (a.age || 0));
+
+  // per-currency totals (trust-fix #3)
+  const byCur = {};
+  for (const x of owed) {
+    byCur[x.cur] = (byCur[x.cur] || 0) + x.due;
+  }
+  // keep backward-compat: single currency → flat totalOwed + currency; multi → byCurrency map
+  const currencies = Object.keys(byCur);
+  const totalOwed = currencies.length === 1 ? byCur[currencies[0]] : Object.values(byCur).reduce((s, v) => s + v, 0);
+  const currency = currencies.length === 1 ? currencies[0] : (owed[0]?.cur || 'PHP');
+
+  return {
+    location: LOC,
+    scanned: inv.length,
+    outstanding: owed.length,
+    totalOwed,
+    currency,
+    ...(currencies.length > 1 ? { byCurrency: byCur } : {}),
+    list: owed.slice(0, TOP),
+  };
+}
+
+export async function run(args, ctx) {
+  const data = await collect(args, ctx);
+  ctx.out.data(data);
+
+  const TOP = args.top ?? 20;
+  ctx.out.card(() => {
+    ctx.out.line(`\n  RECEIVABLES — ${money(data.totalOwed, data.currency)} outstanding across ${data.outstanding} invoice(s)  ·  ${data.scanned} scanned  ·  loc ${data.location}`);
+    ctx.out.line('  ' + '─'.repeat(72));
+    if (!data.list.length) {
+      ctx.out.line('  Nothing outstanding. All settled. ✅\n');
+      return;
+    }
+    data.list.forEach((x, i) => {
+      const aged = x.age == null ? '—' : (x.age >= 30 ? `${x.age}d ⚠` : `${x.age}d`);
+      ctx.out.line(`  ${String(i + 1).padStart(2)}. ${(x.name || '?').slice(0, 24).padEnd(24)} ${money(x.due, x.cur).padStart(11)}  ${String(x.status).padEnd(14)} aged ${aged}`);
+      ctx.out.line(`      invoice ${x.num} · id ${x.id}`);
+    });
+    if (data.outstanding > TOP) ctx.out.line(`  … +${data.outstanding - TOP} more`);
+    ctx.out.line('  ' + '─'.repeat(72));
+    ctx.out.line('  → I can (re)send or void ONE at a time on your say-so (L2). I NEVER charge/collect — that stays you.\n');
+  });
+  return 0;
+}

package/commands/reconcile.mjs

@@ -0,0 +1,205 @@
+// commands/reconcile.mjs — Collected by source + status breakdown + flags.
+// Trust-fix #1: LOC from ctx.cfg.loc.
+// Trust-fix #2: transactions + subscriptions paginate to completion.
+// Trust-fix #3: collected-by-source per currency (never cross-sums).
+// READ-ONLY. NEVER charges, refunds, or collects.
+import { paginate } from '../lib/paginate.mjs';
+
+export const meta = {
+  name: 'reconcile',
+  summary: 'Money reconciliation — collected by source, flags, recurring',
+  flags: [
+    { name: '--days', type: 'int', default: 30, desc: 'window in days' },
+    { name: '--top', type: 'int', default: 20, desc: 'max source rows' },
+  ],
+  readOnly: true,
+};
+
+const SYM = { PHP: '₱', USD: '$', EUR: '€', GBP: '£' };
+const m = (n, c = 'PHP') => !Number.isFinite(Number(n)) ? '—' : (SYM[c] || c + ' ') + Number(n || 0).toLocaleString('en-PH', { maximumFractionDigits: 0 });
+const SUCCESS = new Set(['succeeded', 'success', 'paid', 'completed', 'captured']);
+const srcOf = (t) =>
+  (t.paymentProviderType || t.providerType || t.source || t.chargeSnapshot?.provider || t.entitySourceType || 'unknown').toString();
+
+export async function collect(args, ctx) {
+  const DAYS = args.days ?? 30;
+  const LOC = ctx.cfg.loc;
+  const NOW = ctx.now;
+  const START = NOW - DAYS * 24 * 60 * 60 * 1000;
+  // Mirror snapshot's inWindow normalization: numeric seconds (< 1e12) → ms.
+  // GHL currently returns ISO strings, but numeric-epoch fields are defensively handled.
+  const inWin = (v) => {
+    const t = typeof v === 'number' ? (v < 1e12 ? v * 1000 : v) : (Date.parse(v) || 0);
+    return t >= START && t <= NOW;
+  };
+
+  // transactions paginated to completion (trust-fix #2)
+  const txns = [];
+  let txnErr = null;
+  for await (const t of paginate({
+    fetchPage: async (offset = 0) => {
+      const r = await ctx.http.get('/payments/transactions', {
+        query: { altId: LOC, altType: 'location', limit: 100, offset },
+      });
+      if (!r.ok) return { _err: r.code, data: [] };
+      return r.j;
+    },
+    getItems: (resp) => {
+      if (resp._err) { txnErr = resp._err; return []; }
+      return resp.data || resp.transactions || [];
+    },
+    nextCursor: (resp, items, offset = 0) => {
+      if (resp._err || items.length < 100) return null;
+      return offset + 100;
+    },
+    maxPages: 500,
+    startCursor: 0,
+  })) {
+    txns.push(t);
+  }
+
+  if (txnErr && txns.length === 0) {
+    ctx.out.warn(`can't see transactions → HTTP ${txnErr}`, { degraded: true });
+    return {
+      location: LOC, days: DAYS, scanned: 0, inWindow: 0, collected: 0, currency: 'PHP',
+      bySource: {}, byStatus: {}, flags: { refunds: 0, failed: 0, orphans: 0 }, subscriptions: null,
+    };
+  }
+
+  const win = txns.filter(t => inWin(t.createdAt || t.created_at || t.dateAdded));
+
+  // per-source, per-currency (trust-fix #3 — real implementation)
+  const byStatus = {};
+  // byCur: { PHP: { bySource: { stripe: {c,v} }, total: n }, USD: { ... } }
+  const byCur = {};
+  const refunds = [], failed = [], orphans = [];
+
+  for (const t of win) {
+    const st = (t.status || t.paymentStatus || '').toLowerCase();
+    byStatus[st] = (byStatus[st] || 0) + 1;
+    const amt = Number(t.amount) || 0;
+    const cur = (t.currency || 'PHP').toUpperCase();
+    if (SUCCESS.has(st)) {
+      const s = srcOf(t);
+      byCur[cur] ??= { bySource: {}, total: 0 };
+      byCur[cur].bySource[s] ??= { c: 0, v: 0 };
+      byCur[cur].bySource[s].c++;
+      byCur[cur].bySource[s].v += amt;
+      byCur[cur].total += amt;
+      if (!(t.entityId || t.invoiceId || t.entitySourceType)) orphans.push(t);
+    } else if (/refund/.test(st)) {
+      refunds.push(t);
+    } else if (/fail|declin|error/.test(st)) {
+      failed.push(t);
+    }
+  }
+
+  // flatten for output — single currency → backward-compat flat shape; multi → byCurrency map
+  const currencies = Object.keys(byCur);
+  const isSingle = currencies.length <= 1;
+  const currency = isSingle ? (currencies[0] || 'PHP') : (currencies[0] || 'PHP');
+  const collected = isSingle ? (byCur[currency]?.total ?? 0) : null;
+  const byCurrency = isSingle ? null : Object.fromEntries(currencies.map(c => [c, byCur[c].total]));
+  // bySource: when single currency keep flat {src:{c,v}} for backward compat; multi-currency not surfaced at top level
+  const bySource = isSingle ? (byCur[currency]?.bySource ?? {}) : Object.fromEntries(
+    currencies.flatMap(c => Object.entries(byCur[c].bySource).map(([s, v]) => [`${s}(${c})`, v]))
+  );
+
+  // subscriptions paginated to completion (trust-fix #2)
+  let subs = null;
+  const subItems = [];
+  let subErr = null;
+  for await (const s of paginate({
+    fetchPage: async (offset = 0) => {
+      const r = await ctx.http.get('/payments/subscriptions', {
+        query: { altId: LOC, altType: 'location', limit: 100, offset },
+      });
+      if (!r.ok) return { _err: r.code, data: [] };
+      return r.j;
+    },
+    getItems: (resp) => {
+      if (resp._err) { subErr = resp._err; return []; }
+      return resp.data || resp.subscriptions || [];
+    },
+    nextCursor: (resp, items, offset = 0) => {
+      if (resp._err || items.length < 100) return null;
+      return offset + 100;
+    },
+    maxPages: 100,
+    startCursor: 0,
+  })) {
+    subItems.push(s);
+  }
+
+  if (!subErr) {
+    const active = subItems.filter(s => /active|trialing/i.test(s.status || ''));
+    // MRR per-currency — same treatment as transactions (never cross-sum currencies)
+    const mrrByCur = {};
+    for (const x of active) {
+      const cur = (x.currency || 'PHP').toUpperCase();
+      mrrByCur[cur] = (mrrByCur[cur] || 0) + (Number(x.amount) || 0);
+    }
+    const mrrCurrencies = Object.keys(mrrByCur);
+    const isSingleMrr = mrrCurrencies.length <= 1;
+    subs = {
+      active: active.length,
+      total: subItems.length,
+      // single-currency: flat mrr for backward compat; multi-currency: mrrByCurrency map
+      ...(isSingleMrr
+        ? { mrr: mrrByCur[mrrCurrencies[0]] ?? 0 }
+        : { mrrByCurrency: mrrByCur }),
+    };
+  }
+
+  return {
+    location: LOC,
+    days: DAYS,
+    scanned: txns.length,
+    inWindow: win.length,
+    // single-currency: flat `collected` + `currency`; multi-currency: `byCurrency` map (no cross-sum)
+    ...(isSingle
+      ? { collected, currency }
+      : { byCurrency }),
+    bySource,
+    byStatus,
+    flags: { refunds: refunds.length, failed: failed.length, orphans: orphans.length },
+    subscriptions: subs,
+  };
+}
+
+export async function run(args, ctx) {
+  const data = await collect(args, ctx);
+  ctx.out.data(data);
+
+  const isMulti = !!data.byCurrency;
+  const collectedLine = isMulti
+    ? Object.entries(data.byCurrency).map(([c, v]) => m(v, c)).join(' + ')
+    : m(data.collected, data.currency);
+  const cur = data.currency || 'PHP';
+
+  ctx.out.card(() => {
+    ctx.out.line(`\n  RECONCILE — ${collectedLine} collected · last ${data.days}d · ${data.inWindow} txn in window · loc ${data.location}`);
+    ctx.out.line('  ' + '─'.repeat(64));
+    ctx.out.line('  BY SOURCE (succeeded)');
+    const srcs = Object.entries(data.bySource).sort((a, b) => b[1].v - a[1].v);
+    if (!srcs.length) ctx.out.line('    (none)');
+    else for (const [s, v] of srcs) ctx.out.line(`    ${s.slice(0, 24).padEnd(24)} ${String(v.c).padStart(3)} txn  ${m(v.v, isMulti ? (s.match(/\((\w+)\)$/)?.[1] || cur) : cur).padStart(12)}`);
+    ctx.out.line('\n  BY STATUS');
+    for (const [s, c] of Object.entries(data.byStatus).sort((a, b) => b[1] - a[1]))
+      ctx.out.line(`    ${s.slice(0, 24).padEnd(24)} ${String(c).padStart(3)}`);
+    ctx.out.line('\n  FLAGS');
+    ctx.out.line(`    refunds ${data.flags.refunds}  ·  failed ${data.flags.failed}  ·  orphan (no invoice/order) ${data.flags.orphans}`);
+    if (data.subscriptions) {
+      const sub = data.subscriptions;
+      const mrrLine = sub.mrrByCurrency
+        ? Object.entries(sub.mrrByCurrency).map(([c, v]) => m(v, c)).join(' + ')
+        : m(sub.mrr, cur);
+      ctx.out.line(`\n  RECURRING  ${sub.active} active / ${sub.total} subs  ·  ${mrrLine} per cycle`);
+    } else {
+      ctx.out.line("\n  RECURRING  can't see (payments/subscriptions scope absent or none)");
+    }
+    ctx.out.line('  ' + '─'.repeat(64));
+    ctx.out.line('  Read-only. I reconcile + flag — I never charge, refund, or collect. That stays you.\n');
+  });
+  return 0;
+}

package/commands/segment.mjs

@@ -0,0 +1,133 @@
+// commands/segment.mjs — Multi-criteria contact segment finder.
+// Trust-fix #1: LOC from ctx.cfg.loc.
+// Trust-fix #2: contacts paginate to completion.
+// READ-ONLY. Never writes a tag, never messages.
+import { paginate } from '../lib/paginate.mjs';
+
+export const meta = {
+  name: 'segment',
+  summary: 'Find contacts by criteria — tag, phone, age, etc.',
+  flags: [
+    { name: '--tag', type: 'str', desc: 'must have this tag' },
+    { name: '--without-tag', type: 'str', desc: 'must NOT have this tag' },
+    { name: '--no-tags', type: 'bool', desc: 'contacts with zero tags' },
+    { name: '--created-days', type: 'int', desc: 'created within N days' },
+    { name: '--has-phone', type: 'bool', desc: 'must have phone' },
+    { name: '--no-phone', type: 'bool', desc: 'must NOT have phone' },
+    { name: '--top', type: 'int', default: 20, desc: 'max rows to show in sample' },
+  ],
+  readOnly: true,
+};
+
+export async function collect(args, ctx) {
+  const TAG = args.tag?.toLowerCase() ?? null;
+  const WITHOUT = args['without-tag']?.toLowerCase() ?? null;
+  const NO_TAGS = !!args['no-tags'];
+  const CREATED_DAYS = args['created-days'] ?? null;
+  const HAS_PHONE = !!args['has-phone'];
+  const NO_PHONE = !!args['no-phone'];
+  const TOP = args.top ?? 20;
+  const LOC = ctx.cfg.loc;
+  const NOW = ctx.now;
+  const START = CREATED_DAYS ? NOW - Number(CREATED_DAYS) * 86400000 : null;
+
+  const crit = [
+    TAG && `tag=${TAG}`,
+    WITHOUT && `without=${WITHOUT}`,
+    NO_TAGS && 'no-tags',
+    CREATED_DAYS && `created≤${CREATED_DAYS}d`,
+    HAS_PHONE && 'has-phone',
+    NO_PHONE && 'no-phone',
+  ].filter(Boolean);
+
+  if (!crit.length) {
+    ctx.out.warn('No criteria given. Use e.g. --created-days 30 --no-tags', { degraded: false });
+    return null; // signal usage error
+  }
+
+  function matches(c) {
+    const tags = (c.tags || []).map(t => String(t).toLowerCase());
+    if (TAG && !tags.includes(TAG)) return false;
+    if (WITHOUT && tags.includes(WITHOUT)) return false;
+    if (NO_TAGS && tags.length > 0) return false;
+    if (START) { const t = Date.parse(c.dateAdded || c.createdAt) || 0; if (t < START) return false; }
+    if (HAS_PHONE && !c.phone) return false;
+    if (NO_PHONE && c.phone) return false;
+    return true;
+  }
+
+  let scanned = 0;
+  const hits = [];
+  let firstErr = null;
+
+  for await (const c of paginate({
+    fetchPage: async (cursor) => {
+      const q = { locationId: LOC, limit: 100 };
+      if (cursor) { q.startAfter = cursor.startAfter; q.startAfterId = cursor.startAfterId; }
+      const r = await ctx.http.get('/contacts/', { query: q });
+      if (!r.ok) return { _err: r.code, contacts: [] };
+      return r.j;
+    },
+    getItems: (resp) => {
+      if (resp._err) { firstErr = resp._err; return []; }
+      return resp.contacts || resp.data || [];
+    },
+    nextCursor: (resp, items) => {
+      if (resp._err || items.length < 100) return null;
+      const last = items[items.length - 1];
+      return {
+        startAfter: last.dateAdded ? Date.parse(last.dateAdded) : undefined,
+        startAfterId: last.id,
+      };
+    },
+    maxPages: 200,
+  })) {
+    scanned++;
+    if (matches(c)) hits.push(c);
+  }
+
+  if (firstErr && scanned === 0) {
+    ctx.out.warn(`can't see contacts → HTTP ${firstErr}`, { degraded: true });
+    return { location: LOC, criteria: crit, scanned: 0, matched: 0, contactIds: [], sample: [] };
+  }
+
+  return {
+    location: LOC,
+    criteria: crit,
+    scanned,
+    matched: hits.length,
+    contactIds: hits.map(c => c.id),
+    sample: hits.slice(0, TOP).map(c => ({
+      name: c.contactName || ((c.firstName || '') + ' ' + (c.lastName || '')).trim() || c.email,
+      email: c.email,
+      phone: c.phone || null,
+      tags: c.tags || [],
+      id: c.id,
+    })),
+  };
+}
+
+export async function run(args, ctx) {
+  const data = await collect(args, ctx);
+  if (data === null) return 2; // usage error — no criteria
+
+  ctx.out.data(data);
+  const TOP = args.top ?? 20;
+
+  ctx.out.card(() => {
+    ctx.out.line(`\n  SEGMENT — ${data.matched} contact(s) match [${data.criteria.join(' AND ')}]  ·  ${data.scanned} scanned  ·  loc ${data.location}`);
+    ctx.out.line('  ' + '─'.repeat(70));
+    if (!data.sample.length) {
+      ctx.out.line('  No matches.\n');
+      return;
+    }
+    data.sample.forEach((c, i) => {
+      const name = (c.name || '(no name)').slice(0, 26);
+      ctx.out.line(`  ${String(i + 1).padStart(3)}. ${name.padEnd(26)} ${(c.email || '—').slice(0, 28).padEnd(28)} [${(c.tags || []).join(', ').slice(0, 20)}]`);
+    });
+    if (data.matched > TOP) ctx.out.line(`  … +${data.matched - TOP} more (--top to show, --json for all IDs)`);
+    ctx.out.line('  ' + '─'.repeat(70));
+    ctx.out.line(`  → hand to ghl-contacts: bulk-tag these ${data.matched} (L2 — I echo the count + tag, you confirm, then apply). NEVER auto-tagged here.\n`);
+  });
+  return 0;
+}