SDK Documentation

Official client libraries for ClockEye

Overview

ClockEye provides official SDKs for popular programming languages. These libraries wrap our REST API and provide type-safe, idiomatic interfaces for your language of choice.

Features

  • Type-safe API clients with full IntelliSense support
  • Automatic request retries with exponential backoff
  • Built-in rate limiting and error handling
  • Webhook signature verification
  • Promise-based async operations
  • Comprehensive TypeScript types

Available SDKs

JavaScript / TypeScript

@clockeye/sdk
v2.0.0
Installation
npm install @clockeye/sdk
Example
import { ClockEye } from '@clockeye/sdk'

const client = new ClockEye({
  apiKey: process.env.TIMEDECK_API_KEY
})

// Start a timer
const timer = await client.timers.start({
  projectId: 'proj_123',
  description: 'Working on feature'
})

// Get time entries
const entries = await client.timeEntries.list({
  userId: 'user_456',
  startDate: '2025-01-01',
  endDate: '2025-01-31'
})

Python

clockeye
v2.0.0
Installation
pip install clockeye
Example
from clockeye import ClockEye

client = ClockEye(api_key=os.environ['TIMEDECK_API_KEY'])

# Start a timer
timer = client.timers.start(
    project_id='proj_123',
    description='Working on feature'
)

# Get time entries
entries = client.time_entries.list(
    user_id='user_456',
    start_date='2025-01-01',
    end_date='2025-01-31'
)

Ruby

clockeye
v2.0.0
Installation
gem install clockeye
Example
require 'clockeye'

client = ClockEye::Client.new(
  api_key: ENV['TIMEDECK_API_KEY']
)

# Start a timer
timer = client.timers.start(
  project_id: 'proj_123',
  description: 'Working on feature'
)

# Get time entries
entries = client.time_entries.list(
  user_id: 'user_456',
  start_date: '2025-01-01',
  end_date: '2025-01-31'
)

Go

github.com/clockeye/sdk-go
v2.0.0
Installation
go get github.com/clockeye/sdk-go
Example
package main

import (
    "os"
    clockeye "github.com/clockeye/sdk-go"
)

func main() {
    client := clockeye.NewClient(os.Getenv("TIMEDECK_API_KEY"))

    // Start a timer
    timer, _ := client.Timers.Start(&clockeye.StartTimerParams{
        ProjectID:   "proj_123",
        Description: "Working on feature",
    })

    // Get time entries
    entries, _ := client.TimeEntries.List(&clockeye.ListEntriesParams{
        UserID:    "user_456",
        StartDate: "2025-01-01",
        EndDate:   "2025-01-31",
    })
}

Authentication

All SDKs use API keys for authentication. Generate an API key from your ClockEye dashboard under Settings → API Keys.

Security Best Practice

Never commit API keys to version control. Use environment variables or a secrets manager to store your API keys securely.

Error Handling

All SDKs provide consistent error handling with typed error classes:

import { ClockEye, TimedeckError, RateLimitError } from '@clockeye/sdk'

try {
  const entries = await client.timeEntries.list()
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Rate limited. Retry after:', error.retryAfter)
  } else if (error instanceof TimedeckError) {
    console.log('API error:', error.message, error.code)
  }
}

Additional Resources

API Reference
Webhooks Guide