Quickstart

curl -s -X POST localhost:8080/v1/buckets/apps -d '{"create_stream_on_append":true}'
curl -s -X POST localhost:8080/v1/streams/apps/orders%2Feu -d '{"class":"standard"}'

# Append records (bodies are UTF-8; use body_b64 for binary).
curl -s localhost:8080/v1/streams/apps/orders%2Feu/records \
  -d '{"records":[{"body":"one"},{"body":"two"}]}'

# Read from the start; every response carries the tail position.
curl -s 'localhost:8080/v1/streams/apps/orders%2Feu/records?seq_num=0&limit=10'

# The last record by tail offset; or everything since a timestamp.
curl -s 'localhost:8080/v1/streams/apps/orders%2Feu/records?tail_offset=1'
curl -s 'localhost:8080/v1/streams/apps/orders%2Feu/records?timestamp_ms=0&limit=10'

# The committed tail — one past the last record.
curl -s localhost:8080/v1/streams/apps/orders%2Feu/records/tail

# Follow live as SSE; event ids are resume cursors for Last-Event-ID.
curl -N 'localhost:8080/v1/streams/apps/orders%2Feu/records/subscribe?seq_num=0'

# Conditional append: succeeds only if the next sequence number is exactly 2.
curl -s localhost:8080/v1/streams/apps/orders%2Feu/records \
  -d '{"records":[{"body":"three"}],"match_seq_num":2}'

# Drop history below 2 (logically instant; reclaimed in the background).
curl -s -X POST localhost:8080/v1/streams/apps/orders%2Feu/trim -d '{"seq_num":2}'

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/supabase/nova/client"
)

func main() {
	ctx := context.Background()

	c, err := client.New(client.Options{Addrs: []string{"localhost:7781"}})
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()

	addr := client.Address{Bucket: "demo", Key: "events"}

	// A producer owns an append session; batching is automatic.
	p, err := c.OpenStream(ctx, addr)
	if err != nil {
		log.Fatal(err)
	}

	res, err := p.Append(ctx, client.Bodies([]byte("first"), []byte("second"))...)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("appended", res.Start.SeqNum, "through", res.End.SeqNum-1, "tail", res.Tail.SeqNum)

	if err := p.Close(ctx); err != nil {
		log.Fatal(err)
	}

	// The committed tail, strongly consistent.
	tail, err := c.CheckTail(ctx, addr)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("tail", tail.SeqNum)

	// Ordered live tailing from the start; reconnects and resumes on its own.
	for records, err := range c.Subscribe(ctx, addr, 0) {
		if err != nil {
			log.Fatal(err)
		}
		for _, r := range records {
			fmt.Printf("%d\t%s\n", r.SeqNum, r.Body)
		}
	}
}

docker compose -f nova-compose.yml down -v