Developer tools
Migration guides
Node.js 1.0

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

  1. Fully Typed API: Complete TypeScript definitions for all requests and responses

  2. Enhanced Error Handling: Typed errors with better context

  3. Auto-pagination: Easily iterate through paginated resources

  4. Request/Response Access: More control over raw responses

  5. Configurable Logging: Better debugging capabilities

  6. Configurable Timeouts and Retries: Fine-tune request behavior

  7. New Resources: Additional resources like Audiences, Channels, and Integrations

Breaking Changes

  1. The notify method is now workflows.trigger

  2. Client initialization accepts an options object instead of just the API key

  3. Some parameter names have changed to match the API (e.g., cancellationKeycancellation_key)

  4. Error handling has been completely revamped with typed errors

  5. Method naming convention changes:

    • users.getPreferences() now requires a preference set ID parameter
    • users.bulkIdentify() is now users.bulk.identify()
    • users.bulkDelete() is now users.bulk.delete()
    • users.bulkSetPreferences() is now users.bulk.setPreferences()
  6. 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
  7. 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

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.