@deliverd/sdk 0.25.0 → 0.26.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 (51) hide show
  1. package/README.md +82 -3
  2. package/dist/adapters/index.d.ts +4 -0
  3. package/dist/adapters/index.d.ts.map +1 -1
  4. package/dist/adapters/index.js +2 -0
  5. package/dist/adapters/mastra.d.ts +81 -0
  6. package/dist/adapters/mastra.d.ts.map +1 -0
  7. package/dist/adapters/mastra.js +54 -0
  8. package/dist/adapters/muse-spark.d.ts +79 -0
  9. package/dist/adapters/muse-spark.d.ts.map +1 -0
  10. package/dist/adapters/muse-spark.js +59 -0
  11. package/dist/adapters/shared.d.ts +2 -1
  12. package/dist/adapters/shared.d.ts.map +1 -1
  13. package/dist/data-screen.d.ts +233 -0
  14. package/dist/data-screen.d.ts.map +1 -0
  15. package/dist/data-screen.js +389 -0
  16. package/dist/dev.d.ts.map +1 -1
  17. package/dist/dev.js +42 -2
  18. package/dist/governance.d.ts +94 -0
  19. package/dist/governance.d.ts.map +1 -0
  20. package/dist/governance.js +166 -0
  21. package/dist/index.d.ts +27 -0
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +30 -0
  24. package/dist/messages.d.ts +2 -0
  25. package/dist/messages.d.ts.map +1 -1
  26. package/dist/messages.js +8 -1
  27. package/dist/released.d.ts +1 -1
  28. package/dist/released.d.ts.map +1 -1
  29. package/dist/released.js +2184 -0
  30. package/dist/screen.d.ts +85 -0
  31. package/dist/screen.d.ts.map +1 -0
  32. package/dist/screen.js +69 -0
  33. package/dist/tasks.d.ts +38 -1
  34. package/dist/tasks.d.ts.map +1 -1
  35. package/dist/tasks.js +67 -0
  36. package/dist/types.d.ts +589 -3
  37. package/dist/types.d.ts.map +1 -1
  38. package/package.json +5 -5
  39. package/src/adapters/index.ts +11 -0
  40. package/src/adapters/mastra.ts +118 -0
  41. package/src/adapters/muse-spark.ts +147 -0
  42. package/src/adapters/shared.ts +2 -1
  43. package/src/data-screen.ts +533 -0
  44. package/src/dev.ts +45 -2
  45. package/src/governance.ts +204 -0
  46. package/src/index.ts +43 -0
  47. package/src/messages.ts +10 -1
  48. package/src/released.ts +2184 -0
  49. package/src/screen.ts +144 -0
  50. package/src/tasks.ts +88 -0
  51. package/src/types.ts +577 -3
