Add example programs

- examples/basic: Client setup, projects, tasks, and create operations
- examples/fluent: Fluent API with TaskParams, TaskUpdateParams, tags
- examples/search: Project-specific and global search functionality

.beads/issues.jsonl

@@ -5,7 +5,7 @@
 {"id":"kanboard-api-2ze","title":"Implement BoardScope fluent builder","description":"Implement BoardScope for fluent project-scoped operations.\n\n## Requirements\n- BoardScope struct with client and projectID\n- Client.Board(projectID int) *BoardScope method\n- BoardScope methods:\n  - GetColumns(ctx) ([]Column, error)\n  - GetCategories(ctx) ([]Category, error)\n  - GetTasks(ctx, status TaskStatus) ([]Task, error)\n  - SearchTasks(ctx, query string) ([]Task, error)\n  - CreateTask(ctx, task *TaskParams) (*Task, error)\n\n## Files to create\n- board_scope.go\n\n## Example usage\n```go\ncolumns, _ := client.Board(1).GetColumns(ctx)\ntask, _ := client.Board(1).CreateTask(ctx, kanboard.NewTask(\"Title\"))\n```\n\n## Acceptance criteria\n- All methods delegate to direct Client methods\n- Proper error propagation","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:35:40.044649709+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:29:29.648709021+01:00","closed_at":"2026-01-15T18:29:29.648709021+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-2ze","depends_on_id":"kanboard-api-apl","type":"blocks","created_at":"2026-01-15T17:43:30.81063282+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-2ze","depends_on_id":"kanboard-api-l9b","type":"blocks","created_at":"2026-01-15T17:43:30.874964284+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-2ze","depends_on_id":"kanboard-api-0fz","type":"blocks","created_at":"2026-01-15T17:43:30.939377116+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-2ze","depends_on_id":"kanboard-api-91a","type":"blocks","created_at":"2026-01-15T17:43:31.005026627+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-3dc","title":"Implement Link API methods","description":"Implement direct API methods for task link operations.\n\n## Methods to implement\n- GetAllTaskLinks(ctx, taskID int) ([]TaskLink, error) - getAllTaskLinks\n- CreateTaskLink(ctx, taskID, oppositeTaskID, linkID int) (int, error) - createTaskLink\n- RemoveTaskLink(ctx, taskLinkID int) error - removeTaskLink (Nice-to-have)\n\n## TaskScope methods to add\n- GetLinks(ctx) ([]TaskLink, error)\n- LinkTo(ctx, oppositeTaskID, linkID int) error\n\n## Files to create\n- links.go\n- task_scope.go (extend)\n\n## Acceptance criteria\n- CreateTaskLink returns the link ID\n- Links include related task information","status":"closed","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:09.328552773+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:43:29.707624597+01:00","closed_at":"2026-01-15T18:43:29.707624597+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-3dc","depends_on_id":"kanboard-api-uls","type":"blocks","created_at":"2026-01-15T17:43:49.785710003+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-3dc","depends_on_id":"kanboard-api-cyc","type":"blocks","created_at":"2026-01-15T17:43:49.886111429+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-5fb","title":"Implement TaskUpdateParams builder","description":"Implement TaskUpdateParams for fluent task update configuration.\n\n## Requirements\n- TaskUpdateParams struct with pointer fields\n- NewTaskUpdate() *TaskUpdateParams constructor\n- Fluent setter methods:\n  - SetTitle(title string) *TaskUpdateParams\n  - SetDescription(desc string) *TaskUpdateParams\n  - SetColor(colorID string) *TaskUpdateParams\n  - SetOwner(ownerID int) *TaskUpdateParams\n  - SetCategory(categoryID int) *TaskUpdateParams\n  - SetPriority(priority int) *TaskUpdateParams\n  - SetDueDate(date time.Time) *TaskUpdateParams\n- Internal method to convert to UpdateTaskRequest\n\n## Files to create\n- task_update_params.go\n\n## Example usage\n```go\nparams := kanboard.NewTaskUpdate().\n    SetTitle(\"New Title\").\n    SetPriority(2)\n```\n\n## Acceptance criteria\n- Only set fields are included in update request\n- All setters return *TaskUpdateParams for chaining","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:35:40.814955926+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:33:14.78349244+01:00","closed_at":"2026-01-15T18:33:14.78349244+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-5fb","depends_on_id":"kanboard-api-cyc","type":"blocks","created_at":"2026-01-15T17:43:31.134402453+01:00","created_by":"Oliver Jakoubek"}]}
