3.0.0: modernize toolchain, drop legacy endpoints, add helpers#189
Merged
Conversation
bartes
changed the title
bartes
changed the title
bartes
changed the title
Runtime & build: - Use the built-in global fetch / AbortSignal; drop node-fetch, abort-controller and timeout-signal. Requires Node >= 20. - Replace the lodash.* micro-packages with native helpers. - Ship a dual ESM + CJS build via tsup with an exports map and type definitions. - Modernize tsconfig (target ES2022; enforce strictNullChecks and fix the resulting null-safety issues). - Migrate CI to GitHub Actions (Node 20/22/24 matrix + lint); switch the package manager to npm; bump pino v9 / pino-pretty v13. Breaking: - Remove the legacy endpoints and their Castle methods: authenticate, track, getDevice, getDevicesForUser, approveDevice, reportDevice. Use risk / filter / log instead. Remove the related payload/result types. Features: - Webhook signature verification: verifyWebhookSignature / WebhookVerifyService validate the X-Castle-Signature header (constant-time HMAC-SHA256 of the raw body) and raise WebhookVerificationError on mismatch. - Secure mode: secureModeSignature / SecureModeService return a hex HMAC-SHA256 of the user id. Payload types: - Add a typed transaction field to RiskPayload (base_amount, amount as a fiat/crypto object, payment_method, shipping_address, merchant), exported as TransactionPayload. Add the same field to FilterPayload and LogPayload. Addresses #188. - Add region_code to AddressPayload and type RiskPayload.user.address as AddressPayload. - Remove the dead ImpersonationFailed error. - risk() no longer throws in doNotTrack mode when the payload has no user. Docs: - Restructure the README and complete the 3.0.0 changelog.
bartes
force-pushed
the
chore/modernize-sdk
branch
from
ab93042 to
376663f
Compare
mknapik
approved these changes
Jun 2, 2026
Make queryEvents, eventsSchema, and groupEvents the official Events API methods, keeping searchEvents and getEventsSchema as deprecated aliases so existing code keeps working. Update the README and CHANGELOG to recommend the new names, and cover both the new methods and the aliases in tests. Add Node 26 to the CI test matrix, bump the lint workflow to Node 26, and pin Node 26.2.0 as the local default in .tool-versions / .nvmrc.
The rename ships as part of the unreleased 3.0.0, so list it under 3.0.0 Enhancements rather than a separate Unreleased heading.
Provide searchEvents and getEventsSchema as straightforward aliases of queryEvents and eventsSchema without a deprecation notice.
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.
Summary
3.0.0modernizes the SDK to current Node.js and TypeScript standards, removes the long-deprecated device/authentication endpoints, and introduces webhook-verification and secure-mode helpers. This is a major release: the minimum supported runtime is now Node 20, and a small number of legacy APIs have been removed.The public
risk/filter/log/ Lists / Privacy / Events surface is unchanged.Breaking changes
fetch/AbortSignal.authenticate,track,getDevice,getDevicesForUser,approveDeviceandreportDevicemethods are gone, along with thePayload,DevicePayload,UserDevicePayloadandAuthenticateResulttypes.Migration
authenticate,trackrisk/filter/logapproveDevice,reportDevicecreateListItem/archiveListItem)getDevice,getDevicesForUserNew features
castle.verifyWebhookSignature(rawBody, signature)validates theX-Castle-Signatureheader (constant-time HMAC-SHA256 of the raw body) and throwsWebhookVerificationErroron mismatch.castle.secureModeSignature(userId)returns the hex HMAC-SHA256 of a user id, for signing user identifiers sent from the browser.Improvements
transactionfield toRiskPayload,FilterPayloadandLogPayload(base_amount,amount,payment_method,shipping_address,merchant), exported asTransactionPayload(Missing transaction field in RiskPayload type #188).region_codetoAddressPayload; typeRiskPayload.user.addressasAddressPayload.risk()no longer throws indoNotTrackmode when the payload has nouser.ImpersonationFailederror.Internal
tsupwith anexportsmap and bundled type definitions (verified under bothrequire()andimport).lodash.*micro-packages with native helpers.tsconfigtargetsES2022; the previously ignoredstrictflag is fixed, sostrictNullChecksis now enforced.pinov9 /pino-prettyv13.3.0.0changelog.Notes
noImplicitAnyis intentionally left off for now; onlystrictNullChecksis newly enforced. Tightening it further can be a follow-up.