@runplane/runplane-sdk 1.0.1 → 1.0.3

package/dist/index.d.mts

@@ -0,0 +1,268 @@
+/**
+ * @runplane/runplane-sdk - TypeScript types for the Runplane SDK
+ */
+/** Decision returned by the Runplane control plane */
+type Decision = "ALLOW" | "BLOCK" | "REQUIRE_APPROVAL";
+/** Approval status for pending actions */
+type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
+/** Behavior when the API is unreachable or times out */
+type FailMode = "open" | "closed";
+/**
+ * Configuration options for the Runplane client
+ */
+interface RunplaneConfig {
+    /** Your Runplane API key (starts with ars_) */
+    apiKey: string;
+    /** Base URL for the Runplane API. Defaults to https://runplane.ai */
+    baseUrl?: string;
+    /** Timeout for API requests in milliseconds. Defaults to 3000 */
+    timeoutMs?: number;
+    /**
+     * Behavior when API is unreachable:
+     * - "closed" (default): Block actions when API is unavailable
+     * - "open": Allow actions when API is unavailable (less secure)
+     */
+    failMode?: FailMode;
+    /** Timeout for approval polling in milliseconds. Defaults to 300000 (5 min) */
+    approvalTimeoutMs?: number;
+    /** Interval between approval polls in milliseconds. Defaults to 2000 */
+    approvalPollIntervalMs?: number;
+}
+/**
+ * Request payload for the decide endpoint
+ */
+interface DecideRequest {
+    /** Type of action being performed (e.g., "send_email", "delete_record") */
+    actionType: string;
+    /** Target resource or destination (e.g., "prod-db", "user@example.com") */
+    target: string;
+    /** Additional context for risk evaluation */
+    context?: Record<string, unknown>;
+    /** Optional request ID for idempotency */
+    requestId?: string;
+}
+/**
+ * Response from the decide endpoint
+ */
+interface DecideResponse {
+    /** The decision: ALLOW, BLOCK, or REQUIRE_APPROVAL */
+    decision: Decision;
+    /** Human-readable reason for the decision */
+    reason: string;
+    /** Unique identifier for this request (use for approval polling) */
+    requestId: string;
+    /** The policy rule that matched, if any */
+    matchedRule?: string;
+    /** Computed risk score (0-100) */
+    riskScore?: number;
+    /** Risk severity classification */
+    severity?: string;
+}
+/**
+ * Response from the approval polling endpoint
+ */
+interface ApprovalPollResponse {
+    /** Current status of the approval request */
+    status: ApprovalStatus;
+    /** ISO timestamp when the approval was resolved */
+    resolvedAt?: string;
+    /** User who approved/denied the request */
+    resolvedBy?: string;
+    /** Optional comment from the approver */
+    comment?: string;
+}
+/**
+ * Options for waitForApproval method
+ */
+interface WaitForApprovalOptions {
+    /** Override the default approval timeout */
+    timeoutMs?: number;
+    /** Override the default poll interval */
+    pollIntervalMs?: number;
+    /** Callback invoked on each poll (for progress updates) */
+    onPoll?: (status: ApprovalStatus, elapsedMs: number) => void;
+}
+/**
+ * Result from waitForApproval method
+ */
+interface WaitForApprovalResult {
+    /** Whether the action was approved */
+    approved: boolean;
+    /** Final status */
+    status: ApprovalStatus;
+    /** Optional comment from the approver */
+    comment?: string;
+    /** User who resolved the request */
+    resolvedBy?: string;
+}
+/**
+ * Error codes for RunplaneError
+ */
+type RunplaneErrorCode = "BLOCKED" | "DENIED" | "TIMEOUT" | "NETWORK_ERROR" | "INVALID_CONFIG" | "UNKNOWN";
+
+/**
+ * @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;
+    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;
+}
+
+/**
+ * @runplane/runplane-sdk - Error handling
+ */
+
+/**
+ * Error thrown by the Runplane SDK
+ *
+ * This error is thrown when:
+ * - An action is blocked by policy
+ * - An approval request is denied
+ * - Approval times out (in fail-closed mode)
+ * - Network errors occur (in fail-closed mode)
+ * - Invalid configuration is provided
+ */
+declare class RunplaneError extends Error {
+    /** Error classification code */
+    readonly code: RunplaneErrorCode;
+    /** Request ID associated with this error, if available */
+    readonly requestId?: string;
+    constructor(message: string, code: RunplaneErrorCode, requestId?: string);
+    isBlocked(): boolean;
+    isDenied(): boolean;
+    isTimeout(): boolean;
+    isNetworkError(): boolean;
+}
+
+export { type ApprovalPollResponse, type ApprovalStatus, type DecideRequest, type DecideResponse, type Decision, type FailMode, Runplane, type RunplaneConfig, RunplaneError, type RunplaneErrorCode, type WaitForApprovalOptions, type WaitForApprovalResult };

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+/**
+ * @runplane/runplane-sdk - TypeScript types for the Runplane SDK
+ */
+/** Decision returned by the Runplane control plane */
+type Decision = "ALLOW" | "BLOCK" | "REQUIRE_APPROVAL";
+/** Approval status for pending actions */
+type ApprovalStatus = "pending" | "approved" | "denied" | "expired";
+/** Behavior when the API is unreachable or times out */
+type FailMode = "open" | "closed";
+/**
+ * Configuration options for the Runplane client
+ */
+interface RunplaneConfig {
+    /** Your Runplane API key (starts with ars_) */
+    apiKey: string;
+    /** Base URL for the Runplane API. Defaults to https://runplane.ai */
+    baseUrl?: string;
+    /** Timeout for API requests in milliseconds. Defaults to 3000 */
+    timeoutMs?: number;
+    /**
+     * Behavior when API is unreachable:
+     * - "closed" (default): Block actions when API is unavailable
+     * - "open": Allow actions when API is unavailable (less secure)
+     */
+    failMode?: FailMode;
+    /** Timeout for approval polling in milliseconds. Defaults to 300000 (5 min) */
+    approvalTimeoutMs?: number;
+    /** Interval between approval polls in milliseconds. Defaults to 2000 */
+    approvalPollIntervalMs?: number;
+}
+/**
+ * Request payload for the decide endpoint
+ */
+interface DecideRequest {
+    /** Type of action being performed (e.g., "send_email", "delete_record") */
+    actionType: string;
+    /** Target resource or destination (e.g., "prod-db", "user@example.com") */
+    target: string;
+    /** Additional context for risk evaluation */
+    context?: Record<string, unknown>;
+    /** Optional request ID for idempotency */
+    requestId?: string;
+}
+/**
+ * Response from the decide endpoint
+ */
+interface DecideResponse {
+    /** The decision: ALLOW, BLOCK, or REQUIRE_APPROVAL */
+    decision: Decision;
+    /** Human-readable reason for the decision */
+    reason: string;
+    /** Unique identifier for this request (use for approval polling) */
+    requestId: string;
+    /** The policy rule that matched, if any */
+    matchedRule?: string;
+    /** Computed risk score (0-100) */
+    riskScore?: number;
+    /** Risk severity classification */
+    severity?: string;
+}
+/**
+ * Response from the approval polling endpoint
+ */
+interface ApprovalPollResponse {
+    /** Current status of the approval request */
+    status: ApprovalStatus;
+    /** ISO timestamp when the approval was resolved */
+    resolvedAt?: string;
+    /** User who approved/denied the request */
+    resolvedBy?: string;
+    /** Optional comment from the approver */
+    comment?: string;
+}
+/**
+ * Options for waitForApproval method
+ */
+interface WaitForApprovalOptions {
+    /** Override the default approval timeout */
+    timeoutMs?: number;
+    /** Override the default poll interval */
+    pollIntervalMs?: number;
+    /** Callback invoked on each poll (for progress updates) */
+    onPoll?: (status: ApprovalStatus, elapsedMs: number) => void;
+}
+/**
+ * Result from waitForApproval method
+ */
+interface WaitForApprovalResult {
+    /** Whether the action was approved */
+    approved: boolean;
+    /** Final status */
+    status: ApprovalStatus;
+    /** Optional comment from the approver */
+    comment?: string;
+    /** User who resolved the request */
+    resolvedBy?: string;
+}
+/**
+ * Error codes for RunplaneError
+ */
+type RunplaneErrorCode = "BLOCKED" | "DENIED" | "TIMEOUT" | "NETWORK_ERROR" | "INVALID_CONFIG" | "UNKNOWN";
+
+/**
+ * @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;
+    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;
+}
+
+/**
+ * @runplane/runplane-sdk - Error handling
+ */
+
+/**
+ * Error thrown by the Runplane SDK
+ *
+ * This error is thrown when:
+ * - An action is blocked by policy
+ * - An approval request is denied
+ * - Approval times out (in fail-closed mode)
+ * - Network errors occur (in fail-closed mode)
+ * - Invalid configuration is provided
+ */
+declare class RunplaneError extends Error {
+    /** Error classification code */
+    readonly code: RunplaneErrorCode;
+    /** Request ID associated with this error, if available */
+    readonly requestId?: string;
+    constructor(message: string, code: RunplaneErrorCode, requestId?: string);
+    isBlocked(): boolean;
+    isDenied(): boolean;
+    isTimeout(): boolean;
+    isNetworkError(): boolean;
+}
+
+export { type ApprovalPollResponse, type ApprovalStatus, type DecideRequest, type DecideResponse, type Decision, type FailMode, Runplane, type RunplaneConfig, RunplaneError, type RunplaneErrorCode, type WaitForApprovalOptions, type WaitForApprovalResult };

