twapi

README

🚀 Teamwork.com API - Go SDK

The official Go SDK for the Teamwork.com API

Build powerful integrations with Teamwork's project management platform

📖 API Documentation • 🎯 Examples • 🐛 Report Issues

---

✨ Features

• � Multiple Authentication Methods - Bearer token, Basic auth, and OAuth2
• 🏗️ Type-Safe API - Fully typed requests and responses
• 🌐 Context Support - Built-in context.Context support for cancellation and timeouts
• 📦 Zero Dependencies - Minimal external dependencies
• 🧪 Thoroughly Tested - Comprehensive test coverage
• 📱 Cross-Platform - Works on Windows, macOS, and Linux

📦 Installation

Add this library as a dependency to your Go module:

go get github.com/teamwork/twapi-go-sdk

Requirements:

• Go 1.24 or later
• A Teamwork.com account with API access

🔐 Authentication

The SDK supports multiple authentication methods to suit different use cases:

🎫 Bearer Token (Recommended)

Perfect for server-to-server integrations and scripts:

import "github.com/teamwork/twapi-go-sdk/session"

session := session.NewBearerToken("your_api_token", "https://yourdomain.teamwork.com")

🔑 Basic Authentication

Use with API tokens or user credentials:

// With API token
session := session.NewBasicAuth("your_api_token", "", "https://yourdomain.teamwork.com")

// With username/password
session := session.NewBasicAuth("username", "password", "https://yourdomain.teamwork.com")

🌐 OAuth2

Ideal for user-facing applications (opens browser for authorization):

session := session.NewOAuth2("client_id", "client_secret",
  session.WithOAuth2Server("https://teamwork.com"),
  session.WithOAuth2CallbackServerAddr("127.0.0.1:6275"),
)

[!CAUTION] ⚠️ Note: OAuth2 opens a browser window and is not suitable for headless environments.

🏁 Quick Start

Here's a simple example to get you started:

package main

import (
  "context"
  "fmt"
  "log"

  twapi "github.com/teamwork/twapi-go-sdk"
  "github.com/teamwork/twapi-go-sdk/projects"
  "github.com/teamwork/twapi-go-sdk/session"
)

func main() {
  ctx := context.Background()
  
  // Initialize the SDK with bearer token authentication
  engine := twapi.NewEngine(session.NewBearerToken("your_token", "https://yourdomain.teamwork.com"))

  // Create a new project
  project, err := projects.ProjectCreate(ctx, engine, projects.NewProjectCreateRequest("My Awesome Project"))
  if err != nil {
    log.Fatalf("Failed to create project: %v", err)
  }
  
  fmt.Printf("✅ Created project '%s' with ID: %d\n", project.Name, project.ID)
}

📚 Examples

Working with Projects

package main

import (
  "context"
  "fmt"
  "time"

  twapi "github.com/teamwork/twapi-go-sdk"
  "github.com/teamwork/twapi-go-sdk/projects"
  "github.com/teamwork/twapi-go-sdk/session"
)

