Skip to main content

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.

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);
  },

  // …add `createCheckout`, `addLineItems`, `completeCheckout`, etc. as you
  // implement them. The full method list is in the protocol reference.
});
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

FunctionDescription
createShopsClient(options)CRUD for /api/shops (org-wide, vk_ keys)
createAdapterHandler(adapter)Build a typed webhook handler for a VaultGraph commerce backend

Receipt functions

FunctionDescription
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