kanboard

package module
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 2, 2026 License: MIT Imports: 18 Imported by: 0

README

kanboard-api

Mirror on GitHub Go Reference Go Report Card

Go library for the Kanboard JSON-RPC API. Provides a fluent, chainable API for integrating Kanboard into Go applications.

Installation

go get code.beautifulmachines.dev/jakoubek/kanboard-api

Quick Start

package main

import (
    "context"
    "fmt"
    "log"
    "time"

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

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

    // Create client with API token
    client := kanboard.NewClient("https://kanboard.example.com").
        WithAPIToken("your-api-token").
        WithTimeout(30 * time.Second)

    // Create a task using the fluent API
    task, err := client.Board(1).CreateTaskFromParams(ctx,
        kanboard.NewTask("My Task").
            WithDescription("Task description").
            WithPriority(2).
            WithTags("urgent", "backend"))
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Created task: %d\n", task.ID)
}

Authentication

The library supports two authentication methods:

client := kanboard.NewClient("https://kanboard.example.com").
    WithAPIToken("your-api-token")
Username/Password
client := kanboard.NewClient("https://kanboard.example.com").
    WithBasicAuth("admin", "password")

API Usage

Fluent API

The fluent API provides chainable, scoped operations:

// Board-scoped operations
board := client.Board(projectID)
tasks, _ := board.GetTasks(ctx, kanboard.StatusActive)
columns, _ := board.GetColumns(ctx)
categories, _ := board.GetCategories(ctx)

// Task-scoped operations
task := client.Task(taskID)
task.Close(ctx)
task.MoveToNextColumn(ctx)
task.AddTag(ctx, "reviewed")
task.AddComment(ctx, userID, "Comment text")
Direct API

For lower-level access, use the direct API methods:

// Projects
projects, _ := client.GetAllProjects(ctx)
project, _ := client.GetProjectByID(ctx, projectID)
project, _ := client.GetProjectByName(ctx, "My Project")

// Tasks
tasks, _ := client.GetAllTasks(ctx, projectID, kanboard.StatusActive)
task, _ := client.GetTask(ctx, taskID)
task, _ := client.CreateTask(ctx, kanboard.CreateTaskRequest{
    Title:     "New Task",
    ProjectID: projectID,
})

// Global search across all projects
results, _ := client.SearchTasksGlobal(ctx, "search query")
Task Creation

Use TaskParams for fluent task creation:

params := kanboard.NewTask("Task Title").
    WithDescription("Detailed description").
    WithCategory(categoryID).
    WithOwner(userID).
    WithColor("red").
    WithPriority(3).
    WithScore(5).
    WithDueDate(time.Now().Add(7 * 24 * time.Hour)).
    WithTags("feature", "v2.0").
    InColumn(columnID).
    InSwimlane(swimlaneID)

task, err := client.Board(projectID).CreateTaskFromParams(ctx, params)
Task Updates

Use TaskUpdateParams for partial updates:

updates := kanboard.NewTaskUpdate().
    SetTitle("Updated Title").
    SetDescription("New description").
    SetPriority(1)

err := client.Task(taskID).Update(ctx, updates)
Task Movement
// Move to next/previous column in workflow
client.Task(taskID).MoveToNextColumn(ctx)
client.Task(taskID).MoveToPreviousColumn(ctx)

// Move to specific column
client.Task(taskID).MoveToColumn(ctx, columnID)

// Move to different project
client.Task(taskID).MoveToProject(ctx, newProjectID)
Comments
// Get all comments
comments, _ := client.Task(taskID).GetComments(ctx)

// Add a comment
comment, _ := client.Task(taskID).AddComment(ctx, userID, "Comment text")

// Get task links
links, _ := client.Task(taskID).GetLinks(ctx)

// Link tasks together
client.Task(taskID).LinkTo(ctx, otherTaskID, linkID)
Files
// Get attached files
files, _ := client.Task(taskID).GetFiles(ctx)

// Upload a file
content := []byte("file content")
fileID, _ := client.Task(taskID).UploadFile(ctx, "document.txt", content)

Error Handling

The library provides typed errors for common scenarios:

task, err := client.GetTask(ctx, taskID)
if err != nil {
    if kanboard.IsNotFound(err) {
        // Handle not found
    }
    if kanboard.IsUnauthorized(err) {
        // Handle auth failure
    }
    if kanboard.IsAPIError(err) {
        // Handle Kanboard API error
    }
}

Available sentinel errors:

  • ErrNotFound, ErrProjectNotFound, ErrTaskNotFound, ErrColumnNotFound
  • ErrUnauthorized, ErrForbidden
  • ErrConnectionFailed, ErrTimeout
  • ErrAlreadyInLastColumn, ErrAlreadyInFirstColumn
  • ErrEmptyTitle, ErrInvalidProjectID

Thread Safety

The client is safe for concurrent use by multiple goroutines. Request IDs are generated atomically.

Tag Operations Warning

Kanboard's setTaskTags API replaces all tags. The library implements read-modify-write internally for AddTag and RemoveTag operations. This is not atomic - concurrent tag modifications may cause data loss.

// Safe: single operation
task.SetTags(ctx, "tag1", "tag2", "tag3")

// Caution: concurrent calls to AddTag/RemoveTag may conflict
task.AddTag(ctx, "new-tag")
task.RemoveTag(ctx, "old-tag")

Client Configuration

client := kanboard.NewClient("https://kanboard.example.com").
    WithAPIToken("token").
    WithTimeout(60 * time.Second).
    WithHTTPClient(customHTTPClient).
    WithLogger(slog.Default())

License

MIT License - see LICENSE for details.

Documentation

Overview

Package kanboard provides a Go client for the Kanboard JSON-RPC API.

