Skip to content

Commit 5eb2f12

Browse files
myyramyyra
committed
Initial implementation
1 parent c9e3fa6 commit 5eb2f12

54 files changed

Lines changed: 103052 additions & 1 deletion

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.golangci.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
version: "2"
2+
3+
run:
4+
timeout: 5m
5+
tests: true
6+
skip-dirs:
7+
- internal/revolutapi
8+
9+
linters:
10+
enable:
11+
- asasalint
12+
- asciicheck
13+
- bidichk
14+
- bodyclose
15+
- canonicalheader
16+
- containedctx
17+
- contextcheck
18+
- copyloopvar
19+
- decorder
20+
- dogsled
21+
- durationcheck
22+
- errchkjson
23+
- errname
24+
- errorlint
25+
- exhaustive
26+
- exptostd
27+
- fatcontext
28+
- funcorder
29+
- gocheckcompilerdirectives
30+
- gochecknoinits
31+
- gochecksumtype
32+
- gocognit
33+
- goconst
34+
- gocritic
35+
- gocyclo
36+
- godot
37+
- godox
38+
- goprintffuncname
39+
- gosmopolitan
40+
- grouper
41+
- iface
42+
- importas
43+
- inamedparam
44+
- interfacebloat
45+
- intrange
46+
- ireturn
47+
- loggercheck
48+
- maintidx
49+
- makezero
50+
- misspell
51+
- mnd
52+
- musttag
53+
- nakedret
54+
- nestif
55+
- nilerr
56+
- nilnesserr
57+
- nilnil
58+
- noctx
59+
- nolintlint
60+
- nosprintfhostport
61+
- paralleltest
62+
- perfsprint
63+
- prealloc
64+
- predeclared
65+
- promlinter
66+
- recvcheck
67+
- rowserrcheck
68+
- sloglint
69+
- spancheck
70+
- sqlclosecheck
71+
- staticcheck
72+
- tagalign
73+
- testableexamples
74+
- testpackage
75+
- thelper
76+
- tparallel
77+
- unconvert
78+
- unparam
79+
- usestdlibvars
80+
- usetesting
81+
- wastedassign
82+
- whitespace
83+
- wrapcheck
84+
- zerologlint

‎AGENTS.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Repository Guidelines
2+
3+
This repository provides a Go CLI for Procountor API. The CLI uses alecthomas/kong.
4+
5+
## Core commands
6+
7+
- Build: `just build`
8+
- Run tests: `just test`
9+
- Format: `just format`
10+
- Lint: `just lint`
11+
- Regenerate API client from OpenAPI spec: `just generate`
12+
13+
## Repository layout
14+
15+
- `cmd/procountor/main.go`: minimal binary entrypoint; only calls `cli.Execute(...)`.
16+
- `internal/cli/`: the actual CLI implementation.
17+
- `procountorapi/`: generated ogen client code. Do not hand-edit.
18+
- `internal/apispec/procountor-api.yaml`: source OpenAPI spec.
19+
20+
## Testing
21+
22+
- Write unit tests for all new functionality.
23+
- Before finishing your turn, run `just format`, `just build`, `just test`, and `just lint` and make sure they all pass.

‎README.md‎