-{"id":"kanboard-api-70e","title":"Add GoDoc documentation to all public APIs","description":"Add comprehensive GoDoc comments to all exported types and functions.\n\n## Requirements\n- Package-level documentation in doc.go\n- All exported types documented\n- All exported functions documented with examples\n- All exported constants/variables documented\n\n## Documentation standards\n- Start with the name being documented\n- Include usage examples where helpful\n- Document error conditions\n- Note thread-safety characteristics\n\n## Files to create/modify\n- doc.go (package documentation)\n- All .go files with exported symbols\n\n## Acceptance criteria\n- `go doc` produces clean output\n- All exports have documentation\n- Examples are runnable","status":"in_progress","priority":2,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:54.342657373+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T19:21:15.302778246+01:00","dependencies":[{"issue_id":"kanboard-api-70e","depends_on_id":"kanboard-api-uls","type":"blocks","created_at":"2026-01-15T17:46:55.508211397+01:00","created_by":"Oliver Jakoubek"}]}
+{"id":"kanboard-api-70e","title":"Add GoDoc documentation to all public APIs","description":"Add comprehensive GoDoc comments to all exported types and functions.\n\n## Requirements\n- Package-level documentation in doc.go\n- All exported types documented\n- All exported functions documented with examples\n- All exported constants/variables documented\n\n## Documentation standards\n- Start with the name being documented\n- Include usage examples where helpful\n- Document error conditions\n- Note thread-safety characteristics\n\n## Files to create/modify\n- doc.go (package documentation)\n- All .go files with exported symbols\n\n## Acceptance criteria\n- `go doc` produces clean output\n- All exports have documentation\n- Examples are runnable","status":"closed","priority":2,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:54.342657373+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T19:23:37.326817635+01:00","closed_at":"2026-01-15T19:23:37.326817635+01:00","close_reason":"Package-level doc.go created; all public APIs already have doc comments","dependencies":[{"issue_id":"kanboard-api-70e","depends_on_id":"kanboard-api-uls","type":"blocks","created_at":"2026-01-15T17:46:55.508211397+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-91a","title":"Implement Task API methods (CRUD)","description":"Implement direct API methods for core task operations.\n\n## Methods to implement\n- GetTask(ctx, taskID int) (*Task, error) - getTask\n- GetAllTasks(ctx, projectID int, status TaskStatus) ([]Task, error) - getAllTasks\n- CreateTask(ctx, req CreateTaskRequest) (*Task, error) - createTask\n- UpdateTask(ctx, req UpdateTaskRequest) error - updateTask\n- CloseTask(ctx, taskID int) error - closeTask\n- OpenTask(ctx, taskID int) error - openTask\n\n## Files to create\n- tasks.go\n\n## Acceptance criteria\n- CreateTask returns the created task\n- UpdateTask supports partial updates via pointer fields\n- Proper error types (ErrTaskNotFound, ErrTaskClosed, etc.)","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:35:16.9962543+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:26:49.591860359+01:00","closed_at":"2026-01-15T18:26:49.591860359+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-91a","depends_on_id":"kanboard-api-uls","type":"blocks","created_at":"2026-01-15T17:42:53.291442735+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-91a","depends_on_id":"kanboard-api-cyc","type":"blocks","created_at":"2026-01-15T17:42:53.434459365+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-9k8","title":"Implement TaskParams builder (Options Pattern)","description":"Implement TaskParams for fluent task creation configuration.\n\n## Requirements\n- TaskParams struct with private fields\n- NewTask(title string) *TaskParams constructor\n- Fluent setter methods:\n  - WithDescription(desc string) *TaskParams\n  - InColumn(columnID int) *TaskParams\n  - WithCategory(categoryID int) *TaskParams\n  - WithOwner(ownerID int) *TaskParams\n  - WithColor(colorID string) *TaskParams\n  - WithPriority(priority int) *TaskParams\n  - WithDueDate(date time.Time) *TaskParams\n  - WithTags(tags ...string) *TaskParams\n  - WithReference(ref string) *TaskParams\n- Internal method to convert to CreateTaskRequest\n\n## Files to create\n- task_params.go\n\n## Example usage\n```go\nparams := kanboard.NewTask(\"My Task\").\n    WithDescription(\"Details\").\n    InColumn(2).\n    WithTags(\"urgent\", \"backend\")\n```\n\n## Acceptance criteria\n- Pure configuration object (no I/O)\n- All setters return *TaskParams for chaining\n- Unset optional fields remain nil","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:35:40.439513879+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:31:07.365703704+01:00","closed_at":"2026-01-15T18:31:07.365703704+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-9k8","depends_on_id":"kanboard-api-cyc","type":"blocks","created_at":"2026-01-15T17:43:31.070100884+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-apl","title":"Implement Project API methods","description":"Implement direct API methods for project/board operations.\n\n## Methods to implement\n- GetAllProjects(ctx) ([]Project, error) - getAllProjects\n- GetProjectByID(ctx, projectID int) (*Project, error) - getProjectById\n- GetProjectByName(ctx, name string) (*Project, error) - getProjectByName (Nice-to-have)\n\n## Files to create\n- projects.go\n\n## Acceptance criteria\n- All methods use context for cancellation\n- Proper error handling and wrapping\n- Returns ErrProjectNotFound when appropriate","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:35:15.864764497+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:21:36.226187777+01:00","closed_at":"2026-01-15T18:21:36.226187777+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-apl","depends_on_id":"kanboard-api-uls","type":"blocks","created_at":"2026-01-15T17:42:52.850751716+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-apl","depends_on_id":"kanboard-api-cyc","type":"blocks","created_at":"2026-01-15T17:42:52.946556814+01:00","created_by":"Oliver Jakoubek"}]}
@@ -22,6 +22,6 @@
 {"id":"kanboard-api-ukc","title":"Set up Mage build system","description":"Set up Mage build system for development automation.\n\n## Directory structure\n```\nmagefiles/\n├── go.mod\n├── go.sum\n└── magefile.go\n```\n\n## Targets to implement\n- Test() - Run all tests with race detection and coverage\n- Coverage() - Run tests and open HTML coverage report\n- Lint() - Run golangci-lint\n- Build() - Verify module compiles\n\n## Files to create\n- magefiles/go.mod\n- magefiles/magefile.go\n\n## Acceptance criteria\n- `mage test` runs tests with -race and -coverprofile\n- `mage lint` runs golangci-lint\n- `mage build` verifies compilation","status":"closed","priority":2,"issue_type":"chore","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:30.260235504+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T19:20:02.610796083+01:00","closed_at":"2026-01-15T19:20:02.610796083+01:00","close_reason":"Mage build system implemented with test, coverage, lint, and build targets"}
 {"id":"kanboard-api-uls","title":"Implement Client struct with fluent configuration","description":"Implement the main Client struct with fluent builder pattern for configuration.\n\n## Requirements\n- Client struct with baseURL, httpClient, auth, logger, requestID\n- NewClient(baseURL string) constructor\n- Fluent configuration methods:\n  - WithAPIToken(token string) *Client\n  - WithBasicAuth(username, password string) *Client\n  - WithHTTPClient(client *http.Client) *Client\n  - WithTimeout(timeout time.Duration) *Client\n  - WithLogger(logger *slog.Logger) *Client\n- Default timeout of 30 seconds\n- Thread-safe for concurrent use\n\n## Files to create\n- client.go\n\n## Acceptance criteria\n- Client is immutable after configuration\n- Thread-safe concurrent usage\n- Configurable HTTP client and logger","status":"closed","priority":0,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:34:54.051926732+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:14:16.530243958+01:00","closed_at":"2026-01-15T18:14:16.530243958+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-uls","depends_on_id":"kanboard-api-2g1","type":"blocks","created_at":"2026-01-15T17:42:48.457362117+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-uls","depends_on_id":"kanboard-api-k33","type":"blocks","created_at":"2026-01-15T17:42:48.576622508+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-uls","depends_on_id":"kanboard-api-s7k","type":"blocks","created_at":"2026-01-15T17:42:48.749342195+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-una","title":"Implement TaskScope fluent builder (core methods)","description":"Implement TaskScope for fluent task-scoped operations (core methods).\n\n## Requirements\n- TaskScope struct with client and taskID\n- Client.Task(taskID int) *TaskScope method\n- Core TaskScope methods:\n  - Get(ctx) (*Task, error)\n  - Close(ctx) error\n  - Open(ctx) error\n  - MoveToColumn(ctx, columnID int) error\n  - MoveToProject(ctx, projectID int) error\n  - Update(ctx, params *TaskUpdateParams) error\n\n## Files to create\n- task_scope.go\n\n## Example usage\n```go\ntask, _ := client.Task(123).Get(ctx)\nclient.Task(123).Close(ctx)\nclient.Task(123).Update(ctx, kanboard.NewTaskUpdate().SetTitle(\"New\"))\n```\n\n## Acceptance criteria\n- All methods delegate to direct Client methods\n- Proper error propagation","status":"closed","priority":1,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:35:41.173930396+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:34:32.369975567+01:00","closed_at":"2026-01-15T18:34:32.369975567+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-una","depends_on_id":"kanboard-api-91a","type":"blocks","created_at":"2026-01-15T17:43:31.198935686+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-una","depends_on_id":"kanboard-api-5fb","type":"blocks","created_at":"2026-01-15T17:43:31.261453756+01:00","created_by":"Oliver Jakoubek"}]}
-{"id":"kanboard-api-xhf","title":"Create example programs","description":"Create example programs demonstrating library usage.\n\n## Examples to create\n```\nexamples/\n├── basic/\n│   └── main.go       # Basic client setup and simple operations\n├── fluent/\n│   └── main.go       # Fluent API demonstration\n└── search/\n    └── main.go       # Search functionality demo\n```\n\n## basic/main.go\n- Client creation with API token\n- Get all projects\n- Get tasks from a project\n- Create a simple task\n\n## fluent/main.go\n- Client configuration with all options\n- Task creation with TaskParams\n- Task updates with TaskUpdateParams\n- Tag operations\n\n## search/main.go\n- Project-specific search\n- Global search across all projects\n\n## Files to create\n- examples/basic/main.go\n- examples/fluent/main.go\n- examples/search/main.go\n\n## Acceptance criteria\n- Examples compile and are well-commented\n- Cover main use cases\n- Show both fluent and direct API styles","status":"open","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:53.604889443+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T17:36:53.604889443+01:00","dependencies":[{"issue_id":"kanboard-api-xhf","depends_on_id":"kanboard-api-2ze","type":"blocks","created_at":"2026-01-15T17:46:55.571585285+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-xhf","depends_on_id":"kanboard-api-una","type":"blocks","created_at":"2026-01-15T17:46:55.63515762+01:00","created_by":"Oliver Jakoubek"}]}
+{"id":"kanboard-api-xhf","title":"Create example programs","description":"Create example programs demonstrating library usage.\n\n## Examples to create\n```\nexamples/\n├── basic/\n│   └── main.go       # Basic client setup and simple operations\n├── fluent/\n│   └── main.go       # Fluent API demonstration\n└── search/\n    └── main.go       # Search functionality demo\n```\n\n## basic/main.go\n- Client creation with API token\n- Get all projects\n- Get tasks from a project\n- Create a simple task\n\n## fluent/main.go\n- Client configuration with all options\n- Task creation with TaskParams\n- Task updates with TaskUpdateParams\n- Tag operations\n\n## search/main.go\n- Project-specific search\n- Global search across all projects\n\n## Files to create\n- examples/basic/main.go\n- examples/fluent/main.go\n- examples/search/main.go\n\n## Acceptance criteria\n- Examples compile and are well-commented\n- Cover main use cases\n- Show both fluent and direct API styles","status":"in_progress","priority":3,"issue_type":"task","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:53.604889443+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T19:23:50.145126844+01:00","dependencies":[{"issue_id":"kanboard-api-xhf","depends_on_id":"kanboard-api-2ze","type":"blocks","created_at":"2026-01-15T17:46:55.571585285+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-xhf","depends_on_id":"kanboard-api-una","type":"blocks","created_at":"2026-01-15T17:46:55.63515762+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-zfc","title":"Implement TaskScope tag methods with read-modify-write (CRITICAL)","description":"Implement TaskScope tag methods with read-modify-write pattern. CRITICAL feature.\n\n## TaskScope methods to implement\n- GetTags(ctx) (map[int]string, error)\n- SetTags(ctx, tags ...string) error - replaces ALL tags\n- ClearTags(ctx) error - removes ALL tags\n- AddTag(ctx, tag string) error - read-modify-write\n- RemoveTag(ctx, tag string) error - read-modify-write\n- HasTag(ctx, tag string) (bool, error)\n\n## Read-Modify-Write Workflow for AddTag\n1. Get task via getTask (need project_id)\n2. Get current tags via getTaskTags\n3. Check if tag already exists\n4. If not: add tag to list\n5. Call setTaskTags with updated list\n\n## Read-Modify-Write Workflow for RemoveTag\n1. Get task via getTask (need project_id)\n2. Get current tags via getTaskTags\n3. Filter out the tag to remove\n4. Call setTaskTags with filtered list\n5. If tag didn't exist: no error (idempotent)\n\n## Files to modify\n- task_scope.go\n\n## IMPORTANT WARNING\nThis is NOT atomic. Concurrent tag modifications may cause data loss. Document this limitation.\n\n## Acceptance criteria\n- AddTag is idempotent (no error if tag exists)\n- RemoveTag is idempotent (no error if tag doesn't exist)\n- HasTag correctly checks tag existence","status":"closed","priority":0,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:08.911429864+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:36:32.533937315+01:00","closed_at":"2026-01-15T18:36:32.533937315+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-zfc","depends_on_id":"kanboard-api-16r","type":"blocks","created_at":"2026-01-15T17:43:49.517064988+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-zfc","depends_on_id":"kanboard-api-una","type":"blocks","created_at":"2026-01-15T17:43:49.593313748+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-zfc","depends_on_id":"kanboard-api-91a","type":"blocks","created_at":"2026-01-15T17:43:49.690872321+01:00","created_by":"Oliver Jakoubek"}]}
 {"id":"kanboard-api-zg2","title":"Implement File API methods","description":"Implement direct API methods for task file operations.\n\n## Methods to implement (Must-have)\n- GetAllTaskFiles(ctx, taskID int) ([]TaskFile, error) - getAllTaskFiles\n- CreateTaskFile(ctx, projectID, taskID int, filename string, content []byte) (int, error) - createTaskFile\n\n## Methods to implement (Nice-to-have)\n- DownloadTaskFile(ctx, fileID int) ([]byte, error) - downloadTaskFile\n- RemoveTaskFile(ctx, fileID int) error - removeTaskFile\n\n## TaskScope methods to add\n- GetFiles(ctx) ([]TaskFile, error)\n- UploadFile(ctx, filename string, content []byte) (*TaskFile, error)\n\n## Files to create\n- files.go\n- task_scope.go (extend)\n\n## Acceptance criteria\n- File content base64 encoded for upload\n- CreateTaskFile returns file ID","status":"closed","priority":2,"issue_type":"feature","owner":"mail@oliverjakoubek.de","created_at":"2026-01-15T17:36:09.748005313+01:00","created_by":"Oliver Jakoubek","updated_at":"2026-01-15T18:45:05.499871045+01:00","closed_at":"2026-01-15T18:45:05.499871045+01:00","close_reason":"Closed","dependencies":[{"issue_id":"kanboard-api-zg2","depends_on_id":"kanboard-api-uls","type":"blocks","created_at":"2026-01-15T17:43:49.984099418+01:00","created_by":"Oliver Jakoubek"},{"issue_id":"kanboard-api-zg2","depends_on_id":"kanboard-api-cyc","type":"blocks","created_at":"2026-01-15T17:43:50.049331328+01:00","created_by":"Oliver Jakoubek"}]}

examples/basic/main.go

@@ -0,0 +1,83 @@
+// Example: basic demonstrates basic client setup and simple operations.
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"time"
+
+	kanboard "code.beautifulmachines.dev/jakoubek/kanboard-api"
+)
+
+func main() {
+	// Read configuration from environment
+	baseURL := os.Getenv("KANBOARD_URL")
+	token := os.Getenv("KANBOARD_TOKEN")
+
+	if baseURL == "" || token == "" {
+		log.Fatal("Set KANBOARD_URL and KANBOARD_TOKEN environment variables")
+	}
+
+	// Create a client with API token authentication
+	client := kanboard.NewClient(baseURL).
+		WithAPIToken(token).
+		WithTimeout(30 * time.Second)
+
+	ctx := context.Background()
+
+	// Get all projects
+	projects, err := client.GetAllProjects(ctx)
+	if err != nil {
+		log.Fatalf("Failed to get projects: %v", err)
+	}
+
+	fmt.Printf("Found %d projects:\n", len(projects))
+	for _, p := range projects {
+		fmt.Printf("  - [%d] %s\n", p.ID, p.Name)
+	}
+
+	if len(projects) == 0 {
+		fmt.Println("No projects found. Create one in Kanboard first.")
+		return
+	}
+
+	// Use the first project
+	projectID := int(projects[0].ID)
+
+	// Get all active tasks for the project
+	tasks, err := client.GetAllTasks(ctx, projectID, kanboard.StatusActive)
+	if err != nil {
+		log.Fatalf("Failed to get tasks: %v", err)
+	}
+
+	fmt.Printf("\nActive tasks in project %d:\n", projectID)
+	for _, t := range tasks {
+		fmt.Printf("  - [%d] %s\n", t.ID, t.Title)
+	}
+
+	// Create a simple task using the direct API
+	newTask, err := client.CreateTask(ctx, kanboard.CreateTaskRequest{
+		Title:       "Task created via API",
+		ProjectID:   projectID,
+		Description: "This task was created using the kanboard-api library.",
+	})
+	if err != nil {
+		log.Fatalf("Failed to create task: %v", err)
+	}
+
+	fmt.Printf("\nCreated task: [%d] %s\n", newTask.ID, newTask.Title)
+
+	// Get task details
+	task, err := client.GetTask(ctx, int(newTask.ID))
+	if err != nil {
+		log.Fatalf("Failed to get task: %v", err)
+	}
+
+	fmt.Printf("Task details:\n")
+	fmt.Printf("  Title: %s\n", task.Title)
+	fmt.Printf("  Description: %s\n", task.Description)
+	fmt.Printf("  Column ID: %d\n", task.ColumnID)
+	fmt.Printf("  Created: %s\n", task.DateCreation.Time.Format(time.RFC3339))
+}

examples/fluent/main.go

@@ -0,0 +1,116 @@
+// Example: fluent demonstrates the fluent API for task management.
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"log/slog"
+	"os"
+	"time"
+
+	kanboard "code.beautifulmachines.dev/jakoubek/kanboard-api"
+)
+
+func main() {
+	// Read configuration from environment
+	baseURL := os.Getenv("KANBOARD_URL")
+	token := os.Getenv("KANBOARD_TOKEN")
+
+	if baseURL == "" || token == "" {
+		log.Fatal("Set KANBOARD_URL and KANBOARD_TOKEN environment variables")
+	}
+
+	// Create a fully configured client
+	client := kanboard.NewClient(baseURL).
+		WithAPIToken(token).
+		WithTimeout(60 * time.Second).
+		WithLogger(slog.Default()) // Enable debug logging
+
+	ctx := context.Background()
+
+	// Get the first project
+	projects, err := client.GetAllProjects(ctx)
+	if err != nil {
+		log.Fatalf("Failed to get projects: %v", err)
+	}
+	if len(projects) == 0 {
+		log.Fatal("No projects found")
+	}
+	projectID := int(projects[0].ID)
+
+	// Use BoardScope for project-scoped operations
+	board := client.Board(projectID)
+
+	// Get columns to understand the workflow
+	columns, err := board.GetColumns(ctx)
+	if err != nil {
+		log.Fatalf("Failed to get columns: %v", err)
+	}
+	fmt.Println("Columns in project:")
+	for _, c := range columns {
+		fmt.Printf("  - [%d] %s (position: %d)\n", c.ID, c.Title, c.Position)
+	}
+
+	// Create a task using TaskParams (fluent builder)
+	params := kanboard.NewTask("Feature: User Dashboard").
+		WithDescription("Implement the user dashboard with activity feed").
+		WithPriority(2).
+		WithScore(5).
+		WithTags("feature", "frontend", "v2.0").
+		WithDueDate(time.Now().Add(14 * 24 * time.Hour))
+
+	task, err := board.CreateTaskFromParams(ctx, params)
+	if err != nil {
+		log.Fatalf("Failed to create task: %v", err)
+	}
+	fmt.Printf("\nCreated task: [%d] %s\n", task.ID, task.Title)
+
+	// Use TaskScope for task-scoped operations
+	taskScope := client.Task(int(task.ID))
+
+	// Add more tags
+	if err := taskScope.AddTag(ctx, "priority"); err != nil {
+		log.Fatalf("Failed to add tag: %v", err)
+	}
+	fmt.Println("Added 'priority' tag")
+
+	// Get current tags
+	tags, err := taskScope.GetTags(ctx)
+	if err != nil {
+		log.Fatalf("Failed to get tags: %v", err)
+	}
+	fmt.Printf("Current tags: %v\n", tags)
+
+	// Update the task using TaskUpdateParams
+	updates := kanboard.NewTaskUpdate().
+		SetTitle("Feature: Enhanced User Dashboard").
+		SetDescription("Implement user dashboard with activity feed and notifications").
+		SetPriority(1)
+
+	if err := taskScope.Update(ctx, updates); err != nil {
+		log.Fatalf("Failed to update task: %v", err)
+	}
+	fmt.Println("Updated task title and priority")
+
+	// Move task to next column
+	if err := taskScope.MoveToNextColumn(ctx); err != nil {
+		if err == kanboard.ErrAlreadyInLastColumn {
+			fmt.Println("Task is already in the last column")
+		} else {
+			log.Fatalf("Failed to move task: %v", err)
+		}
+	} else {
+		fmt.Println("Moved task to next column")
+	}
+
+	// Get updated task details
+	updated, err := taskScope.Get(ctx)
+	if err != nil {
+		log.Fatalf("Failed to get task: %v", err)
+	}
+	fmt.Printf("\nUpdated task:\n")
+	fmt.Printf("  Title: %s\n", updated.Title)
+	fmt.Printf("  Column: %d\n", updated.ColumnID)
+	fmt.Printf("  Priority: %d\n", updated.Priority)
+}

examples/search/main.go

@@ -0,0 +1,116 @@
+// Example: search demonstrates search functionality.
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"time"
+
+	kanboard "code.beautifulmachines.dev/jakoubek/kanboard-api"
+)
+
+func main() {
+	// Read configuration from environment
+	baseURL := os.Getenv("KANBOARD_URL")
+	token := os.Getenv("KANBOARD_TOKEN")
+
+	if baseURL == "" || token == "" {
+		log.Fatal("Set KANBOARD_URL and KANBOARD_TOKEN environment variables")
+	}
+
+	client := kanboard.NewClient(baseURL).
+		WithAPIToken(token).
+		WithTimeout(30 * time.Second)
+
+	ctx := context.Background()
+
+	// Get the first project for project-specific search
+	projects, err := client.GetAllProjects(ctx)
+	if err != nil {
+		log.Fatalf("Failed to get projects: %v", err)
+	}
+	if len(projects) == 0 {
+		log.Fatal("No projects found")
+	}
+	projectID := int(projects[0].ID)
+	fmt.Printf("Using project: %s (ID: %d)\n\n", projects[0].Name, projectID)
+
+	// Project-specific search using Kanboard query syntax
+	// See: https://docs.kanboard.org/v1/user/search/
+	fmt.Println("=== Project-Specific Search ===")
+
+	// Search for open tasks
+	tasks, err := client.SearchTasks(ctx, projectID, "status:open")
+	if err != nil {
+		log.Fatalf("Failed to search: %v", err)
+	}
+	fmt.Printf("Open tasks: %d\n", len(tasks))
+	for _, t := range tasks {
+		fmt.Printf("  - [%d] %s\n", t.ID, t.Title)
+	}
+
+	// Search by title keyword
+	tasks, err = client.Board(projectID).SearchTasks(ctx, "title:feature")
+	if err != nil {
+		log.Fatalf("Failed to search: %v", err)
+	}
+	fmt.Printf("\nTasks with 'feature' in title: %d\n", len(tasks))
+	for _, t := range tasks {
+		fmt.Printf("  - [%d] %s\n", t.ID, t.Title)
+	}
+
+	// Search overdue tasks
+	tasks, err = client.SearchTasks(ctx, projectID, "due:<today")
+	if err != nil {
+		log.Fatalf("Failed to search: %v", err)
+	}
+	fmt.Printf("\nOverdue tasks: %d\n", len(tasks))
+	for _, t := range tasks {
+		fmt.Printf("  - [%d] %s (due: %s)\n", t.ID, t.Title, t.DateDue.Time.Format("2006-01-02"))
+	}
+
+	// Global search across ALL projects
+	fmt.Println("\n=== Global Search (All Projects) ===")
+
+	// This searches in parallel across all accessible projects
+	allTasks, err := client.SearchTasksGlobally(ctx, "status:open")
+	if err != nil {
+		log.Fatalf("Failed to global search: %v", err)
+	}
+	fmt.Printf("Open tasks across all projects: %d\n", len(allTasks))
+
+	// Group results by project
+	byProject := make(map[int][]kanboard.Task)
+	for _, t := range allTasks {
+		pid := int(t.ProjectID)
+		byProject[pid] = append(byProject[pid], t)
+	}
+
+	for pid, tasks := range byProject {
+		fmt.Printf("\n  Project %d: %d tasks\n", pid, len(tasks))
+		for _, t := range tasks {
+			fmt.Printf("    - [%d] %s\n", t.ID, t.Title)
+		}
+	}
+
+	// Search examples with Kanboard query syntax
+	fmt.Println("\n=== Query Syntax Examples ===")
+	fmt.Println("Kanboard supports rich query syntax:")
+	fmt.Println("  status:open              - Open tasks")
+	fmt.Println("  status:closed            - Closed tasks")
+	fmt.Println("  assignee:me              - Tasks assigned to current user")
+	fmt.Println("  due:today                - Tasks due today")
+	fmt.Println("  due:<tomorrow            - Tasks due before tomorrow")
+	fmt.Println("  due:>2024-01-01          - Tasks due after date")
+	fmt.Println("  title:\"bug fix\"          - Tasks with exact title match")
+	fmt.Println("  color:red                - Tasks with red color")
+	fmt.Println("  category:\"Bug\"           - Tasks in category")
+	fmt.Println("  tag:urgent               - Tasks with tag")
+	fmt.Println("  priority:3               - Tasks with priority")
+	fmt.Println()
+	fmt.Println("Combine queries with spaces (AND) or | (OR):")
+	fmt.Println("  status:open assignee:me  - Open tasks assigned to me")
+	fmt.Println("  status:open | status:closed - All tasks")
+}