func main() {
  ctx := context.Background()
  engine := twapi.NewEngine(session.NewBearerToken("your_token", "https://yourdomain.teamwork.com"))

  project, err := projects.ProjectCreate(ctx, engine, projects.ProjectCreateRequest{
    Name:        "Q1 Marketing Campaign",
    Description: twapi.Ptr("Marketing campaign for Q1 product launch"),
    StartAt:     twapi.Ptr(time.Now()),
    EndAt:       twapi.Ptr(time.Now().AddDate(0, 3, 0)), // 3 months from now
  })
  if err != nil {
    fmt.Fprintf(os.Stderr, "❌ Failed to create project: %v\n", err)
    os.Exit(1)
  }

  // Retrieve the project
  retrievedProject, err := projects.ProjectGet(ctx, engine, projects.NewProjectRetrieveRequest(int64(project.ID)))
  if err != nil {
    fmt.Fprintf(os.Stderr, "❌ Failed to retrieve project: %v\n", err)
    os.Exit(1)
  }

  fmt.Printf("✅ Project: %s (ID: %d)\n", retrievedProject.Name, retrievedProject.ID)
  
  // List all projects
  projectsList, err := projects.ProjectList(ctx, engine, projects.NewProjectRetrieveManyRequest())
  if err != nil {
    fmt.Fprintf(os.Stderr, "❌ Failed to list projects: %v\n", err)
    os.Exit(1)
  }
  
  fmt.Printf("✅ Found %d projects\n", len(projectsList.Projects))
  
  // Update the project
  updatedProject, err := projects.ProjectUpdate(ctx, engine, projects.ProjectUpdateRequest{
    Path:  projects.ProjectUpdateRequestPath{
      ID: int64(project.ID),
    },
    Name: "Q1 Marketing Campaign - Updated",
  })
  if err != nil {
    fmt.Fprintf(os.Stderr, "❌ Failed to update project: %v\n", err)
    os.Exit(1)
  }
  
  fmt.Printf("✅ Updated project name to: %s\n", updatedProject.Name)

  // Delete the project
  err = projects.ProjectDelete(ctx, engine, projects.NewProjectDeleteRequest(int64(project.ID)))
  if err != nil {
    fmt.Fprintf(os.Stderr, "❌ Failed to delete project: %v\n", err)
    os.Exit(1)
  }

  fmt.Println("✅ Project deleted successfully")
}

OAuth2 Authentication Example

package main

import (
  "context"
  "flag"
  "fmt"
  "os"

  twapi "github.com/teamwork/twapi-go-sdk"
  "github.com/teamwork/twapi-go-sdk/projects"
  "github.com/teamwork/twapi-go-sdk/session"
)

func main() {
  clientID := flag.String("client-id", "", "OAuth2 Client ID")
  clientSecret := flag.String("client-secret", "", "OAuth2 Client Secret")
  flag.Parse()

  if *clientID == "" || *clientSecret == "" {
    fmt.Fprintln(os.Stderr, "❌ client-id and client-secret are required")
    os.Exit(1)
  }

  // Create OAuth2 session (will open browser for authorization)
  session := session.NewOAuth2(*clientID, *clientSecret,
    session.WithOAuth2CallbackServerAddr("127.0.0.1:6275"),
  )
  
  engine := twapi.NewEngine(session)

  // Test the connection by creating a project
  project, err := projects.ProjectCreate(context.Background(), engine, projects.NewProjectCreateRequest("OAuth2 Test Project"))
  if err != nil {
    fmt.Fprintf(os.Stderr, "❌ Failed to create project: %v\n", err)
    os.Exit(1)
  }

  fmt.Printf("✅ OAuth2 authentication successful! Created project: %s (ID: %d)\n", project.Name, project.ID)
}

Error Handling Best Practices

package main

import (
  "context"
  "errors"
  "fmt"
  "net/http"

  twapi "github.com/teamwork/twapi-go-sdk"
  "github.com/teamwork/twapi-go-sdk/projects"
  "github.com/teamwork/twapi-go-sdk/session"
)

func main() {
  ctx := context.Background()
  engine := twapi.NewEngine(session.NewBearerToken("your_token", "https://yourdomain.teamwork.com"))

  project, err := projects.ProjectCreate(ctx, engine, projects.NewProjectCreateRequest("Test Project"))
  if err != nil {
    // Handle different types of errors
    var httpErr *twapi.HTTPError
    if errors.As(err, &httpErr) {
      switch httpErr.StatusCode {
      case http.StatusUnauthorized:
        fmt.Println("❌ Authentication failed - check your API token")
      case http.StatusForbidden:
        fmt.Println("❌ Access denied - insufficient permissions")
      case http.StatusTooManyRequests:
        fmt.Println("❌ Rate limit exceeded - please retry later")
      default:
        fmt.Printf("❌ HTTP error %d: %s\n", httpErr.StatusCode, httpErr.Message)
      }
    } else {
      fmt.Printf("❌ Unexpected error: %v\n", err)
    }
    return
  }

  fmt.Printf("✅ Success! Created project: %s\n", project.Name)
}

🔧 Configuration

Context and Timeouts

