@climactic/mda

Official TypeScript SDK and CLI for the Markdown Anything API. Convert any document to clean markdown.

Zero dependencies. Works in Node.js, Bun, Deno, edge runtimes, and browsers.

Install

npm install @climactic/mda
# or
bun add @climactic/mda

SDK Usage

import { MarkdownAnything } from '@climactic/mda'

const mda = new MarkdownAnything('mda_your_token')

// Convert a file
const result = await mda.convert(file)
console.log(result.markdown)

// With options
const result = await mda.convert(file, {
  enhancedAi: true,
  optimizeTokens: true,
  includeMetadata: true,
})

File Inputs

The SDK accepts multiple file input types:

// File object (browser)
await mda.convert(fileInput)

// Buffer or ArrayBuffer (Node.js)
await mda.convert(buffer, { filename: 'doc.pdf' })

// File path (Node.js / Bun only)
await mda.convert('/path/to/document.pdf')

// Blob
await mda.convert(blob, { filename: 'doc.pdf' })

Async Conversions (Webhooks)

const pending = await mda.convert(file, {
  webhookUrl: 'https://example.com/hook',
  webhookSecret: 'your-secret-min-32-chars..........',
})

console.log(pending.id)     // conversion UUID
console.log(pending.status) // "pending"

// Or poll until complete
const completed = await pending.poll()
console.log(completed.markdown)

Conversion History

const list = await mda.conversions.list({ status: 'completed', page: 1 })

const detail = await mda.conversions.get('conversion-uuid')

Webhook Verification

import { verifyWebhookSignature } from '@climactic/mda'

const isValid = await verifyWebhookSignature(rawBody, signatureHeader, secret)

Error Handling

import { InsufficientCreditsError, RateLimitError } from '@climactic/mda'

try {
  await mda.convert(file)
} catch (error) {
  if (error instanceof InsufficientCreditsError) {
    console.log(`Need ${error.creditsRequired}, have ${error.creditsAvailable}`)
  }
  if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter} seconds`)
  }
}

Configuration

const mda = new MarkdownAnything('mda_your_token', {
  baseUrl: 'https://markdownanything.com', // default
  timeout: 30000,                           // ms
  fetch: customFetch,                       // override fetch
})

CLI Usage

Authentication

# Browser-based login (recommended)
mda auth login

# Manual token entry
mda auth login --token

# Direct token (scripting/CI)
mda auth login mda_your_token

# Check status
mda auth status

# Logout
mda auth logout

Convert Files

# Print markdown to stdout
mda convert document.pdf

# Write to file
mda convert document.pdf -o output.md

# With options
mda convert doc.pdf --enhanced-ai --optimize-tokens

# Full JSON response
mda convert doc.pdf --json

# Batch convert
mda convert *.pdf -o ./output/

# From stdin
cat document.pdf | mda convert --filename document.pdf

Conversion History

mda conversions list
mda conversions list --status completed --json
mda conversions get <uuid>

Environment Variables

MDA_API_KEY — overrides stored credentials.

Documentation

Full documentation at markdownanything.com/docs/sdks/javascript.

License

MIT