@runplane/runplane-sdk 1.1.1 → 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/dist/index.d.ts

@@ -104,138 +104,17 @@ type RunplaneErrorCode = "BLOCKED" | "DENIED" | "TIMEOUT" | "NETWORK_ERROR" | "I
  * @runplane/runplane-sdk - Main client for the Runplane API
  */
 
-/**
- * Runplane SDK Client
- *
- * The main entry point for interacting with the Runplane control plane.
- * Use this to request execution clearance before performing sensitive actions.
- *
- * @example
- * ```typescript
- * import { Runplane } from "@runplane/runplane-sdk";
- *
- * const runplane = new Runplane({
- *   apiKey: process.env.RUNPLANE_SYSTEM_KEY!,
- *   baseUrl: "https://runplane.ai",
- *   failMode: "closed"
- * });
- *
- * const decision = await runplane.decide({
- *   actionType: "send_email",
- *   target: "marketing_list",
- *   context: { recipients: 1200 }
- * });
- *
- * if (decision.decision === "ALLOW") {
- *   // Proceed with the action
- * }
- * ```
- */
 declare class Runplane {
     private readonly baseUrl;
     private readonly apiKey;
     private readonly timeoutMs;
     private readonly failMode;
     private readonly approvalPoller;
+    private hasLoggedInit;
     constructor(config: RunplaneConfig);
-    /**
-     * Request a decision from the Runplane control plane.
-     *
-     * Call this before executing any sensitive action. The response will indicate
-     * whether the action should be ALLOWED, BLOCKED, or REQUIRE_APPROVAL.
-     *
-     * @param request - The action details to evaluate
-     * @returns The decision response
-     *
-     * @example
-     * ```typescript
-     * const decision = await runplane.decide({
-     *   actionType: "delete_record",
-     *   target: "users.prod",
-     *   context: { recordId: "usr_123", reason: "gdpr_request" }
-     * });
-     *
-     * switch (decision.decision) {
-     *   case "ALLOW":
-     *     await deleteRecord(recordId);
-     *     break;
-     *   case "BLOCK":
-     *     console.error("Action blocked:", decision.reason);
-     *     break;
-     *   case "REQUIRE_APPROVAL":
-     *     // Wait for human approval
-     *     const result = await runplane.waitForApproval(decision.requestId);
-     *     if (result.approved) {
-     *       await deleteRecord(recordId);
-     *     }
-     *     break;
-     * }
-     * ```
-     */
     decide(request: DecideRequest): Promise<DecideResponse>;
-    /**
-     * Wait for an approval decision on a pending request.
-     *
-     * Use this when decide() returns REQUIRE_APPROVAL. This method will poll
-     * the approval endpoint until the request is approved, denied, or times out.
-     *
-     * @param requestId - The requestId from the decide() response
-     * @param options - Optional configuration for polling behavior
-     * @returns The approval result
-     *
-     * @example
-     * ```typescript
-     * const decision = await runplane.decide({ ... });
-     *
-     * if (decision.decision === "REQUIRE_APPROVAL") {
-     *   console.log("Waiting for approval...");
-     *
-     *   const result = await runplane.waitForApproval(decision.requestId, {
-     *     timeoutMs: 600000, // 10 minutes
-     *     onPoll: (status, elapsed) => {
-     *       console.log(`Still waiting... ${elapsed}ms elapsed`);
-     *     }
-     *   });
-     *
-     *   if (result.approved) {
-     *     console.log("Approved by:", result.resolvedBy);
-     *   } else {
-     *     console.log("Denied:", result.comment);
-     *   }
-     * }
-     * ```
-     */
     waitForApproval(requestId: string, options?: WaitForApprovalOptions): Promise<WaitForApprovalResult>;
-    /**
-     * Guard a function with containment evaluation.
-     *
-     * This is a convenience method that wraps decide() and waitForApproval()
-     * into a single call. If the action is blocked or denied, it throws.
-     * If approved, it executes the provided function.
-     *
-     * @param actionType - Type of action being performed
-     * @param target - Target resource
-     * @param context - Additional context
-     * @param fn - Function to execute if allowed
-     * @returns The result of fn()
-     * @throws RunplaneError if blocked, denied, or times out (in closed mode)
-     *
-     * @example
-     * ```typescript
-     * const result = await runplane.guard(
-     *   "payment_transfer",
-     *   "external_bank",
-     *   { amount: 50000, currency: "USD" },
-     *   async () => {
-     *     return await paymentService.transfer(amount, recipient);
-     *   }
-     * );
-     * ```
-     */
     guard<T>(actionType: string, target: string, context: Record<string, unknown> | null, fn: () => Promise<T>): Promise<T>;
-    /**
-     * Handle API failures according to failMode
-     */
     private handleFailure;
 }
 

package/dist/index.js

