bookstack-api/README.md

# bookstack-api

[![Mirror on GitHub](https://img.shields.io/badge/mirror-GitHub-blue)](https://github.com/jakoubek/bookstack-api)
[![Go Reference](https://pkg.go.dev/badge/code.beautifulmachines.dev/jakoubek/bookstack-api.svg)](https://pkg.go.dev/code.beautifulmachines.dev/jakoubek/bookstack-api)
[![Go Report Card](https://goreportcard.com/badge/code.beautifulmachines.dev/jakoubek/bookstack-api)](https://goreportcard.com/report/code.beautifulmachines.dev/jakoubek/bookstack-api)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A Go client library for the [BookStack](https://www.bookstackapp.com/) REST API. Zero external dependencies.

## Installation

```bash
go get code.beautifulmachines.dev/jakoubek/bookstack-api
```

## Quick Start

```go
package main

import (
    "context"
    "fmt"
    "log"

    bookstack "code.beautifulmachines.dev/jakoubek/bookstack-api"
)

func main() {
    client, err := bookstack.NewClient(bookstack.Config{
        BaseURL:     "https://docs.example.com",
        TokenID:     os.Getenv("BOOKSTACK_TOKEN_ID"),
        TokenSecret: os.Getenv("BOOKSTACK_TOKEN_SECRET"),
    })
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // List all books
    books, err := client.Books.List(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    for _, book := range books {
        fmt.Printf("%d: %s\n", book.ID, book.Name)
    }
}
```

## Authentication

BookStack uses token-based authentication. Create an API token in your BookStack user profile under **API Tokens**.

Set the token ID and secret as environment variables:

```bash
export BOOKSTACK_TOKEN_ID="your-token-id"
export BOOKSTACK_TOKEN_SECRET="your-token-secret"
```

## Usage

### Search

```go
results, err := client.Search.Search(ctx, "deployment guide", nil)
for _, r := range results {
    fmt.Printf("[%s] %s (score: %.1f)\n", r.Type, r.Name, r.Score)
}
```

### Get a Page

```go
page, err := client.Pages.Get(ctx, 42)
fmt.Println(page.HTML)
```

### Export Page as Markdown

```go
md, err := client.Pages.ExportMarkdown(ctx, 42)
fmt.Println(string(md))
```

### Iterate All Books

Uses Go 1.23+ iterators for memory-efficient pagination:

```go
for book, err := range client.Books.ListAll(ctx) {
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(book.Name)
}
```

### Pagination and Filtering

```go
pages, err := client.Pages.List(ctx, &bookstack.ListOptions{
    Count:  10,
    Offset: 0,
    Sort:   "-updated_at",
    Filter: map[string]string{"book_id": "1"},
})
```

### Create and Update Pages

```go
page, err := client.Pages.Create(ctx, &bookstack.PageCreateRequest{
    BookID:   1,
    Name:     "New Page",
    Markdown: "# Hello\n\nPage content here.",
})

page, err = client.Pages.Update(ctx, page.ID, &bookstack.PageUpdateRequest{
    Markdown: "# Updated\n\nNew content.",
})
```

### Error Handling

```go
page, err := client.Pages.Get(ctx, 999)
if errors.Is(err, bookstack.ErrNotFound) {
    fmt.Println("Page not found")
} else if errors.Is(err, bookstack.ErrUnauthorized) {
    fmt.Println("Invalid credentials")
}
```

## Available Services

| Service | Operations |
|---------|-----------|
| `Books` | List, ListAll, Get |
| `Pages` | List, ListAll, Get, Create, Update, Delete, ExportMarkdown, ExportPDF |
| `Chapters` | List, ListAll, Get |
| `Shelves` | List, ListAll, Get |
| `Search` | Search |
| `Attachments` | List, Get, Create, Update, Delete |
| `Comments` | List, Get, Create, Update, Delete |

## Requirements

- Go 1.23+
- BookStack instance with API enabled

## License

See [LICENSE](LICENSE) file.