npm package: @formalingo/sdk
Description: Official TypeScript SDK for the Formalingo API
Latest version: 0.1.3

# @formalingo/sdk

Official TypeScript SDK for the [Formalingo](https://www.formalingo.com) API — build and manage AI-powered forms and document signing programmatically.

## Installation

```bash
npm install @formalingo/sdk
# or
yarn add @formalingo/sdk
# or
pnpm add @formalingo/sdk
```

## Quick Start

```typescript
import { createClient } from "@formalingo/sdk"

const client = createClient("af_live_YOUR_API_KEY")

// List all forms
const forms = await client.forms.get()

// Create a form
const form = await client.forms.post({
  body: {
    title: "Customer Feedback",
    description: "Help us improve our service",
  },
})
```

## Setup

### Get Your API Key

1. Log in to [Formalingo](https://app.formalingo.com)
2. Go to **Settings > API Keys**
3. Create a new key

### Initialize the Client

```typescript
import { createClient } from "@formalingo/sdk"

// Production (default)
const client = createClient("af_live_YOUR_API_KEY")

// Custom base URL (e.g., local development)
const client = createClient("af_live_YOUR_API_KEY", "http://localhost:3000")
```

## Usage Examples

### Forms

```typescript
// List forms
const forms = await client.forms.get()

// Get a specific form
const form = await client.forms.byFormId("form-id").get()

// Update a form
await client.forms.byFormId("form-id").put({
  body: { title: "Updated Title", status: "published" },
})

// Delete a form
await client.forms.byFormId("form-id").delete()
```

### Sections & Questions

```typescript
const formApi = client.forms.byFormId("form-id")

// Create a section
const section = await formApi.sections.post({
  body: { title: "Personal Info", order: 0 },
})

// Add a question
const question = await formApi.questions.post({
  body: {
    sectionId: section.id,
    type: "short_text",
    title: "What is your name?",
    required: true,
    order: 0,
  },
})

// Multiple choice question
await formApi.questions.post({
  body: {
    sectionId: section.id,
    type: "mcq",
    title: "How did you hear about us?",
    required: false,
    order: 1,
    options: {
      choices: ["Search engine", "Social media", "Friend", "Other"],
    },
  },
})
```

### Recipients

```typescript
// Create a recipient (generates a shareable link)
const recipient = await client.forms.byFormId("form-id").recipients.post({
  body: {
    label: "John Doe",
    prefill: { name: "John Doe", email: "john@example.com" },
  },
})

// The shareable form URL
const formUrl = `https://www.formalingo.com/f/${recipient.token}`
```

### Branding

```typescript
await client.forms.byFormId("form-id").branding.put({
  body: {
    primaryColor: "#4F46E5",
    backgroundColor: "#F9FAFB",
    welcomeHeading: "Welcome!",
    welcomeSubtitle: "This will only take a minute.",
    thankYouHeading: "Thank you!",
    thankYouMessage: "Your response has been recorded.",
  },
})
```

### Documents

```typescript
// List documents
const documents = await client.documents.get()

// Create a document with signers
const doc = await client.documents.post({
  body: {
    title: "NDA Agreement",
    content: "Full document text...",
    signers: [
      { name: "Alice", email: "alice@example.com" },
      { name: "Bob", email: "bob@example.com" },
    ],
  },
})
```

### Error Handling

```typescript
try {
  const form = await client.forms.byFormId("nonexistent").get()
} catch (error) {
  if (error instanceof Error) {
    console.error("API error:", error.message)
  }
}
```

## Advanced Usage

For full control over the underlying Kiota client:

```typescript
import { createFormalingoClient } from "@formalingo/sdk"
import {
  ApiKeyAuthenticationProvider,
  ApiKeyLocation,
} from "@microsoft/kiota-abstractions"
import { FetchRequestAdapter } from "@microsoft/kiota-http-fetchlibrary"

const auth = new ApiKeyAuthenticationProvider(
  "Bearer af_live_YOUR_API_KEY",
  "Authorization",
  ApiKeyLocation.Header
)
const adapter = new FetchRequestAdapter(auth)
adapter.baseUrl = "https://app.formalingo.com"

const rawClient = createFormalingoClient(adapter)
const v1 = rawClient.api.v1
```

## Requirements

- Node.js 20+
- ESM (this package uses `"type": "module"`)

## Other SDKs

Formalingo also provides SDKs for:

- **Python** — [`formalingo-sdk`](https://github.com/Formalingo/sdk-python)
- **.NET** — [`Formalingo.Sdk`](https://www.nuget.org/packages/Formalingo.Sdk)
- **Go** — [`github.com/Formalingo/sdk-go`](https://github.com/Formalingo/sdk-go)

## Documentation

Full API documentation and guides: [formalingo.com/docs](https://www.formalingo.com/docs)

## License

MIT