11b82cbb91
* 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>
82 lines
3.5 KiB
TypeScript
82 lines
3.5 KiB
TypeScript
/**
|
|
* /llms.txt: agent-discoverable index of the Accounted API.
|
|
*
|
|
* Convention adopted by Stripe, Anthropic, and other agent-facing platforms:
|
|
* a plain-text Markdown file at the doc root that points LLM crawlers and
|
|
* IDE agents (Cursor, Claude Code, Windsurf) at the canonical resources
|
|
* they need. Cheaper than scraping HTML.
|
|
*/
|
|
|
|
import { NextResponse } from 'next/server'
|
|
import { API_V1_VERSION } from '@/lib/api/v1/version'
|
|
import { withPublicSecurityHeaders } from '@/lib/api/v1/security-headers'
|
|
import { getCanonicalBaseUrl } from '@/lib/api/v1/base-url'
|
|
|
|
export async function GET(_request: Request) {
|
|
const base = getCanonicalBaseUrl()
|
|
|
|
const body = `# Accounted API
|
|
|
|
> Swedish double-entry bookkeeping as a public REST API. API version ${API_V1_VERSION}.
|
|
|
|
This API lets agents and integrations do anything the Accounted dashboard can do:
|
|
read transactions, create invoices, mark them paid, run VAT reports, file year-end
|
|
declarations, ingest SIE files, and subscribe to webhooks for state changes.
|
|
|
|
## Quickstart
|
|
|
|
1. Create an API key in the Accounted dashboard at /settings/api.
|
|
2. Authenticate with \`Authorization: Bearer gnubok_sk_<live|test>_<random>\`.
|
|
3. List companies the key can access: \`GET ${base}/api/v1/companies\`.
|
|
4. Use the returned \`id\` as \`{companyId}\` in subsequent paths.
|
|
|
|
## Core principles
|
|
|
|
- **Dry-run on every write.** Add \`?dry_run=true\` or \`X-Dry-Run: true\` to any
|
|
POST/PATCH/DELETE to preview the effect (journal lines, voucher number,
|
|
account deltas) without committing. The same call without dry-run commits.
|
|
- **Idempotency-Key on every write.** Pass a UUID in \`Idempotency-Key\`; replays
|
|
return the cached response (24h TTL) with \`Idempotent-Replayed: true\`.
|
|
- **Test mode.** Create a key with mode \`test\` (prefix \`gnubok_sk_test_\`) in the
|
|
dashboard. A test key forces \`dry_run\` on every write against your real company:
|
|
you get a realistic 200 + preview of what *would* happen, but nothing is ever
|
|
saved or sent. Reads return real data; responses carry \`X-Gnubok-Mode: test\`.
|
|
Writes on endpoints that can't be simulated are refused (403
|
|
\`TEST_KEY_WRITE_BLOCKED\`). It's \`?dry_run=true\` baked into the credential, so
|
|
you can develop safely before switching to a live key.
|
|
- **Compliance pre-flight.** \`GET /api/v1/companies/{id}/compliance/check?type=…\`
|
|
returns structured findings (voucher gaps, locked-period violations, VAT close
|
|
blockers, missing receipts) before you submit.
|
|
|
|
## Resources
|
|
|
|
- Agent skill (full API surface for coding agents): \`npx skills add erp-mafia/accounted --skill accounted-api\`
|
|
- OpenAPI 3.1 spec: ${base}/api/v1/openapi.json
|
|
- Skills catalogue: ${base}/.well-known/skills/index.json
|
|
- Health check: ${base}/api/v1/health
|
|
- Docs (cookbook + reference): ${base}/docs/api
|
|
- Error reference: ${base}/docs/api/errors
|
|
- Security disclosure policy: ${base}/SECURITY.md (responsible disclosure to security@arcim.io)
|
|
|
|
## Schema discovery
|
|
|
|
Every \`.md\` URL under /docs/api is served as plain Markdown so agents can
|
|
ingest it without HTML parsing.
|
|
|
|
## Versioning
|
|
|
|
The URL major version is \`/api/v1/\`. Within v1, the response shape is pinned to
|
|
\`${API_V1_VERSION}\`. Future breaking changes inside v1 will accept an optional
|
|
\`Gnubok-Version: YYYY-MM-DD\` header for opt-in upgrades; older versions keep
|
|
working until explicitly retired.
|
|
`
|
|
|
|
return new NextResponse(body, {
|
|
status: 200,
|
|
headers: withPublicSecurityHeaders({
|
|
'Content-Type': 'text/markdown; charset=utf-8',
|
|
'Cache-Control': 'public, max-age=300, s-maxage=300',
|
|
}),
|
|
})
|
|
}
|