This library offers both a fluent API for convenient, chainable operations and direct API methods for lower-level access. The client is safe for concurrent use by multiple goroutines.

Quick Start

Create a client with API token authentication: 

client := kanboard.NewClient("https://kanboard.example.com").
    WithAPIToken("your-api-token")

Authentication

The library supports two authentication methods:

Fluent API

Use Client.Board for project-scoped operations: 

board := client.Board(projectID)
tasks, _ := board.GetTasks(ctx, kanboard.StatusActive)
task, _ := board.CreateTaskFromParams(ctx,
    kanboard.NewTask("Title").WithDescription("Details"))

Use Client.Task for task-scoped operations: 

task := client.Task(taskID)
task.MoveToNextColumn(ctx)
task.AddTag(ctx, "reviewed")
task.AddComment(ctx, userID, "Comment text")

Task Creation

Use TaskParams for fluent task creation: 

params := kanboard.NewTask("Title").
    WithDescription("Details").
    WithPriority(2).
    WithTags("urgent", "backend")

Error Handling

The library provides typed errors and helper functions: 

task, err := client.GetTask(ctx, taskID)
if kanboard.IsNotFound(err) {
    // Handle not found
}
if kanboard.IsUnauthorized(err) {
    // Handle auth failure
}

Thread Safety

The Client is safe for concurrent use. Request IDs are generated atomically.

Tag Operations

Warning: Kanboard's setTaskTags API replaces all tags. The TaskScope.AddTag and TaskScope.RemoveTag methods use read-modify-write internally and are not atomic. Concurrent tag modifications may cause data loss.

Index

Constants

View Source 
const DefaultTimeout = 30 * time.Second

DefaultTimeout is the default HTTP timeout for API requests.

Variables

View Source 
var (
	// ErrConnectionFailed indicates a connection to the Kanboard server failed.
	ErrConnectionFailed = errors.New("connection to Kanboard server failed")

	// ErrTimeout indicates a request timed out.
	ErrTimeout = errors.New("request timed out")

	// ErrTooManyRedirects indicates the server returned too many redirects.
	ErrTooManyRedirects = errors.New("too many redirects")
)

Network errors

View Source 
var (
	// ErrUnauthorized indicates authentication failed.
	ErrUnauthorized = errors.New("authentication failed: invalid credentials")

	// ErrForbidden indicates insufficient permissions.
	ErrForbidden = errors.New("access forbidden: insufficient permissions")
)

Authentication errors

View Source 
var (
	// ErrNotFound indicates a resource was not found.
	ErrNotFound = errors.New("resource not found")

	// ErrProjectNotFound indicates the specified project was not found.
	ErrProjectNotFound = errors.New("project not found")

	// ErrTaskNotFound indicates the specified task was not found.
	ErrTaskNotFound = errors.New("task not found")

	// ErrColumnNotFound indicates the specified column was not found.
	ErrColumnNotFound = errors.New("column not found")

	// ErrCommentNotFound indicates the specified comment was not found.
	ErrCommentNotFound = errors.New("comment not found")

	// ErrCategoryNotFound indicates the specified category was not found.
	ErrCategoryNotFound = errors.New("category not found")
)

Resource errors

View Source 
var (
	// ErrAlreadyInLastColumn indicates a task is already in the last column.
	ErrAlreadyInLastColumn = errors.New("task is already in the last column")

	// ErrAlreadyInFirstColumn indicates a task is already in the first column.
	ErrAlreadyInFirstColumn = errors.New("task is already in the first column")

	// ErrTaskClosed indicates a task is already closed.
	ErrTaskClosed = errors.New("task is already closed")

	// ErrTaskOpen indicates a task is already open.
	ErrTaskOpen = errors.New("task is already open")
)

Logic errors

View Source 
var (
	// ErrEmptyTitle indicates a task title cannot be empty.
	ErrEmptyTitle = errors.New("task title cannot be empty")

	// ErrInvalidProjectID indicates an invalid project ID was provided.
	ErrInvalidProjectID = errors.New("invalid project ID")
)

Validation errors

Functions

func IsAPIError 

func IsAPIError(err error) bool

IsAPIError returns true if the error is an APIError from the Kanboard API.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the error indicates a resource was not found.

func IsOperationFailed added in v1.0.1 

func IsOperationFailed(err error) bool

IsOperationFailed returns true if the error is an OperationFailedError.

func IsUnauthorized 

func IsUnauthorized(err error) bool

IsUnauthorized returns true if the error indicates an authentication failure.

Types

type APIError 

type APIError struct {
	Code    int
	Message string
}

APIError represents an error returned by the Kanboard API.

func (*APIError) Error 

func (e *APIError) Error() string

Error implements the error interface.

type Authenticator 

type Authenticator interface {
	Apply(req *http.Request)
}

Authenticator applies authentication to HTTP requests.

type BoardScope 

type BoardScope struct {
	// contains filtered or unexported fields
}

BoardScope provides fluent project-scoped operations.

func (*BoardScope) CreateCategory added in v1.3.0 

func (b *BoardScope) CreateCategory(ctx context.Context, name string, colorID string) (int, error)

CreateCategory creates a new category in the project and returns its ID.

func (*BoardScope) CreateTask 

func (b *BoardScope) CreateTask(ctx context.Context, req CreateTaskRequest) (*Task, error)

CreateTask creates a new task in the project. The ProjectID field in the request is overwritten with the board's project ID.

func (*BoardScope) CreateTaskFromParams 

func (b *BoardScope) CreateTaskFromParams(ctx context.Context, params *TaskParams) (*Task, error)

CreateTaskFromParams creates a new task in the project using TaskParams. This provides a fluent interface for task creation.

