@edge-protocol/sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to `@edge-protocol/sdk` are documented here.
+
+---
+
+## [0.8.0] — 2026-06-20
+
+### Added
+
+- **`sdk.simulate(pass, requests[])`** — predict outcomes for a sequence of transactions without executing. Zero network calls. Returns `SimulationResult` with approved, blocked, and escalated decisions plus projected budget state after each step. Use to show agents their plan before touching the chain.
+
+- **`sdk.budgetStatus(pass)`** — returns a complete `BudgetStatus` snapshot: spent, remaining, utilization percentage, `isNearLimit`, `isExhausted`.
+
+- **`sdk.utilizationPct(pass)`** — budget utilization as 0-100 number. Use for progress bars and budget warnings.
+
+- **`sdk.isNearLimit(pass, threshold?)`** — returns true if utilization exceeds threshold (default 80%). Use to warn agents before they exhaust budget.
+
+- **`sdk.timeRemaining(pass)`** — milliseconds until pass expires. Returns 0 if expired.
+
+- **`sdk.isExpiringSoon(pass, withinMs?)`** — returns true if pass expires within the given window (default 1 hour).
+
+- **`EdgePass.withPolicy(pass, signer, sdk, fn)`** — higher-order function that wraps any async tool call with EdgePass policy enforcement. The wrapped function only executes if the transaction is approved. Perfect for Vercel AI SDK / Mastra tool definitions.
+
+- **New types exported:** `SimulatedDecision`, `SimulationResult`, `BudgetStatus`
+
+### Changed
+
+- `PolicyEngine.simulate()` is now a static method on `PolicyEngine` and also exposed as `sdk.simulate()` on the `EdgePass` class for convenience.
+- All budget and time helpers are now available both as static `PolicyEngine` methods and instance `sdk` methods.
+
+---
+
+## [0.7.1] — 2026-06-19
+
+### Fixed
+
+- Reverted `tx.objectRef()` optimization from v0.7.0. While theoretically faster, storing object version at fetch time caused version conflicts when Enoki gas sponsorship updated the object between fetch and execution. `tx.object(pass.id)` resolves version at signing time which is the correct and safe pattern.
+
+---
+
+## [0.7.0] — 2026-06-19 — YANKED
+
+Version yanked due to object version conflict regression. Use 0.7.1 instead.
+
+---
+
+## [0.6.6] — 2026-06-18
+
+### Changed
+
+- Updated README with mainnet contract address and live transaction digests
+- Stronger competitive positioning and security model documentation
+
+---
+
+## [0.6.0] — 2026-06-17
+
+### Added
+
+- **Error status as a distinct fourth outcome** — infrastructure failures (`status: 'error'`) are now clearly distinguished from policy rejections (`status: 'blocked'`). A network failure no longer pretends to be a policy decision.
+- **`classifyError()`** — internal error classifier that maps RPC/network/signing errors to typed `EdgeErrorCode` values for programmatic handling.
+- **`fetchPass()` validation** — validates objectId format before hitting the RPC. Throws with a clear message for malformed IDs rather than a cryptic RPC error.
+- **Config validation on `create()`** — prevents impossible EdgePass configurations (e.g. autoThreshold >= escalateThreshold) at creation time rather than at execution time.
+
+---
+
+## [0.5.0] — 2026-06-16
+
+### Added
+
+- **Events system** — `sdk.on('approved')`, `sdk.on('escalated')`, `sdk.on('blocked')`. React to transaction outcomes without polling. Chain-able.
+- `sdk.off()` and `sdk.removeAllListeners()` for cleanup.
+- 34 comprehensive tests — PolicyEngine, fromTemplate, constants, events system.
+
+### Changed
+
+- Events fire for policy outcomes only (`approved`, `escalated`, `blocked`). Infrastructure errors (`status: 'error'`) do not fire events — check `outcome.status === 'error'` explicitly.
+
+---
+
+## [0.4.7] — 2026-06-15
+
+### Added
+
+- Comprehensive `DOCS.md` — full API reference, examples, types, architecture.
+- `maxPerTransaction` field on `EdgePassConfig` — optional per-transaction cap independent of escalation threshold.
+
+---
+
+## [0.4.6] — 2026-06-14
+
+### Added
+
+- 27 comprehensive tests — PolicyEngine validation, `fromTemplate()`, constants.
+- `EDGE_TEMPLATES` constants for festival, gaming, subscription, defi, enterprise.
+- `EdgePass.fromTemplate()` static helper.
+
+---
+
+## [0.4.0] — 2026-06-13
+
+### Added
+
+- Initial public release.
+- `EdgePass` class with `create()`, `execute()`, `validate()`, `fetch()`, `revoke()`.
+- `PolicyEngine` with 7-rule validation chain.
+- `ExecutionEngine` with on-chain PTB construction.
+- Mainnet + testnet support.
+- zkLogin compatible signer interface.

