SDK & Libraries

Official client libraries for integrating Verk into your applications. Build powerful integrations with type-safe, well-documented SDKs.

Official SDKs

Verk provides officially maintained SDKs for popular programming languages:

• JavaScript/TypeScript - Full-featured SDK with TypeScript support
• Python - Pythonic API with async support
• Go - Idiomatic Go SDK with concurrency support

All SDKs include:

• Type-safe API clients
• Automatic authentication handling
• Built-in retry logic and error handling
• Comprehensive documentation
• Full test coverage

JavaScript/TypeScript SDK

Installation

npm install @verk/sdk
# or
yarn add @verk/sdk
# or
pnpm add @verk/sdk

Quick Start

import { VerkClient } from '@verk/sdk'

const verk = new VerkClient({
  apiKey: process.env.VERK_API_KEY,
  baseUrl: 'https://api.verk.com/v1', // optional
})

// Create a task
const task = await verk.tasks.create({
  title: 'Implement authentication',
  projectId: 'proj_123',
  priority: 'high',
  assigneeId: 'user_456',
})

console.log(`Created task: ${task.id}`)

Configuration

const verk = new VerkClient({
  apiKey: 'your_api_key',
  baseUrl: 'https://api.verk.com/v1',
  timeout: 30000, // 30 seconds
  retries: 3,
  onError: error => {
    console.error('API Error:', error)
  },
})

Tasks API

List Tasks

// Get all tasks
const tasks = await verk.tasks.list()

// With filters
const tasks = await verk.tasks.list({
  status: 'in_progress',
  projectId: 'proj_123',
  assigneeId: 'user_456',
  limit: 50,
})

// Pagination
const firstPage = await verk.tasks.list({ limit: 20 })
const secondPage = await verk.tasks.list({
  limit: 20,
  offset: 20,
})

Create Task

const task = await verk.tasks.create({
  title: 'Design landing page',
  description: 'Create mockups for new landing page',
  projectId: 'proj_123',
  priority: 'high',
  status: 'todo',
  assigneeId: 'user_456',
  dueDate: new Date('2024-12-31'),
  customFields: {
    estimatedHours: 8,
    category: 'Design',
  },
})

Update Task

const updated = await verk.tasks.update('task_123', {
  status: 'in_progress',
  priority: 'medium',
  assigneeId: 'user_789',
})

Delete Task

await verk.tasks.delete('task_123')

Get Task

const task = await verk.tasks.get('task_123')

Projects API

// List projects
const projects = await verk.projects.list()

// Create project
const project = await verk.projects.create({
  name: 'Mobile App Redesign',
  description: 'Q1 2024 mobile redesign project',
  icon: 'mobile',
  color: '#3B82F6',
})

// Update project
await verk.projects.update('proj_123', {
  name: 'Updated Project Name',
})

// Delete project
await verk.projects.delete('proj_123')

Members API

// List members
const members = await verk.members.list()

// Invite member
await verk.members.invite({
  email: 'newuser@example.com',
  role: 'member',
})

// Update member role
await verk.members.update('user_123', {
  role: 'admin',
})

Comments API

// List comments
const comments = await verk.comments.list('task_123')

// Create comment
const comment = await verk.comments.create('task_123', {
  content: 'Great work on this!',
  mentions: ['user_456'],
})

// Update comment
await verk.comments.update('comment_123', {
  content: 'Updated comment text',
})

// Delete comment
await verk.comments.delete('comment_123')

File Upload

// Node.js file upload
import fs from 'fs'

const fileStream = fs.createReadStream('./document.pdf')
const file = await verk.files.upload({
  file: fileStream,
  projectId: 'proj_123',
  name: 'Requirements Document',
})

// Browser file upload
const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
  const file = event.target.files?.[0]
  if (!file) return

  const uploaded = await verk.files.upload({
    file,
    projectId: 'proj_123',
  })

  console.log(`Uploaded: ${uploaded.url}`)
}

Webhooks

// Create webhook
const webhook = await verk.webhooks.create({
  url: 'https://your-server.com/webhook',
  events: ['task.created', 'task.updated'],
  secret: 'your_webhook_secret',
})