The SDK supports Go's context.Context for request cancellation and timeouts:

import "time"

// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// Use the context in API calls
project, err := projects.ProjectCreate(ctx, engine, request)

Custom HTTP Client

You can customize the underlying HTTP client:

import (
  "net/http"
  "time"
)

// Create engine with custom HTTP client
httpClient := &http.Client{
  Timeout: 60 * time.Second,
  Transport: &http.Transport{
    MaxIdleConns:        10,
    IdleConnTimeout:     30 * time.Second,
    DisableCompression:  true,
  },
}

engine := twapi.NewEngine(session,
  twapi.WithHTTPClient(httpClient),
)

Middleware

You can add custom middleware to intercept and modify HTTP requests/responses. Middlewares are executed in the order they are added:

import (
  "fmt"
  "net/http"
  "time"

  twapi "github.com/teamwork/twapi-go-sdk"
  "github.com/teamwork/twapi-go-sdk/session"
)

// Logging middleware
func loggingMiddleware(next twapi.HTTPClient) twapi.HTTPClient {
  return twapi.HTTPClientFunc(func(req *http.Request) (*http.Response, error) {
    start := time.Now()
    fmt.Printf("➡️  %s %s", req.Method, req.URL)

    resp, err := next.Do(req)
    duration := time.Since(start)

    switch {
    case err != nil:
      fmt.Printf(" ❌ %s (took %v)\n", err.Error(), duration)
    case resp.StatusCode >= 400:
      fmt.Printf(" ❌ %s (took %v)\n", resp.Status, duration)
    default:
      fmt.Printf(" ✅ %s (took %v)\n", resp.Status, duration)
    }
    return resp, err
  })
}

// Rate limiting middleware
func rateLimitingMiddleware(next twapi.HTTPClient) twapi.HTTPClient {
  return twapi.HTTPClientFunc(func(req *http.Request) (*http.Response, error) {
    // Add rate limiting logic here
    time.Sleep(100 * time.Millisecond) // Simple delay example
    return next.Do(req)
  })
}

// Authentication header middleware
func authHeaderMiddleware(apiKey string) func(twapi.HTTPClient) twapi.HTTPClient {
  return func(next twapi.HTTPClient) twapi.HTTPClient {
    return twapi.HTTPClientFunc(func(req *http.Request) (*http.Response, error) {
      req.Header.Set("X-Custom-Auth", apiKey)
      return next.Do(req)
    })
  }
}

func main() {
  session := session.NewBearerToken("your_token", "https://yourdomain.teamwork.com")

  // Chain multiple middlewares
  engine := twapi.NewEngine(session,
    twapi.WithMiddleware(loggingMiddleware),
    twapi.WithMiddleware(rateLimitingMiddleware),
    twapi.WithMiddleware(authHeaderMiddleware("custom-key")),
  )

  // Now all requests will go through the middleware chain
  // ...use engine for API calls...
}

Iterator for Paginated Results

The SDK provides an iterator function to easily handle paginated API responses:

import (
  "context"
  "fmt"

  twapi "github.com/teamwork/twapi-go-sdk"
  "github.com/teamwork/twapi-go-sdk/projects"
  "github.com/teamwork/twapi-go-sdk/session"
)

func main() {
  ctx := context.Background()
  engine := twapi.NewEngine(session.NewBearerToken("your_token", "https://yourdomain.teamwork.com"))

  // Create an iterator for paginated project results
  next, err := twapi.Iterate[projects.ProjectListRequest, *projects.ProjectListResponse](
    ctx,
    engine,
    projects.NewProjectListRequest(),
  )
  if err != nil {
    fmt.Printf("Failed to create iterator: %v\n", err)
    return
  }

  // Iterate through all pages
  var iteration int
  for {
    iteration++
    fmt.Printf("📄 Page %d\n", iteration)

    response, hasNext, err := next()
    if err != nil {
      fmt.Printf("Error fetching page: %v\n", err)
      break
    }
    if response == nil {
      break
    }

    // Process projects from current page
    for _, project := range response.Projects {
      fmt.Printf("  ➢ %s (ID: %d)\n", project.Name, project.ID)
    }

    // Check if there are more pages
    if !hasNext {
      break
    }
  }
}

