Introduce node clients#128
Merged
Merged
Conversation
skelz0r
force-pushed
the
clients/javascript
branch
from
cd29f97 to
5f317b4
Compare
In languages like JavaScript, spreading `{ ...defaults, ...{ key: undefined } }`
silently erases the default value for that key. The previous wording only said
"nil params are dropped" without specifying when relative to the merge step.
This led to a real bug during the Node.js port where per-call undefined params
from scaffolded resource methods would erase client-level defaults for
recipient/context/object.
…imeouts The WHATWG fetch API (Node 18+, Deno, browsers) only exposes a single AbortController timeout covering the full request lifecycle — there is no way to set a connect timeout independently. The spec now allows accepting both values for interface consistency while applying only the read timeout when the transport doesn't support the split.
…ntent The spec said "emit a deprecation warning through the language-native channel" but didn't specify the mechanism per language or the minimum content of the message. Without this, each port invents its own format, making deprecation warnings inconsistent across SDKs. Now requires the path template + method name in the message, and names the idiomatic API per language.
meta.retry_in is in seconds, but many languages (JS, Java) use milliseconds for timers. During the Node.js port a real bug happened: the delay was multiplied by 1000 when calling the sleep helper, which internally also multiplied by 1000, turning a 0.5s retry into a 500s wait and causing test timeouts. Added an explicit implementer warning.
The previous wording was Ruby/Faraday-centric ("strip [] when the library
appends it automatically"). Each HTTP library handles array serialization
differently — some auto-append brackets, some don't, some use indexed keys.
Added a reference table covering Ruby, Node, Python, and PHP so porters know
what to do without reverse-engineering Faraday's behavior. Also recommends
a wire-format assertion test since bracket bugs are silent.
TESTING.md is the staging conformance playbook that every new client must pass before being declared SPECS-conformant. It was only referenced deep in SPECS.md §12.4 — easy to miss when following the README's step-by-step porting guide. Moved it to step 2, right after reading SPECS.md, so porters discover it before writing any code.
- CLAUDE.md: add "Nouveau client" section listing the 5 places to update when implementing a new SDK (changelog, api_entreprise docs, api_particulier docs, clients/README, CLAUDE.md itself). Also add Node.js build commands to the "Lecture obligatoire" section. - README.md: add node/ to the directory inventory table.
SPECS.md-conformant Node.js client matching the Ruby reference implementation. Two packages: @api-gouv-dinum/api-entreprise and @api-gouv-dinum/api-particulier, built with zero runtime dependencies (native fetch, Node 18+). Architecture: - commons/ source of truth, vendored into each package via bin/sync-commons.ts (same pattern as Ruby) - bin/scaffold-resources.ts generates resource classes from the OpenAPI YAML specs in commons/swagger/ - Dual ESM + CJS output via tsup, with .d.ts type declarations - GitHub Actions CI (Node 18/20/22 matrix) + npm publish via Trusted Publishing (OIDC) on tag node-api-*-v* Covered SPECS.md conformance: - Immutable Configuration with with()/copy(), env var defaults - BearerToken auth strategy (pluggable AuthStrategy interface) - JSON:API response envelope (data, links, meta, rateLimit) - Full error hierarchy: ClientError (Auth, Authorization, NotFound, Conflict, Validation, RateLimit) + ServerError (Provider, ProviderUnavailable) + TransportError - SIRET/SIREN Luhn validation with La Poste exception - RateLimit-* header parsing with retryAfter() - Opt-in retry middleware (exponential backoff + jitter, honors Retry-After and meta.retry_in) - User-Agent per §10 format - Query string redaction for API Particulier (PII protection) - Array params encoded as key[]=v1&key[]=v2 - Deprecation warnings via process.emitWarning Tests: 176 passing (106 commons + 52 api-entreprise + 18 api-particulier) covering the full §12.1 unit matrix and §12.2 integration scenarios.
Add changelog entry for the Node.js SDK release and update the SDK tables in both API Entreprise and API Particulier documentation pages to mark Node.js as available.
skelz0r
force-pushed
the
clients/javascript
branch
from
5f317b4 to
3dca3b6
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://www.npmjs.com/package/@api-gouv-dinum/api-entreprise
https://www.npmjs.com/package/@api-gouv-dinum/api-particulier
CI configuré + readme/claude setup pour les futures releases.
Quelques itérations sur le specs.md à la suite de l'implémentation en full autonomie de claude.