@vaultgraph/sdk 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 # VaultGraph SDK
 
-[VaultGraph](https://vaultgraph.com) is a platform for building trustworthy AI agent applications. 
+[VaultGraph](https://vaultgraph.com) is a platform for building trustworthy AI agent applications.
 
 ## What this SDK is for
 
@@ -11,7 +11,7 @@
 
 ## Prerequisites
 
-- A VaultGraph vendor organization in the portal (create or join at https://app.vaultgraph.com). Marketing site: https://vaultgraph.com.
+- A VaultGraph vendor organization in the portal (create or join at https://app.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.
 
@@ -122,6 +122,31 @@ const { receipt, signature } = createSignedReceipt({
 });
 ```
 
+### Manage agents via the API (server-only)
+
+```ts
+import { createAgentsClient } from "@vaultgraph/sdk";
+
+const agents = createAgentsClient({
+  apiKey: process.env.VAULTGRAPH_VENDOR_API_KEY!,
+});
+
+const created = await agents.create({
+  name: "Support Bot",
+  description: "Handles tier-1 support workflows.",
+});
+
+const list = await agents.list();
+const detail = await agents.get(created.id);
+
+const updated = await agents.update(created.id, {
+  name: "Support Bot v2",
+  description: "Now with escalation scoring.",
+});
+
+await agents.delete(updated.id);
+```
+
 ## API surface
 
 - `hashContext(value, options?)` → sha256 hash of canonical JSON/bytes
@@ -132,9 +157,9 @@ const { receipt, signature } = createSignedReceipt({
 - `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`)
+- `createAgentsClient(options)` → CRUD helper for `/api/agents`
 - `generateKeyPair()` → returns PEM-encoded Ed25519 keypair
-- Types: `CreateReceiptInput`, `JobReceipt`, `JobReceiptV0`, `JobResolution`, `ReceiptVersion`, `SubmitReceiptOptions`, `SubmitReceiptResponse`
+- Types: `CreateReceiptInput`, `JobReceipt`, `JobReceiptV0`, `JobResolution`, `ReceiptVersion`, `SubmitReceiptOptions`, `SubmitReceiptResponse`, `AgentRecord`, `AgentCreateInput`, `AgentUpdateInput`, `AgentsClientOptions`, `AgentsClient`
 
 ## Notes
 

package/dist/index.d.ts

@@ -1,18 +1,80 @@
-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';
+import { KeyLike, BinaryToTextEncoding } from 'crypto';
 
+/**
+ * Agent record returned by the API.
+ */
+interface AgentRecord {
+    id: string;
+    name: string;
+    description: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Payload for creating agents.
+ */
+interface AgentCreateInput {
+    name: string;
+    description?: string | null;
+}
+/**
+ * Payload for updating agents.
+ */
+interface AgentUpdateInput {
+    name: string;
+    description?: string | null;
+}
+/**
+ * Configuration for `createAgentsClient`.
+ */
+interface AgentsClientOptions {
+    apiKey: string;
+    /** API base URL; defaults to the portal URL (app.vaultgraph.com in prod). */
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Client interface for the agent API.
+ */
+interface AgentsClient {
+    list: () => Promise<AgentRecord[]>;
+    get: (id: string) => Promise<AgentRecord>;
+    create: (input: AgentCreateInput) => Promise<AgentRecord>;
+    update: (id: string, input: AgentUpdateInput) => Promise<AgentRecord>;
+    delete: (id: string) => Promise<{
+        id: string;
+    }>;
+}
+
+/**
+ * Creates a minimal API client for managing agents.
+ */
+declare function createAgentsClient(options: AgentsClientOptions): AgentsClient;
+
+/**
+ * Input for `createSignedReceipt`.
+ */
 interface CreateSignedReceiptOptions extends CreateReceiptInput {
+    /** PEM-encoded private key used to sign the receipt. */
     privateKey: KeyLike;
+    /** Optional signing algorithm; defaults to Ed25519 when null. */
     algorithm?: string | null;
+    /** Encoding for the resulting signature. */
     encoding?: BinaryToTextEncoding;
 }
+/**
+ * Input for `submitSignedReceipt`.
+ */
 interface SubmitSignedReceiptOptions extends CreateSignedReceiptOptions {
     /** API base URL; defaults to the portal URL (app.vaultgraph.com in prod). */
     apiUrl?: string;
+    /** Vendor API key for authentication. */
     apiKey: string;
+    /** Public key matching the signing private key. */
     publicKey: KeyLike;
     /** Optional fetch implementation for custom transports or tests. */
     fetchImpl?: typeof fetch;
@@ -40,4 +102,4 @@ declare function generateKeyPair(): {
     publicKey: string;
 };
 
-export { type CreateSignedReceiptOptions, type SubmitSignedReceiptOptions, createSignedReceipt, generateKeyPair, submitSignedReceipt };
+export { type AgentCreateInput, type AgentRecord, type AgentUpdateInput, type AgentsClient, type AgentsClientOptions, type CreateSignedReceiptOptions, type SubmitSignedReceiptOptions, createAgentsClient, createSignedReceipt, generateKeyPair, submitSignedReceipt };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { createHash, sign, verify, createPrivateKey, createPublicKey, generateKeyPairSync } from 'crypto';
 
-// src/index.ts
+// ../lib/src/job-receipt.ts
 var JOB_RESOLUTIONS = ["resolved", "partial", "failed"];
 var VALID_JOB_RESOLUTIONS = JOB_RESOLUTIONS;
 var jobReceiptV0Schema = {
@@ -217,7 +217,154 @@ function getPortalURL() {
   return process.env.NEXT_PUBLIC_PORTAL_URL || process.env.NODE_ENV === "development" && "http://localhost:3001" || "https://app.vaultgraph.com";
 }
 
-// src/index.ts
+// src/shared/api.ts
+function assertNonEmpty(value, name) {
+  if (!value || !value.trim()) {
+    throw new Error(`${name} is required`);
+  }
+}
+function extractApiError(payload, fallback) {
+  if (!payload || typeof payload !== "object") {
+    return fallback || "Request failed";
+  }
+  const { detail, error } = payload;
+  return detail || error || fallback || "Request failed";
+}
+async function requestJson(options) {
+  const { apiUrl, apiKey, path, method, body, fetchImpl, headers } = options;
+  assertNonEmpty(apiUrl, "apiUrl");
+  assertNonEmpty(apiKey, "apiKey");
+  assertNonEmpty(path, "path");
+  const url = new URL(path, apiUrl).toString();
+  const fetcher = fetchImpl ?? fetch;
+  const res = await fetcher(url, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      "x-api-key": apiKey,
+      ...headers ?? {}
+    },
+    body: body === void 0 ? void 0 : JSON.stringify(body)
+  });
+  const payload = await safeParseJson2(res);
+  if (!res.ok) {
+    throw new Error(extractApiError(payload, res.statusText));
+  }
+  return payload;
+}
+async function safeParseJson2(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+// src/agents/client.ts
+function createAgentsClient(options) {
+  const { apiKey, apiUrl, fetchImpl } = options;
+  const targetApiUrl = apiUrl ?? getPortalURL();
+  assertNonEmpty(apiKey, "apiKey");
+  assertNonEmpty(targetApiUrl, "apiUrl");
+  return {
+    list: async () => {
+      const payload = await requestJson({
+        apiUrl: targetApiUrl,
+        apiKey,
+        path: "/api/agents",
+        method: "GET",
+        fetchImpl
+      });
+      return extractDataArray(payload, "agents");
+    },
+    get: async (id) => {
+      assertNonEmpty(id, "id");
+      const encodedId = encodeURIComponent(id);
+      const payload = await requestJson({
+        apiUrl: targetApiUrl,
+        apiKey,
+        path: `/api/agents/${encodedId}`,
+        method: "GET",
+        fetchImpl
+      });
+      return extractDataRecord(payload, "agent");
+    },
+    create: async (input) => {
+      assertNonEmpty(input.name, "name");
+      const payload = await requestJson({
+        apiUrl: targetApiUrl,
+        apiKey,
+        path: "/api/agents",
+        method: "POST",
+        body: {
+          name: input.name,
+          description: input.description ?? null
+        },
+        fetchImpl
+      });
+      return extractDataRecord(payload, "agent");
+    },
+    update: async (id, input) => {
+      assertNonEmpty(id, "id");
+      assertNonEmpty(input.name, "name");
+      const encodedId = encodeURIComponent(id);
+      const payload = await requestJson({
+        apiUrl: targetApiUrl,
+        apiKey,
+        path: `/api/agents/${encodedId}`,
+        method: "PUT",
+        body: {
+          name: input.name,
+          description: input.description ?? null
+        },
+        fetchImpl
+      });
+      return extractDataRecord(payload, "agent");
+    },
+    delete: async (id) => {
+      assertNonEmpty(id, "id");
+      const encodedId = encodeURIComponent(id);
+      const payload = await requestJson({
+        apiUrl: targetApiUrl,
+        apiKey,
+        path: `/api/agents/${encodedId}`,
+        method: "DELETE",
+        fetchImpl
+      });
+      return extractDeleteResponse(payload);
+    }
+  };
+}
+function extractDataArray(payload, label) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error(`Invalid ${label} response payload`);
+  }
+  const data = payload.data;
+  if (!Array.isArray(data)) {
+    throw new Error(`Invalid ${label} response data`);
+  }
+  return data;
+}
+function extractDataRecord(payload, label) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error(`Invalid ${label} response payload`);
+  }
+  const data = payload.data;
+  if (!data || typeof data !== "object") {
+    throw new Error(`Invalid ${label} response data`);
+  }
+  return data;
+}
+function extractDeleteResponse(payload) {
+  if (!payload || typeof payload !== "object") {
+    throw new Error("Invalid delete response payload");
+  }
+  const id = payload.id;
+  if (!id) {
+    throw new Error("Invalid delete response data");
+  }
+  return { id };
+}
 function createSignedReceipt(options) {
   const { privateKey, algorithm, encoding, ...receiptInput } = options;
   const receipt = createReceipt(receiptInput);
@@ -251,4 +398,4 @@ function generateKeyPair() {
   return { privateKey, publicKey };
 }
 
-export { JOB_RESOLUTIONS, canonicalJSONStringify, createReceipt, createSignedReceipt, generateKeyPair, hashContext, jobReceiptV0Schema, serializeReceipt, signReceipt, submitReceipt, submitSignedReceipt, verifyReceipt };
+export { JOB_RESOLUTIONS, canonicalJSONStringify, createAgentsClient, createReceipt, createSignedReceipt, generateKeyPair, hashContext, jobReceiptV0Schema, serializeReceipt, signReceipt, submitReceipt, submitSignedReceipt, verifyReceipt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultgraph/sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "check-types": "tsc --noEmit",
-    "release": "bash ./scripts/publish.sh"
+    "release": "bash ./scripts/publish.sh",
+    "docs:sync": "node ./scripts/docs-sync.mjs"
   },
   "devDependencies": {
     "@repo/lib": "workspace:*",