Jakob Wennberg
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>
78 lines
3.7 KiB
TypeScript
78 lines
3.7 KiB
TypeScript
/**
|
|
* The OpenAPI generator emits machine-readable request contracts:
|
|
* path `parameters` derived from the route pattern and `requestBody` from
|
|
* the registered Zod body schema. Historically the spec only carried
|
|
* response schemas + prose, which forced spec consumers (agent skills,
|
|
* client generators) to guess request shapes.
|
|
*/
|
|
|
|
import { describe, expect, it } from 'vitest'
|
|
import { generateOpenApiSpec } from '../registry'
|
|
// Side-effect import: populates the ENDPOINTS registry from every route file.
|
|
import '../load-routes'
|
|
|
|
type OperationObject = {
|
|
parameters?: Array<{ name: string; in: string; required: boolean; schema: unknown }>
|
|
requestBody?: {
|
|
required: boolean
|
|
content: Record<string, { schema: { properties?: Record<string, unknown>; required?: string[] } }>
|
|
}
|
|
}
|
|
|
|
const spec = generateOpenApiSpec('https://unit.test')
|
|
|
|
function operation(path: string, method: string): OperationObject {
|
|
const op = (spec.paths[path] as Record<string, OperationObject> | undefined)?.[method]
|
|
expect(op, `${method.toUpperCase()} ${path} missing from spec`).toBeDefined()
|
|
return op as OperationObject
|
|
}
|
|
|
|
describe('generateOpenApiSpec request contracts', () => {
|
|
it('declares a path parameter for every templated segment, on every operation', () => {
|
|
for (const [path, item] of Object.entries(spec.paths)) {
|
|
const templated = [...path.matchAll(/\{([^}]+)\}/g)].map((m) => m[1])
|
|
for (const [method, op] of Object.entries(item as Record<string, OperationObject>)) {
|
|
const declared = (op.parameters ?? []).filter((p) => p.in === 'path').map((p) => p.name)
|
|
expect(declared.sort(), `${method.toUpperCase()} ${path}`).toEqual([...templated].sort())
|
|
}
|
|
}
|
|
})
|
|
|
|
it('emits requestBody from the registered Zod body schema', () => {
|
|
const op = operation('/api/v1/companies/{companyId}/invoices', 'post')
|
|
expect(op.requestBody?.required).toBe(true)
|
|
const schema = op.requestBody?.content['application/json']?.schema
|
|
expect(schema?.properties).toHaveProperty('customer_id')
|
|
expect(schema?.properties).toHaveProperty('items')
|
|
expect(schema?.required).toContain('customer_id')
|
|
})
|
|
|
|
it('renders multipart z.unknown() parts as binary file parts', () => {
|
|
const op = operation('/api/v1/companies/{companyId}/documents', 'post')
|
|
const schema = op.requestBody?.content['multipart/form-data']?.schema
|
|
expect(schema?.properties?.file).toEqual({ type: 'string', format: 'binary' })
|
|
// Non-file parts keep their real schema.
|
|
expect(schema?.properties?.journal_entry_id).toMatchObject({ type: 'string' })
|
|
})
|
|
|
|
it('omits requestBody on endpoints without a registered body', () => {
|
|
expect(operation('/api/v1/companies', 'get').requestBody).toBeUndefined()
|
|
})
|
|
|
|
it('converts wrapped Zod constructs (.default, z.record) instead of degrading to {}', () => {
|
|
const op = operation('/api/v1/companies/{companyId}/journal-entries', 'post')
|
|
const schema = op.requestBody?.content['application/json']?.schema as {
|
|
properties: Record<string, { type?: string; enum?: unknown[]; items?: { properties: Record<string, { type?: string; additionalProperties?: unknown }> } }>
|
|
required?: string[]
|
|
}
|
|
// JournalEntrySourceTypeSchema.default('manual'): enum survives, field not required.
|
|
expect(schema.properties.source_type.enum).toContain('manual')
|
|
expect(schema.required).not.toContain('source_type')
|
|
const line = schema.properties.lines.items!.properties
|
|
// nonNegativeAmount.default(0) is a number, and z.record renders as an
|
|
// object with additionalProperties rather than an empty schema.
|
|
expect(line.debit_amount.type).toBe('number')
|
|
expect(line.dimensions.additionalProperties).toBeTruthy()
|
|
})
|
|
})
|