@vorim/sdk 3.10.0 → 3.12.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 +13 -0
- package/dist/index.cjs +1 -1
- package/dist/index.js +1 -1
- package/dist/integrations/cloudflare.cjs +134 -0
- package/dist/integrations/cloudflare.cjs.map +1 -0
- package/dist/integrations/cloudflare.d.cts +93 -0
- package/dist/integrations/cloudflare.d.ts +93 -0
- package/dist/integrations/cloudflare.js +108 -0
- package/dist/integrations/cloudflare.js.map +1 -0
- package/dist/integrations/shopify.cjs +203 -0
- package/dist/integrations/shopify.cjs.map +1 -0
- package/dist/integrations/shopify.d.cts +175 -0
- package/dist/integrations/shopify.d.ts +175 -0
- package/dist/integrations/shopify.js +177 -0
- package/dist/integrations/shopify.js.map +1 -0
- package/dist/integrations/truanon.cjs +188 -0
- package/dist/integrations/truanon.cjs.map +1 -0
- package/dist/integrations/truanon.d.cts +115 -0
- package/dist/integrations/truanon.d.ts +115 -0
- package/dist/integrations/truanon.js +161 -0
- package/dist/integrations/truanon.js.map +1 -0
- package/dist/integrations/web-bot-auth.cjs +143 -0
- package/dist/integrations/web-bot-auth.cjs.map +1 -0
- package/dist/integrations/web-bot-auth.d.cts +51 -0
- package/dist/integrations/web-bot-auth.d.ts +51 -0
- package/dist/integrations/web-bot-auth.js +108 -0
- package/dist/integrations/web-bot-auth.js.map +1 -0
- package/package.json +41 -1
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
|
|
20
|
+
// src/integrations/shopify.ts
|
|
21
|
+
var shopify_exports = {};
|
|
22
|
+
__export(shopify_exports, {
|
|
23
|
+
VorimShopify: () => VorimShopify,
|
|
24
|
+
createVorimShopify: () => createVorimShopify
|
|
25
|
+
});
|
|
26
|
+
module.exports = __toCommonJS(shopify_exports);
|
|
27
|
+
var OPERATION_SCOPE = {
|
|
28
|
+
read: "agent:read",
|
|
29
|
+
orderCreate: "agent:write",
|
|
30
|
+
inventoryAdjustQuantities: "agent:write",
|
|
31
|
+
fulfillmentCreate: "agent:write",
|
|
32
|
+
returnProcess: "agent:write",
|
|
33
|
+
productCreate: "agent:write",
|
|
34
|
+
productUpdate: "agent:write",
|
|
35
|
+
refundCreate: "agent:transact"
|
|
36
|
+
};
|
|
37
|
+
var VorimShopify = class {
|
|
38
|
+
sdk;
|
|
39
|
+
agentId;
|
|
40
|
+
shopDomain;
|
|
41
|
+
humanId;
|
|
42
|
+
minTrustScore;
|
|
43
|
+
maxRefundAmount;
|
|
44
|
+
onError;
|
|
45
|
+
constructor(sdk, config) {
|
|
46
|
+
if (!config?.agentId) throw new Error("[vorim] Shopify integration requires an agentId.");
|
|
47
|
+
if (!config?.shopDomain) throw new Error("[vorim] Shopify integration requires a shopDomain.");
|
|
48
|
+
this.sdk = sdk;
|
|
49
|
+
this.agentId = config.agentId;
|
|
50
|
+
this.shopDomain = config.shopDomain;
|
|
51
|
+
this.humanId = config.humanId;
|
|
52
|
+
this.minTrustScore = config.minTrustScore ?? 0;
|
|
53
|
+
this.maxRefundAmount = config.maxRefundAmount;
|
|
54
|
+
this.onError = config.onError ?? "closed";
|
|
55
|
+
}
|
|
56
|
+
/** The Vorim scope a given operation requires. Unknown mutations fall back to
|
|
57
|
+
* agent:write (a mutation is at least a write). */
|
|
58
|
+
scopeFor(operation) {
|
|
59
|
+
return OPERATION_SCOPE[operation] ?? "agent:write";
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Check whether the acting agent may run this store operation, before it
|
|
63
|
+
* runs. Enforces (in order): trust floor, refund ceiling, permission scope.
|
|
64
|
+
* Returns { authorized, reason }.
|
|
65
|
+
*/
|
|
66
|
+
async authorize(action) {
|
|
67
|
+
const scope = this.scopeFor(action.operation);
|
|
68
|
+
if (action.operation === "refundCreate" && this.maxRefundAmount != null && typeof action.amount === "number" && action.amount > this.maxRefundAmount) {
|
|
69
|
+
return {
|
|
70
|
+
authorized: false,
|
|
71
|
+
reason: `refund ${action.amount} exceeds this agent's ceiling of ${this.maxRefundAmount}`
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
try {
|
|
75
|
+
if (this.minTrustScore > 0) {
|
|
76
|
+
const trust = await this.sdk.verify(this.agentId);
|
|
77
|
+
if ((trust?.trust_score ?? 0) < this.minTrustScore) {
|
|
78
|
+
return { authorized: false, reason: `trust score below ${this.minTrustScore}` };
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
const perm = await this.sdk.check(this.agentId, scope);
|
|
82
|
+
return perm.allowed ? { authorized: true } : { authorized: false, reason: perm.reason ?? `missing scope ${scope}` };
|
|
83
|
+
} catch (e) {
|
|
84
|
+
return this.onError === "open" ? { authorized: true, reason: "vorim unreachable, failed open" } : { authorized: false, reason: `vorim unreachable: ${e?.message ?? "error"}` };
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Emit a source-signed audit event for a store operation and return whether
|
|
89
|
+
* it was recorded. Called after the mutation runs (or after a denial). The
|
|
90
|
+
* event names the agent, the shop, and the human the agent acts for, so the
|
|
91
|
+
* record is attributable and independently verifiable offline.
|
|
92
|
+
*/
|
|
93
|
+
async record(action, result, reason) {
|
|
94
|
+
const scope = this.scopeFor(action.operation);
|
|
95
|
+
try {
|
|
96
|
+
await this.sdk.emit({
|
|
97
|
+
agent_id: this.agentId,
|
|
98
|
+
event_type: "api_request",
|
|
99
|
+
action: `shopify:${action.operation}${action.resourceId ? " " + action.resourceId : ""}`,
|
|
100
|
+
resource: action.resourceId || this.shopDomain,
|
|
101
|
+
permission: scope,
|
|
102
|
+
result,
|
|
103
|
+
input_hash: action.inputHash,
|
|
104
|
+
metadata: {
|
|
105
|
+
integration: "shopify-admin",
|
|
106
|
+
shop_domain: this.shopDomain,
|
|
107
|
+
acts_for_human: this.humanId,
|
|
108
|
+
operation: action.operation,
|
|
109
|
+
...action.amount != null ? { amount: action.amount } : {},
|
|
110
|
+
...action.currency ? { currency: action.currency } : {},
|
|
111
|
+
...reason ? { reason } : {}
|
|
112
|
+
}
|
|
113
|
+
}, { sign: true });
|
|
114
|
+
return true;
|
|
115
|
+
} catch {
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* The full flow for one store operation: authorize, run the Admin GraphQL
|
|
121
|
+
* mutation if allowed, sign a receipt either way. If not authorized, `run` is
|
|
122
|
+
* never called (the mutation does not happen). Rethrows an error from `run`
|
|
123
|
+
* after recording it, with the receipt attached as `vorimReceipt`, so your
|
|
124
|
+
* handler still sees Shopify failures.
|
|
125
|
+
*/
|
|
126
|
+
async guard(action, run) {
|
|
127
|
+
const auth = await this.authorize(action);
|
|
128
|
+
if (!auth.authorized) {
|
|
129
|
+
const recorded = await this.record(action, "denied", auth.reason);
|
|
130
|
+
return { receipt: this.receipt(action, false, "denied", auth.reason, recorded) };
|
|
131
|
+
}
|
|
132
|
+
try {
|
|
133
|
+
const value = await run();
|
|
134
|
+
const recorded = await this.record(action, "success");
|
|
135
|
+
return { receipt: this.receipt(action, true, "success", void 0, recorded), value };
|
|
136
|
+
} catch (e) {
|
|
137
|
+
const recorded = await this.record(action, "error", e?.message);
|
|
138
|
+
throw Object.assign(e ?? new Error("shopify operation failed"), {
|
|
139
|
+
vorimReceipt: this.receipt(action, true, "error", e?.message, recorded)
|
|
140
|
+
});
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
// --- Named helpers for the high-risk Admin mutations -----------------------
|
|
144
|
+
// Each wraps guard() with the right operation label so the scope and receipt
|
|
145
|
+
// are correct without the caller having to remember the mapping. You pass the
|
|
146
|
+
// GraphQL call as `run`; this layer never talks to Shopify itself.
|
|
147
|
+
/** Guard an `orderCreate`. Requires agent:write. */
|
|
148
|
+
orderCreate(meta, run) {
|
|
149
|
+
return this.guard({ operation: "orderCreate", resourceId: meta.orderId, inputHash: meta.inputHash }, run);
|
|
150
|
+
}
|
|
151
|
+
/** Guard a `refundCreate`. Requires agent:transact AND stays within
|
|
152
|
+
* `maxRefundAmount` if one was configured. `amount` is in minor units. */
|
|
153
|
+
refundCreate(meta, run) {
|
|
154
|
+
return this.guard(
|
|
155
|
+
{ operation: "refundCreate", resourceId: meta.orderId, amount: meta.amount, currency: meta.currency, inputHash: meta.inputHash },
|
|
156
|
+
run
|
|
157
|
+
);
|
|
158
|
+
}
|
|
159
|
+
/** Guard an `inventoryAdjustQuantities`. Requires agent:write. */
|
|
160
|
+
inventoryAdjustQuantities(meta, run) {
|
|
161
|
+
return this.guard({ operation: "inventoryAdjustQuantities", resourceId: meta.resourceId, inputHash: meta.inputHash }, run);
|
|
162
|
+
}
|
|
163
|
+
/** Guard a `fulfillmentCreate`. Requires agent:write. */
|
|
164
|
+
fulfillmentCreate(meta, run) {
|
|
165
|
+
return this.guard({ operation: "fulfillmentCreate", resourceId: meta.orderId, inputHash: meta.inputHash }, run);
|
|
166
|
+
}
|
|
167
|
+
/** Guard a `returnProcess`. Requires agent:write. */
|
|
168
|
+
returnProcess(meta, run) {
|
|
169
|
+
return this.guard({ operation: "returnProcess", resourceId: meta.resourceId, inputHash: meta.inputHash }, run);
|
|
170
|
+
}
|
|
171
|
+
/** Guard a `productCreate` or `productUpdate`. Requires agent:write. */
|
|
172
|
+
productWrite(meta, run) {
|
|
173
|
+
return this.guard(
|
|
174
|
+
{ operation: meta.operation ?? "productUpdate", resourceId: meta.productId, inputHash: meta.inputHash },
|
|
175
|
+
run
|
|
176
|
+
);
|
|
177
|
+
}
|
|
178
|
+
receipt(action, authorized, result, reason, recorded) {
|
|
179
|
+
return {
|
|
180
|
+
authorized,
|
|
181
|
+
agentId: this.agentId,
|
|
182
|
+
humanId: this.humanId,
|
|
183
|
+
shopDomain: this.shopDomain,
|
|
184
|
+
operation: action.operation,
|
|
185
|
+
resourceId: action.resourceId,
|
|
186
|
+
amount: action.amount,
|
|
187
|
+
currency: action.currency,
|
|
188
|
+
result,
|
|
189
|
+
scope: this.scopeFor(action.operation),
|
|
190
|
+
reason,
|
|
191
|
+
recorded
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
};
|
|
195
|
+
function createVorimShopify(sdk, config) {
|
|
196
|
+
return new VorimShopify(sdk, config);
|
|
197
|
+
}
|
|
198
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
199
|
+
0 && (module.exports = {
|
|
200
|
+
VorimShopify,
|
|
201
|
+
createVorimShopify
|
|
202
|
+
});
|
|
203
|
+
//# sourceMappingURL=shopify.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../../src/integrations/shopify.ts"],"sourcesContent":["// ============================================================================\n// Vorim AI — Shopify (merchant-side store operations) Integration\n//\n// This guards an AI agent that MANAGES a Shopify store through the Admin\n// GraphQL API — creating orders, issuing refunds, adjusting inventory,\n// fulfilling, processing returns, editing products. Before each mutation runs\n// it checks the acting agent holds the right permission (and, for refunds, that\n// the amount is within a delegated ceiling), then signs a tamper-evident audit\n// record of what the agent did.\n//\n// WHY MERCHANT-SIDE, NOT CHECKOUT\n// The buyer-side purchase moment is already covered by signed rails: ACP's\n// delegated payment token + allowance, Visa's Trusted Agent Protocol and Web\n// Bot Auth (per-agent Ed25519 identity over the HTTP request — Vorim already\n// integrates Web Bot Auth), and AP2's signed mandates. Those prove identity and\n// payment authorization AT THE MOMENT OF PURCHASE and then stop at the\n// transaction boundary. None of them produce a signed, attenuated record of an\n// agent's operations ON THE STORE. On the Admin API an agent authenticates with\n// a single OAuth token and coarse write_* scopes: every agent on that token\n// looks identical, there is no way to cap a sub-agent below write_orders, and\n// nothing proves agent X (not agent Y) issued a given refundCreate. That is the\n// gap this fills. It COMPOSES WITH Web Bot Auth / TAP on the buyer side rather\n// than competing with the payment rails.\n//\n// SCOPE MAPPING (uses Vorim's three real scopes)\n// read Admin data -> agent:read\n// mutate the store -> agent:write (orders, inventory, fulfil,\n// returns, products)\n// move money back to a buyer -> agent:transact (refundCreate) + amount cap\n//\n// This layer never holds a Shopify token and never calls Shopify itself. You\n// pass it the mutation to run; it authorizes, runs it, and signs the receipt.\n//\n// Usage:\n// import createVorim from '@vorim/sdk';\n// import { createVorimShopify } from '@vorim/sdk/integrations/shopify';\n//\n// const vorim = createVorim({ apiKey: 'agid_sk_...' });\n// const shop = createVorimShopify(vorim, {\n// agentId: 'agid_abc123',\n// shopDomain: 'acme.myshopify.com',\n// humanId: 'user_42', // the person the agent acts for\n// maxRefundAmount: 20000, // cap this agent's refunds at $200.00 (cents)\n// });\n//\n// // Wrap the Admin GraphQL call you were going to make anyway:\n// const { receipt, value } = await shop.refundCreate(\n// { orderId: 'gid://shopify/Order/123', amount: 4999, currency: 'USD' },\n// () => adminClient.request(REFUND_CREATE_MUTATION, { input }),\n// );\n// if (!receipt.authorized) console.warn(receipt.reason);\n// ============================================================================\n\nimport type { VorimSDK } from '../index.js';\nimport type { PermissionScope } from '../types.js';\n\n/** The Admin GraphQL mutations this guard knows how to classify. Any other\n * label is accepted too; it just defaults to the 'write' risk tier. */\nexport type ShopifyOperation =\n | 'orderCreate'\n | 'refundCreate'\n | 'inventoryAdjustQuantities'\n | 'fulfillmentCreate'\n | 'returnProcess'\n | 'productCreate'\n | 'productUpdate'\n | 'read';\n\n/** Map each Admin mutation to the least Vorim scope that should be required to\n * run it. Reads need read; store mutations need write; moving money back to a\n * customer (refundCreate) needs transact, the same scope Vorim requires for\n * any value-moving action. */\nconst OPERATION_SCOPE: Record<string, PermissionScope> = {\n read: 'agent:read',\n orderCreate: 'agent:write',\n inventoryAdjustQuantities: 'agent:write',\n fulfillmentCreate: 'agent:write',\n returnProcess: 'agent:write',\n productCreate: 'agent:write',\n productUpdate: 'agent:write',\n refundCreate: 'agent:transact',\n};\n\nexport interface ShopifyGuardConfig {\n /** The acting agent's Vorim id (agid_...). */\n agentId: string;\n /** The store this agent operates on, e.g. 'acme.myshopify.com'. Recorded in\n * every receipt so an action is attributable to a specific shop. */\n shopDomain: string;\n /** The human/principal the agent acts for. Recorded in every receipt so a\n * store action is attributable to a person, not just a machine. */\n humanId?: string;\n /** Minimum trust score the acting agent must hold before any mutation runs.\n * Default 0 (off). */\n minTrustScore?: number;\n /** Attenuation: cap the total this agent may refund in a single refundCreate,\n * in the currency's minor unit (e.g. cents). Shopify's coarse write_orders\n * scope cannot express this; Vorim can. Omit for no ceiling. */\n maxRefundAmount?: number;\n /** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */\n onError?: 'closed' | 'open';\n}\n\nexport interface ShopifyAction {\n /** The Admin GraphQL mutation being run, e.g. 'refundCreate'. Drives the\n * scope requirement. Unknown labels default to the 'write' tier. */\n operation: ShopifyOperation | string;\n /** The Shopify resource the action targets, e.g. an order or product GID. */\n resourceId?: string;\n /** For refundCreate: the amount moving back to the customer, in the minor\n * unit (cents). Checked against maxRefundAmount. */\n amount?: number;\n /** Currency code for `amount`, e.g. 'USD'. Informational. */\n currency?: string;\n /** Optional hash of the mutation variables so the receipt covers the exact\n * input without the guard storing it. */\n inputHash?: string;\n}\n\n/** An offline-verifiable receipt for one Shopify store operation. */\nexport interface ShopifyReceipt {\n authorized: boolean;\n agentId: string;\n humanId?: string;\n shopDomain: string;\n operation: string;\n resourceId?: string;\n amount?: number;\n currency?: string;\n result: 'success' | 'denied' | 'error';\n scope: PermissionScope;\n /** Reason a check failed, when authorized is false. */\n reason?: string;\n /** True once the audit event was signed and ingested. */\n recorded: boolean;\n}\n\nexport class VorimShopify {\n private sdk: VorimSDK;\n private agentId: string;\n private shopDomain: string;\n private humanId?: string;\n private minTrustScore: number;\n private maxRefundAmount?: number;\n private onError: 'closed' | 'open';\n\n constructor(sdk: VorimSDK, config: ShopifyGuardConfig) {\n if (!config?.agentId) throw new Error('[vorim] Shopify integration requires an agentId.');\n if (!config?.shopDomain) throw new Error('[vorim] Shopify integration requires a shopDomain.');\n this.sdk = sdk;\n this.agentId = config.agentId;\n this.shopDomain = config.shopDomain;\n this.humanId = config.humanId;\n this.minTrustScore = config.minTrustScore ?? 0;\n this.maxRefundAmount = config.maxRefundAmount;\n this.onError = config.onError ?? 'closed';\n }\n\n /** The Vorim scope a given operation requires. Unknown mutations fall back to\n * agent:write (a mutation is at least a write). */\n private scopeFor(operation: string): PermissionScope {\n return OPERATION_SCOPE[operation] ?? 'agent:write';\n }\n\n /**\n * Check whether the acting agent may run this store operation, before it\n * runs. Enforces (in order): trust floor, refund ceiling, permission scope.\n * Returns { authorized, reason }.\n */\n async authorize(action: ShopifyAction): Promise<{ authorized: boolean; reason?: string }> {\n const scope = this.scopeFor(action.operation);\n\n // Attenuation: a refund above this agent's delegated ceiling is denied\n // before any Vorim round-trip. This is the differentiator over Shopify's\n // coarse write_orders scope, which cannot bound a refund amount.\n if (\n action.operation === 'refundCreate' &&\n this.maxRefundAmount != null &&\n typeof action.amount === 'number' &&\n action.amount > this.maxRefundAmount\n ) {\n return {\n authorized: false,\n reason: `refund ${action.amount} exceeds this agent's ceiling of ${this.maxRefundAmount}`,\n };\n }\n\n try {\n // Trust floor (optional): refuse low-trust agents up front.\n if (this.minTrustScore > 0) {\n const trust = await this.sdk.verify(this.agentId);\n if ((trust?.trust_score ?? 0) < this.minTrustScore) {\n return { authorized: false, reason: `trust score below ${this.minTrustScore}` };\n }\n }\n const perm = await this.sdk.check(this.agentId, scope);\n return perm.allowed\n ? { authorized: true }\n : { authorized: false, reason: perm.reason ?? `missing scope ${scope}` };\n } catch (e: any) {\n // Fail closed by default: a check we could not complete is a deny.\n return this.onError === 'open'\n ? { authorized: true, reason: 'vorim unreachable, failed open' }\n : { authorized: false, reason: `vorim unreachable: ${e?.message ?? 'error'}` };\n }\n }\n\n /**\n * Emit a source-signed audit event for a store operation and return whether\n * it was recorded. Called after the mutation runs (or after a denial). The\n * event names the agent, the shop, and the human the agent acts for, so the\n * record is attributable and independently verifiable offline.\n */\n async record(action: ShopifyAction, result: 'success' | 'denied' | 'error', reason?: string): Promise<boolean> {\n const scope = this.scopeFor(action.operation);\n try {\n await this.sdk.emit({\n agent_id: this.agentId,\n event_type: 'api_request',\n action: `shopify:${action.operation}${action.resourceId ? ' ' + action.resourceId : ''}`,\n resource: action.resourceId || this.shopDomain,\n permission: scope,\n result,\n input_hash: action.inputHash,\n metadata: {\n integration: 'shopify-admin',\n shop_domain: this.shopDomain,\n acts_for_human: this.humanId,\n operation: action.operation,\n ...(action.amount != null ? { amount: action.amount } : {}),\n ...(action.currency ? { currency: action.currency } : {}),\n ...(reason ? { reason } : {}),\n },\n }, { sign: true }); // source-signed: the agent's key signs the record\n return true;\n } catch {\n return false;\n }\n }\n\n /**\n * The full flow for one store operation: authorize, run the Admin GraphQL\n * mutation if allowed, sign a receipt either way. If not authorized, `run` is\n * never called (the mutation does not happen). Rethrows an error from `run`\n * after recording it, with the receipt attached as `vorimReceipt`, so your\n * handler still sees Shopify failures.\n */\n async guard<T>(action: ShopifyAction, run: () => Promise<T>): Promise<{ receipt: ShopifyReceipt; value?: T }> {\n const auth = await this.authorize(action);\n if (!auth.authorized) {\n const recorded = await this.record(action, 'denied', auth.reason);\n return { receipt: this.receipt(action, false, 'denied', auth.reason, recorded) };\n }\n try {\n const value = await run();\n const recorded = await this.record(action, 'success');\n return { receipt: this.receipt(action, true, 'success', undefined, recorded), value };\n } catch (e: any) {\n const recorded = await this.record(action, 'error', e?.message);\n throw Object.assign(e ?? new Error('shopify operation failed'), {\n vorimReceipt: this.receipt(action, true, 'error', e?.message, recorded),\n });\n }\n }\n\n // --- Named helpers for the high-risk Admin mutations -----------------------\n // Each wraps guard() with the right operation label so the scope and receipt\n // are correct without the caller having to remember the mapping. You pass the\n // GraphQL call as `run`; this layer never talks to Shopify itself.\n\n /** Guard an `orderCreate`. Requires agent:write. */\n orderCreate<T>(meta: { orderId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'orderCreate', resourceId: meta.orderId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard a `refundCreate`. Requires agent:transact AND stays within\n * `maxRefundAmount` if one was configured. `amount` is in minor units. */\n refundCreate<T>(meta: { orderId?: string; amount?: number; currency?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard(\n { operation: 'refundCreate', resourceId: meta.orderId, amount: meta.amount, currency: meta.currency, inputHash: meta.inputHash },\n run,\n );\n }\n\n /** Guard an `inventoryAdjustQuantities`. Requires agent:write. */\n inventoryAdjustQuantities<T>(meta: { resourceId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'inventoryAdjustQuantities', resourceId: meta.resourceId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard a `fulfillmentCreate`. Requires agent:write. */\n fulfillmentCreate<T>(meta: { orderId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'fulfillmentCreate', resourceId: meta.orderId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard a `returnProcess`. Requires agent:write. */\n returnProcess<T>(meta: { resourceId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard({ operation: 'returnProcess', resourceId: meta.resourceId, inputHash: meta.inputHash }, run);\n }\n\n /** Guard a `productCreate` or `productUpdate`. Requires agent:write. */\n productWrite<T>(meta: { operation?: 'productCreate' | 'productUpdate'; productId?: string; inputHash?: string }, run: () => Promise<T>) {\n return this.guard(\n { operation: meta.operation ?? 'productUpdate', resourceId: meta.productId, inputHash: meta.inputHash },\n run,\n );\n }\n\n private receipt(\n action: ShopifyAction,\n authorized: boolean,\n result: 'success' | 'denied' | 'error',\n reason: string | undefined,\n recorded: boolean,\n ): ShopifyReceipt {\n return {\n authorized,\n agentId: this.agentId,\n humanId: this.humanId,\n shopDomain: this.shopDomain,\n operation: action.operation,\n resourceId: action.resourceId,\n amount: action.amount,\n currency: action.currency,\n result,\n scope: this.scopeFor(action.operation),\n reason,\n recorded,\n };\n }\n}\n\n/**\n * Create a VorimShopify guard around a Vorim SDK instance.\n *\n * @example\n * ```typescript\n * import createVorim from '@vorim/sdk';\n * import { createVorimShopify } from '@vorim/sdk/integrations/shopify';\n *\n * const vorim = createVorim({ apiKey: 'agid_sk_...' });\n * const shop = createVorimShopify(vorim, {\n * agentId: 'agid_abc123',\n * shopDomain: 'acme.myshopify.com',\n * humanId: 'user_42',\n * maxRefundAmount: 20000, // this agent can refund up to $200.00\n * });\n *\n * const { receipt, value } = await shop.refundCreate(\n * { orderId: 'gid://shopify/Order/123', amount: 4999, currency: 'USD' },\n * () => adminClient.request(REFUND_CREATE, { input }),\n * );\n * ```\n */\nexport function createVorimShopify(sdk: VorimSDK, config: ShopifyGuardConfig): VorimShopify {\n return new VorimShopify(sdk, config);\n}\n"],"mappings":"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","names":[]}
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { VorimSDK } from '../index.cjs';
|
|
2
|
+
import { P as PermissionScope } from '../types-zzK9YOoa.cjs';
|
|
3
|
+
|
|
4
|
+
/** The Admin GraphQL mutations this guard knows how to classify. Any other
|
|
5
|
+
* label is accepted too; it just defaults to the 'write' risk tier. */
|
|
6
|
+
type ShopifyOperation = 'orderCreate' | 'refundCreate' | 'inventoryAdjustQuantities' | 'fulfillmentCreate' | 'returnProcess' | 'productCreate' | 'productUpdate' | 'read';
|
|
7
|
+
interface ShopifyGuardConfig {
|
|
8
|
+
/** The acting agent's Vorim id (agid_...). */
|
|
9
|
+
agentId: string;
|
|
10
|
+
/** The store this agent operates on, e.g. 'acme.myshopify.com'. Recorded in
|
|
11
|
+
* every receipt so an action is attributable to a specific shop. */
|
|
12
|
+
shopDomain: string;
|
|
13
|
+
/** The human/principal the agent acts for. Recorded in every receipt so a
|
|
14
|
+
* store action is attributable to a person, not just a machine. */
|
|
15
|
+
humanId?: string;
|
|
16
|
+
/** Minimum trust score the acting agent must hold before any mutation runs.
|
|
17
|
+
* Default 0 (off). */
|
|
18
|
+
minTrustScore?: number;
|
|
19
|
+
/** Attenuation: cap the total this agent may refund in a single refundCreate,
|
|
20
|
+
* in the currency's minor unit (e.g. cents). Shopify's coarse write_orders
|
|
21
|
+
* scope cannot express this; Vorim can. Omit for no ceiling. */
|
|
22
|
+
maxRefundAmount?: number;
|
|
23
|
+
/** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */
|
|
24
|
+
onError?: 'closed' | 'open';
|
|
25
|
+
}
|
|
26
|
+
interface ShopifyAction {
|
|
27
|
+
/** The Admin GraphQL mutation being run, e.g. 'refundCreate'. Drives the
|
|
28
|
+
* scope requirement. Unknown labels default to the 'write' tier. */
|
|
29
|
+
operation: ShopifyOperation | string;
|
|
30
|
+
/** The Shopify resource the action targets, e.g. an order or product GID. */
|
|
31
|
+
resourceId?: string;
|
|
32
|
+
/** For refundCreate: the amount moving back to the customer, in the minor
|
|
33
|
+
* unit (cents). Checked against maxRefundAmount. */
|
|
34
|
+
amount?: number;
|
|
35
|
+
/** Currency code for `amount`, e.g. 'USD'. Informational. */
|
|
36
|
+
currency?: string;
|
|
37
|
+
/** Optional hash of the mutation variables so the receipt covers the exact
|
|
38
|
+
* input without the guard storing it. */
|
|
39
|
+
inputHash?: string;
|
|
40
|
+
}
|
|
41
|
+
/** An offline-verifiable receipt for one Shopify store operation. */
|
|
42
|
+
interface ShopifyReceipt {
|
|
43
|
+
authorized: boolean;
|
|
44
|
+
agentId: string;
|
|
45
|
+
humanId?: string;
|
|
46
|
+
shopDomain: string;
|
|
47
|
+
operation: string;
|
|
48
|
+
resourceId?: string;
|
|
49
|
+
amount?: number;
|
|
50
|
+
currency?: string;
|
|
51
|
+
result: 'success' | 'denied' | 'error';
|
|
52
|
+
scope: PermissionScope;
|
|
53
|
+
/** Reason a check failed, when authorized is false. */
|
|
54
|
+
reason?: string;
|
|
55
|
+
/** True once the audit event was signed and ingested. */
|
|
56
|
+
recorded: boolean;
|
|
57
|
+
}
|
|
58
|
+
declare class VorimShopify {
|
|
59
|
+
private sdk;
|
|
60
|
+
private agentId;
|
|
61
|
+
private shopDomain;
|
|
62
|
+
private humanId?;
|
|
63
|
+
private minTrustScore;
|
|
64
|
+
private maxRefundAmount?;
|
|
65
|
+
private onError;
|
|
66
|
+
constructor(sdk: VorimSDK, config: ShopifyGuardConfig);
|
|
67
|
+
/** The Vorim scope a given operation requires. Unknown mutations fall back to
|
|
68
|
+
* agent:write (a mutation is at least a write). */
|
|
69
|
+
private scopeFor;
|
|
70
|
+
/**
|
|
71
|
+
* Check whether the acting agent may run this store operation, before it
|
|
72
|
+
* runs. Enforces (in order): trust floor, refund ceiling, permission scope.
|
|
73
|
+
* Returns { authorized, reason }.
|
|
74
|
+
*/
|
|
75
|
+
authorize(action: ShopifyAction): Promise<{
|
|
76
|
+
authorized: boolean;
|
|
77
|
+
reason?: string;
|
|
78
|
+
}>;
|
|
79
|
+
/**
|
|
80
|
+
* Emit a source-signed audit event for a store operation and return whether
|
|
81
|
+
* it was recorded. Called after the mutation runs (or after a denial). The
|
|
82
|
+
* event names the agent, the shop, and the human the agent acts for, so the
|
|
83
|
+
* record is attributable and independently verifiable offline.
|
|
84
|
+
*/
|
|
85
|
+
record(action: ShopifyAction, result: 'success' | 'denied' | 'error', reason?: string): Promise<boolean>;
|
|
86
|
+
/**
|
|
87
|
+
* The full flow for one store operation: authorize, run the Admin GraphQL
|
|
88
|
+
* mutation if allowed, sign a receipt either way. If not authorized, `run` is
|
|
89
|
+
* never called (the mutation does not happen). Rethrows an error from `run`
|
|
90
|
+
* after recording it, with the receipt attached as `vorimReceipt`, so your
|
|
91
|
+
* handler still sees Shopify failures.
|
|
92
|
+
*/
|
|
93
|
+
guard<T>(action: ShopifyAction, run: () => Promise<T>): Promise<{
|
|
94
|
+
receipt: ShopifyReceipt;
|
|
95
|
+
value?: T;
|
|
96
|
+
}>;
|
|
97
|
+
/** Guard an `orderCreate`. Requires agent:write. */
|
|
98
|
+
orderCreate<T>(meta: {
|
|
99
|
+
orderId?: string;
|
|
100
|
+
inputHash?: string;
|
|
101
|
+
}, run: () => Promise<T>): Promise<{
|
|
102
|
+
receipt: ShopifyReceipt;
|
|
103
|
+
value?: T | undefined;
|
|
104
|
+
}>;
|
|
105
|
+
/** Guard a `refundCreate`. Requires agent:transact AND stays within
|
|
106
|
+
* `maxRefundAmount` if one was configured. `amount` is in minor units. */
|
|
107
|
+
refundCreate<T>(meta: {
|
|
108
|
+
orderId?: string;
|
|
109
|
+
amount?: number;
|
|
110
|
+
currency?: string;
|
|
111
|
+
inputHash?: string;
|
|
112
|
+
}, run: () => Promise<T>): Promise<{
|
|
113
|
+
receipt: ShopifyReceipt;
|
|
114
|
+
value?: T | undefined;
|
|
115
|
+
}>;
|
|
116
|
+
/** Guard an `inventoryAdjustQuantities`. Requires agent:write. */
|
|
117
|
+
inventoryAdjustQuantities<T>(meta: {
|
|
118
|
+
resourceId?: string;
|
|
119
|
+
inputHash?: string;
|
|
120
|
+
}, run: () => Promise<T>): Promise<{
|
|
121
|
+
receipt: ShopifyReceipt;
|
|
122
|
+
value?: T | undefined;
|
|
123
|
+
}>;
|
|
124
|
+
/** Guard a `fulfillmentCreate`. Requires agent:write. */
|
|
125
|
+
fulfillmentCreate<T>(meta: {
|
|
126
|
+
orderId?: string;
|
|
127
|
+
inputHash?: string;
|
|
128
|
+
}, run: () => Promise<T>): Promise<{
|
|
129
|
+
receipt: ShopifyReceipt;
|
|
130
|
+
value?: T | undefined;
|
|
131
|
+
}>;
|
|
132
|
+
/** Guard a `returnProcess`. Requires agent:write. */
|
|
133
|
+
returnProcess<T>(meta: {
|
|
134
|
+
resourceId?: string;
|
|
135
|
+
inputHash?: string;
|
|
136
|
+
}, run: () => Promise<T>): Promise<{
|
|
137
|
+
receipt: ShopifyReceipt;
|
|
138
|
+
value?: T | undefined;
|
|
139
|
+
}>;
|
|
140
|
+
/** Guard a `productCreate` or `productUpdate`. Requires agent:write. */
|
|
141
|
+
productWrite<T>(meta: {
|
|
142
|
+
operation?: 'productCreate' | 'productUpdate';
|
|
143
|
+
productId?: string;
|
|
144
|
+
inputHash?: string;
|
|
145
|
+
}, run: () => Promise<T>): Promise<{
|
|
146
|
+
receipt: ShopifyReceipt;
|
|
147
|
+
value?: T | undefined;
|
|
148
|
+
}>;
|
|
149
|
+
private receipt;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Create a VorimShopify guard around a Vorim SDK instance.
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* ```typescript
|
|
156
|
+
* import createVorim from '@vorim/sdk';
|
|
157
|
+
* import { createVorimShopify } from '@vorim/sdk/integrations/shopify';
|
|
158
|
+
*
|
|
159
|
+
* const vorim = createVorim({ apiKey: 'agid_sk_...' });
|
|
160
|
+
* const shop = createVorimShopify(vorim, {
|
|
161
|
+
* agentId: 'agid_abc123',
|
|
162
|
+
* shopDomain: 'acme.myshopify.com',
|
|
163
|
+
* humanId: 'user_42',
|
|
164
|
+
* maxRefundAmount: 20000, // this agent can refund up to $200.00
|
|
165
|
+
* });
|
|
166
|
+
*
|
|
167
|
+
* const { receipt, value } = await shop.refundCreate(
|
|
168
|
+
* { orderId: 'gid://shopify/Order/123', amount: 4999, currency: 'USD' },
|
|
169
|
+
* () => adminClient.request(REFUND_CREATE, { input }),
|
|
170
|
+
* );
|
|
171
|
+
* ```
|
|
172
|
+
*/
|
|
173
|
+
declare function createVorimShopify(sdk: VorimSDK, config: ShopifyGuardConfig): VorimShopify;
|
|
174
|
+
|
|
175
|
+
export { type ShopifyAction, type ShopifyGuardConfig, type ShopifyOperation, type ShopifyReceipt, VorimShopify, createVorimShopify };
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { VorimSDK } from '../index.js';
|
|
2
|
+
import { P as PermissionScope } from '../types-zzK9YOoa.js';
|
|
3
|
+
|
|
4
|
+
/** The Admin GraphQL mutations this guard knows how to classify. Any other
|
|
5
|
+
* label is accepted too; it just defaults to the 'write' risk tier. */
|
|
6
|
+
type ShopifyOperation = 'orderCreate' | 'refundCreate' | 'inventoryAdjustQuantities' | 'fulfillmentCreate' | 'returnProcess' | 'productCreate' | 'productUpdate' | 'read';
|
|
7
|
+
interface ShopifyGuardConfig {
|
|
8
|
+
/** The acting agent's Vorim id (agid_...). */
|
|
9
|
+
agentId: string;
|
|
10
|
+
/** The store this agent operates on, e.g. 'acme.myshopify.com'. Recorded in
|
|
11
|
+
* every receipt so an action is attributable to a specific shop. */
|
|
12
|
+
shopDomain: string;
|
|
13
|
+
/** The human/principal the agent acts for. Recorded in every receipt so a
|
|
14
|
+
* store action is attributable to a person, not just a machine. */
|
|
15
|
+
humanId?: string;
|
|
16
|
+
/** Minimum trust score the acting agent must hold before any mutation runs.
|
|
17
|
+
* Default 0 (off). */
|
|
18
|
+
minTrustScore?: number;
|
|
19
|
+
/** Attenuation: cap the total this agent may refund in a single refundCreate,
|
|
20
|
+
* in the currency's minor unit (e.g. cents). Shopify's coarse write_orders
|
|
21
|
+
* scope cannot express this; Vorim can. Omit for no ceiling. */
|
|
22
|
+
maxRefundAmount?: number;
|
|
23
|
+
/** Fail closed (deny on any Vorim error) or fail open. Default 'closed'. */
|
|
24
|
+
onError?: 'closed' | 'open';
|
|
25
|
+
}
|
|
26
|
+
interface ShopifyAction {
|
|
27
|
+
/** The Admin GraphQL mutation being run, e.g. 'refundCreate'. Drives the
|
|
28
|
+
* scope requirement. Unknown labels default to the 'write' tier. */
|
|
29
|
+
operation: ShopifyOperation | string;
|
|
30
|
+
/** The Shopify resource the action targets, e.g. an order or product GID. */
|
|
31
|
+
resourceId?: string;
|
|
32
|
+
/** For refundCreate: the amount moving back to the customer, in the minor
|
|
33
|
+
* unit (cents). Checked against maxRefundAmount. */
|
|
34
|
+
amount?: number;
|
|
35
|
+
/** Currency code for `amount`, e.g. 'USD'. Informational. */
|
|
36
|
+
currency?: string;
|
|
37
|
+
/** Optional hash of the mutation variables so the receipt covers the exact
|
|
38
|
+
* input without the guard storing it. */
|
|
39
|
+
inputHash?: string;
|
|
40
|
+
}
|
|
41
|
+
/** An offline-verifiable receipt for one Shopify store operation. */
|
|
42
|
+
interface ShopifyReceipt {
|
|
43
|
+
authorized: boolean;
|
|
44
|
+
agentId: string;
|
|
45
|
+
humanId?: string;
|
|
46
|
+
shopDomain: string;
|
|
47
|
+
operation: string;
|
|
48
|
+
resourceId?: string;
|
|
49
|
+
amount?: number;
|
|
50
|
+
currency?: string;
|
|
51
|
+
result: 'success' | 'denied' | 'error';
|
|
52
|
+
scope: PermissionScope;
|
|
53
|
+
/** Reason a check failed, when authorized is false. */
|
|
54
|
+
reason?: string;
|
|
55
|
+
/** True once the audit event was signed and ingested. */
|
|
56
|
+
recorded: boolean;
|
|
57
|
+
}
|
|
58
|
+
declare class VorimShopify {
|
|
59
|
+
private sdk;
|
|
60
|
+
private agentId;
|
|
61
|
+
private shopDomain;
|
|
62
|
+
private humanId?;
|
|
63
|
+
private minTrustScore;
|
|
64
|
+
private maxRefundAmount?;
|
|
65
|
+
private onError;
|
|
66
|
+
constructor(sdk: VorimSDK, config: ShopifyGuardConfig);
|
|
67
|
+
/** The Vorim scope a given operation requires. Unknown mutations fall back to
|
|
68
|
+
* agent:write (a mutation is at least a write). */
|
|
69
|
+
private scopeFor;
|
|
70
|
+
/**
|
|
71
|
+
* Check whether the acting agent may run this store operation, before it
|
|
72
|
+
* runs. Enforces (in order): trust floor, refund ceiling, permission scope.
|
|
73
|
+
* Returns { authorized, reason }.
|
|
74
|
+
*/
|
|
75
|
+
authorize(action: ShopifyAction): Promise<{
|
|
76
|
+
authorized: boolean;
|
|
77
|
+
reason?: string;
|
|
78
|
+
}>;
|
|
79
|
+
/**
|
|
80
|
+
* Emit a source-signed audit event for a store operation and return whether
|
|
81
|
+
* it was recorded. Called after the mutation runs (or after a denial). The
|
|
82
|
+
* event names the agent, the shop, and the human the agent acts for, so the
|
|
83
|
+
* record is attributable and independently verifiable offline.
|
|
84
|
+
*/
|
|
85
|
+
record(action: ShopifyAction, result: 'success' | 'denied' | 'error', reason?: string): Promise<boolean>;
|
|
86
|
+
/**
|
|
87
|
+
* The full flow for one store operation: authorize, run the Admin GraphQL
|
|
88
|
+
* mutation if allowed, sign a receipt either way. If not authorized, `run` is
|
|
89
|
+
* never called (the mutation does not happen). Rethrows an error from `run`
|
|
90
|
+
* after recording it, with the receipt attached as `vorimReceipt`, so your
|
|
91
|
+
* handler still sees Shopify failures.
|
|
92
|
+
*/
|
|
93
|
+
guard<T>(action: ShopifyAction, run: () => Promise<T>): Promise<{
|
|
94
|
+
receipt: ShopifyReceipt;
|
|
95
|
+
value?: T;
|
|
96
|
+
}>;
|
|
97
|
+
/** Guard an `orderCreate`. Requires agent:write. */
|
|
98
|
+
orderCreate<T>(meta: {
|
|
99
|
+
orderId?: string;
|
|
100
|
+
inputHash?: string;
|
|
101
|
+
}, run: () => Promise<T>): Promise<{
|
|
102
|
+
receipt: ShopifyReceipt;
|
|
103
|
+
value?: T | undefined;
|
|
104
|
+
}>;
|
|
105
|
+
/** Guard a `refundCreate`. Requires agent:transact AND stays within
|
|
106
|
+
* `maxRefundAmount` if one was configured. `amount` is in minor units. */
|
|
107
|
+
refundCreate<T>(meta: {
|
|
108
|
+
orderId?: string;
|
|
109
|
+
amount?: number;
|
|
110
|
+
currency?: string;
|
|
111
|
+
inputHash?: string;
|
|
112
|
+
}, run: () => Promise<T>): Promise<{
|
|
113
|
+
receipt: ShopifyReceipt;
|
|
114
|
+
value?: T | undefined;
|
|
115
|
+
}>;
|
|
116
|
+
/** Guard an `inventoryAdjustQuantities`. Requires agent:write. */
|
|
117
|
+
inventoryAdjustQuantities<T>(meta: {
|
|
118
|
+
resourceId?: string;
|
|
119
|
+
inputHash?: string;
|
|
120
|
+
}, run: () => Promise<T>): Promise<{
|
|
121
|
+
receipt: ShopifyReceipt;
|
|
122
|
+
value?: T | undefined;
|
|
123
|
+
}>;
|
|
124
|
+
/** Guard a `fulfillmentCreate`. Requires agent:write. */
|
|
125
|
+
fulfillmentCreate<T>(meta: {
|
|
126
|
+
orderId?: string;
|
|
127
|
+
inputHash?: string;
|
|
128
|
+
}, run: () => Promise<T>): Promise<{
|
|
129
|
+
receipt: ShopifyReceipt;
|
|
130
|
+
value?: T | undefined;
|
|
131
|
+
}>;
|
|
132
|
+
/** Guard a `returnProcess`. Requires agent:write. */
|
|
133
|
+
returnProcess<T>(meta: {
|
|
134
|
+
resourceId?: string;
|
|
135
|
+
inputHash?: string;
|
|
136
|
+
}, run: () => Promise<T>): Promise<{
|
|
137
|
+
receipt: ShopifyReceipt;
|
|
138
|
+
value?: T | undefined;
|
|
139
|
+
}>;
|
|
140
|
+
/** Guard a `productCreate` or `productUpdate`. Requires agent:write. */
|
|
141
|
+
productWrite<T>(meta: {
|
|
142
|
+
operation?: 'productCreate' | 'productUpdate';
|
|
143
|
+
productId?: string;
|
|
144
|
+
inputHash?: string;
|
|
145
|
+
}, run: () => Promise<T>): Promise<{
|
|
146
|
+
receipt: ShopifyReceipt;
|
|
147
|
+
value?: T | undefined;
|
|
148
|
+
}>;
|
|
149
|
+
private receipt;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Create a VorimShopify guard around a Vorim SDK instance.
|
|
153
|
+
*
|
|
154
|
+
* @example
|
|
155
|
+
* ```typescript
|
|
156
|
+
* import createVorim from '@vorim/sdk';
|
|
157
|
+
* import { createVorimShopify } from '@vorim/sdk/integrations/shopify';
|
|
158
|
+
*
|
|
159
|
+
* const vorim = createVorim({ apiKey: 'agid_sk_...' });
|
|
160
|
+
* const shop = createVorimShopify(vorim, {
|
|
161
|
+
* agentId: 'agid_abc123',
|
|
162
|
+
* shopDomain: 'acme.myshopify.com',
|
|
163
|
+
* humanId: 'user_42',
|
|
164
|
+
* maxRefundAmount: 20000, // this agent can refund up to $200.00
|
|
165
|
+
* });
|
|
166
|
+
*
|
|
167
|
+
* const { receipt, value } = await shop.refundCreate(
|
|
168
|
+
* { orderId: 'gid://shopify/Order/123', amount: 4999, currency: 'USD' },
|
|
169
|
+
* () => adminClient.request(REFUND_CREATE, { input }),
|
|
170
|
+
* );
|
|
171
|
+
* ```
|
|
172
|
+
*/
|
|
173
|
+
declare function createVorimShopify(sdk: VorimSDK, config: ShopifyGuardConfig): VorimShopify;
|
|
174
|
+
|
|
175
|
+
export { type ShopifyAction, type ShopifyGuardConfig, type ShopifyOperation, type ShopifyReceipt, VorimShopify, createVorimShopify };
|