Skip to main content

Crate basecamp_sdk

Crate basecamp_sdk 

Source
Expand description

§basecamp-sdk

The Rust client for the Basecamp API, generated from the Smithy model in this repository’s spec/: every wire operation, every request and response shape, and every operation’s retry, idempotency and pagination behaviour come from openapi.json and behavior-model.json. The hand-written part is the plumbing they share — authentication, retries, pagination, the two-hop download, OAuth — and the SPEC §18 merge-safe composites.

Project detail includes the optional logo; see project logo upload, removal and authenticated download.

[dependencies]
basecamp-sdk = "0.18"
tokio = { version = "1", features = ["full"] }

§First call

use basecamp_sdk::{Client, Config};

#[tokio::main]
async fn main() -> Result<(), basecamp_sdk::Error> {
    let client = Client::builder(Config::default())
        .access_token(std::env::var("BASECAMP_TOKEN").expect("BASECAMP_TOKEN"))
        .build()?;
    let account =
        client.for_account(std::env::var("BASECAMP_ACCOUNT_ID").expect("BASECAMP_ACCOUNT_ID"));

    for project in account.projects().list(&Default::default()).await?.iter() {
        println!("{} ({})", project.name, project.id);
    }
    Ok(())
}

Services hang off an AccountClient: account.projects(), account.todos(), account.cards() and so on, one per Basecamp service. Every method maps to one operation of the model; the routes themselves are public data under routes.

§Pagination

A paginated read answers a Page: the first page’s items plus the cursor Basecamp handed out. Follow it a page at a time with AccountClient::next_page, or collect the whole collection with AccountClient::collect_all, which stops at the client’s page cap and says so in ListMeta::truncated. AccountClient::pages and AccountClient::items walk lazily as streams; the item stream ends with a usage error when the cap leaves a page unread. A read whose page is an envelope around the collection gathers the same way: its generated shape implements PageItems. A Link header pointing off the API origin is refused, never followed.

§Errors

Every call answers a Result<T, Error>. The error carries the SPEC §6 record: a code, the message and hint, the HTTP status, whether the call is retryable and the Retry-After the server named, the request id, and — on a 400/422 — the structured field_errors.

§Retries

Retries follow SPEC §7’s three gates: the HTTP method’s own idempotency, the model’s idempotent flag for a POST, and the operation’s declared retry_on statuses. Attempts are min(client cap, operation max); a Retry-After header is honoured at every retried status, and the local backoff is exponential with a 30 s ceiling and 100 ms of jitter. A 401 is replayed once after the token provider refreshes, spending an attempt.

§Bring your own HTTP client

The SDK sends on one HttpClient. The reqwest feature (on by default) ships one over rustls; with --no-default-features an application supplies its own.

§Features

FeatureDefaultWhat it adds
reqwestyesThe shipped HttpClient
rustls-tlsyesrustls for the shipped client
native-tlsnoThe platform TLS stack for the shipped client (additive)
oauthyesoauth: PKCE, device grant, token exchange and refresh
tracingyesOne tracing span per operation
event-feednoReserved for the SPEC §23 connector

§Environment variables

Only Config::from_env reads the environment; a Config built literally reads no variable at all.

VariableMeaningOnly when
BASECAMP_BASE_URLThe API origin (trailing / stripped)Config::from_env()
BASECAMP_TIMEOUTPer-attempt timeout, in secondsConfig::from_env()
BASECAMP_MAX_RETRIESTotal attempts per request, the first includedConfig::from_env()

BASECAMP_TOKEN and BASECAMP_ACCOUNT_ID appear in the examples only because the caller reads them; the SDK never looks either up.

§Examples

examples/ holds one compiled program per README section — first_call, pagination, errors and custom_http_client — and rs-test builds them all.

§Versioning

The crate follows the repository’s vX.Y.Z tags. Pre-1.0, a breaking change lands in a 0.MINOR release and an additive one in a 0.x.PATCH. The minimum supported Rust version is 1.88 and is enforced in CI; it moves only in a 0.MINOR release, never past the second-newest stable.

§Request construction policy

Request bodies, query-parameter structs and Config are plain pub structs with Default and no #[non_exhaustive], so they are built literally — CreateTodoRequestContent { content, ..Default::default() } — from any crate. A field the model adds to one of them is therefore a source break, accepted as a 0.MINOR release under the pre-1.0 policy. Response models and open enumerations (ErrorCode, the model’s own string enums) are #[non_exhaustive]: a field or variant the API grows is not a break. A shape that requests and responses share (QuestionSchedule) is a request shape, and stays literal-constructible. Types with private fields (Error, Client) need neither.

