Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .claude/skills/client-lib-conventions/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
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: `<Service><Method>Request` (faceted) / `<Method>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`.
2 changes: 1 addition & 1 deletion .copier-answers.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY.
_commit: v1.2.1
_commit: v1.5.0
_src_path: gh:acidsailor/go-scaffolds
author: Denis Shaporov / acidsailor
author_email: d@shaporov.dev
Expand Down
5 changes: 3 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ go.work.sum
# Task runner cache
/.task/

# Local agent tooling
/.claude/
# Local agent tooling (keep committed skills, ignore worktrees/settings)
/.claude/*
!/.claude/skills/
/.worktrees/
4 changes: 2 additions & 2 deletions taskfile.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,6 @@ tasks:
- goreleaser release --clean

update:
desc: Pull latest go-scaffolds v1 template tooling (3-way merge; source untouched)
desc: Pull latest go-scaffolds v1 template tooling (3-way merge; source untouched; no prompts)
cmds:
- uvx copier update --vcs-ref v1
- uvx copier update --defaults --vcs-ref v1