@formdata/core

Core library for interacting with the Form-Data API. This package provides essential functions for managing form configurations, parsing form definitions, and communicating with the Form-Data service.

This package is used by the cli, and in most cases users do not have to use it directly.

Installation

npm install @formdata/core

Features

• 📝 Form Configuration: Read and manage form configurations
• 📑 Form Parsing: Parse form definition files into structured objects
• 🔌 API Integration: Communicate with Form-Data API
• 🔑 Authentication: Manage authentication tokens

Usage Examples

Getting Started

import { getConfig, getFormConfig, parseFormDefinition } from '@formdata/core';

// Get the main configuration
const config = getConfig();

// Get configuration for a specific form
const contactForm = getFormConfig('contact-form');

// Parse a form definition file
const formDefinition = parseFormDefinition(formContent);

Working with Form Configurations

The core library provides functions to read and manipulate form configurations:

import { 
  getConfig, 
  saveConfig,
  getFormConfig,
  readFormDescriptor,
  addForm,
  setActiveEnvironment,
  getAllForms
} from '@formdata/core';

// Get current configuration
const config = getConfig();

// Add a new form to configuration
addForm({
  id: 'contact-form',
  path: './forms/contact-form.fd'
});

// Change the active environment
setActiveEnvironment('staging');

// Get all form configurations
const allForms = getAllForms();

Parsing Form Definitions

Parse form definition files (.fd) into structured objects:

import { parseFormDefinition } from '@formdata/core';
import fs from 'fs';

// Read a form definition file
const formContent = fs.readFileSync('./forms/contact-form.fd', 'utf8');

// Parse the definition
const formDefinition = parseFormDefinition(formContent);

// Access form properties
console.log(formDefinition.name);
console.log(formDefinition.endpoint);
console.log(formDefinition.blocks); // Array of form elements

Interacting with the API

import { 
  apiRequest,
  deployForm,
  syncForm 
} from '@formdata/core';

// Deploy a form to the active environment
await deployForm('contact-form');

// Sync a form between environments
await syncForm('contact-form', 'staging', 'production');

// Make a custom API request
const response = await apiRequest('/forms', {
  method: 'GET'
});

Authentication Management

import {
  getAuthData,
  isAuthenticated,
  getApiToken,
  getWorkspace
} from '@formdata/core';

// Check if authenticated
if (isAuthenticated()) {
  // Get the current authentication data
  const authData = getAuthData();
  
  // Get the API token for requests
  const token = getApiToken();
  
  // Get current workspace
  const workspace = getWorkspace();
}

API Reference

Configuration Functions

• getConfig(): Get the current Form-Data configuration
• saveConfig(config): Save Form-Data configuration to disk
• getFormConfig(formId): Get configuration for a specific form
• readFormDescriptor(formId): Read raw form descriptor content
• addForm(formConfig): Add a form to the configuration
• setActiveEnvironment(envName): Change the active environment
• getAllForms(): Get all forms from configuration

Form Parsing Functions

• parseFormDefinition(text): Parse a form definition text into a structured object

API Communication Functions

• apiRequest(path, options): Make a request to the Form-Data API
• deployForm(formId, options): Deploy a form to the active environment
• syncForm(formId, sourceEnv, targetEnv): Sync a form between environments
• ApiError: Error class for API-related errors

Authentication Functions

• getAuthData(): Get the current authentication data
• getWorkspaceAuthData(workspace): Get auth data for a specific workspace
• saveAuthData(data): Save authentication data
• clearAuthData(): Clear authentication data
• isAuthenticated(): Check if user is authenticated
• getApiToken(): Get the API token for the current workspace
• getWorkspace(): Get the current workspace

Type Definitions

The core library exports several TypeScript type definitions:

• FormConfig: Form configuration properties
• FormDataConfig: Overall configuration structure
• FormDefinition: Parsed form definition
• FormBlock: Individual form element
• FormError: Error during form parsing
• AuthData: Authentication data structure
• WorkspaceAuthData: Workspace-specific auth data

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT