@chainpatrol/cli 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @chainpatrol/cli
 
+## 0.14.0
+
+### Minor Changes
+
+- 339729c: Add an `--include` filter to `chainpatrol metrics organization` (backed
+  by a new optional `include` field on `GET /organization/metrics`) so
+  callers can ask for just the metrics they care about instead of paying
+  for the full ~11-aggregate fan-out.
+
+  `--include` (or `include: [...]` in the JSON body) accepts a comma list
+  of any of: `reports`, `newThreats`, `threatsWatchlisted`,
+  `takedownsFiled`, `takedownsCompleted`, `domainThreats`,
+  `twitterThreats`, `telegramThreats`, `otherThreats`, `blockedByType`,
+  `blockedByDay`. The server runs only those Prisma aggregates;
+  unrequested fields come back as `null`. Omitting `--include` (or
+  passing an empty list) preserves the existing "compute everything"
+  behavior.
+
+  This is the targeted follow-up to the 3-month-default change for the
+  same 503 issue: agents that only need takedown counts can now skip the
+  nine other counts entirely, keeping each call well inside the platform
+  function cap and cheap enough to run repeatedly per org.
+
+  The response schema's metric fields and `blockedByType`/`blockedByDay`
+  arrays are now nullable to express "not included" — TypeScript callers
+  of the CLI's `OrganizationMetricsResult` that previously read
+  `result.metrics.reports` as `number` will need `?? 0` (or to opt in to
+  `--include` and check for `null` explicitly).
+
+## 0.13.0
+
+### Minor Changes
+
+- 7cc2783: Default every `chainpatrol metrics …` subcommand
+  (`summary` / `found` / `breakdown` / `organization`) to a trailing
+  **3-month** window when no `--from`/`--to`/`--this-week` flag is
+  supplied, and echo the resolved range in every output format
+  (human, markdown, csv, json) so consumers can see exactly what
+  window the numbers describe.
+
+  Previously, omitting the date flags sent `undefined` for `startDate`
+  / `endDate`, which caused the metrics handler to fan out ~15 parallel
+  unbounded Prisma aggregates per call. On large orgs that routinely
+  exceeded the platform's 30s function cap and surfaced to agents as
+  flaky `503` responses. The new default keeps the queries bounded
+  and produces a stable, labelled result.
+
+  `--this-week` is now also wired through to `metrics summary`,
+  `metrics breakdown`, and `metrics organization` (it was already
+  supported on `metrics found`).
+
+  JSON output now includes a `range: { startDate, endDate, label }`
+  field on every metrics subcommand. The label is one of
+  `"last 3 months"` (default), `"this week"`, or
+  `"custom range (<startIso> → <endIso>)"`.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/{breakdown-KCTKQNDY.js → breakdown-K5Q6TDKE.js}

