@deliverd/sdk 0.27.0 → 0.28.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/context.ts ADDED
@@ -0,0 +1,161 @@
1
+ import type { HttpClient } from "./http.js";
2
+ import type {
3
+ ContextGiven,
4
+ DraftPlaybookInput,
5
+ EditKnowledgeInput,
6
+ ExportKnowledgeInput,
7
+ ImportedKnowledge,
8
+ ImportKnowledgeInput,
9
+ KnowledgeDetail,
10
+ KnowledgeEntryData,
11
+ KnowledgeExport,
12
+ KnowledgeSearchResult,
13
+ PlaybookData,
14
+ PlaybookDetail,
15
+ PlaybookSummary,
16
+ PromoteFindingInput,
17
+ ProposedKnowledge,
18
+ ProposeKnowledgeInput,
19
+ RequestPlaybookApprovalInput,
20
+ SearchKnowledgeInput,
21
+ StartedPlaybook,
22
+ StartPlaybookInput,
23
+ } from "./types.js";
24
+
25
+ /**
26
+ * Context: what your agents know, and how the job gets done.
27
+ *
28
+ * Knowledge is the organisation's, not any one agent's: an agent proposes an
29
+ * entry, a person confirms it in Deliverd, and every agent after that reads
30
+ * it, through this SDK, the MCP tools, or an AGENTS.md exported from it. The
31
+ * export is Markdown and imports back, so none of it is locked to a tool.
32
+ *
33
+ * A playbook is a written-down job: steps, each with the rule that applies
34
+ * before it acts (a gate, an approval, a review). Running one starts an
35
+ * objective with a side task per step. A person puts a playbook in force; an
36
+ * agent's key can draft one and run one, never publish it, and never confirm
37
+ * knowledge.
38
+ */
39
+
40
+ const enc = encodeURIComponent;
41
+
42
+ export class Knowledge {
43
+ constructor(private readonly http: HttpClient) {}
44
+
45
+ /** Ranked by relevance to `q`; confirmed entries unless `status` says otherwise. */
46
+ search(input: SearchKnowledgeInput = {}, signal?: AbortSignal): Promise<KnowledgeSearchResult> {
47
+ return this.http.request<KnowledgeSearchResult>({
48
+ method: "GET",
49
+ path: "/knowledge",
50
+ query: { q: input.q, kind: input.kind, status: input.status, workspaceId: input.workspaceId, flowId: input.flowId, limit: input.limit },
51
+ signal,
52
+ });
53
+ }
54
+
55
+ /** One entry, with the versions before and after it. */
56
+ get(id: string, signal?: AbortSignal): Promise<KnowledgeDetail> {
57
+ return this.http.request<KnowledgeDetail>({ method: "GET", path: `/knowledge/${enc(id)}`, signal });
58
+ }
59
+
60
+ /** Propose an entry. It is a proposal until a person confirms it. */
61
+ propose(input: ProposeKnowledgeInput, signal?: AbortSignal): Promise<ProposedKnowledge> {
62
+ return this.http.request<ProposedKnowledge>({ method: "POST", path: "/knowledge", body: input, signal });
63
+ }
64
+
65
+ /** Change a proposal you made. A confirmed entry is changed by proposing a revision (`supersedesId`). */
66
+ edit(id: string, input: EditKnowledgeInput, signal?: AbortSignal): Promise<KnowledgeEntryData> {
67
+ return this.http.request<KnowledgeEntryData>({ method: "PATCH", path: `/knowledge/${enc(id)}`, body: input, signal });
68
+ }
69
+
70
+ /** Propose a task's finding as knowledge, keeping where it came from. */
71
+ promoteFinding(taskId: string, findingId: string, input: PromoteFindingInput = {}, signal?: AbortSignal): Promise<ProposedKnowledge> {
72
+ return this.http.request<ProposedKnowledge>({
73
+ method: "POST",
74
+ path: `/tasks/${enc(taskId)}/findings/${enc(findingId)}/knowledge`,
75
+ body: input,
76
+ signal,
77
+ });
78
+ }
79
+
80
+ /** Bring in a Deliverd export or a notes file such as AGENTS.md. Each heading becomes a proposed entry. */
81
+ import(input: ImportKnowledgeInput, signal?: AbortSignal): Promise<ImportedKnowledge> {
82
+ return this.http.request<ImportedKnowledge>({ method: "POST", path: "/knowledge/import", body: input, signal });
83
+ }
84
+
85
+ /** Everything you may see, as Markdown that imports back. */
86
+ exportMarkdown(input: ExportKnowledgeInput = {}, signal?: AbortSignal): Promise<string> {
87
+ return this.http.request<string>({
88
+ method: "GET",
89
+ path: "/knowledge/export",
90
+ query: { format: "markdown", status: input.status, workspaceId: input.workspaceId },
91
+ responseType: "text",
92
+ signal,
93
+ });
94
+ }
95
+
96
+ /** The same, as JSON. */
97
+ exportJson(input: ExportKnowledgeInput = {}, signal?: AbortSignal): Promise<KnowledgeExport> {
98
+ return this.http.request<KnowledgeExport>({
99
+ method: "GET",
100
+ path: "/knowledge/export",
101
+ query: { format: "json", status: input.status, workspaceId: input.workspaceId },
102
+ signal,
103
+ });
104
+ }
105
+
106
+ /** An AGENTS.md of the confirmed knowledge and the playbooks in force, for a tool that reads files. */
107
+ agentsMd(options: { workspaceId?: string } = {}, signal?: AbortSignal): Promise<string> {
108
+ return this.http.request<string>({
109
+ method: "GET",
110
+ path: "/knowledge/agents-md",
111
+ query: { workspaceId: options.workspaceId },
112
+ responseType: "text",
113
+ signal,
114
+ });
115
+ }
116
+
117
+ /** What a task and its side tasks were given, newest first: the record behind "what did it know?". */
118
+ async given(taskId: string, signal?: AbortSignal): Promise<ContextGiven[]> {
119
+ const out = await this.http.request<{ given: ContextGiven[] }>({ method: "GET", path: `/tasks/${enc(taskId)}/context-given`, signal });
120
+ return out.given;
121
+ }
122
+ }
123
+
124
+ export class Playbooks {
125
+ constructor(private readonly http: HttpClient) {}
126
+
127
+ /** One row per playbook: its newest version, and the version in force. */
128
+ async list(signal?: AbortSignal): Promise<PlaybookSummary[]> {
129
+ const out = await this.http.request<{ playbooks: PlaybookSummary[] }>({ method: "GET", path: "/playbooks", signal });
130
+ return out.playbooks;
131
+ }
132
+
133
+ get(id: string, signal?: AbortSignal): Promise<PlaybookDetail> {
134
+ return this.http.request<PlaybookDetail>({ method: "GET", path: `/playbooks/${enc(id)}`, signal });
135
+ }
136
+
137
+ /** Draft a new playbook. Nobody runs a draft until a person puts it in force. */
138
+ draft(input: DraftPlaybookInput, signal?: AbortSignal): Promise<PlaybookData> {
139
+ return this.http.request<PlaybookData>({ method: "POST", path: "/playbooks", body: input, signal });
140
+ }
141
+
142
+ /** Draft the next version of a playbook; the version in force keeps running until this one replaces it. */
143
+ draftVersion(id: string, input: DraftPlaybookInput, signal?: AbortSignal): Promise<PlaybookData> {
144
+ return this.http.request<PlaybookData>({ method: "POST", path: `/playbooks/${enc(id)}/versions`, body: input, signal });
145
+ }
146
+
147
+ /** Change a draft that has not been put to anybody. */
148
+ updateDraft(id: string, input: DraftPlaybookInput, signal?: AbortSignal): Promise<PlaybookData> {
149
+ return this.http.request<PlaybookData>({ method: "PATCH", path: `/playbooks/${enc(id)}`, body: input, signal });
150
+ }
151
+
152
+ /** Put a draft to people as a Deliverd approval. Approved, it goes in force. Needs `approvals:write` and `tasks:write`. */
153
+ requestApproval(id: string, input: RequestPlaybookApprovalInput = {}, signal?: AbortSignal): Promise<PlaybookData> {
154
+ return this.http.request<PlaybookData>({ method: "POST", path: `/playbooks/${enc(id)}/approval`, body: input, signal });
155
+ }
156
+
157
+ /** Run the version in force: an objective, and a side task per step. */
158
+ start(id: string, input: StartPlaybookInput = {}, signal?: AbortSignal): Promise<StartedPlaybook> {
159
+ return this.http.request<StartedPlaybook>({ method: "POST", path: `/playbooks/${enc(id)}/start`, body: input, signal });
160
+ }
161
+ }
package/src/http.ts CHANGED
@@ -43,6 +43,8 @@ interface RequestOptions {
43
43
  * knows how to derive.
44
44
  */
45
45
  idempotencyKey?: string;
46
+ /** `text` hands back the body as it came, for a route that returns a file. */
47
+ responseType?: "json" | "text";
46
48
  }