package/dist/index.js

@@ -1,21 +1,362 @@
-class Runplane {
-  constructor(apiKey, baseUrl = "https://runplane.ai") {
-        this.apiKey = apiKey;
-    this.baseUrl = baseUrl;
-  }
-
-  async decide(payload) {
-    const response = await fetch(`${this.baseUrl}/api/decide`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
-      },
-      body: JSON.stringify(payload)
-    });
-
-    return response.json();
-  }
-}
-
-module.exports = Runplane;
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Runplane: () => Runplane,
+  RunplaneError: () => RunplaneError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/error.ts
+var RunplaneError = class _RunplaneError extends Error {
+  constructor(message, code, requestId) {
+    super(message);
+    this.name = "RunplaneError";
+    this.code = code;
+    this.requestId = requestId;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _RunplaneError);
+    }
+  }
+  isBlocked() {
+    return this.code === "BLOCKED";
+  }
+  isDenied() {
+    return this.code === "DENIED";
+  }
+  isTimeout() {
+    return this.code === "TIMEOUT";
+  }
+  isNetworkError() {
+    return this.code === "NETWORK_ERROR";
+  }
+};
+
+// src/approval.ts
+var ApprovalPoller = class {
+  // Cap at 10 seconds
+  constructor(config) {
+    this.maxPollIntervalMs = 1e4;
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.defaultTimeoutMs = config.timeoutMs;
+    this.defaultPollIntervalMs = config.pollIntervalMs;
+  }
+  /**
+   * Poll for approval status until resolved or timeout
+   */
+  async poll(requestId, options) {
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const initialInterval = options?.pollIntervalMs ?? this.defaultPollIntervalMs;
+    const onPoll = options?.onPoll;
+    const startTime = Date.now();
+    let interval = initialInterval;
+    while (Date.now() - startTime < timeoutMs) {
+      try {
+        const response = await this.fetchApprovalStatus(requestId);
+        const elapsed = Date.now() - startTime;
+        const normalizedStatus = this.normalizeStatus(response);
+        if (onPoll) {
+          onPoll(normalizedStatus, elapsed);
+        }
+        if (normalizedStatus !== "pending") {
+          return {
+            approved: normalizedStatus === "approved",
+            status: normalizedStatus,
+            comment: response.comment || response.reason,
+            resolvedBy: response.resolvedBy || response.approvedBy
+          };
+        }
+        await this.sleep(interval);
+        interval = Math.min(interval * 1.5, this.maxPollIntervalMs);
+      } catch {
+        await this.sleep(interval);
+        interval = Math.min(interval * 2, this.maxPollIntervalMs);
+      }
+    }
+    return {
+      approved: false,
+      status: "expired"
+    };
+  }
+  /**
+   * Fetch current approval status from the API
+   */
+  async fetchApprovalStatus(requestId) {
+    const response = await fetch(
+      `${this.baseUrl}/api/approvals/poll/${requestId}`,
+      {
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to fetch approval status: ${response.statusText}`);
+    }
+    return response.json();
+  }
+  /**
+   * Normalize server response → SDK canonical format
+   */
+  normalizeStatus(response) {
+    const raw = response.status || response.decision || response.decisionOutcome || "";
+    const normalized = String(raw).toLowerCase();
+    if (normalized === "approved" || normalized === "allow") {
+      return "approved";
+    }
+    if (normalized === "denied" || normalized === "deny" || normalized === "block") {
+      return "denied";
+    }
+    if (normalized === "pending") {
+      return "pending";
+    }
+    if (normalized === "expired") {
+      return "expired";
+    }
+    return "pending";
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://runplane.ai";
+var DEFAULT_TIMEOUT_MS = 3e3;
+var DEFAULT_FAIL_MODE = "closed";
+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"
+      );
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.failMode = config.failMode ?? DEFAULT_FAIL_MODE;
+    this.approvalPoller = new ApprovalPoller({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      timeoutMs: config.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
+      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);
+    try {
+      const response = await fetch(`${this.baseUrl}/api/decide`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          agentKey: this.apiKey,
+          actionType: request.actionType,
+          target: request.target,
+          context: request.context ?? {},
+          requestId: request.requestId
+        }),
+        signal: controller.signal
+      });
+      const json = await response.json();
+      if (!response.ok) {
+        return this.handleFailure(
+          `API error: ${json.error ?? response.statusText}`,
+          request
+        );
+      }
+      return {
+        decision: json.decision,
+        reason: json.reason,
+        requestId: json.requestId,
+        matchedRule: json.matchedRule,
+        riskScore: json.riskScore,
+        severity: json.severity
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return this.handleFailure(`Network failure: ${message}`, request);
+    } finally {
+      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) {
+    const response = await this.decide({
+      actionType,
+      target,
+      context: context ?? void 0
+    });
+    if (response.decision === "BLOCK") {
+      throw new RunplaneError(
+        `Action blocked: ${response.reason}`,
+        "BLOCKED",
+        response.requestId
+      );
+    }
+    if (response.decision === "ALLOW") {
+      return fn();
+    }
+    const approval = await this.waitForApproval(response.requestId);
+    if (approval.approved) {
+      return fn();
+    }
+    if (approval.status === "denied") {
+      throw new RunplaneError(
+        `Action denied: ${approval.comment || "No reason provided"}`,
+        "DENIED",
+        response.requestId
+      );
+    }
+    if (this.failMode === "open") {
+      return fn();
+    }
+    throw new RunplaneError(
+      "Approval timeout - action blocked (fail-closed)",
+      "TIMEOUT",
+      response.requestId
+    );
+  }
+  /**
+   * Handle API failures according to failMode
+   */
+  handleFailure(reason, request) {
+    const requestId = request.requestId ?? crypto.randomUUID();
+    if (this.failMode === "open") {
+      return {
+        decision: "ALLOW",
+        reason: `${reason} (fail-open)`,
+        requestId
+      };
+    }
+    return {
+      decision: "BLOCK",
+      reason: `${reason} (fail-closed)`,
+      requestId
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Runplane,
+  RunplaneError
+});

package/dist/index.mjs

@@ -0,0 +1,334 @@
+// src/error.ts
+var RunplaneError = class _RunplaneError extends Error {
+  constructor(message, code, requestId) {
+    super(message);
+    this.name = "RunplaneError";
+    this.code = code;
+    this.requestId = requestId;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _RunplaneError);
+    }
+  }
+  isBlocked() {
+    return this.code === "BLOCKED";
+  }
+  isDenied() {
+    return this.code === "DENIED";
+  }
+  isTimeout() {
+    return this.code === "TIMEOUT";
+  }
+  isNetworkError() {
+    return this.code === "NETWORK_ERROR";
+  }
+};
+
+// src/approval.ts
+var ApprovalPoller = class {
+  // Cap at 10 seconds
+  constructor(config) {
+    this.maxPollIntervalMs = 1e4;
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.defaultTimeoutMs = config.timeoutMs;
+    this.defaultPollIntervalMs = config.pollIntervalMs;
+  }
+  /**
+   * Poll for approval status until resolved or timeout
+   */
+  async poll(requestId, options) {
+    const timeoutMs = options?.timeoutMs ?? this.defaultTimeoutMs;
+    const initialInterval = options?.pollIntervalMs ?? this.defaultPollIntervalMs;
+    const onPoll = options?.onPoll;
+    const startTime = Date.now();
+    let interval = initialInterval;
+    while (Date.now() - startTime < timeoutMs) {
+      try {
+        const response = await this.fetchApprovalStatus(requestId);
+        const elapsed = Date.now() - startTime;
+        const normalizedStatus = this.normalizeStatus(response);
+        if (onPoll) {
+          onPoll(normalizedStatus, elapsed);
+        }
+        if (normalizedStatus !== "pending") {
+          return {
+            approved: normalizedStatus === "approved",
+            status: normalizedStatus,
+            comment: response.comment || response.reason,
+            resolvedBy: response.resolvedBy || response.approvedBy
+          };
+        }
+        await this.sleep(interval);
+        interval = Math.min(interval * 1.5, this.maxPollIntervalMs);
+      } catch {
+        await this.sleep(interval);
+        interval = Math.min(interval * 2, this.maxPollIntervalMs);
+      }
+    }
+    return {
+      approved: false,
+      status: "expired"
+    };
+  }
+  /**
+   * Fetch current approval status from the API
+   */
+  async fetchApprovalStatus(requestId) {
+    const response = await fetch(
+      `${this.baseUrl}/api/approvals/poll/${requestId}`,
+      {
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`
+        }
+      }
+    );
+    if (!response.ok) {
+      throw new Error(`Failed to fetch approval status: ${response.statusText}`);
+    }
+    return response.json();
+  }
+  /**
+   * Normalize server response → SDK canonical format
+   */
+  normalizeStatus(response) {
+    const raw = response.status || response.decision || response.decisionOutcome || "";
+    const normalized = String(raw).toLowerCase();
+    if (normalized === "approved" || normalized === "allow") {
+      return "approved";
+    }
+    if (normalized === "denied" || normalized === "deny" || normalized === "block") {
+      return "denied";
+    }
+    if (normalized === "pending") {
+      return "pending";
+    }
+    if (normalized === "expired") {
+      return "expired";
+    }
+    return "pending";
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://runplane.ai";
+var DEFAULT_TIMEOUT_MS = 3e3;
+var DEFAULT_FAIL_MODE = "closed";
+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"
+      );
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.failMode = config.failMode ?? DEFAULT_FAIL_MODE;
+    this.approvalPoller = new ApprovalPoller({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      timeoutMs: config.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
+      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);
+    try {
+      const response = await fetch(`${this.baseUrl}/api/decide`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          agentKey: this.apiKey,
+          actionType: request.actionType,
+          target: request.target,
+          context: request.context ?? {},
+          requestId: request.requestId
+        }),
+        signal: controller.signal
+      });
+      const json = await response.json();
+      if (!response.ok) {
+        return this.handleFailure(
+          `API error: ${json.error ?? response.statusText}`,
+          request
+        );
+      }
+      return {
+        decision: json.decision,
+        reason: json.reason,
+        requestId: json.requestId,
+        matchedRule: json.matchedRule,
+        riskScore: json.riskScore,
+        severity: json.severity
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return this.handleFailure(`Network failure: ${message}`, request);
+    } finally {
+      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) {
+    const response = await this.decide({
+      actionType,
+      target,
+      context: context ?? void 0
+    });
+    if (response.decision === "BLOCK") {
+      throw new RunplaneError(
+        `Action blocked: ${response.reason}`,
+        "BLOCKED",
+        response.requestId
+      );
+    }
+    if (response.decision === "ALLOW") {
+      return fn();
+    }
+    const approval = await this.waitForApproval(response.requestId);
+    if (approval.approved) {
+      return fn();
+    }
+    if (approval.status === "denied") {
+      throw new RunplaneError(
+        `Action denied: ${approval.comment || "No reason provided"}`,
+        "DENIED",
+        response.requestId
+      );
+    }
+    if (this.failMode === "open") {
+      return fn();
+    }
+    throw new RunplaneError(
+      "Approval timeout - action blocked (fail-closed)",
+      "TIMEOUT",
+      response.requestId
+    );
+  }
+  /**
+   * Handle API failures according to failMode
+   */
+  handleFailure(reason, request) {
+    const requestId = request.requestId ?? crypto.randomUUID();
+    if (this.failMode === "open") {
+      return {
+        decision: "ALLOW",
+        reason: `${reason} (fail-open)`,
+        requestId
+      };
+    }
+    return {
+      decision: "BLOCK",
+      reason: `${reason} (fail-closed)`,
+      requestId
+    };
+  }
+};
+export {
+  Runplane,
+  RunplaneError
+};

package/package.json

@@ -1 +1,57 @@
-{"name":"@runplane/runplane-sdk","version":"1.0.1","description":"Runplane AI Runtime Governance SDK","main":"dist/index.js","type":"commonjs","license":"MIT","files":["dist"]}
+{
+  "name": "@runplane/runplane-sdk",
+  "version": "1.0.3",
+  "description": "Official SDK for the Runplane control plane - runtime governance for AI agent actions",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "eslint src/",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "runplane",
+    "ai",
+    "agents",
+    "governance",
+    "security",
+    "containment",
+    "policy",
+    "llm",
+    "langchain",
+    "openai"
+  ],
+  "author": "Runplane <support@runplane.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/runplane/sdk.git"
+  },
+  "homepage": "https://runplane.ai/docs",
+  "bugs": {
+    "url": "https://github.com/runplane/sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}