Versioning and the stability guarantee

The problem this solves

You will put @quberoute/sdk inside an app, ship it to an app store, and stop thinking about it. Some of those installs will still be running the version you shipped in three years’ time, because somebody who has not updated an app since 2026 still taps links.

That makes our wire format a promise rather than an implementation detail. A promise nobody wrote down is one somebody breaks by renaming a field in good faith, so here it is written down — and there is a test suite whose only job is to fail if we break it.

The guarantee

You are on v1. Within v1, we will never:

1. remove or rename an exported function, class, type or method;
2. remove or rename a field the server sends, or a field the SDK sends;
3. change the meaning, units or type of an existing field;
4. add a REQUIRED option, or make an existing optional one required;
5. narrow what an existing field accepts;
6. stop serving a request from an older v1 SDK.

Rule 6 is the one that matters most, and it is the one most often missing elsewhere. Everything you send us is optional except your install token. A client that has never heard of a field we added last month simply does not send it, and is served correctly. We prove that with a test that builds a client speaking only the original shape and asserts today’s server answers it.

What we may do

• add optional options;
• add fields to responses — your code ignores what it does not read;
• add new endpoints;
• relax validation;
• improve matching, including adding new strategies;
• change anything marked internal, below.

What is covered, and what is not

Covered. These exports:

// exports
  QubeRoute
  QubeRouteClient
  SDK_VERSION
  toMinorUnits

// client methods
  onLink()
  track()
  reset()

// init options
  key
  endpoint?
  timeoutMs?
  deferredMatching?
  clipboardMatching?
  onError?
  storage?
  platform?

Not covered, and may change in any release. The transport and platform-detection modules; the storage keys and the serialised form of the offline queue; the order and number of requests the SDK makes; and any response field not listed above.

That last one is a real asymmetry and it is deliberate: if you read a field we never documented, you are relying on something we did not promise, and we will not carry it. If you need something that is not on the list, ask — [email protected] — and we will either document it or explain why not.

How long a version lasts

At least 24 months after its successor ships. Two years because your release cycle is not ours to control: a team shipping annually to a slow-updating user base needs two cycles to move everybody, and the last install to update is the one that matters.

The clock does not start until the replacement ships, is documented, and is stable. Nothing is ever deprecated in favour of something you cannot yet use.

How you find out

• an entry in the changelog on the day the successor ships
• a deprecation notice at the top of the version’s documentation page
• an email to every organisation with an app whose keys have served a request from that version in the previous 90 days

What “supported” means

• every documented endpoint continues to answer correctly
• security fixes are applied
• a bug that breaks a documented behaviour is fixed

And what it does not mean:

• new features are added to it
• new fields appear in its responses

How we hold ourselves to it

tests/unit/sdk-contract.test.ts checks every list in both directions and against a second, independent source: the exports against what the module really exports, the options against the type declaration, the wire fields against what the route handlers actually read, and the signals against our own security documentation. Deleting an entry to make one test pass makes another fail, and the one that fails names the field.

tests/db/sdk-v1-compat.test.ts is the guarantee itself: it builds a client that knows only the shape v1 launched with — no clipboard fields, no Android — and asserts the current server serves it correctly.

One honest limit. These prove we have not broken the contract in the repository. They cannot prove a deployed server has not, and they cannot prove a future one will not. Nothing tests a promise about the future; what a test can do is make breaking it loud, and that is what these do.