package/dist/react/index.d.ts

@@ -0,0 +1,29 @@
+import { Transaction } from '@mysten/sui/transactions';
+import { EdgePass } from '../core/EdgePass';
+import { EdgePassObject, TransactionRequest, TransactionOutcome, SimulationResult, BudgetStatus, Network } from '../utils/types';
+export interface UseEdgePassConfig {
+    passId: string;
+    network: Network;
+    enokiApiKey: string;
+    signer?: {
+        signAndExecute: (tx: Transaction) => Promise<{
+            digest: string;
+        }>;
+    };
+    autoRefresh?: boolean;
+    pollInterval?: number;
+}
+export interface UseEdgePassResult {
+    pass: EdgePassObject | null;
+    loading: boolean;
+    error: Error | null;
+    execute: (request: TransactionRequest) => Promise<TransactionOutcome>;
+    simulate: (requests: TransactionRequest[]) => SimulationResult | null;
+    budgetStatus: BudgetStatus | null;
+    refresh: () => Promise<void>;
+    sdk: EdgePass;
+}
+export declare function useEdgePass({ passId, network, enokiApiKey, signer, autoRefresh, pollInterval, }: UseEdgePassConfig): UseEdgePassResult;
+export declare function useBudgetStatus(config: UseEdgePassConfig): BudgetStatus | null;
+export declare function useSimulate(config: UseEdgePassConfig, requests: TransactionRequest[]): SimulationResult | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,OAAO,EACR,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAS,MAAM,CAAC;IACtB,OAAO,EAAQ,OAAO,CAAC;IACvB,WAAW,EAAI,MAAM,CAAC;IACtB,MAAM,CAAC,EAAQ;QAAE,cAAc,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;IACpF,WAAW,CAAC,EAAG,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAU,cAAc,GAAG,IAAI,CAAC;IACpC,OAAO,EAAO,OAAO,CAAC;IACtB,KAAK,EAAS,KAAK,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAO,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC3E,QAAQ,EAAM,CAAC,QAAQ,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,GAAG,IAAI,CAAC;IAC1E,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,OAAO,EAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,GAAG,EAAW,QAAQ,CAAC;CACxB;AAED,wBAAgB,WAAW,CAAC,EAC1B,MAAM,EACN,OAAO,EACP,WAAW,EACX,MAAM,EACN,WAAkB,EAClB,YAAgB,GACjB,EAAE,iBAAiB,GAAG,iBAAiB,CAsDvC;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,YAAY,GAAG,IAAI,CAG9E;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,kBAAkB,EAAE,GAC7B,gBAAgB,GAAG,IAAI,CAGzB"}