func (*BoardScope) GetCategories 

func (b *BoardScope) GetCategories(ctx context.Context) ([]Category, error)

GetCategories returns all categories for the project.

func (*BoardScope) GetCategoryByName added in v1.3.0 

func (b *BoardScope) GetCategoryByName(ctx context.Context, name string) (*Category, error)

GetCategoryByName returns a category by name within the project.

func (*BoardScope) GetColumns 

func (b *BoardScope) GetColumns(ctx context.Context) ([]Column, error)

GetColumns returns all columns for the project, sorted by position.

func (*BoardScope) GetTasks 

func (b *BoardScope) GetTasks(ctx context.Context, status TaskStatus) ([]Task, error)

GetTasks returns all tasks for the project with the specified status.

func (*BoardScope) SearchTasks 

func (b *BoardScope) SearchTasks(ctx context.Context, query string) ([]Task, error)

SearchTasks searches for tasks in the project using Kanboard query syntax.

type Category 

type Category struct {
	ID        StringInt `json:"id"`
	Name      string    `json:"name"`
	ProjectID StringInt `json:"project_id"`
	ColorID   string    `json:"color_id"`
}

Category represents a Kanboard category.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is the Kanboard API client. It is safe for concurrent use by multiple goroutines.

func NewClient 

func NewClient(baseURL string) *Client