Lines changed: 176 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,177 @@
11
# procountor
2-
Procountor client
2+
3+
Lightweight Go CLI for Procountor API operations.
4+
5+
The CLI is a thin wrapper around:
6+
- `internal/apispec/procountor-api.yaml`
7+
- generated ogen client in `procountorapi/`
8+
9+
External consumers can import the generated client directly:
10+
11+
```go
12+
import "github.com/myyra/procountor/procountorapi"
13+
```
14+
15+
All API operations are exposed as explicit Kong commands, grouped by OpenAPI tag.
16+
17+
## Build
18+
19+
```bash
20+
go build ./...
21+
```
22+
23+
Run:
24+
25+
```bash
26+
go run ./cmd/procountor --help
27+
```
28+
29+
## Authentication Model
30+
31+
This CLI uses persisted login state by default.
32+
33+
Run once:
34+
35+
```bash
36+
procountor auth login
37+
```
38+
39+
`auth login` uses `--username`/`--password` (or `PROCOUNTOR_USERNAME`/`PROCOUNTOR_PASSWORD`) and prompts when needed, performs the `/login/companies -> /login` flow, and stores tokens in:
40+
- `$XDG_STATE_HOME/procountor/auth.json`, or
41+
- `~/.local/state/procountor/auth.json` when `XDG_STATE_HOME` is not set.
42+
43+
The stored access token is automatically refreshed via `/token` when expired.
44+
45+
Useful auth commands:
46+
- `procountor auth companies`
47+
- `procountor auth login`
48+
- `procountor auth refresh`
49+
- `procountor auth status`
50+
- `procountor auth logout`
51+
52+
## Global Flags
53+
54+
- `--base-url` or `PROCOUNTOR_BASE_URL`: API base URL.
55+
- Default: `https://nemo.procountor.com/api`
56+
- `--auth-file` or `PROCOUNTOR_AUTH_FILE`: override persisted auth state path.
57+
- `--timeout`: HTTP timeout (default `30s`).
58+
- `--verbose` / `-v`: print raw HTTP requests and responses to stderr.
59+
- Verbose output is dimmed when stderr is a terminal.
60+
- `--output`: output format (`human`, `json`, or `plain`, default `human`).
61+
62+
Login credential env vars:
63+
- `PROCOUNTOR_USERNAME`: username for `auth companies` and `auth login`.
64+
- `PROCOUNTOR_PASSWORD`: password for `auth companies` and `auth login`.
65+
66+
## Request Input
67+
68+
Commands with request bodies use one of two primary models:
69+
- small or patch-shaped bodies use explicit flags
70+
- document-shaped create/replace bodies use command-specific whole-object import flags such as `--invoice`, `--ledger-receipt`, `--business-partner`, and `--cost-receipt`
71+
72+
For flag-shaped commands:
73+
- top-level scalar and enum fields use normal flags
74+
- nested object fields use embedded sub-flags such as `--payment-info.bank-account` and `--options.receipt-name`
75+
76+
Complex object arrays are not assembled through repeatable JSON flags. If you need to author or replace a nested list of objects, use the command's whole-document import flag instead.
77+
78+
Whole-object import always uses an explicit command-specific flag. Bare stdin is never treated as an implicit whole request body.
79+
80+
Use per-command help for the exact flag contract:
81+
- `procountor <group> <command> --help`
82+
83+
Natural single-resource IDs are positional. Examples:
84+
- `procountor invoices get 12345`
85+
- `procountor ledger-receipts transactions update 12345 67890 --account 3000`
86+
- `procountor attachments content 555 --out attachment.pdf`
87+
88+
## Binary Output
89+
90+
Binary endpoints support `--out`:
91+
- `attachments content`
92+
- `invoices image`
93+
94+
If `--out` is omitted, binary bytes are written to stdout.
95+
96+
## Pagination
97+
98+
Paginated search/list commands use `--paginate` and return only the result array (no `meta`/`nemoMeta` envelope).
99+
100+
`--paginate` formats:
101+
- `<limit>` (same as `0:<limit>`)
102+
- `<from>:<limit>`
103+
- `all`
104+
- `<from>:all`
105+
106+
Default: `--paginate 0:200`
107+
108+
## Command Groups
109+
110+
- `auth`
111+
- `attachments`
112+
- `business-partners`
113+
- `chart-of-accounts`
114+
- `company`
115+
- `cost-centers`
116+
- `cost-receipts`
117+
- `dimensions`
118+
- `fiscal-years`
119+
- `invoices`
120+
- `ledger-receipts`
121+
- `persons`
122+
- `products`
123+
- `reports`
124+
- `vats`
125+
126+
Use per-command help for exact flags:
127+
128+
```bash
129+
procountor <group> <command> --help
130+
```
131+
132+
## Schema
133+
134+
Use `schema` with a command path to print that command's JSON request-body schema.
135+
136+
Commands that do not send an `application/json` request body print nothing.
137+
138+
```bash
139+
procountor schema invoices save
140+
procountor schema reports accounting
141+
```
142+
143+
## Examples
144+
145+
```bash
146+
# One-time login (prompts for credentials)
147+
procountor auth login
148+
149+
# Non-interactive login
150+
PROCOUNTOR_USERNAME=my-user PROCOUNTOR_PASSWORD=my-pass procountor auth login
151+
152+
# Search invoices using stored auth
153+
procountor invoices search --status SENT --paginate 50
154+
155+
# Machine-readable JSON output
156+
procountor invoices search --status SENT --paginate 50 --output json
157+
158+
# Get one invoice
159+
procountor invoices get 12345
160+
161+
# Save invoice from command-specific import flag
162+
procountor invoices save --invoice @./invoice.json
163+
164+
# Update one ledger receipt transaction without roundtripping JSON manually
165+
procountor ledger-receipts transactions update 12345 67890 --account 3000
166+
167+
# Download invoice image
168+
procountor invoices image 12345 --format PNG --out ./invoice.png
169+
170+
# Inspect company VAT defaults and a country VAT table
171+
procountor vats settings
172+
procountor vats country --country-code DK
173+
174+
# Show auth status / clear local auth state
175+
procountor auth status
176+
procountor auth logout
177+
```

‎cmd/procountor/main.go‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"os"
6+
7+
"github.com/myyra/procountor/internal/cli"
8+
)
9+
10+
func main() {
11+
os.Exit(cli.Execute(context.Background(), os.Args[1:], os.Stdin, os.Stdout, os.Stderr))
12+
}

‎docs/articles.json‎

Lines changed: 14813 additions & 0 deletions
Large diffs are not rendered by default.

‎go.mod‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
module github.com/myyra/procountor
2+
3+
go 1.25
4+
5+
require (
6+
github.com/alecthomas/kong v1.14.0
7+
github.com/fatih/color v1.18.0
8+
github.com/go-faster/errors v0.7.1
9+
github.com/go-faster/jx v1.2.0
10+
github.com/mattn/go-isatty v0.0.20
11+
github.com/ogen-go/ogen v1.18.0
12+
golang.org/x/term v0.40.0
13+
gopkg.in/yaml.v3 v3.0.1
14+
)
15+
16+
require (
17+
github.com/dlclark/regexp2 v1.11.5 // indirect
18+
github.com/ghodss/yaml v1.0.0 // indirect
19+
github.com/go-faster/yaml v0.4.6 // indirect
20+
github.com/google/uuid v1.6.0 // indirect
21+
github.com/kr/pretty v0.3.1 // indirect
22+
github.com/mattn/go-colorable v0.1.13 // indirect
23+
github.com/rogpeppe/go-internal v1.12.0 // indirect
24+
github.com/segmentio/asm v1.2.1 // indirect
25+
github.com/shopspring/decimal v1.4.0 // indirect
26+
go.uber.org/multierr v1.11.0 // indirect
27+
go.uber.org/zap v1.27.1 // indirect
28+
golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 // indirect
29+
golang.org/x/net v0.50.0 // indirect
30+
golang.org/x/sync v0.19.0 // indirect
31+
golang.org/x/sys v0.41.0 // indirect
32+
golang.org/x/text v0.34.0 // indirect
33+
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
34+
gopkg.in/yaml.v2 v2.4.0 // indirect
35+
)

0 commit comments

Comments
 (0)