/** AgentForms API client — thin wrapper over /api/v2/. */
import type { ApiKey, FieldDefinition, Form, FormsResponse, Permission, Submission, SubmissionsResponse } from './types';
export declare class AgentFormsError extends Error {
readonly statusCode: number;
readonly response: unknown;
constructor(message: string, statusCode?: number, response?: unknown);
}
interface ClientInternals {
readonly apiKey: string;
readonly baseURL: string;
readonly timeout: number;
}
export declare class FormsClient {
private readonly _c;
constructor(client: ClientInternals);
/** List all forms. */
list(limit?: number, offset?: number): Promise<FormsResponse>;
/**
* Create a new form programmatically.
*
* @param name - Form display name
* @param fields - List of field definitions
* @param metadata - Optional JSON metadata attached to the form
*/
create(name: string, fields: FieldDefinition[], metadata?: Record<string, unknown>): Promise<Form>;
/**
* Generate a form from natural language using AI.
* Tier-gated (Starter+).
*
* @param prompt - Natural language description (e.g., "A survey for event feedback")
* @param formName - Override the AI-generated form name
*/
generate(prompt: string, formName?: string): Promise<Form>;
/** Get form details by token. */
get(token: string): Promise<Form>;
/** Replace all fields on a form. */
updateFields(token: string, fields: FieldDefinition[]): Promise<Record<string, unknown>>;
/** Delete a form and all submissions. */
delete(token: string): Promise<Record<string, unknown>>;
/** Get public form config. */
config(token: string): Promise<Record<string, unknown>>;
}
export declare class KeysClient {
private readonly _c;
constructor(client: ClientInternals);
/** List all API keys. */
list(): Promise<ApiKey[]>;
/**
* Create a new API key.
*
* @param name - Human-readable name
* @param permissions - List of permissions (defaults to all if omitted)
* @returns Key details including the full_key (returned once — store it securely)
*/
create(name: string, permissions?: Permission[]): Promise<Record<string, unknown>>;
/** Revoke an API key. */
revoke(keyId: number): Promise<Record<string, unknown>>;
}
export declare class SubmissionsClient {
private readonly _c;
constructor(client: ClientInternals);
/** List submissions for a form. */
list(formToken: string, limit?: number, offset?: number): Promise<SubmissionsResponse>;
/** Get a single submission. */
get(formToken: string, submissionId: number): Promise<Submission>;
}
/**
* Client for the AgentForms Agent API.
*
* @example
* ```ts
* import { AgentForms } from '@agentforms/sdk';
*
* const af = new AgentForms('afk_live_...');
*
* // Create a form
* const form = await af.forms.create('Customer Feedback', [
* { name: 'rating', label: 'Rating', type: 'select', options: ['1','2','3','4','5'], required: true },
* { name: 'feedback', label: 'Feedback', type: 'textarea' },
* ]);
* console.log(form.share_url);
* ```
*/
export declare class AgentForms {
readonly apiKey: string;
readonly baseURL: string;
readonly timeout: number;
readonly forms: FormsClient;
readonly keys: KeysClient;
readonly submissions: SubmissionsClient;
/**
* @param apiKey - Your AgentForms API key
* @param baseURL - API base URL (default: https://agentforms.io/api/v2)
* @param timeout - Request timeout in seconds (default: 30)
*/
constructor(apiKey: string, baseURL?: string, timeout?: number);
}
export {};