@@ -0,0 +1,204 @@
1
+ import type { HttpClient } from "./http.js";
2
+ import { listOrCollect, type PageOf } from "./paging.js";
3
+ import type {
4
+ AiIncident,
5
+ AiIncidentDetail,
6
+ AiSystem,
7
+ AiSystemDetail,
8
+ AuthorityDecision,
9
+ CheckAuthorityInput,
10
+ CreateCustomFrameworkInput,
11
+ CustomFramework,
12
+ DraftedIncidentReport,
13
+ DraftIncidentReportInput,
14
+ FrameworkCatalogue,
15
+ FrameworkMapping,
16
+ FrameworkMappingInput,
17
+ GovernanceSummary,
18
+ GovernanceSummaryInput,
19
+ IctRegister,
20
+ ListIncidentsInput,
21
+ ModelChangeInput,
22
+ ModelChangeResult,
23
+ RegisterAiSystemInput,
24
+ ReportIncidentInput,
25
+ UpdateAiSystemInput,
26
+ } from "./types.js";
27
+
28
+ const enc = encodeURIComponent;
29
+
30
+ /**
31
+ * The organisation's register of AI systems. A governed task names one by
32
+ * `aiSystemId` instead of describing it again, and a change of model is
33
+ * recorded here so every task using it is reassessed.
34
+ */
35
+ export class AiSystems {
36
+ constructor(private readonly http: HttpClient) {}
37
+
38
+ /** The register, active and retired, or only one of them. */
39
+ async list(input: { status?: AiSystem["status"] } = {}, signal?: AbortSignal): Promise<AiSystem[]> {
40
+ const { aiSystems } = await this.http.request<{ aiSystems: AiSystem[] }>({
41
+ method: "GET",
42
+ path: "/ai-systems",
43
+ query: { status: input.status },
44
+ signal,
45
+ });
46
+ return aiSystems;
47
+ }
48
+
49
+ /** One system, and the governed tasks that name it. */
50
+ get(id: string, signal?: AbortSignal): Promise<AiSystemDetail> {
51
+ return this.http.request<AiSystemDetail>({ method: "GET", path: `/ai-systems/${enc(id)}`, signal });
52
+ }
53
+
54
+ /** Add a system to the register. Digests of its prompt and guardrails, never the text. */
55
+ register(input: RegisterAiSystemInput, signal?: AbortSignal): Promise<AiSystem> {
56
+ return this.http.request<AiSystem>({ method: "POST", path: "/ai-systems", body: input, signal });
57
+ }
58
+
59
+ /** Change a system's record. An agent may raise its risk but not lower it, and may not retire it. */
60
+ update(id: string, input: UpdateAiSystemInput, signal?: AbortSignal): Promise<AiSystem> {
61
+ return this.http.request<AiSystem>({ method: "PATCH", path: `/ai-systems/${enc(id)}`, body: input, signal });
62
+ }
63
+
64
+ /**
65
+ * Record a new provider, model, version, prompt or guardrails (Enterprise).
66
+ * Every governed task using the system is reassessed, and evidence of the
67
+ * old release stops counting.
68
+ */
69
+ recordModelChange(id: string, input: ModelChangeInput, signal?: AbortSignal): Promise<ModelChangeResult> {
70
+ return this.http.request<ModelChangeResult>({
71
+ method: "POST",
72
+ path: `/ai-systems/${enc(id)}/model-change`,
73
+ body: input,
74
+ signal,
75
+ });
76
+ }
77
+ }
78
+
79
+ /**
80
+ * AI incidents, and the DORA reports on the major ones. A high or critical
81
+ * incident closes its task's governance gate until a person resolves it in
82
+ * Deliverd; classifying it, and submitting a report, are a person's too.
83
+ */
84
+ export class Incidents {
85
+ constructor(private readonly http: HttpClient) {}
86
+
87
+ /** Report an incident against a governed task, an AI system, or both. */
88
+ report(input: ReportIncidentInput, signal?: AbortSignal): Promise<AiIncident> {
89
+ return this.http.request<AiIncident>({ method: "POST", path: "/governance/incidents", body: input, signal });
90
+ }
91
+
92
+ /** One incident: its DORA classification, its reports and their sign-off, and which report is due next. */
93
+ get(id: string, signal?: AbortSignal): Promise<AiIncidentDetail> {
94
+ return this.http.request<AiIncidentDetail>({ method: "GET", path: `/governance/incidents/${enc(id)}`, signal });
95
+ }
96
+
97
+ /**
98
+ * Newest first. With no `limit` this is every incident; with a `limit` it is
99
+ * one page of that size, and `listPage` hands back the cursor to continue from.
100
+ */
101
+ async list(input: ListIncidentsInput = {}, signal?: AbortSignal): Promise<AiIncident[]> {
102
+ return listOrCollect(input, (q) => this.listPage({ ...input, ...q }, signal));
103
+ }
104
+
105
+ /** One page, and the cursor to continue from — null when it is the end. */
106
+ listPage(input: ListIncidentsInput = {}, signal?: AbortSignal): Promise<PageOf<AiIncident>> {
107
+ return this.http.request<PageOf<AiIncident>>({
108
+ method: "GET",
109
+ path: "/governance/incidents",
110
+ query: { status: input.status, aiSystemId: input.aiSystemId, limit: input.limit, cursor: input.cursor },
111
+ signal,
112
+ });
113
+ }
114
+
115
+ /**
116
+ * Draft a DORA report on a major incident and put it to a person to sign
117
+ * off. Reports follow in order: initial, intermediate, final. Needs
118
+ * `approvals:write` as well as `tasks:write`.
119
+ */
120
+ draftReport(id: string, input: DraftIncidentReportInput, signal?: AbortSignal): Promise<DraftedIncidentReport> {
121
+ return this.http.request<DraftedIncidentReport>({
122
+ method: "POST",
123
+ path: `/governance/incidents/${enc(id)}/reports`,
124
+ body: input,
125
+ signal,
126
+ });
127
+ }
128
+ }
129
+
130
+ /**
131
+ * Compliance Mode across the organisation (Business and Enterprise): the AI
132
+ * system register, incidents, what an agent may do, the frameworks and the
133
+ * ICT register. A governed task's own governance is on `deliverd.tasks`.
134
+ *
135
+ * ```ts
136
+ * const { mode } = await deliverd.governance.checkAuthority({ action: "send" });
137
+ * if (mode === "denied") return;
138
+ * ```
139
+ *
140
+ * Every answer records governance and certifies nothing.
141
+ */
142
+ export class AiGovernance {
143
+ readonly aiSystems: AiSystems;
144
+ readonly incidents: Incidents;
145
+
146
+ constructor(private readonly http: HttpClient) {
147
+ this.aiSystems = new AiSystems(http);
148
+ this.incidents = new Incidents(http);
149
+ }
150
+
151
+ /**
152
+ * May this agent take this kind of action: on its own (`allowed`), only
153
+ * with a person's approval (`approval`), or not at all (`denied`)? By the
154
+ * organisation's policy and the agent's own, which can only be stricter
155
+ * (Enterprise). Reads; records nothing.
156
+ */
157
+ checkAuthority(input: CheckAuthorityInput, signal?: AbortSignal): Promise<AuthorityDecision> {
158
+ return this.http.request<AuthorityDecision>({
159
+ method: "POST",
160
+ path: "/governance/authority/evaluate",
161
+ body: input,
162
+ signal,
163
+ });
164
+ }
165
+
166
+ /** The frameworks the organisation can see: the built-in packs and its own, and which are applied. */
167
+ frameworks(signal?: AbortSignal): Promise<FrameworkCatalogue> {
168
+ return this.http.request<FrameworkCatalogue>({ method: "GET", path: "/governance/frameworks", signal });
169
+ }
170
+
171
+ /**
172
+ * How framework requirements map onto the common controls and, with
173
+ * `taskId`, how far that task's controls cover each one. A mapping, never
174
+ * a compliance verdict.
175
+ */
176
+ frameworkMapping(input: FrameworkMappingInput = {}, signal?: AbortSignal): Promise<FrameworkMapping> {
177
+ return this.http.request<FrameworkMapping>({
178
+ method: "GET",
179
+ path: "/governance/frameworks/mapping",
180
+ query: { taskId: input.taskId, framework: input.framework },
181
+ signal,
182
+ });
183
+ }
184
+
185
+ /** Draft the organisation's own framework (Enterprise). It adds nothing until a person publishes and applies it. */
186
+ createCustomFramework(input: CreateCustomFrameworkInput, signal?: AbortSignal): Promise<CustomFramework> {
187
+ return this.http.request<CustomFramework>({ method: "POST", path: "/governance/frameworks", body: input, signal });
188
+ }
189
+
190
+ /** The ICT third-party register: providers, contracts, the AI systems under each, gaps and concentration. */
191
+ ictRegister(signal?: AbortSignal): Promise<IctRegister> {
192
+ return this.http.request<IctRegister>({ method: "GET", path: "/governance/ict-register", signal });
193
+ }
194
+
195
+ /** The organisation's AI governance in counts, optionally narrowed. Never a compliance percentage. */
196
+ summary(input: GovernanceSummaryInput = {}, signal?: AbortSignal): Promise<GovernanceSummary> {
197
+ return this.http.request<GovernanceSummary>({
198
+ method: "GET",
199
+ path: "/governance/summary",
200
+ query: { ...input },
201
+ signal,
202
+ });
203
+ }
204
+ }
package/src/index.ts CHANGED
@@ -6,8 +6,10 @@ import { Reviews, type ReviewWaitOptions } from "./reviews.js";
6
6
  import { Collections, type CollectWaitOptions } from "./collections.js";