// List webhooks
const webhooks = await verk.webhooks.list()

// Delete webhook
await verk.webhooks.delete('webhook_123')

Error Handling

import { VerkError, VerkAPIError } from '@verk/sdk'

try {
  const task = await verk.tasks.create({
    title: 'New task',
    projectId: 'proj_123',
  })
} catch (error) {
  if (error instanceof VerkAPIError) {
    console.error('API Error:', {
      status: error.status,
      code: error.code,
      message: error.message,
      param: error.param,
    })
  } else if (error instanceof VerkError) {
    console.error('SDK Error:', error.message)
  } else {
    console.error('Unknown error:', error)
  }
}

TypeScript Types

import type {
  Task,
  Project,
  Member,
  Comment,
  CreateTaskRequest,
  UpdateTaskRequest,
} from '@verk/sdk'

// Fully typed API responses
const task: Task = await verk.tasks.get('task_123')
const projects: Project[] = await verk.projects.list()

Python SDK

Installation

pip install verk-sdk

Quick Start

from verk import VerkClient

# Initialize client
verk = VerkClient(api_key="your_api_key")

# Create task
task = verk.tasks.create(
 title="Implement authentication",
 project_id="proj_123",
 priority="high",
 assignee_id="user_456"
)

print(f"Created task: {task.id}")

Configuration

from verk import VerkClient

verk = VerkClient(
 api_key="your_api_key",
 base_url="https://api.verk.com/v1",
 timeout=30,
 max_retries=3
)

Tasks API

# List tasks
tasks = verk.tasks.list(
 status="in_progress",
 project_id="proj_123",
 limit=50
)

# Create task
task = verk.tasks.create(
 title="Design landing page",
 description="Create mockups",
 project_id="proj_123",
 priority="high",
 due_date="2024-12-31T23:59:59Z"
)

# Update task
updated = verk.tasks.update(
 "task_123",
 status="done",
 priority="low"
)

# Delete task
verk.tasks.delete("task_123")

# Get task
task = verk.tasks.get("task_123")

Async Support

import asyncio
from verk import AsyncVerkClient

async def main():
 async with AsyncVerkClient(api_key="your_api_key") as verk:
  # Concurrent requests
  tasks = await asyncio.gather(
   verk.tasks.get("task_1"),
   verk.tasks.get("task_2"),
   verk.tasks.get("task_3")
  )

  print(f"Retrieved {len(tasks)} tasks")

asyncio.run(main())

Context Manager

with VerkClient(api_key="your_api_key") as verk:
 tasks = verk.tasks.list()
 # Client automatically closed

Error Handling

from verk import VerkClient, VerkAPIError, VerkError

try:
 task = verk.tasks.create(
  title="New task",
  project_id="proj_123"
 )
except VerkAPIError as e:
 print(f"API Error: {e.status_code} - {e.message}")
 print(f"Error code: {e.error_code}")
except VerkError as e:
 print(f"SDK Error: {e}")

Pagination Helper

# Iterate through all tasks
for task in verk.tasks.iter():
 print(f"Task: {task.title}")

# With filters
for task in verk.tasks.iter(status="todo", project_id="proj_123"):
 print(f"Todo: {task.title}")

Go SDK

Installation

go get github.com/verk/go-sdk

Quick Start

package main

import (
 "context"
 "fmt"
 "log"

 "github.com/verk/go-sdk"
)

func main() {
 client := verk.NewClient("your_api_key")

 // Create task
 task, err := client.Tasks.Create(context.Background(), &verk.CreateTaskRequest{
  Title:  "Implement authentication",
  ProjectID: "proj_123",
  Priority: verk.PriorityHigh,
  AssigneeID: "user_456",
 })
 if err != nil {
  log.Fatal(err)
 }

 fmt.Printf("Created task: %s\n", task.ID)
}

Configuration

import "github.com/verk/go-sdk"

client := verk.NewClient(
 "your_api_key",
 verk.WithBaseURL("https://api.verk.com/v1"),
 verk.WithTimeout(30 * time.Second),
 verk.WithRetries(3),
)

Tasks API

