- Rust 98.2%
- Python 1.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
- tec-client: async client for tribe/events/v1 (events, venues, organizers, categories, tags) and the experimental tec/v1 (events, venues, organizers), read and write. - Strongly typed models: id newtypes, jiff date-times, Url/WebLink/Html, password-protected entities as a separate variant, lenient decoding of PHP-isms (string ids, false-as-null, [] maps). - Calendar-aligned date windows (today/week/month/year/all), parallel in-order pagination with retries and de-duplication. - TLS via rustls with OS trust store or bundled Mozilla roots (features). - Series linking (permalink slug, parent post, implied series) and RRULE inference with EXDATE/RDATE and confidence. - tec-crawl: CLI emitting compact, full or per-series JSON lines. - Tests against the plugin's own response snapshots, wiremock, and real iondistrict.com series data. |
||
| crates | ||
| docs | ||
| tools | ||
| .gitignore | ||
| Cargo.toml | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
wp-events
A Rust client for the REST APIs of The Events Calendar (TEC), the WordPress events plugin.
| Crate | What it is |
|---|---|
crates/tec-client |
Async library: typed models, every endpoint, parallel crawling, TLS choice |
crates/tec-crawl |
CLI built on the library: crawls a site and prints JSON lines |
Install
[dependencies]
tec-client = "1"
cargo install tec-crawl
The wire-level API specifications this client was built from (derived from the plugin source,
TEC 6.18.3.1) are in docs/: spec_tribe_v1.md and
spec_tec_v1.md.
APIs covered
tribe/events/v1 (legacy) — client.tribe() |
tec/v1 (new) — client.tec() |
|
|---|---|---|
| Availability | Every TEC site (unless disabled) | TEC 6.15+, marked experimental |
| Events | list, get, get by slug, create, update, delete, crawl | list, get, create, update (PATCH), delete (trash/force), crawl |
| Venues / organizers | list, get, get by slug, create, update, delete, crawl | list, get, create, update, delete, crawl |
| Categories / tags | list, get, create, update, delete, crawl | — |
| Docs | doc() |
docs() |
| Recurring events (Pro) | one item per occurrence, each with its own id | occurrences share the parent's id, and date filters are checked against the series' first occurrence (see below) |
Use the legacy API for crawling calendars. It is on every site and it lists every occurrence of a recurring event.
tec/v1 and recurring events
Verified on iondistrict.com (TEC 6.18 with Events Calendar Pro), using series 60334, which runs monthly from 2026-07-09 to 2027-04-08:
tec/v1 query |
Rows returned |
|---|---|
| no date filter | 10 occurrences, all with id: 60334 |
| a July 2026 window | all 10, including ones in 2027 |
| a November 2026 window | 0, though Nov 12 is an occurrence |
The server checks the window against the parent post's stored dates, which belong to the first
occurrence. If those match, it returns every occurrence; if not, it returns none.
GET /tec/v1/events/{occurrence id} returns 404.
How the client handles this:
- De-duplication uses
(id, start)(Protectable::key), so occurrences are not merged. - Windowed crawls drop occurrences that fall outside the window.
- Series the server dropped cannot be recovered. Use the legacy API when completeness matters.
Quick start
use futures::TryStreamExt;
use tec_client::{Bound, Client, CrawlOptions, DateRange, TlsRoots};
use tec_client::jiff::tz::TimeZone;
let client = Client::builder("https://example.org")?
.tls_roots(TlsRoots::System) // or TlsRoots::Bundled
.discover().await?; // finds /wp-json/ or ?rest_route= via the Link header
let range = DateRange::new(Bound::Week, Bound::Month)
.time_zone(TimeZone::get("America/New_York")?);
let mut events = client.tribe().events()
.crawl(&range, Default::default(), CrawlOptions { concurrency: 4, ..Default::default() })?;
while let Some(e) = events.try_next().await? {
println!("{} {:?} {}", e.id, e.start_date, e.title);
}
CLI:
cargo run -p tec-crawl -- --site https://demo.theeventscalendar.com --start week --end month --tz America/Detroit
cargo run -p tec-crawl -- --site https://example.org --resource venues
cargo run -p tec-crawl -- --site https://example.org --api tec --start all --end all --tls bundled
TEC_USER=me TEC_APP_PASSWORD='xxxx xxxx' cargo run -p tec-crawl -- --site https://example.org # include drafts
Events are printed in compact form by default (tec_client::EventSummary): id, series_id
(tec/v1 recurring only), decoded title, zoned start/end (e.g. 2026-11-03T16:00:00-06:00),
all_day, timezone, url, cost, venue (name/address/city/region/postal_code/country),
organizers, categories, tags, image, status. --format full prints every field. --format series prints one record per series (see below).
Password-protected tec/v1 events are skipped in compact form.
Date windows
Bound values: today, week, month, year, all, YYYY-MM-DD, or an RFC 3339 timestamp.
Windows line up with the calendar in the zone you choose; the default zone is the system one, and the
site's own zone is usually the better choice.
| keyword | as start |
as end (exclusive) |
|---|---|---|
today |
today 00:00 | tomorrow 00:00 |
week |
first day of this week (Monday by default, configurable) | first day of next week |
month |
1st of this month | 1st of next month |
year |
Jan 1 | Jan 1 next year |
all |
unbounded | unbounded |
| a date | that day 00:00 | the following day 00:00, so the date itself is included |
RangeMode::StartsWithin (the default) matches events that start inside the window.
RangeMode::Overlaps also matches events that began earlier and are still running.
How the window is sent to each API:
- Legacy: the client turns on
strict_datesand sends exact zoned bounds. This also switches off the server's hidden default window (yesterday to +24 months), which otherwise hides past events. - tec/v1: the bounds are sent directly; this API has no default window.
Parallel fetching
CrawlOptions { per_page, concurrency, max_pages, dedupe }
- Page 1 is fetched first to learn the total page count. Pages 2..N are then fetched with up to
concurrencyrequests at once. - Results come out in page order.
- If a later page returns "page not found" (the data shrank mid-crawl), the stream ends cleanly.
dedupe(on by default) drops items repeated across page boundaries when events are published during a crawl.
GET requests are retried on 429, 502, 503, 504 and on connection errors, with exponential backoff
that honours Retry-After (see RetryPolicy).
A live check against demo.theeventscalendar.com crawled 28 of 28 events with concurrency 6.
TLS
The client uses rustls with the ring crypto backend; there is no OpenSSL dependency. Roots are
chosen at runtime with TlsRoots, and each root source is behind a cargo feature (both are on by
default):
TlsRoots |
Feature | Use when |
|---|---|---|
System (default) |
system-roots |
You want the OS trust store: corporate CAs, OS updates (rustls-platform-verifier) |
Bundled |
bundled-roots |
FROM scratch / distroless images with no CA bundle (Mozilla roots via webpki-roots) |
Custom(certs) / TlsRoots::custom_pem(..) |
always available | A private CA or pinned roots |
To ship only one source, depend with default-features = false, features = ["bundled-roots"].
ClientBuilder::http_client(reqwest::Client) accepts a fully custom client instead.
Authentication
Reading published content needs no authentication. For writes, drafts and private items, use
Auth::ApplicationPassword (WordPress 5.6+, over HTTPS), Auth::Bearer (JWT/OAuth plugins) or
Auth::CookieNonce.
Series and recurrence
Linking occurrences to series. Both APIs encode series membership in the permalink:
/event/{series-slug}/{date}/ for occurrences of an Events Calendar Pro recurring series, and
/event/{slug}/ for one-off events.
- Any event:
event.permalink()?.series()returns the series slug (SeriesSlug). - Legacy API, occurrence to series:
events().series_parent(&slug)returns the parent post (by-slug lookup). - Legacy API, series to occurrences:
events().series_occurrences(parent_id, opts)returns every occurrence, usinginclude=<parent>. - tec/v1: each row already carries the parent (
post.id,Event::series_parent()) and the occurrence (occurrence_id). SeriesIndex::build(&events, &GroupOptions)groups any set of events.series_of(id)maps an occurrence id to its series.- Repeating one-off posts: with
implied: true(the default), these are grouped too, when they share the same title, venue, organizers and start time. Much of iondistrict's programming is entered this way: 105 such groups, versus 38 Pro series.
Inferring the RRULE. Neither API exposes the rule an editor configured.
Series::infer_recurrence() recovers the simplest rule that explains the observed dates:
- the frequencies tried are DAILY, WEEKLY (interval 1–4), MONTHLY by day of month, MONTHLY by
nth or last weekday (
2TH,-1FR), and YEARLY; EXDATEs cover skipped dates (holidays) andRDATEs cover extra ones;- each result has a
ConfidenceofExact,WithExceptionsorWeak(fewer than 4 occurrences); InferredRecurrence::to_ical()writes theDTSTART/DURATION/RRULE/EXDATElines.
On iondistrict.com the inference agrees exactly with an independent python-dateutil
implementation (tools/infer_rrule.py) for all 38 Pro series. This is enforced by a test against
the real data. Limits:
UNTILis the last occurrence seen, because Pro only generates occurrences a limited time ahead.- Hidden events look like EXDATEs.
- With only 2 occurrences no rule is inferred. Houston Open Source Society, for example, needs its organizer's "third Wednesday" to be known.
cargo run -p tec-crawl -- --site https://iondistrict.com --start all --end all --tz America/Chicago --format series
cargo run -p tec-client --example series -- https://iondistrict.com 10004983
Typing decisions
The goal is strong types that still decode real responses:
- URLs generated by the server (permalinks, REST URLs, images, terms, directions) are
url::Url. Links typed in by editors (website,virtual_url) areWebLink, which keeps the text verbatim when it isn't a valid URL. - Rendered text (titles, descriptions, excerpts, schedule details, cost, venue and organizer
names) is
Html..to_text()strips tags and decodes entities. - Time zones are
WpTimeZone, and.to_time_zone()handles IANA names andUTC+5.5. Durations arejiff::SignedDuration, and PHP timezone kinds arePhpTimezoneType. - Ids are newtypes (
EventId,VenueId,OrganizerId,TermId,UserId,AttachmentId). They accept both12and"12". - Dates are
jiffvalues.0000-00-00 00:00:00,falseand""becomeNone.- Events have helpers:
start_instant(),start_zoned(), andtime_zone(), which handles WordPressUTC+5.5pseudo-zones.
- Open sets are enums with an
Other(String)fallback:PostStatus,Taxonomy,PostType,CurrencyPosition,EventOrderBy, … - Polymorphic fields are normalised:
- legacy
venue([], one object, or a list) becomesvenues: Vec<Venue>; image: falsebecomesNone;custom_fields: []becomes an empty map;ticketed(bool or a provider list) becomes theTicketedenum;- tec
multiday(falseor a day count) becomesOption<u32>; - tec
duration(a numeric string) becomesOption<u64>.
- legacy
- Password-protected posts:
- tec/v1 entities are
Protectable<T>:Visible(T), orPasswordProtected(stub). This is needed because the server rewrites every field of a protected post. - Legacy events report
is_password_blanked(), and their boolean fields areOption<bool>.
- tec/v1 entities are
- Write bodies encode what is required:
NewEvent::new(title, start, end)requires the mandatory fields; update structs make every field optional.- Inline venue and organizer creation use
VenueRefandOrganizerRef.
- Unknown response keys are kept in an
extramap rather than rejected.
Server quirks the client handles
- Booleans are sent as
1/0: tec/v1 casts"false"to true.DELETE ?force=falsewould permanently delete, so the client sendsforcein a JSON body instead. - Lists are sent as
x[]=(tec/v1) or as comma-separated values (legacy). Empty parameters are never sent; the legacy API returns 400 for them. - tec/v1 requires the
X-TEC-EEAacknowledgement header on every call. The client sends it. - Pages past the end return a 404, and its code differs per endpoint. The paginator treats it as end of data.
- On password-protected organizers and venues, the server blanks the name field to
[]. The client treats this asNone.
Server quirks you should know about (documented on the types)
- Legacy updates are not partial. Omitting a field resets
all_day,show_map,show_map_link,sticky,featuredandhide_from_listingsto false, deletes the featured image, and publishes drafts. SeeEventUpdate. - tec/v1 updates also reset fields. When omitted,
comment_statusandping_statusare set toopenandstickytofalse. Separately,title,contentandexcerpthave their HTML stripped on write. - Some tec/v1 event filters do nothing.
categoriesandtagsare accepted but ignored in TEC ≤ 6.18. - Missing ids in tec/v1 return 401/403, not 404.
- Hidden events ("hide from listings") never appear in legacy
/events.
Tests
cargo test # 40 tests
- Unit tests: date ranges, query encoding, request bodies, pagination order and dedupe.
- Fixture tests: every response snapshot from the plugin's own test suite (both APIs, including password-protected cases), plus one live response from the demo site, and the series and RRULE inference against all recurring series on iondistrict.com.
- Mock-server tests (wiremock): a multi-page crawl, page-not-found ending a crawl, typed errors, retries, the tec/v1 header and pagination headers, the DELETE body, and REST-root discovery for plain permalinks.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
The test fixtures under crates/tec-client/tests/fixtures/ include response snapshots from The
Events Calendar's test suite (GPL-2.0-or-later) and public event data captured from
demo.theeventscalendar.com and iondistrict.com. They are used for testing only and are not
included in the published crates.
Suggested next steps
- A preserving
patch()for legacy updates. It would fetch the event, merge in your changes, and send the full state, avoiding the reset-on-omit behaviour above. Titles come back HTML-entity-encoded, so this needs an entity decoder (for examplehtml-escape). - Incremental sync. Neither API filters by
modified. Crawl the whole window and diff on(id, modified_utc), or storeglobal_idfor cross-site identity. - schema.org output. Legacy single-event GETs include
json_ld(anEventwithPlaceandOffers). Ato_schema_org()helper could build the same from archive items, which don't include it. - Site time zone. No public endpoint exposes it (
/wp/v2/settingsrequires auth). Pass the zone with--tz, or infer it fromdates.start_sitein tec/v1 responses. - Rate limiting. Add a per-host token bucket if you crawl many sites concurrently.