@badgie/crm-cli 0.5.0 → 0.7.0

package/dist/commands/top-clients.js

@@ -1,32 +1,293 @@
 import { getAuthedClient } from '../core/supabase.js';
 import { commonListOptions, output, parseColumns, parseLimit } from '../core/format.js';
-import { maybeResolve } from '../core/resolve.js';
+import { maybeResolve, resolveRef } from '../core/resolve.js';
 import { bulkOptions, collectIds, runBulk } from '../core/bulk.js';
 import { swapIfLegacyOrder } from '../core/compat.js';
-async function listTopClients(_a, opts) {
-    const { client } = await getAuthedClient();
+const ACTIVE_CLIENT_STATUSES = ['active', 'active free trial'];
+const REVIEW_SELECT = `
+  *,
+  reviewed_by_member:team_members!client_monthly_reviews_reviewed_by_fkey(id, full_name, email, avatar_url),
+  client:clients(
+    id, name, email, sport, city, status, assigned_to,
+    plan_type, plan_student_tier, plan_student_count, plan_payment_frequency, plan_payment_amount,
+    assigned:team_members!clients_assigned_to_fkey(id, full_name, email, avatar_url)
+  )
+`;
+const CLIENT_CONFIG_SELECT = `
+  id, name, email, sport, city, status, assigned_to,
+  plan_type, plan_student_tier, plan_student_count, plan_payment_frequency, plan_payment_amount,
+  assigned:team_members!clients_assigned_to_fkey(id, full_name, email, avatar_url)
+`;
+const TOP_CLIENT_QUESTIONS = [
+    {
+        id: 'notes',
+        key: 'notes',
+        label: 'Notas generales',
+        storage: { table: 'client_monthly_reviews', column: 'notes', type: 'text' },
+        answerCommand: 'badgie-crm top-clients notes set --review-id <id> --notes "..."',
+    },
+    {
+        id: 'needs',
+        key: 'needs',
+        label: 'Necesidades identificadas',
+        storage: { table: 'client_monthly_reviews', column: 'needs', type: 'text[]' },
+        answerCommand: 'badgie-crm top-clients answer set --review-id <id> --question needs --value \'["..."]\'',
+    },
+    {
+        id: 'testimonials',
+        key: 'testimonials',
+        label: 'Testimonios',
+        storage: { table: 'client_monthly_reviews', column: 'testimonials', type: 'text[]' },
+        answerCommand: 'badgie-crm top-clients answer set --review-id <id> --question testimonials --value \'["..."]\'',
+    },
+    {
+        id: 'risk_level',
+        key: 'risk_level',
+        label: 'Riesgo',
+        allowedValues: ['low', 'medium', 'high'],
+        storage: { table: 'client_monthly_reviews', column: 'risk_level', type: 'text' },
+        answerCommand: 'badgie-crm top-clients answer set --review-id <id> --question risk_level --value high',
+    },
+    {
+        id: 'next_actions',
+        key: 'next_actions',
+        label: 'Proximas acciones',
+        storage: { table: 'client_monthly_reviews', column: 'next_actions', type: 'text[]' },
+        answerCommand: 'badgie-crm top-clients answer set --review-id <id> --question next_actions --value \'["..."]\'',
+    },
+    {
+        id: 'status',
+        key: 'status',
+        label: 'Estado',
+        allowedValues: ['pending', 'in_progress', 'completed'],
+        storage: { table: 'client_monthly_reviews', column: 'status', type: 'text' },
+        answerCommand: 'badgie-crm top-clients set-status completed <id>',
+    },
+    {
+        id: 'reviewed_at',
+        key: 'reviewed_at',
+        label: 'Fecha de revision',
+        storage: { table: 'client_monthly_reviews', column: 'reviewed_at', type: 'timestamp' },
+        answerCommand: 'badgie-crm top-clients answer set --review-id <id> --question reviewed_at --value 2026-04-26',
+    },
+    {
+        id: 'satisfaction_score',
+        key: 'satisfaction_score',
+        label: 'Satisfaccion',
+        allowedValues: [1, 2, 3, 4, 5],
+        storage: { table: 'client_monthly_reviews', column: 'satisfaction_score', type: 'integer' },
+        answerCommand: 'badgie-crm top-clients answer set --review-id <id> --question satisfaction_score --value 5',
+    },
+    {
+        id: 'contacted',
+        key: 'contacted',
+        label: 'Contactado esta semana',
+        allowedValues: [true, false],
+        storage: { table: 'client_monthly_reviews', column: 'metadata.contacted/contact_log', type: 'jsonb' },
+        answerCommand: 'badgie-crm top-clients answer set --review-id <id> --question contacted --value true',
+    },
+];
+const QUESTION_ALIASES = Object.fromEntries(TOP_CLIENT_QUESTIONS.flatMap((q) => [
+    [q.id, q.key],
+    [q.key, q.key],
+]));
+function currentMonthYear(opts) {
     const now = new Date();
     const month = typeof opts.month === 'string' ? Number(opts.month) : now.getMonth() + 1;
     const year = typeof opts.year === 'string' ? Number(opts.year) : now.getFullYear();
-    // Reviews for selected month/year
+    assertMonthYear(month, year);
+    return { month, year };
+}
+function assertMonthYear(month, year) {
+    if (!Number.isInteger(month) || month < 1 || month > 12) {
+        throw new Error('--month must be an integer between 1 and 12');
+    }
+    if (!Number.isInteger(year) || year < 2000 || year > 2100) {
+        throw new Error('--year must be a YYYY integer');
+    }
+}
+function boolFromUnknown(value, label) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value !== 'string')
+        throw new Error(`${label} must be true|false`);
+    const v = value.trim().toLowerCase();
+    if (v === 'true' || v === '1' || v === 'yes')
+        return true;
+    if (v === 'false' || v === '0' || v === 'no')
+        return false;
+    throw new Error(`${label} must be true|false (got "${value}")`);
+}
+function nullableString(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        return undefined;
+    const v = value.trim();
+    if (v === '' || v.toLowerCase() === 'null' || v.toLowerCase() === 'none')
+        return null;
+    return v;
+}
+function numberOrNull(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '' || value.trim().toLowerCase() === 'null') {
+        return null;
+    }
+    const n = Number(value);
+    if (!Number.isFinite(n))
+        throw new Error(`${label} must be a number`);
+    return n;
+}
+function parseJsonish(value) {
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '';
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return value;
+    }
+}
+function parseStringArray(value, label) {
+    const parsed = parseJsonish(value);
+    if (parsed === null)
+        return null;
+    if (Array.isArray(parsed)) {
+        return parsed.map((v) => String(v).trim()).filter(Boolean);
+    }
+    return value
+        .split(/\n|,/)
+        .map((v) => v.trim())
+        .filter(Boolean);
+}
+function normalizeStatus(status) {
+    if (status === 'pending' || status === 'in_progress' || status === 'completed')
+        return status;
+    throw new Error('status must be pending|in_progress|completed');
+}
+function normalizeRisk(risk) {
+    if (risk === 'low' || risk === 'medium' || risk === 'high')
+        return risk;
+    throw new Error('risk_level must be low|medium|high');
+}
+function safeMetadata(metadata) {
+    if (metadata && typeof metadata === 'object' && !Array.isArray(metadata)) {
+        return { ...metadata };
+    }
+    return {};
+}
+function isValidContactLogEntry(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const o = x;
+    return typeof o.at === 'string' && (o.type === 'marked' || o.type === 'unmarked');
+}
+function mergeContactedMetadata(existing, contacted, reviewStatus) {
+    const base = safeMetadata(existing);
+    const prevLog = Array.isArray(base.contact_log)
+        ? base.contact_log.filter(isValidContactLogEntry)
+        : [];
+    return {
+        ...base,
+        contacted,
+        contact_log: [
+            ...prevLog,
+            {
+                at: new Date().toISOString(),
+                type: contacted ? 'marked' : 'unmarked',
+                review_status: reviewStatus || 'pending',
+            },
+        ],
+    };
+}
+function isContactedThisWeek(review) {
+    const now = new Date();
+    const dow = now.getDay();
+    const offsetToMonday = dow === 0 ? -6 : 1 - dow;
+    const monday = new Date(now.getFullYear(), now.getMonth(), now.getDate() + offsetToMonday);
+    monday.setHours(0, 0, 0, 0);
+    const sunday = new Date(monday);
+    sunday.setDate(monday.getDate() + 6);
+    sunday.setHours(23, 59, 59, 999);
+    const metadata = safeMetadata(review.metadata);
+    const log = Array.isArray(metadata.contact_log)
+        ? metadata.contact_log.filter(isValidContactLogEntry)
+        : metadata.contacted === true && (review.updated_at || review.created_at)
+            ? [{ at: review.updated_at || review.created_at || '', type: 'marked' }]
+            : [];
+    const inWeek = log.filter((e) => {
+        const t = new Date(e.at).getTime();
+        return t >= monday.getTime() && t <= sunday.getTime();
+    });
+    inWeek.sort((a, b) => new Date(b.at).getTime() - new Date(a.at).getTime());
+    return inWeek[0]?.type === 'marked';
+}
+function answered(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    return true;
+}
+function outputOptions(opts) {
+    return { pretty: !!opts.pretty, columns: parseColumns(opts) };
+}
+async function getCurrentTeamMemberId(client) {
+    const { data } = await client.auth.getUser();
+    const email = data.user?.email;
+    if (!email)
+        return null;
+    const { data: member, error } = await client
+        .from('team_members')
+        .select('id')
+        .eq('email', email)
+        .maybeSingle();
+    if (error)
+        throw error;
+    return member?.id ?? null;
+}
+async function fetchReview(client, id) {
+    const { data, error } = await client
+        .from('client_monthly_reviews')
+        .select(REVIEW_SELECT)
+        .eq('id', id)
+        .single();
+    if (error)
+        throw error;
+    return data;
+}
+async function listTopClients(_a, opts) {
+    const { client } = await getAuthedClient();
+    const { month, year } = currentMonthYear(opts);
+    const kam = await maybeResolve(client, 'team_member', opts.kam);
+    const reviewer = await maybeResolve(client, 'team_member', opts.reviewer);
+    const limit = parseLimit(opts);
+    const hasClientSideFilters = !!kam || typeof opts.search === 'string';
     let reviewsQ = client
         .from('client_monthly_reviews')
-        .select(`id, client_id, month, year, status, reviewed_by,
-       reviewed_by_member:team_members!client_monthly_reviews_reviewed_by_fkey(id, full_name, email),
-       client:clients(id, name, sport, city, assigned_to, assigned:team_members!clients_assigned_to_fkey(full_name, email))`)
+        .select(REVIEW_SELECT)
         .eq('month', month)
         .eq('year', year)
         .order('created_at', { ascending: false })
-        .limit(parseLimit(opts));
-    const kam = await maybeResolve(client, 'team_member', opts.kam);
-    if (kam)
-        reviewsQ = reviewsQ.eq('reviewed_by', kam);
+        .limit(hasClientSideFilters ? Math.max(1000, limit) : limit);
+    if (reviewer)
+        reviewsQ = reviewsQ.eq('reviewed_by', reviewer);
     if (typeof opts.status === 'string')
         reviewsQ = reviewsQ.eq('status', opts.status);
     const { data, error } = await reviewsQ;
     if (error)
         throw error;
-    let rows = data ?? [];
+    let rows = (data ?? []);
+    if (kam) {
+        rows = rows.filter((r) => {
+            const c = r.client ?? null;
+            return c?.assigned_to === kam || r.reviewed_by === kam;
+        });
+    }
     if (typeof opts.search === 'string') {
         const needle = opts.search.toLowerCase();
         rows = rows.filter((r) => {
@@ -34,13 +295,168 @@ async function listTopClients(_a, opts) {
             return c?.name?.toLowerCase().includes(needle) ?? false;
         });
     }
-    output(rows, { pretty: !!opts.pretty, columns: parseColumns(opts) });
+    if (hasClientSideFilters)
+        rows = rows.slice(0, limit);
+    output(rows, outputOptions(opts));
+}
+async function getTopClient(args, opts) {
+    const id = args.id;
+    if (!id)
+        throw new Error('review id is required');
+    const { client } = await getAuthedClient();
+    output(await fetchReview(client, id), { pretty: !!opts.pretty });
+}
+async function listQuestions(_a, opts) {
+    output({
+        source: 'client_monthly_reviews columns used by the current Top Clients UI',
+        questions: TOP_CLIENT_QUESTIONS,
+    }, { pretty: !!opts.pretty });
+}
+async function listAnswers(_a, opts) {
+    const reviewId = typeof opts.reviewId === 'string' ? opts.reviewId : null;
+    if (!reviewId)
+        throw new Error('--review-id is required');
+    const { client } = await getAuthedClient();
+    const review = await fetchReview(client, reviewId);
+    const rows = TOP_CLIENT_QUESTIONS.map((q) => {
+        let value = review[q.key];
+        if (q.key === 'contacted')
+            value = isContactedThisWeek(review);
+        return {
+            id: q.id,
+            key: q.key,
+            label: q.label,
+            value,
+            answered: answered(value),
+            storage: q.storage,
+        };
+    });
+    output(rows, outputOptions(opts));
+}
+async function summary(_a, opts) {
+    const { client } = await getAuthedClient();
+    const { month, year } = currentMonthYear(opts);
+    const [reviewsRes, clientsRes] = await Promise.all([
+        client
+            .from('client_monthly_reviews')
+            .select('id, client_id, status, risk_level, reviewed_by, reviewed_at, metadata, created_at, updated_at')
+            .eq('month', month)
+            .eq('year', year),
+        client
+            .from('clients')
+            .select('id, name, status, assigned_to')
+            .in('status', ACTIVE_CLIENT_STATUSES),
+    ]);
+    if (reviewsRes.error)
+        throw reviewsRes.error;
+    if (clientsRes.error)
+        throw clientsRes.error;
+    const reviews = reviewsRes.data ?? [];
+    const activeClients = clientsRes.data ?? [];
+    const totalClientIds = new Set();
+    activeClients.forEach((c) => totalClientIds.add(c.id));
+    reviews.forEach((r) => {
+        if (r.client_id)
+            totalClientIds.add(r.client_id);
+    });
+    const completed = reviews.filter((r) => r.status === 'completed').length;
+    const inProgress = reviews.filter((r) => r.status === 'in_progress').length;
+    const pending = [...totalClientIds].filter((clientId) => {
+        const r = reviews.find((x) => x.client_id === clientId);
+        return !r || (r.status !== 'completed' && r.status !== 'in_progress');
+    }).length;
+    const contacted = reviews.filter(isContactedThisWeek).length;
+    const total = totalClientIds.size;
+    const completionRate = total > 0 ? Math.round((completed / total) * 100) : 0;
+    const byRisk = {
+        low: reviews.filter((r) => r.risk_level === 'low').length,
+        medium: reviews.filter((r) => r.risk_level === 'medium').length,
+        high: reviews.filter((r) => r.risk_level === 'high').length,
+        unset: reviews.filter((r) => !r.risk_level).length,
+    };
+    output({
+        month,
+        year,
+        total_clients_in_scope: total,
+        active_clients: activeClients.length,
+        reviews_created: reviews.length,
+        completed,
+        in_progress: inProgress,
+        pending,
+        contacted_this_week: contacted,
+        completion_rate: completionRate,
+        by_risk: byRisk,
+    }, { pretty: !!opts.pretty });
+}
+async function generate(_a, opts) {
+    const { client } = await getAuthedClient();
+    const { month, year } = currentMonthYear(opts);
+    const dryRun = !!opts.dryRun;
+    const { data: clients, error: clientsError } = await client
+        .from('clients')
+        .select('id, name, status, assigned_to')
+        .in('status', ACTIVE_CLIENT_STATUSES)
+        .order('name');
+    if (clientsError)
+        throw clientsError;
+    const clientIds = (clients ?? []).map((c) => c.id);
+    let existing = [];
+    if (clientIds.length > 0) {
+        const { data, error } = await client
+            .from('client_monthly_reviews')
+            .select('id, client_id')
+            .eq('month', month)
+            .eq('year', year)
+            .in('client_id', clientIds);
+        if (error)
+            throw error;
+        existing = data ?? [];
+    }
+    const existingByClient = new Map(existing.map((r) => [r.client_id, r.id]));
+    const toCreate = (clients ?? []).filter((c) => !existingByClient.has(c.id));
+    const rows = toCreate.map((c) => ({
+        client_id: c.id,
+        month,
+        year,
+        status: 'pending',
+        reviewed_by: c.assigned_to ?? null,
+    }));
+    if (dryRun || rows.length === 0) {
+        output({
+            dry_run: dryRun,
+            month,
+            year,
+            active_clients: clients?.length ?? 0,
+            existing_reviews: existing.length,
+            would_create: rows.length,
+            create_preview: toCreate.slice(0, parseLimit(opts, 20)).map((c) => ({
+                client_id: c.id,
+                name: c.name,
+                reviewed_by: c.assigned_to,
+            })),
+        }, { pretty: !!opts.pretty });
+        return;
+    }
+    const { data, error } = await client
+        .from('client_monthly_reviews')
+        .insert(rows)
+        .select(REVIEW_SELECT);
+    if (error)
+        throw error;
+    output({
+        month,
+        year,
+        created: data?.length ?? 0,
+        existing_reviews: existing.length,
+        reviews: data ?? [],
+    }, { pretty: !!opts.pretty });
 }
 async function setReviewStatus(args, opts) {
     swapIfLegacyOrder(args, 'status', 'id', 'top-clients set-status');
     const { client } = await getAuthedClient();
     if (!args.status)
         throw new Error('status argument is required');
+    const status = normalizeStatus(args.status);
     const ids = await collectIds({
         positional: args.id,
         ids: opts.ids,
@@ -49,12 +465,15 @@ async function setReviewStatus(args, opts) {
     });
     if (ids.length === 0)
         throw new Error('No IDs provided. Pass <id>, --ids, --ids-file, or --stdin.');
+    const patch = { status };
+    if (status === 'completed')
+        patch.reviewed_at = new Date().toISOString();
     if (ids.length === 1 && !opts.dryRun) {
         const { data, error } = await client
             .from('client_monthly_reviews')
-            .update({ status: args.status })
+            .update(patch)
             .eq('id', ids[0])
-            .select('id, status')
+            .select(REVIEW_SELECT)
             .single();
         if (error)
             throw error;
@@ -64,9 +483,9 @@ async function setReviewStatus(args, opts) {
     const result = await runBulk(ids, async (id) => {
         const { data, error } = await client
             .from('client_monthly_reviews')
-            .update({ status: args.status })
+            .update(patch)
             .eq('id', id)
-            .select('id, status')
+            .select('id, status, reviewed_at')
             .single();
         if (error)
             throw error;
@@ -74,6 +493,230 @@ async function setReviewStatus(args, opts) {
     }, { dryRun: !!opts.dryRun, concurrency: Number(opts.concurrency ?? 5), label: 'set-status' });
     output({ updated: result.ok.length, failed: result.failed.length, errors: result.failed.slice(0, 10) }, { pretty: !!opts.pretty });
 }
+async function setAnswer(_a, opts) {
+    const reviewId = typeof opts.reviewId === 'string' ? opts.reviewId : null;
+    const questionInput = typeof opts.question === 'string' ? opts.question : null;
+    const rawValue = typeof opts.value === 'string' ? opts.value : null;
+    if (!reviewId)
+        throw new Error('--review-id is required');
+    if (!questionInput)
+        throw new Error('--question is required');
+    if (rawValue === null)
+        throw new Error('--value is required');
+    const question = QUESTION_ALIASES[questionInput] ?? questionInput;
+    const { client } = await getAuthedClient();
+    const before = await fetchReview(client, reviewId);
+    let patch = {};
+    switch (question) {
+        case 'notes':
+            patch = { notes: rawValue || null };
+            break;
+        case 'needs':
+        case 'testimonials':
+        case 'next_actions':
+            patch = { [question]: parseStringArray(rawValue, question) };
+            break;
+        case 'risk_level':
+            patch = { risk_level: rawValue.trim().toLowerCase() === 'null' ? null : normalizeRisk(rawValue) };
+            break;
+        case 'status': {
+            const status = normalizeStatus(rawValue);
+            patch = { status };
+            if (status === 'completed')
+                patch.reviewed_at = new Date().toISOString();
+            break;
+        }
+        case 'reviewed_at': {
+            if (rawValue.trim().toLowerCase() === 'null') {
+                patch = { reviewed_at: null };
+            }
+            else {
+                const d = new Date(rawValue);
+                if (Number.isNaN(d.getTime())) {
+                    throw new Error(`reviewed_at must be a valid date (got "${rawValue}"). Use ISO 8601, e.g. 2026-04-26 or 2026-04-26T10:00:00Z.`);
+                }
+                patch = { reviewed_at: d.toISOString() };
+            }
+            break;
+        }
+        case 'satisfaction_score': {
+            const n = Number(rawValue);
+            if (!Number.isInteger(n) || n < 1 || n > 5)
+                throw new Error('satisfaction_score must be an integer 1..5');
+            patch = { satisfaction_score: n };
+            break;
+        }
+        case 'metadata':
+            patch = { metadata: parseJsonish(rawValue) };
+            break;
+        case 'contacted': {
+            const contacted = boolFromUnknown(rawValue, '--value');
+            patch = { metadata: mergeContactedMetadata(before.metadata, contacted, before.status) };
+            break;
+        }
+        default:
+            throw new Error(`Unknown question "${questionInput}". Run \`badgie-crm top-clients questions list\`.`);
+    }
+    if (opts.dryRun) {
+        output({ dry_run: true, review_id: reviewId, question, patch, before }, { pretty: !!opts.pretty });
+        return;
+    }
+    const { data, error } = await client
+        .from('client_monthly_reviews')
+        .update(patch)
+        .eq('id', reviewId)
+        .select(REVIEW_SELECT)
+        .single();
+    if (error)
+        throw error;
+    output(data, { pretty: !!opts.pretty });
+}
+async function setNotes(_a, opts) {
+    const reviewId = typeof opts.reviewId === 'string' ? opts.reviewId : null;
+    if (!reviewId)
+        throw new Error('--review-id is required');
+    if (typeof opts.notes !== 'string')
+        throw new Error('--notes is required');
+    const { client } = await getAuthedClient();
+    const patch = { notes: opts.notes.trim() === '' ? null : opts.notes };
+    if (opts.dryRun) {
+        output({ dry_run: true, review_id: reviewId, patch }, { pretty: !!opts.pretty });
+        return;
+    }
+    const { data, error } = await client
+        .from('client_monthly_reviews')
+        .update(patch)
+        .eq('id', reviewId)
+        .select(REVIEW_SELECT)
+        .single();
+    if (error)
+        throw error;
+    output(data, { pretty: !!opts.pretty });
+}
+async function setOwner(_a, opts) {
+    const reviewId = typeof opts.reviewId === 'string' ? opts.reviewId : null;
+    if (!reviewId)
+        throw new Error('--review-id is required');
+    const { client } = await getAuthedClient();
+    const kam = opts.clearKam || opts.clearOwner
+        ? null
+        : await maybeResolve(client, 'team_member', opts.kam);
+    if (!opts.clearKam && !opts.clearOwner && !kam)
+        throw new Error('--kam is required (or pass --clear-kam)');
+    const patch = { reviewed_by: kam };
+    if (opts.dryRun) {
+        output({ dry_run: true, review_id: reviewId, patch }, { pretty: !!opts.pretty });
+        return;
+    }
+    const { data, error } = await client
+        .from('client_monthly_reviews')
+        .update(patch)
+        .eq('id', reviewId)
+        .select(REVIEW_SELECT)
+        .single();
+    if (error)
+        throw error;
+    output(data, { pretty: !!opts.pretty });
+}
+async function getConfig(_a, opts) {
+    const clientRef = typeof opts.clientId === 'string' ? opts.clientId : null;
+    if (!clientRef)
+        throw new Error('--client-id is required');
+    const { client } = await getAuthedClient();
+    const clientId = await resolveRef(client, 'client', clientRef);
+    const { data, error } = await client
+        .from('clients')
+        .select(CLIENT_CONFIG_SELECT)
+        .eq('id', clientId)
+        .single();
+    if (error)
+        throw error;
+    output({
+        client: data,
+        top_clients_scope: {
+            included_when_status_in: ACTIVE_CLIENT_STATUSES,
+            currently_included: ACTIVE_CLIENT_STATUSES.includes(data.status),
+        },
+        supported_config_fields: [
+            'clients.status',
+            'clients.assigned_to',
+            'clients.plan_type',
+            'clients.plan_student_tier',
+            'clients.plan_student_count',
+            'clients.plan_payment_frequency',
+            'clients.plan_payment_amount',
+        ],
+        no_dedicated_schema_fields: [
+            'review periodicity',
+            'active questions per client',
+            'top-client priority',
+        ],
+        note: 'The current UI derives Top Clients from active clients and stores monthly answers in client_monthly_reviews.',
+    }, { pretty: !!opts.pretty });
+}
+async function setConfig(_a, opts) {
+    const clientRef = typeof opts.clientId === 'string' ? opts.clientId : null;
+    if (!clientRef)
+        throw new Error('--client-id is required');
+    const { client } = await getAuthedClient();
+    const clientId = await resolveRef(client, 'client', clientRef);
+    const patch = {};
+    if (typeof opts.status === 'string')
+        patch.status = opts.status;
+    if (opts.topClient !== undefined && patch.status === undefined) {
+        patch.status = boolFromUnknown(opts.topClient, '--top-client') ? 'active' : 'inactive';
+    }
+    if (opts.clearKam) {
+        patch.assigned_to = null;
+    }
+    else if (typeof opts.kam === 'string') {
+        patch.assigned_to = await resolveRef(client, 'team_member', opts.kam);
+    }
+    const planType = nullableString(opts.planType);
+    if (planType !== undefined)
+        patch.plan_type = planType;
+    const planStudentTier = nullableString(opts.planStudentTier);
+    if (planStudentTier !== undefined)
+        patch.plan_student_tier = planStudentTier;
+    const planPaymentFrequency = nullableString(opts.planPaymentFrequency);
+    if (planPaymentFrequency !== undefined)
+        patch.plan_payment_frequency = planPaymentFrequency;
+    const planStudentCount = numberOrNull(opts.planStudentCount, '--plan-student-count');
+    if (planStudentCount !== undefined)
+        patch.plan_student_count = planStudentCount;
+    const planPaymentAmount = numberOrNull(opts.planPaymentAmount, '--plan-payment-amount');
+    if (planPaymentAmount !== undefined)
+        patch.plan_payment_amount = planPaymentAmount;
+    if (Object.keys(patch).length === 0) {
+        throw new Error('Pass at least one config field to update. Run `badgie-crm top-clients config get --client-id <client>`.');
+    }
+    if (opts.dryRun) {
+        output({ dry_run: true, client_id: clientId, patch }, { pretty: !!opts.pretty });
+        return;
+    }
+    const { data, error } = await client
+        .from('clients')
+        .update({ ...patch, updated_at: new Date().toISOString() })
+        .eq('id', clientId)
+        .select(CLIENT_CONFIG_SELECT)
+        .single();
+    if (error)
+        throw error;
+    if ('assigned_to' in patch) {
+        const actorId = await getCurrentTeamMemberId(client).catch(() => null);
+        await client.from('activities').insert({
+            client_id: clientId,
+            type: 'note',
+            title: 'Cambio de KAM',
+            description: `KAM actualizado desde badgie-crm CLI`,
+            created_by: actorId,
+        });
+    }
+    output(data, { pretty: !!opts.pretty });
+}
+const prettyOption = { flag: '--pretty', description: 'human output' };
+const jsonOption = { flag: '--json', description: 'force JSON output (default)' };
+const dryRunOption = { flag: '--dry-run', description: 'show what would happen without writing' };
 export const topClientsModule = {
     name: 'top-clients',
     summary: 'Monthly top-client reviews (KAM follow-up tracker)',
@@ -85,28 +728,182 @@ export const topClientsModule = {
             options: [
                 { flag: '--month <n>', description: '1-12 (default current month)' },
                 { flag: '--year <n>', description: 'YYYY (default current year)' },
-                { flag: '--kam <uuid|name|email>', description: 'filter by reviewed_by (team member)' },
-                { flag: '--status <s>', description: 'pending|completed|…' },
+                { flag: '--kam <uuid|name|email>', description: 'filter by client KAM (clients.assigned_to) or review owner (reviewed_by)' },
+                { flag: '--reviewer <uuid|name|email>', description: 'filter strictly by reviewed_by (team member)' },
+                { flag: '--status <s>', description: 'pending|in_progress|completed' },
                 { flag: '--search <text>', description: 'filter by client name (client-side)' },
                 ...commonListOptions(),
             ],
             examples: [
-                'badgie-crm top-clients list --month 3 --year 2026 --status pending --pretty',
-                'badgie-crm top-clients list --kam <uuid> --pretty',
+                'badgie-crm top-clients list --month 4 --year 2026 --limit 10',
+                'badgie-crm top-clients list --month 4 --year 2026 --kam Greg --status pending --pretty',
             ],
             handler: listTopClients,
         },
+        {
+            path: ['top-clients', 'get'],
+            summary: 'Show one monthly review with client and reviewer joined',
+            tags: ['read'],
+            args: [{ name: 'id', required: true, description: 'client_monthly_reviews.id' }],
+            options: [prettyOption, jsonOption],
+            examples: ['badgie-crm top-clients get <review-id> --pretty'],
+            handler: getTopClient,
+        },
+        {
+            path: ['top-clients', 'questions', 'list'],
+            summary: 'List review questions/answer fields used by the current UI',
+            tags: ['read'],
+            options: [prettyOption, jsonOption],
+            examples: ['badgie-crm top-clients questions list'],
+            handler: listQuestions,
+        },
+        {
+            path: ['top-clients', 'answers', 'list'],
+            summary: 'List stored answers for one review',
+            tags: ['read'],
+            options: [
+                { flag: '--review-id <id>', description: 'client_monthly_reviews.id (required)' },
+                ...commonListOptions(),
+            ],
+            examples: ['badgie-crm top-clients answers list --review-id <review-id> --pretty'],
+            handler: listAnswers,
+        },
+        {
+            path: ['top-clients', 'summary'],
+            summary: 'Monthly Top Clients summary stats',
+            tags: ['read'],
+            options: [
+                { flag: '--month <n>', description: '1-12 (default current month)' },
+                { flag: '--year <n>', description: 'YYYY (default current year)' },
+                prettyOption,
+                jsonOption,
+            ],
+            examples: ['badgie-crm top-clients summary --month 4 --year 2026'],
+            handler: summary,
+        },
+        {
+            path: ['top-clients', 'generate'],
+            summary: 'Create or preview monthly reviews for active Top Clients',
+            description: 'Top Clients scope matches the UI: clients whose status is active or active free trial. Existing reviews for the same client/month/year are not duplicated.',
+            tags: ['write'],
+            options: [
+                { flag: '--month <n>', description: '1-12 (default current month)' },
+                { flag: '--year <n>', description: 'YYYY (default current year)' },
+                dryRunOption,
+                { flag: '--limit <n>', description: 'max preview rows for --dry-run (default 20)' },
+                prettyOption,
+                jsonOption,
+            ],
+            examples: [
+                'badgie-crm top-clients generate --month 4 --year 2026 --dry-run',
+                'badgie-crm top-clients generate --month 4 --year 2026 --pretty',
+            ],
+            handler: generate,
+        },
         {
             path: ['top-clients', 'set-status'],
             summary: 'Change review status (single or bulk)',
             tags: ['write'],
             args: [
-                { name: 'status', required: true, description: 'new status' },
+                { name: 'status', required: true, description: 'pending|in_progress|completed' },
                 { name: 'id', required: false, description: 'client_monthly_reviews.id (or use --ids / --stdin)' },
             ],
-            options: [...bulkOptions, { flag: '--pretty', description: 'human output' }],
+            options: [...bulkOptions, prettyOption, jsonOption],
+            examples: [
+                'badgie-crm top-clients set-status completed <review-id>',
+                'badgie-crm top-clients set-status in_progress --ids "<id1>,<id2>" --dry-run',
+            ],
             handler: setReviewStatus,
         },
+        {
+            path: ['top-clients', 'answer', 'set'],
+            summary: 'Set one answer field on a review',
+            description: 'Question can be notes, needs, testimonials, risk_level, next_actions, status, reviewed_at, satisfaction_score, metadata, or contacted. Arrays accept JSON arrays or comma/newline-separated text.',
+            tags: ['write'],
+            options: [
+                { flag: '--review-id <id>', description: 'client_monthly_reviews.id (required)' },
+                { flag: '--question <key|id>', description: 'question key from `top-clients questions list` (required)' },
+                { flag: '--value <text|json>', description: 'answer value (required)' },
+                dryRunOption,
+                prettyOption,
+                jsonOption,
+            ],
+            examples: [
+                'badgie-crm top-clients answer set --review-id <id> --question risk_level --value high',
+                'badgie-crm top-clients answer set --review-id <id> --question needs --value \'["Más demos", "Soporte técnico"]\'',
+                'badgie-crm top-clients answer set --review-id <id> --question contacted --value true',
+            ],
+            handler: setAnswer,
+        },
+        {
+            path: ['top-clients', 'notes', 'set'],
+            summary: 'Set review notes',
+            tags: ['write'],
+            options: [
+                { flag: '--review-id <id>', description: 'client_monthly_reviews.id (required)' },
+                { flag: '--notes <text>', description: 'notes text (required, empty string clears)' },
+                dryRunOption,
+                prettyOption,
+                jsonOption,
+            ],
+            examples: ['badgie-crm top-clients notes set --review-id <id> --notes "Cliente estable, revisar renovacion"'],
+            handler: setNotes,
+        },
+        {
+            path: ['top-clients', 'owner', 'set'],
+            summary: 'Set the review owner/reviewer (reviewed_by)',
+            tags: ['write'],
+            options: [
+                { flag: '--review-id <id>', description: 'client_monthly_reviews.id (required)' },
+                { flag: '--kam <uuid|name|email>', description: 'team member assigned as reviewed_by' },
+                { flag: '--clear-kam', description: 'clear reviewed_by' },
+                { flag: '--clear-owner', description: 'alias for --clear-kam' },
+                dryRunOption,
+                prettyOption,
+                jsonOption,
+            ],
+            examples: ['badgie-crm top-clients owner set --review-id <id> --kam Greg --pretty'],
+            handler: setOwner,
+        },
+        {
+            path: ['top-clients', 'config', 'get'],
+            summary: 'Show Top Clients configuration derived from an existing client row',
+            description: 'The current UI has no dedicated top-client config table. Inclusion is derived from clients.status, KAM from clients.assigned_to, and answers from client_monthly_reviews.',
+            tags: ['read'],
+            options: [
+                { flag: '--client-id <uuid|name|email>', description: 'client reference (required)' },
+                prettyOption,
+                jsonOption,
+            ],
+            examples: ['badgie-crm top-clients config get --client-id "Club Example"'],
+            handler: getConfig,
+        },
+        {
+            path: ['top-clients', 'config', 'set'],
+            summary: 'Update Top Clients-related client configuration fields',
+            description: 'Updates only existing client columns used by the UI: status/top-client inclusion, assigned KAM, and plan fields. There are no dedicated DB columns for review periodicity, active questions, or top-client priority.',
+            tags: ['write'],
+            options: [
+                { flag: '--client-id <uuid|name|email>', description: 'client reference (required)' },
+                { flag: '--kam <uuid|name|email>', description: 'set clients.assigned_to' },
+                { flag: '--clear-kam', description: 'clear clients.assigned_to' },
+                { flag: '--status <s>', description: 'set clients.status directly' },
+                { flag: '--top-client <bool>', description: 'true => status active, false => status inactive (ignored if --status is passed)' },
+                { flag: '--plan-type <value>', description: 'set clients.plan_type (empty/null clears)' },
+                { flag: '--plan-student-tier <value>', description: 'set clients.plan_student_tier (empty/null clears)' },
+                { flag: '--plan-student-count <n>', description: 'set clients.plan_student_count (empty/null clears)' },
+                { flag: '--plan-payment-frequency <value>', description: 'set clients.plan_payment_frequency (empty/null clears)' },
+                { flag: '--plan-payment-amount <n>', description: 'set clients.plan_payment_amount (empty/null clears)' },
+                dryRunOption,
+                prettyOption,
+                jsonOption,
+            ],
+            examples: [
+                'badgie-crm top-clients config set --client-id "Club Example" --kam Greg --dry-run',
+                'badgie-crm top-clients config set --client-id <client-id> --top-client true --plan-payment-frequency monthly',
+            ],
+            handler: setConfig,
+        },
     ],
 };
 //# sourceMappingURL=top-clients.js.map