// List tasks
tasks, err := client.Tasks.List(ctx, &verk.ListTasksParams{
 Status: verk.StatusInProgress,
 ProjectID: "proj_123",
 Limit:  50,
})
if err != nil {
 log.Fatal(err)
}

// Create task
task, err := client.Tasks.Create(ctx, &verk.CreateTaskRequest{
 Title:  "Design landing page",
 Description: "Create mockups",
 ProjectID: "proj_123",
 Priority: verk.PriorityHigh,
})

// Update task
updated, err := client.Tasks.Update(ctx, "task_123", &verk.UpdateTaskRequest{
 Status: verk.StatusDone,
 Priority: verk.PriorityLow,
})

// Delete task
err = client.Tasks.Delete(ctx, "task_123")

Concurrency

import "golang.org/x/sync/errgroup"

func fetchTasks(ctx context.Context, taskIDs []string) ([]*verk.Task, error) {
 g, ctx := errgroup.WithContext(ctx)
 tasks := make([]*verk.Task, len(taskIDs))

 for i, id := range taskIDs {
  i, id := i, id // capture loop vars
  g.Go(func() error {
   task, err := client.Tasks.Get(ctx, id)
   if err != nil {
    return err
   }
   tasks[i] = task
   return nil
  })
 }

 if err := g.Wait(); err != nil {
  return nil, err
 }

 return tasks, nil
}

Error Handling

import "github.com/verk/go-sdk"

task, err := client.Tasks.Create(ctx, req)
if err != nil {
 if apiErr, ok := err.(*verk.APIError); ok {
  fmt.Printf("API Error: %d - %s\n", apiErr.StatusCode, apiErr.Message)
  fmt.Printf("Error code: %s\n", apiErr.Code)
 } else {
  log.Fatal(err)
 }
}

Community Libraries

Ruby

gem install verk-ruby

require 'verk'

client = Verk::Client.new(api_key: ENV['VERK_API_KEY'])
task = client.tasks.create(
 title: 'New task',
 project_id: 'proj_123'
)

Maintainer: @username

PHP

composer require verk/php-sdk

<?php
use Verk\Client;

$client = new Client(['api_key' => getenv('VERK_API_KEY')]);
$task = $client->tasks->create([
 'title' => 'New task',
 'project_id' => 'proj_123'
]);

Maintainer: @username

Rust

[dependencies]
verk-sdk = "0.1.0"

use verk_sdk::Client;

#[tokio::main]
async fn main() {
 let client = Client::new("your_api_key");
 let task = client.tasks().create()
  .title("New task")
  .project_id("proj_123")
  .send()
  .await
  .unwrap();
}

Maintainer: @username

Code Examples

Bulk Task Creation

// Create multiple tasks efficiently
const taskData = [
  { title: 'Task 1', priority: 'high' },
  { title: 'Task 2', priority: 'medium' },
  { title: 'Task 3', priority: 'low' },
]

const tasks = await Promise.all(
  taskData.map(data =>
    verk.tasks.create({
      ...data,
      projectId: 'proj_123',
    })
  )
)

console.log(`Created ${tasks.length} tasks`)

Task Synchronization

# Sync external tasks to Verk
def sync_tasks_from_external_system():
 external_tasks = fetch_external_tasks()

 for ext_task in external_tasks:
  # Check if task exists
  existing = verk.tasks.list(
   custom_fields={"external_id": ext_task.id}
  )

  if existing:
   # Update existing
   verk.tasks.update(existing[0].id, {
    "title": ext_task.title,
    "status": map_status(ext_task.status)
   })
  else:
   # Create new
   verk.tasks.create({
    "title": ext_task.title,
    "project_id": "proj_123",
    "custom_fields": {
     "external_id": ext_task.id
    }
   })

Real-time Updates

// Poll for task updates
async function watchTask(taskId: string) {
  let lastUpdate = Date.now()

  setInterval(async () => {
    const task = await verk.tasks.get(taskId)
    const updated = new Date(task.updatedAt).getTime()

    if (updated > lastUpdate) {
      console.log('Task updated:', task)
      lastUpdate = updated
    }
  }, 5000) // Check every 5 seconds
}

Custom Workflow