🐛 Error Handling

The SDK provides structured error handling:

import "errors"

project, err := projects.ProjectCreate(ctx, engine, request)
if err != nil {
  var httpErr *twapi.HTTPError
  if errors.As(err, &httpErr) {
    fmt.Printf("HTTP %d: %s\n", httpErr.StatusCode, httpErr.Message)
    // Handle specific status codes
  }
}

🧪 Testing

Run the test suite:

go test ./...

Run integration tests:

TWAPI_SERVER=https://yourdomain.teamwork.com/ TWAPI_TOKEN=your_api_token go test ./...

Run tests with coverage:

go test -race -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

📋 Requirements

• Go Version: 1.24 or later
• Dependencies: Minimal external dependencies (see go.mod)
• Teamwork Account: Valid Teamwork.com account with API access

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📖 API Documentation
• 🐛 Report Issues
• 💬 Community Support

---

Made with ❤️ by the Teamwork.com team

⭐ Star us on GitHub if this project helped you!

Documentation

Index

• func Execute[R HTTPRequester, T HTTPResponser](ctx context.Context, engine *Engine, requester R) (T, error)
• func Iterate[T HTTPRequester, R interface{ ... }](ctx context.Context, e *Engine, req T) (next func() (R, bool, error), err error)
• func Ptr[T any](v T) *T
• type Date
  • func (d Date) MarshalJSON() ([]byte, error)
  • func (d Date) MarshalText() ([]byte, error)
  • func (d Date) String() string
  • func (d *Date) UnmarshalJSON(data []byte) error
  • func (d *Date) UnmarshalText(text []byte) error
• type Engine
  • func NewEngine(session Session, opts ...EngineOption) *Engine
• type EngineOption
  • func WithHTTPClient(client HTTPClient) EngineOption
  • func WithLogger(logger *slog.Logger) EngineOption
  • func WithMiddleware(middleware func(HTTPClient) HTTPClient) EngineOption
• type HTTPClient
• type HTTPClientFunc
  • func (f HTTPClientFunc) Do(req *http.Request) (*http.Response, error)
• type HTTPError
  • func NewHTTPError(resp *http.Response, message string) *HTTPError
  • func (e *HTTPError) Error() string
• type HTTPRequester
• type HTTPResponser
• type Money
  • func (m *Money) Set(value float64)
  • func (m Money) Value() float64
• type OptionalDateTime
  • func (d OptionalDateTime) MarshalJSON() ([]byte, error)
  • func (d *OptionalDateTime) UnmarshalJSON(data []byte) error
• type Relationship
• type Session
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t Time) MarshalText() ([]byte, error)
  • func (t Time) String() string
  • func (t *Time) UnmarshalJSON(data []byte) error
  • func (t *Time) UnmarshalText(text []byte) error

Functions

func Execute

func Execute[R HTTPRequester, T HTTPResponser](ctx context.Context, engine *Engine, requester R) (T, error)

Execute sends an HTTP request using the provided requester and handles the response using the provided responser.

func Iterate

func Iterate[T HTTPRequester, R interface {
	HTTPResponser
	Iterate() *T
}](ctx context.Context, e *Engine, req T) (next func() (R, bool, error), err error)

Iterate allows scanning through paginated results from the Teamwork API.

func Ptr

func Ptr[T any](v T) *T

Ptr returns a pointer to the value v.

Types

type Date

type Date time.Time

Date is a type alias for time.Time, used to represent date values in the API.

func (Date) MarshalJSON

func (d Date) MarshalJSON() ([]byte, error)

MarshalJSON encodes the Date as a string in the format "2006-01-02".

func (Date) MarshalText

func (d Date) MarshalText() ([]byte, error)

MarshalText encodes the Date as a string in the format "2006-01-02".

func (Date) String

func (d Date) String() string

String returns the string representation of the Date in the format "2006-01-02".

func (*Date) UnmarshalJSON

func (d *Date) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a JSON string into a Date type.