47
49
 
48
50
  const sleep = (ms: number, signal?: AbortSignal) =>
@@ -121,7 +123,7 @@ export class HttpClient {
121
123
  method: options.method,
122
124
  headers: {
123
125
  Authorization: `Bearer ${this.apiKey}`,
124
- Accept: "application/json",
126
+ Accept: options.responseType === "text" ? "text/markdown, application/json" : "application/json",
125
127
  "User-Agent": USER_AGENT,
126
128
  // One id per logical request, kept across retries: it is the
127
129
  // thing to quote when something went wrong, and generating it
@@ -143,6 +145,7 @@ export class HttpClient {
143
145
  if (response.status === 204) return undefined as T;
144
146
 
145
147
  const text = await response.text();
148
+ if (options.responseType === "text" && response.ok) return text as T;
146
149
  let json: unknown;
147
150
  try {
148
151
  json = text ? JSON.parse(text) : {};
package/src/index.ts CHANGED
@@ -6,6 +6,7 @@ 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 { Knowledge, Playbooks } from "./context.js";
9
10
  import { AiGovernance } from "./governance.js";
10
11
  import { Webhooks } from "./webhooks.js";
11
12
  import { DecisionTokens } from "./decision-token.js";
@@ -33,6 +34,7 @@ export { Review, Reviews, type ReviewWaitOptions } from "./reviews.js";
33
34
  export { Collection, Collections, type CollectWaitOptions } from "./collections.js";
34
35
  export { Flow, Flows, type FlowPrimitives } from "./flows.js";
35
36
  export { Task, Tasks } from "./tasks.js";
37
+ export { Knowledge, Playbooks } from "./context.js";
36
38
  export { AiGovernance, AiSystems, Incidents } from "./governance.js";
37
39
  export { WebhookEndpoints } from "./webhook-endpoints.js";
38
40
  export {
@@ -179,6 +181,10 @@ export class Deliverd {
179
181
  readonly collections: Collections;
180
182
  readonly flows: Flows;
181
183
  readonly tasks: Tasks;
184
+ /** What your agents know: proposed by agents, confirmed by people, exported to anywhere. */
185
+ readonly knowledge: Knowledge;
186
+ /** Jobs written down as steps, each with the rule that applies before it acts. */
187
+ readonly playbooks: Playbooks;
182
188
  /** Compliance Mode across the organisation: AI systems, incidents, authority, frameworks, the ICT register. */
183
189
  readonly governance: AiGovernance;
184
190
  readonly reports: Reports;
@@ -216,6 +222,8 @@ export class Deliverd {
216
222
  */
217
223
  this.flows = new Flows(this.http, this);
218
224
  this.tasks = new Tasks(this.http);
225
+ this.knowledge = new Knowledge(this.http);
226
+ this.playbooks = new Playbooks(this.http);
219
227
  this.governance = new AiGovernance(this.http);
220
228
  this.reports = new Reports(this.http);
221
229
  this.comments = new Comments(this.http);