TYPESCRIPT types.ts

/** 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;
}