package/dist/react/index.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useEdgePass = useEdgePass;
+exports.useBudgetStatus = useBudgetStatus;
+exports.useSimulate = useSimulate;
+const react_1 = require("react");
+const EdgePass_1 = require("../core/EdgePass");
+function useEdgePass({ passId, network, enokiApiKey, signer, autoRefresh = true, pollInterval = 0, }) {
+    const [pass, setPass] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const sdkRef = (0, react_1.useRef)(new EdgePass_1.EdgePass({ network, enokiApiKey }));
+    (0, react_1.useEffect)(() => {
+        sdkRef.current = new EdgePass_1.EdgePass({ network, enokiApiKey });
+    }, [network, enokiApiKey]);
+    const refresh = (0, react_1.useCallback)(async () => {
+        if (!passId)
+            return;
+        try {
+            setError(null);
+            const fetched = await sdkRef.current.fetch(passId);
+            setPass(fetched);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e : new Error(String(e)));
+        }
+    }, [passId]);
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        setLoading(true);
+        sdkRef.current.fetch(passId)
+            .then(fetched => { if (!cancelled) {
+            setPass(fetched);
+            setError(null);
+        } })
+            .catch(e => { if (!cancelled)
+            setError(e instanceof Error ? e : new Error(String(e))); })
+            .finally(() => { if (!cancelled)
+            setLoading(false); });
+        return () => { cancelled = true; };
+    }, [passId]);
+    (0, react_1.useEffect)(() => {
+        if (!pollInterval || pollInterval <= 0)
+            return;
+        const interval = setInterval(refresh, pollInterval);
+        return () => clearInterval(interval);
+    }, [refresh, pollInterval]);
+    const execute = (0, react_1.useCallback)(async (request) => {
+        if (!pass)
+            throw new Error('EdgePass not loaded');
+        if (!signer)
+            throw new Error('No signer provided');
+        const outcome = await sdkRef.current.execute(pass, request, signer);
+        if (outcome.status === 'approved' && autoRefresh)
+            await refresh();
+        return outcome;
+    }, [pass, signer, autoRefresh, refresh]);
+    const simulate = (0, react_1.useCallback)((requests) => {
+        if (!pass)
+            return null;
+        return sdkRef.current.simulate(pass, requests);
+    }, [pass]);
+    const budgetStatus = pass ? sdkRef.current.budgetStatus(pass) : null;
+    return { pass, loading, error, execute, simulate, budgetStatus, refresh, sdk: sdkRef.current };
+}
+function useBudgetStatus(config) {
+    const { budgetStatus } = useEdgePass(config);
+    return budgetStatus;
+}
+function useSimulate(config, requests) {
+    const { simulate } = useEdgePass(config);
+    return simulate(requests);
+}
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

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

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "@edge-protocol/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Programmable trust infrastructure for autonomous AI agents on Sui. Give agents your rules, not your keys.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "require": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    }
+  },
   "files": [
     "dist",
     "README.md",
-    "DOCS.md"
+    "DOCS.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
@@ -15,51 +26,22 @@
     "test": "ts-node --compiler-options '{\"module\":\"CommonJS\"}' src/test.ts",
     "prepublishOnly": "pnpm build"
   },
-  "keywords": [
-    "sui",
-    "sui-sdk",
-    "zklogin",
-    "autonomous-agents",
-    "ai-agents",
-    "trust-delegation",
-    "edgepass",
-    "walrus",
-    "defi",
-    "web3",
-    "blockchain",
-    "move",
-    "move-language",
-    "ptb",
-    "programmable-transaction",
-    "agent-policy",
-    "spending-limits",
-    "crypto-agents",
-    "agentic-web",
-    "autonomous",
-    "trust",
-    "delegation",
-    "agent",
-    "mysten",
-    "enoki",
-    "sponsored-transactions"
-  ],
-  "author": "fluturecode",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/fluturecode/edge"
-  },
-  "homepage": "https://github.com/fluturecode/edge#readme",
-  "bugs": {
-    "url": "https://github.com/fluturecode/edge/issues"
-  },
   "dependencies": {
     "@mysten/sui": "^1.30.0",
     "@mysten/zklogin": "^0.8.1"
   },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^20.19.41",
+    "@types/react": "^18.3.31",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }
-}
+}