@deliverd/sdk 0.8.2 → 0.9.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/LICENSE +21 -21
- package/README.md +654 -562
- package/dist/adapters/ai-sdk.d.ts +48 -0
- package/dist/adapters/ai-sdk.d.ts.map +1 -0
- package/dist/adapters/ai-sdk.js +12 -0
- package/dist/adapters/claude-agent-sdk.d.ts +55 -0
- package/dist/adapters/claude-agent-sdk.d.ts.map +1 -0
- package/dist/adapters/claude-agent-sdk.js +24 -0
- package/dist/adapters/index.d.ts +19 -0
- package/dist/adapters/index.d.ts.map +1 -0
- package/dist/adapters/index.js +13 -0
- package/dist/adapters/langgraph.d.ts +145 -0
- package/dist/adapters/langgraph.d.ts.map +1 -0
- package/dist/adapters/langgraph.js +69 -0
- package/dist/adapters/openai-agents.d.ts +68 -0
- package/dist/adapters/openai-agents.d.ts.map +1 -0
- package/dist/adapters/openai-agents.js +55 -0
- package/dist/adapters/shared.d.ts +91 -0
- package/dist/adapters/shared.d.ts.map +1 -0
- package/dist/adapters/shared.js +98 -0
- package/dist/approvals.d.ts +15 -1
- package/dist/approvals.d.ts.map +1 -1
- package/dist/approvals.js +19 -1
- package/dist/collections.d.ts +8 -0
- package/dist/collections.d.ts.map +1 -1
- package/dist/collections.js +11 -1
- package/dist/dev.d.ts +6 -0
- package/dist/dev.d.ts.map +1 -1
- package/dist/dev.js +11 -0
- package/dist/gates.d.ts.map +1 -1
- package/dist/gates.js +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/released.d.ts +1 -1
- package/dist/released.d.ts.map +1 -1
- package/dist/released.js +451 -0
- package/dist/reviews.d.ts +8 -0
- package/dist/reviews.d.ts.map +1 -1
- package/dist/reviews.js +11 -1
- package/dist/types.d.ts +73 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/webhooks.d.ts +15 -1
- package/dist/webhooks.d.ts.map +1 -1
- package/dist/webhooks.js +13 -0
- package/package.json +59 -55
- package/src/adapters/ai-sdk.ts +59 -0
- package/src/adapters/claude-agent-sdk.ts +90 -0
- package/src/adapters/index.ts +23 -0
- package/src/adapters/langgraph.ts +202 -0
- package/src/adapters/openai-agents.ts +112 -0
- package/src/adapters/shared.ts +179 -0
- package/src/approvals.ts +342 -322
- package/src/collections.ts +247 -236
- package/src/dev.ts +780 -761
- package/src/duration.ts +21 -21
- package/src/errors.ts +62 -62
- package/src/flows.ts +222 -222
- package/src/gates.ts +231 -230
- package/src/http.ts +217 -217
- package/src/index.ts +444 -443
- package/src/messages.ts +161 -161
- package/src/paging.ts +64 -64
- package/src/released.ts +2523 -2072
- package/src/reports.ts +490 -490
- package/src/reviews.ts +236 -225
- package/src/types.ts +921 -838
- package/src/webhooks.ts +117 -98
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { type ToolApprovalOptions } from "./shared.js";
|
|
2
|
+
/**
|
|
3
|
+
* The Vercel AI SDK: a person approves tool calls, through Deliverd.
|
|
4
|
+
*
|
|
5
|
+
* ```ts
|
|
6
|
+
* import { generateText } from "ai";
|
|
7
|
+
* import { Deliverd } from "@deliverd/sdk";
|
|
8
|
+
* import { deliverdToolApproval } from "@deliverd/sdk/adapters";
|
|
9
|
+
*
|
|
10
|
+
* const result = await generateText({
|
|
11
|
+
* model,
|
|
12
|
+
* tools: { refund, sendEmail, lookupOrder },
|
|
13
|
+
* toolApproval: deliverdToolApproval({
|
|
14
|
+
* deliverd: new Deliverd(),
|
|
15
|
+
* approvers: ["finance"],
|
|
16
|
+
* when: (tool) => tool === "refund" || tool === "sendEmail",
|
|
17
|
+
* }),
|
|
18
|
+
* prompt,
|
|
19
|
+
* });
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* `toolApproval` is the AI SDK's own approval hook on `generateText`,
|
|
23
|
+
* `streamText` and `ToolLoopAgent`; this function is one it accepts. A call
|
|
24
|
+
* that needs no person is `not-applicable`. One that does waits for Deliverd:
|
|
25
|
+
* `approved` runs it, `denied` hands the model the person's reason.
|
|
26
|
+
*
|
|
27
|
+
* Shapes follow `GenericToolApprovalFunction` and `ToolApprovalStatus` in
|
|
28
|
+
* `ai`'s type definitions (v7).
|
|
29
|
+
*/
|
|
30
|
+
/** The part of the AI SDK's approval call this adapter reads. */
|
|
31
|
+
export interface AiSdkApprovalCall {
|
|
32
|
+
toolCall: {
|
|
33
|
+
toolName: string;
|
|
34
|
+
toolCallId: string;
|
|
35
|
+
input: unknown;
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
export type AiSdkApprovalStatus = {
|
|
39
|
+
type: "not-applicable";
|
|
40
|
+
} | {
|
|
41
|
+
type: "approved";
|
|
42
|
+
reason?: string;
|
|
43
|
+
} | {
|
|
44
|
+
type: "denied";
|
|
45
|
+
reason?: string;
|
|
46
|
+
};
|
|
47
|
+
export declare function deliverdToolApproval(options: ToolApprovalOptions): (call: AiSdkApprovalCall) => Promise<AiSdkApprovalStatus>;
|
|
48
|
+
//# sourceMappingURL=ai-sdk.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/ai-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,mBAAmB,GAC3B,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAe3D"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import { askAboutCall } from "./shared.js";
|
|
2
|
+
export function deliverdToolApproval(options) {
|
|
3
|
+
return async ({ toolCall }) => {
|
|
4
|
+
if (options.when && !(await options.when(toolCall.toolName, toolCall.input))) {
|
|
5
|
+
return { type: "not-applicable" };
|
|
6
|
+
}
|
|
7
|
+
const outcome = await askAboutCall(toolCall.toolName, toolCall.input, `ai-sdk:${toolCall.toolCallId}`, options);
|
|
8
|
+
return outcome.allowed
|
|
9
|
+
? { type: "approved", reason: outcome.decidedBy ? `Approved by ${outcome.decidedBy}` : undefined }
|
|
10
|
+
: { type: "denied", reason: outcome.reason };
|
|
11
|
+
};
|
|
12
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { type ToolApprovalOptions } from "./shared.js";
|
|
2
|
+
/**
|
|
3
|
+
* The Claude Agent SDK: a person approves tool calls, through Deliverd.
|
|
4
|
+
*
|
|
5
|
+
* ```ts
|
|
6
|
+
* import { query } from "@anthropic-ai/claude-agent-sdk";
|
|
7
|
+
* import { Deliverd } from "@deliverd/sdk";
|
|
8
|
+
* import { deliverdCanUseTool } from "@deliverd/sdk/adapters";
|
|
9
|
+
*
|
|
10
|
+
* const deliverd = new Deliverd();
|
|
11
|
+
* for await (const message of query({
|
|
12
|
+
* prompt: "Tidy the release notes and publish them",
|
|
13
|
+
* options: {
|
|
14
|
+
* canUseTool: deliverdCanUseTool({
|
|
15
|
+
* deliverd,
|
|
16
|
+
* approvers: ["release-managers"],
|
|
17
|
+
* when: (tool) => tool === "Bash" || tool.startsWith("mcp__"),
|
|
18
|
+
* }),
|
|
19
|
+
* },
|
|
20
|
+
* })) { … }
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* A call that needs no person is allowed with its input unchanged. One that
|
|
24
|
+
* does waits for the decision, from the page, the email link, Slack or Teams:
|
|
25
|
+
* allowed, it runs; declined, the model is told why and told not to retry.
|
|
26
|
+
* The run's abort signal cancels the wait.
|
|
27
|
+
*
|
|
28
|
+
* Shapes follow `CanUseTool` and `PermissionResult` in
|
|
29
|
+
* `@anthropic-ai/claude-agent-sdk`'s `sdk.d.ts`.
|
|
30
|
+
*/
|
|
31
|
+
/** The options `canUseTool` receives that this adapter reads. */
|
|
32
|
+
export interface ClaudeCanUseToolContext {
|
|
33
|
+
signal: AbortSignal;
|
|
34
|
+
/** The tool call's id, which keeps a retried call from asking twice. */
|
|
35
|
+
toolUseID?: string;
|
|
36
|
+
}
|
|
37
|
+
export type ClaudePermissionResult = {
|
|
38
|
+
behavior: "allow";
|
|
39
|
+
updatedInput: Record<string, unknown>;
|
|
40
|
+
} | {
|
|
41
|
+
behavior: "deny";
|
|
42
|
+
message: string;
|
|
43
|
+
};
|
|
44
|
+
export type ClaudeCanUseTool = (toolName: string, input: Record<string, unknown>, context: ClaudeCanUseToolContext) => Promise<ClaudePermissionResult>;
|
|
45
|
+
export interface ClaudeToolApprovalOptions extends ToolApprovalOptions {
|
|
46
|
+
/**
|
|
47
|
+
* Fields of a tool's input the approver may correct before approving, per
|
|
48
|
+
* tool: `editable: (tool) => tool === "refund" ? ["amount"] : []`. The call
|
|
49
|
+
* then runs with what they approved — the Agent SDK's `updatedInput` —
|
|
50
|
+
* rather than with what the model proposed.
|
|
51
|
+
*/
|
|
52
|
+
editable?: (toolName: string, input: Record<string, unknown>) => string[];
|
|
53
|
+
}
|
|
54
|
+
export declare function deliverdCanUseTool(options: ClaudeToolApprovalOptions): ClaudeCanUseTool;
|
|
55
|
+
//# sourceMappingURL=claude-agent-sdk.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"claude-agent-sdk.d.ts","sourceRoot":"","sources":["../../src/adapters/claude-agent-sdk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,iEAAiE;AACjE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,WAAW,CAAC;IACpB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC5D;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C,MAAM,MAAM,gBAAgB,GAAG,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErC,MAAM,WAAW,yBAA0B,SAAQ,mBAAmB;IACpE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;CAC3E;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,gBAAgB,CAmBvF"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { askAboutCall } from "./shared.js";
|
|
2
|
+
export function deliverdCanUseTool(options) {
|
|
3
|
+
return async (toolName, input, context) => {
|
|
4
|
+
if (options.when && !(await options.when(toolName, input))) {
|
|
5
|
+
return { behavior: "allow", updatedInput: input };
|
|
6
|
+
}
|
|
7
|
+
const id = context.toolUseID ?? `${toolName}:${stableHash(input)}`;
|
|
8
|
+
const outcome = await askAboutCall(toolName, input, `claude-agent-sdk:${id}`, options, context.signal, options.editable?.(toolName, input));
|
|
9
|
+
// What was approved runs, which is the proposal unless a person corrected it.
|
|
10
|
+
return outcome.allowed
|
|
11
|
+
? { behavior: "allow", updatedInput: outcome.input ?? input }
|
|
12
|
+
: { behavior: "deny", message: outcome.reason };
|
|
13
|
+
};
|
|
14
|
+
}
|
|
15
|
+
/** A short, stable fingerprint of an input, for when no call id is given. */
|
|
16
|
+
function stableHash(value) {
|
|
17
|
+
const text = JSON.stringify(value) ?? "";
|
|
18
|
+
let h = 0x811c9dc5;
|
|
19
|
+
for (let i = 0; i < text.length; i++) {
|
|
20
|
+
h ^= text.charCodeAt(i);
|
|
21
|
+
h = Math.imul(h, 0x01000193);
|
|
22
|
+
}
|
|
23
|
+
return (h >>> 0).toString(16);
|
|
24
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deliverd inside the agent frameworks people already use: a person approves
|
|
3
|
+
* a tool call from their inbox, Slack or Teams, and the agent carries on.
|
|
4
|
+
*
|
|
5
|
+
* `@deliverd/sdk/adapters`, separate from the main entry so none of it is
|
|
6
|
+
* loaded unless it is used. No dependencies: each adapter matches its
|
|
7
|
+
* framework's hook by shape.
|
|
8
|
+
*/
|
|
9
|
+
export { deliverdCanUseTool } from "./claude-agent-sdk.js";
|
|
10
|
+
export type { ClaudeCanUseTool, ClaudeCanUseToolContext, ClaudePermissionResult, ClaudeToolApprovalOptions, } from "./claude-agent-sdk.js";
|
|
11
|
+
export { deliverdToolApproval } from "./ai-sdk.js";
|
|
12
|
+
export type { AiSdkApprovalCall, AiSdkApprovalStatus } from "./ai-sdk.js";
|
|
13
|
+
export { resolveInterruptions, runWithDeliverdApprovals } from "./openai-agents.js";
|
|
14
|
+
export type { OpenAiApprovalItem, OpenAiInterruptedResult } from "./openai-agents.js";
|
|
15
|
+
export { approveInGraph, resumeFromCallback } from "./langgraph.js";
|
|
16
|
+
export type { DeliverdInterruptValue, GraphApprovalRecord, GraphApprover, GraphDecision } from "./langgraph.js";
|
|
17
|
+
export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
|
|
18
|
+
export type { Approver, CallDescription, CallOutcome, ToolApprovalOptions } from "./shared.js";
|
|
19
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAChH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Deliverd inside the agent frameworks people already use: a person approves
|
|
3
|
+
* a tool call from their inbox, Slack or Teams, and the agent carries on.
|
|
4
|
+
*
|
|
5
|
+
* `@deliverd/sdk/adapters`, separate from the main entry so none of it is
|
|
6
|
+
* loaded unless it is used. No dependencies: each adapter matches its
|
|
7
|
+
* framework's hook by shape.
|
|
8
|
+
*/
|
|
9
|
+
export { deliverdCanUseTool } from "./claude-agent-sdk.js";
|
|
10
|
+
export { deliverdToolApproval } from "./ai-sdk.js";
|
|
11
|
+
export { resolveInterruptions, runWithDeliverdApprovals } from "./openai-agents.js";
|
|
12
|
+
export { approveInGraph, resumeFromCallback } from "./langgraph.js";
|
|
13
|
+
export { defaultDescription, DEFAULT_TOOL_EXPIRY } from "./shared.js";
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { type Duration } from "../duration.js";
|
|
2
|
+
import type { ApprovalFactor, ApprovalRisk, CallbackEnvelope, FieldChange } from "../types.js";
|
|
3
|
+
/**
|
|
4
|
+
* LangGraph: pause a graph on a person's decision, and wake it with a
|
|
5
|
+
* callback instead of a process waiting on it.
|
|
6
|
+
*
|
|
7
|
+
* Inside a node, instead of blocking on `deliverd.approve()`:
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { interrupt } from "@langchain/langgraph";
|
|
11
|
+
* import { approveInGraph } from "@deliverd/sdk/adapters";
|
|
12
|
+
*
|
|
13
|
+
* async function refund(state, config) {
|
|
14
|
+
* const decision = await approveInGraph(deliverd, {
|
|
15
|
+
* interrupt,
|
|
16
|
+
* threadId: config.configurable.thread_id,
|
|
17
|
+
* step: "refund",
|
|
18
|
+
* title: `Refund £${state.amount} to ${state.customer}`,
|
|
19
|
+
* approvers: ["finance"],
|
|
20
|
+
* callbackUrl: "https://agent.example.com/hooks/deliverd",
|
|
21
|
+
* });
|
|
22
|
+
* if (!decision.approved) return { refunded: false, reason: decision.note };
|
|
23
|
+
* …
|
|
24
|
+
* }
|
|
25
|
+
* ```
|
|
26
|
+
*
|
|
27
|
+
* And where the callback lands:
|
|
28
|
+
*
|
|
29
|
+
* ```ts
|
|
30
|
+
* import { Command } from "@langchain/langgraph";
|
|
31
|
+
* import { resumeFromCallback } from "@deliverd/sdk/adapters";
|
|
32
|
+
*
|
|
33
|
+
* const envelope = deliverd.webhooks.constructCallback(secret, rawBody, signature);
|
|
34
|
+
* const resume = resumeFromCallback(envelope);
|
|
35
|
+
* if (resume) await graph.invoke(new Command({ resume: resume.value }), { configurable: { thread_id: resume.threadId } });
|
|
36
|
+
* ```
|
|
37
|
+
*
|
|
38
|
+
* **Why it is safe to re-run.** LangGraph resumes a node from its first line.
|
|
39
|
+
* The request is keyed by `externalId` (`langgraph:<thread>:<step>`), so the
|
|
40
|
+
* second run finds the request the first one made rather than filing another,
|
|
41
|
+
* sees it settled, and returns without interrupting again. A resume that
|
|
42
|
+
* arrives early — before anyone decided — re-reads the request, finds it
|
|
43
|
+
* still pending and returns `approved: false, status: "pending"`: the
|
|
44
|
+
* decision is always Deliverd's record, never the resume value, so a stray
|
|
45
|
+
* resume can never approve anything.
|
|
46
|
+
*
|
|
47
|
+
* `interrupt` is passed in rather than imported, so this package keeps no
|
|
48
|
+
* dependency on LangGraph. Its signature follows `interrupt` in
|
|
49
|
+
* `@langchain/langgraph`'s type definitions.
|
|
50
|
+
*/
|
|
51
|
+
/** The parts of the Deliverd client this adapter uses. */
|
|
52
|
+
export interface GraphApprover {
|
|
53
|
+
approvals: {
|
|
54
|
+
findByExternalId(externalId: string): Promise<GraphApprovalRecord | null>;
|
|
55
|
+
create(input: {
|
|
56
|
+
title: string;
|
|
57
|
+
description?: string;
|
|
58
|
+
risk?: ApprovalRisk;
|
|
59
|
+
factors?: ApprovalFactor[];
|
|
60
|
+
approvers?: string[];
|
|
61
|
+
externalId: string;
|
|
62
|
+
expiresAt?: string;
|
|
63
|
+
callbackUrl?: string;
|
|
64
|
+
metadata?: Record<string, unknown>;
|
|
65
|
+
flowId?: string;
|
|
66
|
+
input?: Record<string, unknown>;
|
|
67
|
+
editableFields?: string[];
|
|
68
|
+
}): Promise<GraphApprovalRecord & {
|
|
69
|
+
callbackSecret: string | null;
|
|
70
|
+
}>;
|
|
71
|
+
};
|
|
72
|
+
}
|
|
73
|
+
/** The request as this adapter reads it back. */
|
|
74
|
+
export interface GraphApprovalRecord {
|
|
75
|
+
id: string;
|
|
76
|
+
status: string;
|
|
77
|
+
url: string;
|
|
78
|
+
note: string | null;
|
|
79
|
+
decidedBy: string | null;
|
|
80
|
+
approvedInput?: Record<string, unknown> | null;
|
|
81
|
+
changes?: FieldChange[];
|
|
82
|
+
}
|
|
83
|
+
export interface GraphDecision {
|
|
84
|
+
approved: boolean;
|
|
85
|
+
status: string;
|
|
86
|
+
note: string | null;
|
|
87
|
+
decidedBy: string | null;
|
|
88
|
+
approvalId: string;
|
|
89
|
+
url: string;
|
|
90
|
+
/**
|
|
91
|
+
* What to run with, when an `input` was sent and approved: with the
|
|
92
|
+
* approver's corrections. Null otherwise.
|
|
93
|
+
*/
|
|
94
|
+
input: Record<string, unknown> | null;
|
|
95
|
+
changes: FieldChange[];
|
|
96
|
+
}
|
|
97
|
+
/** What the graph is paused on, as `interrupt` receives it. */
|
|
98
|
+
export interface DeliverdInterruptValue {
|
|
99
|
+
deliverd: {
|
|
100
|
+
approvalId: string;
|
|
101
|
+
url: string;
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
export declare function approveInGraph(deliverd: GraphApprover, options: {
|
|
105
|
+
/** `interrupt` from `@langchain/langgraph`. */
|
|
106
|
+
interrupt: (value: DeliverdInterruptValue) => unknown;
|
|
107
|
+
/** The graph's thread: `config.configurable.thread_id`. */
|
|
108
|
+
threadId: string;
|
|
109
|
+
/** A name for this point in the graph, unique within the thread. No colons. */
|
|
110
|
+
step: string;
|
|
111
|
+
title: string;
|
|
112
|
+
description?: string;
|
|
113
|
+
risk?: ApprovalRisk;
|
|
114
|
+
factors?: ApprovalFactor[];
|
|
115
|
+
approvers?: string[];
|
|
116
|
+
/** Where Deliverd POSTs the decision; pair with `resumeFromCallback`. */
|
|
117
|
+
callbackUrl?: string;
|
|
118
|
+
/** How long the request stays open. Default a day. */
|
|
119
|
+
expiresIn?: Duration;
|
|
120
|
+
flowId?: string;
|
|
121
|
+
/** The arguments the node will run with, shown to the approver. */
|
|
122
|
+
input?: Record<string, unknown>;
|
|
123
|
+
/** Fields of `input` the approver may correct; the decision's `input` has them. */
|
|
124
|
+
editableFields?: string[];
|
|
125
|
+
/** Called once, when the request is first made, with the secret its callback is signed with. */
|
|
126
|
+
onCreated?: (created: {
|
|
127
|
+
approvalId: string;
|
|
128
|
+
url: string;
|
|
129
|
+
callbackSecret: string | null;
|
|
130
|
+
}) => void | Promise<void>;
|
|
131
|
+
}): Promise<GraphDecision>;
|
|
132
|
+
/**
|
|
133
|
+
* The thread to resume and the value to resume it with, from a verified
|
|
134
|
+
* callback. Null for a callback that is not about a graph's approval, and
|
|
135
|
+
* for a question — the graph stays paused until the request settles.
|
|
136
|
+
*/
|
|
137
|
+
export declare function resumeFromCallback(envelope: CallbackEnvelope): {
|
|
138
|
+
threadId: string;
|
|
139
|
+
step: string;
|
|
140
|
+
value: {
|
|
141
|
+
approvalId: string;
|
|
142
|
+
status: string;
|
|
143
|
+
};
|
|
144
|
+
} | null;
|
|
145
|
+
//# sourceMappingURL=langgraph.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"langgraph.d.ts","sourceRoot":"","sources":["../../src/adapters/langgraph.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import { durationMs } from "../duration.js";
|
|
2
|
+
/**
|
|
3
|
+
* Every graph request's `externalId` starts with this; the thread and step
|
|
4
|
+
* follow, and are what a callback is matched back to (callbacks carry the
|
|
5
|
+
* `externalId`, which is set by this adapter and nothing else).
|
|
6
|
+
*/
|
|
7
|
+
const PREFIX = "langgraph:";
|
|
8
|
+
export async function approveInGraph(deliverd, options) {
|
|
9
|
+
if (options.step.includes(":")) {
|
|
10
|
+
throw new Error(`step must not contain ":" (got "${options.step}"): it is how the thread is found again.`);
|
|
11
|
+
}
|
|
12
|
+
const externalId = `${PREFIX}${options.threadId}:${options.step}`;
|
|
13
|
+
let approval = await deliverd.approvals.findByExternalId(externalId);
|
|
14
|
+
if (!approval) {
|
|
15
|
+
const created = await deliverd.approvals.create({
|
|
16
|
+
title: options.title,
|
|
17
|
+
description: options.description,
|
|
18
|
+
risk: options.risk,
|
|
19
|
+
factors: options.factors,
|
|
20
|
+
approvers: options.approvers,
|
|
21
|
+
externalId,
|
|
22
|
+
expiresAt: new Date(Date.now() + durationMs(options.expiresIn ?? "24h")).toISOString(),
|
|
23
|
+
callbackUrl: options.callbackUrl,
|
|
24
|
+
metadata: { langgraph: { threadId: options.threadId, step: options.step } },
|
|
25
|
+
flowId: options.flowId,
|
|
26
|
+
input: options.input,
|
|
27
|
+
editableFields: options.editableFields,
|
|
28
|
+
});
|
|
29
|
+
await options.onCreated?.({ approvalId: created.id, url: created.url, callbackSecret: created.callbackSecret });
|
|
30
|
+
approval = created;
|
|
31
|
+
}
|
|
32
|
+
if (approval.status === "pending") {
|
|
33
|
+
// Pauses the graph on the first run. It returns only when the graph is
|
|
34
|
+
// resumed, and what it returns is not trusted: the request is re-read.
|
|
35
|
+
options.interrupt({ deliverd: { approvalId: approval.id, url: approval.url } });
|
|
36
|
+
approval = (await deliverd.approvals.findByExternalId(externalId)) ?? approval;
|
|
37
|
+
}
|
|
38
|
+
return {
|
|
39
|
+
approved: approval.status === "approved",
|
|
40
|
+
status: approval.status,
|
|
41
|
+
note: approval.note,
|
|
42
|
+
decidedBy: approval.decidedBy,
|
|
43
|
+
approvalId: approval.id,
|
|
44
|
+
url: approval.url,
|
|
45
|
+
input: approval.status === "approved" ? (approval.approvedInput ?? options.input ?? null) : null,
|
|
46
|
+
changes: approval.changes ?? [],
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* The thread to resume and the value to resume it with, from a verified
|
|
51
|
+
* callback. Null for a callback that is not about a graph's approval, and
|
|
52
|
+
* for a question — the graph stays paused until the request settles.
|
|
53
|
+
*/
|
|
54
|
+
export function resumeFromCallback(envelope) {
|
|
55
|
+
if (envelope.requestType !== "approval" || envelope.event === "approval.question")
|
|
56
|
+
return null;
|
|
57
|
+
const externalId = envelope.data.externalId;
|
|
58
|
+
if (typeof externalId !== "string" || !externalId.startsWith(PREFIX))
|
|
59
|
+
return null;
|
|
60
|
+
const rest = externalId.slice(PREFIX.length);
|
|
61
|
+
const cut = rest.lastIndexOf(":");
|
|
62
|
+
if (cut <= 0 || cut === rest.length - 1)
|
|
63
|
+
return null;
|
|
64
|
+
return {
|
|
65
|
+
threadId: rest.slice(0, cut),
|
|
66
|
+
step: rest.slice(cut + 1),
|
|
67
|
+
value: { approvalId: envelope.requestId, status: String(envelope.data.status ?? envelope.event.split(".")[1]) },
|
|
68
|
+
};
|
|
69
|
+
}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import { type ToolApprovalOptions } from "./shared.js";
|
|
2
|
+
/**
|
|
3
|
+
* The OpenAI Agents SDK: a person resolves the run's approval interruptions,
|
|
4
|
+
* through Deliverd.
|
|
5
|
+
*
|
|
6
|
+
* Mark the tools that need a person with `needsApproval: true` as usual; a run
|
|
7
|
+
* then stops with `result.interruptions`. Instead of building your own prompt:
|
|
8
|
+
*
|
|
9
|
+
* ```ts
|
|
10
|
+
* import { Agent, run } from "@openai/agents";
|
|
11
|
+
* import { Deliverd } from "@deliverd/sdk";
|
|
12
|
+
* import { runWithDeliverdApprovals } from "@deliverd/sdk/adapters";
|
|
13
|
+
*
|
|
14
|
+
* const result = await runWithDeliverdApprovals(
|
|
15
|
+
* (input) => run(agent, input),
|
|
16
|
+
* "Refund order 1042",
|
|
17
|
+
* { deliverd: new Deliverd(), approvers: ["finance"] }
|
|
18
|
+
* );
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* Each interruption becomes a request in Deliverd; approved ones are
|
|
22
|
+
* `state.approve(item)`, declined ones `state.reject(item, { message })` with
|
|
23
|
+
* the person's reason, and the run resumes from its state until nothing is
|
|
24
|
+
* waiting. `resolveInterruptions` does one round, for a loop you own.
|
|
25
|
+
*
|
|
26
|
+
* Shapes follow `RunToolApprovalItem`, `RunState.approve` / `reject` and
|
|
27
|
+
* `RunResult.interruptions` in `@openai/agents-core`'s type definitions.
|
|
28
|
+
*/
|
|
29
|
+
/** The part of a `RunToolApprovalItem` this adapter reads. */
|
|
30
|
+
export interface OpenAiApprovalItem {
|
|
31
|
+
name?: string;
|
|
32
|
+
arguments?: string;
|
|
33
|
+
rawItem?: {
|
|
34
|
+
callId?: string;
|
|
35
|
+
id?: string;
|
|
36
|
+
name?: string;
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
/** The part of a run result this adapter reads and resolves. */
|
|
40
|
+
export interface OpenAiInterruptedResult<Item extends OpenAiApprovalItem = OpenAiApprovalItem, State = unknown> {
|
|
41
|
+
interruptions: Item[];
|
|
42
|
+
state: State & {
|
|
43
|
+
approve(item: Item, options?: {
|
|
44
|
+
alwaysApprove?: boolean;
|
|
45
|
+
}): void;
|
|
46
|
+
reject(item: Item, options?: {
|
|
47
|
+
alwaysReject?: boolean;
|
|
48
|
+
message?: string;
|
|
49
|
+
}): void;
|
|
50
|
+
};
|
|
51
|
+
}
|
|
52
|
+
/** Ask about every interruption in a result, and record each answer on its state. */
|
|
53
|
+
export declare function resolveInterruptions<Item extends OpenAiApprovalItem>(result: OpenAiInterruptedResult<Item>, options: ToolApprovalOptions): Promise<{
|
|
54
|
+
approved: number;
|
|
55
|
+
rejected: number;
|
|
56
|
+
}>;
|
|
57
|
+
/**
|
|
58
|
+
* Run until nothing is waiting on a person.
|
|
59
|
+
*
|
|
60
|
+
* `runOnce` is your call to the SDK's `run(agent, input)`; it is called
|
|
61
|
+
* first with `input`, then with the result's state after each round of
|
|
62
|
+
* decisions. A cap on rounds stops an agent that keeps asking from waiting
|
|
63
|
+
* forever.
|
|
64
|
+
*/
|
|
65
|
+
export declare function runWithDeliverdApprovals<Result extends OpenAiInterruptedResult<Item>, Item extends OpenAiApprovalItem = OpenAiApprovalItem, Input = unknown>(runOnce: (input: Input | Result["state"]) => Promise<Result>, input: Input, options: ToolApprovalOptions & {
|
|
66
|
+
maxRounds?: number;
|
|
67
|
+
}): Promise<Result>;
|
|
68
|
+
//# sourceMappingURL=openai-agents.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"openai-agents.d.ts","sourceRoot":"","sources":["../../src/adapters/openai-agents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAED,gEAAgE;AAChE,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB,GAAG,kBAAkB,EAAE,KAAK,GAAG,OAAO;IAC5G,aAAa,EAAE,IAAI,EAAE,CAAC;IACtB,KAAK,EAAE,KAAK,GAAG;QACb,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE;YAAE,aAAa,CAAC,EAAE,OAAO,CAAA;SAAE,GAAG,IAAI,CAAC;QACjE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE;YAAE,YAAY,CAAC,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;KAClF,CAAC;CACH;AAED,qFAAqF;AACrF,wBAAsB,oBAAoB,CAAC,IAAI,SAAS,kBAAkB,EACxE,MAAM,EAAE,uBAAuB,CAAC,IAAI,CAAC,EACrC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBjD;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,SAAS,uBAAuB,CAAC,IAAI,CAAC,EAC5C,IAAI,SAAS,kBAAkB,GAAG,kBAAkB,EACpD,KAAK,GAAG,OAAO,EAEf,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,EAC5D,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,mBAAmB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,OAAO,CAAC,MAAM,CAAC,CAYjB"}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { askAboutCall } from "./shared.js";
|
|
2
|
+
/** Ask about every interruption in a result, and record each answer on its state. */
|
|
3
|
+
export async function resolveInterruptions(result, options) {
|
|
4
|
+
let approved = 0;
|
|
5
|
+
let rejected = 0;
|
|
6
|
+
for (const item of result.interruptions) {
|
|
7
|
+
const toolName = item.name ?? item.rawItem?.name ?? "a tool";
|
|
8
|
+
const input = parseArguments(item.arguments);
|
|
9
|
+
if (options.when && !(await options.when(toolName, input))) {
|
|
10
|
+
result.state.approve(item);
|
|
11
|
+
approved += 1;
|
|
12
|
+
continue;
|
|
13
|
+
}
|
|
14
|
+
const callId = item.rawItem?.callId ?? item.rawItem?.id ?? `${toolName}:${item.arguments ?? ""}`;
|
|
15
|
+
const outcome = await askAboutCall(toolName, input, `openai-agents:${callId}`, options);
|
|
16
|
+
if (outcome.allowed) {
|
|
17
|
+
result.state.approve(item);
|
|
18
|
+
approved += 1;
|
|
19
|
+
}
|
|
20
|
+
else {
|
|
21
|
+
result.state.reject(item, { message: outcome.reason });
|
|
22
|
+
rejected += 1;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
return { approved, rejected };
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Run until nothing is waiting on a person.
|
|
29
|
+
*
|
|
30
|
+
* `runOnce` is your call to the SDK's `run(agent, input)`; it is called
|
|
31
|
+
* first with `input`, then with the result's state after each round of
|
|
32
|
+
* decisions. A cap on rounds stops an agent that keeps asking from waiting
|
|
33
|
+
* forever.
|
|
34
|
+
*/
|
|
35
|
+
export async function runWithDeliverdApprovals(runOnce, input, options) {
|
|
36
|
+
let result = await runOnce(input);
|
|
37
|
+
for (let round = 0; result.interruptions.length > 0; round++) {
|
|
38
|
+
if (round >= (options.maxRounds ?? 10)) {
|
|
39
|
+
throw new Error(`The run was still waiting for approval after ${options.maxRounds ?? 10} rounds; stopping rather than asking forever.`);
|
|
40
|
+
}
|
|
41
|
+
await resolveInterruptions(result, options);
|
|
42
|
+
result = await runOnce(result.state);
|
|
43
|
+
}
|
|
44
|
+
return result;
|
|
45
|
+
}
|
|
46
|
+
function parseArguments(raw) {
|
|
47
|
+
if (!raw)
|
|
48
|
+
return {};
|
|
49
|
+
try {
|
|
50
|
+
return JSON.parse(raw);
|
|
51
|
+
}
|
|
52
|
+
catch {
|
|
53
|
+
return raw;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import type { Duration } from "../duration.js";
|
|
2
|
+
import type { ApprovalFactor, ApprovalRisk, Decision, FieldChange } from "../types.js";
|
|
3
|
+
/**
|
|
4
|
+
* What the framework adapters share: how a tool call becomes a request, and
|
|
5
|
+
* what the answer becomes.
|
|
6
|
+
*
|
|
7
|
+
* The adapters are written against each framework's own hook — the Claude
|
|
8
|
+
* Agent SDK's `canUseTool`, the AI SDK's `toolApproval`, the OpenAI Agents
|
|
9
|
+
* SDK's interruptions, LangGraph's `interrupt` — by shape rather than by
|
|
10
|
+
* import, so `@deliverd/sdk` keeps its promise of no dependencies. Each
|
|
11
|
+
* shape was taken from that framework's published type definitions and is
|
|
12
|
+
* checked against them in this package's tests.
|
|
13
|
+
*/
|
|
14
|
+
/** Anything with Deliverd's `approve()`: the client, or a test double. */
|
|
15
|
+
export interface Approver {
|
|
16
|
+
approve(options: {
|
|
17
|
+
title: string;
|
|
18
|
+
description?: string;
|
|
19
|
+
risk?: ApprovalRisk;
|
|
20
|
+
factors?: ApprovalFactor[];
|
|
21
|
+
approvers?: string[];
|
|
22
|
+
externalId?: string;
|
|
23
|
+
flowId?: string;
|
|
24
|
+
metadata?: Record<string, unknown>;
|
|
25
|
+
callbackUrl?: string;
|
|
26
|
+
input?: Record<string, unknown>;
|
|
27
|
+
editableFields?: string[];
|
|
28
|
+
expiresIn?: Duration;
|
|
29
|
+
timeout?: Duration;
|
|
30
|
+
signal?: AbortSignal;
|
|
31
|
+
}): Promise<Decision>;
|
|
32
|
+
}
|
|
33
|
+
/** What a person is shown about one tool call. */
|
|
34
|
+
export interface CallDescription {
|
|
35
|
+
title: string;
|
|
36
|
+
description?: string;
|
|
37
|
+
risk?: ApprovalRisk;
|
|
38
|
+
factors?: ApprovalFactor[];
|
|
39
|
+
}
|
|
40
|
+
export interface ToolApprovalOptions {
|
|
41
|
+
/** The client: `new Deliverd()`. */
|
|
42
|
+
deliverd: Approver;
|
|
43
|
+
/**
|
|
44
|
+
* Which calls need a person. Every call when omitted — so name the few
|
|
45
|
+
* that matter: `when: (tool) => ["send_email", "refund"].includes(tool)`.
|
|
46
|
+
*/
|
|
47
|
+
when?: (toolName: string, input: unknown) => boolean | Promise<boolean>;
|
|
48
|
+
/** Who may decide: people, teams, groups. The organisation's admins when omitted. */
|
|
49
|
+
approvers?: string[];
|
|
50
|
+
/** What the approver reads. A readable default is built from the tool and its input. */
|
|
51
|
+
describe?: (toolName: string, input: unknown) => CallDescription;
|
|
52
|
+
/** How long the request stays open. Default one hour: an agent is waiting. */
|
|
53
|
+
expiresIn?: Duration;
|
|
54
|
+
/** Give up waiting after this and refuse the call. Defaults to the request's own expiry. */
|
|
55
|
+
timeout?: Duration;
|
|
56
|
+
/** The flow this run belongs to, so every call it asked about is on one timeline. */
|
|
57
|
+
flowId?: string;
|
|
58
|
+
metadata?: Record<string, unknown>;
|
|
59
|
+
}
|
|
60
|
+
export declare function structuredInput(input: unknown): Record<string, unknown> | undefined;
|
|
61
|
+
export declare const DEFAULT_TOOL_EXPIRY: Duration;
|
|
62
|
+
/** A plain account of a call, for when the caller did not write one. */
|
|
63
|
+
export declare function defaultDescription(toolName: string, input: unknown): CallDescription;
|
|
64
|
+
/** The answer an adapter hands back to its framework. */
|
|
65
|
+
export type CallOutcome = {
|
|
66
|
+
allowed: true;
|
|
67
|
+
decidedBy: string | null;
|
|
68
|
+
note: string | null;
|
|
69
|
+
/** What to run with: the approver's correction, when they made one. */
|
|
70
|
+
input: Record<string, unknown> | null;
|
|
71
|
+
changes: FieldChange[];
|
|
72
|
+
} | {
|
|
73
|
+
allowed: false;
|
|
74
|
+
reason: string;
|
|
75
|
+
};
|
|
76
|
+
/**
|
|
77
|
+
* Ask about one call and wait.
|
|
78
|
+
*
|
|
79
|
+
* `externalId` makes the ask idempotent: a framework that retries a step, or
|
|
80
|
+
* a process that restarts mid-wait, finds the request it already made instead
|
|
81
|
+
* of filing a second one (`approve()` reuses by `externalId`).
|
|
82
|
+
*
|
|
83
|
+
* A refusal, an expiry and a wait that ran out are all "not allowed", each
|
|
84
|
+
* with a sentence the model can read and act on — never a thrown error, which
|
|
85
|
+
* most frameworks would turn into a crashed run rather than a declined call.
|
|
86
|
+
*/
|
|
87
|
+
export declare function askAboutCall(toolName: string, input: unknown, externalId: string, options: ToolApprovalOptions, signal?: AbortSignal,
|
|
88
|
+
/** Fields a person may correct. Only for a framework that can run a corrected call. */
|
|
89
|
+
editableFields?: string[]): Promise<CallOutcome>;
|
|
90
|
+
export declare function refusalReason(toolName: string, decision: Pick<Decision, "status" | "note" | "decidedBy">): string;
|
|
91
|
+
//# sourceMappingURL=shared.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/adapters/shared.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEvF;;;;;;;;;;GAUG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,OAAO,EAAE;QACf,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,YAAY,CAAC;QACpB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;QAC3B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,SAAS,CAAC,EAAE,QAAQ,CAAC;QACrB,OAAO,CAAC,EAAE,QAAQ,CAAC;QACnB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvB;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,qFAAqF;IACrF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,eAAe,CAAC;IACjE,8EAA8E;IAC9E,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB,4FAA4F;IAC5F,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAQD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAOnF;AAED,eAAO,MAAM,mBAAmB,EAAE,QAAe,CAAC;AAGlD,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,eAAe,CAapF;AAED,yDAAyD;AACzD,MAAM,MAAM,WAAW,GACnB;IACE,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACtC,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB,GACD;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,WAAW;AACpB,uFAAuF;AACvF,cAAc,CAAC,EAAE,MAAM,EAAE,GACxB,OAAO,CAAC,WAAW,CAAC,CAmCtB;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC,GAAG,MAAM,CAWjH"}
|