VaultGraph remote commerce adapter protocol

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.

​

1. Transport

• Direction: VaultGraph → merchant. The merchant exposes one HTTPS endpoint; the gateway calls it.
• Method: POST.
• URL shape: {endpoint_url}/{method} — the configured endpoint_url joined with the method name as a single path segment. The path prefix is the merchant’s choice — VaultGraph does not reserve or require any particular name. Example: https://shop.example.com/webhooks/vaultgraph/createCheckout.
• TLS: required. The gateway will not call plain http:// endpoints.
• Content-Type: application/json; charset=utf-8 on both directions.

​

2. Request envelope

{
  "protocol": "1.0",
  "method": "createCheckout",
  "params": { "input": { "currency": "GBP" } }
}

​

Headers

​

3. Signing

1. The gateway takes the current Unix timestamp in seconds.
2. It computes signature = HMAC_SHA256(secret, "${timestamp}.${idempotencyKey}.${rawBody}") and hex-encodes it. ${idempotencyKey} is the value of the X-VaultGraph-Idempotency-Key header (§5); on non-mutating methods, which carry no idempotency key, it is the empty string.
3. It sets X-VaultGraph-Signature: t=<timestamp>,v1=<hex_signature>.

1. Reject requests where X-VaultGraph-Signature is missing or malformed.
2. Reject requests where |now - timestamp| > 5 minutes. This is the replay window.
3. Recompute the HMAC over the timestamp, the X-VaultGraph-Idempotency-Key header value (empty string when absent), and the raw body bytes (not a re-serialized JSON), and reject on mismatch. Use a constant-time comparison.

​

Secret rotation

​

4. Response envelope

{
  "data": {
    /* method-specific result */
  }
}

{
  "error": {
    "code": "checkout_not_open",
    "status": 409,
    "detail": "Checkout ck_abc has already completed."
  }
}

​

5. Idempotency

• createCheckout
• addLineItems
• updateLineItem
• removeLineItem
• applyDiscount
• setFulfillment
• setBuyer
• completeCheckout

• The merchant SHOULD store the full response (status + body) keyed by the idempotency key.
• If the same key arrives a second time within the merchant’s TTL, the merchant SHOULD return the stored response verbatim instead of re-running the operation.
• Cache both success AND error responses. A mutating call that fails after committing a side effect (e.g. order written, downstream notification failed) must NOT re-execute on retry. The gateway treats merchant errors with recognized codes as deterministic answers and will not retry them, but a network blip mid-response can still cause a retry — the cache is what protects against the duplicate.
• Recommended TTL: 24 hours. Retries beyond that window are vanishingly rare; storage costs grow if you keep them forever.

​

6. Methods

​

Catalog search

{
  "query": "running shoes", // optional free-text search
  "filters": {
    // optional
    "categories": ["footwear"], // OR logic across the list
    "price": { "min": 5000, "max": 20000 }, // inclusive, integer minor units
  },
  "pagination": { "cursor": "…", "limit": 20 }, // optional; limit is clamped to ≤ 100
}

​

Pagination

• The merchant chooses the cursor encoding (offset, keyset, base64 JSON — whatever fits the underlying store). The gateway treats it as an opaque blob: it never inspects or generates the value.
• When more pages remain, the merchant returns pagination: { "has_next_page": true, "cursor": "<token>" }. cursor MUST be present whenever has_next_page is true.
• On the last page the merchant either omits pagination entirely or returns pagination: { "has_next_page": false }. total_count MAY be included on any page.
• The caller passes the returned cursor straight back as input.pagination.cursor on the next call; the gateway forwards it unchanged.
• The gateway does not auto-paginate — each call returns exactly one page and the caller drives the loop.

​

Fulfillment

​

7. Error codes

​

8. Timeout & retry

• Per-attempt timeout: 10 seconds (configurable per backend in the portal).
• Retries: up to 2 (configurable per backend in the portal), with exponential backoff starting at 100 ms.

• network errors (DNS, TCP, TLS, socket close mid-response),
• response timeouts (the request aborted before headers),
• HTTP 5xx without a recognized error envelope.

​

9. Versioning

• Envelope version is the protocol field plus the X-VaultGraph-Version header. Additive payload changes (new methods, new optional fields on data) ship under the same envelope.
• Backwards-incompatible envelope changes will bump the major version (1.0 → 2.0) and use a new header value. The gateway will continue to send 1.0 to backends that have not opted in.
• Merchants that don’t implement a method may return {"error":{"code":"not_implemented","status":501}} — the gateway surfaces it as commerce_backend_unavailable. The @vaultgraph/sdk/adapter helper emits this envelope automatically for any method you don’t supply, so you can ship a partial implementation and grow into the surface incrementally.

​

10. Reference implementation

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

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

  async searchProducts({ query, filters, pagination }) {
    /* ... */
  },
  async getProduct(id) {
    /* ... */
  },
  async createCheckout(input) {
    /* ... */
  },
  // ...one method per row in §6 — every method is optional, anything you
  // skip auto-responds with `not_implemented` (501).
});

// Plug into your HTTP framework — handler is just (req) => res.