https://github.com/basecamp/basecamp-sdk

Basecamp software dev kit
https://github.com/basecamp/basecamp-sdk

basecamp

Last synced: 3 months ago
JSON representation

Basecamp software dev kit

Host: GitHub
URL: https://github.com/basecamp/basecamp-sdk
Owner: basecamp
License: mit
Created: 2026-01-25T20:54:57.000Z (5 months ago)
Default Branch: main
Last Pushed: 2026-03-26T04:51:09.000Z (3 months ago)
Last Synced: 2026-03-26T20:41:43.590Z (3 months ago)
Topics: basecamp
Language: Go
Homepage: https://basecamp.com/sdk
Size: 3.72 MB
Stars: 14
Watchers: 1
Forks: 2
Open Issues: 2
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Agents: AGENTS.md

Awesome Lists containing this project

README

          #  Basecamp SDK

Official [Basecamp](https://basecamp.com) [API](https://github.com/basecamp/bc3-api) clients, runtimes, and software development kits for Go, Ruby, TypeScript, Swift, Kotlin, and Python.

OpenAPI 3.1 spec included.

## Languages

| Language | Path | Status | Package |

|----------|------|--------|---------|

| [Go](go/) | `go/` | Active | `github.com/basecamp/basecamp-sdk/go` |

| [Ruby](ruby/) | `ruby/` | Active | `basecamp-sdk` |

| [TypeScript](typescript/) | `typescript/` | Active | `@37signals/basecamp` |

| [Swift](swift/) | `swift/` | Active | `Basecamp` (SPM) |

| [Kotlin](kotlin/) | `kotlin/` | Active | `com.basecamp:basecamp-sdk` (GitHub Packages) |

| [Python](python/) | `python/` | Active | `basecamp-sdk` (PyPI) |

| Feature | Go | TypeScript | Ruby | Swift | Kotlin | Python |

|---------|:--:|:----------:|:----:|:-----:|:------:|:------:|

| OAuth 2.0 Authentication | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ |

| Static Token Authentication | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

| ETag HTTP Caching (opt-in) | ✓ | ✓ | via Faraday† | ✓ | ✓ | ✗ |

| Automatic Retry with Backoff | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

| Pagination Handling | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

| Observability Hooks | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

| Structured Errors | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

| Webhook Verification | ✓ | ✓ | ✓ | ✗ | ✓ | ✓ |

† Ruby SDK uses Faraday - add caching via [faraday-http-cache](https://github.com/sourcelevel/faraday-http-cache)

**Note:** HTTP caching is disabled by default. Enable explicitly via configuration:

- **Go:** `cfg.CacheEnabled = true` or `BASECAMP_CACHE_ENABLED=true`

- **TypeScript:** `enableCache: true` in client options

- **Swift:** `BasecampConfig(enableCache: true)`

- **Kotlin:** `enableCache = true` in builder DSL

All SDKs are generated from a single [Smithy](https://smithy.io/) specification, ensuring consistent behavior and API coverage across languages.

## Quick Start

### Go

```go

package main

import (

    "context"

    "fmt"

    "os"

    "github.com/basecamp/basecamp-sdk/go/pkg/basecamp"

)

func main() {

    cfg := basecamp.DefaultConfig()

    token := &basecamp.StaticTokenProvider{Token: os.Getenv("BASECAMP_TOKEN")}

    client := basecamp.NewClient(cfg, token)

    account := client.ForAccount(os.Getenv("BASECAMP_ACCOUNT_ID"))

    result, err := account.Projects().List(context.Background(), nil)

    if err != nil {

        fmt.Fprintf(os.Stderr, "Error: %v\n", err)

        os.Exit(1)

    }

    for _, p := range result.Projects {

        fmt.Printf("%d: %s\n", p.ID, p.Name)

    }

}

```

### Ruby

```ruby

require "basecamp"

client = Basecamp.client(access_token: ENV["BASECAMP_TOKEN"])

account = client.for_account(ENV["BASECAMP_ACCOUNT_ID"])

account.projects.list.each do |project|

  puts "#{project['id']}: #{project['name']}"

end

```

### TypeScript

```typescript

import { createBasecampClient } from "@37signals/basecamp";

const client = createBasecampClient({

  accountId: process.env.BASECAMP_ACCOUNT_ID!,

  accessToken: process.env.BASECAMP_TOKEN!,

});

const projects = await client.projects.list();

projects.forEach(p => console.log(`${p.id}: ${p.name}`));

```

### Swift

```swift

import Basecamp

let client = BasecampClient(

    accessToken: ProcessInfo.processInfo.environment["BASECAMP_TOKEN"]!,

    userAgent: "my-app/1.0 (you@example.com)"

)

let account = client.forAccount(ProcessInfo.processInfo.environment["BASECAMP_ACCOUNT_ID"]!)

let projects = try await account.projects.list()

for project in projects {

    print("\(project.id): \(project.name)")

}

```

### Kotlin

```kotlin

val client = BasecampClient {

    accessToken(System.getenv("BASECAMP_TOKEN"))

    userAgent = "my-app/1.0 (you@example.com)"

}

val account = client.forAccount(System.getenv("BASECAMP_ACCOUNT_ID"))

val projects = account.projects.list()

projects.forEach { println("${it.id}: ${it.name}") }

```

### Python

```python

import os

from basecamp import Client

client = Client(access_token=os.environ["BASECAMP_TOKEN"])

account = client.for_account(os.environ["BASECAMP_ACCOUNT_ID"])

projects = account.projects.list()

for project in projects:

    print(f"{project['id']}: {project['name']}")

```

## Features

All SDKs provide:

- **Full API coverage** - 35+ services covering projects, todos, messages, schedules, campfires, card tables, and more

- **OAuth 2.0 authentication** - Token refresh, PKCE support (Go, TypeScript, Ruby, Kotlin, Python), and static token options

- **Automatic retry** - Exponential backoff with jitter, respects `Retry-After` headers

- **Pagination** - Link header–based pagination support (high-level handling may vary by SDK; see language docs)

- **ETag caching** - Built-in HTTP caching for efficient API usage (Go, TypeScript, Ruby†, Swift, Kotlin)

- **Structured errors** - Typed errors with helpful hints and CLI-friendly exit codes

- **Observability hooks** - Integration points for logging, metrics, and tracing

## API Coverage

| Category | Services |

|----------|----------|

| **Projects** | Projects, Templates, Tools, People |

| **To-dos** | Todos, Todolists, Todosets, TodolistGroups |

| **Messages** | Messages, MessageBoards, MessageTypes, Comments |

| **Chat** | Campfires (lines, chatbots) |

| **Scheduling** | Schedules, Timeline, Lineup, Checkins |

| **Files** | Vaults, Documents, Uploads, Attachments |

| **Card Tables** | CardTables, Cards, CardColumns, CardSteps |

| **Client Portal** | ClientApprovals, ClientCorrespondences, ClientReplies |

| **Automation** | Webhooks, Subscriptions, Events |

| **Reporting** | Search, Reports, Timesheets, Recordings |

## Specification

The [`spec/`](spec/) directory contains the API specification in [Smithy IDL](https://smithy.io/) format. This specification drives:

- OpenAPI generation for client codegen

- Type definitions across all SDKs

- Consistent behavior modeling (pagination, retries, idempotency)

See the [spec README](spec/README.md) for details on the model structure.

## Documentation

- [Go SDK documentation](go/README.md) - Full API reference with examples

- [Ruby SDK documentation](ruby/README.md) - Gem usage and configuration

- [TypeScript SDK documentation](typescript/README.md) - npm package usage

- [Swift SDK documentation](swift/README.md) - SPM package with async/await

- [Kotlin SDK documentation](kotlin/README.md) - Gradle package with coroutines

- [Python SDK documentation](python/README.md) - PyPI package with sync and async support

- [Contributing guide](CONTRIBUTING.md) - Development setup and guidelines

- [Security policy](SECURITY.md) - Reporting vulnerabilities

## Environment Variables

All SDKs support common environment variables:

| Variable | Description |

|----------|-------------|

| `BASECAMP_TOKEN` | OAuth access token |

| `BASECAMP_ACCOUNT_ID` | Basecamp account ID |

| `BASECAMP_BASE_URL` | API base URL (default: `https://3.basecampapi.com`) |

See individual SDK documentation for language-specific options.

## License

MIT

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/basecamp/basecamp-sdk

Awesome Lists containing this project

README