docs(pq-key-fingerprint/ts): phase 3 - add package documentation (ENG-1762)

[eacet]

Summary

Package(s)

Languages

• TypeScript
• Rust

Checklist

• Tests pass for all modified packages
• Linting/formatting passes (biome check, cargo fmt)
• Both language implementations are consistent (or noted as follow-up)
• Package README updated if public API changed
• No unnecessary dependencies added

Related Issues

[eacet]

• test(pq-key-fingerprint/ts): phase 4 - comprehensive test coverage (ENG-1763) #25
• docs(pq-key-fingerprint/ts): phase 3 - add package documentation (ENG-1762) #24 👈 (View in Graphite)
• feat(pq-key-fingerprint/ts): phase 2 - implement fingerprint core logic (ENG-1761) #23
• feat(pq-key-fingerprint/ts): phase 1 - rebuild source API surface (ENG-1760) #22
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR adds comprehensive documentation for the pq-key-fingerprint TypeScript package with usage examples, API reference, and a compatibility note. The documentation is accurate and reflects the actual implementation.

Key observations:

• Usage examples are correct and consistent with the actual source code (fingerprint.ts, types.ts, errors.ts).
• The API section correctly documents FingerprintDigest, FingerprintEncoding, FingerprintOptions, FingerprintResult, and all five exported functions.
• The API section could be enhanced by defining the referenced types (PublicKeyInput, AlgorithmName, PQJwk) to improve self-containedness and reduce the need for readers to cross-reference external packages.
• The four exported error subclasses (InvalidFingerprintInputError, InvalidKeyTypeError, UnsupportedDigestError, RuntimeCapabilityError) are not documented, which limits developers' ability to write fine-grained error handling.
• FingerprintOptions is documented as an interface, but the project convention prefers type for simple option bags without inheritance.

Confidence Score: 4/5

• Safe to merge — documentation-only change with no runtime impact; minor completeness and style improvements are suggested.
• This PR only modifies a README file and introduces no code changes. All documented behaviours match the actual implementation. Three comments suggest documentation completeness and style improvements: adding type definitions for better self-containedness, documenting exported error classes for fine-grained error handling, and using type instead of interface to align with project convention. None of these affect correctness or safety—they are enhancements to documentation quality.
• No files require special attention. All feedback targets documentation completeness and style consistency.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Caller] -->|bytes + alg| B[fingerprintPublicKeyBytes]
    A -->|PublicKeyInput| C[fingerprintPublicKey]
    A -->|SPKI DER Uint8Array| D[fingerprintSPKI]
    A -->|PEM string| E[fingerprintPEM]
    A -->|PQJwk| F[fingerprintJWK]

    B --> G[normalizePublicKeyInput / build KeyData]
    C --> G
    D -->|fromSPKI - pq-key-encoder| G
    E -->|fromPEM - pq-key-encoder| G
    F -->|fromJWK - pq-key-encoder| G

    G --> H{type === 'public'?}
    H -->|No| ERR1[InvalidKeyTypeError]
    H -->|Yes| I[digestBytes via WebCrypto subtle.digest]
    I -->|unavailable| ERR2[RuntimeCapabilityError]
    I -->|digest result Uint8Array| J[encodeFingerprint]

    J -->|hex default| K[string - hex]
    J -->|base64| L[string - base64]
    J -->|base64url| M[string - base64url]
    J -->|bytes| N[Uint8Array]

    subgraph ErrorBoundary [withErrorBoundary]
        G
        H
        I
        J
    end

    ERR1 --> OUT[FingerprintError thrown to caller]
    ERR2 --> OUT

Loading

_{Last reviewed commit: cf30961}

[eacet]

Merge activity

• Mar 10, 4:45 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Mar 10, 4:49 PM UTC: Graphite rebased this pull request as part of a merge.
• Mar 10, 4:50 PM UTC: @eacet merged this pull request with Graphite.