@vorim/sdk 3.18.2 → 3.20.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/CHANGELOG.md +49 -0
- package/README.md +73 -1
- package/dist/index.cjs +145 -7
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +111 -3
- package/dist/index.d.ts +111 -3
- package/dist/index.js +138 -7
- package/dist/index.js.map +1 -1
- package/dist/integrations/anthropic.d.cts +1 -1
- package/dist/integrations/anthropic.d.ts +1 -1
- package/dist/integrations/ap2.d.cts +1 -1
- package/dist/integrations/ap2.d.ts +1 -1
- package/dist/integrations/aws-iam.d.cts +1 -1
- package/dist/integrations/aws-iam.d.ts +1 -1
- package/dist/integrations/bank-rails.d.cts +1 -1
- package/dist/integrations/bank-rails.d.ts +1 -1
- package/dist/integrations/circle.d.cts +1 -1
- package/dist/integrations/circle.d.ts +1 -1
- package/dist/integrations/cloudflare.d.cts +1 -1
- package/dist/integrations/cloudflare.d.ts +1 -1
- package/dist/integrations/coinbase-cdp.d.cts +1 -1
- package/dist/integrations/coinbase-cdp.d.ts +1 -1
- package/dist/integrations/commerce-agents.cjs +467 -0
- package/dist/integrations/commerce-agents.cjs.map +1 -0
- package/dist/integrations/commerce-agents.d.cts +199 -0
- package/dist/integrations/commerce-agents.d.ts +199 -0
- package/dist/integrations/commerce-agents.js +429 -0
- package/dist/integrations/commerce-agents.js.map +1 -0
- package/dist/integrations/crewai.d.cts +1 -1
- package/dist/integrations/crewai.d.ts +1 -1
- package/dist/integrations/entra.d.cts +1 -1
- package/dist/integrations/entra.d.ts +1 -1
- package/dist/integrations/fhir.d.cts +1 -1
- package/dist/integrations/fhir.d.ts +1 -1
- package/dist/integrations/grok.d.cts +1 -1
- package/dist/integrations/grok.d.ts +1 -1
- package/dist/integrations/guidewire.d.cts +1 -1
- package/dist/integrations/guidewire.d.ts +1 -1
- package/dist/integrations/hermes.d.cts +1 -1
- package/dist/integrations/hermes.d.ts +1 -1
- package/dist/integrations/jira.cjs +190 -0
- package/dist/integrations/jira.cjs.map +1 -0
- package/dist/integrations/jira.d.cts +162 -0
- package/dist/integrations/jira.d.ts +162 -0
- package/dist/integrations/jira.js +164 -0
- package/dist/integrations/jira.js.map +1 -0
- package/dist/integrations/langchain.d.cts +1 -1
- package/dist/integrations/langchain.d.ts +1 -1
- package/dist/integrations/langgraph.d.cts +1 -1
- package/dist/integrations/langgraph.d.ts +1 -1
- package/dist/integrations/legal.d.cts +1 -1
- package/dist/integrations/legal.d.ts +1 -1
- package/dist/integrations/life-sciences.d.cts +1 -1
- package/dist/integrations/life-sciences.d.ts +1 -1
- package/dist/integrations/linear.cjs +193 -0
- package/dist/integrations/linear.cjs.map +1 -0
- package/dist/integrations/linear.d.cts +173 -0
- package/dist/integrations/linear.d.ts +173 -0
- package/dist/integrations/linear.js +167 -0
- package/dist/integrations/linear.js.map +1 -0
- package/dist/integrations/lithic.d.cts +1 -1
- package/dist/integrations/lithic.d.ts +1 -1
- package/dist/integrations/llamaindex.d.cts +1 -1
- package/dist/integrations/llamaindex.d.ts +1 -1
- package/dist/integrations/marqeta.d.cts +1 -1
- package/dist/integrations/marqeta.d.ts +1 -1
- package/dist/integrations/modern-treasury.d.cts +1 -1
- package/dist/integrations/modern-treasury.d.ts +1 -1
- package/dist/integrations/nekuda.d.cts +1 -1
- package/dist/integrations/nekuda.d.ts +1 -1
- package/dist/integrations/okta.d.cts +1 -1
- package/dist/integrations/okta.d.ts +1 -1
- package/dist/integrations/openai.d.cts +1 -1
- package/dist/integrations/openai.d.ts +1 -1
- package/dist/integrations/openrouter.d.cts +1 -1
- package/dist/integrations/openrouter.d.ts +1 -1
- package/dist/integrations/paypal-agent.d.cts +1 -1
- package/dist/integrations/paypal-agent.d.ts +1 -1
- package/dist/integrations/perplexity.cjs +430 -0
- package/dist/integrations/perplexity.cjs.map +1 -0
- package/dist/integrations/perplexity.d.cts +65 -0
- package/dist/integrations/perplexity.d.ts +65 -0
- package/dist/integrations/perplexity.js +388 -0
- package/dist/integrations/perplexity.js.map +1 -0
- package/dist/integrations/plaid.d.cts +1 -1
- package/dist/integrations/plaid.d.ts +1 -1
- package/dist/integrations/ramp.d.cts +1 -1
- package/dist/integrations/ramp.d.ts +1 -1
- package/dist/integrations/shopify.d.cts +1 -1
- package/dist/integrations/shopify.d.ts +1 -1
- package/dist/integrations/siem.d.cts +1 -1
- package/dist/integrations/siem.d.ts +1 -1
- package/dist/integrations/skyfire.d.cts +1 -1
- package/dist/integrations/skyfire.d.ts +1 -1
- package/dist/integrations/stripe-acp.d.cts +1 -1
- package/dist/integrations/stripe-acp.d.ts +1 -1
- package/dist/integrations/stripe-issuing.d.cts +1 -1
- package/dist/integrations/stripe-issuing.d.ts +1 -1
- package/dist/integrations/truanon.d.cts +1 -1
- package/dist/integrations/truanon.d.ts +1 -1
- package/dist/integrations/ucp.d.cts +1 -1
- package/dist/integrations/ucp.d.ts +1 -1
- package/dist/integrations/vercel-ai.d.cts +1 -1
- package/dist/integrations/vercel-ai.d.ts +1 -1
- package/dist/integrations/x402.d.cts +1 -1
- package/dist/integrations/x402.d.ts +1 -1
- package/dist/{types-Lp1iHEDz.d.cts → types-BmeluKHI.d.cts} +1 -1
- package/dist/{types-Lp1iHEDz.d.ts → types-BmeluKHI.d.ts} +1 -1
- package/package.json +41 -1
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
import { VorimSDK } from '../index.cjs';
|
|
2
|
+
import { P as PermissionScope } from '../types-BmeluKHI.cjs';
|
|
3
|
+
import { E as EscalationPolicy, T as TransportFailurePolicy } from '../_runtime-gate-DOJUKJBu.cjs';
|
|
4
|
+
|
|
5
|
+
type CommerceRole = 'shopping' | 'merchant';
|
|
6
|
+
/** StorefrontBackend methods -> the least scope that should be required.
|
|
7
|
+
* Keyed by the blueprint's own (snake_case) method names; a camelCase host
|
|
8
|
+
* method resolves to the same entry. */
|
|
9
|
+
declare const SHOPPING_OPERATION_SCOPE: Record<string, PermissionScope>;
|
|
10
|
+
/** MerchantBackend methods -> the least scope that should be required. */
|
|
11
|
+
declare const MERCHANT_OPERATION_SCOPE: Record<string, PermissionScope>;
|
|
12
|
+
/** The two operations that leave the sandbox: one produces a payable cart, the
|
|
13
|
+
* other writes to the live store. Give each a Vorim policy rule that escalates
|
|
14
|
+
* it to a named human — the guard resolves that escalation per `onEscalation`,
|
|
15
|
+
* and `approveChange()` is the purpose-built path for apply_change. Escalation
|
|
16
|
+
* is a policy decision, so nothing here can conjure one: with no rule
|
|
17
|
+
* configured, a plain allow runs. */
|
|
18
|
+
declare const HUMAN_APPROVAL_OPERATIONS: readonly ["checkout_handoff", "apply_change"];
|
|
19
|
+
/** The approval bridge's own operation label. */
|
|
20
|
+
declare const APPROVE_CHANGE = "approve_change";
|
|
21
|
+
/** An offline-verifiable receipt for one commerce backend operation. */
|
|
22
|
+
interface CommerceReceipt {
|
|
23
|
+
authorized: boolean;
|
|
24
|
+
agentId: string;
|
|
25
|
+
role: CommerceRole;
|
|
26
|
+
operation: string;
|
|
27
|
+
result: 'success' | 'denied' | 'error';
|
|
28
|
+
scope: PermissionScope;
|
|
29
|
+
/** True once the audit event was signed and ingested. */
|
|
30
|
+
recorded: boolean;
|
|
31
|
+
storeId?: string;
|
|
32
|
+
humanId?: string;
|
|
33
|
+
sessionId?: string;
|
|
34
|
+
resourceId?: string;
|
|
35
|
+
/** sha256 over the call's arguments, so the receipt covers the exact input
|
|
36
|
+
* without the guard storing it. */
|
|
37
|
+
inputHash?: string;
|
|
38
|
+
/** Reason a check failed, when authorized is false. */
|
|
39
|
+
reason?: string;
|
|
40
|
+
/** The runtime decision this call was resolved by, when runtime control is on. */
|
|
41
|
+
decisionId?: string;
|
|
42
|
+
}
|
|
43
|
+
/** Thrown by a guarded backend method when Vorim denied the call. */
|
|
44
|
+
declare class CommerceDeniedError extends Error {
|
|
45
|
+
readonly receipt: CommerceReceipt;
|
|
46
|
+
constructor(message: string, receipt: CommerceReceipt);
|
|
47
|
+
}
|
|
48
|
+
interface CommerceGuardConfig {
|
|
49
|
+
/** The acting agent's Vorim id (agid_...). */
|
|
50
|
+
agentId: string;
|
|
51
|
+
/** 'shopping' or 'merchant' — picks the scope map and labels the audit
|
|
52
|
+
* record. A deployment running both agents builds one guard per role, each
|
|
53
|
+
* with its own agent id, so a shopper-facing agent can never be mistaken for
|
|
54
|
+
* the one that moves prices. */
|
|
55
|
+
role: CommerceRole;
|
|
56
|
+
/** The customer or operator the agent acts for. Falls back to the per-request
|
|
57
|
+
* session context (userId/user_id, operator) when the call carries one. */
|
|
58
|
+
humanId?: string;
|
|
59
|
+
/** The store / merchant this agent operates on. Recorded on every receipt. */
|
|
60
|
+
storeId?: string;
|
|
61
|
+
/** Minimum trust score the acting agent must hold. Default 0 (off). */
|
|
62
|
+
minTrustScore?: number;
|
|
63
|
+
/** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */
|
|
64
|
+
onError?: 'closed' | 'open';
|
|
65
|
+
/** Scope required by a backend method the maps do not know. Default
|
|
66
|
+
* 'agent:write' — a method we cannot classify is assumed to write. */
|
|
67
|
+
unknownScope?: PermissionScope;
|
|
68
|
+
/** Route decisions through beforeAction (live policy, budgets, human
|
|
69
|
+
* escalation) instead of a static check/verify. Default false. */
|
|
70
|
+
useRuntimeControl?: boolean;
|
|
71
|
+
/** What to do on an `escalate` verdict. Default 'wait'. */
|
|
72
|
+
onEscalation?: EscalationPolicy;
|
|
73
|
+
/** Timeout (ms) for onEscalation: 'wait'. */
|
|
74
|
+
escalationTimeoutMs?: number;
|
|
75
|
+
/** What to do when the control plane is unreachable. Default 'deny'. */
|
|
76
|
+
onTransportFailure?: TransportFailurePolicy;
|
|
77
|
+
/** Turn a denial receipt into the error the backend should throw. Use it to
|
|
78
|
+
* return commerce-agents' own NotOffered / Unavailable so the model gets the
|
|
79
|
+
* blueprint's wording instead of the generic failure text. */
|
|
80
|
+
onDenied?: (receipt: CommerceReceipt) => Error;
|
|
81
|
+
}
|
|
82
|
+
/** What one guarded call is about, pulled off the bound arguments. */
|
|
83
|
+
interface CommerceAction {
|
|
84
|
+
operation: string;
|
|
85
|
+
resourceId?: string;
|
|
86
|
+
sessionId?: string;
|
|
87
|
+
humanId?: string;
|
|
88
|
+
payload?: Record<string, unknown>;
|
|
89
|
+
inputHash?: string;
|
|
90
|
+
}
|
|
91
|
+
/** camelCase -> snake_case, so a TypeScript host's `searchProducts` finds the
|
|
92
|
+
* blueprint's `search_products` entry. */
|
|
93
|
+
declare function normalizeOperation(operation: string): string;
|
|
94
|
+
/**
|
|
95
|
+
* Describe one backend call: which resource it touches, whose session it runs
|
|
96
|
+
* in, and a JSON-safe payload for payload-conditioned policy rules.
|
|
97
|
+
*
|
|
98
|
+
* The blueprint's per-request context (ShoppingSessionContext /
|
|
99
|
+
* MerchantSessionContext) is always the first argument; it is the host's own
|
|
100
|
+
* object, so it is read for identity and then left out of the payload rather
|
|
101
|
+
* than shipped to the policy engine.
|
|
102
|
+
*/
|
|
103
|
+
declare function describeCommerceCall(operation: string, args: unknown[]): Promise<CommerceAction>;
|
|
104
|
+
declare class VorimCommerceGuard {
|
|
105
|
+
private sdk;
|
|
106
|
+
private agentId;
|
|
107
|
+
readonly role: CommerceRole;
|
|
108
|
+
private humanId?;
|
|
109
|
+
private storeId?;
|
|
110
|
+
private minTrustScore;
|
|
111
|
+
private onError;
|
|
112
|
+
private unknownScope;
|
|
113
|
+
private useRuntimeControl;
|
|
114
|
+
private onEscalation;
|
|
115
|
+
private escalationTimeoutMs?;
|
|
116
|
+
private onTransportFailure;
|
|
117
|
+
private onDenied?;
|
|
118
|
+
constructor(sdk: VorimSDK, config: CommerceGuardConfig);
|
|
119
|
+
/** The scope map for this guard's role. */
|
|
120
|
+
get scopes(): Record<string, PermissionScope>;
|
|
121
|
+
/** Whether an operation is one this guard's role knows how to classify. */
|
|
122
|
+
knows(operation: string): boolean;
|
|
123
|
+
/** The Vorim scope an operation requires; unknown methods take unknownScope. */
|
|
124
|
+
scopeFor(operation: string): PermissionScope;
|
|
125
|
+
/**
|
|
126
|
+
* Check whether the acting agent may run this operation, before it runs.
|
|
127
|
+
* Static path: trust floor, then permission scope. Runtime path: a
|
|
128
|
+
* beforeAction decision, with `escalate` resolved per onEscalation.
|
|
129
|
+
*/
|
|
130
|
+
authorize(action: CommerceAction): Promise<{
|
|
131
|
+
authorized: boolean;
|
|
132
|
+
reason?: string;
|
|
133
|
+
decisionId?: string;
|
|
134
|
+
}>;
|
|
135
|
+
/**
|
|
136
|
+
* Emit a source-signed audit event and return whether it was recorded. The
|
|
137
|
+
* event names the agent, the store, the session and the person the agent acts
|
|
138
|
+
* for, so a cart write or a live price move is attributable and independently
|
|
139
|
+
* verifiable offline.
|
|
140
|
+
*/
|
|
141
|
+
record(action: CommerceAction, result: 'success' | 'denied' | 'error', reason?: string, decisionId?: string): Promise<boolean>;
|
|
142
|
+
/**
|
|
143
|
+
* The full flow for one backend call: authorize, run it if allowed, sign a
|
|
144
|
+
* receipt either way. If not authorized, `run` is never called — the
|
|
145
|
+
* catalogue is never queried, the cart is never written, nothing goes live.
|
|
146
|
+
* An error from `run` is recorded and rethrown with the receipt attached as
|
|
147
|
+
* `vorimReceipt`, so the executor's failure ladder still sees the real
|
|
148
|
+
* failure.
|
|
149
|
+
*/
|
|
150
|
+
guard<T>(action: CommerceAction, run: () => Promise<T>): Promise<{
|
|
151
|
+
receipt: CommerceReceipt;
|
|
152
|
+
value?: T;
|
|
153
|
+
}>;
|
|
154
|
+
/**
|
|
155
|
+
* Ask a human to approve a staged merchant change, and mark it approved on the
|
|
156
|
+
* session state when they do.
|
|
157
|
+
*
|
|
158
|
+
* This is the bridge to MerchantAgentConfig.require_host_approval:
|
|
159
|
+
* commerce-agents applies a change only for ids in
|
|
160
|
+
* MerchantSessionState.approved_change_ids, and this fills that set from a
|
|
161
|
+
* signed human decision rather than from host code that trusted the
|
|
162
|
+
* conversation. With useRuntimeControl off there is nobody to escalate to, so
|
|
163
|
+
* it falls back to the static scope check — which proves the agent *may* apply
|
|
164
|
+
* changes, not that a person approved this one.
|
|
165
|
+
*/
|
|
166
|
+
approveChange(changeId: string, opts?: {
|
|
167
|
+
state?: {
|
|
168
|
+
approved_change_ids?: Set<string>;
|
|
169
|
+
approvedChangeIds?: Set<string>;
|
|
170
|
+
};
|
|
171
|
+
sessionId?: string;
|
|
172
|
+
payload?: Record<string, unknown>;
|
|
173
|
+
}): Promise<CommerceReceipt>;
|
|
174
|
+
/** The error a guarded backend method throws on a denial. */
|
|
175
|
+
denialError(receipt: CommerceReceipt): Error;
|
|
176
|
+
private receipt;
|
|
177
|
+
}
|
|
178
|
+
/** Reaches the unguarded backend behind a proxy, for host code that
|
|
179
|
+
* legitimately bypasses the agent path (a nightly sync, a support tool). */
|
|
180
|
+
declare const UNGUARDED: unique symbol;
|
|
181
|
+
interface GuardBackendOptions {
|
|
182
|
+
/** Gate a method neither scope map knows, at `unknownScope`, rather than
|
|
183
|
+
* waving it through: a backend that grew a method since these maps were
|
|
184
|
+
* written should not be the hole. Default true. Note that a guarded method
|
|
185
|
+
* always returns a promise — turn this off if your backend exposes
|
|
186
|
+
* synchronous helpers. */
|
|
187
|
+
guardUnknown?: boolean;
|
|
188
|
+
}
|
|
189
|
+
/** Wrap a StorefrontBackend so every shopping tool call is authorized and
|
|
190
|
+
* signed. The guard's role must be 'shopping'. */
|
|
191
|
+
declare function guardStorefrontBackend<B extends object>(backend: B, guard: VorimCommerceGuard, options?: GuardBackendOptions): B;
|
|
192
|
+
/** Wrap a MerchantBackend so every merchant tool call — reads, staged changes,
|
|
193
|
+
* and the live applyChange — is authorized and signed. The guard's role must
|
|
194
|
+
* be 'merchant'. */
|
|
195
|
+
declare function guardMerchantBackend<B extends object>(backend: B, guard: VorimCommerceGuard, options?: GuardBackendOptions): B;
|
|
196
|
+
/** Create a {@link VorimCommerceGuard}. See {@link CommerceGuardConfig}. */
|
|
197
|
+
declare function createVorimCommerceGuard(sdk: VorimSDK, config: CommerceGuardConfig): VorimCommerceGuard;
|
|
198
|
+
|
|
199
|
+
export { APPROVE_CHANGE, type CommerceAction, CommerceDeniedError, type CommerceGuardConfig, type CommerceReceipt, type CommerceRole, type GuardBackendOptions, HUMAN_APPROVAL_OPERATIONS, MERCHANT_OPERATION_SCOPE, SHOPPING_OPERATION_SCOPE, UNGUARDED, VorimCommerceGuard, createVorimCommerceGuard, createVorimCommerceGuard as default, describeCommerceCall, guardMerchantBackend, guardStorefrontBackend, normalizeOperation };
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
import { VorimSDK } from '../index.js';
|
|
2
|
+
import { P as PermissionScope } from '../types-BmeluKHI.js';
|
|
3
|
+
import { E as EscalationPolicy, T as TransportFailurePolicy } from '../_runtime-gate-DOJUKJBu.js';
|
|
4
|
+
|
|
5
|
+
type CommerceRole = 'shopping' | 'merchant';
|
|
6
|
+
/** StorefrontBackend methods -> the least scope that should be required.
|
|
7
|
+
* Keyed by the blueprint's own (snake_case) method names; a camelCase host
|
|
8
|
+
* method resolves to the same entry. */
|
|
9
|
+
declare const SHOPPING_OPERATION_SCOPE: Record<string, PermissionScope>;
|
|
10
|
+
/** MerchantBackend methods -> the least scope that should be required. */
|
|
11
|
+
declare const MERCHANT_OPERATION_SCOPE: Record<string, PermissionScope>;
|
|
12
|
+
/** The two operations that leave the sandbox: one produces a payable cart, the
|
|
13
|
+
* other writes to the live store. Give each a Vorim policy rule that escalates
|
|
14
|
+
* it to a named human — the guard resolves that escalation per `onEscalation`,
|
|
15
|
+
* and `approveChange()` is the purpose-built path for apply_change. Escalation
|
|
16
|
+
* is a policy decision, so nothing here can conjure one: with no rule
|
|
17
|
+
* configured, a plain allow runs. */
|
|
18
|
+
declare const HUMAN_APPROVAL_OPERATIONS: readonly ["checkout_handoff", "apply_change"];
|
|
19
|
+
/** The approval bridge's own operation label. */
|
|
20
|
+
declare const APPROVE_CHANGE = "approve_change";
|
|
21
|
+
/** An offline-verifiable receipt for one commerce backend operation. */
|
|
22
|
+
interface CommerceReceipt {
|
|
23
|
+
authorized: boolean;
|
|
24
|
+
agentId: string;
|
|
25
|
+
role: CommerceRole;
|
|
26
|
+
operation: string;
|
|
27
|
+
result: 'success' | 'denied' | 'error';
|
|
28
|
+
scope: PermissionScope;
|
|
29
|
+
/** True once the audit event was signed and ingested. */
|
|
30
|
+
recorded: boolean;
|
|
31
|
+
storeId?: string;
|
|
32
|
+
humanId?: string;
|
|
33
|
+
sessionId?: string;
|
|
34
|
+
resourceId?: string;
|
|
35
|
+
/** sha256 over the call's arguments, so the receipt covers the exact input
|
|
36
|
+
* without the guard storing it. */
|
|
37
|
+
inputHash?: string;
|
|
38
|
+
/** Reason a check failed, when authorized is false. */
|
|
39
|
+
reason?: string;
|
|
40
|
+
/** The runtime decision this call was resolved by, when runtime control is on. */
|
|
41
|
+
decisionId?: string;
|
|
42
|
+
}
|
|
43
|
+
/** Thrown by a guarded backend method when Vorim denied the call. */
|
|
44
|
+
declare class CommerceDeniedError extends Error {
|
|
45
|
+
readonly receipt: CommerceReceipt;
|
|
46
|
+
constructor(message: string, receipt: CommerceReceipt);
|
|
47
|
+
}
|
|
48
|
+
interface CommerceGuardConfig {
|
|
49
|
+
/** The acting agent's Vorim id (agid_...). */
|
|
50
|
+
agentId: string;
|
|
51
|
+
/** 'shopping' or 'merchant' — picks the scope map and labels the audit
|
|
52
|
+
* record. A deployment running both agents builds one guard per role, each
|
|
53
|
+
* with its own agent id, so a shopper-facing agent can never be mistaken for
|
|
54
|
+
* the one that moves prices. */
|
|
55
|
+
role: CommerceRole;
|
|
56
|
+
/** The customer or operator the agent acts for. Falls back to the per-request
|
|
57
|
+
* session context (userId/user_id, operator) when the call carries one. */
|
|
58
|
+
humanId?: string;
|
|
59
|
+
/** The store / merchant this agent operates on. Recorded on every receipt. */
|
|
60
|
+
storeId?: string;
|
|
61
|
+
/** Minimum trust score the acting agent must hold. Default 0 (off). */
|
|
62
|
+
minTrustScore?: number;
|
|
63
|
+
/** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */
|
|
64
|
+
onError?: 'closed' | 'open';
|
|
65
|
+
/** Scope required by a backend method the maps do not know. Default
|
|
66
|
+
* 'agent:write' — a method we cannot classify is assumed to write. */
|
|
67
|
+
unknownScope?: PermissionScope;
|
|
68
|
+
/** Route decisions through beforeAction (live policy, budgets, human
|
|
69
|
+
* escalation) instead of a static check/verify. Default false. */
|
|
70
|
+
useRuntimeControl?: boolean;
|
|
71
|
+
/** What to do on an `escalate` verdict. Default 'wait'. */
|
|
72
|
+
onEscalation?: EscalationPolicy;
|
|
73
|
+
/** Timeout (ms) for onEscalation: 'wait'. */
|
|
74
|
+
escalationTimeoutMs?: number;
|
|
75
|
+
/** What to do when the control plane is unreachable. Default 'deny'. */
|
|
76
|
+
onTransportFailure?: TransportFailurePolicy;
|
|
77
|
+
/** Turn a denial receipt into the error the backend should throw. Use it to
|
|
78
|
+
* return commerce-agents' own NotOffered / Unavailable so the model gets the
|
|
79
|
+
* blueprint's wording instead of the generic failure text. */
|
|
80
|
+
onDenied?: (receipt: CommerceReceipt) => Error;
|
|
81
|
+
}
|
|
82
|
+
/** What one guarded call is about, pulled off the bound arguments. */
|
|
83
|
+
interface CommerceAction {
|
|
84
|
+
operation: string;
|
|
85
|
+
resourceId?: string;
|
|
86
|
+
sessionId?: string;
|
|
87
|
+
humanId?: string;
|
|
88
|
+
payload?: Record<string, unknown>;
|
|
89
|
+
inputHash?: string;
|
|
90
|
+
}
|
|
91
|
+
/** camelCase -> snake_case, so a TypeScript host's `searchProducts` finds the
|
|
92
|
+
* blueprint's `search_products` entry. */
|
|
93
|
+
declare function normalizeOperation(operation: string): string;
|
|
94
|
+
/**
|
|
95
|
+
* Describe one backend call: which resource it touches, whose session it runs
|
|
96
|
+
* in, and a JSON-safe payload for payload-conditioned policy rules.
|
|
97
|
+
*
|
|
98
|
+
* The blueprint's per-request context (ShoppingSessionContext /
|
|
99
|
+
* MerchantSessionContext) is always the first argument; it is the host's own
|
|
100
|
+
* object, so it is read for identity and then left out of the payload rather
|
|
101
|
+
* than shipped to the policy engine.
|
|
102
|
+
*/
|
|
103
|
+
declare function describeCommerceCall(operation: string, args: unknown[]): Promise<CommerceAction>;
|
|
104
|
+
declare class VorimCommerceGuard {
|
|
105
|
+
private sdk;
|
|
106
|
+
private agentId;
|
|
107
|
+
readonly role: CommerceRole;
|
|
108
|
+
private humanId?;
|
|
109
|
+
private storeId?;
|
|
110
|
+
private minTrustScore;
|
|
111
|
+
private onError;
|
|
112
|
+
private unknownScope;
|
|
113
|
+
private useRuntimeControl;
|
|
114
|
+
private onEscalation;
|
|
115
|
+
private escalationTimeoutMs?;
|
|
116
|
+
private onTransportFailure;
|
|
117
|
+
private onDenied?;
|
|
118
|
+
constructor(sdk: VorimSDK, config: CommerceGuardConfig);
|
|
119
|
+
/** The scope map for this guard's role. */
|
|
120
|
+
get scopes(): Record<string, PermissionScope>;
|
|
121
|
+
/** Whether an operation is one this guard's role knows how to classify. */
|
|
122
|
+
knows(operation: string): boolean;
|
|
123
|
+
/** The Vorim scope an operation requires; unknown methods take unknownScope. */
|
|
124
|
+
scopeFor(operation: string): PermissionScope;
|
|
125
|
+
/**
|
|
126
|
+
* Check whether the acting agent may run this operation, before it runs.
|
|
127
|
+
* Static path: trust floor, then permission scope. Runtime path: a
|
|
128
|
+
* beforeAction decision, with `escalate` resolved per onEscalation.
|
|
129
|
+
*/
|
|
130
|
+
authorize(action: CommerceAction): Promise<{
|
|
131
|
+
authorized: boolean;
|
|
132
|
+
reason?: string;
|
|
133
|
+
decisionId?: string;
|
|
134
|
+
}>;
|
|
135
|
+
/**
|
|
136
|
+
* Emit a source-signed audit event and return whether it was recorded. The
|
|
137
|
+
* event names the agent, the store, the session and the person the agent acts
|
|
138
|
+
* for, so a cart write or a live price move is attributable and independently
|
|
139
|
+
* verifiable offline.
|
|
140
|
+
*/
|
|
141
|
+
record(action: CommerceAction, result: 'success' | 'denied' | 'error', reason?: string, decisionId?: string): Promise<boolean>;
|
|
142
|
+
/**
|
|
143
|
+
* The full flow for one backend call: authorize, run it if allowed, sign a
|
|
144
|
+
* receipt either way. If not authorized, `run` is never called — the
|
|
145
|
+
* catalogue is never queried, the cart is never written, nothing goes live.
|
|
146
|
+
* An error from `run` is recorded and rethrown with the receipt attached as
|
|
147
|
+
* `vorimReceipt`, so the executor's failure ladder still sees the real
|
|
148
|
+
* failure.
|
|
149
|
+
*/
|
|
150
|
+
guard<T>(action: CommerceAction, run: () => Promise<T>): Promise<{
|
|
151
|
+
receipt: CommerceReceipt;
|
|
152
|
+
value?: T;
|
|
153
|
+
}>;
|
|
154
|
+
/**
|
|
155
|
+
* Ask a human to approve a staged merchant change, and mark it approved on the
|
|
156
|
+
* session state when they do.
|
|
157
|
+
*
|
|
158
|
+
* This is the bridge to MerchantAgentConfig.require_host_approval:
|
|
159
|
+
* commerce-agents applies a change only for ids in
|
|
160
|
+
* MerchantSessionState.approved_change_ids, and this fills that set from a
|
|
161
|
+
* signed human decision rather than from host code that trusted the
|
|
162
|
+
* conversation. With useRuntimeControl off there is nobody to escalate to, so
|
|
163
|
+
* it falls back to the static scope check — which proves the agent *may* apply
|
|
164
|
+
* changes, not that a person approved this one.
|
|
165
|
+
*/
|
|
166
|
+
approveChange(changeId: string, opts?: {
|
|
167
|
+
state?: {
|
|
168
|
+
approved_change_ids?: Set<string>;
|
|
169
|
+
approvedChangeIds?: Set<string>;
|
|
170
|
+
};
|
|
171
|
+
sessionId?: string;
|
|
172
|
+
payload?: Record<string, unknown>;
|
|
173
|
+
}): Promise<CommerceReceipt>;
|
|
174
|
+
/** The error a guarded backend method throws on a denial. */
|
|
175
|
+
denialError(receipt: CommerceReceipt): Error;
|
|
176
|
+
private receipt;
|
|
177
|
+
}
|
|
178
|
+
/** Reaches the unguarded backend behind a proxy, for host code that
|
|
179
|
+
* legitimately bypasses the agent path (a nightly sync, a support tool). */
|
|
180
|
+
declare const UNGUARDED: unique symbol;
|
|
181
|
+
interface GuardBackendOptions {
|
|
182
|
+
/** Gate a method neither scope map knows, at `unknownScope`, rather than
|
|
183
|
+
* waving it through: a backend that grew a method since these maps were
|
|
184
|
+
* written should not be the hole. Default true. Note that a guarded method
|
|
185
|
+
* always returns a promise — turn this off if your backend exposes
|
|
186
|
+
* synchronous helpers. */
|
|
187
|
+
guardUnknown?: boolean;
|
|
188
|
+
}
|
|
189
|
+
/** Wrap a StorefrontBackend so every shopping tool call is authorized and
|
|
190
|
+
* signed. The guard's role must be 'shopping'. */
|
|
191
|
+
declare function guardStorefrontBackend<B extends object>(backend: B, guard: VorimCommerceGuard, options?: GuardBackendOptions): B;
|
|
192
|
+
/** Wrap a MerchantBackend so every merchant tool call — reads, staged changes,
|
|
193
|
+
* and the live applyChange — is authorized and signed. The guard's role must
|
|
194
|
+
* be 'merchant'. */
|
|
195
|
+
declare function guardMerchantBackend<B extends object>(backend: B, guard: VorimCommerceGuard, options?: GuardBackendOptions): B;
|
|
196
|
+
/** Create a {@link VorimCommerceGuard}. See {@link CommerceGuardConfig}. */
|
|
197
|
+
declare function createVorimCommerceGuard(sdk: VorimSDK, config: CommerceGuardConfig): VorimCommerceGuard;
|
|
198
|
+
|
|
199
|
+
export { APPROVE_CHANGE, type CommerceAction, CommerceDeniedError, type CommerceGuardConfig, type CommerceReceipt, type CommerceRole, type GuardBackendOptions, HUMAN_APPROVAL_OPERATIONS, MERCHANT_OPERATION_SCOPE, SHOPPING_OPERATION_SCOPE, UNGUARDED, VorimCommerceGuard, createVorimCommerceGuard, createVorimCommerceGuard as default, describeCommerceCall, guardMerchantBackend, guardStorefrontBackend, normalizeOperation };
|