// Automated task workflow
func processNewTask(ctx context.Context, taskID string) error {
 // Get task
 task, err := client.Tasks.Get(ctx, taskID)
 if err != nil {
  return err
 }

 // Assign based on priority
 var assigneeID string
 switch task.Priority {
 case verk.PriorityHigh:
  assigneeID = "senior_dev_123"
 case verk.PriorityMedium:
  assigneeID = "mid_dev_456"
 default:
  assigneeID = "junior_dev_789"
 }

 // Update task
 _, err = client.Tasks.Update(ctx, taskID, &verk.UpdateTaskRequest{
  AssigneeID: assigneeID,
  Status:  verk.StatusInProgress,
 })

 return err
}

Best Practices

API Key Management

Environment Variables

# .env
VERK_API_KEY=verk_live_abc123...

import { VerkClient } from '@verk/sdk'

const verk = new VerkClient({
  apiKey: process.env.VERK_API_KEY,
})

Never commit API keys to version control. Use environment variables or secret management systems.

Rate Limiting

Implement exponential backoff:

async function createTaskWithRetry(data: CreateTaskRequest) {
  let retries = 0
  const maxRetries = 3

  while (retries < maxRetries) {
    try {
      return await verk.tasks.create(data)
    } catch (error) {
      if (error.status === 429) {
        const delay = Math.pow(2, retries) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
        retries++
      } else {
        throw error
      }
    }
  }

  throw new Error('Max retries exceeded')
}

Caching

Cache frequently accessed data:

from functools import lru_cache
import time

@lru_cache(maxsize=128)
def get_project_cached(project_id: str):
 return verk.projects.get(project_id)

# Cache expires after 5 minutes
cache_timestamp = {}

def get_project_with_ttl(project_id: str):
 now = time.time()
 if project_id in cache_timestamp:
  if now - cache_timestamp[project_id] < 300:
   return get_project_cached(project_id)
  else:
   get_project_cached.cache_clear()

 cache_timestamp[project_id] = now
 return get_project_cached(project_id)

Error Handling

Handle errors gracefully:

try {
  const task = await verk.tasks.create(data)
  return { success: true, task }
} catch (error) {
  if (error instanceof VerkAPIError) {
    // Log API errors
    logger.error('Verk API Error', {
      status: error.status,
      code: error.code,
      message: error.message,
    })

    // User-friendly error messages
    if (error.status === 401) {
      return { success: false, error: 'Authentication failed' }
    } else if (error.status === 429) {
      return { success: false, error: 'Rate limit exceeded' }
    }
  }

  return { success: false, error: 'Unknown error' }
}

Batch Operations

Process in batches to avoid rate limits:

def batch_create_tasks(task_list, batch_size=10):
 results = []

 for i in range(0, len(task_list), batch_size):
  batch = task_list[i:i + batch_size]

  for task_data in batch:
   try:
    task = verk.tasks.create(**task_data)
    results.append(task)
   except VerkAPIError as e:
    logger.error(f"Failed to create task: {e}")

  # Rate limit pause between batches
  time.sleep(1)

 return results

Testing

Mock Client (JavaScript)

import { VerkClient } from '@verk/sdk'

// Mock for testing
jest.mock('@verk/sdk')

describe('Task Service', () => {
  it('should create task', async () => {
    const mockCreate = jest.fn().mockResolvedValue({
      id: 'task_123',
      title: 'Test task',
    })

    ;(VerkClient as jest.Mock).mockImplementation(() => ({
      tasks: { create: mockCreate },
    }))

    const verk = new VerkClient({ apiKey: 'test' })
    const task = await verk.tasks.create({
      title: 'Test task',
      projectId: 'proj_123',
    })

    expect(task.id).toBe('task_123')
    expect(mockCreate).toHaveBeenCalled()
  })
})

Test Mode (Python)

# Use test API key
verk = VerkClient(api_key="verk_test_123...")

# Test operations won't affect production data
task = verk.tasks.create(
 title="Test task",
 project_id="proj_test_123"
)

Related Documentation

• API Reference - Complete API documentation
• Webhooks - Event notifications
• Customization - Advanced integration
• API Keys - Authentication setup

---

Need SDK help? Check our GitHub discussions or contact support.