§Re-exported dependencies

chrono types are the model’s date and time representation and reqwest’s builder is the shipped transport’s seam, so both crates are re-exported here at the version this crate was built against: use basecamp_sdk::chrono and basecamp_sdk::reqwest rather than guessing the matching minor. A minor bump of either is a 0.MINOR release of this crate.

§Public traits

HttpClient, AuthStrategy, TokenProvider and Hooks are Send + Sync and object-safe; the SDK holds each as an Arc<dyn Trait>. A method added to one of them gets a default body, so implementing them stays source-compatible across 0.x.PATCH releases.

Re-exports§

pub use auth::AuthStrategy;
pub use auth::BearerAuth;
pub use auth::StaticTokenProvider;
pub use auth::TokenProvider;
pub use client::AccountClient;
pub use client::Client;
pub use client::ClientBuilder;
pub use client::Response;
pub use config::Config;
pub use download::DownloadResult;
pub use error::Error;
pub use error::ErrorCode;
pub use hooks::Hooks;
pub use http::HttpClient;
pub use mentions::mention_markup;
pub use mentions::mentioned_person_ids;
pub use mentions::person_id_from_sgid;
pub use mentions::with_mentions;
pub use oauth::DeviceAuthorization;oauth
pub use oauth::DeviceFlowError;oauth
pub use oauth::DeviceFlowReason;oauth
pub use oauth::DiscoveryOutcome;oauth
pub use oauth::ExchangeRequest;oauth
pub use oauth::FallbackReason;oauth
pub use oauth::OAuthClient;oauth
pub use oauth::Pkce;oauth
pub use oauth::ProtectedResourceMetadata;oauth
pub use oauth::RefreshRequest;oauth
pub use oauth::RefreshingTokenProvider;oauth
pub use oauth::SelectionError;oauth
pub use oauth::SelectionFailure;oauth
pub use oauth::ServerMetadata;oauth
pub use oauth::Token;oauth
pub use operation::Operation;
pub use pagination::ListMeta;
pub use pagination::ListResult;
pub use pagination::Page;
pub use pagination::PageItems;
pub use types::AuthRoutableUrl;
pub use types::Date;
pub use types::DateChange;
pub use types::DateTime;
pub use types::FlexibleTime;
pub use types::SensitiveString;
pub use version::API_VERSION;
pub use version::VERSION;
pub use chrono;
pub use reqwest;reqwest

Modules§

auth
SPEC §4: how credentials get onto a request, and how a refreshed token replaces a rejected one.
client
SPEC §3: the client, and the account-scoped client every service hangs off.
config
SPEC §2: what a client needs to know before it can talk to Basecamp.
download
SPEC §14: the two-hop download. An authenticated GET on the API origin answers a redirect to a signed storage URL, which is then fetched bare.
error
SPEC §6: the one error every call can answer with.
hooks
SPEC §12: what the SDK tells an application about the calls it makes.
http
The HTTP layer the client sends on, and the seam for replacing it.
mentions
Mention helpers over Basecamp rich text.
metadata
Per-operation behaviour from behavior-model.json, generated from the model.
models
The request and response types the Basecamp API speaks, generated from the model.
oauthoauth
SPEC §16: OAuth utilities — PKCE, resource-first discovery, the authorization-code exchange and refresh, and the RFC 8628 device grant.
operation
A request the client has not sent yet.
pagination
SPEC §8: Link-header pagination.
retry
SPEC §7: the three gates, the attempt budget and the backoff curve.
route
One API operation as data: its method, its path template and the behaviour the model attaches to it. Every route the SDK knows lives in crate::routes.
routes
Every modelled route as public data, generated from the model.
security
SPEC §9: HTTPS enforcement, origin comparison and redaction.
services
The SPEC §18 hand-written composites, built over the generated wire operations. Nothing here touches the wire on its own.
types
The scalar types the model’s shapes are built from.
url
Recognizes Basecamp paths and URLs, as pasted from the web app or the API, and names the operations they refer to. Works offline, from the route table alone.
version
The SDK’s own version and the API contract it was generated against.
webhooks
SPEC §15: verifying a webhook delivery’s signature.

Constants§

OPERATION_COUNT
How many operations the model declares.