@deliverd/sdk 0.15.0 → 0.17.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/src/reports.ts CHANGED
@@ -10,6 +10,7 @@ import type {
10
10
  ReportData,
11
11
  ScheduleSummary,
12
12
  SendResult,
13
+ ShareOptions,
13
14
  UpdateReportInput,
14
15
  EvidencePack,
15
16
  } from "./types.js";
@@ -122,12 +123,28 @@ export class Reports {
122
123
  });
123
124
  }
124
125
 
125
- /** Grant people, teams or groups access. Filing is not access; this is. */
126
- async share(idOrSlug: string, audience: unknown, signal?: AbortSignal): Promise<unknown[]> {
126
+ /**
127
+ * Grant people, teams or groups access. Filing is not access; this is.
128
+ *
129
+ * `{ capability: "comment" }` lets them comment as well as read; leave it
130
+ * out for view. A signal in third place, as before options existed, still
131
+ * works.
132
+ */
133
+ async share(
134
+ idOrSlug: string,
135
+ audience: unknown,
136
+ options?: ShareOptions | AbortSignal,
137
+ signal?: AbortSignal
138
+ ): Promise<unknown[]> {
139
+ if (options instanceof AbortSignal) {
140
+ signal = options;
141
+ options = undefined;
142
+ }
143
+ const capability = options?.capability;
127
144
  const { granted } = await this.http.request<{ granted: unknown[] }>({
128
145
  method: "POST",
129
146
  path: `/reports/${encodeURIComponent(idOrSlug)}/share`,
130
- body: { audience },
147
+ body: capability ? { audience, capability } : { audience },
131
148
  signal,
132
149
  });
133
150
  return granted;
package/src/tasks.ts CHANGED
@@ -6,12 +6,16 @@ import type {
6
6
  ApplySideTaskInput,
7
7
  CancelTaskInput,
8
8
  CompleteTaskInput,
9
+ ControlThresholds,
9
10
  CreateSideTaskInput,
10
11
  CreateTaskInput,
11
12
  DecisionApproval,
13
+ Governance,
14
+ GovernanceGateCheck,
12
15
  LinkTasksInput,
13
16
  ListTasksInput,
14
17
  RequestDecisionApprovalInput,
18
+ SubmitEvidenceInput,
15
19
  TaskContext,
16
20
  TaskData,
17
21
  TaskFinding,
@@ -36,6 +40,12 @@ import type {
36
40
  *
37
41
  * Nothing here asks a person anything by itself. A decision is recorded as a
38
42
  * suggestion, and `requestDecisionApproval()` is how one is put to somebody.
43
+ *
44
+ * A governed task (Compliance Mode, Business and Enterprise) also has
45
+ * controls, evidence and a gate: `submitEvidence()` records what a run
46
+ * measured, or a tool's own report, and `checkGovernanceGate()` says whether
47
+ * the work may proceed. Thresholds are a person's to set; an agent's key is
48
+ * refused, so whatever submits the results does not decide what passes.
39
49
  */
40
50
 
41
51
  const enc = encodeURIComponent;
@@ -194,6 +204,26 @@ export class Task {
194
204
  signal,
195
205
  });
196
206
  }
207
+
208
+ /** Its governance: controls, their thresholds and scores, evidence, readiness and the gate. */
209
+ governance(signal?: AbortSignal): Promise<Governance> {
210
+ return new Tasks(this.http).governance(this.data.id, signal);
211
+ }
212
+
213
+ /** Record evidence for the controls it speaks to: a link, what a run measured, or a tool's own report. */
214
+ submitEvidence(input: SubmitEvidenceInput, signal?: AbortSignal): Promise<Governance> {
215
+ return new Tasks(this.http).submitEvidence(this.data.id, input, signal);
216
+ }
217
+
218
+ /** Whether the governed work may proceed. Ask before deploying, sending or acting on the result. */
219
+ checkGovernanceGate(options: { action?: string } = {}, signal?: AbortSignal): Promise<GovernanceGateCheck> {
220
+ return new Tasks(this.http).checkGovernanceGate(this.data.id, options, signal);
221
+ }
222
+
223
+ /** Set what a control's scored evidence must meet, or clear it with `null`. A person's key only. */
224
+ setThresholds(control: string, thresholds: ControlThresholds | null, signal?: AbortSignal): Promise<Governance> {
225
+ return new Tasks(this.http).setThresholds(this.data.id, control, thresholds, signal);
226
+ }
197
227
  }
198
228
 
199
229
  export class Tasks {
@@ -309,4 +339,48 @@ export class Tasks {
309
339
  link(id: string, input: LinkTasksInput, signal?: AbortSignal): Promise<TaskLinkResult> {
310
340
  return this.http.request<TaskLinkResult>({ method: "POST", path: `/tasks/${enc(id)}/links`, body: input, signal });
311
341
  }
342
+
343
+ /** A governed task's governance: controls, their thresholds and scores, evidence, readiness and the gate. */
344
+ governance(id: string, signal?: AbortSignal): Promise<Governance> {
345
+ return this.http.request<Governance>({ method: "GET", path: `/tasks/${enc(id)}/governance`, signal });
346
+ }
347
+
348
+ /**
349
+ * Record evidence for a governed task and the controls it speaks to. For an
350
+ * eval or red-team run, send what it measured as `results`, or the tool's
351
+ * own `report` and let the server read it. A control with thresholds is met
352
+ * only when its newest scored evidence meets them. Called on a side task,
353
+ * it belongs to the objective and remembers where it came from.
354
+ */
355
+ submitEvidence(id: string, input: SubmitEvidenceInput, signal?: AbortSignal): Promise<Governance> {
356
+ return this.http.request<Governance>({ method: "POST", path: `/tasks/${enc(id)}/governance/evidence`, body: input, signal });
357
+ }
358
+
359
+ /**
360
+ * Whether governed work may proceed: `allowed`, what is missing, what else
361
+ * blocks it, and the `scores` of each control with thresholds. With
362
+ * `action` (Enterprise), also whether this agent may take that kind of action.
363
+ */
364
+ checkGovernanceGate(id: string, options: { action?: string } = {}, signal?: AbortSignal): Promise<GovernanceGateCheck> {
365
+ return this.http.request<GovernanceGateCheck>({
366
+ method: "GET",
367
+ path: `/tasks/${enc(id)}/governance/gate`,
368
+ query: { action: options.action },
369
+ signal,
370
+ });
371
+ }
372
+
373
+ /**
374
+ * Set what a control's scored evidence must meet, or clear it with `null`.
375
+ * A person's key only: an agent's is refused (`not_permitted`), because
376
+ * whatever submits the results must not also decide what passes.
377
+ */
378
+ setThresholds(id: string, control: string, thresholds: ControlThresholds | null, signal?: AbortSignal): Promise<Governance> {
379
+ return this.http.request<Governance>({
380
+ method: "PUT",
381
+ path: `/tasks/${enc(id)}/governance/controls/${enc(control)}/thresholds`,
382
+ body: { thresholds },
383
+ signal,
384
+ });
385
+ }
312
386
  }
package/src/types.ts CHANGED
@@ -612,6 +612,18 @@ export interface SendResult {
612
612
  alreadyHadAccess: string[];
613
613
  }
614
614
 
615
+ /**
616
+ * What a share lets its audience do. `"view"` is the default.
617
+ *
618
+ * "Can manage", which lets someone share the report on, is not here: it is a
619
+ * person's decision, made in the app, and the API refuses it from a key.
620
+ */
621
+ export type ShareCapability = "view" | "comment";
622
+
623
+ export interface ShareOptions {
624
+ capability?: ShareCapability;
625
+ }
626
+
615
627
  /* ── Schedules ───────────────────────────────────────────────────────────── */
616
628
 
617
629
  /**
@@ -1510,6 +1522,207 @@ export interface GovernanceProfileInput {
1510
1522
  jurisdictions?: string[];
1511
1523
  }
1512
1524
 
1525
+ /*
1526
+ * Compliance Mode: a governed task's controls, the evidence that satisfies
1527
+ * them, and the gate. Evidence can carry what a run measured; a control with
1528
+ * thresholds (set by a person) is met only when the newest evidence with
1529
+ * results meets them.
1530
+ */
1531
+
1532
+ /** What a piece of evidence is. */
1533
+ export type EvidenceType =
1534
+ | "assessment"
1535
+ | "test_result"
1536
+ | "approval"
1537
+ | "decision"
1538
+ | "policy"
1539
+ | "risk_assessment"
1540
+ | "security_review"
1541
+ | "privacy_review"
1542
+ | "data_assessment"
1543
+ | "model_evaluation"
1544
+ | "human_review"
1545
+ | "incident"
1546
+ | "mitigation"
1547
+ | "external_document"
1548
+ | "system_log"
1549
+ | "execution_receipt"
1550
+ | "red_team";
1551
+
1552
+ /** One thing an evaluation, test suite or red-team run measured. */
1553
+ export interface EvidenceResult {
1554
+ /** As the tool names it — `pass_rate`, `attack_success_rate` — so a threshold can name it too. */
1555
+ metric: string;
1556
+ value: number;
1557
+ /** The tool's own verdict on this result, where it gives one. */
1558
+ passed?: boolean;
1559
+ /** How serious a failure of this result is. */
1560
+ severity?: ApprovalRisk;
1561
+ /** A grouping the tool gives it: a red-team plugin, a risk category. */
1562
+ category?: string;
1563
+ dataset?: string;
1564
+ /** The trace or row it can be inspected at. https. */
1565
+ url?: string;
1566
+ }
1567
+
1568
+ /** The run a set of results came from. */
1569
+ export interface EvidenceRun {
1570
+ tool: string;
1571
+ runId?: string;
1572
+ name?: string;
1573
+ /** The run in the tool, for a reviewer to open. https. */
1574
+ url?: string;
1575
+ startedAt?: string;
1576
+ }
1577
+
1578
+ /** The tools whose own report the server reads. `deliverd` is a results file in `EvidenceResult` shape. */
1579
+ export type EvidenceReportFormat = "deliverd" | "promptfoo" | "inspect" | "garak" | "weave" | "braintrust" | "junit";
1580
+
1581
+ export interface SubmitEvidenceInput {
1582
+ type: EvidenceType;
1583
+ title: string;
1584
+ /** What it shows, for a reviewer. */
1585
+ description?: string;
1586
+ /** An https link to it. */
1587
+ url?: string;
1588
+ /** The controls it speaks to; one item may satisfy several. */
1589
+ controls?: string[];
1590
+ /** The finding in this task it rests on. */
1591
+ findingId?: string;
1592
+ /** What was measured. */
1593
+ results?: EvidenceResult[];
1594
+ run?: EvidenceRun;
1595
+ /** A tool's own report, as it wrote it, read by the server into results. Instead of `results`. Up to 4 MB. */
1596
+ report?: EvidenceReport;
1597
+ }
1598
+
1599
+ export interface EvidenceReport {
1600
+ format: EvidenceReportFormat;
1601
+ content: string;
1602
+ }
1603
+
1604
+ export interface ThresholdRule {
1605
+ metric: string;
1606
+ comparator: ">=" | ">" | "<=" | "<" | "==";
1607
+ value: number;
1608
+ }
1609
+
1610
+ /** What a control's scored evidence must meet. Set by a person; an agent's key is refused. */
1611
+ export interface ControlThresholds {
1612
+ rules: ThresholdRule[];
1613
+ /** Fail on any result the tool marked failed at this severity or above. */
1614
+ failOnSeverity: ApprovalRisk | null;
1615
+ }
1616
+
1617
+ /** What the newest scored evidence came to, against a control's thresholds. */
1618
+ export interface ControlScores {
1619
+ passed: boolean;
1620
+ reason: string;
1621
+ evidenceId: string;
1622
+ }
1623
+
1624
+ export interface GovernanceControl {
1625
+ key: string;
1626
+ title: string;
1627
+ family: string;
1628
+ /** How it is satisfied: by the profile, by evidence, or by an approval. */
1629
+ kind: "profile" | "evidence" | "approval";
1630
+ /** The organisation's own control rather than a common one. */
1631
+ custom: boolean;
1632
+ status: "outstanding" | "satisfied" | "waived";
1633
+ required: boolean;
1634
+ /** Pieces of evidence that count towards it. */
1635
+ evidence: number;
1636
+ thresholds: ControlThresholds | null;
1637
+ thresholdsSetBy: string | null;
1638
+ scores: ControlScores | null;
1639
+ /** The framework requirements that ask for it. */
1640
+ sources: GovernanceControlSource[];
1641
+ }
1642
+
1643
+ export interface GovernanceControlSource {
1644
+ framework: string;
1645
+ version: string;
1646
+ ref: string;
1647
+ }
1648
+
1649
+ export interface GovernanceEvidence {
1650
+ id: string;
1651
+ type: EvidenceType;
1652
+ title: string;
1653
+ description: string;
1654
+ url: string | null;
1655
+ controls: string[];
1656
+ results: EvidenceResult[] | null;
1657
+ run: EvidenceRun | null;
1658
+ createdByLabel: string;
1659
+ createdAt: string;
1660
+ }
1661
+
1662
+ export interface GovernanceReadiness {
1663
+ required: number;
1664
+ done: number;
1665
+ missing: string[];
1666
+ /** Controls satisfied or waived, of those required. Never a legal claim. */
1667
+ percent: number;
1668
+ }
1669
+
1670
+ export interface GovernanceBlocker {
1671
+ kind: string;
1672
+ message: string;
1673
+ id?: string;
1674
+ }
1675
+
1676
+ export interface GovernanceGateScore {
1677
+ control: string;
1678
+ passed: boolean;
1679
+ reason: string;
1680
+ evidenceId: string | null;
1681
+ }
1682
+
1683
+ /** Whether governed work may proceed. `allowed: false` names what stands in the way. */
1684
+ export interface GovernanceGateCheck {
1685
+ taskId: string;
1686
+ allowed: boolean;
1687
+ reason: string;
1688
+ missingControls: string[];
1689
+ blockers: GovernanceBlocker[];
1690
+ /** Each required control with thresholds, and why its newest run passed or failed. */
1691
+ scores: GovernanceGateScore[];
1692
+ readiness: GovernanceReadiness;
1693
+ }
1694
+
1695
+ export interface GovernanceFramework {
1696
+ key: string;
1697
+ name: string;
1698
+ version: string;
1699
+ applies: boolean;
1700
+ covered: number;
1701
+ applicable: number;
1702
+ }
1703
+
1704
+ /** A governed task's governance: its profile, controls, evidence, readiness and gate. */
1705
+ export interface Governance {
1706
+ taskId: string;
1707
+ title: string;
1708
+ url: string;
1709
+ profile: GovernanceProfileInput;
1710
+ controls: GovernanceControl[];
1711
+ evidence: GovernanceEvidence[];
1712
+ readiness: GovernanceReadiness;
1713
+ gate: GovernanceGate;
1714
+ frameworks: GovernanceFramework[];
1715
+ /** That this records governance and certifies nothing. */
1716
+ statement: string;
1717
+ }
1718
+
1719
+ export interface GovernanceGate {
1720
+ allowed: boolean;
1721
+ reason: string;
1722
+ missingControls: string[];
1723
+ blockers: GovernanceBlocker[];
1724
+ }
1725
+
1513
1726
  export interface ListTasksInput {
1514
1727
  /** A status, or `active` for anything not completed or cancelled. */
1515
1728
  status?: TaskStatus | "active";