@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/README.md +42 -0
- package/dist/context.d.ts +46 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +123 -0
- package/dist/http.d.ts +2 -0
- package/dist/http.d.ts.map +1 -1
- package/dist/http.js +3 -1
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -0
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +1425 -0
- package/dist/types.d.ts +314 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/context.ts +161 -0
- package/src/http.ts +4 -1
- package/src/index.ts +8 -0
- package/src/released.ts +1426 -0
- package/src/types.ts +288 -0
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);
|