Ruby SDK upgrade (v0.x to v1.0)

Basic Changes

Client Initialization

New Features in v1.0

1. Strong Typing with Sorbet: Improved type definitions for better IDE integration

2. Auto-pagination: Easily iterate through paginated resources

3. Enhanced Error Handling: More specific error classes

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

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

6. Request Options: More control over individual requests

Breaking Changes

1. Client Design: The new SDK uses an instance-based client rather than module functions

   • Create a client instance with knock = Knockapi::Client.new()
   • Call methods via the client: knock.workflows.trigger() instead of Knock::Workflows.trigger()

2. Method Naming and Organization:

   • Knock::Users.identify() → knock.users.update()
   • Knock::Users.set_preferences() → knock.recipients.preferences.set()
   • Knock::Users.get_channel_data() → knock.recipients.channel_data.get()
   • Bulk operations are now organized in their own namespaces: knock.users.bulk.*, knock.objects.bulk.*
   • The main module is now Knockapi instead of Knock

3. Method Parameters: Parameters are now passed differently

   • Most methods now take the ID(s) as positional parameter(s), followed by named parameters
   • Resource IDs moved from named parameters to positional parameters (e.g., id: "user-1" → "user-1")
   • data: parameters have been flattened in most methods

4. Preference Management:

   • Preferences are now handled through the recipients.preferences module
   • The preference set ID must be explicitly provided (usually "default")

5. Response Handling:

   • The new SDK returns model instances rather than raw hashes
   • Pagination is handled via cursor-based pagination instead of page-based

Common Operations

Triggering Workflows

Old SDK:

New SDK:

Identifying Users

Old SDK:

New SDK:

Working with Preferences

Old SDK:

New SDK:

Support

If you encounter any issues during migration, please reach out to our support team or open an issue on GitHub.