1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7# go-lunatask
  8
  9[![Godocs.io Reference](https://godocs.io/git.secluded.site/go-lunatask?status.svg)][godocs.io]
 10[![Pkg.go.dev Reference](https://pkg.go.dev/badge/git.secluded.site/go-lunatask.svg)][pkg.go.dev]
 11[![Go Report Card](https://goreportcard.com/badge/git.secluded.site/go-lunatask)](https://goreportcard.com/report/git.secluded.site/go-lunatask)
 12![Test coverage](https://img.shields.io/badge/coverage-84.9%25-brightgreen)
 13[![REUSE compatibility](https://api.reuse.software/badge/git.secluded.site/go-lunatask)](https://api.reuse.software/info/git.secluded.site/go-lunatask)
 14[![Liberapay donation status](https://img.shields.io/liberapay/receives/Amolith.svg?logo=liberapay)](https://liberapay.com/Amolith/)
 15
 16[godocs.io]: https://godocs.io/git.secluded.site/go-lunatask
 17[pkg.go.dev]: https://pkg.go.dev/git.secluded.site/go-lunatask
 18
 19Go client library for [Lunatask]'s [public API].
 20
 21[Lunatask]: https://lunatask.app
 22[public API]: https://lunatask.app/api
 23
 24[lune](https://git.secluded.site/lune), a CLI and MCP server for Lunatask, is
 25this library's primary consumer.
 26
 27## Usage
 28
 29Generate an access token in the Lunatask desktop app under `Settings` →
 30`Access tokens`.
 31
 32```sh
 33go get git.secluded.site/go-lunatask@latest
 34```
 35
 36See the module documentation on [godocs.io] or [pkg.go.dev] for more
 37detail.
 38
 39```go
 40package main
 41
 42import (
 43	"context"
 44	"log"
 45	"os"
 46
 47	"git.secluded.site/go-lunatask"
 48)
 49
 50func main() {
 51	client := lunatask.NewClient(os.Getenv("LUNATASK_TOKEN"), lunatask.UserAgent("MyApp/1.0"))
 52
 53	// Verify credentials
 54	if _, err := client.Ping(context.Background()); err != nil {
 55		log.Fatal(err)
 56	}
 57
 58	// Create a task
 59	task, err := client.NewTask("Review pull requests").Create(context.Background())
 60	if err != nil {
 61		log.Fatal(err)
 62	}
 63	if task == nil {
 64		log.Println("Task already exists")
 65	}
 66}
 67```
 68
 69### A note on duplicate handling
 70
 71Create methods return `(nil, nil)` when a matching entity already
 72exists. This is intentional API behavior on Lunatask's part because of
 73its end-to-end encryption.
 74
 75```go
 76task, err := client.NewTask("Review PR").Create(ctx)
 77if err != nil {
 78    return err // actual error
 79}
 80if task == nil {
 81    // duplicate exists, not created
 82}
 83```
 84
 85## Contributions
 86
 87Patch requests are in [amolith/go-lunatask] on [pr.pico.sh]. You don't
 88need a new account to contribute, you don't need to fork this repo, you
 89don't need to fiddle with `git send-email`, you don't need to faff with
 90your email client to get `git request-pull` working...
 91
 92You just need:
 93
 94- Git
 95- SSH
 96- An SSH key
 97
 98```sh
 99# Clone this repo, make your changes, and commit them
100# Create a new patch request with
101git format-patch origin/main --stdout | ssh pr.pico.sh pr create amolith/go-lunatask
102# After potential feedback, submit a revision to an existing patch request with
103git format-patch origin/main --stdout | ssh pr.pico.sh pr add {prID}
104# List patch requests
105ssh pr.pico.sh pr ls amolith/go-lunatask
106```
107
108See "How do Patch Requests work?" on [pr.pico.sh]'s home page for a more
109complete example workflow.
110
111[amolith/go-lunatask]: https://pr.pico.sh/r/amolith/go-lunatask
112[pr.pico.sh]: https://pr.pico.sh
113
114## License
115
116AGPL-3.0-or-later