@@ -1,31 +1,40 @@
+import {
+  resolveDateRange
+} from "./chunk-S37VFIZY.js";
 import {
   printOutput,
   toCsvRows
 } from "./chunk-VFT3TD3E.js";
 import {
   createApiClient
-} from "./chunk-OSRFCVBT.js";
+} from "./chunk-YZEMTNCX.js";
 import "./chunk-EGWK6SRQ.js";
 import "./chunk-TFCNKBRC.js";
 import "./chunk-U73SABXK.js";
 
 // src/commands/metrics/breakdown.ts
 async function runMetricsBreakdown(options) {
+  const range = resolveDateRange({
+    from: options.from,
+    to: options.to,
+    thisWeek: options.thisWeek
+  });
   const client = options.apiClient ?? createApiClient();
   const result = await client.getMetricsBreakdown({
     slug: options.org,
     by: options.by,
-    startDate: options.from,
-    endDate: options.to,
+    startDate: range.startDate,
+    endDate: range.endDate,
     brandIds: options.brandIds
   });
   const outputFormat = options.outputFormat ?? (options.json ? "json" : "human");
   printOutput({
     outputFormat,
-    json: result,
+    json: { ...result, range },
     markdown: [
-      `# Metrics Breakdown (${options.org})`,
+      `# Metrics Breakdown (${options.org}) \u2014 ${range.label}`,
       "",
+      `- Range: ${range.startDate} \u2192 ${range.endDate}`,
       `- Grouped by: ${result.by}`,
       "",
       ...result.points.map((point) => {
@@ -40,6 +49,9 @@ async function runMetricsBreakdown(options) {
     ].join("\n"),
     csv: toCsvRows(
       result.points.map((point) => ({
+        rangeLabel: range.label,
+        startDate: range.startDate,
+        endDate: range.endDate,
         key: point.key,
         count: point.count,
         date: point.date ?? null,
@@ -50,7 +62,10 @@ async function runMetricsBreakdown(options) {
       }))
     ),
     human: () => {
-      console.log(`Metrics breakdown for ${options.org} by ${result.by}`);
+      console.log(
+        `Metrics breakdown for ${options.org} by ${result.by} \u2014 ${range.label}`
+      );
+      console.log(`Range: ${range.startDate} \u2192 ${range.endDate}`);
       for (const point of result.points) {
         if (result.by === "day") {
           console.log(`${point.date ?? point.key}: ${point.count}`);

package/dist/{check-P5JJJNEX.js → check-NJH7BUIM.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-VFT3TD3E.js";
 import {
   createApiClient
-} from "./chunk-OSRFCVBT.js";
+} from "./chunk-YZEMTNCX.js";
 import "./chunk-EGWK6SRQ.js";
 import "./chunk-TFCNKBRC.js";
 import "./chunk-U73SABXK.js";

package/dist/{chunk-W42ITB5J.js → chunk-6X5BFFXA.js}

@@ -659,20 +659,92 @@ takedowns?", reach for \`orgs list\` \u2014 it's the only command that exposes
 service flags across multiple orgs in one call. Run it in \`--json\` mode
 and summarize patterns by service or by subscription tier.
 
-### \`metrics summary | found | breakdown\` \u2014 Org metrics for spike/drop analysis
+### \`metrics summary | found | breakdown | organization\` \u2014 Org metrics for spike/drop analysis
 
 \`\`\`bash
-chainpatrol --json metrics summary  --org <slug> --this-week
-chainpatrol --json metrics breakdown --org <slug> --by day --this-week
-chainpatrol --json metrics found    --org <slug> --from <YYYY-MM-DD> --to <YYYY-MM-DD>
+chainpatrol --json metrics summary      --org <slug>                                  # defaults to last 3 months
+chainpatrol --json metrics summary      --org <slug> --this-week
+chainpatrol --json metrics breakdown    --org <slug> --by day --this-week
+chainpatrol --json metrics found        --org <slug> --from <YYYY-MM-DD> --to <YYYY-MM-DD>
+chainpatrol --json metrics organization --org <slug>                                  # defaults to last 3 months
 \`\`\`
 
+**Always operate on a bounded window.** When no \`--from\`/\`--to\`/\`--this-week\`
+is passed, every metrics subcommand defaults to the trailing **last 3 months**
+ending now. The default exists because unbounded org-wide aggregates over
+multi-year history routinely time out at the platform layer (Vercel's
+30s function cap), which surfaces to clients as a 503. Stick to the default,
+or pass an explicit narrower window \u2014 don't try to bypass the default by
+guessing wide \`--from\` values.
+
+The resolved range is echoed back in every output format so the user can
+see exactly what they got:
+
+- JSON: \`{ "range": { "startDate": "...", "endDate": "...", "label": "last 3 months" } }\`
+- Markdown / human: the header line includes the label, e.g.
+  \`Organization metrics for acme \u2014 last 3 months\`, followed by
+  \`Range: <startDate> \u2192 <endDate>\`.
+
+When reporting numbers to the user (especially averages and rates),
+**state the window explicitly** \u2014 say "averaged over the last 3 months"
+rather than just quoting a number, since the same prompt phrased
+differently can pick a different window.
+
 \`breakdown\` is the one you usually want for healthchecks: it returns a
 time series (by day or week) of reports, new threats, watchlisted threats,
 and takedowns filed/completed. Compare the latest period against a prior
 window to spot the **spike** or **drop** signals described in the manual
 HealthCheck Guide. \`summary\` returns a single window total; \`found\` is
-oriented around when threats were first discovered.
+oriented around when threats were first discovered; \`organization\` is
+the full customer-facing dashboard slice (reports, new threats,
+watchlisted, takedowns filed/completed, plus per-type and per-day
+breakdowns).
+
+#### \`--include\` \u2014 only compute the metrics you actually need
+
+\`metrics organization\` runs one Prisma aggregate per requested field.
+By default all 11 are computed in parallel. Pass \`--include\` (or
+\`include: [\u2026]\` in the JSON body) with the comma-separated subset you
+care about to skip the rest \u2014 the unrequested fields come back as
+\`null\` instead of a number, and the server never runs those queries:
+
+\`\`\`bash
+# Only takedowns \u2014 one of the cheap shapes
+chainpatrol --json metrics organization --org <slug> \\
+  --include takedownsFiled,takedownsCompleted
+
+# Time series only, no scalar counts
+chainpatrol --json metrics organization --org <slug> --include blockedByDay
+\`\`\`
+
+Allowed values: \`reports\`, \`newThreats\`, \`threatsWatchlisted\`,
+\`takedownsFiled\`, \`takedownsCompleted\`, \`domainThreats\`,
+\`twitterThreats\`, \`telegramThreats\`, \`otherThreats\`,
+\`blockedByType\`, \`blockedByDay\`.
+
+Use this whenever the user's question is specific ("how many takedowns
+did we file last month?"). It is the lowest-effort way to make a
+metrics call cheap enough to run repeatedly. Pair it with an explicit
+date window for the best behavior.
+
+#### "Across all orgs" via an API key \u2014 what's actually possible
+
+A ChainPatrol API key is scoped to a single organization. The
+\`/organization/metrics\` endpoint derives the org from the key, so
+**there is no way to fetch metrics for multiple orgs with one API key**.
+If the user asks for "averages across all orgs":
+
+1. If they're authenticated with a user session, list accessible orgs
+   first (\`chainpatrol --json orgs list\`) and then call
+   \`metrics organization\` once per org **serially** (concurrent
+   fan-out across many orgs is what triggers 503/throttling on the
+   metrics endpoint).
+2. If they're using a single API key, explain that the key only
+   covers one org \u2014 they need either session auth or one key per
+   org, not a loop with the same key.
+3. Whatever window you choose, **make it explicit** in your reply
+   ("last 3 months", "last 7 days", etc) \u2014 never report an average
+   without naming the window it was computed over.
 
 ### \`presets list | run\` \u2014 Packaged workflows for common jobs
 

package/dist/{chunk-DJVB73FL.js → chunk-BIKTBRER.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-VFT3TD3E.js";
 import {
   createApiClient
-} from "./chunk-OSRFCVBT.js";
+} from "./chunk-YZEMTNCX.js";
 import {
   DateTime
 } from "./chunk-TFCNKBRC.js";

package/dist/chunk-S37VFIZY.js

@@ -0,0 +1,66 @@
+import {
+  DateTime
+} from "./chunk-TFCNKBRC.js";
+
+// src/lib/date-range.ts
+var DEFAULT_RANGE_MONTHS = 3;
+var DEFAULT_RANGE_LABEL = `last ${DEFAULT_RANGE_MONTHS} months`;
+function customLabel(start, end) {
+  const startIso = start.toUTC().toISODate();
+  const endIso = end.toUTC().toISODate();
+  return `custom range (${startIso} \u2192 ${endIso})`;
+}
+function resolveDateRange({
+  from,
+  to,
+  thisWeek
+}) {
+  if (from && to) {
+    const start2 = DateTime.fromISO(from).toUTC();
+    const end = DateTime.fromISO(to).toUTC();
+    return {
+      startDate: start2.toISO() ?? from,
+      endDate: end.toISO() ?? to,
+      label: customLabel(start2, end)
+    };
+  }
+  if (from && !to) {
+    const now2 = DateTime.now().toUTC();
+    const start2 = DateTime.fromISO(from).toUTC();
+    return {
+      startDate: start2.toISO() ?? from,
+      endDate: now2.toISO() ?? "",
+      label: customLabel(start2, now2)
+    };
+  }
+  if (!from && to) {
+    const end = DateTime.fromISO(to).toUTC();
+    const start2 = end.minus({ days: 7 });
+    return {
+      startDate: start2.toISO() ?? "",
+      endDate: end.toISO() ?? to,
+      label: customLabel(start2, end)
+    };
+  }
+  if (thisWeek) {
+    const now2 = DateTime.now().toUTC();
+    const start2 = now2.startOf("week");
+    const end = now2.endOf("week");
+    return {
+      startDate: start2.toISO() ?? now2.minus({ days: 7 }).toISO() ?? "",
+      endDate: end.toISO() ?? now2.toISO() ?? "",
+      label: "this week"
+    };
+  }
+  const now = DateTime.now().toUTC();
+  const start = now.minus({ months: DEFAULT_RANGE_MONTHS });
+  return {
+    startDate: start.toISO() ?? "",
+    endDate: now.toISO() ?? "",
+    label: DEFAULT_RANGE_LABEL
+  };
+}
+
+export {
+  resolveDateRange
+};

package/dist/{chunk-OSRFCVBT.js → chunk-YZEMTNCX.js}

@@ -45,6 +45,19 @@ var TAKEDOWN_SORT_KEYS = [
   "assigneeId",
   "brandId"
 ];
+var ORGANIZATION_METRICS_INCLUDE_FIELDS = [
+  "reports",
+  "newThreats",
+  "threatsWatchlisted",
+  "takedownsFiled",
+  "takedownsCompleted",
+  "domainThreats",
+  "twitterThreats",
+  "telegramThreats",
+  "otherThreats",
+  "blockedByType",
+  "blockedByDay"
+];
 var REQUEST_TIMEOUT_MS = 3e4;
 function defaultGetCredential() {
   const envKey = process.env.CHAINPATROL_API_KEY;
@@ -71,7 +84,16 @@ function createApiClient(options) {
     const headers = buildAuthHeaders();
     const search = new URLSearchParams();
     for (const [key, value] of Object.entries(query)) {
-      if (value !== void 0 && value !== "") {
+      if (value === void 0) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          if (item !== void 0 && item !== "") {
+            search.append(key, item);
+          }
+        }
+        continue;
+      }
+      if (value !== "") {
         search.set(key, value);
       }
     }
@@ -258,7 +280,8 @@ function createApiClient(options) {
         organizationSlug: input.organizationSlug,
         brandSlug: input.brandSlug,
         startDate: parseIsoDateString(input.startDate),
-        endDate: parseIsoDateString(input.endDate)
+        endDate: parseIsoDateString(input.endDate),
+        include: input.include
       });
     },
     listHealthchecks() {
@@ -378,5 +401,6 @@ export {
   TAKEDOWN_STATUSES,
   LIVENESS_STATUSES,
   TAKEDOWN_SORT_KEYS,
+  ORGANIZATION_METRICS_INCLUDE_FIELDS,
   createApiClient
 };