Admin: scripting safely

Dry runs, undo, idempotent writes and the audit log.

Beta

The admin routes are beta: they’re what Admin itself uses, and may still change. They answer only admins (the moderation queues also moderators); anyone else gets 404 not_found, as if the route didn’t exist.

Dry run, then apply

The changes that move or merge records have a preview that returns the exact plan and changes nothing:

Preview a merge, then Merge two records. The preview lists what moves, what fills in, warnings, problems that block it, and the fields left for you to decide.
Preview moving issues to another series, then Move issues to another series.

admin.ts

import { createCollectorClient } from '@collector/sdk';

const collector = createCollectorClient({ token: process.env.COLLECTOR_ADMIN_TOKEN });

const merge = {
  entity: 'issue',
  winnerId: '00000000-0000-4000-8000-000000000001',
  loserId: '00000000-0000-4000-8000-000000000002',
  note: 'Duplicate created by an import',
} as const;

// 1. Dry run: the preview is the exact plan, and changes nothing.
const preview = await collector.previewAdminMerge({ body: merge });
if (preview.problems.length || preview.undecided > 0) {
  console.error('Not merging:', preview.problems, `${preview.undecided} field(s) to decide`);
  process.exit(1);
}
for (const warning of preview.warnings) console.warn(warning);

// 2. Apply it. The client sends an Idempotency-Key, so a retry can't merge twice.
const { id } = await collector.executeAdminMerge({ body: merge });
console.log('merged:', id);

// 3. A merge can be undone from its id.
// const { applied, skipped } = await collector.undoAdminMerge({ path: { id } });

Undo

Merges and moves are journaled, so they can be taken back:

Undo a merge and Undo an issue move.
Undo a revert of an overridden field, and Undo an assigned import suggestion.

Writing safely

Idempotent writes: merges, moves, plan grants and announcements take an Idempotency-Key, so a retried script can’t do them twice.
Field locks: Lock or unlock a field keeps imports from changing a value you corrected.
The audit log: admin actions are recorded; read them with Audit log, which pages back with before.
Admin API keys (expiring within 90 days, limited to your servers’ addresses) are coming with ENGIN-45. Until then, admin routes take an admin’s signed-in session.

Dry run, then apply

The changes that move or merge records have a preview that returns the exact plan and changes nothing:

Preview a merge, then Merge two records. The preview lists what moves, what fills in, warnings, problems that block it, and the fields left for you to decide.
Preview moving issues to another series, then Move issues to another series.

admin.ts

import { createCollectorClient } from '@collector/sdk';

const collector = createCollectorClient({ token: process.env.COLLECTOR_ADMIN_TOKEN });

const merge = {
  entity: 'issue',
  winnerId: '00000000-0000-4000-8000-000000000001',
  loserId: '00000000-0000-4000-8000-000000000002',
  note: 'Duplicate created by an import',
} as const;

// 1. Dry run: the preview is the exact plan, and changes nothing.
const preview = await collector.previewAdminMerge({ body: merge });
if (preview.problems.length || preview.undecided > 0) {
  console.error('Not merging:', preview.problems, `${preview.undecided} field(s) to decide`);
  process.exit(1);
}
for (const warning of preview.warnings) console.warn(warning);

// 2. Apply it. The client sends an Idempotency-Key, so a retry can't merge twice.
const { id } = await collector.executeAdminMerge({ body: merge });
console.log('merged:', id);

// 3. A merge can be undone from its id.
// const { applied, skipped } = await collector.undoAdminMerge({ path: { id } });

Writing safely

Idempotent writes: merges, moves, plan grants and announcements take an Idempotency-Key, so a retried script can’t do them twice.
Field locks: Lock or unlock a field keeps imports from changing a value you corrected.
The audit log: admin actions are recorded; read them with Audit log, which pages back with before.
Admin API keys (expiring within 90 days, limited to your servers’ addresses) are coming with ENGIN-45. Until then, admin routes take an admin’s signed-in session.