# jetstream

the Zig SDK for [Jetstream v2](https://bsky.network/docs/jetstream/): live
subscriptions, filtered archive replay, and replay-to-live cutover. follows
the official Go client's shape, with multi-host live failover. built on
[zat](https://tangled.org/zat.dev/zat) for AT Protocol support.

## install

requires Zig 0.17.0.

```sh
zig fetch --save https://tangled.org/zat.dev/jetstream/archive/v0.1.5.tar.gz
```

add the module to your executable in `build.zig`:

```zig
const jetstream = b.dependency("jetstream", .{}).module("jetstream");
exe.root_module.addImport("jetstream", jetstream);
```

see the [changelog](CHANGELOG.md) for release changes.

## use

subscribe to live posts without an API key:

```zig
const std = @import("std");
const jetstream = @import("jetstream");

const Handler = struct {
    pub fn onEvent(_: *@This(), event: jetstream.Event) bool {
        std.debug.print("{d} {s}\n", .{ event.seq, event.did });
        return true;
    }
};

pub fn main(init: std.process.Init) !void {
    var handler = Handler{};
    try jetstream.subscribe(init.io, init.gpa, .{
        .hosts = &.{"https://stream.waow.tech"},
        .collections = &.{"app.bsky.feed.post"},
        .kinds = &.{.commit},
    }, &handler);
}
```

provide multiple hosts for [live failover](docs/failover.md). use
`after_seq` for archive replay, or `live_cursor` to resume within live
retention; the [client contract](docs/client.md) covers cursor scope,
authentication, and error handling. return `false` from `onEvent` to stop.

## develop

```sh
zig build test --summary all
zig build
checks/run ci
```

the loopback checks require Go 1.27, Bash, and jq. they compare the local SDK
with the pinned official Go client and record bounded live/catch-up measurements.
see [verification and release gates](docs/verification.md).

## docs

[docs/](docs/) covers the client contract, failover, and upstream comparisons.
[examples/](examples/) contains bounded consumers and smoke programs.

## license

[MIT](LICENSE)