@vaultgraph/sdk 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,21 @@
 # VaultGraph SDK
 
-VaultGraph client helpers for generating, signing, verifying, and submitting VaultGraph JobReceipts. Intended for server-side usage (Node 18+/edge runtimes with `fetch`).
+[VaultGraph](https://vaultgraph.com) is a platform for building trustworthy AI agent applications. 
+
+## What this SDK is for
+
+- Build canonical `JobReceipt` payloads that match the portal ingestion API.
+- Hash sensitive context before it leaves your system.
+- Sign receipts with your vendor keys and submit them to `/api/receipts` using your vendor API key.
+- Verify signatures locally when needed.
+
+## Prerequisites
+
+- A VaultGraph vendor organization in the portal (create or join at https://app.vaultgraph.com). Marketing site: https://vaultgraph.com.
+- Vendor API key created in the portal (Org Settings → API Keys). Keep this server-side only.
+- At least one agent and consumer defined in the portal so you can reference their IDs when creating receipts.
+
+If you need step-by-step UI guidance, see the [VaultGraph Docs](https://vaultgraph.com/docs).
 
 ## Install
 
@@ -12,28 +27,24 @@ pnpm add @vaultgraph/sdk
 
 ### Generate a keypair (one-time, server-side)
 
-**Supported algorithm (MVP): Ed25519.** The ingestion API verifies with `algorithm: null`, which assumes Ed25519/Ed448; RSA/ECDSA signatures are not accepted right now.
+**Supported algorithm: Ed25519.** The ingestion API verifies with `algorithm: null`, which assumes Ed25519/Ed448; RSA/ECDSA signatures are not accepted right now.
 
 ```ts
-import { generateKeyPairSync } from "crypto";
+import { generateKeyPair } from "@vaultgraph/sdk";
 
-const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
-  privateKeyEncoding: { format: "pem", type: "pkcs8" },
-  publicKeyEncoding: { format: "pem", type: "spki" },
-});
+const { privateKey, publicKey } = generateKeyPair();
 
 console.log("Private key (keep secret):\n", privateKey);
 console.log("Public key (share with VaultGraph):\n", publicKey);
 ```
 
-Store the private key in your secrets manager; never ship it to the browser. Publish the public key wherever you manage org settings or bundle it with exports.
+This helper is server-only (Node 18+/edge) and returns PEM-encoded Ed25519 keys. Store the private key in your secrets manager; never ship it to the browser. Publish the public key wherever you manage org settings or bundle it with exports.
 
 ### Create, sign, verify, and submit
 
 ```ts
 import {
   createReceipt,
-  createSignedReceipt,
   hashContext,
   signReceipt,
   submitReceipt,
@@ -53,8 +64,8 @@ const receipt = createReceipt({
   metadata: { channel: "email" },
 });
 
-// 3) Sign the receipt (Ed25519, ECDSA, RSA supported)
-const { signature } = createSignedReceipt({
+// 3) Sign the receipt with Ed25519 algorithm
+const signature = signReceipt({
   receipt,
   privateKey: process.env.VAULTGRAPH_VENDOR_PRIVATE_KEY!,
 });
@@ -68,7 +79,6 @@ const ok = verifyReceipt({
 
 // 5) Submit to your portal deployment
 await submitReceipt({
-  apiUrl: "https://app.vaultgraph.com", // or your self-hosted URL
   receipt,
   signature,
   publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
@@ -76,6 +86,26 @@ await submitReceipt({
 });
 ```
 
+### Convenience: create + sign + submit in one step (server-only)
+
+```ts
+import { submitSignedReceipt } from "@vaultgraph/sdk";
+
+const { receipt, signature, response } = await submitSignedReceipt({
+  apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
+  publicKey: process.env.VAULTGRAPH_VENDOR_PUBLIC_KEY!,
+  privateKey: process.env.VAULTGRAPH_VENDOR_PRIVATE_KEY!,
+  agentId: "agent-123",
+  consumerId: "consumer-456",
+  jobId: "job-789",
+  resolution: "resolved",
+  contextHash: hashContext({ transcript: "hello" }),
+  metadata: { source: "sdk" },
+});
+
+console.log(response); // { id, status }
+```
+
 ### Convenience: create + sign in one step
 
 ```ts
@@ -100,11 +130,16 @@ const { receipt, signature } = createSignedReceipt({
 - `signReceipt(options)` → signature string (base64 default)
 - `verifyReceipt(options)` → boolean
 - `createSignedReceipt(options)` → `{ receipt, signature }`
+- `submitSignedReceipt(options)` → creates, signs, and submits; defaults `apiUrl` to portal base
+- `submitReceipt(options)` → POSTs to `/api/receipts` (requires `apiKey`)
 - `submitReceipt(options)` → POSTs to `/api/receipts` (requires `apiKey`)
-- Types: `JobReceipt`, `JobResolution`, `ReceiptVersion`, `SubmitReceiptOptions`, `SubmitReceiptResponse`
+- `generateKeyPair()` → returns PEM-encoded Ed25519 keypair
+- Types: `CreateReceiptInput`, `JobReceipt`, `JobReceiptV0`, `JobResolution`, `ReceiptVersion`, `SubmitReceiptOptions`, `SubmitReceiptResponse`
 
 ## Notes
 
 - Do not send raw conversation context; send `context_hash` instead.
 - Keep your private key and vendor API key server-side only (API key is required for ingestion).
 - Receipt versioning currently `v0`; breaking changes will bump the major version of this package.
+- Portal: https://app.vaultgraph.com
+- Docs: https://vaultgraph.com/docs

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { KeyLike, BinaryToTextEncoding } from 'crypto';
 import { CreateReceiptInput, JobReceipt } from '@repo/lib/job-receipt';
 export { CreateReceiptInput, JOB_RESOLUTIONS, JobReceipt, JobReceiptV0, JobResolution, ReceiptVersion, canonicalJSONStringify, createReceipt, hashContext, jobReceiptV0Schema, serializeReceipt, signReceipt, verifyReceipt } from '@repo/lib/job-receipt';
+import { SubmitReceiptResponse } from '@repo/lib/submit-receipt';
 export { SubmitReceiptOptions, SubmitReceiptResponse, submitReceipt } from '@repo/lib/submit-receipt';
 
 interface CreateSignedReceiptOptions extends CreateReceiptInput {
@@ -8,6 +9,14 @@ interface CreateSignedReceiptOptions extends CreateReceiptInput {
     algorithm?: string | null;
     encoding?: BinaryToTextEncoding;
 }
+interface SubmitSignedReceiptOptions extends CreateSignedReceiptOptions {
+    /** API base URL; defaults to the portal URL (app.vaultgraph.com in prod). */
+    apiUrl?: string;
+    apiKey: string;
+    publicKey: KeyLike;
+    /** Optional fetch implementation for custom transports or tests. */
+    fetchImpl?: typeof fetch;
+}
 /**
  * Convenience helper to construct and sign a receipt in one step.
  */
@@ -15,5 +24,20 @@ declare function createSignedReceipt(options: CreateSignedReceiptOptions): {
     receipt: JobReceipt;
     signature: string;
 };
+/**
+ * Server-only helper to create, sign, and submit a receipt in one step.
+ */
+declare function submitSignedReceipt(options: SubmitSignedReceiptOptions): Promise<{
+    receipt: JobReceipt;
+    signature: string;
+    response: SubmitReceiptResponse;
+}>;
+/**
+ * Generates an Ed25519 keypair encoded as PEM strings (server-only).
+ */
+declare function generateKeyPair(): {
+    privateKey: string;
+    publicKey: string;
+};
 
-export { type CreateSignedReceiptOptions, createSignedReceipt };
+export { type CreateSignedReceiptOptions, type SubmitSignedReceiptOptions, createSignedReceipt, generateKeyPair, submitSignedReceipt };

package/dist/index.js

@@ -1,6 +1,6 @@
-import { createHash, sign, verify, createPrivateKey, createPublicKey } from 'crypto';
+import { createHash, sign, verify, createPrivateKey, createPublicKey, generateKeyPairSync } from 'crypto';
 
-// ../lib/src/job-receipt.ts
+// src/index.ts
 var JOB_RESOLUTIONS = ["resolved", "partial", "failed"];
 var VALID_JOB_RESOLUTIONS = JOB_RESOLUTIONS;
 var jobReceiptV0Schema = {
@@ -167,15 +167,7 @@ function canonicalize(value) {
 
 // ../lib/src/submit-receipt.ts
 async function submitReceipt(options) {
-  const {
-    apiUrl,
-    receipt,
-    signature,
-    publicKey,
-    metadata,
-    apiKey,
-    fetchImpl
-  } = options;
+  const { apiUrl, receipt, signature, publicKey, apiKey, fetchImpl } = options;
   if (!apiUrl || !apiUrl.trim()) {
     throw new Error("apiUrl is required");
   }
@@ -193,8 +185,7 @@ async function submitReceipt(options) {
     body: JSON.stringify({
       receipt,
       signature,
-      public_key: publicKey,
-      metadata
+      public_key: publicKey
     })
   });
   const payload = await safeParseJson(res);
@@ -221,6 +212,11 @@ async function safeParseJson(response) {
   }
 }
 
+// ../lib/src/site-url.ts
+function getPortalURL() {
+  return process.env.NEXT_PUBLIC_PORTAL_URL || process.env.NODE_ENV === "development" && "http://localhost:3001" || "https://app.vaultgraph.com";
+}
+
 // src/index.ts
 function createSignedReceipt(options) {
   const { privateKey, algorithm, encoding, ...receiptInput } = options;
@@ -233,5 +229,26 @@ function createSignedReceipt(options) {
   });
   return { receipt, signature };
 }
+async function submitSignedReceipt(options) {
+  const { apiUrl, apiKey, publicKey, fetchImpl, ...createAndSignOptions } = options;
+  const { receipt, signature } = createSignedReceipt(createAndSignOptions);
+  const targetApiUrl = apiUrl ?? getPortalURL();
+  const response = await submitReceipt({
+    apiUrl: targetApiUrl,
+    apiKey,
+    receipt,
+    signature,
+    publicKey: createPublicKey(publicKey).export({ type: "spki", format: "pem" }).toString(),
+    fetchImpl
+  });
+  return { receipt, signature, response };
+}
+function generateKeyPair() {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519", {
+    privateKeyEncoding: { format: "pem", type: "pkcs8" },
+    publicKeyEncoding: { format: "pem", type: "spki" }
+  });
+  return { privateKey, publicKey };
+}
 
-export { JOB_RESOLUTIONS, canonicalJSONStringify, createReceipt, createSignedReceipt, hashContext, jobReceiptV0Schema, serializeReceipt, signReceipt, submitReceipt, verifyReceipt };
+export { JOB_RESOLUTIONS, canonicalJSONStringify, createReceipt, createSignedReceipt, generateKeyPair, hashContext, jobReceiptV0Schema, serializeReceipt, signReceipt, submitReceipt, submitSignedReceipt, verifyReceipt };

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@vaultgraph/sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "type": "module",
   "license": "MIT",
+  "homepage": "https://vaultgraph.com/",
+  "bugs": {
+    "url": "mailto:admin@vaultgraph.com"
+  },
   "files": ["dist"],
   "main": "./dist/index.js",
   "module": "./dist/index.js",