@agentpress/sdk 0.2.78 → 0.2.82

package/dist/index.mjs

@@ -1,335 +1,357 @@
-// src/errors.ts
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+//#region src/errors.ts
+/**
+* Base error class for all SDK errors. Catch this to handle any error
+* thrown by the AgentPress SDK regardless of specific type.
+*/
 var AgentPressError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "AgentPressError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
+	constructor(message) {
+		super(message);
+		this.name = "AgentPressError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
 };
+/**
+* Thrown at construction time when `AgentPressOptions` contains invalid values
+* (e.g., non-positive timeout, malformed `webhookSecret`).
+*/
 var ConfigurationError = class extends AgentPressError {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigurationError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
+	constructor(message) {
+		super(message);
+		this.name = "ConfigurationError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
 };
+/**
+* Thrown when the API returns a non-2xx HTTP response.
+*
+* Properties:
+* - `statusCode` - HTTP status code (e.g., 401, 404, 500)
+* - `responseBody` - Raw response body text for debugging
+* - `url` - The full request URL that failed
+*/
 var HttpError = class extends AgentPressError {
-  statusCode;
-  responseBody;
-  url;
-  constructor(statusCode, responseBody, url) {
-    super(`HTTP ${statusCode} from ${url}`);
-    this.name = "HttpError";
-    this.statusCode = statusCode;
-    this.responseBody = responseBody;
-    this.url = url;
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
+	statusCode;
+	responseBody;
+	url;
+	constructor(statusCode, responseBody, url) {
+		super(`HTTP ${statusCode} from ${url}`);
+		this.name = "HttpError";
+		this.statusCode = statusCode;
+		this.responseBody = responseBody;
+		this.url = url;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
 };
+/** Thrown when a request exceeds the configured `timeout` (default 30s). */
 var TimeoutError = class extends AgentPressError {
-  constructor(url, timeout) {
-    super(`Request to ${url} timed out after ${timeout}ms`);
-    this.name = "TimeoutError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
+	constructor(url, timeout) {
+		super(`Request to ${url} timed out after ${timeout}ms`);
+		this.name = "TimeoutError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
 };
+/** Thrown by {@link WebhooksClient.verifyOrThrow} when an inbound webhook signature is invalid or expired. */
 var WebhookSignatureError = class extends AgentPressError {
-  constructor(message) {
-    super(message);
-    this.name = "WebhookSignatureError";
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
+	constructor(message) {
+		super(message);
+		this.name = "WebhookSignatureError";
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
 };
-
-// src/utils.ts
-import { randomUUID } from "crypto";
+//#endregion
+//#region src/utils.ts
 function randomMessageId() {
-  return `msg_${randomUUID()}`;
+	return `msg_${randomUUID()}`;
 }
-
-// src/webhooks/signing.ts
-import { createHmac, timingSafeEqual } from "crypto";
-var SIGNATURE_PREFIX = "v1,";
-var DEFAULT_TOLERANCE_SECONDS = 5 * 60;
+//#endregion
+//#region src/webhooks/signing.ts
+const SIGNATURE_PREFIX = "v1,";
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+* Sign a webhook payload using Svix-compatible HMAC-SHA256.
+*
+* @param secret - The webhook secret (with "whsec_" prefix)
+* @param msgId - Unique message ID (e.g., "msg_<uuid>")
+* @param timestamp - Unix timestamp in seconds
+* @param body - JSON stringified payload
+* @returns Signature string in format "v1,<base64>"
+*/
 function sign(secret, msgId, timestamp, body) {
-  const secretBytes = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
-  const message = `${msgId}.${timestamp}.${body}`;
-  const signature = createHmac("sha256", secretBytes).update(message).digest("base64");
-  return `${SIGNATURE_PREFIX}${signature}`;
+	const secretBytes = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
+	const message = `${msgId}.${timestamp}.${body}`;
+	return `${SIGNATURE_PREFIX}${createHmac("sha256", secretBytes).update(message).digest("base64")}`;
 }
+/**
+* Verify a Svix webhook signature.
+*
+* @param secret - The webhook secret (with "whsec_" prefix)
+* @param payload - Raw request body (string or Buffer)
+* @param headers - Svix headers object
+* @param toleranceSeconds - Max age of signature in seconds (default: 5 min)
+* @returns true if valid, false if invalid or expired
+*/
 function verify(secret, payload, headers, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS) {
-  const msgId = headers["svix-id"];
-  const timestampStr = headers["svix-timestamp"];
-  const signatureHeader = headers["svix-signature"];
-  const timestamp = parseInt(timestampStr, 10);
-  if (Number.isNaN(timestamp)) return false;
-  const now = Math.floor(Date.now() / 1e3);
-  if (Math.abs(now - timestamp) > toleranceSeconds) return false;
-  const body = typeof payload === "string" ? payload : payload.toString("utf-8");
-  const expected = sign(secret, msgId, timestamp, body);
-  const signatures = signatureHeader.split(" ");
-  const expectedBuf = Buffer.from(expected);
-  for (const sig of signatures) {
-    const sigBuf = Buffer.from(sig);
-    if (sigBuf.length === expectedBuf.length && timingSafeEqual(sigBuf, expectedBuf)) {
-      return true;
-    }
-  }
-  return false;
+	const msgId = headers["svix-id"];
+	const timestampStr = headers["svix-timestamp"];
+	const signatureHeader = headers["svix-signature"];
+	const timestamp = parseInt(timestampStr, 10);
+	if (Number.isNaN(timestamp)) return false;
+	const now = Math.floor(Date.now() / 1e3);
+	if (Math.abs(now - timestamp) > toleranceSeconds) return false;
+	const expected = sign(secret, msgId, timestamp, typeof payload === "string" ? payload : payload.toString("utf-8"));
+	const signatures = signatureHeader.split(" ");
+	const expectedBuf = Buffer.from(expected);
+	for (const sig of signatures) {
+		const sigBuf = Buffer.from(sig);
+		if (sigBuf.length === expectedBuf.length && timingSafeEqual(sigBuf, expectedBuf)) return true;
+	}
+	return false;
 }
-
-// src/actions/client.ts
+//#endregion
+//#region src/actions/client.ts
+/**
+* Client for programmatically approving or rejecting staged actions.
+* Uses HMAC-SHA256 signing (Svix-compatible), identical to {@link WebhooksClient}.
+*
+* @example
+* ```ts
+* const client = new AgentPress({ webhookSecret: "whsec_...", org: "my-org" });
+*
+* // Approve a staged action
+* await client.actions.approve("act_123", {
+*   action: "my_webhook_action",
+* });
+*
+* // Reject with a reason
+* await client.actions.reject("act_456", {
+*   action: "my_webhook_action",
+*   reason: "Insufficient data",
+* });
+* ```
+*/
 var ActionsClient = class {
-  options;
-  http;
-  constructor(options, http) {
-    this.options = options;
-    this.http = http;
-  }
-  /**
-   * Approve a staged action, optionally modifying the tool call.
-   *
-   * @throws ConfigurationError if webhookSecret is not configured
-   * @throws HttpError on non-2xx response
-   * @throws TimeoutError if request exceeds timeout
-   */
-  async approve(actionId, params) {
-    return this.manage(actionId, params.action, "approve", {
-      editedToolCall: params.editedToolCall
-    });
-  }
-  /**
-   * Reject a staged action.
-   *
-   * @throws ConfigurationError if webhookSecret is not configured
-   * @throws HttpError on non-2xx response
-   * @throws TimeoutError if request exceeds timeout
-   */
-  async reject(actionId, params) {
-    return this.manage(actionId, params.action, "reject", {
-      reason: params.reason
-    });
-  }
-  async manage(actionId, webhookAction, operation, body) {
-    if (!this.options.webhookSecret) {
-      throw new ConfigurationError(
-        "webhookSecret is required for action management operations"
-      );
-    }
-    const path = `/webhooks/actions/${this.options.org}/${webhookAction}/manage/${actionId}/${operation}`;
-    const bodyStr = JSON.stringify(body);
-    const msgId = randomMessageId();
-    const timestamp = Math.floor(Date.now() / 1e3);
-    const signature = sign(
-      this.options.webhookSecret,
-      msgId,
-      timestamp,
-      bodyStr
-    );
-    return this.http.request(path, {
-      method: "POST",
-      body: bodyStr,
-      headers: {
-        "svix-id": msgId,
-        "svix-timestamp": String(timestamp),
-        "svix-signature": signature
-      }
-    });
-  }
+	options;
+	http;
+	constructor(options, http) {
+		this.options = options;
+		this.http = http;
+	}
+	/**
+	* Approve a staged action, optionally modifying the tool call.
+	*
+	* @throws ConfigurationError if webhookSecret is not configured
+	* @throws HttpError on non-2xx response
+	* @throws TimeoutError if request exceeds timeout
+	*/
+	async approve(actionId, params) {
+		return this.manage(actionId, params.action, "approve", { editedToolCall: params.editedToolCall });
+	}
+	/**
+	* Reject a staged action.
+	*
+	* @throws ConfigurationError if webhookSecret is not configured
+	* @throws HttpError on non-2xx response
+	* @throws TimeoutError if request exceeds timeout
+	*/
+	async reject(actionId, params) {
+		return this.manage(actionId, params.action, "reject", { reason: params.reason });
+	}
+	async manage(actionId, webhookAction, operation, body) {
+		if (!this.options.webhookSecret) throw new ConfigurationError("webhookSecret is required for action management operations");
+		const path = `/webhooks/actions/${this.options.org}/${webhookAction}/manage/${actionId}/${operation}`;
+		const bodyStr = JSON.stringify(body);
+		const msgId = randomMessageId();
+		const timestamp = Math.floor(Date.now() / 1e3);
+		const signature = sign(this.options.webhookSecret, msgId, timestamp, bodyStr);
+		return this.http.request(path, {
+			method: "POST",
+			body: bodyStr,
+			headers: {
+				"svix-id": msgId,
+				"svix-timestamp": String(timestamp),
+				"svix-signature": signature
+			}
+		});
+	}
 };
-
-// src/http.ts
+//#endregion
+//#region src/http.ts
+/**
+* Internal shared HTTP client. Not part of the public API -- used by
+* namespace clients (e.g., `WebhooksClient`) to make authenticated requests.
+* @internal
+*/
 var HttpClient = class {
-  baseUrl;
-  timeout;
-  onRequest;
-  onResponse;
-  constructor(options) {
-    this.baseUrl = options.baseUrl;
-    this.timeout = options.timeout;
-    this.onRequest = options.onRequest;
-    this.onResponse = options.onResponse;
-  }
-  /**
-   * Send an HTTP request to the API. Constructs the full URL from `baseUrl` + `path`,
-   * applies the configured timeout via `AbortSignal`, fires `onRequest`/`onResponse`
-   * hooks, and parses the JSON response.
-   *
-   * @throws {TimeoutError} If the request exceeds the configured timeout.
-   * @throws {HttpError} If the API returns a non-2xx status code.
-   * @throws {AgentPressError} On network failures or non-JSON responses.
-   */
-  async request(path, init) {
-    const url = `${this.baseUrl}${path}`;
-    const headers = new Headers(init.headers);
-    if (!headers.has("Content-Type")) {
-      headers.set("Content-Type", "application/json");
-    }
-    const requestInit = {
-      ...init,
-      headers,
-      signal: AbortSignal.timeout(this.timeout)
-    };
-    this.onRequest?.(url, requestInit);
-    let response;
-    try {
-      response = await fetch(url, requestInit);
-    } catch (error) {
-      if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
-        throw new TimeoutError(url, this.timeout);
-      }
-      const message = error instanceof Error ? error.message : "Unknown fetch error";
-      throw new AgentPressError(`Request to ${url} failed: ${message}`);
-    }
-    this.onResponse?.(url, response.clone());
-    const text = await response.text();
-    if (!response.ok) {
-      throw new HttpError(response.status, text, url);
-    }
-    try {
-      return JSON.parse(text);
-    } catch {
-      throw new AgentPressError(
-        `Expected JSON response from ${url} but received: ${text.slice(0, 200)}`
-      );
-    }
-  }
+	baseUrl;
+	timeout;
+	onRequest;
+	onResponse;
+	constructor(options) {
+		this.baseUrl = options.baseUrl;
+		this.timeout = options.timeout;
+		this.onRequest = options.onRequest;
+		this.onResponse = options.onResponse;
+	}
+	/**
+	* Send an HTTP request to the API. Constructs the full URL from `baseUrl` + `path`,
+	* applies the configured timeout via `AbortSignal`, fires `onRequest`/`onResponse`
+	* hooks, and parses the JSON response.
+	*
+	* @throws {TimeoutError} If the request exceeds the configured timeout.
+	* @throws {HttpError} If the API returns a non-2xx status code.
+	* @throws {AgentPressError} On network failures or non-JSON responses.
+	*/
+	async request(path, init) {
+		const url = `${this.baseUrl}${path}`;
+		const headers = new Headers(init.headers);
+		if (!headers.has("Content-Type")) headers.set("Content-Type", "application/json");
+		const requestInit = {
+			...init,
+			headers,
+			signal: AbortSignal.timeout(this.timeout)
+		};
+		this.onRequest?.(url, requestInit);
+		let response;
+		try {
+			response = await fetch(url, requestInit);
+		} catch (error) {
+			if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) throw new TimeoutError(url, this.timeout);
+			throw new AgentPressError(`Request to ${url} failed: ${error instanceof Error ? error.message : "Unknown fetch error"}`);
+		}
+		this.onResponse?.(url, response.clone());
+		const text = await response.text();
+		if (!response.ok) throw new HttpError(response.status, text, url);
+		try {
+			return JSON.parse(text);
+		} catch {
+			throw new AgentPressError(`Expected JSON response from ${url} but received: ${text.slice(0, 200)}`);
+		}
+	}
 };
-
-// src/webhooks/client.ts
+//#endregion
+//#region src/webhooks/client.ts
 var WebhooksClient = class {
-  options;
-  http;
-  constructor(options, http) {
-    this.options = options;
-    this.http = http;
-  }
-  /**
-   * Send an arbitrary webhook payload to AgentPress.
-   * Signs the payload with HMAC-SHA256 (Svix-compatible).
-   *
-   * @throws ConfigurationError if webhookSecret is not configured
-   * @throws HttpError on non-2xx response
-   * @throws TimeoutError if request exceeds timeout
-   */
-  async send(params) {
-    if (!this.options.webhookSecret) {
-      throw new ConfigurationError(
-        "webhookSecret is required for webhook operations"
-      );
-    }
-    const path = `/webhooks/actions/${this.options.org}/${params.action}`;
-    const body = JSON.stringify(params.payload);
-    const msgId = randomMessageId();
-    const timestamp = Math.floor(Date.now() / 1e3);
-    const signature = sign(this.options.webhookSecret, msgId, timestamp, body);
-    return this.http.request(path, {
-      method: "POST",
-      body,
-      headers: {
-        "svix-id": msgId,
-        "svix-timestamp": String(timestamp),
-        "svix-signature": signature
-      }
-    });
-  }
-  /**
-   * Verify an inbound Svix webhook signature.
-   *
-   * @returns true if valid, false if invalid or expired
-   * @throws ConfigurationError if webhookSecret is not configured
-   */
-  verify(params) {
-    if (!this.options.webhookSecret) {
-      throw new ConfigurationError(
-        "webhookSecret is required for webhook verification"
-      );
-    }
-    return verify(
-      this.options.webhookSecret,
-      params.payload,
-      params.headers
-    );
-  }
-  /**
-   * Verify an inbound Svix webhook signature, throwing on failure.
-   * Useful for middleware patterns where invalid signatures should halt processing.
-   *
-   * @throws WebhookSignatureError if signature is invalid or expired
-   * @throws ConfigurationError if webhookSecret is not configured
-   */
-  verifyOrThrow(params) {
-    if (!this.verify(params)) {
-      throw new WebhookSignatureError("Invalid webhook signature");
-    }
-  }
-  /**
-   * Verify and parse an inbound webhook from AgentPress.
-   * Combines signature verification with JSON parsing and type casting.
-   * This is the recommended way to handle incoming webhooks.
-   *
-   * @throws WebhookSignatureError if signature is invalid or expired
-   * @throws ConfigurationError if webhookSecret is not configured
-   * @throws AgentPressError if payload is not valid JSON
-   */
-  constructEvent(params) {
-    this.verifyOrThrow(params);
-    const body = typeof params.payload === "string" ? params.payload : params.payload.toString("utf-8");
-    try {
-      return JSON.parse(body);
-    } catch {
-      throw new AgentPressError("Webhook payload is not valid JSON");
-    }
-  }
+	options;
+	http;
+	constructor(options, http) {
+		this.options = options;
+		this.http = http;
+	}
+	/**
+	* Send an arbitrary webhook payload to AgentPress.
+	* Signs the payload with HMAC-SHA256 (Svix-compatible).
+	*
+	* @throws ConfigurationError if webhookSecret is not configured
+	* @throws HttpError on non-2xx response
+	* @throws TimeoutError if request exceeds timeout
+	*/
+	async send(params) {
+		if (!this.options.webhookSecret) throw new ConfigurationError("webhookSecret is required for webhook operations");
+		const path = `/webhooks/actions/${this.options.org}/${params.action}`;
+		const body = JSON.stringify(params.payload);
+		const msgId = randomMessageId();
+		const timestamp = Math.floor(Date.now() / 1e3);
+		const signature = sign(this.options.webhookSecret, msgId, timestamp, body);
+		return this.http.request(path, {
+			method: "POST",
+			body,
+			headers: {
+				"svix-id": msgId,
+				"svix-timestamp": String(timestamp),
+				"svix-signature": signature
+			}
+		});
+	}
+	/**
+	* Verify an inbound Svix webhook signature.
+	*
+	* @returns true if valid, false if invalid or expired
+	* @throws ConfigurationError if webhookSecret is not configured
+	*/
+	verify(params) {
+		if (!this.options.webhookSecret) throw new ConfigurationError("webhookSecret is required for webhook verification");
+		return verify(this.options.webhookSecret, params.payload, params.headers);
+	}
+	/**
+	* Verify an inbound Svix webhook signature, throwing on failure.
+	* Useful for middleware patterns where invalid signatures should halt processing.
+	*
+	* @throws WebhookSignatureError if signature is invalid or expired
+	* @throws ConfigurationError if webhookSecret is not configured
+	*/
+	verifyOrThrow(params) {
+		if (!this.verify(params)) throw new WebhookSignatureError("Invalid webhook signature");
+	}
+	/**
+	* Verify and parse an inbound webhook from AgentPress.
+	* Combines signature verification with JSON parsing and type casting.
+	* This is the recommended way to handle incoming webhooks.
+	*
+	* @throws WebhookSignatureError if signature is invalid or expired
+	* @throws ConfigurationError if webhookSecret is not configured
+	* @throws AgentPressError if payload is not valid JSON
+	*/
+	constructEvent(params) {
+		this.verifyOrThrow(params);
+		const body = typeof params.payload === "string" ? params.payload : params.payload.toString("utf-8");
+		try {
+			return JSON.parse(body);
+		} catch {
+			throw new AgentPressError("Webhook payload is not valid JSON");
+		}
+	}
 };
-
-// src/client.ts
+//#endregion
+//#region src/client.ts
+/**
+* Main entry point for the AgentPress SDK. Provides namespaced access to API
+* resources (e.g., `client.webhooks.send()`, `client.actions.approve()`).
+* Validates all configuration options at construction time, so invalid config fails fast.
+*
+* @example
+* ```ts
+* const client = new AgentPress({
+*   apiKey: "ak_...",
+*   webhookSecret: "whsec_...",
+* });
+* await client.webhooks.send({ action: "my_action", payload: { ... } });
+* await client.actions.approve("act_123", { action: "my_action" });
+* ```
+*/
 var AgentPress = class {
-  /** Webhook operations: send outbound webhooks and verify inbound signatures. */
-  webhooks;
-  /** Action management: approve or reject staged actions. */
-  actions;
-  /**
-   * @param options - SDK configuration. All fields are optional with sensible defaults.
-   * @throws {ConfigurationError} If `timeout` is non-positive or `webhookSecret` has an invalid prefix.
-   */
-  constructor(options = {}) {
-    const resolved = resolveOptions(options);
-    const http = new HttpClient(resolved);
-    this.webhooks = new WebhooksClient(resolved, http);
-    this.actions = new ActionsClient(resolved, http);
-  }
+	/** Webhook operations: send outbound webhooks and verify inbound signatures. */
+	webhooks;
+	/** Action management: approve or reject staged actions. */
+	actions;
+	/**
+	* @param options - SDK configuration. All fields are optional with sensible defaults.
+	* @throws {ConfigurationError} If `timeout` is non-positive or `webhookSecret` has an invalid prefix.
+	*/
+	constructor(options = {}) {
+		const resolved = resolveOptions(options);
+		const http = new HttpClient(resolved);
+		this.webhooks = new WebhooksClient(resolved, http);
+		this.actions = new ActionsClient(resolved, http);
+	}
 };
 function resolveOptions(options) {
-  const baseUrl = (options.baseUrl ?? "https://api.agent.press").replace(
-    /\/+$/,
-    ""
-  );
-  const timeout = options.timeout ?? 3e4;
-  const org = options.org ?? "default-org";
-  if (timeout <= 0 || !Number.isFinite(timeout)) {
-    throw new ConfigurationError("timeout must be a positive number");
-  }
-  if (options.webhookSecret !== void 0 && !options.webhookSecret.startsWith("whsec_")) {
-    throw new ConfigurationError('webhookSecret must start with "whsec_"');
-  }
-  return {
-    baseUrl,
-    timeout,
-    org,
-    webhookSecret: options.webhookSecret,
-    apiKey: options.apiKey,
-    onRequest: options.onRequest,
-    onResponse: options.onResponse
-  };
+	const baseUrl = (options.baseUrl ?? "https://api.agent.press").replace(/\/+$/, "");
+	const timeout = options.timeout ?? 3e4;
+	const org = options.org ?? "default-org";
+	if (timeout <= 0 || !Number.isFinite(timeout)) throw new ConfigurationError("timeout must be a positive number");
+	if (options.webhookSecret !== void 0 && !options.webhookSecret.startsWith("whsec_")) throw new ConfigurationError("webhookSecret must start with \"whsec_\"");
+	return {
+		baseUrl,
+		timeout,
+		org,
+		webhookSecret: options.webhookSecret,
+		apiKey: options.apiKey,
+		onRequest: options.onRequest,
+		onResponse: options.onResponse
+	};
 }
-export {
-  ActionsClient,
-  AgentPress,
-  AgentPressError,
-  ConfigurationError,
-  HttpError,
-  TimeoutError,
-  WebhookSignatureError
-};
+//#endregion
+export { ActionsClient, AgentPress, AgentPressError, ConfigurationError, HttpError, TimeoutError, WebhookSignatureError };
+
 //# sourceMappingURL=index.mjs.map