api-import-export-doctor

A tiny zero-dependency CLI that grades API import/export documentation before users discover the painful gaps: file formats, mapping, validation errors, async jobs, limits, privacy, retries, webhooks, and export expiry.

npx api-import-export-doctor docs/import-export.md --min-score 85

Why people use it

Import/export features look simple until production users hit million-row CSV files, duplicate records, expired links, and unclear error files. This tool gives your docs a fast score and concrete fixes.

Checks

• Supported formats, MIME types, encodings, sample templates
• Required fields, schema, field/column mapping
• Row-level validation, error files, partial failures
• Async job lifecycle, polling, status states
• Size limits, row limits, timeouts, rate limits
• Idempotency, duplicate handling, upsert/merge conflicts
• PII, secrets, encryption, retention, export deletion
• Export filters, scopes, fields, permissions
• Signed download URLs and expiry behavior
• Completion webhooks/callbacks
• Concrete curl and JSON examples
• Retry, resume, and recovery behavior
• Audit IDs and troubleshooting guidance

Usage

api-import-export-doctor README.md
api-import-export-doctor docs/import-export.md --min-score 90
api-import-export-doctor docs/import-export.md --json

Exit code is non-zero when the score is below --min-score, making it CI-friendly.

Good output

✅ api-import-export-doctor score: 100/100 (minimum 85)

Bad output

❌ api-import-export-doctor score: 0/100 (minimum 90)
Recommendations:
- List every supported format, MIME type, encoding, and sample file shape.
- Show row-level validation errors, error-file format, and partial-failure behavior.

CI

- run: npx api-import-export-doctor docs/import-export.md --min-score 85

Local development

npm install
npm run check

License

MIT