func (*Date) UnmarshalText

func (d *Date) UnmarshalText(text []byte) error

UnmarshalText decodes a text string into a Date type. This is required when using Date type as a map key.

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine is the main structure that handles communication with the Teamwork API.

func NewEngine

func NewEngine(session Session, opts ...EngineOption) *Engine

NewEngine creates a new Engine instance with the provided HTTP client and session.

type EngineOption

type EngineOption func(*Engine)

EngineOption is a function that modifies the Engine configuration.

func WithHTTPClient

func WithHTTPClient(client HTTPClient) EngineOption

WithHTTPClient sets the HTTP client for the Engine. By default, it uses http.DefaultClient. When setting the HTTP client, any middlewares that were added using WithMiddleware before this call will be ignored.

func WithLogger

func WithLogger(logger *slog.Logger) EngineOption

WithLogger sets the logger for the Engine. By default, it uses slog.Default().

func WithMiddleware

func WithMiddleware(middleware func(HTTPClient) HTTPClient) EngineOption

WithMiddleware adds a middleware to the Engine. Middlewares are applied in the order they are added.

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is an interface that defines the methods required for an HTTP client. This allows for adding middlewares and easier testing.

type HTTPClientFunc

type HTTPClientFunc func(req *http.Request) (*http.Response, error)

HTTPClientFunc is a function type that implements the HTTPClient interface.

func (HTTPClientFunc) Do

func (f HTTPClientFunc) Do(req *http.Request) (*http.Response, error)

Do executes the HTTP request and returns the response.

type HTTPError

type HTTPError struct {
	StatusCode int
	Headers    http.Header
	Message    string
	Details    string
}

HTTPError represents an error response from the API.

func NewHTTPError

func NewHTTPError(resp *http.Response, message string) *HTTPError

NewHTTPError creates a new HTTPError from an http.Response.

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error implements the error interface.

type HTTPRequester

type HTTPRequester interface {
	HTTPRequest(ctx context.Context, server string) (*http.Request, error)
}

HTTPRequester knows how to create an HTTP request for a specific entity.

type HTTPResponser

type HTTPResponser interface {
	HandleHTTPResponse(*http.Response) error
}

HTTPResponser knows how to handle an HTTP response for a specific entity.

type Money

type Money int64

Money represents a monetary value in the API.

func (*Money) Set

func (m *Money) Set(value float64)

Set sets the value of Money from a float64.

func (Money) Value

func (m Money) Value() float64

Value returns the value of Money as a float64.

type OptionalDateTime

type OptionalDateTime time.Time

OptionalDateTime is a type alias for time.Time, used to represent date and time values in the API. The difference is that it will accept empty strings as valid values.

func (OptionalDateTime) MarshalJSON

func (d OptionalDateTime) MarshalJSON() ([]byte, error)

MarshalJSON encodes the OptionalDateTime as a string in the format "2006-01-02T15:04:05Z07:00".

func (*OptionalDateTime) UnmarshalJSON

func (d *OptionalDateTime) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a JSON string into an OptionalDateTime type.

type Relationship

type Relationship struct {
	ID   int64          `json:"id"`
	Type string         `json:"type"`
	Meta map[string]any `json:"meta,omitempty"`
}

Relationship describes the relation between the main entity and a sideload type.

type Session

type Session interface {
	Authenticate(context.Context, *http.Request) error
	Server() string
}

Session is an interface that defines the methods required for a session to authenticate requests to the Teamwork Engine.

type Time

type Time time.Time

Time is a type alias for time.Time, used to represent time values in the API.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON encodes the Time as a string in the format "15:04:05".

func (Time) MarshalText

func (t Time) MarshalText() ([]byte, error)

MarshalText encodes the Time as a string in the format "15:04:05".

func (Time) String

func (t Time) String() string

String returns the string representation of the Time in the format "15:04:05".

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a JSON string into a Date type.

func (*Time) UnmarshalText

func (t *Time) UnmarshalText(text []byte) error

UnmarshalText decodes a text string into a Time type. This is required when using Time type as a map key.