Skip to main content
@catenaclearing/connect-sdk follows semver from 1.0.0.
The betas come first. Both packages are published as 1.0.0-beta.N under the beta tag before the stable 1.0.0. The betas carry no compatibility promise: a beta can change anything the previous beta shipped, and the changelog says what changed. The promise on this page starts with the stable 1.0.0.
  • A major release removes or changes something you rely on: dropping an option, renaming a callback, or changing what a documented behaviour does.
  • A minor release adds: a new export, a new option, a new event.
  • A patch release fixes something without changing what you call or what you receive.

​
What the promise covers

  • The documented exports, open, resume and preload, and their options, and the exported TypeScript types for the options, the handle and the event payloads. See the JavaScript reference.
  • The six callbacks, onOpen, onConnection, onConnectionDeleted, onSuccess, onExit and onClose, and the fields of their payloads: connectionId, connectionIds and reason. See Events and outcomes.
  • The behaviour these docs describe and you can observe: one launch at a time, which callbacks arrive on which of the three modes, and that onSuccess and onExit never both arrive for one launch.
  • For a page that reads the flow’s completion messages directly, without the package: in a message whose version is 1, the source marker catena-connect, the six event names open, connection, connection_deleted, success, exit and close, and the field names that sit beside event: connectionId, connectionIds and reason.
  • For a page that launches the flow from a URL it builds itself: the launch URL parameter names embed, embed_key, variant, theme, brand_color, brand_secondary, brand_logo and brand_logo_dark, and the three embed values iframe, popup and redirect.

​
What it does not cover

  • The 0.0.x releases. They were a typed skeleton with no runtime behaviour, and their one export, PACKAGE_NAME, is not part of the API.
  • The @catenaclearing/connect-sdk/contract entry point. It exists so the Catena app’s own tests can check that what the app sends matches what the package reads. You should not need to import it, and it can change in a minor release.
  • The appearance and content of the flow inside the surface. That is the Catena app, and it changes on its own schedule.
  • Which of the three modes a given browser ends up in. The decision is made by measurement, and browsers change.
  • The file layout under dist, the sessionStorage keys the redirect mode writes, and anything else you could only reach by inspecting internals.
  • Query parameters already on your invite URL. The package writes its own (the embed key, the mode, and the presentation options you pass), replacing any of those already present, and leaves the rest as they are. What the app does with the rest is the app’s to document. An option the package does not know is not forwarded, so a new app parameter arrives as a new option in a minor release.

​
What counts as breaking

Any of these is a major release:
  • Removing or renaming a covered export, option, callback or payload field.
  • Narrowing an input that was accepted, such as rejecting a container that used to work.
  • Changing a covered documented behaviour, such as letting two launches run at once or delivering onOpen on the redirect path.
  • A type change that makes consumer code that compiled before fail to compile.
  • For the message contract: changing the source marker, an existing event name, or the name or position of an existing field, or renaming a launch URL parameter or one of the three embed values.
Additions are minor. A new export, a new option, a new optional field or a new event does not break a correct integration. Ignore events and fields you do not recognize.

​
Deprecation

A covered surface that is going away is marked deprecated in a minor release and keeps working for at least six months and at least one further minor release before a major removes it. The removal’s changelog entry carries a migration note. You hear about a deprecation in three places:
  1. The changelog entry for the release that marks it.
  2. The list at the end of this section.
  3. Your editor, because the type declarations carry the deprecation and name the replacement.
Install-time warnings from the registry are reserved for versions you should not be running: one that has left support, carries a security problem, or has a defect you have to move off. Deprecating a covered surface never shows up as one. Currently deprecated: Nothing.

​
Support

  • The current major receives features and fixes.
  • The previous major receives security fixes, and fixes for breakage caused by changes on the Catena side, for twelve months after the next major is published. For that window the flow keeps posting the messages the previous major reads.
  • Older majors and the 0.0.x releases are unsupported.
A published version is never unpublished. A version with a defect is superseded by a fixed one and, if you have to move off it, marked deprecated on the registry with a pointer to the fix.
One exception to the deprecation window: a security fix that cannot ship without a breaking change ships with the shortest notice possible, and is announced in the changelog, on this page and in the type declarations at once.

​
The React wrapper

@catenaclearing/connect-sdk-react follows this policy as written: semver from 1.0.0, with no promise across the betas before it, the same definitions of major, minor and patch, the same deprecation notice and the same support windows. It has no policy of its own. What the promise covers for the wrapper:
  • The three exports, useCatenaConnect, CatenaConnect and useCatenaConnectResume, and their options and props. See React.
  • The exported types: CatenaConnectProps, UseCatenaConnectOpenOptions, UseCatenaConnectOptions, UseCatenaConnectResult, UseCatenaConnectResumeOptions, and the core types it re-exports.
  • The behaviour the React page documents and you can observe: teardown on unmount, handlers following the render, options fixed per launch, and delivery once on the return page.
What it does not cover:
  • Anything about the flow. That is the core package’s promise and the Catena app’s.
  • The core package’s internals.
  • The 0.0.x versions. They were published only to reserve the package name, are deprecated on the registry, depend on a core release that predates the flow, and do not work. Install the beta, or 1.0.0 or later once it is published.
Currently deprecated: Nothing.

​
How the policy is enforced

The package maintainers check every changelog entry against this policy before a release is published. Automated checks in the package repository run on every change.