From 1dc26d76c1a768b0b608ec5a0070369facc27368 Mon Sep 17 00:00:00 2001 From: ysyneu Date: Thu, 8 Oct 2026 23:07:18 -0700 Subject: [PATCH] docs: document auth, pagination and development; fix package doc example - README: badges, links row, OAuth access-token client, ListOptions and SearchAfterCtx pagination, make targets and e2e setup. - doc.go: the example referenced a nonexistent IncidentListRequest type (it is ListIncidentsRequest) and linked the old domain. --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++-- doc.go | 4 ++-- 2 files changed, 53 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9538061..a3a7fde 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ # go-flashduty -The official Go client for the [Flashduty](https://www.flashduty.com) Open API — a thin, typed SDK covering every Flashduty REST endpoint. +[![Go Reference](https://pkg.go.dev/badge/github.com/flashcatcloud/go-flashduty.svg)](https://pkg.go.dev/github.com/flashcatcloud/go-flashduty) +[![CI](https://img.shields.io/github/actions/workflow/status/flashcatcloud/go-flashduty/ci.yml?style=flat-square&branch=main&label=CI)](https://github.com/flashcatcloud/go-flashduty/actions) +[![Release](https://img.shields.io/github/v/tag/flashcatcloud/go-flashduty?style=flat-square&color=24bfa5&label=release)](https://github.com/flashcatcloud/go-flashduty/tags) +[![License](https://img.shields.io/github/license/flashcatcloud/go-flashduty?style=flat-square&color=24bfa5)](LICENSE) -📖 **API reference:** +**go-flashduty** is the official Go SDK for the [Flashduty](https://www.flashduty.com) Open API. Flashduty is an incident management and on-call platform; this client gives Go programs typed access to every public endpoint: incidents, alerts, channels, on-call schedules, status pages, monitors, RUM, and the AI SRE. + +[Website](https://www.flashduty.com) · [API reference](https://docs.flashduty.com/en/openapi/introduction) · [Go package docs](https://pkg.go.dev/github.com/flashcatcloud/go-flashduty) · [Console](https://console.flashcat.cloud) · [Flashduty CLI](https://github.com/flashcatcloud/flashduty-cli) > **Status:** Typed API operations are generated from the Flashduty OpenAPI specification, covered by unit tests, and validated end-to-end against the live API. @@ -47,6 +52,16 @@ func main() { } ``` +## Authentication + +Create an APP key in the [console](https://console.flashcat.cloud) (My → APP Key); the [API reference](https://docs.flashduty.com/en/openapi/introduction) describes the steps. `NewClient` sends it as the `app_key` query parameter. + +To call the API with an OAuth access token instead, use `NewClientWithAccessToken`; it sends `Authorization: Bearer ` and accepts the same options: + +```go +client, err := flashduty.NewClientWithAccessToken(accessToken) +``` + ## Design - **Thin and typed.** Every method maps to exactly one HTTP call and returns `(*T, *Response, error)`. No hidden cross-endpoint enrichment. @@ -69,6 +84,27 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", ) ``` +### Pagination + +List requests embed `ListOptions`. Zero values are omitted, so the server defaults apply (page 1, 20 items). `Response.Total` and `Response.HasNextPage` describe the result set: + +```go +req := &flashduty.ListIncidentsRequest{ListOptions: flashduty.ListOptions{Page: 1, Limit: 100}} +for { + list, resp, err := client.Incidents.List(ctx, req) + if err != nil { + return err + } + handle(list.Items) + if !resp.HasNextPage { + break + } + req.Page++ +} +``` + +Endpoints that support deep pagination return an opaque cursor in `Response.SearchAfterCtx`; pass it back in `ListOptions.SearchAfterCtx` to fetch the next page. + ### Errors and rate limits ```go @@ -135,6 +171,19 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", ) ``` +## Development + +The typed service layer (`services_gen.go`, `models_gen.go`) is generated from the OpenAPI spec vendored in `openapi/`. Don't edit the generated files; change the spec or the generator in `internal/cmd/gen`. + +```bash +make sync-spec # refresh openapi/ from flashduty-docs +make generate # regenerate the typed service layer +make check # fmt, lint, test, build +make e2e # live end-to-end tests; needs FLASHDUTY_E2E_APP_KEY (optional FLASHDUTY_E2E_BASE_URL) +``` + +End-to-end tests create resources with a `gofd-e2e-` prefix and delete them on cleanup; they never modify existing data. + ## Related projects - [Flashduty CLI](https://github.com/flashcatcloud/flashduty-cli) — the `flashduty` command-line tool, built on this SDK, for managing incidents, alerts, on-call and status pages from a terminal ([docs](https://docs.flashduty.com/en/developer/cli)). diff --git a/doc.go b/doc.go index f94cb24..0c4778b 100644 --- a/doc.go +++ b/doc.go @@ -1,5 +1,5 @@ // Package flashduty is the official Go client for the Flashduty Open API -// (https://flashcat.cloud). It is a thin, typed wrapper: every method maps to +// (https://www.flashduty.com). It is a thin, typed wrapper: every method maps to // exactly one HTTP call, returns (*T, *Response, error), and performs no hidden // cross-endpoint enrichment. // @@ -11,7 +11,7 @@ // } // // Endpoints are grouped into services on the client, e.g. -// client.Incidents.List(ctx, &flashduty.IncidentListRequest{...}). Most are POST +// client.Incidents.List(ctx, &flashduty.ListIncidentsRequest{...}). Most are POST // actions; a few read endpoints are GET with query parameters. Services are // added by the code generator; see internal/cmd/gen. //