VaultGraph SDK

The official Node.js SDK for VaultGraph, the hosted MCP gateway for e-commerce merchants.

Use this SDK to:

• Integrate your storefront with VaultGraph in one file with the @vaultgraph/sdk/adapter helper. 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 JobReceipt payloads.

Install

pnpm add @vaultgraph/sdk

Also works with npm install @vaultgraph/sdk or yarn add @vaultgraph/sdk.

Before you start

1. Sign up at app.vaultgraph.com and create your organization.
2. Create a shop, then a deployment for that shop. Each deployment gets its own MCP endpoint.
3. Generate an API key. Organization keys (vk_...) cover org-wide operations such as listing shops; deployment keys (dk_...) are scoped to a single deployment.

Keep API keys out of browser code — the SDK is server-side only.

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:

import { createAdapterHandler } from "@vaultgraph/sdk/adapter";

const handler = createAdapterHandler({
  signingSecret: process.env.VAULTGRAPH_SIGNING_SECRET!,

  async searchProducts({ query, filters, pagination } = {}) {
    // Return a ProductPage: `{ products, pagination? }`. Set
    // `pagination: { has_next_page: true, cursor }` while more rows remain;
    // omit `pagination` on the last page.
    return myDb.products.search({ query, filters, pagination });
  },
  async getProduct(id) {
    return myDb.products.find(id);
  },
  async listCategories() {
    // Return your store's whole category vocabulary: `{ value, count? }[]`.
    // The labels are what agents pass to `searchProducts`' filters.categories,
    // so this is how they discover categories and recover from an empty search.
    return myDb.products.categories();
  },
  async listOrders(context) {
    // Every method receives the request's context as its final argument —
    // opaque values your integration attached, typically a signed customer
    // session token (see the protocol reference's "Request context").
    // Verify it, then scope the read.
    const customerId = verifySessionToken(context?.session_token);
    return customerId ? myDb.orders.forCustomer(customerId) : [];
  },

  // …add `createCheckout`, `addLineItems`, `completeCheckout`, etc. as you
  // implement them. The protocol reference lists every method with its
  // inputs, return shape, preconditions, and which error to throw when.
});

The handler is framework-agnostic — it returns (req) => Promise<res>. Mount it from any HTTP server:

// Next.js App Router
export async function POST(request: Request) {
  const result = await handler({
    rawBody: await request.text(),
    headers: Object.fromEntries(request.headers),
  });
  return new Response(result.body, {
    status: result.status,
    headers: result.headers,
  });
}

Configure the endpoint URL and a shared HMAC secret on your deployment in app.vaultgraph.com and you're live. The full wire contract — envelope shape, signing scheme, error mapping, idempotency rules, and retry policy — is documented in the Remote adapter protocol reference.

Pass an optional 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:

import { createShopsClient } from "@vaultgraph/sdk";

const shops = createShopsClient({
  apiKey: process.env.VAULTGRAPH_API_KEY!, // vk_...
});

// Create
const shop = await shops.create({
  name: "Acme Store",
  description: "Flagship storefront.",
});

// List and get
const all = await shops.list();
const detail = await shops.get(shop.id);

// Update
await shops.update(shop.id, { name: "Acme Store EU" });

// Delete
await shops.delete(shop.id);

Offline receipt primitives

The SDK also exports primitives for building, signing, and verifying canonical JobReceipt payloads offline:

import {
  createSignedReceipt,
  generateKeyPair,
  verifyReceipt,
} from "@vaultgraph/sdk";

const { publicKey, privateKey } = generateKeyPair();

const { receipt, signature } = createSignedReceipt({
  jobId: "job-001",
  resolution: "success",
  contextHash: "abc123",
  privateKey,
});

const ok = verifyReceipt({ receipt, signature, publicKey });

These run entirely locally and do not call the VaultGraph API.

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, RequestContext, 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