The official Node.js SDK for VaultGraph, the hosted MCP gateway for e-commerce merchants. Use this SDK to:Documentation Index
Fetch the complete documentation index at: https://docs.vaultgraph.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
- Integrate your storefront with VaultGraph in one file with the
@vaultgraph/sdk/adapterhelper. The hosted gateway POSTs to one HTTPS endpoint you expose; your cart/checkout/order records never leave your infrastructure. This is the merchant integration path — your storefront never calls VaultGraph. - Manage your VaultGraph workspace from your backend (create shops, rotate keys).
- Build and verify offline
JobReceiptpayloads.
Install
npm install @vaultgraph/sdk or yarn add @vaultgraph/sdk.
Before you start
- Sign up at app.vaultgraph.com and create your organization.
- Create a shop, then a deployment for that shop. Each deployment gets its own MCP endpoint.
- Generate an API key. Organization keys (
vk_...) cover org-wide operations such as listing shops; deployment keys (dk_...) are scoped to a single deployment.
Integrate your storefront (@vaultgraph/sdk/adapter)
Mount one HTTPS endpoint and your storefront is wired to VaultGraph. The helper handles signing, replay protection, idempotency dedupe, and error serialization. Callbacks are typed over Checkout, Buyer, LineItem, Order, Product, Variant, … from @vaultgraph/sdk/adapter.
If you’re integrating an existing storefront, this is the only thing you need to implement on your side. There are no merchant-side calls to VaultGraph and no REST endpoints to consume. The gateway calls your endpoint; you respond.
Every method is optional. Implement only what you need today — anything you skip auto-returns not_implemented (501), which the gateway surfaces as commerce_backend_unavailable to agents. The gateway also advertises only the tools you implement: the handler reports your method set on request, so agents see exactly what your backend serves. Add methods incrementally as you build out your storefront:
(req) => Promise<res>. Mount it from any HTTP server:
idempotencyStore to createAdapterHandler — any { get(key), set(key, { status, body }) } and the helper replays the cached response on retries instead of re-running your code.
Manage shops
Use the shops client for control-plane operations against/api/shops — separate from storefront integration:
Offline receipt primitives
The SDK also exports primitives for building, signing, and verifying canonicalJobReceipt payloads offline:
API reference
Client factories
| Function | Description |
|---|---|
createShopsClient(options) | CRUD for /api/shops (org-wide, vk_ keys) |
createAdapterHandler(adapter) | Build a typed webhook handler for a VaultGraph commerce backend |
Receipt functions
| Function | Description |
|---|---|
prepareReceiptContext(value) | Normalize context and return the exact hashed payload |
createReceipt(input) | Build a normalized JobReceipt |
createTelemetry(input) | Build a normalized Telemetry payload |
serializeReceipt(receipt) | Canonical JSON string of a receipt |
signReceipt(options) | Sign a receipt and return a base64 signature |
verifyReceipt(options) | Verify a receipt signature and return a boolean |
createSignedReceipt(options) | Create and sign in one step |
generateKeyPair() | Generate a PEM-encoded Ed25519 key pair |
Types
Shops:ShopRecord, ShopCreateInput, ShopUpdateInput, ShopsClient, ShopsClientOptions
Adapter (@vaultgraph/sdk/adapter subpath): MerchantCommerceAdapter, AdapterHandler, AdapterHandlerOptions, AdapterHandlerRequest, AdapterHandlerResponse, AdapterIdempotencyStore, AdapterHandlerError, Product, Variant, Price, PriceRange, Media, ProductPage, ProductPagination, SearchCatalogInput, FulfillmentMethod, Checkout, CheckoutCreateInput, Order, Buyer, BillingAddress, LineItem, ShippingDestination.
Receipts: CreateReceiptInput, JobReceipt, JobReceiptV0, JobResolution, ReceiptVersion, Telemetry, CreateSignedReceiptOptions, ApiError
Links
- Platform: app.vaultgraph.com
- Website: vaultgraph.com
- npm: @vaultgraph/sdk