@@ -138,10 +138,16 @@ var DEFAULT_APPROVAL_TIMEOUT_MS = 3e5;
 var DEFAULT_APPROVAL_POLL_INTERVAL_MS = 2e3;
 var Runplane = class {
   constructor(config) {
-    if (!config.apiKey) {
-      throw new RunplaneError(
-        "API key is required",
-        "INVALID_CONFIG"
+    // 🔥 New: log only once per instance
+    this.hasLoggedInit = false;
+    if (!config?.apiKey || config.apiKey.trim() === "") {
+      throw new Error(
+        `Runplane API key is required.
+
+\u{1F449} Start your free 14-day trial:
+https://runplane.ai/
+
+Then add your API key to the SDK config.`
       );
     }
     this.apiKey = config.apiKey;
@@ -155,40 +161,6 @@ var Runplane = class {
       pollIntervalMs: config.approvalPollIntervalMs ?? DEFAULT_APPROVAL_POLL_INTERVAL_MS
     });
   }
-  /**
-   * Request a decision from the Runplane control plane.
-   * 
-   * Call this before executing any sensitive action. The response will indicate
-   * whether the action should be ALLOWED, BLOCKED, or REQUIRE_APPROVAL.
-   * 
-   * @param request - The action details to evaluate
-   * @returns The decision response
-   * 
-   * @example
-   * ```typescript
-   * const decision = await runplane.decide({
-   *   actionType: "delete_record",
-   *   target: "users.prod",
-   *   context: { recordId: "usr_123", reason: "gdpr_request" }
-   * });
-   * 
-   * switch (decision.decision) {
-   *   case "ALLOW":
-   *     await deleteRecord(recordId);
-   *     break;
-   *   case "BLOCK":
-   *     console.error("Action blocked:", decision.reason);
-   *     break;
-   *   case "REQUIRE_APPROVAL":
-   *     // Wait for human approval
-   *     const result = await runplane.waitForApproval(decision.requestId);
-   *     if (result.approved) {
-   *       await deleteRecord(recordId);
-   *     }
-   *     break;
-   * }
-   * ```
-   */
   async decide(request) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -197,7 +169,7 @@ var Runplane = class {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "Authorization": `Bearer ${this.apiKey}`
+          Authorization: `Bearer ${this.apiKey}`
         },
         body: JSON.stringify({
           agentKey: this.apiKey,
@@ -240,68 +212,16 @@ var Runplane = class {
       clearTimeout(timeout);
     }
   }
-  /**
-   * Wait for an approval decision on a pending request.
-   * 
-   * Use this when decide() returns REQUIRE_APPROVAL. This method will poll
-   * the approval endpoint until the request is approved, denied, or times out.
-   * 
-   * @param requestId - The requestId from the decide() response
-   * @param options - Optional configuration for polling behavior
-   * @returns The approval result
-   * 
-   * @example
-   * ```typescript
-   * const decision = await runplane.decide({ ... });
-   * 
-   * if (decision.decision === "REQUIRE_APPROVAL") {
-   *   console.log("Waiting for approval...");
-   *   
-   *   const result = await runplane.waitForApproval(decision.requestId, {
-   *     timeoutMs: 600000, // 10 minutes
-   *     onPoll: (status, elapsed) => {
-   *       console.log(`Still waiting... ${elapsed}ms elapsed`);
-   *     }
-   *   });
-   *   
-   *   if (result.approved) {
-   *     console.log("Approved by:", result.resolvedBy);
-   *   } else {
-   *     console.log("Denied:", result.comment);
-   *   }
-   * }
-   * ```
-   */
   async waitForApproval(requestId, options) {
     return this.approvalPoller.poll(requestId, options);
   }
-  /**
-   * Guard a function with containment evaluation.
-   * 
-   * This is a convenience method that wraps decide() and waitForApproval()
-   * into a single call. If the action is blocked or denied, it throws.
-   * If approved, it executes the provided function.
-   * 
-   * @param actionType - Type of action being performed
-   * @param target - Target resource
-   * @param context - Additional context
-   * @param fn - Function to execute if allowed
-   * @returns The result of fn()
-   * @throws RunplaneError if blocked, denied, or times out (in closed mode)
-   * 
-   * @example
-   * ```typescript
-   * const result = await runplane.guard(
-   *   "payment_transfer",
-   *   "external_bank",
-   *   { amount: 50000, currency: "USD" },
-   *   async () => {
-   *     return await paymentService.transfer(amount, recipient);
-   *   }
-   * );
-   * ```
-   */
   async guard(actionType, target, context, fn) {
+    if (!this.hasLoggedInit) {
+      console.log(
+        "Runplane active. Manage your policies at https://runplane.ai/"
+      );
+      this.hasLoggedInit = true;
+    }
     const response = await this.decide({
       actionType,
       target,
@@ -337,9 +257,6 @@ var Runplane = class {
       response.requestId
     );
   }
-  /**
-   * Handle API failures according to failMode
-   */
   handleFailure(reason, request) {
     const requestId = request.requestId ?? crypto.randomUUID();
     if (this.failMode === "open") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runplane/runplane-sdk",
-  "version": "1.1.1",
+  "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": {