NewClient creates a new Kanboard API client. The baseURL should be the base URL of the Kanboard instance (e.g., "https://kanboard.example.com"). The path /jsonrpc.php is appended automatically. Supports subdirectory installations (e.g., "https://example.com/kanboard" → POST https://example.com/kanboard/jsonrpc.php).

func (*Client) Board 

func (c *Client) Board(projectID int) *BoardScope

Board returns a BoardScope for fluent project-scoped operations.

func (*Client) CloseTask 

func (c *Client) CloseTask(ctx context.Context, taskID int) error

CloseTask closes a task (sets it to inactive). Returns ErrTaskClosed if the task is already closed.

func (*Client) CreateCategory added in v1.3.0 

func (c *Client) CreateCategory(ctx context.Context, projectID int, name string, colorID string) (int, error)

CreateCategory creates a new category and returns its ID.

func (*Client) CreateComment 

func (c *Client) CreateComment(ctx context.Context, taskID, userID int, content string) (*Comment, error)

CreateComment creates a new comment on a task and returns the created comment.

func (*Client) CreateTag 

func (c *Client) CreateTag(ctx context.Context, projectID int, name, colorID string) (int, error)

CreateTag creates a new tag in a project and returns the tag ID.

func (*Client) CreateTask 

func (c *Client) CreateTask(ctx context.Context, req CreateTaskRequest) (*Task, error)

CreateTask creates a new task and returns the created task.

func (*Client) CreateTaskFile 

func (c *Client) CreateTaskFile(ctx context.Context, projectID, taskID int, filename string, content []byte) (int, error)

CreateTaskFile uploads a file to a task. The file content is automatically base64 encoded. Returns the ID of the created file. 

func (c *Client) CreateTaskLink(ctx context.Context, taskID, oppositeTaskID, linkID int) (int, error)

CreateTaskLink creates a link between two tasks. The linkID specifies the type of relationship (e.g., "blocks", "is blocked by"). Returns the ID of the created link.

func (*Client) DownloadTaskFile 

func (c *Client) DownloadTaskFile(ctx context.Context, fileID int) ([]byte, error)

DownloadTaskFile downloads a file's content by its ID. The content is returned as raw bytes (decoded from base64).

func (*Client) GetAllCategories 

func (c *Client) GetAllCategories(ctx context.Context, projectID int) ([]Category, error)

GetAllCategories returns all categories for a project.

func (*Client) GetAllComments 

func (c *Client) GetAllComments(ctx context.Context, taskID int) ([]Comment, error)

GetAllComments returns all comments for a task.

func (*Client) GetAllProjects 

func (c *Client) GetAllProjects(ctx context.Context) ([]Project, error)

GetAllProjects returns all projects accessible to the authenticated user.

func (*Client) GetAllTags 

func (c *Client) GetAllTags(ctx context.Context) ([]Tag, error)

GetAllTags returns all tags in the system.

func (*Client) GetAllTaskFiles 

func (c *Client) GetAllTaskFiles(ctx context.Context, taskID int) ([]TaskFile, error)

GetAllTaskFiles returns all files attached to a task. 

func (c *Client) GetAllTaskLinks(ctx context.Context, taskID int) ([]TaskLink, error)

GetAllTaskLinks returns all links for a task.

func (*Client) GetAllTasks 

func (c *Client) GetAllTasks(ctx context.Context, projectID int, status TaskStatus) ([]Task, error)

GetAllTasks returns all tasks for a project with the specified status.

func (*Client) GetCategory 

func (c *Client) GetCategory(ctx context.Context, categoryID int) (*Category, error)

GetCategory returns a category by its ID. Returns ErrCategoryNotFound if the category does not exist.

func (*Client) GetCategoryByName added in v1.3.0 

func (c *Client) GetCategoryByName(ctx context.Context, projectID int, name string) (*Category, error)

GetCategoryByName returns a category by name within a project. Returns ErrCategoryNotFound if no category matches.

func (*Client) GetColorList added in v1.0.1 

func (c *Client) GetColorList(ctx context.Context) (map[string]string, error)

GetColorList returns the available task colors. Returns a map of color_id to display name (e.g., "yellow" -> "Yellow").

func (*Client) GetColumn 

func (c *Client) GetColumn(ctx context.Context, columnID int) (*Column, error)

GetColumn returns a column by its ID. Returns ErrColumnNotFound if the column does not exist.

func (*Client) GetColumns 

func (c *Client) GetColumns(ctx context.Context, projectID int) ([]Column, error)

GetColumns returns all columns for a project, sorted by position.

func (*Client) GetComment 

func (c *Client) GetComment(ctx context.Context, commentID int) (*Comment, error)

GetComment returns a comment by its ID. Returns ErrCommentNotFound if the comment does not exist.

func (*Client) GetProjectByID 

func (c *Client) GetProjectByID(ctx context.Context, projectID int) (*Project, error)

GetProjectByID returns a project by its ID. Returns ErrProjectNotFound if the project does not exist.

func (*Client) GetProjectByName 

func (c *Client) GetProjectByName(ctx context.Context, name string) (*Project, error)

GetProjectByName returns a project by its name. Returns ErrProjectNotFound if the project does not exist.

func (*Client) GetTagsByProject 

func (c *Client) GetTagsByProject(ctx context.Context, projectID int) ([]Tag, error)

GetTagsByProject returns all tags for a specific project.

func (*Client) GetTask 

func (c *Client) GetTask(ctx context.Context, taskID int) (*Task, error)

GetTask returns a task by its ID. Returns ErrTaskNotFound if the task does not exist.

func (*Client) GetTaskByReference added in v1.4.0 

func (c *Client) GetTaskByReference(ctx context.Context, projectID int, reference string) (*Task, error)

GetTaskByReference returns a task by its external reference within a project. Returns ErrTaskNotFound if no task matches the reference.

func (*Client) GetTaskFile added in v1.1.0 

func (c *Client) GetTaskFile(ctx context.Context, fileID int) (*TaskFile, error)

GetTaskFile returns a single file's metadata by its ID.

func (*Client) GetTaskTags 

func (c *Client) GetTaskTags(ctx context.Context, taskID int) (map[int]string, error)

GetTaskTags returns the tags assigned to a task as a map of tagID to tag name.

func (*Client) GetTimezone added in v1.5.0 

func (c *Client) GetTimezone(ctx context.Context) (string, error)

GetTimezone returns the server's configured timezone string (e.g., "UTC", "Europe/Berlin").

func (*Client) MoveTaskPosition 

func (c *Client) MoveTaskPosition(ctx context.Context, projectID, taskID, columnID, position, swimlaneID int) error

MoveTaskPosition moves a task to a specific position within a column and swimlane. Use position=1 for first position, position=0 to append at end.

func (*Client) MoveTaskToProject 

func (c *Client) MoveTaskToProject(ctx context.Context, taskID, projectID int) error

MoveTaskToProject moves a task to a different project.

func (*Client) OpenTask 

func (c *Client) OpenTask(ctx context.Context, taskID int) error

OpenTask opens a task (sets it to active). Returns ErrTaskOpen if the task is already open.

func (*Client) RemoveAllTaskFiles added in v1.1.0 

func (c *Client) RemoveAllTaskFiles(ctx context.Context, taskID int) error

RemoveAllTaskFiles removes all files attached to a task.

func (*Client) RemoveCategory added in v1.3.0 

func (c *Client) RemoveCategory(ctx context.Context, categoryID int) error

RemoveCategory deletes a category.

func (*Client) RemoveComment 

func (c *Client) RemoveComment(ctx context.Context, commentID int) error

RemoveComment deletes a comment.

func (*Client) RemoveTag 

func (c *Client) RemoveTag(ctx context.Context, tagID int) error

RemoveTag deletes a tag from the system.

func (*Client) RemoveTaskFile 

func (c *Client) RemoveTaskFile(ctx context.Context, fileID int) error

RemoveTaskFile deletes a file from a task. 

func (c *Client) RemoveTaskLink(ctx context.Context, taskLinkID int) error

RemoveTaskLink deletes a task link.

func (*Client) SearchTasks 

func (c *Client) SearchTasks(ctx context.Context, projectID int, query string) ([]Task, error)

SearchTasks searches for tasks in a project using Kanboard's query syntax. The query supports filters like: status:open, assignee:me, color:red, etc.

func (*Client) SearchTasksGlobally 

func (c *Client) SearchTasksGlobally(ctx context.Context, query string) ([]Task, error)

SearchTasksGlobally searches for tasks across all accessible projects. The search is executed in parallel across all projects using errgroup. If any project search fails, all ongoing searches are cancelled.

func (*Client) SetTaskTags 

func (c *Client) SetTaskTags(ctx context.Context, projectID, taskID int, tags []string) error

SetTaskTags sets the tags for a task, replacing all existing tags. Tags are specified by name. Non-existent tags will be auto-created.

func (*Client) Task 

func (c *Client) Task(taskID int) *TaskScope

Task returns a TaskScope for fluent task-scoped operations.

func (*Client) UpdateCategory added in v1.3.0 

func (c *Client) UpdateCategory(ctx context.Context, categoryID int, name string, colorID string) error

UpdateCategory updates a category's name and optionally its color.

func (*Client) UpdateComment 

func (c *Client) UpdateComment(ctx context.Context, commentID int, content string) error

UpdateComment updates the content of a comment.

func (*Client) UpdateTag 

func (c *Client) UpdateTag(ctx context.Context, tagID int, name, colorID string) error

UpdateTag updates an existing tag's name and/or color.

func (*Client) UpdateTask 

func (c *Client) UpdateTask(ctx context.Context, req UpdateTaskRequest) error

UpdateTask updates an existing task. Only non-nil fields in the request will be updated.

func (*Client) UpdateTaskFromParams 

func (c *Client) UpdateTaskFromParams(ctx context.Context, taskID int, params *TaskUpdateParams) error

UpdateTaskFromParams updates an existing task using TaskUpdateParams. This provides a fluent interface for task updates.

func (*Client) WithAPIToken 

func (c *Client) WithAPIToken(token string) *Client

WithAPIToken configures the client to use API token authentication. Uses "jsonrpc" as the username for HTTP Basic Auth.

func (*Client) WithAPITokenUser 

func (c *Client) WithAPITokenUser(token, user string) *Client

WithAPITokenUser configures the client to use API token authentication with a custom username. If user is empty, "jsonrpc" will be used as the default.

func (*Client) WithAuthHeader 

func (c *Client) WithAuthHeader(headerName string) *Client

WithAuthHeader configures a custom header name for authentication. If not set, the standard "Authorization" header is used. This must be called before configuring authentication (WithAPIToken, WithBasicAuth, etc.). Example: WithAuthHeader("X-API-Auth")

func (*Client) WithBasicAuth 

func (c *Client) WithBasicAuth(username, password string) *Client

WithBasicAuth configures the client to use username/password authentication.

func (*Client) WithHTTPClient 

func (c *Client) WithHTTPClient(client *http.Client) *Client

WithHTTPClient sets a custom HTTP client. This replaces the default client entirely, including timeout and redirect settings. Note: The custom client's CheckRedirect handler will be used instead of the built-in redirect handler that preserves authentication headers.

func (*Client) WithLogger 

func (c *Client) WithLogger(logger *slog.Logger) *Client

WithLogger sets the logger for debug output. If set, the client will log request/response details at debug level.

func (*Client) WithTimeout 

func (c *Client) WithTimeout(timeout time.Duration) *Client

WithTimeout sets the HTTP client timeout. This creates a new HTTP client with the specified timeout.

func (*Client) WithTimezone added in v1.5.0 

func (c *Client) WithTimezone() *Client

WithTimezone enables automatic timestamp conversion. On the first API call, the client fetches the server's timezone via getTimezone and converts all Timestamp fields in responses to that timezone.

type Column 

type Column struct {
	ID          StringInt `json:"id"`
	Title       string    `json:"title"`
	Position    StringInt `json:"position"`
	ProjectID   StringInt `json:"project_id"`
	TaskLimit   StringInt `json:"task_limit"`
	Description string    `json:"description"`
}

Column represents a Kanboard column.

type Comment 

type Comment struct {
	ID           StringInt `json:"id"`
	TaskID       StringInt `json:"task_id"`
	UserID       StringInt `json:"user_id"`
	DateCreation Timestamp `json:"date_creation"`
	Content      string    `json:"comment"`
	Username     string    `json:"username"`
	Name         string    `json:"name"`
	Email        string    `json:"email"`
	AvatarPath   string    `json:"avatar_path"`
}

Comment represents a Kanboard comment.

type CreateTaskRequest 

type CreateTaskRequest struct {
	Title               string   `json:"title"`
	ProjectID           int      `json:"project_id"`
	Description         string   `json:"description,omitempty"`
	ColumnID            int      `json:"column_id,omitempty"`
	OwnerID             int      `json:"owner_id,omitempty"`
	CreatorID           int      `json:"creator_id,omitempty"`
	ColorID             string   `json:"color_id,omitempty"`
	CategoryID          int      `json:"category_id,omitempty"`
	DateDue             int64    `json:"date_due,omitempty"`
	Score               int      `json:"score,omitempty"`
	SwimlaneID          int      `json:"swimlane_id,omitempty"`
	Priority            int      `json:"priority,omitempty"`
	Reference           string   `json:"reference,omitempty"`
	Tags                []string `json:"tags,omitempty"`
	DateStarted         int64    `json:"date_started,omitempty"`
	RecurrenceStatus    int      `json:"recurrence_status,omitempty"`
	RecurrenceTrigger   int      `json:"recurrence_trigger,omitempty"`
	RecurrenceFactor    int      `json:"recurrence_factor,omitempty"`
	RecurrenceTimeframe int      `json:"recurrence_timeframe,omitempty"`
	RecurrenceBasedate  int      `json:"recurrence_basedate,omitempty"`
}

CreateTaskRequest is the request payload for creating a task.

type IntOrFalse 

type IntOrFalse int

IntOrFalse is an int that can be unmarshaled from a JSON int or false. Kanboard API returns false on failure, int (ID) on success for create operations.

func (*IntOrFalse) UnmarshalJSON 

func (i *IntOrFalse) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type JSONRPCError 

type JSONRPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

JSONRPCError represents a JSON-RPC 2.0 error.

func (*JSONRPCError) Error 

func (e *JSONRPCError) Error() string

Error implements the error interface.

type JSONRPCRequest 

type JSONRPCRequest struct {
	JSONRPC string      `json:"jsonrpc"`
	Method  string      `json:"method"`
	ID      int64       `json:"id"`
	Params  interface{} `json:"params,omitempty"`
}

JSONRPCRequest represents a JSON-RPC 2.0 request.

type JSONRPCResponse 

type JSONRPCResponse struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int64           `json:"id"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *JSONRPCError   `json:"error,omitempty"`
}

JSONRPCResponse represents a JSON-RPC 2.0 response.

type OperationFailedError added in v1.0.1 

type OperationFailedError struct {
	Operation string
	Hints     []string
}

OperationFailedError represents an API operation that returned false without details. The Kanboard API often returns only true/false without explaining why an operation failed.

func (*OperationFailedError) Error added in v1.0.1 

func (e *OperationFailedError) Error() string

Error implements the error interface.

type Project 

type Project struct {
	ID                  StringInt  `json:"id"`
	Name                string     `json:"name"`
	Description         string     `json:"description"`
	IsActive            StringBool `json:"is_active"`
	Token               string     `json:"token"`
	LastModified        Timestamp  `json:"last_modified"`
	IsPublic            StringBool `json:"is_public"`
	IsPrivate           StringBool `json:"is_private"`
	DefaultSwimlane     string     `json:"default_swimlane"`
	ShowDefaultSwimlane StringBool `json:"show_default_swimlane"`
	Identifier          string     `json:"identifier"`
	StartDate           Timestamp  `json:"start_date"`
	EndDate             Timestamp  `json:"end_date"`
	OwnerID             StringInt  `json:"owner_id"`
	PriorityDefault     StringInt  `json:"priority_default"`
	PriorityStart       StringInt  `json:"priority_start"`
	PriorityEnd         StringInt  `json:"priority_end"`
	Email               string     `json:"email"`
}

Project represents a Kanboard project (board).

type StringBool 

type StringBool bool

StringBool is a bool that can be unmarshaled from a string "0" or "1".

func (StringBool) MarshalJSON 

func (b StringBool) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*StringBool) UnmarshalJSON 

func (b *StringBool) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type StringInt 

type StringInt int

StringInt is an int that can be unmarshaled from a JSON string.

func (*StringInt) UnmarshalJSON 

func (i *StringInt) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type StringInt64 

type StringInt64 int64

StringInt64 is an int64 that can be unmarshaled from a JSON string.

func (*StringInt64) UnmarshalJSON 

func (i *StringInt64) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Tag 

type Tag struct {
	ID        StringInt `json:"id"`
	Name      string    `json:"name"`
	ProjectID StringInt `json:"project_id"`
	ColorID   string    `json:"color_id"`
}

Tag represents a Kanboard tag.

type Task 

type Task struct {
	ID                  StringInt  `json:"id"`
	Title               string     `json:"title"`
	Description         string     `json:"description"`
	DateCreation        Timestamp  `json:"date_creation"`
	DateModification    Timestamp  `json:"date_modification"`
	DateCompleted       Timestamp  `json:"date_completed"`
	DateStarted         Timestamp  `json:"date_started"`
	DateDue             Timestamp  `json:"date_due"`
	DateMoved           Timestamp  `json:"date_moved"`
	ColorID             string     `json:"color_id"`
	ProjectID           StringInt  `json:"project_id"`
	ColumnID            StringInt  `json:"column_id"`
	OwnerID             StringInt  `json:"owner_id"`
	CreatorID           StringInt  `json:"creator_id"`
	Position            StringInt  `json:"position"`
	IsActive            StringBool `json:"is_active"`
	Score               StringInt  `json:"score"`
	CategoryID          StringInt  `json:"category_id"`
	SwimlaneID          StringInt  `json:"swimlane_id"`
	Priority            StringInt  `json:"priority"`
	Reference           string     `json:"reference"`
	RecurrenceStatus    StringInt  `json:"recurrence_status"`
	RecurrenceTrigger   StringInt  `json:"recurrence_trigger"`
	RecurrenceFactor    StringInt  `json:"recurrence_factor"`
	RecurrenceTimeframe StringInt  `json:"recurrence_timeframe"`
	RecurrenceBasedate  StringInt  `json:"recurrence_basedate"`
	RecurrenceParent    StringInt  `json:"recurrence_parent"`
	RecurrenceChild     StringInt  `json:"recurrence_child"`
}

Task represents a Kanboard task.

type TaskFile 

type TaskFile struct {
	ID           StringInt   `json:"id"`
	Name         string      `json:"name"`
	Path         string      `json:"path"`
	IsImage      StringBool  `json:"is_image"`
	TaskID       StringInt   `json:"task_id"`
	DateCreation Timestamp   `json:"date_creation"`
	UserID       StringInt   `json:"user_id"`
	Size         StringInt64 `json:"size"`
	Username     string      `json:"username"`  // Only returned by getAllTaskFiles
	UserName     string      `json:"user_name"` // Only returned by getAllTaskFiles
}

TaskFile represents a file attached to a task. 

type TaskLink struct {
	ID             StringInt `json:"id"`
	LinkID         StringInt `json:"link_id"`
	TaskID         StringInt `json:"task_id"`
	OppositeTaskID StringInt `json:"opposite_task_id"`
	Label          string    `json:"label"`
	Title          string    `json:"title"`
}

TaskLink represents a link between two tasks.

type TaskParams 

type TaskParams struct {
	// contains filtered or unexported fields
}

TaskParams is a fluent builder for task creation configuration. It is a pure configuration object with no I/O.

func NewTask 

func NewTask(title string) *TaskParams

NewTask creates a new TaskParams with the given title.

func (*TaskParams) InColumn 

func (p *TaskParams) InColumn(columnID int) *TaskParams

InColumn sets the column ID for the task.

func (*TaskParams) InSwimlane 

func (p *TaskParams) InSwimlane(swimlaneID int) *TaskParams

InSwimlane sets the swimlane ID for the task.

func (*TaskParams) WithCategory 

func (p *TaskParams) WithCategory(categoryID int) *TaskParams

WithCategory sets the category ID for the task.

func (*TaskParams) WithColor 

func (p *TaskParams) WithColor(colorID string) *TaskParams

WithColor sets the color ID for the task.

func (*TaskParams) WithCreator 

func (p *TaskParams) WithCreator(creatorID int) *TaskParams

WithCreator sets the creator ID for the task.

func (*TaskParams) WithDescription 

func (p *TaskParams) WithDescription(desc string) *TaskParams

WithDescription sets the task description.

func (*TaskParams) WithDueDate 

func (p *TaskParams) WithDueDate(date time.Time) *TaskParams

WithDueDate sets the due date for the task.

func (*TaskParams) WithOwner 

func (p *TaskParams) WithOwner(ownerID int) *TaskParams

WithOwner sets the owner (assignee) ID for the task.

func (*TaskParams) WithPriority 

func (p *TaskParams) WithPriority(priority int) *TaskParams

WithPriority sets the priority for the task.

func (*TaskParams) WithReference 

func (p *TaskParams) WithReference(ref string) *TaskParams

WithReference sets the external reference for the task.

func (*TaskParams) WithScore 

func (p *TaskParams) WithScore(score int) *TaskParams

WithScore sets the complexity score for the task.

func (*TaskParams) WithStartDate 

func (p *TaskParams) WithStartDate(date time.Time) *TaskParams

WithStartDate sets the start date for the task.

func (*TaskParams) WithTags 

func (p *TaskParams) WithTags(tags ...string) *TaskParams

WithTags sets the tags for the task.

type TaskScope 

type TaskScope struct {
	// contains filtered or unexported fields
}

TaskScope provides fluent task-scoped operations.

func (*TaskScope) AddComment 

func (t *TaskScope) AddComment(ctx context.Context, userID int, content string) (*Comment, error)

AddComment adds a comment to this task and returns the created comment. The userID is the ID of the user creating the comment.

func (*TaskScope) AddTag 

func (t *TaskScope) AddTag(ctx context.Context, tag string) error

AddTag adds a tag to this task using a read-modify-write pattern. If the tag already exists on the task, this is a no-op (idempotent).

WARNING: This operation is not atomic. Concurrent tag modifications may cause data loss.

func (*TaskScope) ClearTags 

func (t *TaskScope) ClearTags(ctx context.Context) error

ClearTags removes all tags from this task.

WARNING: This operation is not atomic. Concurrent tag modifications may cause data loss.

func (*TaskScope) Close 

func (t *TaskScope) Close(ctx context.Context) error

Close closes the task (sets it to inactive).

func (*TaskScope) DownloadFile added in v1.1.0 

func (t *TaskScope) DownloadFile(ctx context.Context, fileID int) ([]byte, error)

DownloadFile downloads a file's content by ID.

func (*TaskScope) Get 

func (t *TaskScope) Get(ctx context.Context) (*Task, error)

Get returns the task.

func (*TaskScope) GetComments 

func (t *TaskScope) GetComments(ctx context.Context) ([]Comment, error)

GetComments returns all comments for this task.

func (*TaskScope) GetFile added in v1.1.0 

func (t *TaskScope) GetFile(ctx context.Context, fileID int) (*TaskFile, error)

GetFile returns a file's metadata by ID.

func (*TaskScope) GetFiles 

func (t *TaskScope) GetFiles(ctx context.Context) ([]TaskFile, error)

GetFiles returns all files attached to this task. 

func (t *TaskScope) GetLinks(ctx context.Context) ([]TaskLink, error)

GetLinks returns all links for this task.

func (*TaskScope) GetTags 

func (t *TaskScope) GetTags(ctx context.Context) (map[int]string, error)

GetTags returns the tags assigned to this task as a map of tagID to tag name.

func (*TaskScope) HasTag 

func (t *TaskScope) HasTag(ctx context.Context, tag string) (bool, error)

HasTag checks if this task has a specific tag.

func (*TaskScope) LinkTo 

func (t *TaskScope) LinkTo(ctx context.Context, oppositeTaskID, linkID int) error

LinkTo creates a link from this task to another task. The linkID specifies the type of relationship (e.g., "blocks", "is blocked by").

func (*TaskScope) MoveToColumn 

func (t *TaskScope) MoveToColumn(ctx context.Context, columnID int) error

MoveToColumn moves the task to a different column. The task is placed at the end of the column (position=0). Requires the project ID to be fetched from the task.

func (*TaskScope) MoveToNextColumn 

func (t *TaskScope) MoveToNextColumn(ctx context.Context) error

MoveToNextColumn moves the task to the next column in the workflow. Columns are ordered by their position field. Returns ErrAlreadyInLastColumn if the task is already in the last column.

func (*TaskScope) MoveToPreviousColumn 

func (t *TaskScope) MoveToPreviousColumn(ctx context.Context) error

MoveToPreviousColumn moves the task to the previous column in the workflow. Columns are ordered by their position field. Returns ErrAlreadyInFirstColumn if the task is already in the first column.

func (*TaskScope) MoveToProject 

func (t *TaskScope) MoveToProject(ctx context.Context, projectID int) error

MoveToProject moves the task to a different project.

func (*TaskScope) Open 

func (t *TaskScope) Open(ctx context.Context) error

Open opens the task (sets it to active).

func (*TaskScope) RemoveAllFiles added in v1.1.0 

func (t *TaskScope) RemoveAllFiles(ctx context.Context) error

RemoveAllFiles removes all files from this task.

func (*TaskScope) RemoveFile added in v1.1.0 

func (t *TaskScope) RemoveFile(ctx context.Context, fileID int) error

RemoveFile removes a file by ID.

func (*TaskScope) RemoveTag 

func (t *TaskScope) RemoveTag(ctx context.Context, tag string) error

RemoveTag removes a tag from this task using a read-modify-write pattern. If the tag doesn't exist on the task, this is a no-op (idempotent).

WARNING: This operation is not atomic. Concurrent tag modifications may cause data loss.

func (*TaskScope) SetTags 

func (t *TaskScope) SetTags(ctx context.Context, tags ...string) error

SetTags sets the tags for this task, replacing all existing tags. Tags are specified by name. Non-existent tags will be auto-created.

WARNING: This operation is not atomic. Concurrent tag modifications may cause data loss.

func (*TaskScope) Update 

func (t *TaskScope) Update(ctx context.Context, params *TaskUpdateParams) error

Update updates the task using TaskUpdateParams.

func (*TaskScope) UploadFile 

func (t *TaskScope) UploadFile(ctx context.Context, filename string, content []byte) (int, error)

UploadFile uploads a file to this task and returns the file ID. The file content is automatically base64 encoded.

type TaskStatus 

type TaskStatus int

TaskStatus represents the status of a task. 

const (
	// StatusActive represents an open/active task.
	StatusActive TaskStatus = 1
	// StatusInactive represents a closed/inactive task.
	StatusInactive TaskStatus = 0
)

type TaskUpdateParams 

type TaskUpdateParams struct {
	// contains filtered or unexported fields
}

TaskUpdateParams is a fluent builder for task update configuration. Only set fields are included in the update request.

func NewTaskUpdate 

func NewTaskUpdate() *TaskUpdateParams

NewTaskUpdate creates a new TaskUpdateParams.

func (*TaskUpdateParams) ClearCategory 

func (p *TaskUpdateParams) ClearCategory() *TaskUpdateParams

ClearCategory removes the category from the task.

func (*TaskUpdateParams) ClearDueDate 

func (p *TaskUpdateParams) ClearDueDate() *TaskUpdateParams

ClearDueDate clears the due date from the task.

func (*TaskUpdateParams) ClearOwner 

func (p *TaskUpdateParams) ClearOwner() *TaskUpdateParams

ClearOwner removes the owner from the task.

func (*TaskUpdateParams) ClearStartDate 

func (p *TaskUpdateParams) ClearStartDate() *TaskUpdateParams

ClearStartDate clears the start date from the task.

func (*TaskUpdateParams) SetCategory 

func (p *TaskUpdateParams) SetCategory(categoryID int) *TaskUpdateParams

SetCategory sets the category ID for the task.

func (*TaskUpdateParams) SetColor 

func (p *TaskUpdateParams) SetColor(colorID string) *TaskUpdateParams

SetColor sets the color ID for the task.

func (*TaskUpdateParams) SetDescription 

func (p *TaskUpdateParams) SetDescription(desc string) *TaskUpdateParams

SetDescription sets the task description.

func (*TaskUpdateParams) SetDueDate 

func (p *TaskUpdateParams) SetDueDate(date time.Time) *TaskUpdateParams

SetDueDate sets the due date for the task.

func (*TaskUpdateParams) SetOwner 

func (p *TaskUpdateParams) SetOwner(ownerID int) *TaskUpdateParams

SetOwner sets the owner (assignee) ID for the task.

func (*TaskUpdateParams) SetPriority 

func (p *TaskUpdateParams) SetPriority(priority int) *TaskUpdateParams

SetPriority sets the priority for the task.

func (*TaskUpdateParams) SetReference 

func (p *TaskUpdateParams) SetReference(ref string) *TaskUpdateParams

SetReference sets the external reference for the task.

func (*TaskUpdateParams) SetScore 

func (p *TaskUpdateParams) SetScore(score int) *TaskUpdateParams

SetScore sets the complexity score for the task.

func (*TaskUpdateParams) SetStartDate 

func (p *TaskUpdateParams) SetStartDate(date time.Time) *TaskUpdateParams

SetStartDate sets the start date for the task.

func (*TaskUpdateParams) SetTags 

func (p *TaskUpdateParams) SetTags(tags ...string) *TaskUpdateParams

SetTags sets the tags for the task. This replaces all existing tags on the task. Call with no arguments to clear all tags.

func (*TaskUpdateParams) SetTitle 

func (p *TaskUpdateParams) SetTitle(title string) *TaskUpdateParams

SetTitle sets the task title.

type Timestamp 

type Timestamp struct {
	time.Time
}

Timestamp wraps time.Time and handles Kanboard's Unix timestamp JSON format. Kanboard returns timestamps as Unix integers, with 0 or empty strings for null values.

func (Timestamp) MarshalJSON 

func (t Timestamp) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler. Returns 0 for zero time, otherwise returns Unix timestamp.

func (*Timestamp) UnmarshalJSON 

func (t *Timestamp) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler. Supports Unix timestamps as integers, empty strings, "0" strings, and zero values.

type UpdateTaskRequest 

type UpdateTaskRequest struct {
	ID                  int      `json:"id"`
	Title               *string  `json:"title,omitempty"`
	Description         *string  `json:"description,omitempty"`
	ColorID             *string  `json:"color_id,omitempty"`
	OwnerID             *int     `json:"owner_id,omitempty"`
	CategoryID          *int     `json:"category_id,omitempty"`
	DateDue             *int64   `json:"date_due,omitempty"`
	Score               *int     `json:"score,omitempty"`
	Priority            *int     `json:"priority,omitempty"`
	Reference           *string  `json:"reference,omitempty"`
	DateStarted         *int64   `json:"date_started,omitempty"`
	RecurrenceStatus    *int     `json:"recurrence_status,omitempty"`
	RecurrenceTrigger   *int     `json:"recurrence_trigger,omitempty"`
	RecurrenceFactor    *int     `json:"recurrence_factor,omitempty"`
	RecurrenceTimeframe *int     `json:"recurrence_timeframe,omitempty"`
	RecurrenceBasedate  *int     `json:"recurrence_basedate,omitempty"`
	Tags                []string `json:"tags,omitempty"`
}

UpdateTaskRequest is the request payload for updating a task. Pointer fields allow distinguishing between "not set" and "set to zero value".

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
Example: basic demonstrates basic client setup and simple operations.
 Example: basic demonstrates basic client setup and simple operations.
fluent command
Example: fluent demonstrates the fluent API for task management.
 Example: fluent demonstrates the fluent API for task management.
search command
Example: search demonstrates search functionality.
 Example: search demonstrates search functionality.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.