@vanditk2/agentvault-types 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandit Kunapareddi
+
+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

@@ -0,0 +1,32 @@
+# `@vanditk2/agentvault-types`
+
+Shared TypeScript types for [AgentVault](https://github.com/vandit-kunapareddi/agentvault) — the public contract every external protocol handler, trust provider, or webhook consumer is written against.
+
+## Install
+
+```bash
+npm install @vanditk2/agentvault-types
+```
+
+## What's in here
+
+Just types. No runtime code, no dependencies.
+
+- `Protocol` — `"x402" | "mpp" | "acp" | "unknown"` (the union widens to any string so you can register custom protocols)
+- `CredentialPayload` — the JWT shape the checkpoint issues + verifies
+- `CheckpointRequest` / `CheckpointResponse` / `CheckpointStatus`
+- `PaymentReceipt`
+- `HandlerArgs` / `ProtocolHandler` — the contract every protocol handler implements
+- `EscalationStatus` / `EscalationDecision` / `EscalationRow` / `ResolveEscalationRequest`
+
+## When to use it
+
+If you're writing **a custom protocol handler** to register with the AgentVault checkpoint, you'll import `ProtocolHandler`, `HandlerArgs`, `PaymentReceipt`. See [`examples/custom-protocol-handler`](https://github.com/vandit-kunapareddi/agentvault/tree/main/examples/custom-protocol-handler) for a worked example.
+
+If you're writing **a webhook subscriber**, the event payload shapes are documented in [`docs/WEBHOOKS.md`](https://github.com/vandit-kunapareddi/agentvault/blob/main/docs/WEBHOOKS.md) — they reference these types.
+
+If you're building **an agent that pays through AgentVault**, you probably want [`@vanditk2/agentvault-sdk`](https://www.npmjs.com/package/@vanditk2/agentvault-sdk) instead, which re-exports the relevant types.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Built-in protocols the checkpoint and SDK know about by name. External
+ * protocol handlers can register themselves with any string — the union
+ * here is just for autocomplete and as documentation of the built-ins.
+ * The `(string & {})` widens the type to accept arbitrary strings without
+ * collapsing the literal autocomplete suggestions.
+ */
+export type Protocol = "x402" | "mpp" | "acp" | "unknown" | (string & {});
+export interface CredentialPayload {
+    agentId: string;
+    agentName: string;
+    walletAddress: string;
+    authorizedBy: string;
+    dailyCap: number;
+    perTxLimit: number;
+    approvedVendors: string[];
+    /**
+     * Optional per-vendor daily spend caps, keyed by vendor hostname. When set,
+     * a payment is blocked if today's spend with that specific vendor plus the
+     * current amount would exceed the per-vendor limit, independently of the
+     * global daily cap. Vendors not present in the map fall back to the global
+     * limits.
+     */
+    vendorLimits?: Record<string, number>;
+    supportedProtocols: Protocol[];
+    issuedAt: number;
+    expiresAt: number;
+}
+export interface CheckpointRequest {
+    credential: string;
+    vendor: string;
+    amount: number;
+    protocol?: Protocol;
+    endpoint?: string;
+}
+export type CheckpointStatus = "approved" | "blocked" | "escalated" | "recognized";
+export interface PaymentReceipt {
+    protocol: Protocol;
+    receiptId: string;
+    vendor: string;
+    amount: number;
+    currency: "USDC";
+    settled: boolean;
+    timestamp: string;
+}
+/**
+ * Arguments passed into a protocol handler by the checkpoint router. The
+ * pipeline has already run trust + budget + vendor checks by the time a
+ * handler is called — the handler's only job is to execute (or simulate)
+ * the payment and return a receipt.
+ */
+export interface HandlerArgs {
+    vendor: string;
+    amount: number;
+    endpoint?: string;
+}
+/**
+ * The contract every protocol handler implements. Returning a receipt with
+ * `settled: false` is logged as "recognized" (not approved); throwing is
+ * caught by the checkpoint and surfaced as a blocked transaction with the
+ * error message as the reason.
+ */
+export type ProtocolHandler = (args: HandlerArgs) => Promise<PaymentReceipt>;
+export interface CheckpointResponse {
+    status: CheckpointStatus;
+    reason?: string;
+    protocol?: Protocol;
+    trustTier?: string;
+    receipt?: PaymentReceipt;
+}
+export type PaymentResult = CheckpointResponse;
+export interface MockPaymentRequest {
+    amount: number;
+    agentId?: string;
+}
+export interface MockPaymentResponse {
+    receiptId: string;
+    vendor: string;
+    amount: number;
+    currency: "USDC";
+    timestamp: string;
+}
+export type EscalationStatus = "pending" | "approved" | "blocked" | "timed_out";
+export type EscalationDecision = "approved" | "blocked";
+export interface EscalationRow {
+    id: string;
+    transactionId: string;
+    agentId: string;
+    agentName: string;
+    vendor: string;
+    amount: number;
+    reason: string | null;
+    status: EscalationStatus;
+    notifiedAt: string | null;
+    resolvedAt: string | null;
+    resolvedBy: string | null;
+    createdAt: string;
+    deadlineAt: string | null;
+}
+export interface ResolveEscalationRequest {
+    decision: EscalationDecision;
+    resolvedBy?: string;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vanditk2/agentvault-types",
+  "version": "0.1.0",
+  "description": "Shared TypeScript types for AgentVault — the public contract for protocol handlers, credentials, escalations, and webhook events.",
+  "keywords": [
+    "agentvault",
+    "agentic-payments",
+    "ai-agents",
+    "x402",
+    "mpp",
+    "acp",
+    "types"
+  ],
+  "license": "MIT",
+  "author": "Vandit Kunapareddi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vandit-kunapareddi/agentvault.git",
+    "directory": "packages/types"
+  },
+  "homepage": "https://github.com/vandit-kunapareddi/agentvault#readme",
+  "bugs": {
+    "url": "https://github.com/vandit-kunapareddi/agentvault/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}