@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.
Files changed (109) hide show
  1. package/CHANGELOG.md +49 -0
  2. package/README.md +73 -1
  3. package/dist/index.cjs +145 -7
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +111 -3
  6. package/dist/index.d.ts +111 -3
  7. package/dist/index.js +138 -7
  8. package/dist/index.js.map +1 -1
  9. package/dist/integrations/anthropic.d.cts +1 -1
  10. package/dist/integrations/anthropic.d.ts +1 -1
  11. package/dist/integrations/ap2.d.cts +1 -1
  12. package/dist/integrations/ap2.d.ts +1 -1
  13. package/dist/integrations/aws-iam.d.cts +1 -1
  14. package/dist/integrations/aws-iam.d.ts +1 -1
  15. package/dist/integrations/bank-rails.d.cts +1 -1
  16. package/dist/integrations/bank-rails.d.ts +1 -1
  17. package/dist/integrations/circle.d.cts +1 -1
  18. package/dist/integrations/circle.d.ts +1 -1
  19. package/dist/integrations/cloudflare.d.cts +1 -1
  20. package/dist/integrations/cloudflare.d.ts +1 -1
  21. package/dist/integrations/coinbase-cdp.d.cts +1 -1
  22. package/dist/integrations/coinbase-cdp.d.ts +1 -1
  23. package/dist/integrations/commerce-agents.cjs +467 -0
  24. package/dist/integrations/commerce-agents.cjs.map +1 -0
  25. package/dist/integrations/commerce-agents.d.cts +199 -0
  26. package/dist/integrations/commerce-agents.d.ts +199 -0
  27. package/dist/integrations/commerce-agents.js +429 -0
  28. package/dist/integrations/commerce-agents.js.map +1 -0
  29. package/dist/integrations/crewai.d.cts +1 -1
  30. package/dist/integrations/crewai.d.ts +1 -1
  31. package/dist/integrations/entra.d.cts +1 -1
  32. package/dist/integrations/entra.d.ts +1 -1
  33. package/dist/integrations/fhir.d.cts +1 -1
  34. package/dist/integrations/fhir.d.ts +1 -1
  35. package/dist/integrations/grok.d.cts +1 -1
  36. package/dist/integrations/grok.d.ts +1 -1
  37. package/dist/integrations/guidewire.d.cts +1 -1
  38. package/dist/integrations/guidewire.d.ts +1 -1
  39. package/dist/integrations/hermes.d.cts +1 -1
  40. package/dist/integrations/hermes.d.ts +1 -1
  41. package/dist/integrations/jira.cjs +190 -0
  42. package/dist/integrations/jira.cjs.map +1 -0
  43. package/dist/integrations/jira.d.cts +162 -0
  44. package/dist/integrations/jira.d.ts +162 -0
  45. package/dist/integrations/jira.js +164 -0
  46. package/dist/integrations/jira.js.map +1 -0
  47. package/dist/integrations/langchain.d.cts +1 -1
  48. package/dist/integrations/langchain.d.ts +1 -1
  49. package/dist/integrations/langgraph.d.cts +1 -1
  50. package/dist/integrations/langgraph.d.ts +1 -1
  51. package/dist/integrations/legal.d.cts +1 -1
  52. package/dist/integrations/legal.d.ts +1 -1
  53. package/dist/integrations/life-sciences.d.cts +1 -1
  54. package/dist/integrations/life-sciences.d.ts +1 -1
  55. package/dist/integrations/linear.cjs +193 -0
  56. package/dist/integrations/linear.cjs.map +1 -0
  57. package/dist/integrations/linear.d.cts +173 -0
  58. package/dist/integrations/linear.d.ts +173 -0
  59. package/dist/integrations/linear.js +167 -0
  60. package/dist/integrations/linear.js.map +1 -0
  61. package/dist/integrations/lithic.d.cts +1 -1
  62. package/dist/integrations/lithic.d.ts +1 -1
  63. package/dist/integrations/llamaindex.d.cts +1 -1
  64. package/dist/integrations/llamaindex.d.ts +1 -1
  65. package/dist/integrations/marqeta.d.cts +1 -1
  66. package/dist/integrations/marqeta.d.ts +1 -1
  67. package/dist/integrations/modern-treasury.d.cts +1 -1
  68. package/dist/integrations/modern-treasury.d.ts +1 -1
  69. package/dist/integrations/nekuda.d.cts +1 -1
  70. package/dist/integrations/nekuda.d.ts +1 -1
  71. package/dist/integrations/okta.d.cts +1 -1
  72. package/dist/integrations/okta.d.ts +1 -1
  73. package/dist/integrations/openai.d.cts +1 -1
  74. package/dist/integrations/openai.d.ts +1 -1
  75. package/dist/integrations/openrouter.d.cts +1 -1
  76. package/dist/integrations/openrouter.d.ts +1 -1
  77. package/dist/integrations/paypal-agent.d.cts +1 -1
  78. package/dist/integrations/paypal-agent.d.ts +1 -1
  79. package/dist/integrations/perplexity.cjs +430 -0
  80. package/dist/integrations/perplexity.cjs.map +1 -0
  81. package/dist/integrations/perplexity.d.cts +65 -0
  82. package/dist/integrations/perplexity.d.ts +65 -0
  83. package/dist/integrations/perplexity.js +388 -0
  84. package/dist/integrations/perplexity.js.map +1 -0
  85. package/dist/integrations/plaid.d.cts +1 -1
  86. package/dist/integrations/plaid.d.ts +1 -1
  87. package/dist/integrations/ramp.d.cts +1 -1
  88. package/dist/integrations/ramp.d.ts +1 -1
  89. package/dist/integrations/shopify.d.cts +1 -1
  90. package/dist/integrations/shopify.d.ts +1 -1
  91. package/dist/integrations/siem.d.cts +1 -1
  92. package/dist/integrations/siem.d.ts +1 -1
  93. package/dist/integrations/skyfire.d.cts +1 -1
  94. package/dist/integrations/skyfire.d.ts +1 -1
  95. package/dist/integrations/stripe-acp.d.cts +1 -1
  96. package/dist/integrations/stripe-acp.d.ts +1 -1
  97. package/dist/integrations/stripe-issuing.d.cts +1 -1
  98. package/dist/integrations/stripe-issuing.d.ts +1 -1
  99. package/dist/integrations/truanon.d.cts +1 -1
  100. package/dist/integrations/truanon.d.ts +1 -1
  101. package/dist/integrations/ucp.d.cts +1 -1
  102. package/dist/integrations/ucp.d.ts +1 -1
  103. package/dist/integrations/vercel-ai.d.cts +1 -1
  104. package/dist/integrations/vercel-ai.d.ts +1 -1
  105. package/dist/integrations/x402.d.cts +1 -1
  106. package/dist/integrations/x402.d.ts +1 -1
  107. package/dist/{types-Lp1iHEDz.d.cts → types-BmeluKHI.d.cts} +1 -1
  108. package/dist/{types-Lp1iHEDz.d.ts → types-BmeluKHI.d.ts} +1 -1
  109. 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 };