shortcut_sdk - Shortcut REST API v3 client
==========================================
shortcut_sdk is a minimal Rust library distributed as a single source file
(`shortcut_sdk.rs`). It wraps the Shortcut REST API v3 with typed
request and response structs and a thin `Client` over HTTP.
Requirements
------------
rustc with the 2024 edition, plus libtls and libcrypto for the vendored
http crate. No cargo, no procedural macros, no async runtime.
Building
--------
Build the rlib:
make
Run the unit tests:
make test
Generate browsable rustdoc under `build/doc/shortcut_sdk/index.html`:
make doc
Format and lint everything (used in CI):
make ci
Vendoring into your project
---------------------------
shortcut_sdk depends on two vendored single-file crates: `http` and
`jackson` (both shipped under `vendor/`). Copy `shortcut_sdk.rs` and
the contents of `vendor/` into your project, then build them as rlibs
and link your binary against all three:
rustc --edition 2024 --crate-type rlib --crate-name http \
-o build/libhttp.rlib vendor/http.rs
rustc --edition 2024 --crate-type rlib --crate-name jackson \
-o build/libjackson.rlib vendor/jackson.rs
SHORTCUT_SDK_VERSION=0.1.0 \
rustc --edition 2024 --crate-type rlib --crate-name shortcut_sdk \
--extern http=build/libhttp.rlib \
--extern jackson=build/libjackson.rlib \
-C link-arg=-ltls -C link-arg=-lcrypto \
-o build/libshortcut_sdk.rlib shortcut_sdk.rs
Your binary then links against shortcut_sdk:
rustc --edition 2024 --crate-type bin \
--extern shortcut_sdk=build/libshortcut_sdk.rlib \
--extern http=build/libhttp.rlib \
--extern jackson=build/libjackson.rlib \
-L build -C link-arg=-ltls -C link-arg=-lcrypto \
-o build/myapp main.rs
The Makefile in this repository follows the same pattern; reading it is
the shortest path to wiring up your own.
Quick tour
----------
Authenticate with a Shortcut API token (set the `SHORTCUT_TOKEN`
environment variable in production code):
use shortcut_sdk::{Client, CreateStoryParams, SearchQuery};
let c = Client::new(std::env::var("SHORTCUT_TOKEN")?);
Read a story, list stories from a group, search across the workspace:
let s = c.get_story(1234)?;
let inbox = c.list_group_stories("uuid-platform", Some(50), None)?;
let hits = c.search_stories(
&SearchQuery::new("owner:ijanc state:in-progress").page_size(25),
)?;
Create a story with the fluent params builder (optional fields stay
unset and are not sent on the wire):
let s = c.create_story(
&CreateStoryParams::default()
.name("Write SDK docs")
.workflow_state_id(500_000_123)
.owner_ids(vec!["uuid-1".into()]),
)?;
Upload a PRD as an attachment to a story:
use shortcut_sdk::FileUpload;
c.upload_files(
&[FileUpload::new("PRD.pdf", "application/pdf")],
Some(s.id),
)?;
Download
--------
got clone ssh://ijanc@ijanc.org/shortcut_sdk
git clone https://git.ijanc.org/shortcut_sdk.git
git clone https://git.sr.ht/~ijanc/shortcut_sdk
git clone https://github.com/shortcut_sdk.git
License
-------
ISC -- see LICENSE.
