bookstack-api/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Go library for the Bookstack REST API. Primary consumers are AI agents via CLI (with --json flag) and Go developers needing programmatic Bookstack access.

Build & Test Commands

# Build
go build ./...

# Run all tests
go test ./...

# Run single test
go test -run TestName ./...

# Run tests with coverage
go test -cover ./...

# Lint (if golangci-lint is installed)
golangci-lint run

# Format code
gofmt -w .

Architecture

Flat Package Structure

All code lives in the root package bookstack. No subpackages.

bookstack.go       # Client, Config, NewClient()
books.go           # BooksService
pages.go           # PagesService
chapters.go        # ChaptersService
shelves.go         # ShelvesService
search.go          # SearchService
types.go           # All data structures (Book, Page, Chapter, Shelf, SearchResult)
errors.go          # Error types (ErrNotFound, ErrUnauthorized, APIError, etc.)
http.go            # HTTP helpers, request building
iterator.go        # Pagination iterator using Go 1.23+ iter.Seq

Client Pattern

Services are attached to the main Client struct:

client := bookstack.NewClient(bookstack.Config{
    BaseURL:     "https://docs.example.com",
    TokenID:     os.Getenv("BOOKSTACK_TOKEN_ID"),
    TokenSecret: os.Getenv("BOOKSTACK_TOKEN_SECRET"),
})

// Access services via client
books, err := client.Books.List(ctx, nil)
page, err := client.Pages.Get(ctx, 123)

Pagination via Iterators

Use Go 1.23+ iterator pattern for list operations:

for book, err := range client.Books.ListAll(ctx) {
    if err != nil {
        return err
    }
    // process book
}

Error Handling

Use sentinel errors with errors.Is():

if errors.Is(err, bookstack.ErrNotFound) {
    // handle 404
}

APIError provides detailed information when needed.

Key Design Decisions

• Zero external dependencies - Only Go standard library
• Go 1.21+ required
• No caching/rate-limiting - Caller responsibility
• Token auth via Authorization: Token <id>:<secret> header
• Bookstack hierarchy: Shelf → Book → Chapter → Page

Bookstack API Reference

• Rate limit: 180 req/min (server configurable)
• Pagination: count (max 500), offset, sort, filter[field]