# API Reference

## Parse

`parse_header(header)` performs recoverable parsing. It returns `Ok(Disposition)` when the disposition type is valid, and stores recoverable syntax or decoding issues in `Disposition.diagnostics`.

`parse_header_strict(header)` rejects any diagnostic with `Error` severity.

`Disposition` exposes:

- `kind`
- `params`
- `diagnostics`
- `filename()`
- `plain_filename()`
- `extended_filename()`
- `name()`
- `get_param(name)`
- `params_named(name)`
- `has_errors()`
- `to_header()`

## Generate

`attachment(filename)` builds an attachment header with a safe plain filename and, when needed, a `filename*` extended value.

`inline()` builds a minimal inline disposition.

`form_data(name, filename?)` builds a multipart form-data disposition.

`DispositionBuilder` provides a composable builder:

- `DispositionBuilder::attachment()`
- `DispositionBuilder::inline()`
- `DispositionBuilder::form_data()`
- `with_param(name, value)`
- `with_extended_param(name, value, charset?, language?)`
- `with_filename(filename)`
- `with_filename_policy(filename, policy)`
- `build()`
- `to_header()`

## Filename Safety

`FilenamePolicy` controls replacement, maximum length, default filename and hidden-file behavior.

Presets:

- `FilenamePolicy::default()`
- `FilenamePolicy::strict_download()`
- `FilenamePolicy::multipart_upload()`
- `FilenamePolicy::object_storage_key()`

Main functions:

- `sanitize_filename(filename)`
- `sanitize_filename_with_policy(filename, policy)`
- `sanitize_filename_preserve_extension(filename, policy)`
- `sanitize_filename_strict(filename)`
- `sanitize_upload_filename(filename)`
- `sanitize_object_key(filename)`
- `safe_filename_from_header(header)`
- `filename_ascii_fallback(filename)`

Helpers:

- `filename_extension(filename)`
- `filename_stem(filename)`
- `filename_has_extension(filename, extension)`
- `normalize_extension(extension)`

## Review And Reports

`lint_header(header)` returns a `HeaderReview` with parse result, safe filename report, recommendations and status.

Batch helpers:

- `lint_headers(headers)`
- `lint_headers_with_policy(headers, policy)`
- `summarize_reviews(reviews)`
- `evaluate_audit_gate(reviews)`
- `evaluate_audit_gate_with_policy(reviews, policy)`
- `evaluate_headers_gate(headers)`
- `evaluate_headers_gate_with_policy(headers, filename_policy, audit_policy)`
- `reviews_by_status(reviews, status)`
- `reviews_with_recommendation(reviews, code)`
- `reviews_with_filename_changes(reviews)`
- `reviews_to_text(reviews)`
- `reviews_to_markdown(reviews)`
- `reviews_to_json(reviews)`

`Diagnostic`, `Recommendation`, `FilenameReport` and `HeaderReview` all provide text or JSON rendering helpers.

`AuditGatePolicy` provides reusable policy presets:

- `AuditGatePolicy::strict()`
- `AuditGatePolicy::download_gateway()`
- `AuditGatePolicy::report_only()`

`AuditGateResult` exposes:

- `accepted`
- `status`
- `summary`
- `reasons`
- `reason_text()`
- `to_text()`

## Download Profiles

`prepare_download(request)` converts a `DownloadRequest` into a safe `PreparedDownload`.

Request constructors:

- `DownloadRequest::attachment(filename)`
- `DownloadRequest::inline_preview(filename, content_type?)`
- `DownloadRequest::from_content_type(content_type)`

Classification helpers:

- `normalize_content_type(content_type)`
- `extension_for_content_type(content_type)`
- `content_type_for_extension(extension)`
- `infer_filename_from_content_type(content_type?)`
- `classify_filename(filename)`
- `classify_extension(extension)`
- `extension_risk(kind, extension?)`
- `inline_allowed_for_kind(kind)`

## Repair

`repair_header(header)` normalizes a header into a safer serialized form.

`canonicalize_header(header)` strictly parses and serializes a valid header.

`canonicalize_header_loose(header)` serializes any header with a valid disposition type even when recoverable diagnostics exist.

Batch helpers:

- `repair_headers(headers)`
- `repairs_to_headers(repairs)`
- `repairs_to_text(repairs)`

## Compatibility

`check_compatibility(header, profile)` validates one header against a target client or gateway profile.

Profiles:

- `ModernHttpClient`
- `LegacyHttpClient`
- `BrowserDownload`
- `MultipartFormParser`
- `ObjectStorageGateway`

Batch helper:

- `compatibility_matrix(header)`
- `compatibility_matrix_to_text(reports)`