@vorim/sdk 4.0.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 (64) hide show
  1. package/CHANGELOG.md +7 -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 +6 -1
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +5 -0
  7. package/dist/index.d.ts +5 -0
  8. package/dist/index.js +6 -1
  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/delivery.cjs +327 -0
  17. package/dist/integrations/delivery.cjs.map +1 -0
  18. package/dist/integrations/delivery.d.cts +33 -0
  19. package/dist/integrations/delivery.d.ts +33 -0
  20. package/dist/integrations/delivery.js +296 -0
  21. package/dist/integrations/delivery.js.map +1 -0
  22. package/dist/integrations/ebay.cjs +350 -0
  23. package/dist/integrations/ebay.cjs.map +1 -0
  24. package/dist/integrations/ebay.d.cts +73 -0
  25. package/dist/integrations/ebay.d.ts +73 -0
  26. package/dist/integrations/ebay.js +321 -0
  27. package/dist/integrations/ebay.js.map +1 -0
  28. package/dist/integrations/etsy.cjs +330 -0
  29. package/dist/integrations/etsy.cjs.map +1 -0
  30. package/dist/integrations/etsy.d.cts +41 -0
  31. package/dist/integrations/etsy.d.ts +41 -0
  32. package/dist/integrations/etsy.js +301 -0
  33. package/dist/integrations/etsy.js.map +1 -0
  34. package/dist/integrations/google-merchant.cjs +332 -0
  35. package/dist/integrations/google-merchant.cjs.map +1 -0
  36. package/dist/integrations/google-merchant.d.cts +43 -0
  37. package/dist/integrations/google-merchant.d.ts +43 -0
  38. package/dist/integrations/google-merchant.js +303 -0
  39. package/dist/integrations/google-merchant.js.map +1 -0
  40. package/dist/integrations/meta.cjs +375 -0
  41. package/dist/integrations/meta.cjs.map +1 -0
  42. package/dist/integrations/meta.d.cts +83 -0
  43. package/dist/integrations/meta.d.ts +83 -0
  44. package/dist/integrations/meta.js +346 -0
  45. package/dist/integrations/meta.js.map +1 -0
  46. package/dist/integrations/social-ads.cjs +328 -0
  47. package/dist/integrations/social-ads.cjs.map +1 -0
  48. package/dist/integrations/social-ads.d.cts +36 -0
  49. package/dist/integrations/social-ads.d.ts +36 -0
  50. package/dist/integrations/social-ads.js +297 -0
  51. package/dist/integrations/social-ads.js.map +1 -0
  52. package/dist/integrations/tiktok-shop.cjs +334 -0
  53. package/dist/integrations/tiktok-shop.cjs.map +1 -0
  54. package/dist/integrations/tiktok-shop.d.cts +44 -0
  55. package/dist/integrations/tiktok-shop.d.ts +44 -0
  56. package/dist/integrations/tiktok-shop.js +305 -0
  57. package/dist/integrations/tiktok-shop.js.map +1 -0
  58. package/dist/integrations/walmart.cjs +344 -0
  59. package/dist/integrations/walmart.cjs.map +1 -0
  60. package/dist/integrations/walmart.d.cts +60 -0
  61. package/dist/integrations/walmart.d.ts +60 -0
  62. package/dist/integrations/walmart.js +315 -0
  63. package/dist/integrations/walmart.js.map +1 -0
  64. package/package.json +92 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
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
+
3
10
  ## 4.0.0
4
11
 
5
12
  ### Changed (breaking)
@@ -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 };
package/dist/index.cjs CHANGED
@@ -931,7 +931,7 @@ async function verifyHttpRequest(request, options) {
931
931
  }
932
932
 
933
933
  // src/index.ts
934
- var SDK_VERSION = true ? "4.0.0" : "0.0.0";
934
+ var SDK_VERSION = true ? "4.1.0" : "0.0.0";
935
935
  var USER_AGENT = `vorim-sdk/${SDK_VERSION}`;
936
936
  function sleep(ms) {
937
937
  return new Promise((resolve) => setTimeout(resolve, ms));
@@ -1598,6 +1598,11 @@ var VorimSDK = class _VorimSDK {
1598
1598
  * Create or update a token budget for an agent or workflow. One budget per
1599
1599
  * (scope, scope_ref) — calling this again for the same target updates it.
1600
1600
  *
1601
+ * A budget is a ceiling; a policy rule enforces it. Add a rule with
1602
+ * `match_conditions: { token_budget_gt: { scope } }` and a `deny` (or
1603
+ * `escalate`) decision, otherwise actions are still allowed once the budget
1604
+ * is used up.
1605
+ *
1601
1606
  * @example
1602
1607
  * await vorim.setBudget({
1603
1608
  * scope: 'workflow', scope_ref: 'nightly-summariser',