Node.js SDK upgrade (v0.x to v1.0)
This guide will help you upgrade your existing Knock Node.js SDK to the 1.0 release.
Basic Changes
Import Style
Client Initialization
New Features in v1.0
-
Fully Typed API: Complete TypeScript definitions for all requests and responses
-
Enhanced Error Handling: Typed errors with better context
-
Auto-pagination: Easily iterate through paginated resources
-
Request/Response Access: More control over raw responses
-
Configurable Logging: Better debugging capabilities
-
Configurable Timeouts and Retries: Fine-tune request behavior
-
New Resources: Additional resources like Audiences, Channels, and Integrations
Breaking Changes
-
The
notify
method is nowworkflows.trigger
-
Client initialization accepts an options object instead of just the API key
-
Some parameter names have changed to match the API (e.g.,
cancellationKey
→cancellation_key
) -
Error handling has been completely revamped with typed errors
-
Method naming convention changes:
users.getPreferences()
now requires a preference set ID parameterusers.bulkIdentify()
is nowusers.bulk.identify()
users.bulkDelete()
is nowusers.bulk.delete()
users.bulkSetPreferences()
is nowusers.bulk.setPreferences()
-
Parameter style changes:
- All parameters are now in camelCase in the method signature but use snake_case in the request body
- Query parameters are now passed as a separate object in most list methods
-
Response handling:
- The new SDK returns the data directly in most cases rather than wrapped in a
data
property - Pagination is handled differently with cursor-based pagination
- The new SDK returns the data directly in most cases rather than wrapped in a
Common Operations
Triggering Workflows
Old version:
1.x release:
Identifying Users
Old version:
1.x release:
Working with Objects
Old version:
1.x release:
Support
If you encounter any issues during migration, please reach out to our support team or open an issue on GitHub.