npm package: @formdata/core
Description: Core library for Form-Data management
Latest version: 0.86.0

# @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

```bash
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

```javascript
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:

```javascript
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:

```javascript
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

```javascript
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

```javascript
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