# SDK migration notes

> Customer-facing API and SDK compatibility notes, versions, and migration windows.

Canonical: <https://www.tryadeli.com/docs/sdk-migrations>

This page records customer-facing compatibility changes between the public API and `@adeli/sdk`. It contains no private rollout links or internal release details.

> **Warning: Pre-release**
>
> `@adeli/sdk` has not been published yet. There is no minimum SDK version, migration action, or API deprecation date to apply today. Continue using the documented HTTP API until a released version is announced.

## Candidate contract review — not a release notice

The initial SDK candidate replaces broad response placeholders with typed contracts for all 48 operations. Consumers regenerating their own types should review these areas before adopting the candidate:

- Required account capability fields and nullable profile metadata are represented explicitly; do not assume missing fields and `null` are interchangeable.
- Account detail and connection routes retain their profile scope. Ads operations retain required account/query scope and idempotency keys where applicable.
- Accepted publishing (`202`) and partial outcomes (`207`) are successful HTTP responses, not proof that every provider action finished successfully. Inspect the returned status and per-item outcomes.
- Comment and campaign deletion can return `204` with no JSON body. Do not attempt to decode an empty response.
- Error responses retain the nested `error` envelope; permission/reconnection details vary and must be narrowed safely.
- Generated response fixtures and validators may need updates for the concrete field, enum, and union definitions instead of accepting arbitrary objects.

These notes describe local contract/type review, not a claim that a new API version is deployed. No SDK upgrade, deprecation, or compatibility-window date is announced. A released entry must confirm actual API availability and supply any necessary migration examples before customers are asked to change their integrations.

## How future entries are structured

Each released change will name the affected operation IDs, API availability and deprecation dates, the minimum SDK version, and a before/after migration example. Breaking API changes will include a compatibility window or staged rollout; an SDK major version alone does not protect existing HTTP API clients.

For example, a future entry will state the actual values rather than placeholders:

| Field               | Release entry will include                                            |
| ------------------- | --------------------------------------------------------------------- |
| Affected operations | Exact `operationId` names and public routes                           |
| Minimum SDK         | Published `@adeli/sdk` version                                        |
| API timing          | Availability date and any deprecation date                            |
| Migration           | A before/after request or SDK call that compiles against that release |

Until then, follow [Quickstart](https://www.tryadeli.com/docs/quickstart) and the [API reference](https://www.tryadeli.com/docs/api). The [TypeScript SDK page](https://www.tryadeli.com/docs/sdk) is intentionally marked pre-release and must not be treated as an installation promise.