7
7
  import { Flows } from "./flows.js";
8
8
  import { Tasks } from "./tasks.js";
9
+ import { AiGovernance } from "./governance.js";
9
10
  import { Webhooks } from "./webhooks.js";
10
11
  import { WebhookEndpoints } from "./webhook-endpoints.js";
12
+ import { screen, Screened, type ScreenOptions } from "./screen.js";
11
13
  import { developmentFetch, type DevelopmentOptions } from "./dev.js";
12
14
  import { durationMs, type Duration } from "./duration.js";
13
15
  import { DeliverdError } from "./errors.js";
@@ -30,7 +32,22 @@ export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
30
32
  export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
31
33
  export { Flow, Flows, type FlowPrimitives } from "./flows.js";
32
34
  export { Task, Tasks } from "./tasks.js";
35
+ export { AiGovernance, AiSystems, Incidents } from "./governance.js";
33
36
  export { WebhookEndpoints } from "./webhook-endpoints.js";
37
+ export { Screened, type ScreenOptions } from "./screen.js";
38
+ export {
39
+ DATA_KINDS,
40
+ redact,
41
+ restore,
42
+ screenText,
43
+ summarise,
44
+ type DataKind,
45
+ type DetectedSpan,
46
+ type Redaction,
47
+ type ScreenFinding,
48
+ type ScreenTerm,
49
+ type SpanDetector,
50
+ } from "./data-screen.js";
34
51
  export {
35
52
  constructCallback,
36
53
  constructEvent,
@@ -148,6 +165,8 @@ export class Deliverd {
148
165
  readonly collections: Collections;
149
166
  readonly flows: Flows;
150
167
  readonly tasks: Tasks;
168
+ /** Compliance Mode across the organisation: AI systems, incidents, authority, frameworks, the ICT register. */
169
+ readonly governance: AiGovernance;
151
170
  readonly reports: Reports;
152
171
  readonly comments: Comments;
153
172
  readonly schedules: Schedules;
@@ -181,6 +200,7 @@ export class Deliverd {
181
200
  */
182
201
  this.flows = new Flows(this.http, this);
183
202
  this.tasks = new Tasks(this.http);
203
+ this.governance = new AiGovernance(this.http);
184
204
  this.reports = new Reports(this.http);
185
205
  this.comments = new Comments(this.http);
186
206
  this.schedules = new Schedules(this.http);
@@ -421,6 +441,29 @@ export class Deliverd {
421
441
  }
422
442
 
423
443
  /** Publish HTML to a secure URL. The sixth primitive, one call in. */
444
+ /**
445
+ * Check text before it goes to an AI model, and wait if a person has to decide.
446
+ *
447
+ * The detectors run here, so the text never leaves your machine: Deliverd is
448
+ * told only what was found, by kind, and answers from what your AI register
449
+ * approves that model to receive.
450
+ *
451
+ * ```ts
452
+ * const screened = await deliverd.screen(prompt, { aiSystemId: CLAIMS_MODEL });
453
+ * if (!screened.allowed) return screened.reasons;
454
+ * const answer = await model.generate(screened.text!);
455
+ * return screened.restore(answer);
456
+ * ```
457
+ *
458
+ * `allow` sends it as it is; `redact` gives you `screened.text` with the
459
+ * findings replaced by placeholders, and `restore()` puts them back in the
460
+ * answer; `ask` puts it to a person and waits; `deny` sends nothing. A net,
461
+ * not a guarantee: names in particular are not reliably found.
462
+ */
463
+ screen(text: string, options: ScreenOptions = {}): Promise<Screened> {
464
+ return screen(this.http, this.approvals, text, options, this.development);
465
+ }
466
+
424
467
  publish(input: PublishReportInput, signal?: AbortSignal): Promise<PublishResult> {
425
468
  return this.reports.publish(input, signal);
426
469
  }
package/src/messages.ts CHANGED
@@ -17,10 +17,19 @@ export interface Explanation {
17
17
  hint: string;
18
18
  }
19
19
 
20
+ /** Where somebody without an account makes one, counted against this package. */
21
+ export const SIGN_UP_URL =
22
+ "https://deliverd.dev/sign-up?utm_source=npm&utm_medium=package&utm_campaign=sdk&utm_content=no-api-key";
23
+
20
24
  export const EXPLANATIONS: Record<string, Explanation> = {
21
25
  no_api_key: {
22
26
  message: "No API key.",
23
- hint: "Set DELIVERD_API_KEY in your environment, or pass { apiKey } — or use { mode: \"development\" } to run without one.",
27
+ /*
28
+ * The one moment somebody has installed the package and has no account:
29
+ * the link is the way to get one, tagged so a sign-up from here is
30
+ * counted against this package (`SIGN_UP_URL`, `packaging.test.ts`).
31
+ */
32
+ hint: `Set DELIVERD_API_KEY in your environment, or pass { apiKey } — or use { mode: "development" } to run without one. No account yet? Setting up a free one hands you a key: ${SIGN_UP_URL}`,
24
33
  },
25
34
  auth_error: {
26
35
  message: "That credential was not accepted.",