@runplane/runplane-sdk 1.1.2 → 1.1.3

package/README.md

@@ -1,83 +1,122 @@
 # @runplane/runplane-sdk
 
-Official SDK for the Runplane control plane — runtime governance for AI agent actions.
+Control what your AI agents are allowed to do — in real time.
 
 Runplane sits between your AI agents and execution. Every action passes through `guard()`, which enforces a decision before your code runs.
 
-## Installation
+---
+
+## 🚀 Start in 2 Minutes
+
+### 1. Install the SDK
 
 ```bash
 npm install @runplane/runplane-sdk
 ```
 
-## Quick Start (CommonJS)
+---
+
+### 2. Get your API key (Free 14-day trial)
+
+👉 https://runplane.ai/
+
+Create your account and copy your API key.
+
+⚠️ **Important:** The SDK will not work without a valid API key.
+
+---
+
+### 3. Run your first protected action
 
 ```javascript
 require("dotenv").config()
-const { Runplane } = require("@runplain/runplane-sdk");
+const { Runplane } = require("@runplane/runplane-sdk")
+
 const runplane = new Runplane({
   apiKey: process.env.RUNPLANE_API_KEY,
 })
 
-// guard() intercepts execution and enforces the decision
-await runplane.guard(
-  "transfer_funds",
-  "finance-system",
-  { fromAccountId: "acc_1", toAccountId: "acc_2", amount: 400 },
-  async () => {
-    return await executeTransfer()
-  }
-)
+async function main() {
+  await runplane.guard(
+    "transfer_funds",
+    "finance-system",
+    { fromAccountId: "acc_1", toAccountId: "acc_2", amount: 400 },
+    async () => {
+      return await executeTransfer()
+    }
+  )
+}
+
+main()
 ```
 
-## How It Works
+---
+
+## 💡 What Runplane Does
+
+Runplane gives you **real-time control over AI agent actions**.
+
+Before any action runs, Runplane evaluates:
+
+* Policies
+* Risk
+* Context
 
-`guard()` calls the Runplane API over the network before executing your handler:
+And returns a decision:
+
+* **ALLOW** → execution continues
+* **BLOCK** → action is stopped
+* **REQUIRE_APPROVAL** → human approval required
+
+---
+
+## ⚙️ How It Works
+
+`guard()` calls the Runplane API before executing your handler:
 
 1. Sends action + target + context to Runplane
 2. Runplane evaluates policies and risk
-3. Returns one of three decisions:
-   - **ALLOW** → handler executes immediately
-   - **BLOCK** → throws `RunplaneError`, handler never runs
-   - **REQUIRE_APPROVAL** → throws `RunplaneError`, awaits human decision
+3. Returns a decision:
 
-## API Reference
+   * **ALLOW** → handler executes
+   * **BLOCK** → throws `RunplaneError`
+   * **REQUIRE_APPROVAL** → throws `RunplaneError` and waits for approval
 
-### `new Runplane(config)`
+---
 
-Create a new Runplane client.
+## 📘 API Reference
+
+### `new Runplane(config)`
 
 ```javascript
 const runplane = new Runplane({
-  apiKey: "your_api_key",           // Required
-  baseUrl: "https://runplane.ai",   // Optional, defaults to https://runplane.ai
+  apiKey: "your_api_key",
+  baseUrl: "https://runplane.ai",
 })
 ```
 
-### `guard(action, target, context, handler)`
+---
 
-The primary integration method. Wraps your action with Runplane enforcement.
+### `guard(action, target, context, handler)`
 
 ```javascript
 const result = await runplane.guard(
-  "delete_record",           // action type
-  "hr_system",               // target resource
-  { employeeId: "emp_123" }, // context
+  "delete_record",
+  "hr_system",
+  { employeeId: "emp_123" },
   async () => {
-    // Your code here - only runs if ALLOW
     return await deleteEmployee("emp_123")
   }
 )
 ```
 
-**Returns:** The result of `handler()` if decision is ALLOW.
+**Returns:** handler result if ALLOW
+**Throws:** `RunplaneError` if BLOCK or REQUIRE_APPROVAL
 
-**Throws:** `RunplaneError` if decision is BLOCK or REQUIRE_APPROVAL.
+---
 
 ### `decide(payload)`
 
-Low-level method to request a decision without automatic enforcement.
-
 ```javascript
 const result = await runplane.decide({
   action: "send_email",
@@ -85,17 +124,19 @@ const result = await runplane.decide({
   context: { recipients: 1200 },
 })
 
-console.log(result.decision) // "ALLOW" | "BLOCK" | "REQUIRE_APPROVAL"
+console.log(result.decision)
 ```
 
-## Handling Decisions
+---
+
+## 🧠 Handling Decisions
 
 ```javascript
 const { Runplane, RunplaneError } = require("@runplane/runplane-sdk")
 
 try {
   await runplane.guard("action", "target", {}, async () => {
-    // ...
+    // your code
   })
 } catch (err) {
   if (err instanceof RunplaneError) {
@@ -109,36 +150,50 @@ try {
 }
 ```
 
-## Decision Types
+---
+
+## 📊 Decision Types
 
-| Decision | Behavior |
-|----------|----------|
-| `ALLOW` | Handler executes immediately, result returned |
-| `BLOCK` | Throws `RunplaneError` with code `"BLOCK"` |
-| `REQUIRE_APPROVAL` | Throws `RunplaneError` with code `"REQUIRE_APPROVAL"` |
+| Decision           | Behavior                     |
+| ------------------ | ---------------------------- |
+| `ALLOW`            | Handler executes immediately |
+| `BLOCK`            | Throws `RunplaneError`       |
+| `REQUIRE_APPROVAL` | Requires human approval      |
 
-## Error Object
+---
 
-When `guard()` throws, the error includes:
+## ❗ Error Object
 
 ```javascript
 {
   message: "Runplane blocked this action",
-  code: "BLOCK",               // "BLOCK" | "REQUIRE_APPROVAL" | "API_ERROR"
-  runplane: {                  // Full decision response
+  code: "BLOCK",
+  runplane: {
     decision: "BLOCK",
-    reason: "Policy: destructive action on production database",
+    reason: "Policy violation",
     requestId: "req_abc123",
     riskScore: 91,
   }
 }
 ```
 
-## Requirements
+---
+
+## ⚠️ Requirements
+
+* Node.js 18+
+* Runplane API key 👉 https://runplane.ai/
+* Internet access
+
+---
+
+## 💬 Feedback
+
+Got stuck? Something unclear? Want to suggest improvements?
+
+👉 https://runplane.ai/
 
-- Node.js 18+
-- Valid Runplane API key
-- Network access to `https://runplane.ai`
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runplane/runplane-sdk",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Runtime governance SDK for AI agent actions. Wrap sensitive operations with guard() to enforce ALLOW, BLOCK, or REQUIRE_APPROVAL decisions before execution.",
   "main": "./dist/index.js",
   "exports": {
@@ -37,7 +37,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/runplane/sdk.git"
+    "url": "git+https://github.com/runplane/sdk.git"
   },
   "homepage": "https://runplane.ai/developer",
   "bugs": {