@erdoai/cli 0.225.0 → 0.227.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/dist/index.js +283 -8
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -2019,6 +2019,74 @@ var ErdoClient = class {
2019
2019
  listDatasetRevisions(slug) {
2020
2020
  return this.request("GET", `/v1/datasets/${encodeURIComponent(slug)}/revisions`);
2021
2021
  }
2022
+ // --- dataset change history and corrections ---
2023
+ // What each write changed, grouped by the refresh run (or one-off write)
2024
+ // that made it. Passing a run id pages that run's changes instead.
2025
+ listDatasetChanges(slug, opts = {}) {
2026
+ const q = new URLSearchParams();
2027
+ if (opts.since) q.set("since", opts.since);
2028
+ if (opts.until) q.set("until", opts.until);
2029
+ if (opts.cursor) q.set("cursor", opts.cursor);
2030
+ if (opts.limit) q.set("limit", String(opts.limit));
2031
+ const qs = q.toString();
2032
+ return this.request(
2033
+ "GET",
2034
+ `/v1/datasets/${encodeURIComponent(slug)}/changes${qs ? `?${qs}` : ""}`
2035
+ );
2036
+ }
2037
+ listDatasetChangeRunEntries(slug, runID, opts = {}) {
2038
+ const q = new URLSearchParams();
2039
+ if (opts.cursor) q.set("cursor", opts.cursor);
2040
+ if (opts.limit) q.set("limit", String(opts.limit));
2041
+ const qs = q.toString();
2042
+ return this.request(
2043
+ "GET",
2044
+ `/v1/datasets/${encodeURIComponent(slug)}/changes/${encodeURIComponent(runID)}/entries${qs ? `?${qs}` : ""}`
2045
+ );
2046
+ }
2047
+ // Every recorded change to one row, newest first. A composite key's row key
2048
+ // is a JSON array of its values in key order.
2049
+ getDatasetRowHistory(slug, keyColumn, rowKey, opts = {}) {
2050
+ const q = new URLSearchParams({ key_column: keyColumn, row_key: rowKey });
2051
+ if (opts.cursor) q.set("cursor", opts.cursor);
2052
+ if (opts.limit) q.set("limit", String(opts.limit));
2053
+ return this.request("GET", `/v1/datasets/${encodeURIComponent(slug)}/row-history?${q}`);
2054
+ }
2055
+ // The caller's own visits in the Erdo app. Reading them records no visit.
2056
+ getDatasetLastVisit(slug) {
2057
+ return this.request("GET", `/v1/datasets/${encodeURIComponent(slug)}/last-visit`);
2058
+ }
2059
+ listDatasetCorrections(slug) {
2060
+ return this.request(
2061
+ "GET",
2062
+ `/v1/datasets/${encodeURIComponent(slug)}/corrections`
2063
+ );
2064
+ }
2065
+ // A null value blanks the cell. Later refreshes keep the value until it is
2066
+ // handed back.
2067
+ correctDatasetCell(slug, body) {
2068
+ return this.request(
2069
+ "POST",
2070
+ `/v1/datasets/${encodeURIComponent(slug)}/corrections`,
2071
+ body
2072
+ );
2073
+ }
2074
+ handBackDatasetCorrection(slug, correctionID) {
2075
+ return this.request(
2076
+ "POST",
2077
+ `/v1/datasets/${encodeURIComponent(slug)}/corrections/${encodeURIComponent(correctionID)}/hand-back`,
2078
+ {}
2079
+ );
2080
+ }
2081
+ // Puts back the row a 'removed' change recorded and keeps it through later
2082
+ // replaces until it is handed back.
2083
+ restoreDatasetRow(slug, changeID) {
2084
+ return this.request(
2085
+ "POST",
2086
+ `/v1/datasets/${encodeURIComponent(slug)}/restore-row`,
2087
+ { change_id: changeID }
2088
+ );
2089
+ }
2022
2090
  // --- dataset refreshes ---
2023
2091
  // The configuration that keeps one dataset current — the recipe and the
2024
2092
  // triggers that run it. A dataset nothing refreshes answers configured:false
@@ -6870,10 +6938,10 @@ reviewsCmd.command("decide <id>").description(
6870
6938
  );
6871
6939
  var pagesCmd = program.command("pages").description("Create and manage pages/artifacts");
6872
6940
  var criticCmd = program.command("critic").description("Review campaign creative");
6873
- criticCmd.command("review").description("Review an ad or document and print per-lens findings").option("-f, --file <path>", "JSON file containing the full critic review request envelope").option("--text <text>", "Document text to review (use instead of --file)").option("--claims-dataset <slug>", "Claims dataset slug for document reviews").option("--wait", "Poll a running document review's run until it completes").option("--json", "print the complete raw JSON response").action(async (opts) => {
6941
+ criticCmd.command("review").description("Review an ad or document and print per-lens findings").option("-f, --file <path>", "JSON file containing the full critic review request envelope").option("--text <text>", "Document text to review (use instead of --file)").option("--wait", "Poll a running document review's run until it completes").option("--json", "print the complete raw JSON response").action(async (opts) => {
6874
6942
  try {
6875
6943
  if (!opts.file && !opts.text) throw new Error("provide --file or --text");
6876
- const input = opts.text ? { subject_kind: "document", document: { text: opts.text, claims_dataset_slug: opts.claimsDataset } } : JSON.parse(readFileSync5(opts.file, "utf8"));
6944
+ const input = opts.text ? { subject_kind: "document", document: { text: opts.text } } : JSON.parse(readFileSync5(opts.file, "utf8"));
6877
6945
  const result = await new ErdoClient().reviewCritic(input);
6878
6946
  let finalResult = result;
6879
6947
  if (opts.wait && result.status === "running" && result.run_id) {
@@ -6901,15 +6969,12 @@ criticCmd.command("review").description("Review an ad or document and print per-
6901
6969
  for (const lens of finalResult.lenses) {
6902
6970
  console.log(`
6903
6971
  ${lens.lens_slug}: ${lens.summary}`);
6904
- for (const finding of lens.findings) {
6905
- console.log(` [${finding.severity}] ${finding.issue}`);
6972
+ for (const finding of lens.findings ?? []) {
6973
+ console.log(` [${finding.severity}] ${finding.issue}${finding.unsupported ? " (unsupported)" : ""}`);
6906
6974
  console.log(` Evidence: ${finding.evidence}`);
6975
+ if (finding.source_url) console.log(` Source: ${finding.source_url}`);
6907
6976
  console.log(` Suggested rewrite: ${finding.suggested_rewrite}`);
6908
6977
  }
6909
- for (const claim of lens.claims ?? []) {
6910
- console.log(` Claim ${claim.claim_id}: ${claim.verdict} \u2014 ${claim.claim}`);
6911
- if (claim.note) console.log(` Note: ${claim.note}`);
6912
- }
6913
6978
  }
6914
6979
  if (finalResult.usage) console.log(`
6915
6980
  Usage: ${JSON.stringify(finalResult.usage)}`);
@@ -9226,6 +9291,216 @@ Read one with: erdo datasets fetch ${res.dataset_slug} --revision <id> --sql "SE
9226
9291
  fail(e);
9227
9292
  }
9228
9293
  });
9294
+ function changeValue(v) {
9295
+ return v === null ? "(blank)" : v;
9296
+ }
9297
+ function printDatasetChanges(changes) {
9298
+ printAlignedTable(
9299
+ ["change", "kind", "row", "field", "old", "new", "at"],
9300
+ changes.map((c) => [
9301
+ c.id,
9302
+ c.kind,
9303
+ c.row_key,
9304
+ c.field ?? "",
9305
+ // A removed row's old value is the whole row as JSON, kept for restore.
9306
+ c.kind === "added" ? "" : changeValue(c.old_value),
9307
+ c.kind === "removed" || c.kind === "handed_back" ? "" : changeValue(c.new_value),
9308
+ c.created_at
9309
+ ])
9310
+ );
9311
+ }
9312
+ function describeChangeRun(run) {
9313
+ const who = run.actor_type === "refresh" ? `refresh${run.run_id ? ` run ${run.run_id}` : ""}` : run.actor_type;
9314
+ const counts = [
9315
+ `${run.rows_added} added`,
9316
+ `${run.rows_changed} changed`,
9317
+ `${run.rows_removed} removed`,
9318
+ ...run.rows_corrected ? [`${run.rows_corrected} kept by a correction`] : []
9319
+ ].join(", ");
9320
+ const detail = run.field_diffs ? counts : `${run.rows_written} rows written, not compared row by row`;
9321
+ const key = run.key_column ? ` key ${run.key_column}` : "";
9322
+ return `${run.id} ${run.operation} by ${who}${key} ${run.started_at} \u2192 ${run.last_write_at} (${detail})${run.truncated ? " [entries truncated]" : ""}`;
9323
+ }
9324
+ function printDatasetCorrections(corrections) {
9325
+ printAlignedTable(
9326
+ ["id", "kind", "key", "row", "field", "value", "since"],
9327
+ corrections.map((c) => [
9328
+ c.id,
9329
+ c.kind,
9330
+ c.key_column,
9331
+ c.row_key,
9332
+ c.field ?? "",
9333
+ c.kind === "row" ? "(restored row)" : changeValue(c.value),
9334
+ c.created_at
9335
+ ])
9336
+ );
9337
+ }
9338
+ datasetsCmd.command("changes <slug>").description(
9339
+ "List what changed in a dataset, grouped by the refresh run (or one-off write) that changed it, newest first: rows added, each changed field with its old and new value, rows a replace removed, and values a correction kept. --since-last-visit starts from when you last opened the dataset in the Erdo app. --run <id> pages one run's changes. History is kept for 90 days."
9340
+ ).option("--since <time>", "RFC 3339 start of the period (default 7 days ago)").option("--until <time>", "RFC 3339 end of the period (default now)").option("--since-last-visit", "start from when you last opened this dataset in the Erdo app").option("--run <id>", "page this run's changes in write order instead of listing runs").option("--cursor <cursor>", "next_cursor from the previous page (a run's change_cursor with --run)").option("-l, --limit <n>", "page size", (v) => parseInt(v, 10)).option("--json", "print the raw JSON result").action(
9341
+ async (slug, opts) => {
9342
+ try {
9343
+ if (opts.sinceLastVisit && opts.since) throw new Error("use --since or --since-last-visit, not both");
9344
+ if (opts.run && (opts.since || opts.until || opts.sinceLastVisit)) {
9345
+ throw new Error("--run pages one run's changes; it takes no period");
9346
+ }
9347
+ const client = new ErdoClient();
9348
+ if (opts.run) {
9349
+ const page = await client.listDatasetChangeRunEntries(slug, opts.run, { cursor: opts.cursor, limit: opts.limit });
9350
+ if (opts.json) {
9351
+ print(page);
9352
+ return;
9353
+ }
9354
+ printDatasetChanges(page.changes ?? []);
9355
+ if (page.next_cursor) console.error(`(more: --run ${opts.run} --cursor ${page.next_cursor})`);
9356
+ return;
9357
+ }
9358
+ let since = opts.since;
9359
+ if (opts.sinceLastVisit) {
9360
+ const visit = await client.getDatasetLastVisit(slug);
9361
+ if (!visit.last_viewed_at) {
9362
+ throw new Error(`you have never opened ${slug} in the Erdo app; pass --since instead`);
9363
+ }
9364
+ since = visit.last_viewed_at;
9365
+ }
9366
+ const res = await client.listDatasetChanges(slug, { since, until: opts.until, cursor: opts.cursor, limit: opts.limit });
9367
+ if (opts.json) {
9368
+ print(res);
9369
+ return;
9370
+ }
9371
+ const runs = res.runs ?? [];
9372
+ if (runs.length === 0) {
9373
+ console.log(`No changes to ${slug}${since ? ` since ${since}` : " in the last 7 days"}.`);
9374
+ return;
9375
+ }
9376
+ for (const run of runs) {
9377
+ console.log(describeChangeRun(run));
9378
+ const changes = run.changes ?? [];
9379
+ if (changes.length > 0) printDatasetChanges(changes);
9380
+ if (run.more_changes && run.change_cursor) {
9381
+ console.log(` \u2026 more: erdo datasets changes ${slug} --run ${run.id} --cursor ${run.change_cursor}`);
9382
+ }
9383
+ console.log("");
9384
+ }
9385
+ if (res.next_cursor) console.error(`(more runs: --cursor ${res.next_cursor})`);
9386
+ } catch (e) {
9387
+ fail(e);
9388
+ }
9389
+ }
9390
+ );
9391
+ datasetsCmd.command("row-history <slug> <row-key>").description(
9392
+ "Every recorded change to one row, newest first. The row key is the key value as `datasets changes` shows it; for a composite key, a JSON array of the values in key order."
9393
+ ).requiredOption("--key-column <column>", "the column (comma-separated for a composite key) the row key is in, as a change run's key_column shows it").option("--cursor <cursor>", "next_cursor from the previous page").option("-l, --limit <n>", "page size (default 200, max 1000)", (v) => parseInt(v, 10)).option("--json", "print the raw JSON result").action(async (slug, rowKey, opts) => {
9394
+ try {
9395
+ const page = await new ErdoClient().getDatasetRowHistory(slug, opts.keyColumn, rowKey, { cursor: opts.cursor, limit: opts.limit });
9396
+ if (opts.json) {
9397
+ print(page);
9398
+ return;
9399
+ }
9400
+ const changes = page.changes ?? [];
9401
+ if (changes.length === 0) {
9402
+ console.log(`No recorded changes to ${rowKey} in ${slug} (history is kept for 90 days).`);
9403
+ return;
9404
+ }
9405
+ printDatasetChanges(changes);
9406
+ if (page.next_cursor) console.error(`(more: --cursor ${page.next_cursor})`);
9407
+ } catch (e) {
9408
+ fail(e);
9409
+ }
9410
+ });
9411
+ datasetsCmd.command("last-visit <slug>").description(
9412
+ "When you last opened a dataset in the Erdo app, and the visit before that. Reading this records no visit. `datasets changes <slug> --since-last-visit` lists what changed since."
9413
+ ).option("--json", "print the raw JSON result").action(async (slug, opts) => {
9414
+ try {
9415
+ const visit = await new ErdoClient().getDatasetLastVisit(slug);
9416
+ if (opts.json) {
9417
+ print(visit);
9418
+ return;
9419
+ }
9420
+ if (!visit.last_viewed_at) {
9421
+ console.log(`You have not opened ${slug} in the Erdo app.`);
9422
+ return;
9423
+ }
9424
+ console.log(`last visit ${visit.last_viewed_at}`);
9425
+ console.log(`visit before ${visit.previous_viewed_at ?? "-"}`);
9426
+ } catch (e) {
9427
+ fail(e);
9428
+ }
9429
+ });
9430
+ datasetsCmd.command("restore-row <slug> <change-id>").description(
9431
+ "Put back a row a refresh's replace removed, as it stood then, and keep it through later replaces until it is handed back. The change id is a 'removed' change from `datasets changes` or `datasets row-history`. Refused if the row had a value in a column the dataset no longer has. File datasets only, not managed lead datasets."
9432
+ ).option("--json", "print the raw JSON result").action(async (slug, changeID, opts) => {
9433
+ try {
9434
+ const id = Number(changeID);
9435
+ if (!Number.isSafeInteger(id) || id <= 0) throw new Error("change-id must be the numeric id of a 'removed' change");
9436
+ const res = await new ErdoClient().restoreDatasetRow(slug, id);
9437
+ if (opts.json) {
9438
+ print(res);
9439
+ return;
9440
+ }
9441
+ console.log(`Restored ${res.correction.row_key}. Refreshes keep it until you hand it back:`);
9442
+ console.log(` erdo datasets corrections hand-back ${slug} ${res.correction.id}`);
9443
+ } catch (e) {
9444
+ fail(e);
9445
+ }
9446
+ });
9447
+ var datasetCorrectionsCmd = datasetsCmd.command("corrections").description("Corrections refreshes keep: corrected cells and restored rows");
9448
+ datasetCorrectionsCmd.command("list <slug>").description("List the corrected cells and restored rows refreshes are keeping on a dataset").option("--json", "print the raw JSON result").action(async (slug, opts) => {
9449
+ try {
9450
+ const res = await new ErdoClient().listDatasetCorrections(slug);
9451
+ if (opts.json) {
9452
+ print(res);
9453
+ return;
9454
+ }
9455
+ const corrections = res.corrections ?? [];
9456
+ if (corrections.length === 0) {
9457
+ console.log(`Refreshes are keeping no corrections on ${slug}.`);
9458
+ return;
9459
+ }
9460
+ printDatasetCorrections(corrections);
9461
+ } catch (e) {
9462
+ fail(e);
9463
+ }
9464
+ });
9465
+ datasetCorrectionsCmd.command("set <slug>").description(
9466
+ "Correct one field of one row and keep it: later refreshes that send a different value keep yours until it is handed back. The row must exist; key columns cannot be corrected. File datasets only, not managed lead datasets."
9467
+ ).requiredOption("--key-column <column>", "the column (comma-separated for a composite key) that identifies the row").requiredOption("--row-key <value>", "the row's key value; a JSON array of values for a composite key").requiredOption("--field <column>", "the column to correct").option("--value <value>", "the value to keep").option("--blank", "keep the cell blank").option("--json", "print the raw JSON result").action(
9468
+ async (slug, opts) => {
9469
+ try {
9470
+ if (opts.value === void 0 === !opts.blank) throw new Error("pass exactly one of --value or --blank");
9471
+ const res = await new ErdoClient().correctDatasetCell(slug, {
9472
+ key_column: opts.keyColumn,
9473
+ row_key: opts.rowKey,
9474
+ field: opts.field,
9475
+ value: opts.blank ? null : opts.value
9476
+ });
9477
+ if (opts.json) {
9478
+ print(res);
9479
+ return;
9480
+ }
9481
+ const c = res.correction;
9482
+ console.log(`Corrected ${c.field} on ${c.row_key} to ${changeValue(c.value)}. Refreshes keep it until you hand it back:`);
9483
+ console.log(` erdo datasets corrections hand-back ${slug} ${c.id}`);
9484
+ } catch (e) {
9485
+ fail(e);
9486
+ }
9487
+ }
9488
+ );
9489
+ datasetCorrectionsCmd.command("hand-back <slug> <correction-id>").description(
9490
+ "Hand a corrected cell or restored row back to the refresh. The current value stays until the next refresh, which may change it (or remove the row) again."
9491
+ ).option("--json", "print the raw JSON result").action(async (slug, correctionID, opts) => {
9492
+ try {
9493
+ const res = await new ErdoClient().handBackDatasetCorrection(slug, correctionID);
9494
+ if (opts.json) {
9495
+ print(res);
9496
+ return;
9497
+ }
9498
+ const c = res.correction;
9499
+ console.log(`Handed back ${c.kind === "row" ? "the restored row" : c.field} on ${c.row_key}; the next refresh decides its value.`);
9500
+ } catch (e) {
9501
+ fail(e);
9502
+ }
9503
+ });
9229
9504
  datasetsCmd.command("schema <slug>").alias("describe").description(
9230
9505
  "Show physical columns by default, or the declared write contract with --declared. File datasets read the stored `data` table; integration datasets show their discovered resource tables and columns. For an integration dataset, choose a resource/table explicitly when fetching: `datasets fetch <slug> --sql 'SELECT * FROM <table>'`."
9231
9506
  ).option("--json", "print the raw JSON result instead of a table").option("--declared", "read the declared write contract (column names, type hints, required flags, semantic roles, currency, plus the dataset's owner, record role and provenance requirement) instead of the physical columns").action(async (slug, opts) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@erdoai/cli",
3
- "version": "0.225.0",
3
+ "version": "0.227.0",
4
4
  "description": "Erdo CLI \u2014 drive datasets, pages, and evals from the terminal or CI",
5
5
  "type": "module",
6
6
  "bin": {