@vaultgraph/sdk 0.1.2 → 0.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VaultGraph, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -15,18 +15,15 @@ pnpm add @vaultgraph/sdk
 **Supported algorithm (MVP): 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
 
@@ -35,6 +32,7 @@ import {
   createReceipt,
   createSignedReceipt,
   hashContext,
+  submitSignedReceipt,
   signReceipt,
   submitReceipt,
   verifyReceipt,
@@ -68,14 +66,34 @@ 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!,
   apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
+  // apiUrl: "https://localhost:3000" // optional override
 });
 ```
 
+### 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,6 +118,7 @@ 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`)
 - Types: `JobReceipt`, `JobResolution`, `ReceiptVersion`, `SubmitReceiptOptions`, `SubmitReceiptResponse`
 

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,8 +1,9 @@
 {
   "name": "@vaultgraph/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
+  "license": "MIT",
   "files": ["dist"],
   "main": "./dist/index.js",
   "module": "./dist/index.js",