feat!: modernize SDK against current OpenAPI spec (knock-node parity)

[cjbell]

This implements the plan in #39. It brings the Java SDK in line with the current OpenAPI spec and with knock-node. It fixes three bugs that made existing calls fail or return nothing, adds 9 endpoints (89 → 98), adds the fields that were missing, and ports Node's user-token signing. MIGRATION.md lists every breaking change.

Release

This ships as 2.0.0. Several changes break source or binary compatibility for code built against 1.x. For example, the 204 methods changing from String to void causes NoSuchMethodError in already-compiled callers.

• The last commit carries a Release-As: 2.0.0 footer and a BREAKING CHANGE: footer. The PR title is marked feat!. Release-please will propose 2.0.0 whether this is merged or squashed.
• The version in build.gradle.kts is still 1.0.0. Release-please bumps it in its release PR.

Bug fixes

• Message-family pages were always empty. Message lists, message events, delivery logs, and user and object message lists now parse the items envelope. The accessor changes from entries() to items().
• Object-array query params returned 422. Queries now use the indexed form (objects[0][id]=…) that the API expects, via app.knock.api.lib.QueryArrays. UserListSubscriptionsParams.objects, ObjectListSubscriptionsParams.recipients, and ScheduleListParams.recipients now take RecipientReference.
• Bulk add subscriptions now requires id on each item, as the API does.
• Preference center row types. The API returns workflows and categories, which the spec doesn't list. They're now known enum values.

New endpoints

• workflowRecipientRuns(): list and get
• users().preferenceCenter(): getConfig and generateSignedUrl
• users().unsetPreferences and objects().unsetPreferences
• objects().bulk().deleteSubscriptions
• users().guides().resetGuideEngagements and unarchiveGuideMessage

Breaking changes

• 204 endpoints return nothing. This covers delete on users, objects, and tenants; unsetChannelData; audience addMembers and removeMembers; and workflows().cancel. The async variants return CompletableFuture<Void?>.
• Guide mark-as methods. They target PUT /v1/users/{user_id}/guides/messages/{action} and drop messageId. GuideActionResponse replaces the three per-action responses. GuideGetChannelResponse now has entries, guide_groups, guide_group_display_logs, and ineligible_guides.
• messages().activities() removed. It duplicated messages().listActivities().
• ScheduleCreateParams.repeats() now returns an Optional.

New fields

• Workflow trigger: settings (sandbox_mode, skip_delay).
• Schedule create: actor.
• Tenants: name and resolve_full_preference_settings.
• Audience add members: create_audience.
• Feed listItems: locale, exclude, mode, and inserted_at.{gt,gte,lt,lte}.
• Inline identify user: avatar, locale, and phone_number.
• Message.source: step_ref, type, workflow_run_id, and workflow_recipient_run_id.
• Slack, MS Teams, and Discord connections: knock_tenant_id. Slack token connections also get channel_name.

User token signing

app.knock.api.lib.UserTokens provides signUserToken and buildUserTokenGrant, with Grant, TokenEntity, and SignUserTokenOptions.

• It uses JDK crypto only and stays Java 8 compatible.
• Java-signed tokens are byte-identical to Node's for the same key, time, and grants.
• It accepts PKCS#8 or PKCS#1 PEMs, raw or base64-encoded, and falls back to KNOCK_SIGNING_KEY.
• The README documents it, and knock-java-example now has a runnable Main.

Findings for the API and spec

• Node's inserted_at filter is silently ignored. Node sends inserted_at[gt], which the API ignores; the API only honors inserted_at.gt, the form in the spec. Java uses the spec form.
• Guide {message_id} paths. The spec still lists guide paths with {message_id} alongside the path-less ones.
• Preference center row types. The spec lists singular row types, but the API returns plural ones.

Not in this PR

These items from plan §6 are deferred:

• Splitting the push and OneSignal channel-data unions.
• The Slack incoming webhook url → incoming_webhook.url change. This needs confirmation that the API actually changed.
• Removing TenantSetParams.preferences.
• The MessageContents and AudienceMemberRequest renames.
• Preference-set additions: channels, commercial_subscribed, and the persistence strategy.
• Message.channel and recipient_snapshot.
• Inline object name.

I also didn't add standalone Guide*Request models, because Node doesn't use them. The params classes carry those fields.

Most of this is hand-written into Stainless-generated files. The spec and Stainless config need matching updates, or the next regeneration will overwrite these changes.

Testing

• ./scripts/lint passes.

• ./scripts/test (Prism mock) passes: 1049 tests with 0 failures. The 198 skipped are the generated service tests, which are always disabled.

• A read-only live smoke test against a real account, with strict response validation, passed for:

  • workflow recipient runs: list with filters and an object recipient, and get
  • preferenceCenter().getConfig
  • messages().list, including the new source fields
  • feed listItems with mode, exclude, and inserted_at
  • tenants().get with resolve_full_preference_settings

  It isn't committed.

  

[cursor]

Not approved: this is a breaking SDK modernization, not an auto-release PR, so it needs human review even though lint and test are green. No reviewers were assigned because two are already requested.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}