scripter-x 1.0.2 → 1.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scripter-x",
-  "version": "1.0.2",
+  "version": "1.0.7",
   "description": "ScripterX — local Flipkart session extractor (runs on your residential IP, syncs to marthunt)",
   "type": "module",
   "bin": {

package/src/api.js

@@ -76,11 +76,13 @@ export class ApiClient {
   async deleteCampaign(cid) { return this._req('DELETE', `/scriptx/campaigns/${cid}`); }
 
   // ── server-side creds ──
-  async saveCreds(provider, { email, password, apiKey } = {}) {
+  async saveCreds(provider, { email, password, apiKey, masterNumber, masterPassword } = {}) {
     const body = { provider };
     if (email != null) body.email = email;
     if (password != null) body.password = password;
     if (apiKey != null) body.api_key = apiKey;
+    if (masterNumber != null) body.master_number = masterNumber;
+    if (masterPassword != null) body.master_password = masterPassword;
     return this._req('POST', '/scriptx/otpcart-creds', { body });
   }
   async testCreds(provider) { return this._req('POST', '/scriptx/otpcart-creds/test', { body: { provider } }); }

package/src/commands.js

@@ -6,6 +6,11 @@ import { ApiClient, AuthError } from './api.js';
 import { saveSessions } from './util.js';
 import * as tp from './providers/tempotp.js';
 import * as oc from './providers/otpcart.js';
+import * as kuku from './providers/kuku.js';
+import * as zepto from './providers/zepto.js';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
 import { Worker } from './worker.js';
 import { RunController } from './controller.js';
 import { STATUS } from './theme.js';
@@ -38,6 +43,39 @@ function maskSecret(s) {
   return s.slice(0, 4) + '…' + s.slice(-4);
 }
 
+// Resolve the kuku premium-MASTER creds for email-linking (use-saved / add-new, like the
+// providers). Validates by logging in + checking premium. Saves locally AND to the server.
+// Returns { number, password, masterSession } — masterSession is the logged-in premium master.
+async function resolveKukuMaster(io, api) {
+  const cfg = config.load();
+  let number = cfg.kuku_master_number, password = cfg.kuku_master_password;
+  if (number && password) {
+    const choice = await io.select(`saved kuku master: ${maskSecret(number)}`, [
+      { label: 'use saved', value: 'use', description: maskSecret(number) },
+      { label: 'add new', value: 'new', description: 'enter a different premium master' }]);
+    if ((choice.value || choice) === 'new') { number = null; password = null; }
+  }
+  let fresh = false;
+  if (!number || !password) {
+    number = (await io.ask('kuku premium master account id')).trim();
+    password = (await io.ask('kuku master password', { mask: true })).trim();
+    fresh = true;
+  }
+  // validate: login + must be premium (else newaddr.com won't work)
+  let masterSession;
+  try { masterSession = await kuku.loginAccount(number, password); }
+  catch (e) { throw new Error(`kuku master login failed: ${e.message}`); }
+  if (!(await kuku.isPremium(masterSession))) {
+    throw new Error('kuku master account is NOT premium — needed for newaddr.com emails');
+  }
+  io.print('  ✓ kuku premium master verified');
+  if (fresh && await io.confirm('save these master creds (locally + your account)?', true)) {
+    config.setMany({ kuku_master_number: number, kuku_master_password: password });
+    try { await api.saveCreds('kuku', { masterNumber: number, masterPassword: password }); } catch { /* server save best-effort */ }
+  }
+  return { number, password, masterSession };
+}
+
 // ── provider setup (shared by run) ──
 async function buildProvider(io, name) {
   const cfg = config.load();
@@ -85,23 +123,46 @@ async function buildProvider(io, name) {
 
 export async function run(io, api, args = {}) {
   api = api || await getApi(io);
+
+  // MODE: extract JSON only, or also link a newaddr.com email to each account.
+  const mode = args.mode || (await io.select('what do you want?', [
+    { label: 'JSON only', value: 'json', description: 'extract the session JSON' },
+    { label: 'JSON + email link', value: 'json_email', description: 'also attach a newaddr.com email (premium kuku)' }])).value;
+  const emailMode = mode === 'json_email';
+
   const pSel = args.provider || (await io.select('provider', [
     { label: 'otpcart', value: 'otpcart', description: 'email/password · WebSocket OTP' },
     { label: 'tempotp', value: 'tempotp', description: 'API key · HTTP poll' }])).value;
   const provider = await buildProvider(io, pSel);
+
+  // In email mode: resolve the premium master + create ONE premium kuku account for the
+  // whole campaign (all emails come from it — no re-creating premium per email).
+  let kukuAccount = null;
+  if (emailMode) {
+    const { masterSession } = await resolveKukuMaster(io, api);
+    io.print('  ◉ preparing a premium kuku account for this campaign…');
+    const acc = await kuku.createAccount();
+    const linkedHash = await kuku.linkPremium(masterSession, acc.accountId, acc.password);
+    kuku.applyLinkedHash(acc, linkedHash);
+    if (!(await kuku.isPremium(acc))) throw new Error('could not premium-link the kuku account');
+    kukuAccount = acc;
+    io.print('  ✓ premium kuku account ready (newaddr.com emails enabled)');
+  }
+
   const count = args.count || Number(await io.ask('how many JSONs?', { dflt: '5' }));
   const concurrency = args.concurrency || Number(await io.ask('concurrency (keep low — one IP)', { dflt: String(config.get('default_concurrency', 2)) }));
   const checkMinutes = args.checkMinutes != null ? args.checkMinutes : await io.confirm('check Minutes (₹100 coupon)?', false);
   const name = args.name || `ScripterX-${Math.floor(Date.now() / 1000)}`;
 
-  if (!(await io.confirm(`start ${count} extraction(s) at concurrency ${concurrency}?`, true))) return;
+  if (!(await io.confirm(`start ${count} extraction(s) at concurrency ${concurrency}${emailMode ? ' + email link' : ''}?`, true))) return;
 
   const cid = await api.createCampaign({ name, provider: pSel, count, concurrency, checkMinutes,
     tempotpServiceId: provider.serviceId || '940', deepCheck: provider.deepCheck || false });
   io.print('  ✓ campaign created · syncing to your dashboard');
 
   const controller = new RunController({ name, provider: pSel, requested: count });
-  const worker = new Worker(api, provider, { campaignId: cid, requested: count, concurrency, checkMinutes,
+  const worker = new Worker(api, provider, { campaignId: cid, requested: count, concurrency, checkMinutes, name,
+    emailMode, kukuAccount,
     onEvent: controller.handleEvent,
     // on a failed/rejected OTP: pause, show the real reason, ask continue-or-stop
     onFailure: async ({ mobile, reason }) => {
@@ -109,11 +170,25 @@ export async function run(io, api, args = {}) {
       return io.confirm('OTP failed. Buy a new number and keep going?', true);
     } });
 
-  if (io.startRun) io.startRun(controller);          // mount the live view (interactive)
-  const onSigint = () => worker.stop();
-  process.on('SIGINT', onSigint);
+  controller.stop = () => worker.stop(); // let the App's double-Ctrl+C stop this run
+  const interactive = !!io.startRun;
+  if (interactive) io.startRun(controller); // mount the live view; App owns Ctrl+C
+  // One-shot mode (no App): double-Ctrl+C to exit — first press stops the campaign + warns,
+  // second within 2s exits. Interactive mode handles this at the App level.
+  let onSigint = null;
+  if (!interactive) {
+    let lastSig = 0;
+    onSigint = () => {
+      const now = Date.now();
+      if (now - lastSig < 2000) { worker.stop(); process.exit(0); }
+      lastSig = now;
+      worker.stop();
+      io.print('  ⚠ stopping campaign — press Ctrl+C again to exit');
+    };
+    process.on('SIGINT', onSigint);
+  }
   const stats = await worker.run();
-  process.off('SIGINT', onSigint);
+  if (onSigint) process.off('SIGINT', onSigint);
   if (io.endRun) io.endRun();
 
   io.print(`  ✓ done — ${stats.succeeded} succeeded · ${stats.failed} failed · ${stats.cancelled} cancelled · ₹${stats.charges} spent`);
@@ -126,6 +201,47 @@ export async function run(io, api, args = {}) {
     if (saved) { io.print(`  ✓ saved ${saved.count} session(s) to:`); io.print(`     ${saved.path}`, 'accent'); }
     else io.print(`  ! couldn't auto-save${lastErr ? ` (${lastErr.message})` : ''} — run \`export ${name}\` to retry`);
   } else io.print('  ◉ no sessions extracted — nothing to save.');
+  if (worker.logPath) io.print(`  ◉ log saved to: ${worker.logPath}`);
+}
+
+// ── zepto: local OTP login → extract session to {phone}-{timestamp}.json ──
+// Dead-simple, no backend: enter a number → we SMS an OTP locally → enter the
+// code → we verify and write the session JSON. Runs entirely on your IP.
+export async function zeptoCmd(io, _api, args = {}) {
+  const number = (args.number || await io.ask('zepto phone number')).replace(/\D/g, '').slice(-10);
+  if (number.length !== 10) throw new Error('enter a 10-digit number');
+
+  const session = zepto.newSession(number);
+  io.print(`  ◉ sending OTP to ${number} …`);
+  const s = await zepto.sendOtp(session);
+  if (!s.ok) throw new Error(`could not send OTP: ${s.msg || s.status}`);
+  io.print('  ✓ OTP sent');
+
+  const otp = (args.otp || await io.ask('enter the OTP')).trim();
+  const v = await zepto.verifyOtp(session, otp);
+  if (!v.ok) throw new Error(`OTP verify failed: ${v.error || v.status}`);
+  io.print(`  ✓ logged in${v.user?.fullName ? ` as ${v.user.fullName}` : ''}`);
+
+  // Build the ZAUTH1 envelope — the format the ZeptoAuthManager tool imports.
+  const envelope = zepto.encodeEnvelope(zepto.toSessionKeys(session), args.cert);
+
+  // {phone}-{timestamp}.txt  in the chosen dir (default ~/Downloads/scripterx/zepto)
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const fname = `${number}-${stamp}.txt`;
+  let dest;
+  if (args.out) {
+    const expanded = args.out.startsWith('~') ? join(homedir(), args.out.slice(1)) : args.out;
+    dest = /\.(txt|json)$/i.test(expanded) ? expanded : join(expanded, fname);
+  } else {
+    const downloads = join(homedir(), 'Downloads');
+    dest = join(existsSync(downloads) ? downloads : homedir(), 'scripterx', 'zepto', fname);
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, envelope + '\n');
+  io.print('  ✓ envelope saved to:');
+  io.print(`     ${dest}`, 'accent');
+  io.print('  ◉ paste into ZeptoAuthManager → Import:');
+  io.print(`     ${envelope}`, 'accent');
 }
 
 export async function campaigns(io, api) {
@@ -183,11 +299,18 @@ export async function creds(io, api, args = {}) {
     { label: 'test', value: 'test', description: 'verify creds' }])).value;
   if (action === 'show') {
     const r = await api.creds();
-    for (const p of ['otpcart', 'tempotp']) io.print(`  ◉ ${p}: ${r[p]?.has_creds ? '✓ saved' : '— not set'}`);
+    for (const p of ['otpcart', 'tempotp', 'kuku']) io.print(`  ◉ ${p}: ${r[p]?.has_creds ? '✓ saved' : '— not set'}`);
   } else if (action === 'save') {
-    const provider = (await io.select('provider', [{ label: 'otpcart', value: 'otpcart' }, { label: 'tempotp', value: 'tempotp' }])).value;
-    if (provider === 'tempotp') await api.saveCreds('tempotp', { apiKey: await io.ask('TempOTP API key') });
-    else await api.saveCreds('otpcart', { email: await io.ask('OTPCart email'), password: await io.ask('OTPCart password', { mask: true }) });
+    const provider = (await io.select('provider', [
+      { label: 'otpcart', value: 'otpcart' }, { label: 'tempotp', value: 'tempotp' },
+      { label: 'kuku', value: 'kuku', description: 'premium master (email linking)' }])).value;
+    if (provider === 'tempotp') await api.saveCreds('tempotp', { apiKey: (await io.ask('TempOTP API key')).trim() });
+    else if (provider === 'kuku') {
+      const number = (await io.ask('kuku premium master account id')).trim();
+      const password = (await io.ask('kuku master password', { mask: true })).trim();
+      config.setMany({ kuku_master_number: number, kuku_master_password: password });
+      await api.saveCreds('kuku', { masterNumber: number, masterPassword: password });
+    } else await api.saveCreds('otpcart', { email: (await io.ask('OTPCart email')).trim(), password: (await io.ask('OTPCart password', { mask: true })).trim() });
     io.print(`  ✓ ${provider} credentials saved.`);
   } else {
     const provider = (await io.select('provider', [{ label: 'otpcart', value: 'otpcart' }, { label: 'tempotp', value: 'tempotp' }])).value;
@@ -237,7 +360,7 @@ export async function configCmd(io, _api, args = {}) {
 }
 
 export function help(io) {
-  io.print('  commands: run · campaigns · export · balance · creds · stop · delete · whoami · config · update · logout · exit');
+  io.print('  commands: run · zepto · campaigns · export · balance · creds · stop · delete · whoami · config · update · logout · exit');
 }
 
 export async function update(io) {
@@ -250,6 +373,6 @@ export async function update(io) {
 
 // dispatch table used by the interactive shell
 export const REGISTRY = {
-  run, campaigns, export: exportCmd, balance, creds, stop, delete: del,
+  run, zepto: zeptoCmd, campaigns, export: exportCmd, balance, creds, stop, delete: del,
   whoami, login, logout, config: configCmd, update, help,
 };

package/src/config.js

@@ -15,6 +15,8 @@ const DEFAULTS = {
   tempotp_api_key: null,
   otpcart_email: null,
   otpcart_password: null,
+  kuku_master_number: null,   // kuku.lu premium master account id (for email linking)
+  kuku_master_password: null,
   default_concurrency: 2,
 };
 

package/src/flipkart.js

@@ -9,6 +9,7 @@ const FKUA = 'Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit
   '(KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1 FKUA/msite/0.0.3/msite/Mobile channelType/brw';
 const WEB_HOST = 'https://1.rome.api.flipkart.com';
 const NATIVE_HOST = 'https://2.rome.api.flipkart.net';
+const EMAIL_HOST = 'https://2.rome.api.flipkart.com'; // FK-5/6/7 email-attach host (.com)
 
 export class BlockedError extends Error {}
 export class WrongOTP extends Error {}          // genuinely wrong/expired OTP code
@@ -71,11 +72,16 @@ export class FlipkartLogin {
           'x-request-metaInfo': '{"actionType":"LOGIN_IDENTITY_VERIFY","pageUri":"questContext"}',
         },
       });
-    } catch (e) { throw new BlockedError(`send failed: ${e.message}`); }
+    } catch (e) { throw new TransientError(`send network error: ${e.message}`); }
+    // 529/5xx = Flipkart overloaded / blocking this IP — retryable.
+    if (res.status === 429 || res.status === 529 || res.status >= 500) {
+      throw new TransientError(`Flipkart busy on send (HTTP ${res.status})`);
+    }
     parseCookies(res, this.jar);
     const data = await res.json().catch(() => ({}));
     const rid = data?.RESPONSE?.actionResponseContext?.requestId;
-    if (!rid) throw new BlockedError('blocked while sending OTP (no requestId)');
+    // no requestId on a 200 = soft anti-bot throttle — also retryable (often clears on retry).
+    if (!rid) throw new TransientError('blocked while sending OTP (no requestId — throttled)');
     this.reqId = rid;
     this.sn = this.jar.SN || '';
     this.vid = this.sn ? this.sn.split('.')[0] : '';
@@ -126,6 +132,7 @@ export class FlipkartLogin {
     return {
       accountId: env.accountId || '', at: env.at || '', rt: env.rt || '', sn: env.sn || '',
       secureToken, secureCookie: this.jar.S || '', ud, vd,
+      cookie_T: fresh.T || this.jar.T || '', // T cookie — needed for the email-attach calls
       visitId: (env.sn || '').split('.')[0], nsid: env.nsid || '',
       mobileNo: mobile.slice(-10), isLoggedIn: true, rt_expires_at: rtExpiry(env.rt || ''),
     };
@@ -155,6 +162,76 @@ export class FlipkartLogin {
     const count = (text.match(/"orderId"\s*:\s*"(OD\w+)"/g) || []).length;
     return count === 0; // no orders ⇒ coupon available
   }
+
+  // ─── Email attach (FK-5/6/7) — on the EMAIL host (2.rome.api.flipkart.com) ──────
+  // Shared headers for the email-attach calls (uses the logged-in session's tokens).
+  _emailHeaders(session) {
+    return {
+      'User-Agent': 'okhttp/4.9.2',
+      'X-User-Agent': nativeUa(session.visitId || this.vid),
+      'Content-Type': 'application/json',
+      at: session.at || '', sn: session.sn || '',
+      sc: session.secureCookie || '', securecookie: session.secureCookie || '',
+      flipkart_secure: 'true',
+      Origin: 'https://www.flipkart.com', Referer: 'https://www.flipkart.com/',
+      'X-Requested-With': 'com.flipkart.android',
+      Cookie: `T=${session.cookie_T || ''}; vd=${session.vd || ''}; ud=${session.ud || ''}`,
+    };
+  }
+
+  // FK-5: is an email already attached? Returns { emailAlready, email }.
+  async profileInfo(session) {
+    await throttle.wait();
+    const res = await fetch(`${EMAIL_HOST}/1/user/profile/info?v=${Date.now()}`, { headers: this._emailHeaders(session) });
+    if (res.status === 429 || res.status === 529 || res.status >= 500) throw new TransientError(`profile-info busy (HTTP ${res.status})`);
+    const data = await res.json().catch(() => ({}));
+    const r = data.RESPONSE || {};
+    // emailVerificationFlow:false = no email yet. If an email exists it shows in RESPONSE.
+    const existing = r.email || r.emailId || null;
+    return { emailAlready: r.emailVerificationFlow === true || !!existing, email: existing };
+  }
+
+  // FK-6: send OTP to BOTH the new email AND the registered phone. Returns the two requestIds.
+  async sendEmailOtp(session, email) {
+    await throttle.wait();
+    const res = await fetch(`${EMAIL_HOST}/8/user/otp/generate`, {
+      method: 'POST', headers: this._emailHeaders(session),
+      body: JSON.stringify({ flowType: 'ADD_UPDATE_IDENTIFIER', newLoginId: email }),
+    });
+    if (res.status === 429 || res.status === 529 || res.status >= 500) throw new TransientError(`email-otp-gen busy (HTTP ${res.status})`);
+    const data = await res.json().catch(() => ({}));
+    const info = data?.RESPONSE?.otpIdentifierInfo || [];
+    let emailReqId = null, phoneReqId = null, phoneUserId = null;
+    for (const it of info) {
+      if (String(it.userId || '').includes('@')) emailReqId = it.requestId;
+      else { phoneReqId = it.requestId; phoneUserId = it.userId; } // "91-<10digit>"
+    }
+    if (!emailReqId || !phoneReqId) {
+      const msg = flipkartErrorMessage(data, JSON.stringify(data));
+      throw new TransientError(msg || 'email-otp-gen: missing requestIds');
+    }
+    return { emailReqId, phoneReqId, phoneUserId };
+  }
+
+  // FK-7: submit BOTH OTPs (email + phone) to link the email. Returns { ok, message }.
+  async verifyEmailOtp(session, { email, emailOtp, emailReqId, phoneUserId, phoneOtp, phoneReqId }) {
+    await throttle.wait();
+    const res = await fetch(`${EMAIL_HOST}/6/user/identity`, {
+      method: 'POST', headers: this._emailHeaders(session),
+      body: JSON.stringify({ otpInfo: [
+        { otp: emailOtp, userId: email, requestId: emailReqId },
+        { otp: phoneOtp, userId: phoneUserId, requestId: phoneReqId },
+      ] }),
+    });
+    if (res.status === 429 || res.status === 529 || res.status >= 500) throw new TransientError(`identity-verify busy (HTTP ${res.status})`);
+    const text = await res.text();
+    let data; try { data = JSON.parse(text); } catch { throw new TransientError('identity-verify: non-JSON'); }
+    const msg = data?.RESPONSE?.message || '';
+    if (/successfully linked|linked to account/i.test(msg)) return { ok: true, message: msg };
+    // wrong/expired OTP or other failure → surface the real reason (not retryable as transient)
+    const err = flipkartErrorMessage(data, text) || msg || `link failed (HTTP ${res.status})`;
+    throw new WrongOTP(err);
+  }
 }
 
 function rtExpiry(rt) {

package/src/index.js

@@ -43,6 +43,9 @@ const HELP = `${paint.bold('scripterx')} — local Flipkart session extractor
   scripterx                 interactive shell (recommended)
   scripterx run [flags]     run an extraction directly
        --provider otpcart|tempotp  --count N  --concurrency N  --name <n>  --check-minutes
+  scripterx zepto [flags]   local Zepto OTP login → {phone}-{timestamp}.txt (ZAUTH1 envelope)
+       --number <10-digit>  --otp <code>  --out <file|dir>  --cert <64hex>
+       (envelope keyed to ZeptoAuthManager cert; override with --cert or $ZAUTH_CERT_SHA)
   scripterx campaigns | export [name] | balance | creds | stop | delete | whoami | config
   scripterx --version`;
 
@@ -93,7 +96,7 @@ async function main() {
   }
 
   // ── one-shot mode ──
-  const map = { run: 'run', campaigns: 'campaigns', export: 'export', balance: 'balance',
+  const map = { run: 'run', zepto: 'zepto', campaigns: 'campaigns', export: 'export', balance: 'balance',
     creds: 'creds', stop: 'stop', delete: 'delete', whoami: 'whoami', login: 'login',
     logout: 'logout', config: 'config', update: 'update', help: 'help' };
   const fnName = map[cmd];
@@ -102,6 +105,8 @@ async function main() {
     provider: flags.provider, count: flags.count ? +flags.count : null,
     concurrency: flags.concurrency ? +flags.concurrency : null, name: flags.name,
     checkMinutes: flags['check-minutes'] === true ? true : (flags['check-minutes'] === false ? false : null),
+    mode: flags.email ? 'json_email' : flags.mode, // --email or --mode json_email
+    number: flags.number, otp: flags.otp, cert: flags.cert, // zepto: local OTP login → ZAUTH1 envelope
     campaign: flags._[0], out: flags.out, action: flags._[0], value: flags._[1],
   };
   try { await REGISTRY[fnName](cliIo, null, args); }

package/src/logger.js

@@ -0,0 +1,52 @@
+// Per-campaign logging → ~/Downloads/scripterx/temp/logs/<campaign>-<id>.log
+// Keeps a clean, timestamped, append-only log of everything that happened in a run, so
+// failures/charges can be audited after the fact. Flushed to disk at campaign end.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, appendFileSync, existsSync } from 'node:fs';
+
+function logDir() {
+  const dir = join(homedir(), 'Downloads', 'scripterx', 'temp', 'logs');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function stamp() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, '0');
+  return `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+
+export class CampaignLogger {
+  constructor({ campaignId, name, provider }) {
+    const safe = (name || campaignId).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || campaignId.slice(0, 8);
+    this.path = join(logDir(), `${safe}-${campaignId.slice(0, 8)}.log`);
+    this.buffer = [];
+    this.header(name, provider, campaignId);
+  }
+
+  header(name, provider, cid) {
+    const d = new Date();
+    this.write(`──────────────────────────────────────────────`);
+    this.write(`ScripterX campaign log`);
+    this.write(`  name:     ${name}`);
+    this.write(`  provider: ${provider}`);
+    this.write(`  id:       ${cid}`);
+    this.write(`  started:  ${d.toISOString()}`);
+    this.write(`──────────────────────────────────────────────`);
+  }
+
+  // append one clean, timestamped line (buffered; written immediately too for crash safety)
+  write(line) {
+    const entry = `[${stamp()}] ${line}\n`;
+    this.buffer.push(entry);
+    try { appendFileSync(this.path, entry); } catch { /* logging must never crash the run */ }
+  }
+
+  summary(stats) {
+    this.write(`──────────────────────────────────────────────`);
+    this.write(`SUMMARY  ✓ ${stats.succeeded}  ✗ ${stats.failed}  ⊘ ${stats.cancelled}  ·  ${stats.generated} numbers  ·  ₹${stats.charges} spent`);
+    this.write(`finished: ${new Date().toISOString()}`);
+    this.write(`──────────────────────────────────────────────`);
+  }
+}