AGENTS.md@pkg/providers · diff
git:20260715.158c111 to git:20260724.cb0170c
10 added, 31 removed. Audit A to A.
# Providers Guide
- Third-party service integrations with standardized OAuth and API patterns.
-
- ## Structure
-
- ```
- providers/
- ├── providers.go # OAuthProvider, GetConfig, RedirectURI, RegisterOAuthProvider, …
- ├── example/ # Reference implementation — follow this for new providers
- │ ├── example.go # Provider struct, GetClient(), NewXxx(), CRUD, OAuth methods
- │ ├── types.go # Request/response/webhook-payload types
- │ └── example_test.go # TDD unit tests (table-driven, httptest mock)
- └── <service>/
- ├── <service>.go # Provider implementation (preferred; name may vary, e.g. adguard_home.go)
- ├── types.go # Service-specific types (optional for tiny clients)
- └── <service>_test.go
- ```
+ Third-party API/OAuth clients. Configure under `flowbot.yaml` → `providers.<name>`.
- ## Patterns
+ ## Entry points
- - **Reference implementation**: When creating or modifying a provider, reference `pkg/providers/example/` for file structure, naming, and code style.
- - Configure via `flowbot.yaml` under `providers.<name>`.
- - OAuth providers implement `GetAuthorizeURL` / `GetAccessToken`. See `example/example.go` for the OAuth method reference.
- - Production OAuth providers also export `Register()` → `providers.RegisterOAuthProvider(ID, factory)` and wire via `fx.Invoke` in `internal/server/providers.go` (currently: github, slack, dropbox). The `example` package demonstrates OAuth methods but does **not** export `Register()` / fx wiring.
- - Constructor pattern: `GetClient()` reads config via `providers.GetConfig()` then calls `NewXxx()`. See `example/example.go` for the full pattern.
- - `GetClient()` may return `(*T, error)` when config validation is required; the example returns `*T` directly for simplicity.
- - Not all providers implement OAuth — token/API-key providers skip `Register()` and `fx.Invoke` wiring.
+ - Shared: `providers.go` (`GetConfig`, `RegisterOAuthProvider`, …)
+ - Reference: `example/` (`GetClient` / `NewXxx`, OAuth methods, httptest tests)
+ - Per service: `<service>/` — preferred `<service>.go` + optional `types.go`
- ## Rules
+ ## Boundaries
- - Never hardcode credentials
- - Never ignore rate limits
- - Always handle API errors gracefully
- - Always use context for timeouts
+ - OAuth production providers export `Register()` and wire via `fx.Invoke` in `internal/server/providers.go` (github, slack, dropbox). `example` shows OAuth methods but does **not** export `Register()`
+ - Token/API-key providers skip OAuth `Register` / fx wiring
+ - Never hardcode credentials; respect rate limits; use context timeouts
## Testing
- - Mock HTTP clients with `httptest`
- - Test auth flows separately from API calls
+ Mock with `httptest`; separate auth flows from API calls.