npm install @rox-register/sdk
# pnpm add @rox-register/sdk · yarn add @rox-register/sdk
# Node >= 20, ESM and CommonJS, TypeScript types included, zero dependencies

import { readFileSync } from "node:fs";
import { RoxRegister } from "@rox-register/sdk";

const client = new RoxRegister({
  apiKey: process.env.RR_API_KEY,          // rr_live_ak_... (vault API key)
  requestSigningKey: {
    kid: "ish-prod-2026-01",               // registered in your Platform
    privateJwk: JSON.parse(readFileSync("request-key.jwk", "utf8")),
    // or privateKeyPem; Ed25519 and P-256 keys both supported
  },
});

// 1 · Seal. The SDK hashes the bytes locally; the file never leaves
//     your process. The request is validated and either rejected
//     immediately or accepted with 202.
const pdf = readFileSync("policy.pdf");
const accepted = await client.seal({
  recordType: "policy",
  externalRef: "POL-2026-88123",
  content: pdf,                            // or contentDigestHex: "..."
  idempotencyKey: "POL-2026-88123-v1",     // safe retries for 48h
});
// accepted.reference -> "rr_ref_01J8ZKQ2..."
// accepted.salt_hex  -> STORE IT: verification by digest needs it

// 2 · Exactly one terminal outcome follows asynchronously, anchored or
//     failed, via the record.anchored / record.failed webhooks, or poll:
const record = await client.getRecord(accepted.record_id);
// record.status: pending and batched are pre-anchor states, treat them
// identically; anchored and failed are the terminal outcomes.

// 3 · Anyone can verify the exact bytes, no API key needed:
const check = await client.verifyFile(pdf, {
  saltHex: accepted.salt_hex,
  reference: accepted.reference,
});
// check.match === true and check.result === "genuine", or one changed
// byte flips it to "mismatch" (counted, alerts the vault owner)

import { constructWebhookEvent, WebhookVerificationError } from "@rox-register/sdk";
import express from "express";

const app = express();
// The MAC covers the EXACT raw body bytes: capture them before parsing.
app.post("/rox/events", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = constructWebhookEvent({
      secret: process.env.RR_WEBHOOK_SECRET,  // whsec_..., shown once at creation
      headers: req.headers,
      rawBody: req.body,                      // Buffer, untouched
    });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.status(401).end();
    throw err;
  }
  // event: {id, type, created_at, data}, signature and freshness verified.
  if (event.type === "record.anchored") markProven(event.data);
  if (event.type === "record.failed") escalate(event.data);
  if (event.type === "verification.mismatch") alertSecurity(event.data);
  res.status(200).end();  // non-2xx deliveries are retried, then marked dead
});

import { hashFields, revealPayload, verifyRevealedField } from "@rox-register/sdk";

// Sealing side: hash the fields locally. Values and per-field salts
// NEVER reach Rox, only the salted hashes do.
const { fieldHashes, fieldSalts, fieldRootHex } = hashFields([
  { name: "policy_no", value: "POL-2026-88123" },
  { name: "insured_name", value: "Aya Hassan" },
  { name: "coverage_egp", value: 250000 },
]);
await client.seal({ recordType: "policy", content: pdf, fieldHashes });
// Retain fieldSalts (and the values) alongside your document.

// Disclosure side: reveal ONLY chosen fields, with inclusion proofs.
const payload = revealPayload({
  fields,                      // the complete ordered list from sealing time
  fieldSalts,
  reveal: ["coverage_egp"],    // any subset
});

// Verifier side: check a revealed field against the anchored field root
// (field_root_hex from the issuer's record view or the RRP-1 proof
// bundle), fully offline.
const ok = verifyRevealedField(payload.revealed[0], record.field_root_hex);

import {
  RoxRegisterAuthError,
  RoxRegisterServerError,
  RoxRegisterStateError,
  RoxRegisterValidationError,
} from "@rox-register/sdk";

try {
  await client.seal({ recordType: "policy", contentDigestHex: digest });
} catch (err) {
  if (err instanceof RoxRegisterAuthError) {
    // RR-1xxx: API key, scope, JWS, timestamp, nonce
    rotateCredentialsAlert(err.code);
  } else if (err instanceof RoxRegisterValidationError) {
    // RR-2xxx: your request (vault state, record type, PII, idempotency)
    fixRequest(err.code, err.problem.detail);
  } else if (err instanceof RoxRegisterStateError) {
    // RR-3xxx / RR-4xxx: gas, backlog, approvals
    topUpGasOrRequestApproval(err.code);
  } else if (err instanceof RoxRegisterServerError) {
    // RR-5xxx: opaque internal; retry with backoff
    scheduleRetry(err.problem.instance);
  }
  // Every error carries the RFC 7807 problem document:
  // err.code, err.status, err.problem (type, title, detail, instance).
}