@vorim/sdk 3.23.0 → 4.1.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 (152) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/dist/_commerce-core-Dyr_dHVP.d.ts +156 -0
  3. package/dist/_commerce-core-wY2jC6rC.d.cts +156 -0
  4. package/dist/index.cjs +217 -14
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +200 -16
  7. package/dist/index.d.ts +200 -16
  8. package/dist/index.js +216 -14
  9. package/dist/index.js.map +1 -1
  10. package/dist/integrations/amazon.cjs +357 -0
  11. package/dist/integrations/amazon.cjs.map +1 -0
  12. package/dist/integrations/amazon.d.cts +88 -0
  13. package/dist/integrations/amazon.d.ts +88 -0
  14. package/dist/integrations/amazon.js +328 -0
  15. package/dist/integrations/amazon.js.map +1 -0
  16. package/dist/integrations/anthropic.d.cts +1 -1
  17. package/dist/integrations/anthropic.d.ts +1 -1
  18. package/dist/integrations/ap2.d.cts +1 -1
  19. package/dist/integrations/ap2.d.ts +1 -1
  20. package/dist/integrations/aws-iam.d.cts +1 -1
  21. package/dist/integrations/aws-iam.d.ts +1 -1
  22. package/dist/integrations/bank-rails.d.cts +1 -1
  23. package/dist/integrations/bank-rails.d.ts +1 -1
  24. package/dist/integrations/circle.d.cts +1 -1
  25. package/dist/integrations/circle.d.ts +1 -1
  26. package/dist/integrations/cloudflare.d.cts +1 -1
  27. package/dist/integrations/cloudflare.d.ts +1 -1
  28. package/dist/integrations/coinbase-cdp.d.cts +1 -1
  29. package/dist/integrations/coinbase-cdp.d.ts +1 -1
  30. package/dist/integrations/commerce-agents.d.cts +1 -1
  31. package/dist/integrations/commerce-agents.d.ts +1 -1
  32. package/dist/integrations/crewai.d.cts +1 -1
  33. package/dist/integrations/crewai.d.ts +1 -1
  34. package/dist/integrations/delivery.cjs +327 -0
  35. package/dist/integrations/delivery.cjs.map +1 -0
  36. package/dist/integrations/delivery.d.cts +33 -0
  37. package/dist/integrations/delivery.d.ts +33 -0
  38. package/dist/integrations/delivery.js +296 -0
  39. package/dist/integrations/delivery.js.map +1 -0
  40. package/dist/integrations/ebay.cjs +350 -0
  41. package/dist/integrations/ebay.cjs.map +1 -0
  42. package/dist/integrations/ebay.d.cts +73 -0
  43. package/dist/integrations/ebay.d.ts +73 -0
  44. package/dist/integrations/ebay.js +321 -0
  45. package/dist/integrations/ebay.js.map +1 -0
  46. package/dist/integrations/entra.d.cts +1 -1
  47. package/dist/integrations/entra.d.ts +1 -1
  48. package/dist/integrations/etsy.cjs +330 -0
  49. package/dist/integrations/etsy.cjs.map +1 -0
  50. package/dist/integrations/etsy.d.cts +41 -0
  51. package/dist/integrations/etsy.d.ts +41 -0
  52. package/dist/integrations/etsy.js +301 -0
  53. package/dist/integrations/etsy.js.map +1 -0
  54. package/dist/integrations/fhir.d.cts +1 -1
  55. package/dist/integrations/fhir.d.ts +1 -1
  56. package/dist/integrations/google-merchant.cjs +332 -0
  57. package/dist/integrations/google-merchant.cjs.map +1 -0
  58. package/dist/integrations/google-merchant.d.cts +43 -0
  59. package/dist/integrations/google-merchant.d.ts +43 -0
  60. package/dist/integrations/google-merchant.js +303 -0
  61. package/dist/integrations/google-merchant.js.map +1 -0
  62. package/dist/integrations/grok.d.cts +1 -1
  63. package/dist/integrations/grok.d.ts +1 -1
  64. package/dist/integrations/guidewire.d.cts +1 -1
  65. package/dist/integrations/guidewire.d.ts +1 -1
  66. package/dist/integrations/hermes.d.cts +1 -1
  67. package/dist/integrations/hermes.d.ts +1 -1
  68. package/dist/integrations/jira.d.cts +1 -1
  69. package/dist/integrations/jira.d.ts +1 -1
  70. package/dist/integrations/langchain.d.cts +1 -1
  71. package/dist/integrations/langchain.d.ts +1 -1
  72. package/dist/integrations/langgraph.d.cts +1 -1
  73. package/dist/integrations/langgraph.d.ts +1 -1
  74. package/dist/integrations/legal.d.cts +1 -1
  75. package/dist/integrations/legal.d.ts +1 -1
  76. package/dist/integrations/life-sciences.d.cts +1 -1
  77. package/dist/integrations/life-sciences.d.ts +1 -1
  78. package/dist/integrations/linear.d.cts +1 -1
  79. package/dist/integrations/linear.d.ts +1 -1
  80. package/dist/integrations/lithic.d.cts +1 -1
  81. package/dist/integrations/lithic.d.ts +1 -1
  82. package/dist/integrations/llamaindex.d.cts +1 -1
  83. package/dist/integrations/llamaindex.d.ts +1 -1
  84. package/dist/integrations/marqeta.d.cts +1 -1
  85. package/dist/integrations/marqeta.d.ts +1 -1
  86. package/dist/integrations/meta.cjs +375 -0
  87. package/dist/integrations/meta.cjs.map +1 -0
  88. package/dist/integrations/meta.d.cts +83 -0
  89. package/dist/integrations/meta.d.ts +83 -0
  90. package/dist/integrations/meta.js +346 -0
  91. package/dist/integrations/meta.js.map +1 -0
  92. package/dist/integrations/modern-treasury.d.cts +1 -1
  93. package/dist/integrations/modern-treasury.d.ts +1 -1
  94. package/dist/integrations/muse.d.cts +1 -1
  95. package/dist/integrations/muse.d.ts +1 -1
  96. package/dist/integrations/nekuda.d.cts +1 -1
  97. package/dist/integrations/nekuda.d.ts +1 -1
  98. package/dist/integrations/okta.d.cts +1 -1
  99. package/dist/integrations/okta.d.ts +1 -1
  100. package/dist/integrations/openai.d.cts +1 -1
  101. package/dist/integrations/openai.d.ts +1 -1
  102. package/dist/integrations/openrouter.d.cts +1 -1
  103. package/dist/integrations/openrouter.d.ts +1 -1
  104. package/dist/integrations/paypal-agent.d.cts +1 -1
  105. package/dist/integrations/paypal-agent.d.ts +1 -1
  106. package/dist/integrations/perplexity.d.cts +1 -1
  107. package/dist/integrations/perplexity.d.ts +1 -1
  108. package/dist/integrations/plaid.d.cts +1 -1
  109. package/dist/integrations/plaid.d.ts +1 -1
  110. package/dist/integrations/ramp.d.cts +1 -1
  111. package/dist/integrations/ramp.d.ts +1 -1
  112. package/dist/integrations/shopify.d.cts +1 -1
  113. package/dist/integrations/shopify.d.ts +1 -1
  114. package/dist/integrations/siem.d.cts +1 -1
  115. package/dist/integrations/siem.d.ts +1 -1
  116. package/dist/integrations/skyfire.d.cts +1 -1
  117. package/dist/integrations/skyfire.d.ts +1 -1
  118. package/dist/integrations/social-ads.cjs +328 -0
  119. package/dist/integrations/social-ads.cjs.map +1 -0
  120. package/dist/integrations/social-ads.d.cts +36 -0
  121. package/dist/integrations/social-ads.d.ts +36 -0
  122. package/dist/integrations/social-ads.js +297 -0
  123. package/dist/integrations/social-ads.js.map +1 -0
  124. package/dist/integrations/stripe-acp.d.cts +1 -1
  125. package/dist/integrations/stripe-acp.d.ts +1 -1
  126. package/dist/integrations/stripe-issuing.d.cts +1 -1
  127. package/dist/integrations/stripe-issuing.d.ts +1 -1
  128. package/dist/integrations/tiktok-shop.cjs +334 -0
  129. package/dist/integrations/tiktok-shop.cjs.map +1 -0
  130. package/dist/integrations/tiktok-shop.d.cts +44 -0
  131. package/dist/integrations/tiktok-shop.d.ts +44 -0
  132. package/dist/integrations/tiktok-shop.js +305 -0
  133. package/dist/integrations/tiktok-shop.js.map +1 -0
  134. package/dist/integrations/truanon.d.cts +1 -1
  135. package/dist/integrations/truanon.d.ts +1 -1
  136. package/dist/integrations/typesafe.d.cts +1 -1
  137. package/dist/integrations/typesafe.d.ts +1 -1
  138. package/dist/integrations/ucp.d.cts +1 -1
  139. package/dist/integrations/ucp.d.ts +1 -1
  140. package/dist/integrations/vercel-ai.d.cts +1 -1
  141. package/dist/integrations/vercel-ai.d.ts +1 -1
  142. package/dist/integrations/walmart.cjs +344 -0
  143. package/dist/integrations/walmart.cjs.map +1 -0
  144. package/dist/integrations/walmart.d.cts +60 -0
  145. package/dist/integrations/walmart.d.ts +60 -0
  146. package/dist/integrations/walmart.js +315 -0
  147. package/dist/integrations/walmart.js.map +1 -0
  148. package/dist/integrations/x402.d.cts +1 -1
  149. package/dist/integrations/x402.d.ts +1 -1
  150. package/dist/{types-BrDQAJdl.d.cts → types-DphtTyIC.d.cts} +72 -3
  151. package/dist/{types-BrDQAJdl.d.ts → types-DphtTyIC.d.ts} +72 -3
  152. package/package.json +92 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,35 @@
