> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catenatelematics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and support

> What the Connect embed SDK's semver promise covers, how deprecation works, and which versions are supported

`@catenaclearing/connect-sdk` follows semver from `1.0.0`.

<Note>
  **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`.
</Note>

* 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](/get-started/connect-sdk/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](/get-started/connect-sdk/events).
* The behaviour these docs describe and you can observe: one launch at a time, which callbacks arrive on which of the [three modes](/get-started/connect-sdk/how-it-works#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](/get-started/connect-sdk/without-the-package#reading-the-completion-messages): 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](/get-started/connect-sdk/without-the-package#the-launch-url): 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](/get-started/connect-sdk/javascript-reference#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.

<Warning>
  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.
</Warning>

## 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](/get-started/connect-sdk/react).
* The exported types: `CatenaConnectProps`, `UseCatenaConnectOpenOptions`, `UseCatenaConnectOptions`, `UseCatenaConnectResult`, `UseCatenaConnectResumeOptions`, and the core types it re-exports.
* The behaviour the [React page](/get-started/connect-sdk/react) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.