@erdoai/cli 0.225.0 → 0.226.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.
- package/dist/index.js +278 -0
- 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
|
|
@@ -9226,6 +9294,216 @@ Read one with: erdo datasets fetch ${res.dataset_slug} --revision <id> --sql "SE
|
|
|
9226
9294
|
fail(e);
|
|
9227
9295
|
}
|
|
9228
9296
|
});
|
|
9297
|
+
function changeValue(v) {
|
|
9298
|
+
return v === null ? "(blank)" : v;
|
|
9299
|
+
}
|
|
9300
|
+
function printDatasetChanges(changes) {
|
|
9301
|
+
printAlignedTable(
|
|
9302
|
+
["change", "kind", "row", "field", "old", "new", "at"],
|
|
9303
|
+
changes.map((c) => [
|
|
9304
|
+
c.id,
|
|
9305
|
+
c.kind,
|
|
9306
|
+
c.row_key,
|
|
9307
|
+
c.field ?? "",
|
|
9308
|
+
// A removed row's old value is the whole row as JSON, kept for restore.
|
|
9309
|
+
c.kind === "added" ? "" : changeValue(c.old_value),
|
|
9310
|
+
c.kind === "removed" || c.kind === "handed_back" ? "" : changeValue(c.new_value),
|
|
9311
|
+
c.created_at
|
|
9312
|
+
])
|
|
9313
|
+
);
|
|
9314
|
+
}
|
|
9315
|
+
function describeChangeRun(run) {
|
|
9316
|
+
const who = run.actor_type === "refresh" ? `refresh${run.run_id ? ` run ${run.run_id}` : ""}` : run.actor_type;
|
|
9317
|
+
const counts = [
|
|
9318
|
+
`${run.rows_added} added`,
|
|
9319
|
+
`${run.rows_changed} changed`,
|
|
9320
|
+
`${run.rows_removed} removed`,
|
|
9321
|
+
...run.rows_corrected ? [`${run.rows_corrected} kept by a correction`] : []
|
|
9322
|
+
].join(", ");
|
|
9323
|
+
const detail = run.field_diffs ? counts : `${run.rows_written} rows written, not compared row by row`;
|
|
9324
|
+
const key = run.key_column ? ` key ${run.key_column}` : "";
|
|
9325
|
+
return `${run.id} ${run.operation} by ${who}${key} ${run.started_at} \u2192 ${run.last_write_at} (${detail})${run.truncated ? " [entries truncated]" : ""}`;
|
|
9326
|
+
}
|
|
9327
|
+
function printDatasetCorrections(corrections) {
|
|
9328
|
+
printAlignedTable(
|
|
9329
|
+
["id", "kind", "key", "row", "field", "value", "since"],
|
|
9330
|
+
corrections.map((c) => [
|
|
9331
|
+
c.id,
|
|
9332
|
+
c.kind,
|
|
9333
|
+
c.key_column,
|
|
9334
|
+
c.row_key,
|
|
9335
|
+
c.field ?? "",
|
|
9336
|
+
c.kind === "row" ? "(restored row)" : changeValue(c.value),
|
|
9337
|
+
c.created_at
|
|
9338
|
+
])
|
|
9339
|
+
);
|
|
9340
|
+
}
|
|
9341
|
+
datasetsCmd.command("changes <slug>").description(
|
|
9342
|
+
"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."
|
|
9343
|
+
).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(
|
|
9344
|
+
async (slug, opts) => {
|
|
9345
|
+
try {
|
|
9346
|
+
if (opts.sinceLastVisit && opts.since) throw new Error("use --since or --since-last-visit, not both");
|
|
9347
|
+
if (opts.run && (opts.since || opts.until || opts.sinceLastVisit)) {
|
|
9348
|
+
throw new Error("--run pages one run's changes; it takes no period");
|
|
9349
|
+
}
|
|
9350
|
+
const client = new ErdoClient();
|
|
9351
|
+
if (opts.run) {
|
|
9352
|
+
const page = await client.listDatasetChangeRunEntries(slug, opts.run, { cursor: opts.cursor, limit: opts.limit });
|
|
9353
|
+
if (opts.json) {
|
|
9354
|
+
print(page);
|
|
9355
|
+
return;
|
|
9356
|
+
}
|
|
9357
|
+
printDatasetChanges(page.changes ?? []);
|
|
9358
|
+
if (page.next_cursor) console.error(`(more: --run ${opts.run} --cursor ${page.next_cursor})`);
|
|
9359
|
+
return;
|
|
9360
|
+
}
|
|
9361
|
+
let since = opts.since;
|
|
9362
|
+
if (opts.sinceLastVisit) {
|
|
9363
|
+
const visit = await client.getDatasetLastVisit(slug);
|
|
9364
|
+
if (!visit.last_viewed_at) {
|
|
9365
|
+
throw new Error(`you have never opened ${slug} in the Erdo app; pass --since instead`);
|
|
9366
|
+
}
|
|
9367
|
+
since = visit.last_viewed_at;
|
|
9368
|
+
}
|
|
9369
|
+
const res = await client.listDatasetChanges(slug, { since, until: opts.until, cursor: opts.cursor, limit: opts.limit });
|
|
9370
|
+
if (opts.json) {
|
|
9371
|
+
print(res);
|
|
9372
|
+
return;
|
|
9373
|
+
}
|
|
9374
|
+
const runs = res.runs ?? [];
|
|
9375
|
+
if (runs.length === 0) {
|
|
9376
|
+
console.log(`No changes to ${slug}${since ? ` since ${since}` : " in the last 7 days"}.`);
|
|
9377
|
+
return;
|
|
9378
|
+
}
|
|
9379
|
+
for (const run of runs) {
|
|
9380
|
+
console.log(describeChangeRun(run));
|
|
9381
|
+
const changes = run.changes ?? [];
|
|
9382
|
+
if (changes.length > 0) printDatasetChanges(changes);
|
|
9383
|
+
if (run.more_changes && run.change_cursor) {
|
|
9384
|
+
console.log(` \u2026 more: erdo datasets changes ${slug} --run ${run.id} --cursor ${run.change_cursor}`);
|
|
9385
|
+
}
|
|
9386
|
+
console.log("");
|
|
9387
|
+
}
|
|
9388
|
+
if (res.next_cursor) console.error(`(more runs: --cursor ${res.next_cursor})`);
|
|
9389
|
+
} catch (e) {
|
|
9390
|
+
fail(e);
|
|
9391
|
+
}
|
|
9392
|
+
}
|
|
9393
|
+
);
|
|
9394
|
+
datasetsCmd.command("row-history <slug> <row-key>").description(
|
|
9395
|
+
"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."
|
|
9396
|
+
).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) => {
|
|
9397
|
+
try {
|
|
9398
|
+
const page = await new ErdoClient().getDatasetRowHistory(slug, opts.keyColumn, rowKey, { cursor: opts.cursor, limit: opts.limit });
|
|
9399
|
+
if (opts.json) {
|
|
9400
|
+
print(page);
|
|
9401
|
+
return;
|
|
9402
|
+
}
|
|
9403
|
+
const changes = page.changes ?? [];
|
|
9404
|
+
if (changes.length === 0) {
|
|
9405
|
+
console.log(`No recorded changes to ${rowKey} in ${slug} (history is kept for 90 days).`);
|
|
9406
|
+
return;
|
|
9407
|
+
}
|
|
9408
|
+
printDatasetChanges(changes);
|
|
9409
|
+
if (page.next_cursor) console.error(`(more: --cursor ${page.next_cursor})`);
|
|
9410
|
+
} catch (e) {
|
|
9411
|
+
fail(e);
|
|
9412
|
+
}
|
|
9413
|
+
});
|
|
9414
|
+
datasetsCmd.command("last-visit <slug>").description(
|
|
9415
|
+
"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."
|
|
9416
|
+
).option("--json", "print the raw JSON result").action(async (slug, opts) => {
|
|
9417
|
+
try {
|
|
9418
|
+
const visit = await new ErdoClient().getDatasetLastVisit(slug);
|
|
9419
|
+
if (opts.json) {
|
|
9420
|
+
print(visit);
|
|
9421
|
+
return;
|
|
9422
|
+
}
|
|
9423
|
+
if (!visit.last_viewed_at) {
|
|
9424
|
+
console.log(`You have not opened ${slug} in the Erdo app.`);
|
|
9425
|
+
return;
|
|
9426
|
+
}
|
|
9427
|
+
console.log(`last visit ${visit.last_viewed_at}`);
|
|
9428
|
+
console.log(`visit before ${visit.previous_viewed_at ?? "-"}`);
|
|
9429
|
+
} catch (e) {
|
|
9430
|
+
fail(e);
|
|
9431
|
+
}
|
|
9432
|
+
});
|
|
9433
|
+
datasetsCmd.command("restore-row <slug> <change-id>").description(
|
|
9434
|
+
"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."
|
|
9435
|
+
).option("--json", "print the raw JSON result").action(async (slug, changeID, opts) => {
|
|
9436
|
+
try {
|
|
9437
|
+
const id = Number(changeID);
|
|
9438
|
+
if (!Number.isSafeInteger(id) || id <= 0) throw new Error("change-id must be the numeric id of a 'removed' change");
|
|
9439
|
+
const res = await new ErdoClient().restoreDatasetRow(slug, id);
|
|
9440
|
+
if (opts.json) {
|
|
9441
|
+
print(res);
|
|
9442
|
+
return;
|
|
9443
|
+
}
|
|
9444
|
+
console.log(`Restored ${res.correction.row_key}. Refreshes keep it until you hand it back:`);
|
|
9445
|
+
console.log(` erdo datasets corrections hand-back ${slug} ${res.correction.id}`);
|
|
9446
|
+
} catch (e) {
|
|
9447
|
+
fail(e);
|
|
9448
|
+
}
|
|
9449
|
+
});
|
|
9450
|
+
var datasetCorrectionsCmd = datasetsCmd.command("corrections").description("Corrections refreshes keep: corrected cells and restored rows");
|
|
9451
|
+
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) => {
|
|
9452
|
+
try {
|
|
9453
|
+
const res = await new ErdoClient().listDatasetCorrections(slug);
|
|
9454
|
+
if (opts.json) {
|
|
9455
|
+
print(res);
|
|
9456
|
+
return;
|
|
9457
|
+
}
|
|
9458
|
+
const corrections = res.corrections ?? [];
|
|
9459
|
+
if (corrections.length === 0) {
|
|
9460
|
+
console.log(`Refreshes are keeping no corrections on ${slug}.`);
|
|
9461
|
+
return;
|
|
9462
|
+
}
|
|
9463
|
+
printDatasetCorrections(corrections);
|
|
9464
|
+
} catch (e) {
|
|
9465
|
+
fail(e);
|
|
9466
|
+
}
|
|
9467
|
+
});
|
|
9468
|
+
datasetCorrectionsCmd.command("set <slug>").description(
|
|
9469
|
+
"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."
|
|
9470
|
+
).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(
|
|
9471
|
+
async (slug, opts) => {
|
|
9472
|
+
try {
|
|
9473
|
+
if (opts.value === void 0 === !opts.blank) throw new Error("pass exactly one of --value or --blank");
|
|
9474
|
+
const res = await new ErdoClient().correctDatasetCell(slug, {
|
|
9475
|
+
key_column: opts.keyColumn,
|
|
9476
|
+
row_key: opts.rowKey,
|
|
9477
|
+
field: opts.field,
|
|
9478
|
+
value: opts.blank ? null : opts.value
|
|
9479
|
+
});
|
|
9480
|
+
if (opts.json) {
|
|
9481
|
+
print(res);
|
|
9482
|
+
return;
|
|
9483
|
+
}
|
|
9484
|
+
const c = res.correction;
|
|
9485
|
+
console.log(`Corrected ${c.field} on ${c.row_key} to ${changeValue(c.value)}. Refreshes keep it until you hand it back:`);
|
|
9486
|
+
console.log(` erdo datasets corrections hand-back ${slug} ${c.id}`);
|
|
9487
|
+
} catch (e) {
|
|
9488
|
+
fail(e);
|
|
9489
|
+
}
|
|
9490
|
+
}
|
|
9491
|
+
);
|
|
9492
|
+
datasetCorrectionsCmd.command("hand-back <slug> <correction-id>").description(
|
|
9493
|
+
"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."
|
|
9494
|
+
).option("--json", "print the raw JSON result").action(async (slug, correctionID, opts) => {
|
|
9495
|
+
try {
|
|
9496
|
+
const res = await new ErdoClient().handBackDatasetCorrection(slug, correctionID);
|
|
9497
|
+
if (opts.json) {
|
|
9498
|
+
print(res);
|
|
9499
|
+
return;
|
|
9500
|
+
}
|
|
9501
|
+
const c = res.correction;
|
|
9502
|
+
console.log(`Handed back ${c.kind === "row" ? "the restored row" : c.field} on ${c.row_key}; the next refresh decides its value.`);
|
|
9503
|
+
} catch (e) {
|
|
9504
|
+
fail(e);
|
|
9505
|
+
}
|
|
9506
|
+
});
|
|
9229
9507
|
datasetsCmd.command("schema <slug>").alias("describe").description(
|
|
9230
9508
|
"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
9509
|
).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) => {
|