@zoerai/integration

A TypeScript library built with tsdown - fast, modern, and type-safe.

Features

• Written in TypeScript with full type definitions
• ESM module support
• Built with tsdown for blazing fast builds
• Comprehensive test coverage with Vitest
• Zero dependencies

Installation

# Using npm
npm install @zoerai/integration

# Using pnpm
pnpm add @zoerai/integration

# Using yarn
yarn add @zoerai/integration

Usage

ESM (ES Modules)

import { greet, add, getVersion, upload } from '@zoerai/integration'

// Greet someone
const greeting = greet({ name: 'Alice' })
console.log(greeting) // "Hello, Alice."

// With enthusiasm
const enthusiasticGreeting = greet({ name: 'Bob', enthusiastic: true })
console.log(enthusiasticGreeting) // "Hello, Bob!"

// Add numbers
const sum = add(5, 3)
console.log(sum) // 8

// Get library version
const version = getVersion()
console.log(version) // "1.0.0"

// Upload a file
const file = {
  name: 'document.pdf',
  size: 2048,
  type: 'application/pdf'
}
const uploadResult = await upload.uploadFile(file)
console.log(uploadResult)
// { success: true, url: '...', fileId: '...', timestamp: ... }

Configuration

Environment Setup

The library automatically detects the environment and uses the appropriate API endpoint:

• Production (default): https://zoer.ai/
• Development: http://127.0.0.1:1011

configure(config)

Manually configure the library settings.

Parameters:

• config.apiUrl? (string): Custom API base URL
• config.environment? ('production' | 'development'): Set environment

Examples:

import { configure } from '@zoerai/integration'

// Set custom API URL
configure({ apiUrl: 'https://custom.api.com/' })

// Set environment (automatically uses the corresponding API URL)
configure({ environment: 'development' })

// Or both
configure({
  apiUrl: 'https://staging.zoer.ai/',
  environment: 'production'
})

getConfig()

Get the current configuration.

Returns: ApiConfig - Current configuration object

Example:

import { getConfig } from '@zoerai/integration'

const config = getConfig()
console.log(config.apiUrl)       // 'https://zoer.ai/'
console.log(config.environment)  // 'production'

getApiUrl()

Get the current API base URL.

Returns: string - Current API base URL

Example:

import { getApiUrl } from '@zoerai/integration'

const url = getApiUrl()
console.log(url)  // 'https://zoer.ai/'

API

greet(options)

Greets a person with a customizable message.

Parameters:

• options.name (string): The name of the person to greet
• options.enthusiastic (boolean, optional): Add enthusiasm to the greeting

Returns: string - The greeting message

Example:

greet({ name: 'Alice' }) // "Hello, Alice."
greet({ name: 'Bob', enthusiastic: true }) // "Hello, Bob!"

add(a, b)

Adds two numbers together.

Parameters:

• a (number): First number
• b (number): Second number

Returns: number - The sum of a and b

Example:

add(5, 3) // 8
add(-2, 10) // 8

getVersion()

Gets the current library version.

Returns: string - The version string

Example:

getVersion() // "1.0.0"

upload.uploadFile(file)

Upload a single file to the backend using multipart/form-data.

Parameters:

• file (UploadFile): The file to upload
  • name (string): File name (e.g., "document.pdf", "image.png")
  • size (number): File size in bytes
  • type (string): MIME type (e.g., "image/png", "application/pdf")
  • data? (Buffer | Blob | ArrayBuffer): File content (optional)

Returns: Promise<UploadResult> - Upload result

• success (boolean): Whether the upload was successful
• url? (string): Uploaded file URL or path
• fileId? (string): Uploaded file ID
• error? (string): Error message if upload failed
• timestamp (number): Upload timestamp

Example:

// Browser environment with File API
const fileInput = document.querySelector('input[type="file"]')
const browserFile = fileInput.files[0]

const uploadFile = {
  name: browserFile.name,
  size: browserFile.size,
  type: browserFile.type,
  data: await browserFile.arrayBuffer()
}

const result = await upload.uploadFile(uploadFile)
console.log(result)
// { success: true, url: '...', fileId: '...', timestamp: ... }

// Node.js environment
import fs from 'fs'

const buffer = fs.readFileSync('path/to/file.pdf')
const result = await upload.uploadFile({
  name: 'document.pdf',
  size: buffer.length,
  type: 'application/pdf',
  data: buffer
})

Development

Install dependencies

pnpm install

Build

# Build the library
pnpm build

# Watch mode for development
pnpm dev

Testing

# Run tests
pnpm test

# Watch mode for tests
pnpm test:watch

# Generate coverage report
pnpm test:coverage

# Open test UI
pnpm test:ui

Built With

• TypeScript - Type-safe JavaScript
• tsdown - The elegant bundler for libraries
• Vitest - Next generation testing framework

License

ISC