diff --git a/.claude/skills/client-lib-conventions/SKILL.md b/.claude/skills/client-lib-conventions/SKILL.md deleted file mode 100644 index 18e1d91..0000000 --- a/.claude/skills/client-lib-conventions/SKILL.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: client-lib-conventions -description: Use when writing, extending, reviewing, or scaffolding this Go HTTP-JSON client library — the shared Denis Shaporov / acidsailor API-design conventions (service facades, value request / pointer response, NewClient, prefix-free method naming, restkit error aliases, oapi-codegen models-only). ---- - -# Client-library API conventions - -Apply these when adding or changing the API surface of this library. - -## Constructor -`NewClient(...) (*Client, error)` with functional options (`Option`, or -`ClientOption` when a generated model already claims the name `Option`). - -## Service grouping (multi-resource clients) -Group methods into service facades exposed as **pointer fields** on `*Client`: - -```go -client.Orders.Get(ctx, req) -``` - -The facade is an unexported `type ordersService struct{ c *Client }`, held as a -`*ordersService` field, wired once in `NewClient`, with **pointer receivers** -(`func (s *ordersService) ...`). A small single-purpose client with no resource -taxonomy stays flat (methods directly on `*Client`). - -## Method signatures -`(ctx context.Context, req XxxRequest) (*XxxResponse, error)`: - -- `context.Context` first. -- Request passed **by value** (`req XxxRequest`); no variadic options. -- Response returned as a **pointer** (`*T`). - -## Returns -- Single object → `*T`. -- Collection → `[]T` (never `[]*T`). - -## Naming -- Methods drop the redundant resource prefix: `GetOrder`→`Get`, `GetOrders`→`List`, - `PlaceOrder`→`Place`. Keep the original meaning otherwise. -- Request structs: `Request` (faceted) / `Request` (flat). -- Response DTOs keep their generated names (do not rename oapi-codegen output). - -## Errors & transport -Re-export `restkit`'s typed errors as aliases (`ResponseError`, `RequestError`, -`ConfigError`) plus the `Op*` stage constants; no sentinel errors — the typed -error is the category, matched with `errors.As`. Models are generated by -oapi-codegen (models-only); never hand-edit `models.gen.go`.