dpdp-kit 0.1.1 → 0.2.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 CHANGED
@@ -6,12 +6,17 @@ import {
6
6
  CONSENT_REQUIRED_BODY
7
7
  } from "./chunk-FGZAH2NF.js";
8
8
  import {
9
+ REQUEST_TYPES,
9
10
  audit,
11
+ checkSchema,
10
12
  durationMs,
13
+ guessPersonal,
11
14
  hasErrors,
12
15
  isDuration,
13
- maxDuration
14
- } from "./chunk-HRKHRKV4.js";
16
+ isRunnable,
17
+ maxDuration,
18
+ tokenize
19
+ } from "./chunk-KVTUMHXO.js";
15
20
 
16
21
  // src/config.ts
17
22
  function defineConfig(config) {
@@ -21,6 +26,9 @@ function purposeNames(config) {
21
26
  return Object.keys(config.purposes);
22
27
  }
23
28
 
29
+ // src/dpdp.ts
30
+ import { randomUUID as randomUUID2 } from "crypto";
31
+
24
32
  // src/erasure.ts
25
33
  function erasureDelay(config, ended) {
26
34
  let delay = "0d";
@@ -52,7 +60,7 @@ function planErasure(config, input) {
52
60
  const allFieldsGo = fields.length === Object.keys(table.fields).length && fields.every((f) => f.action !== "keep");
53
61
  let action;
54
62
  if (fields.some((f) => f.action === "hold")) action = "hold";
55
- else if (input.reason === "account-deletion" && allFieldsGo) action = "delete-rows";
63
+ else if (input.reason !== "withdrawal" && allFieldsGo) action = "delete-rows";
56
64
  else if (fields.some((f) => f.action === "erase")) action = "erase-fields";
57
65
  else action = "keep";
58
66
  tables.push({
@@ -124,6 +132,204 @@ function isNoticeLanguage(value) {
124
132
  return typeof value === "string" && Object.hasOwn(NOTICE_LANGUAGES, value);
125
133
  }
126
134
 
135
+ // src/retention.ts
136
+ import { randomUUID } from "crypto";
137
+ var MAX_ATTEMPTS = 5;
138
+ var STALE_AFTER_MS = 15 * 60 * 1e3;
139
+ var addMs = (iso, ms) => new Date(Date.parse(iso) + ms).toISOString();
140
+ function tasksFromPlan(config, plan, now) {
141
+ const minimum = config.minimumRetention ?? "0d";
142
+ const base = { subjectId: plan.subjectId, reason: plan.reason, createdAt: now, status: "pending", attempts: 0 };
143
+ const due = (wait) => addMs(now, durationMs(maxDuration(wait, minimum)));
144
+ const tasks = [];
145
+ for (const table of plan.tables) {
146
+ if (table.action === "keep") continue;
147
+ if (table.action === "hold" && table.hold) {
148
+ const fields = table.fields.filter((f) => f.action === "hold").map((f) => f.field);
149
+ tasks.push({
150
+ ...base,
151
+ id: randomUUID(),
152
+ kind: table.hold.then === "delete" ? "delete-rows" : "erase-fields",
153
+ table: table.key,
154
+ ...table.hold.then === "delete" ? {} : { fields },
155
+ dueAt: due(table.hold.keep)
156
+ });
157
+ continue;
158
+ }
159
+ const erasable = table.fields.filter((f) => f.action === "erase");
160
+ const wait = erasable.reduce((d, f) => f.after ? maxDuration(d, f.after) : d, "0d");
161
+ tasks.push({
162
+ ...base,
163
+ id: randomUUID(),
164
+ kind: table.action === "delete-rows" ? "delete-rows" : "erase-fields",
165
+ table: table.key,
166
+ ...table.action === "delete-rows" ? {} : { fields: erasable.map((f) => f.field) },
167
+ dueAt: due(wait)
168
+ });
169
+ }
170
+ for (const processor of plan.processors) {
171
+ tasks.push({ ...base, id: randomUUID(), kind: "processor-stop", processor: processor.name, purposes: processor.ended, dueAt: now });
172
+ if (processor.action === "erase") {
173
+ tasks.push({
174
+ ...base,
175
+ id: randomUUID(),
176
+ kind: "processor-erase",
177
+ processor: processor.name,
178
+ purposes: processor.ended,
179
+ dueAt: due("0d")
180
+ });
181
+ }
182
+ }
183
+ return tasks;
184
+ }
185
+ var errorText = (err) => err instanceof Error ? err.message : String(err);
186
+ async function carryOut(task, input) {
187
+ if (task.kind === "processor-stop" || task.kind === "processor-erase") {
188
+ const hook = input.processors[task.processor ?? ""]?.[task.kind === "processor-stop" ? "stop" : "erase"];
189
+ if (!hook) return { manual: true };
190
+ await hook({ subjectId: task.subjectId, purposes: task.purposes ?? [], reason: task.reason });
191
+ return {};
192
+ }
193
+ const def = input.config.data[task.table ?? ""];
194
+ if (!def) throw new Error(`Table "${task.table}" is no longer in the data map`);
195
+ if (!input.data) throw new Error("No data access configured: pass `data` to createDpdp to erase from your tables");
196
+ if (task.kind === "delete-rows") {
197
+ return { affected: await input.data.deleteRows(def.table, def.subject, task.subjectId) };
198
+ }
199
+ return { affected: await input.data.eraseFields(def.table, def.subject, task.subjectId, task.fields ?? []) };
200
+ }
201
+ async function runDueTasks(input) {
202
+ const when = { now: input.now, staleBefore: addMs(input.now, -STALE_AFTER_MS), maxAttempts: MAX_ATTEMPTS };
203
+ const report = { done: [], failed: [], manual: [] };
204
+ for (const task of await input.store.dueTasks({ ...when, limit: input.limit })) {
205
+ if (!await input.store.claimTask({ id: task.id, ...when })) continue;
206
+ const attempts = task.attempts + 1;
207
+ try {
208
+ const result = await carryOut(task, input);
209
+ const { lastError: _, claimedAt: __, ...rest } = task;
210
+ const finished = result.manual ? { ...rest, status: "manual", attempts } : {
211
+ ...rest,
212
+ status: "done",
213
+ attempts,
214
+ doneAt: input.now,
215
+ ...result.affected !== void 0 ? { affected: result.affected } : {}
216
+ };
217
+ await input.store.updateTask(finished);
218
+ (result.manual ? report.manual : report.done).push(finished);
219
+ } catch (err) {
220
+ const { claimedAt: _, ...rest } = task;
221
+ const failed = { ...rest, status: "failed", attempts, lastError: errorText(err) };
222
+ await input.store.updateTask(failed);
223
+ report.failed.push(failed);
224
+ }
225
+ }
226
+ return report;
227
+ }
228
+
229
+ // src/rights.ts
230
+ var DEFAULT_RESPONSE_WITHIN = "90d";
231
+ function responseWithin(config, type) {
232
+ const setting = config.rights?.responseWithin;
233
+ if (setting === void 0) return DEFAULT_RESPONSE_WITHIN;
234
+ if (typeof setting === "string") return setting;
235
+ return setting[type] ?? DEFAULT_RESPONSE_WITHIN;
236
+ }
237
+ function dueAt(config, type, openedAt) {
238
+ return new Date(Date.parse(openedAt) + durationMs(responseWithin(config, type))).toISOString();
239
+ }
240
+ async function buildAccessSummary(input) {
241
+ const { config, data, subjectId, consents, now } = input;
242
+ const legitimateUses = Object.entries(config.purposes).filter(([, def]) => def.basis === "legitimate-use").map(([name]) => name);
243
+ const applies = /* @__PURE__ */ new Set([...consents, ...legitimateUses]);
244
+ const tables = [];
245
+ for (const [key, def] of Object.entries(config.data)) {
246
+ const fields = Object.entries(def.fields).map(([field, f]) => ({
247
+ field,
248
+ category: f.category,
249
+ purposes: [...f.purposes]
250
+ }));
251
+ const rows = await data.read(
252
+ def.table,
253
+ def.subject,
254
+ subjectId,
255
+ fields.map((f) => f.field)
256
+ );
257
+ if (rows.length > 0) tables.push({ key, table: def.table, fields, rows });
258
+ }
259
+ const sharedWith = Object.entries(config.processors ?? {}).map(([name, p]) => ({
260
+ name,
261
+ ...p.description !== void 0 ? { description: p.description } : {},
262
+ purposes: p.purposes.filter((purpose) => applies.has(purpose))
263
+ })).filter((p) => p.purposes.length > 0);
264
+ return { subjectId, generatedAt: now, data: tables, consents, legitimateUses, sharedWith };
265
+ }
266
+
267
+ // src/store.ts
268
+ function isDpdpStore(store) {
269
+ const s = store;
270
+ return typeof s.insertRequest === "function" && typeof s.insertTasks === "function";
271
+ }
272
+ function memoryStore() {
273
+ const all = /* @__PURE__ */ new Map();
274
+ const requests = /* @__PURE__ */ new Map();
275
+ const tasks = /* @__PURE__ */ new Map();
276
+ const byDue = (a, b) => a.dueAt < b.dueAt ? -1 : a.dueAt > b.dueAt ? 1 : 0;
277
+ return {
278
+ all,
279
+ requests,
280
+ tasks,
281
+ async insertRequest(request) {
282
+ requests.set(request.id, structuredClone(request));
283
+ },
284
+ async getRequest(id) {
285
+ const r = requests.get(id);
286
+ return r && structuredClone(r);
287
+ },
288
+ async updateRequest(request) {
289
+ requests.set(request.id, structuredClone(request));
290
+ },
291
+ async listRequests(filter) {
292
+ return [...requests.values()].filter((r) => (!filter.subjectId || r.subjectId === filter.subjectId) && (!filter.status || r.status === filter.status)).sort((a, b) => a.openedAt < b.openedAt ? -1 : 1).map((r) => structuredClone(r));
293
+ },
294
+ async insertTasks(list) {
295
+ for (const t of list) tasks.set(t.id, structuredClone(t));
296
+ },
297
+ async dueTasks({ limit, ...when }) {
298
+ return [...tasks.values()].filter((t) => isRunnable(t, when)).sort(byDue).slice(0, limit).map((t) => structuredClone(t));
299
+ },
300
+ async claimTask({ id, ...when }) {
301
+ const t = tasks.get(id);
302
+ if (!t || !isRunnable(t, when)) return false;
303
+ tasks.set(id, { ...t, status: "running", claimedAt: when.now });
304
+ return true;
305
+ },
306
+ async updateTask(task) {
307
+ tasks.set(task.id, structuredClone(task));
308
+ },
309
+ async getTask(id) {
310
+ const t = tasks.get(id);
311
+ return t && structuredClone(t);
312
+ },
313
+ async listTasks(filter) {
314
+ return [...tasks.values()].filter((t) => (!filter.subjectId || t.subjectId === filter.subjectId) && (!filter.status || t.status === filter.status)).sort(byDue).map((t) => structuredClone(t));
315
+ },
316
+ async lastEvent(subjectId) {
317
+ const list = all.get(subjectId);
318
+ return list?.[list.length - 1];
319
+ },
320
+ async insert(event) {
321
+ const list = all.get(event.subjectId) ?? [];
322
+ if (list.some((e) => e.seq === event.seq)) throw new SeqConflictError(event.subjectId, event.seq);
323
+ list.push(structuredClone(event));
324
+ list.sort((a, b) => a.seq - b.seq);
325
+ all.set(event.subjectId, list);
326
+ },
327
+ async events(subjectId) {
328
+ return structuredClone(all.get(subjectId) ?? []);
329
+ }
330
+ };
331
+ }
332
+
127
333
  // src/dpdp.ts
128
334
  function hashEvent(event) {
129
335
  return sha256(
@@ -219,6 +425,59 @@ ${lines.join("\n")}`, issues);
219
425
  checkSubject(subjectId);
220
426
  return [...grantedFrom(await store.events(subjectId))];
221
427
  }
428
+ const nowIso = () => now().toISOString();
429
+ const processorHooks = options.processors ?? {};
430
+ function fullStore(feature) {
431
+ if (!isDpdpStore(store)) {
432
+ throw new DpdpError(
433
+ "store-unsupported",
434
+ `${feature} needs a store that keeps requests and tasks: memoryStore(), drizzleStore(db), or a full DpdpStore`
435
+ );
436
+ }
437
+ return store;
438
+ }
439
+ function dataAccess() {
440
+ if (!options.data) {
441
+ throw new DpdpError("no-data-access", "Pass `data` to createDpdp (e.g. drizzleData(db)) to read or erase personal data");
442
+ }
443
+ return options.data;
444
+ }
445
+ async function schedule(plan) {
446
+ const tasks = tasksFromPlan(config, plan, nowIso());
447
+ if (tasks.length > 0) await fullStore("Scheduling erasure").insertTasks(tasks);
448
+ return tasks;
449
+ }
450
+ async function requireRequest(id) {
451
+ const request = await fullStore("Rights requests").getRequest(id);
452
+ if (!request) throw new DpdpError("request-not-found", `No rights request with id ${JSON.stringify(id)}`);
453
+ return request;
454
+ }
455
+ async function close(id, status, note) {
456
+ const request = await requireRequest(id);
457
+ if (request.status !== "open") {
458
+ throw new DpdpError("request-closed", `Request ${id} is already ${request.status}`);
459
+ }
460
+ const at = nowIso();
461
+ const closed = {
462
+ ...request,
463
+ status,
464
+ closedAt: at,
465
+ history: [...request.history, { at, status, ...note !== void 0 ? { note } : {} }]
466
+ };
467
+ await fullStore("Rights requests").updateRequest(closed);
468
+ return closed;
469
+ }
470
+ function accountPlan(subjectId, reason, keepFor) {
471
+ for (const p of keepFor) {
472
+ if (!purposes[p]) throw new DpdpError("unknown-purpose", `Unknown purpose ${JSON.stringify(p)}`);
473
+ }
474
+ return planErasure(config, {
475
+ subjectId,
476
+ reason,
477
+ ended: Object.keys(purposes).filter((p) => !keepFor.includes(p)),
478
+ remaining: [...keepFor]
479
+ });
480
+ }
222
481
  return {
223
482
  config,
224
483
  consent: {
@@ -232,7 +491,8 @@ ${lines.join("\n")}`, issues);
232
491
  ended: event.purposes,
233
492
  remaining: [...legitimate, ...stillGranted]
234
493
  });
235
- return { event, erasure };
494
+ const tasks = isDpdpStore(store) ? await schedule(erasure) : [];
495
+ return { event, erasure, tasks };
236
496
  },
237
497
  async has(subjectId, purpose) {
238
498
  checkSubject(subjectId);
@@ -269,52 +529,143 @@ ${lines.join("\n")}`, issues);
269
529
  erasure: {
270
530
  async plan(subjectId, input) {
271
531
  checkSubject(subjectId);
272
- return planErasure(config, {
532
+ return accountPlan(subjectId, input.reason, []);
533
+ },
534
+ schedule,
535
+ async deleteAccount(subjectId) {
536
+ checkSubject(subjectId);
537
+ const plan = accountPlan(subjectId, "account-deletion", []);
538
+ return { plan, tasks: await schedule(plan) };
539
+ }
540
+ },
541
+ retention: {
542
+ async run(input = {}) {
543
+ return runDueTasks({
544
+ config,
545
+ store: fullStore("The retention runner"),
546
+ data: options.data,
547
+ processors: processorHooks,
548
+ now: nowIso(),
549
+ limit: input.limit ?? 500
550
+ });
551
+ },
552
+ async tasks(filter = {}) {
553
+ return fullStore("Erasure tasks").listTasks(filter);
554
+ },
555
+ async markDone(taskId, note) {
556
+ const tasks = fullStore("Erasure tasks");
557
+ const task = await tasks.getTask(taskId);
558
+ if (!task) throw new DpdpError("task-not-found", `No erasure task with id ${JSON.stringify(taskId)}`);
559
+ if (task.status !== "manual" && task.status !== "failed") {
560
+ throw new DpdpError("task-not-manual", `Task ${taskId} is ${task.status}; only manual or failed tasks can be marked done`);
561
+ }
562
+ const done = { ...task, status: "done", doneAt: nowIso(), note };
563
+ await tasks.updateTask(done);
564
+ return done;
565
+ }
566
+ },
567
+ rights: {
568
+ async open(subjectId, type, details) {
569
+ checkSubject(subjectId);
570
+ if (!REQUEST_TYPES.includes(type)) {
571
+ throw new DpdpError("invalid-request-type", `Unknown request type ${JSON.stringify(type)}`);
572
+ }
573
+ const openedAt = nowIso();
574
+ const request = {
575
+ id: randomUUID2(),
273
576
  subjectId,
274
- reason: input.reason,
275
- ended: Object.keys(purposes),
276
- remaining: []
577
+ type,
578
+ status: "open",
579
+ openedAt,
580
+ dueAt: dueAt(config, type, openedAt),
581
+ ...details !== void 0 ? { details: structuredClone(details) } : {},
582
+ history: [{ at: openedAt, status: "open" }]
583
+ };
584
+ await fullStore("Rights requests").insertRequest(request);
585
+ return request;
586
+ },
587
+ get: (id) => fullStore("Rights requests").getRequest(id),
588
+ async list(filter = {}) {
589
+ const { overdue, ...rest } = filter;
590
+ const list = await fullStore("Rights requests").listRequests(overdue ? { ...rest, status: "open" } : rest);
591
+ if (!overdue) return list;
592
+ const at = nowIso();
593
+ return list.filter((r) => r.dueAt < at);
594
+ },
595
+ resolve: (id, note) => close(id, "resolved", note),
596
+ reject: (id, reason) => close(id, "rejected", reason),
597
+ async summary(subjectId) {
598
+ checkSubject(subjectId);
599
+ return buildAccessSummary({
600
+ config,
601
+ data: dataAccess(),
602
+ subjectId,
603
+ consents: await activeFor(subjectId),
604
+ now: nowIso()
277
605
  });
606
+ },
607
+ async erase(subjectId, input = {}) {
608
+ checkSubject(subjectId);
609
+ if (input.requestId) {
610
+ const request = await requireRequest(input.requestId);
611
+ if (request.subjectId !== subjectId) {
612
+ throw new DpdpError("request-not-found", `Request ${input.requestId} belongs to a different person`);
613
+ }
614
+ }
615
+ const plan = accountPlan(subjectId, "erasure-request", input.keepFor ?? []);
616
+ const tasks = await schedule(plan);
617
+ if (input.requestId) {
618
+ await close(input.requestId, "resolved", `Erasure scheduled: ${tasks.length} task(s)`);
619
+ }
620
+ return { plan, tasks };
278
621
  }
279
622
  }
280
623
  };
281
624
  }
282
625
 
283
- // src/store.ts
284
- function memoryStore() {
285
- const all = /* @__PURE__ */ new Map();
626
+ // src/data-access.ts
627
+ function memoryData(tables) {
628
+ const rowsOf = (table) => tables[table] ??= [];
629
+ const mine = (subjectColumn, subjectId) => (row) => String(row[subjectColumn]) === subjectId;
286
630
  return {
287
- all,
288
- async lastEvent(subjectId) {
289
- const list = all.get(subjectId);
290
- return list?.[list.length - 1];
631
+ tables,
632
+ async read(table, subjectColumn, subjectId, columns) {
633
+ return rowsOf(table).filter(mine(subjectColumn, subjectId)).map((row) => Object.fromEntries(columns.map((c) => [c, row[c] ?? null])));
291
634
  },
292
- async insert(event) {
293
- const list = all.get(event.subjectId) ?? [];
294
- if (list.some((e) => e.seq === event.seq)) throw new SeqConflictError(event.subjectId, event.seq);
295
- list.push(structuredClone(event));
296
- list.sort((a, b) => a.seq - b.seq);
297
- all.set(event.subjectId, list);
635
+ async eraseFields(table, subjectColumn, subjectId, columns) {
636
+ const rows = rowsOf(table).filter(mine(subjectColumn, subjectId));
637
+ for (const row of rows) for (const c of columns) row[c] = null;
638
+ return rows.length;
298
639
  },
299
- async events(subjectId) {
300
- return structuredClone(all.get(subjectId) ?? []);
640
+ async deleteRows(table, subjectColumn, subjectId) {
641
+ const before = rowsOf(table).length;
642
+ tables[table] = rowsOf(table).filter((row) => !mine(subjectColumn, subjectId)(row));
643
+ return before - tables[table].length;
301
644
  }
302
645
  };
303
646
  }
304
647
  export {
305
648
  CONSENT_REQUIRED_BODY,
649
+ DEFAULT_RESPONSE_WITHIN,
306
650
  DpdpError,
307
651
  NOTICE_LANGUAGES,
652
+ REQUEST_TYPES,
308
653
  SeqConflictError,
309
654
  audit,
655
+ checkSchema,
310
656
  createDpdp,
311
657
  defineConfig,
312
658
  durationMs,
659
+ guessPersonal,
313
660
  hasErrors,
314
661
  hashEvent,
662
+ isDpdpStore,
315
663
  isDuration,
316
664
  isNoticeLanguage,
665
+ memoryData,
317
666
  memoryStore,
318
667
  planErasure,
319
- purposeNames
668
+ purposeNames,
669
+ tasksFromPlan,
670
+ tokenize
320
671
  };
@@ -0,0 +1,17 @@
1
+ import type { Category } from "./config.js";
2
+ /**
3
+ * How sure we are that a column holds personal data, judging only by its name.
4
+ * - `strong`: almost always personal (phone, email, aadhaar, date_of_birth, ip_address…).
5
+ * - `weak`: often personal, often not (`name` is a person in `users` but a product in `products`).
6
+ */
7
+ export type Confidence = "strong" | "weak";
8
+ export interface PersonalGuess {
9
+ category: Category;
10
+ confidence: Confidence;
11
+ /** What matched, for the audit message, e.g. `"phone"`. */
12
+ matched: string;
13
+ }
14
+ /** `phoneNumber`, `phone_number`, `PhoneNumber`, `phone-number` → `["phone", "number"]`. */
15
+ export declare function tokenize(name: string): string[];
16
+ /** Guess, from its name alone, whether a column holds personal data. */
17
+ export declare function guessPersonal(columnName: string): PersonalGuess | undefined;
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Records kept alongside consent events: rights requests (Sections 11–14) and erasure tasks
3
+ * (Section 8(7), Rule 8(3)).
4
+ */
5
+ /** The rights a person can exercise under Sections 11–14 of the Act. */
6
+ export type RequestType = "access" | "correction" | "erasure" | "grievance" | "nomination";
7
+ export declare const REQUEST_TYPES: readonly RequestType[];
8
+ export type RequestStatus = "open" | "resolved" | "rejected";
9
+ export interface RequestHistoryEntry {
10
+ at: string;
11
+ status: RequestStatus;
12
+ note?: string;
13
+ }
14
+ /** A rights request or grievance, from the moment it's raised until it's answered. */
15
+ export interface RightsRequest {
16
+ id: string;
17
+ subjectId: string;
18
+ type: RequestType;
19
+ status: RequestStatus;
20
+ openedAt: string;
21
+ /** When the answer is due. */
22
+ dueAt: string;
23
+ closedAt?: string;
24
+ /** What the person asked for: the correction, the nominee, the grievance text… */
25
+ details?: Record<string, unknown>;
26
+ /** Every status change, oldest first, so the response can be shown later. */
27
+ history: RequestHistoryEntry[];
28
+ }
29
+ /**
30
+ * One step of erasing a person's data.
31
+ * - `erase-fields`: set the listed fields to null in that table's rows for the person.
32
+ * - `delete-rows`: delete the person's rows in that table.
33
+ * - `processor-stop`: tell a processor to stop using the data for the ended purposes (Section 6(6)).
34
+ * - `processor-erase`: tell a processor to erase the data (Section 8(7)(b)).
35
+ */
36
+ export type TaskKind = "erase-fields" | "delete-rows" | "processor-stop" | "processor-erase";
37
+ /**
38
+ * - `pending`: waiting for its due date.
39
+ * - `running`: claimed by a runner.
40
+ * - `done`: carried out.
41
+ * - `failed`: the last attempt threw; retried on the next run (up to 5 attempts).
42
+ * - `manual`: needs a person, e.g. a processor with no `erase` hook. Mark it done when handled.
43
+ */
44
+ export type TaskStatus = "pending" | "running" | "done" | "failed" | "manual";
45
+ export interface ErasureTask {
46
+ id: string;
47
+ subjectId: string;
48
+ /** Why it exists: `"withdrawal"`, `"account-deletion"` or `"erasure-request"`. */
49
+ reason: string;
50
+ kind: TaskKind;
51
+ /** Key in `config.data`, for table tasks. */
52
+ table?: string;
53
+ /** Field names (as in the data map), for `erase-fields`. */
54
+ fields?: string[];
55
+ /** Key in `config.processors`, for processor tasks. */
56
+ processor?: string;
57
+ /** Purposes that ended, for processor tasks. */
58
+ purposes?: string[];
59
+ createdAt: string;
60
+ /** Not run before this time. */
61
+ dueAt: string;
62
+ status: TaskStatus;
63
+ attempts: number;
64
+ claimedAt?: string;
65
+ doneAt?: string;
66
+ /** Rows changed, for table tasks. */
67
+ affected?: number;
68
+ /** Message from the last failure, for developers. */
69
+ lastError?: string;
70
+ /** Who or what completed a manual task. */
71
+ note?: string;
72
+ }
73
+ export interface RequestFilter {
74
+ subjectId?: string;
75
+ status?: RequestStatus;
76
+ }
77
+ export interface TaskFilter {
78
+ subjectId?: string;
79
+ status?: TaskStatus;
80
+ }
81
+ /** Storage for rights requests. */
82
+ export interface RequestStore {
83
+ insertRequest(request: RightsRequest): Promise<void>;
84
+ getRequest(id: string): Promise<RightsRequest | undefined>;
85
+ /** Replace a stored request. */
86
+ updateRequest(request: RightsRequest): Promise<void>;
87
+ /** Oldest first. */
88
+ listRequests(filter: RequestFilter): Promise<RightsRequest[]>;
89
+ }
90
+ /** Storage for erasure tasks. */
91
+ export interface TaskStore {
92
+ insertTasks(tasks: readonly ErasureTask[]): Promise<void>;
93
+ /**
94
+ * Tasks to run now: `pending` or `failed` (fewer than `maxAttempts`) with `dueAt <= now`, plus
95
+ * `running` tasks claimed before `staleBefore` (their runner died). Oldest due first.
96
+ */
97
+ dueTasks(input: {
98
+ now: string;
99
+ staleBefore: string;
100
+ maxAttempts: number;
101
+ limit: number;
102
+ }): Promise<ErasureTask[]>;
103
+ /**
104
+ * Atomically mark a due task as `running`. Returns false if another runner got it first, so the
105
+ * same task is never carried out twice at once.
106
+ */
107
+ claimTask(input: {
108
+ id: string;
109
+ now: string;
110
+ staleBefore: string;
111
+ maxAttempts: number;
112
+ }): Promise<boolean>;
113
+ /** Replace a stored task. */
114
+ updateTask(task: ErasureTask): Promise<void>;
115
+ getTask(id: string): Promise<ErasureTask | undefined>;
116
+ /** Oldest due first. */
117
+ listTasks(filter: TaskFilter): Promise<ErasureTask[]>;
118
+ }
119
+ /** Whether a task can be picked up by a runner right now. */
120
+ export declare function isRunnable(task: ErasureTask, { now, staleBefore, maxAttempts }: {
121
+ now: string;
122
+ staleBefore: string;
123
+ maxAttempts: number;
124
+ }): boolean;
@@ -0,0 +1,47 @@
1
+ import type { DpdpConfig } from "./config.js";
2
+ import type { DataAccess } from "./data-access.js";
3
+ import type { ErasurePlan } from "./erasure.js";
4
+ import type { ErasureTask, TaskStore } from "./records.js";
5
+ /** What a processor hook is told. */
6
+ export interface ProcessorHookInput {
7
+ subjectId: string;
8
+ /** Purposes that ended. */
9
+ purposes: string[];
10
+ /** `"withdrawal"`, `"account-deletion"` or `"erasure-request"`. */
11
+ reason: string;
12
+ }
13
+ /**
14
+ * How to reach a third party you shared data with. A hook should call their API (or open a ticket).
15
+ * Without a hook the task becomes `manual`, for a person to handle and mark done.
16
+ */
17
+ export interface ProcessorHooks {
18
+ /** Stop using the person's data for the ended purposes (Section 6(6)). */
19
+ stop?: (input: ProcessorHookInput) => Promise<void> | void;
20
+ /** Erase the person's data (Section 8(7)(b)). */
21
+ erase?: (input: ProcessorHookInput) => Promise<void> | void;
22
+ }
23
+ export interface RunReport {
24
+ done: ErasureTask[];
25
+ failed: ErasureTask[];
26
+ manual: ErasureTask[];
27
+ }
28
+ export declare const MAX_ATTEMPTS = 5;
29
+ /** A `running` task claimed longer ago than this is assumed abandoned and picked up again. */
30
+ export declare const STALE_AFTER_MS: number;
31
+ /**
32
+ * Turn an erasure plan into dated tasks. Nothing is erased before the person's data has been kept
33
+ * for `config.minimumRetention` (Rule 8(3)), and legal holds wait for their own period. Those
34
+ * periods count from now, the time the plan is scheduled, which is never earlier than the last
35
+ * processing, so data is kept at least as long as the law requires.
36
+ */
37
+ export declare function tasksFromPlan(config: DpdpConfig<string>, plan: ErasurePlan, now: string): ErasureTask[];
38
+ export interface RunInput {
39
+ config: DpdpConfig<string>;
40
+ store: TaskStore;
41
+ data: DataAccess | undefined;
42
+ processors: Record<string, ProcessorHooks>;
43
+ now: string;
44
+ limit: number;
45
+ }
46
+ /** Carry out every due task once. Safe to run from several processes at the same time. */
47
+ export declare function runDueTasks(input: RunInput): Promise<RunReport>;