feat(api): installable accounted-api agent skill + openapi-to-skill generator (#1516)
* feat(api): installable accounted-api agent skill + openapi-to-skill generator Three layers, per the July/August 2026 agent-skills ecosystem (skills.sh / npx skills add, as used by Stripe/Cloudflare/Supabase for their APIs): - skills/openapi-to-skill/: generic, installable skill that turns any OpenAPI spec into a consumer-side integration skill, with a portable stdlib-only inventory/condenser tool and an output template + quality checklist encoding the distill-not-restate methodology. - skills/accounted-api/: the installable skill for our own API, rendered deterministically by scripts/api-skill/generate.ts from the v1 endpoint registry + hand-authored overlays (auth, conventions, domain gotchas). CI gate: npm run apiskill:check (core-build.yml). - lib/api/v1/registry.ts: generateOpenApiSpec now emits requestBody (incl. multipart binary parts) and path parameters, and the Zod converter learned .default()/z.record()/.pipe()/.transform(), so the public spec carries request contracts instead of prose-only. Docs: /docs/api landing + /llms.txt now point agents at the skill install; corrected the stale test-key description in the landing (test keys read real data and force dry-run writes; they are not sandbox-company bound). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(skills): escape backslashes in markdown table cells (CodeQL js/incomplete-sanitization) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Jakob Wennberg
co-authored by
Claude Fable 5
Jakob Wennberg
Claude Fable 5
Jakob Wennberg
parent
7a49aec0c3
commit
11b82cbb91
@@ -0,0 +1,77 @@
|
||||
## Conventions
|
||||
|
||||
These rules hold across the whole surface; endpoint entries below do not
|
||||
repeat them.
|
||||
|
||||
**Response envelope.** Success: `{ "data": ..., "meta": { "request_id",
|
||||
"api_version", "next_cursor"?, "audit"?, "partial_expansions"? } }`. Errors
|
||||
replace `data` with `error` (no `meta`; `request_id` moves inside `error`).
|
||||
|
||||
**Errors.** Stable machine codes with agent-oriented remediation:
|
||||
|
||||
```json
|
||||
{ "error": { "code": "PERIOD_LOCKED", "message": "Svenska", "message_en": "English",
|
||||
"details": {}, "recovery_hint": "next step", "docs_url": "...",
|
||||
"valid_alternatives": {}, "request_id": "req_..." } }
|
||||
```
|
||||
|
||||
React to `code`, read `message_en` and `recovery_hint`, follow
|
||||
`valid_alternatives` when present (e.g. `next_open_period`). Standard codes on
|
||||
every endpoint: `400` validation, `401` bad key, `403` missing scope, `404`,
|
||||
`429` rate limited (honor `Retry-After`), `500`. Full catalogue:
|
||||
https://app.gnubok.se/docs/api/errors. Only endpoint-specific codes are
|
||||
mentioned per endpoint below.
|
||||
|
||||
**Cursor pagination.** List endpoints take `?cursor=` and return
|
||||
`meta.next_cursor`; loop until it is absent/null. A stale or tampered cursor
|
||||
is NOT an error: the first page is returned again, so terminate on
|
||||
`next_cursor`, never on "page looks familiar".
|
||||
|
||||
**Dry-run on every write that supports it** (`dry-run` badge in the index).
|
||||
Send `?dry_run=true` (or `X-Dry-Run: true`): the response is always `200` with
|
||||
`data.dry_run: true` plus a preview (would-be record, journal lines, voucher
|
||||
number) and the `X-Dry-Run: true` response header; nothing is committed.
|
||||
Commit by re-issuing without the flag and with the SAME `Idempotency-Key`
|
||||
(the dry run is not cached against the key). Preview first on any financial
|
||||
write; it is free.
|
||||
|
||||
**Idempotency-Key.** Send a fresh UUID header on every POST/PATCH/DELETE;
|
||||
several endpoints reject writes without one (`400`). Replaying the same
|
||||
key+body returns the original response with the `Idempotent-Replayed: true`
|
||||
header; the same key with a different body returns `409 IDEMPOTENCY_KEY_REUSE`
|
||||
(24h window). Safe retry loop: keep the key, keep the body.
|
||||
|
||||
**Test keys are simulation-only.** With a `gnubok_sk_test_*` key, reads
|
||||
return real company data (responses carry `X-Gnubok-Mode: test`) and every
|
||||
write is forced into dry-run; writes that cannot be simulated return
|
||||
`403 TEST_KEY_WRITE_BLOCKED`. Nothing a test key does ever persists: it is
|
||||
`?dry_run=true` baked into the credential. Full end-to-end write tests
|
||||
therefore need a live key against a company you own.
|
||||
|
||||
**Atomic writes.** A mutation either commits fully or errors with no side
|
||||
effects. There is no partial state to clean up after an error response
|
||||
(`bulk-create` endpoints that do partial success say so explicitly).
|
||||
|
||||
**Audit inline.** Successful financial writes include `meta.audit` (voucher
|
||||
number, audit-trail URL, immutability timestamp). No follow-up read needed to
|
||||
confirm what was booked.
|
||||
|
||||
**Expansion.** Some list/detail endpoints take `?expand=a,b` (documented per
|
||||
endpoint). If an expansion fails the response still succeeds and names the
|
||||
failed parts in `meta.partial_expansions`; check it before trusting expanded
|
||||
fields.
|
||||
|
||||
**Async operations.** Long-running actions (fiscal-period lock/close/year-end,
|
||||
imports) return `202` with an operation id; poll `GET /api/v1/operations/{id}`
|
||||
until `status` is `succeeded`/`failed`. The response shape is identical
|
||||
whether the work ran inline or queued.
|
||||
|
||||
**Versioning.** Dated versions (current: see `meta.api_version`). Pin with the
|
||||
`Gnubok-Version` request header; responses echo it. Additive changes ship
|
||||
without a version bump; see https://app.gnubok.se/docs/api/versioning.
|
||||
|
||||
**Index badges.** Every operation line below carries machine-readable
|
||||
annotations from the spec: `scope:` (required key scope), `risk:` (low/medium/
|
||||
high; confirm with a human before unprompted high-risk calls), `idempotent`
|
||||
(safe to retry), `dry-run` (previewable), `reversible` (a single follow-up
|
||||
call can undo it, e.g. invoice credit).
|
||||
@@ -0,0 +1,38 @@
|
||||
## Gotchas (Swedish accounting domain)
|
||||
|
||||
Rules a generic REST integration will violate unless told:
|
||||
|
||||
- **Account numbers are strings, not numbers.** BAS accounts (`"1930"`,
|
||||
`"3001"`) are identifiers; send them as JSON strings. Arithmetic on them,
|
||||
zero-stripping, or number coercion corrupts postings.
|
||||
- **Posted journal entries are immutable by law** (Bokföringslagen). There is
|
||||
no PATCH or DELETE on a committed entry, ever. Undo with
|
||||
`POST .../journal-entries/{id}/reverse` (storno), fix with
|
||||
`POST .../journal-entries/{id}/correct`. Design flows around
|
||||
reverse-and-repost, not edit-in-place.
|
||||
- **Voucher numbers are gapless and server-assigned.** Never assume or
|
||||
pre-allocate one; read it from `meta.audit.voucher_number` after commit. A
|
||||
legally required gap explanation goes through
|
||||
`POST .../voucher-gap-explanations`.
|
||||
- **Every entry balances.** `sum(debit) === sum(credit)` to the öre, amounts
|
||||
are decimal SEK numbers (max 2 decimals). Do rounding with
|
||||
round-half-away-from-zero on öre; never float-accumulate line totals
|
||||
client-side and "fix" the difference on a random line.
|
||||
- **Period locks are a feature, not an error to retry.** Writes into a
|
||||
locked/closed period return `PERIOD_LOCKED` (with `valid_alternatives`
|
||||
pointing at open periods). Retrying the same request cannot succeed; either
|
||||
target an open period or surface the lock to the user.
|
||||
- **Drafts vs posted.** Invoices are created as drafts with
|
||||
`invoice_number: null`; the F-series number is assigned atomically on send.
|
||||
Journal entries follow draft -> commit. Nothing financial exists in the
|
||||
ledger until the commit/send action.
|
||||
- **Two invoice worlds.** `invoices` = accounts receivable (you bill
|
||||
customers); `supplier-invoices` = accounts payable (you receive bills).
|
||||
They are different resources with different lifecycles.
|
||||
- **Swedish user-facing text.** `error.message` is Swedish by design; show it
|
||||
to Swedish end users, and use `message_en` for your own logs/logic. Domain
|
||||
terms in responses (moms, verifikat, kostnadsställe) are not translatable
|
||||
labels but legal concepts.
|
||||
- **Compliance pre-flight.** Before building your own validation for Swedish
|
||||
rules, call `GET .../compliance/check`: it runs the server's own rule set
|
||||
(VAT plausibility, sequence integrity, period status) and returns findings.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Accounted API integration
|
||||
|
||||
Accounted is Swedish double-entry bookkeeping (bokföring) as a service: BAS
|
||||
chart of accounts, verifikationer with legally immutable audit trails, VAT
|
||||
(moms), payroll (lön), invoicing, bank reconciliation, and statutory reports,
|
||||
exposed as a REST API designed for agents and integrations first.
|
||||
|
||||
**This skill is for building software against the REST API** (an app, a
|
||||
backend job, an agent tool layer). If the goal is to *operate* a ledger
|
||||
conversationally (book receipts, run month close), use the Accounted MCP
|
||||
connector and its workflow skills instead: install the `accounted` plugin or
|
||||
see https://app.gnubok.se/docs/api/connect-claude.
|
||||
|
||||
If you have used Stripe's API the shape will feel familiar: bearer keys, dated
|
||||
versions, idempotency keys, webhook signatures, cursor pagination. The domain
|
||||
rules are Swedish accounting law; the Gotchas section below stops the classic
|
||||
violations before you ship them.
|
||||
@@ -0,0 +1,28 @@
|
||||
## Auth and base URL
|
||||
|
||||
Every request sends a bearer key:
|
||||
|
||||
```bash
|
||||
curl https://app.gnubok.se/api/v1/companies \
|
||||
-H "Authorization: Bearer gnubok_sk_live_..."
|
||||
```
|
||||
|
||||
- Base URL: `https://app.gnubok.se/api/v1` (legacy machine host, permanent).
|
||||
`https://app.accounted.se/api/v1` serves the identical API.
|
||||
- Keys are created in the Accounted dashboard under **Settings -> API**
|
||||
(`/settings/api`). Two prefixes:
|
||||
- `gnubok_sk_live_*` commits real writes.
|
||||
- `gnubok_sk_test_*` reads real company data but forces every write into
|
||||
dry-run (responses carry `X-Gnubok-Mode: test`). Develop and run evals
|
||||
with a test key; switch to live last.
|
||||
- Each key carries **scopes** (`invoices:read`, `invoices:write`,
|
||||
`payroll:write`, `webhooks:manage`, ...). Every endpoint in the index below
|
||||
is annotated with its required scope; a missing scope returns `403`.
|
||||
- Rate limit: 100 requests/minute per key. On `429`, honor `Retry-After`.
|
||||
- URLs carry the company id explicitly
|
||||
(`/api/v1/companies/{companyId}/invoices`). A key can act on any company its
|
||||
user is a member of; start every session with `GET /api/v1/companies` to
|
||||
discover ids. There is no implicit "current company".
|
||||
|
||||
First calls, in order: `GET /api/v1/health` (no auth, connectivity), then
|
||||
`GET /api/v1/companies` (auth works, discover `companyId`).
|
||||
@@ -0,0 +1,18 @@
|
||||
## Verification
|
||||
|
||||
This skill is generated (`npm run apiskill:generate` in the Accounted repo)
|
||||
from the same endpoint registry that serves the live API, its OpenAPI spec
|
||||
(`https://app.gnubok.se/api/v1/openapi.json`), and its runtime request
|
||||
validators, so schema drift between this text and the server cannot occur for
|
||||
a matching `api_version`. CI regenerates and diffs it on every change.
|
||||
|
||||
Before first use in a new environment, smoke-test:
|
||||
|
||||
```bash
|
||||
curl -s https://app.gnubok.se/api/v1/health
|
||||
curl -s https://app.gnubok.se/api/v1/companies -H "Authorization: Bearer $ACCOUNTED_API_KEY"
|
||||
```
|
||||
|
||||
If `meta.api_version` in responses is newer than the version in this skill's
|
||||
index header, refetch the skill (or read the changelog at
|
||||
https://app.gnubok.se/docs/api/changelog) before relying on endpoint details.
|
||||
Reference in New Issue
Block a user