@agentpress/sdk 0.2.70

package/dist/index.d.cts

@@ -0,0 +1,306 @@
+/** Constructor options for the {@link AgentPress} client. All fields are optional. */
+interface AgentPressOptions {
+    /** Svix webhook signing secret for verifying inbound webhooks. Must start with `"whsec_"`. */
+    webhookSecret?: string;
+    /** API key for authenticated requests. */
+    apiKey?: string;
+    /** @default "https://api.agent.press" */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Must be a positive finite number. @default 30000 */
+    timeout?: number;
+    /** Organization identifier sent with requests. @default "default-org" */
+    org?: string;
+    /** Hook called before every outbound HTTP request (useful for logging/tracing). */
+    onRequest?: (url: string, init: RequestInit) => void;
+    /** Hook called after every HTTP response is received. */
+    onResponse?: (url: string, response: Response) => void;
+}
+/** Parameters for {@link WebhooksClient.send}. */
+interface WebhookSendParams {
+    /** Webhook action name (matches an action rule on the server). */
+    action: string;
+    /** Arbitrary payload data forwarded to the webhook handler. */
+    payload: Record<string, unknown>;
+}
+/** Parameters for verifying an inbound webhook signature via {@link WebhooksClient.verify} or {@link WebhooksClient.verifyOrThrow}. */
+interface WebhookVerifyParams {
+    /** Raw request body (string or Buffer) -- must not be parsed/modified. */
+    payload: string | Buffer;
+    /** Svix signature headers from the incoming request. */
+    headers: {
+        "svix-id": string;
+        "svix-timestamp": string;
+        "svix-signature": string;
+    };
+}
+/** Response from webhook send operations. */
+interface WebhookResponse {
+    success: boolean;
+    /** UUID of the created action (present on successful creation). */
+    actionId?: string;
+    /** `true` if an action with the same `externalId` already existed (idempotency). */
+    alreadyExists?: boolean;
+    skipped?: boolean;
+    data?: Record<string, unknown>;
+}
+/** Action lifecycle event types emitted by AgentPress. */
+type ActionEventType = "action.pending_approval" | "action.approved" | "action.completed" | "action.failed" | "action.rejected" | "action.expired";
+/** A tool call staged for approval (present when eventType is "action.pending_approval"). */
+interface StagedToolCall {
+    toolName: string;
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+}
+/** Parameters for {@link ActionsClient.approve}. */
+interface ApproveActionParams {
+    /** Webhook action identifier (from callback's webhookAction field). */
+    action: string;
+    /** Optionally modify the tool call arguments before execution. */
+    editedToolCall?: {
+        toolName: string;
+        arguments: Record<string, unknown>;
+    };
+}
+/** Parameters for {@link ActionsClient.reject}. */
+interface RejectActionParams {
+    /** Webhook action identifier (from callback's webhookAction field). */
+    action: string;
+    /** Reason for rejection. */
+    reason?: string;
+}
+/** Response from action approve/reject operations. */
+interface ActionManageResponse {
+    success: boolean;
+    actionId: string;
+    status: ActionStatus;
+}
+/** Status of an action in the AgentPress system. */
+type ActionStatus = "pending" | "staged" | "approved" | "rejected" | "completed" | "failed" | "expired";
+/** A tool call made by the agent during action processing. */
+interface ToolCallResult {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    result: unknown;
+}
+/** The agent's response after processing an action. */
+interface AgentResponse {
+    /** The agent's text response, if any. */
+    text: string | null;
+    /** Tool calls made by the agent during processing. */
+    toolCalls: ToolCallResult[];
+}
+/**
+ * Payload received from AgentPress outbound webhooks (post-event callbacks).
+ * This is what your server receives when an action completes.
+ */
+interface ActionCallbackPayload {
+    actionId: string;
+    status: ActionStatus;
+    actionType: string;
+    /** Lifecycle event type (e.g., "action.pending_approval", "action.completed"). */
+    eventType: ActionEventType;
+    /** Webhook action identifier used to create this action. Needed for approve/reject. */
+    webhookAction: string | null;
+    /** Tool awaiting approval (present only when eventType is "action.pending_approval"). */
+    stagedToolCall: StagedToolCall | null;
+    /** ISO 8601 timestamp of when the action completed. */
+    completedAt: string;
+    /** Original data from the inbound webhook that triggered this action. */
+    sourceData: Record<string, unknown>;
+    /** External system identifier. */
+    externalId: string | null;
+    /** AgentPress user ID associated with this action. */
+    userId: string | null;
+    /** Thread ID if the action created a conversation. */
+    threadId: string | null;
+    /** The agent's response including text and tool call results. */
+    agentResponse: AgentResponse;
+    /** Error message if the action failed. */
+    errorMessage: string | null;
+    /** Reason provided if the action was rejected by a human reviewer. */
+    rejectionReason: string | null;
+    /** Additional custom fields from post-event configuration. */
+    [key: string]: unknown;
+}
+/** @internal Resolved (validated, defaulted) options. Not exported from the public API. */
+interface ResolvedOptions {
+    baseUrl: string;
+    timeout: number;
+    org: string;
+    webhookSecret?: string;
+    apiKey?: string;
+    onRequest?: AgentPressOptions["onRequest"];
+    onResponse?: AgentPressOptions["onResponse"];
+}
+
+/**
+ * Internal shared HTTP client. Not part of the public API -- used by
+ * namespace clients (e.g., `WebhooksClient`) to make authenticated requests.
+ * @internal
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly onRequest?;
+    private readonly onResponse?;
+    constructor(options: ResolvedOptions);
+    /**
+     * 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.
+     */
+    request<T>(path: string, init: RequestInit): Promise<T>;
+}
+
+/**
+ * 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",
+ * });
+ * ```
+ */
+declare class ActionsClient {
+    private readonly options;
+    private readonly http;
+    constructor(options: ResolvedOptions, http: HttpClient);
+    /**
+     * 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
+     */
+    approve(actionId: string, params: ApproveActionParams): Promise<ActionManageResponse>;
+    /**
+     * Reject a staged action.
+     *
+     * @throws ConfigurationError if webhookSecret is not configured
+     * @throws HttpError on non-2xx response
+     * @throws TimeoutError if request exceeds timeout
+     */
+    reject(actionId: string, params: RejectActionParams): Promise<ActionManageResponse>;
+    private manage;
+}
+
+declare class WebhooksClient {
+    private readonly options;
+    private readonly http;
+    constructor(options: ResolvedOptions, http: HttpClient);
+    /**
+     * 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
+     */
+    send(params: WebhookSendParams): Promise<WebhookResponse>;
+    /**
+     * Verify an inbound Svix webhook signature.
+     *
+     * @returns true if valid, false if invalid or expired
+     * @throws ConfigurationError if webhookSecret is not configured
+     */
+    verify(params: WebhookVerifyParams): boolean;
+    /**
+     * 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: WebhookVerifyParams): void;
+    /**
+     * 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: WebhookVerifyParams): ActionCallbackPayload;
+}
+
+/**
+ * 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" });
+ * ```
+ */
+declare class AgentPress {
+    /** Webhook operations: send outbound webhooks and verify inbound signatures. */
+    readonly webhooks: WebhooksClient;
+    /** Action management: approve or reject staged actions. */
+    readonly actions: ActionsClient;
+    /**
+     * @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?: AgentPressOptions);
+}
+
+/**
+ * Base error class for all SDK errors. Catch this to handle any error
+ * thrown by the AgentPress SDK regardless of specific type.
+ */
+declare class AgentPressError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown at construction time when `AgentPressOptions` contains invalid values
+ * (e.g., non-positive timeout, malformed `webhookSecret`).
+ */
+declare class ConfigurationError extends AgentPressError {
+    constructor(message: string);
+}
+/**
+ * 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
+ */
+declare class HttpError extends AgentPressError {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    readonly url: string;
+    constructor(statusCode: number, responseBody: string, url: string);
+}
+/** Thrown when a request exceeds the configured `timeout` (default 30s). */
+declare class TimeoutError extends AgentPressError {
+    constructor(url: string, timeout: number);
+}
+/** Thrown by {@link WebhooksClient.verifyOrThrow} when an inbound webhook signature is invalid or expired. */
+declare class WebhookSignatureError extends AgentPressError {
+    constructor(message: string);
+}
+
+export { type ActionCallbackPayload, type ActionEventType, type ActionManageResponse, type ActionStatus, ActionsClient, AgentPress, AgentPressError, type AgentPressOptions, type AgentResponse, type ApproveActionParams, ConfigurationError, HttpError, type RejectActionParams, type StagedToolCall, TimeoutError, type ToolCallResult, type WebhookResponse, type WebhookSendParams, WebhookSignatureError, type WebhookVerifyParams };

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+/** Constructor options for the {@link AgentPress} client. All fields are optional. */
+interface AgentPressOptions {
+    /** Svix webhook signing secret for verifying inbound webhooks. Must start with `"whsec_"`. */
+    webhookSecret?: string;
+    /** API key for authenticated requests. */
+    apiKey?: string;
+    /** @default "https://api.agent.press" */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Must be a positive finite number. @default 30000 */
+    timeout?: number;
+    /** Organization identifier sent with requests. @default "default-org" */
+    org?: string;
+    /** Hook called before every outbound HTTP request (useful for logging/tracing). */
+    onRequest?: (url: string, init: RequestInit) => void;
+    /** Hook called after every HTTP response is received. */
+    onResponse?: (url: string, response: Response) => void;
+}
+/** Parameters for {@link WebhooksClient.send}. */
+interface WebhookSendParams {
+    /** Webhook action name (matches an action rule on the server). */
+    action: string;
+    /** Arbitrary payload data forwarded to the webhook handler. */
+    payload: Record<string, unknown>;
+}
+/** Parameters for verifying an inbound webhook signature via {@link WebhooksClient.verify} or {@link WebhooksClient.verifyOrThrow}. */
+interface WebhookVerifyParams {
+    /** Raw request body (string or Buffer) -- must not be parsed/modified. */
+    payload: string | Buffer;
+    /** Svix signature headers from the incoming request. */
+    headers: {
+        "svix-id": string;
+        "svix-timestamp": string;
+        "svix-signature": string;
+    };
+}
+/** Response from webhook send operations. */
+interface WebhookResponse {
+    success: boolean;
+    /** UUID of the created action (present on successful creation). */
+    actionId?: string;
+    /** `true` if an action with the same `externalId` already existed (idempotency). */
+    alreadyExists?: boolean;
+    skipped?: boolean;
+    data?: Record<string, unknown>;
+}
+/** Action lifecycle event types emitted by AgentPress. */
+type ActionEventType = "action.pending_approval" | "action.approved" | "action.completed" | "action.failed" | "action.rejected" | "action.expired";
+/** A tool call staged for approval (present when eventType is "action.pending_approval"). */
+interface StagedToolCall {
+    toolName: string;
+    toolCallId: string;
+    arguments: Record<string, unknown>;
+}
+/** Parameters for {@link ActionsClient.approve}. */
+interface ApproveActionParams {
+    /** Webhook action identifier (from callback's webhookAction field). */
+    action: string;
+    /** Optionally modify the tool call arguments before execution. */
+    editedToolCall?: {
+        toolName: string;
+        arguments: Record<string, unknown>;
+    };
+}
+/** Parameters for {@link ActionsClient.reject}. */
+interface RejectActionParams {
+    /** Webhook action identifier (from callback's webhookAction field). */
+    action: string;
+    /** Reason for rejection. */
+    reason?: string;
+}
+/** Response from action approve/reject operations. */
+interface ActionManageResponse {
+    success: boolean;
+    actionId: string;
+    status: ActionStatus;
+}
+/** Status of an action in the AgentPress system. */
+type ActionStatus = "pending" | "staged" | "approved" | "rejected" | "completed" | "failed" | "expired";
+/** A tool call made by the agent during action processing. */
+interface ToolCallResult {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    result: unknown;
+}
+/** The agent's response after processing an action. */
+interface AgentResponse {
+    /** The agent's text response, if any. */
+    text: string | null;
+    /** Tool calls made by the agent during processing. */
+    toolCalls: ToolCallResult[];
+}
+/**
+ * Payload received from AgentPress outbound webhooks (post-event callbacks).
+ * This is what your server receives when an action completes.
+ */
+interface ActionCallbackPayload {
+    actionId: string;
+    status: ActionStatus;
+    actionType: string;
+    /** Lifecycle event type (e.g., "action.pending_approval", "action.completed"). */
+    eventType: ActionEventType;
+    /** Webhook action identifier used to create this action. Needed for approve/reject. */
+    webhookAction: string | null;
+    /** Tool awaiting approval (present only when eventType is "action.pending_approval"). */
+    stagedToolCall: StagedToolCall | null;
+    /** ISO 8601 timestamp of when the action completed. */
+    completedAt: string;
+    /** Original data from the inbound webhook that triggered this action. */
+    sourceData: Record<string, unknown>;
+    /** External system identifier. */
+    externalId: string | null;
+    /** AgentPress user ID associated with this action. */
+    userId: string | null;
+    /** Thread ID if the action created a conversation. */
+    threadId: string | null;
+    /** The agent's response including text and tool call results. */
+    agentResponse: AgentResponse;
+    /** Error message if the action failed. */
+    errorMessage: string | null;
+    /** Reason provided if the action was rejected by a human reviewer. */
+    rejectionReason: string | null;
+    /** Additional custom fields from post-event configuration. */
+    [key: string]: unknown;
+}
+/** @internal Resolved (validated, defaulted) options. Not exported from the public API. */
+interface ResolvedOptions {
+    baseUrl: string;
+    timeout: number;
+    org: string;
+    webhookSecret?: string;
+    apiKey?: string;
+    onRequest?: AgentPressOptions["onRequest"];
+    onResponse?: AgentPressOptions["onResponse"];
+}
+
+/**
+ * Internal shared HTTP client. Not part of the public API -- used by
+ * namespace clients (e.g., `WebhooksClient`) to make authenticated requests.
+ * @internal
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly onRequest?;
+    private readonly onResponse?;
+    constructor(options: ResolvedOptions);
+    /**
+     * 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.
+     */
+    request<T>(path: string, init: RequestInit): Promise<T>;
+}
+
+/**
+ * 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",
+ * });
+ * ```
+ */
+declare class ActionsClient {
+    private readonly options;
+    private readonly http;
+    constructor(options: ResolvedOptions, http: HttpClient);
+    /**
+     * 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
+     */
+    approve(actionId: string, params: ApproveActionParams): Promise<ActionManageResponse>;
+    /**
+     * Reject a staged action.
+     *
+     * @throws ConfigurationError if webhookSecret is not configured
+     * @throws HttpError on non-2xx response
+     * @throws TimeoutError if request exceeds timeout
+     */
+    reject(actionId: string, params: RejectActionParams): Promise<ActionManageResponse>;
+    private manage;
+}
+
+declare class WebhooksClient {
+    private readonly options;
+    private readonly http;
+    constructor(options: ResolvedOptions, http: HttpClient);
+    /**
+     * 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
+     */
+    send(params: WebhookSendParams): Promise<WebhookResponse>;
+    /**
+     * Verify an inbound Svix webhook signature.
+     *
+     * @returns true if valid, false if invalid or expired
+     * @throws ConfigurationError if webhookSecret is not configured
+     */
+    verify(params: WebhookVerifyParams): boolean;
+    /**
+     * 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: WebhookVerifyParams): void;
+    /**
+     * 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: WebhookVerifyParams): ActionCallbackPayload;
+}
+
+/**
+ * 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" });
+ * ```
+ */
+declare class AgentPress {
+    /** Webhook operations: send outbound webhooks and verify inbound signatures. */
+    readonly webhooks: WebhooksClient;
+    /** Action management: approve or reject staged actions. */
+    readonly actions: ActionsClient;
+    /**
+     * @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?: AgentPressOptions);
+}
+
+/**
+ * Base error class for all SDK errors. Catch this to handle any error
+ * thrown by the AgentPress SDK regardless of specific type.
+ */
+declare class AgentPressError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown at construction time when `AgentPressOptions` contains invalid values
+ * (e.g., non-positive timeout, malformed `webhookSecret`).
+ */
+declare class ConfigurationError extends AgentPressError {
+    constructor(message: string);
+}
+/**
+ * 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
+ */
+declare class HttpError extends AgentPressError {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    readonly url: string;
+    constructor(statusCode: number, responseBody: string, url: string);
+}
+/** Thrown when a request exceeds the configured `timeout` (default 30s). */
+declare class TimeoutError extends AgentPressError {
+    constructor(url: string, timeout: number);
+}
+/** Thrown by {@link WebhooksClient.verifyOrThrow} when an inbound webhook signature is invalid or expired. */
+declare class WebhookSignatureError extends AgentPressError {
+    constructor(message: string);
+}
+
+export { type ActionCallbackPayload, type ActionEventType, type ActionManageResponse, type ActionStatus, ActionsClient, AgentPress, AgentPressError, type AgentPressOptions, type AgentResponse, type ApproveActionParams, ConfigurationError, HttpError, type RejectActionParams, type StagedToolCall, TimeoutError, type ToolCallResult, type WebhookResponse, type WebhookSendParams, WebhookSignatureError, type WebhookVerifyParams };