TypeScript Types

The AgentsForms SDK (@agentsforms/sdk-js) exports TypeScript types for all API objects.

Installation

npm install @agentsforms/sdk-js

Core types

FormDefinition

The root type for a form definition:

interface FormDefinition {
  name: string;
  slug: string;
  description?: string;
  fields: FormField[];
  settings: FormSettings;
}

FormField

A field in a form:

interface FormField {
  id: string;
  label: string;
  type: FieldType;
  required?: boolean;
  description?: string;
  agentHint?: string;
  options?: FieldOption[];
  defaultValue?: unknown;
  hidden?: boolean;
}

FieldType

type FieldType =
  | 'text'
  | 'textarea'
  | 'email'
  | 'url'
  | 'number'
  | 'boolean'
  | 'date'
  | 'select'
  | 'multi_select'
  | 'checkbox'
  | 'radio'
  | 'hidden'
  | 'file';

FieldOption

interface FieldOption {
  label: string;
  value: string;
}

FormSettings

interface FormSettings {
  allowPartial: boolean;
  submitLabel: string;
  successMessage?: string;
  retentionDays?: number;
}

API response types

Form

A form as returned by the API:

interface Form {
  id: string;
  name: string;
  slug: string;
  status: 'draft' | 'published' | 'archived';
  version: number;
  definition?: FormDefinition;
  submission_count?: number;
  created_at: string;
  updated_at: string;
}

Session

interface Session {
  id: string;
  form_id: string;
  status: 'open' | 'submitted' | 'expired';
  url: string;
  expires_at: string;
  created_at: string;
}

Submission

interface Submission {
  id: string;
  form_id: string;
  form_version: number;
  session_id: string;
  answers: Record<string, unknown>;
  partial: boolean;
  submitted_at: string;
}

Webhook types

interface WebhookEvent<T = unknown> {
  id: string;
  event: string;
  timestamp: string;
  data: T;
}

interface SubmissionCreatedData {
  submission_id: string;
  form_id: string;
  form_slug: string;
  form_version: number;
  session_id: string;
  partial: boolean;
  answers: Record<string, unknown>;
  metadata: Record<string, unknown>;
  submitted_at: string;
}

interface SessionExpiredData {
  session_id: string;
  form_id: string;
  form_slug: string;
  created_at: string;
  expired_at: string;
  metadata: Record<string, unknown>;
}

Error types

interface ApiError {
  error: {
    code: string;
    message: string;
    details?: ValidationDetail[];
  };
}

interface ValidationDetail {
  path: string;
  code: string;
  message: string;
}

---

These types are generated from packages/schemas/src/index.ts (the source of truth) and re-exported by the SDK. For the authoritative schema, see Form Schema Reference →.