xurl/
lib.rs

1//! xurl — fast Rust client for the X (Twitter) API.
2//!
3//! Ships two consumable surfaces:
4//!
5//! - The `xr` binary, a high-level CLI for the X API.
6//! - The `xurl` library exposed via the modules below. Downstream Rust
7//!   consumers build requests via [`api::ApiClient`], drive output through
8//!   [`output::OutputConfig`], pattern-match on [`error::XurlError`], and
9//!   persist auth state in [`store::TokenStore`].
10//!
11//! Four authentication paths are supported, selected per request from the
12//! token store and environment:
13//!
14//! - **OAuth2 PKCE** (browser-driven or headless copy-paste) — every v2
15//!   user-scoped endpoint.
16//! - **OAuth1 HMAC-SHA1** — legacy v1.1 endpoints and some v2 write paths.
17//! - **Bearer (app-only)** — v2 read-only endpoints and search; set via
18//!   `XURL_BEARER_TOKEN`.
19
20// `XurlError`'s largest variant (`AuthMethodMismatch`) carries multiple
21// `String` and `Vec<String>` fields so agents can pattern-match on the
22// envelope structure. Boxing the variant would change the public
23// construction surface and break consumer code; allow the lint instead.
24#![allow(clippy::result_large_err)]
25#![deny(missing_docs)]
26
27pub mod api;
28pub mod auth;
29pub mod cli;
30pub mod config;
31pub mod envelope;
32pub mod error;
33pub mod output;
34pub mod skill_install;
35pub mod store;
36
37// ── Compile-time build and provenance metadata ──────────────────────────
38//
39// API spec consts are read from a checked-in sidecar at
40// `vendor/spec-metadata.json` rather than derived from git context, so
41// the values always describe the actual bytes that ship — uncommitted
42// local refreshes, crates.io tarball installs, and downstream git-pin
43// consumers all see identity that matches the bundled spec.
44//
45// `CRATE_GIT_SHA` is the only field that depends on git context; it
46// resolves to `None` on crates.io tarball builds where `.git` is not
47// present and `Some` on local development and CI builds.
48
49/// Version of this crate, from `[package].version` in `Cargo.toml`.
50pub const CRATE_VERSION: &str = env!("CARGO_PKG_VERSION");
51
52/// Git commit SHA the crate was built from. `None` when the build had
53/// no git context (e.g., `cargo install` from a crates.io tarball,
54/// where `.git` is not present).
55pub const CRATE_GIT_SHA: Option<&'static str> = option_env!("XURL_CRATE_GIT_SHA");
56
57/// X API OpenAPI spec version (`info.version` field) of the vendored
58/// `vendor/x-api-openapi.json` at build time, read from the
59/// `vendor/spec-metadata.json` sidecar. X bumps spec content without
60/// bumping this field; pair with [`API_SPEC_SHA256`] when drift detection
61/// matters.
62pub const API_SPEC_VERSION: &str = env!("XURL_API_SPEC_VERSION");
63
64/// SHA-256 of `vendor/x-api-openapi.json` at the time of its most recent
65/// vendoring, read from `vendor/spec-metadata.json`. Drift-sensitive
66/// identifier — changes every time X changes spec content, regardless of
67/// [`API_SPEC_VERSION`].
68pub const API_SPEC_SHA256: &str = env!("XURL_API_SPEC_SHA256");
69
70/// Date (UTC, `YYYY-MM-DD`) the vendored OpenAPI spec was last refreshed
71/// by `scripts/refresh-x-openapi.sh`, read from `vendor/spec-metadata.json`.
72pub const API_SPEC_DATE: &str = env!("XURL_API_SPEC_DATE");
xurl/lib.rs

xurl/
lib.rs