1
1
  # Changelog — @vorim/sdk
2
2
 
3
+ ## 4.1.0
4
+
5
+ ### Added
6
+
7
+ - **Marketplace and social-commerce guards.** New entry points `integrations/amazon` (Selling Partner API + Amazon Ads), `ebay` (Sell + Buy APIs), `walmart`, `etsy`, `tiktok-shop`, `meta` (Marketing API, Catalog, WhatsApp Business, Messenger), `google-merchant` (Merchant API + Google Ads), `social-ads` (Pinterest, Snapchat) and `delivery` (DoorDash Drive, Uber Direct). Each maps the platform's operations to a Vorim scope, enforces per-agent ceilings the platform's own tokens cannot (`maxOrderAmount`, `maxRefundAmount`, `maxBudgetAmount`, `maxPriceChangePercent`, `maxBatchSize`), refuses or escalates over a ceiling (`overLimit: 'escalate'` waits for the named approver), can route every call through your runtime rules (`useRuntimeControl`), and signs a record naming the platform, account, operation and the person the agent acts for. The guards never hold a platform token. eBay purchases and bids always wait for a person (eBay's User Agreement requires human review); Amazon receipts mark the agent as automated (Amazon Agent Policy); the Meta guard refuses WhatsApp free-form messages outside the 24-hour window, templates without opt-in, promotional Messenger tags and HUMAN_AGENT sends from an agent.
8
+ - `setBudget` docs now say a budget only blocks with a `token_budget_gt` rule.
9
+
10
+ ## 4.0.0
11
+
12
+ ### Changed (breaking)
13
+
14
+ - **`beforeAction` fails closed by default.** `runtimeFailOpen` now defaults to `false`: when the runtime decision API is unreachable (network error, DNS, timeout, 5xx) the transport error is re-thrown instead of returning a synthetic `fallback` allow. A blocked or slowed path to Vorim could previously be turned into an allow. Pass `runtimeFailOpen: true` to keep the old behaviour; choose it per deployment. A reachable server that returns `deny` still denies either way, and the framework integration gates already failed closed. The server default changed on the same day: `runtime_settings.fail_open` is `false` for new orgs.
15
+
16
+ ### Fixed
17
+
18
+ - `setBudget`, `listBudgets`, `getBudgetSpend` and `deleteBudget` work with an API key. The routes were session-only, so every call from the SDK got `401 WRONG_CREDENTIAL_TYPE` while these docs said an API key worked. The key needs the new `runtime:manage` scope (separate from `runtime:decide`, so an agent's own key cannot raise its ceiling).
19
+
20
+ ### Added
21
+
22
+ - **Server-minted swarm id.** Agents gain `swarm_id`: minted on a root agent at its first delegation or ephemeral spawn and inherited by every member; nothing in a request can set it. The server stamps it on runtime decisions (`RuntimeDecision.swarmId`), audit events (in the signed bundle's attestation envelope, not the signed body) and shared-memory writes. `registerEphemeral({ parent_agent_id })` puts a spawned worker in its parent's swarm. `getSwarm(agentId)` lists a swarm. Budgets accept `scope: 'swarm'`, and a policy rule can set `behavior_scope: 'swarm'` so velocity, fan-out and `sod_conflict` read the whole swarm's window instead of one agent's. `workflow_id` remains a caller-supplied label.
23
+ - **Suspend cascades through delegation subtrees.** `updateAgent(id, { status: 'suspended' })` now also suspends every agent reachable through the agent's active identity delegations (pass `cascade: false` to stop only the one agent); `status: 'active'` on a suspended agent reverses exactly that cascade, leaving directly suspended descendants alone. `revoke()` suspends the subtree and revokes the identity links beneath the agent. Every affected agent is announced individually (webhooks, SSF/CAEP). The returned agent carries `cascade.suspended` / `cascade.reactivated`. New `suspendPreview(id)` returns the blast radius first (descendants, how many are active, open escalations, live delegation links).
24
+ - `escalationResolution` can now be `'timed_out'`. The server resolves escalations nobody answers within the org's `escalation_timeout_ms` as `timed_out` (platform-signed, like a human resolution), and `waitForDecisionResolution` translates it to `decision: 'deny'`, the same as a human denial. Previously polling stopped on the resolution but the verdict stayed `escalate`, so a caller's deny check never fired.
25
+ - **Swarm charter and conservation ledger.** `getSwarm()` members carry `parent_agent_id`, `is_ephemeral` and `is_guardian`. `delegateToAgent(...)` and `registerEphemeral(...)` accept `budget_tokens`: a share of the swarm's token budget granted out of the delegator's or parent's own share, refused with `409 ALLOCATION_EXCEEDED` when it would not fit (the ledger's invariant: granted to children plus own spend never exceeds what you hold). Joins that would break the swarm's charter (depth, children per parent, live members, lifetime) are refused with `409 SWARM_CHARTER_EXCEEDED` or `SWARM_EXPIRED`.
26
+ - **Guardian agents.** `listGuardianEscalations(agentId)` returns the pending escalations assigned to the guardians of the agent's swarm, and `guardianResolve(agentId, decisionId, resolution)` signs the canonical approval line (`vorim-escalation-approval|v1|…`) with the agent's cached key and submits it. A rule with `approver_role: 'guardian'` and `quorum_n` needs that many distinct approvals; one veto denies.
27
+ - **Trace context.** `beforeAction()` and `emit()` accept `trace_id` / `span_id` or a W3C `traceparent`; `foldTraceparent()` folds the header into the two ids before signing, so a v1 signature covers stored columns only. `otelAttributes(agentId)` returns `gen_ai.agent.id`, `vorim.swarm.id` and `vorim.parent_agent.id` for the agent's own spans (cached 60 s). Trace ids are correlation only, never authorisation.
28
+ - **Bulk registration.** `registerMany({ agents })` or `registerMany({ template, count })` registers up to 50 agents in one call, optionally grouped into a new swarm; each returned private key is cached like `register()`.
29
+ - **Declarative swarm spec.** `applySwarmSpec(yamlOrObject, { dryRun })` plans or applies a `vorim.swarm/v1` document (members, guardians, charter, budget and shares, breakers, tripwires, attention budget); `getSwarmSpec(swarmId)` exports the current swarm as `{ spec, yaml }`.
30
+ - **Rehearsals, score and attestation.** `rehearseSwarm(swarmId, { preset: 'hazards' | 'replay' } | { scenarios })` runs every active member through the real decision pipeline with nothing written and stores a platform-signed attestation; `listSwarmRehearsals(swarmId)`. `getSwarmScore(swarmId)` gives the members' trust as `min` (gate on it), `weighted_mean` (display) and `trimmed_mean` (peer-derived). `attestSwarm(swarmId)` issues a platform-signed statement of the swarm now (roster hash, policy hash, charter, budget, kills, rehearsal, receipt head, scores), valid 24 hours and verifiable offline against `GET /trust/keys`; `listSwarmAttestations(swarmId)`.
31
+ - **Attention budget.** `getSwarmAttention(swarmId)` reports escalations per hour against the swarm's budget, median time to resolve, mean time between interventions and the fan-out estimate after Olsen and Goodrich; `setSwarmAttention(swarmId, { perHour, onExceed })` sets the budget (past it, escalations are denied unread or the swarm is suspended).
32
+
3
33
  ## 3.23.0
4
34
 
5
35
  ### Added
@@ -0,0 +1,156 @@
1
+ import { VorimSDK } from './index.js';
2
+ import { P as PermissionScope } from './types-DphtTyIC.js';
3
+ import { E as EscalationPolicy } from './_runtime-gate-DOJUKJBu.js';
4
+
5
+ /** What a ceiling an operation is measured against. */
6
+ type CommerceLimitKind = 'order' | 'refund' | 'budget' | 'price' | 'batch';
7
+ /** How dangerous an operation is. Recorded on every receipt. */
8
+ type CommerceRisk = 'read' | 'write' | 'publish' | 'money' | 'spend' | 'message';
9
+ interface CommerceOperationSpec {
10
+ /** Least Vorim scope the operation needs. */
11
+ scope: PermissionScope;
12
+ risk: CommerceRisk;
13
+ /** Ceilings this operation is checked against. */
14
+ limits?: CommerceLimitKind[];
15
+ /** Always needs a named person's approval, whatever the amount (e.g. eBay
16
+ * purchases, which eBay's User Agreement requires a human to review). */
17
+ alwaysApprove?: boolean;
18
+ }
19
+ interface CommerceProfile {
20
+ /** Short platform key used in action targets and metadata, e.g. 'amazon-sp'. */
21
+ platform: string;
22
+ /** Human name, e.g. 'Amazon Selling Partner API'. */
23
+ display: string;
24
+ operations: Record<string, CommerceOperationSpec>;
25
+ /** Platform rules beyond ceilings (e.g. WhatsApp's 24-hour window). Return a
26
+ * reason to refuse, or null. Runs before any Vorim call. */
27
+ validate?: (action: CommerceAction) => string | null;
28
+ }
29
+ interface CommerceLimits {
30
+ /** Max value of one order or purchase, minor units (cents). */
31
+ maxOrderAmount?: number;
32
+ /** Max value of one refund, minor units. */
33
+ maxRefundAmount?: number;
34
+ /** Max daily/lifetime budget an agent may set on an ad, minor units. */
35
+ maxBudgetAmount?: number;
36
+ /** Max price move in one update, percent of the previous price (e.g. 20). */
37
+ maxPriceChangePercent?: number;
38
+ /** Max items / listings / recipients touched in one call. */
39
+ maxBatchSize?: number;
40
+ }
41
+ interface CommerceGuardConfig {
42
+ /** The acting agent's Vorim id (agid_...). */
43
+ agentId: string;
44
+ /** The seller / shop / ad / business account the agent operates on. */
45
+ accountId: string;
46
+ /** The person the agent acts for. Recorded; default escalation target. */
47
+ humanId?: string;
48
+ /** 'sandbox' or 'production'. Recorded on every receipt. Default 'production'. */
49
+ environment?: 'sandbox' | 'production';
50
+ limits?: CommerceLimits;
51
+ /** Over a ceiling: deny (default) or escalate to a named approver. */
52
+ overLimit?: 'deny' | 'escalate';
53
+ /** Named approver for over-ceiling actions. Defaults to humanId. */
54
+ approverId?: string;
55
+ /** Max wait for an approver or an escalating rule, ms. Default 300000. */
56
+ escalationTimeoutMs?: number;
57
+ /** Run every action through the runtime gate so org rules apply. Needs a key
58
+ * with runtime:decide. Default false (scope check only). */
59
+ useRuntimeControl?: boolean;
60
+ /** With useRuntimeControl, what an `escalate` verdict does. Default 'wait'. */
61
+ onEscalation?: EscalationPolicy;
62
+ /** Minimum trust score before any non-read action. Default 0 (off). */
63
+ minTrustScore?: number;
64
+ /** Fail closed (deny on any Vorim error, the default) or open. */
65
+ onError?: 'closed' | 'open';
66
+ }
67
+ interface CommerceAction {
68
+ /** The platform operation, e.g. 'createRefund'. Unknown labels are writes. */
69
+ operation: string;
70
+ /** Order, listing, SKU, campaign, conversation… the action targets. */
71
+ resourceId?: string;
72
+ /** Order / refund / budget value in minor units. */
73
+ amount?: number;
74
+ currency?: string;
75
+ /** For price updates: old and new price, same unit. */
76
+ previousPrice?: number;
77
+ newPrice?: number;
78
+ /** Items, listings or message recipients touched by this call. */
79
+ itemCount?: number;
80
+ /** Marketplace / region, e.g. 'ATVPDKIKX0DER' or 'EBAY_GB'. */
81
+ marketplace?: string;
82
+ /** Hash of the request body, so the receipt covers it without storing it. */
83
+ inputHash?: string;
84
+ /** Platform facts a profile's rules read (e.g. withinServiceWindow, optedIn). */
85
+ attributes?: Record<string, string | number | boolean>;
86
+ }
87
+ type LimitOutcome = 'within' | 'over-ceiling' | 'escalated-approved' | 'escalated-denied';
88
+ interface CommerceReceipt {
89
+ authorized: boolean;
90
+ platform: string;
91
+ agentId: string;
92
+ humanId?: string;
93
+ accountId: string;
94
+ environment: 'sandbox' | 'production';
95
+ operation: string;
96
+ risk: CommerceRisk;
97
+ scope: PermissionScope;
98
+ resourceId?: string;
99
+ amount?: number;
100
+ currency?: string;
101
+ priceChangePercent?: number;
102
+ itemCount?: number;
103
+ limitOutcome: LimitOutcome;
104
+ approverId?: string;
105
+ decisionId?: string;
106
+ result: 'success' | 'denied' | 'error';
107
+ reason?: string;
108
+ /** True once the signed audit event was ingested. */
109
+ recorded: boolean;
110
+ }
111
+ interface Authz {
112
+ authorized: boolean;
113
+ reason?: string;
114
+ outcome: LimitOutcome;
115
+ approverId?: string;
116
+ decisionId?: string;
117
+ }
118
+ declare class VorimCommerceGuard {
119
+ protected sdk: VorimSDK;
120
+ protected profile: CommerceProfile;
121
+ protected cfg: Required<Pick<CommerceGuardConfig, 'agentId' | 'accountId' | 'environment' | 'overLimit' | 'escalationTimeoutMs' | 'useRuntimeControl' | 'onEscalation' | 'minTrustScore' | 'onError'>> & {
122
+ humanId?: string;
123
+ approverId?: string;
124
+ limits: CommerceLimits;
125
+ };
126
+ constructor(sdk: VorimSDK, profile: CommerceProfile, config: CommerceGuardConfig);
127
+ /** The spec an operation resolves to (unknown labels are writes). */
128
+ specFor(operation: string): CommerceOperationSpec;
129
+ /** The first ceiling this action breaks, or null. */
130
+ breach(action: CommerceAction): string | null;
131
+ private payloadFor;
132
+ /** Decide whether the action may run. Never calls the platform. */
133
+ authorize(action: CommerceAction): Promise<Authz>;
134
+ private escalate;
135
+ /** Sign and ingest the audit event for one action. */
136
+ record(action: CommerceAction, result: 'success' | 'denied' | 'error', a?: Partial<Authz> & {
137
+ reason?: string;
138
+ }): Promise<boolean>;
139
+ /**
140
+ * Authorize, run the platform call if allowed, sign a receipt either way.
141
+ * When not authorized, `run` is never called. An error from `run` is
142
+ * recorded and rethrown with the receipt attached as `vorimReceipt`.
143
+ */
144
+ guard<T>(action: CommerceAction, run: () => Promise<T>): Promise<{
145
+ receipt: CommerceReceipt;
146
+ value?: T;
147
+ }>;
148
+ /** Shorthand for guard({ operation, ...fields }, run). */
149
+ op<T>(operation: string, fields: Omit<CommerceAction, 'operation'>, run: () => Promise<T>): Promise<{
150
+ receipt: CommerceReceipt;
151
+ value?: T | undefined;
152
+ }>;
153
+ protected receipt(action: CommerceAction, a: Partial<Authz>, result: 'success' | 'denied' | 'error', recorded: boolean): CommerceReceipt;
154
+ }
155
+
156
+ export { type CommerceProfile as C, VorimCommerceGuard as V, type CommerceGuardConfig as a, type CommerceReceipt as b };
@@ -0,0 +1,156 @@
1
+ import { VorimSDK } from './index.cjs';
2
+ import { P as PermissionScope } from './types-DphtTyIC.cjs';
3
+ import { E as EscalationPolicy } from './_runtime-gate-DOJUKJBu.cjs';
4
+
5
+ /** What a ceiling an operation is measured against. */
6
+ type CommerceLimitKind = 'order' | 'refund' | 'budget' | 'price' | 'batch';
7
+ /** How dangerous an operation is. Recorded on every receipt. */
8
+ type CommerceRisk = 'read' | 'write' | 'publish' | 'money' | 'spend' | 'message';
9
+ interface CommerceOperationSpec {
10
+ /** Least Vorim scope the operation needs. */
11
+ scope: PermissionScope;
12
+ risk: CommerceRisk;
13
+ /** Ceilings this operation is checked against. */
14
+ limits?: CommerceLimitKind[];
15
+ /** Always needs a named person's approval, whatever the amount (e.g. eBay
16
+ * purchases, which eBay's User Agreement requires a human to review). */
17
+ alwaysApprove?: boolean;
18
+ }
19
+ interface CommerceProfile {
20
+ /** Short platform key used in action targets and metadata, e.g. 'amazon-sp'. */
21
+ platform: string;
22
+ /** Human name, e.g. 'Amazon Selling Partner API'. */
23
+ display: string;
24
+ operations: Record<string, CommerceOperationSpec>;
25
+ /** Platform rules beyond ceilings (e.g. WhatsApp's 24-hour window). Return a
26
+ * reason to refuse, or null. Runs before any Vorim call. */
27
+ validate?: (action: CommerceAction) => string | null;
28
+ }
29
+ interface CommerceLimits {
30
+ /** Max value of one order or purchase, minor units (cents). */
31
+ maxOrderAmount?: number;
32
+ /** Max value of one refund, minor units. */
33
+ maxRefundAmount?: number;
34
+ /** Max daily/lifetime budget an agent may set on an ad, minor units. */
35
+ maxBudgetAmount?: number;
36
+ /** Max price move in one update, percent of the previous price (e.g. 20). */
37
+ maxPriceChangePercent?: number;
38
+ /** Max items / listings / recipients touched in one call. */
39
+ maxBatchSize?: number;
40
+ }
41
+ interface CommerceGuardConfig {
42
+ /** The acting agent's Vorim id (agid_...). */
43
+ agentId: string;
44
+ /** The seller / shop / ad / business account the agent operates on. */
45
+ accountId: string;
46
+ /** The person the agent acts for. Recorded; default escalation target. */
47
+ humanId?: string;
48
+ /** 'sandbox' or 'production'. Recorded on every receipt. Default 'production'. */
49
+ environment?: 'sandbox' | 'production';
50
+ limits?: CommerceLimits;
51
+ /** Over a ceiling: deny (default) or escalate to a named approver. */
52
+ overLimit?: 'deny' | 'escalate';
53
+ /** Named approver for over-ceiling actions. Defaults to humanId. */
54
+ approverId?: string;
55
+ /** Max wait for an approver or an escalating rule, ms. Default 300000. */
56
+ escalationTimeoutMs?: number;
57
+ /** Run every action through the runtime gate so org rules apply. Needs a key
58
+ * with runtime:decide. Default false (scope check only). */
59
+ useRuntimeControl?: boolean;
60
+ /** With useRuntimeControl, what an `escalate` verdict does. Default 'wait'. */
61
+ onEscalation?: EscalationPolicy;
62
+ /** Minimum trust score before any non-read action. Default 0 (off). */
63
+ minTrustScore?: number;
64
+ /** Fail closed (deny on any Vorim error, the default) or open. */
65
+ onError?: 'closed' | 'open';
66
+ }
67
+ interface CommerceAction {
68
+ /** The platform operation, e.g. 'createRefund'. Unknown labels are writes. */
69
+ operation: string;
70
+ /** Order, listing, SKU, campaign, conversation… the action targets. */
71
+ resourceId?: string;
72
+ /** Order / refund / budget value in minor units. */
73
+ amount?: number;
74
+ currency?: string;
75
+ /** For price updates: old and new price, same unit. */
76
+ previousPrice?: number;
77
+ newPrice?: number;
78
+ /** Items, listings or message recipients touched by this call. */
79
+ itemCount?: number;
80
+ /** Marketplace / region, e.g. 'ATVPDKIKX0DER' or 'EBAY_GB'. */
81
+ marketplace?: string;
82
+ /** Hash of the request body, so the receipt covers it without storing it. */
83
+ inputHash?: string;
84
+ /** Platform facts a profile's rules read (e.g. withinServiceWindow, optedIn). */
85
+ attributes?: Record<string, string | number | boolean>;
86
+ }
87
+ type LimitOutcome = 'within' | 'over-ceiling' | 'escalated-approved' | 'escalated-denied';
88
+ interface CommerceReceipt {
89
+ authorized: boolean;
90
+ platform: string;
91
+ agentId: string;
92
+ humanId?: string;
93
+ accountId: string;
94
+ environment: 'sandbox' | 'production';
95
+ operation: string;
96
+ risk: CommerceRisk;
97
+ scope: PermissionScope;
98
+ resourceId?: string;
99
+ amount?: number;
100
+ currency?: string;
101
+ priceChangePercent?: number;
102
+ itemCount?: number;
103
+ limitOutcome: LimitOutcome;
104
+ approverId?: string;
105
+ decisionId?: string;
106
+ result: 'success' | 'denied' | 'error';
107
+ reason?: string;
108
+ /** True once the signed audit event was ingested. */
109
+ recorded: boolean;
110
+ }
111
+ interface Authz {
112
+ authorized: boolean;
113
+ reason?: string;
114
+ outcome: LimitOutcome;
115
+ approverId?: string;
116
+ decisionId?: string;
117
+ }
118
+ declare class VorimCommerceGuard {
119
+ protected sdk: VorimSDK;
120
+ protected profile: CommerceProfile;
121
+ protected cfg: Required<Pick<CommerceGuardConfig, 'agentId' | 'accountId' | 'environment' | 'overLimit' | 'escalationTimeoutMs' | 'useRuntimeControl' | 'onEscalation' | 'minTrustScore' | 'onError'>> & {
122
+ humanId?: string;
123
+ approverId?: string;
124
+ limits: CommerceLimits;
125
+ };
126
+ constructor(sdk: VorimSDK, profile: CommerceProfile, config: CommerceGuardConfig);
127
+ /** The spec an operation resolves to (unknown labels are writes). */
128
+ specFor(operation: string): CommerceOperationSpec;
129
+ /** The first ceiling this action breaks, or null. */
130
+ breach(action: CommerceAction): string | null;
131
+ private payloadFor;
132
+ /** Decide whether the action may run. Never calls the platform. */
133
+ authorize(action: CommerceAction): Promise<Authz>;
134
+ private escalate;
135
+ /** Sign and ingest the audit event for one action. */
136
+ record(action: CommerceAction, result: 'success' | 'denied' | 'error', a?: Partial<Authz> & {
137
+ reason?: string;
138
+ }): Promise<boolean>;
139
+ /**
140
+ * Authorize, run the platform call if allowed, sign a receipt either way.
141
+ * When not authorized, `run` is never called. An error from `run` is
142
+ * recorded and rethrown with the receipt attached as `vorimReceipt`.
143
+ */
144
+ guard<T>(action: CommerceAction, run: () => Promise<T>): Promise<{
145
+ receipt: CommerceReceipt;
146
+ value?: T;
147
+ }>;
148
+ /** Shorthand for guard({ operation, ...fields }, run). */
149
+ op<T>(operation: string, fields: Omit<CommerceAction, 'operation'>, run: () => Promise<T>): Promise<{
150
+ receipt: CommerceReceipt;
151
+ value?: T | undefined;
152
+ }>;
153
+ protected receipt(action: CommerceAction, a: Partial<Authz>, result: 'success' | 'denied' | 'error', recorded: boolean): CommerceReceipt;
154
+ }
155
+
156
+ export { type CommerceProfile as C, VorimCommerceGuard as V, type CommerceGuardConfig as a, type CommerceReceipt as b };