@runplane/runplane-sdk 1.1.0 → 1.1.2

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.0",
+  "version": "1.1.2",
   "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": {