/** Type-safe interfaces for the AgentForms API. */
/** Supported field types. */
export type FieldType = 'text' | 'email' | 'tel' | 'textarea' | 'select' | 'number' | 'date' | 'hidden';
/** Permissions assignable to an API key. */
export type Permission = 'read_forms' | 'write_forms' | 'read_submissions' | 'delete_forms';
/** Single form field definition. */
export interface FieldDefinition {
name: string;
label: string;
type: FieldType;
required?: boolean;
options?: string[];
placeholder?: string;
default?: string;
}
/** Full form returned from the API. */
export interface Form {
id: number;
token: string;
name: string;
fields: FieldDefinition[];
created_by: string;
embed_url: string;
submit_url: string;
created_at?: string;
field_count?: number;
metadata?: Record<string, unknown>;
/** Public URL for humans to fill out the form. */
readonly public_url: string;
/** Short share link for messaging. */
readonly share_url: string;
}
/** Single submission record. */
export interface Submission {
id: number;
site_id: number;
submitted_at: string;
dynamic_data: Record<string, unknown>;
client_ip?: string;
user_agent?: string;
}
/** Response from forms.list(). */
export interface FormsResponse {
forms: Form[];
total?: number;
limit?: number;
offset?: number;
}
/** API key representation. */
export interface ApiKey {
id: number;
key_prefix: string;
name: string;
permissions?: Record<string, boolean>;
created_at?: string;
revoked: boolean;
}
/** Response from keys.list(). */
export interface KeysResponse {
keys: ApiKey[];
}
/** Incoming webhook payload from AgentForms. */
export interface WebhookPayload {
event: string;
site_id: number;
site_name: string;
submission_id: number;
submitted_at: string;
fields: Record<string, string>;
field_metadata?: Record<string, unknown>;
}
/** Response from submissions.list(). */
export interface SubmissionsResponse {
submissions: Submission[];
total?: number;
limit?: number;
offset?: number;
}