# Recca Integration SDK Changelog

> Public changelog for SDK packages used by federation tenants:
> `@recca/embed-components` (web components) and `@recca/federation-sdk`
> (Node S2S client). Each entry highlights what tenant-side code **must
> change** to upgrade safely.
>
> SDKs are still pre-1.0 — breaking changes happen. Pin exact versions
> in `package.json` until you've tested the upgrade.

---

## `@recca/embed-components`

### 0.1.3 — 2026-05-17

**Recommended.** Adds Flow B (headless server-side mint + display)
which is the right pattern when the tenant already has their own auth
(VKID / Yandex / email / Telegram). Avoids surfacing a Recca OAuth
popup to users who are already logged in on the tenant's side.

- **NEW** `<recca-referral-display url="..." share-text="..." theme="visitka">`
  — renders a generated short URL with copy + share buttons. No
  network from the browser, no popup. Tenant's backend mints the URL
  via `recca.referralLinks.create(tenantReccaId, {offer_id})`.
- **WARNING** `<recca-referral-input>` (Flow A) is still supported but
  opens the Recca OAuth popup when no session exists. Use it ONLY when
  the tenant's only login mechanism is Recca itself.

Migration from 0.1.2: drop-in additive — existing widgets keep working.

### 0.1.2 — 2026-05-16

- **FIX** Shadow DOM CSS bug: `visitka` theme rendered as plain text
  on some component instances. Replaced manual `<style>` injection
  with `adoptedStyleSheets` API.
- **FIX** Vue compiler integration: documented `compilerOptions.isCustomElement`
  config to avoid "Failed to resolve component" warnings.

Migration from 0.1.1: drop-in. If you saw the CSS leak — it's gone.

### 0.1.1 — 2026-05-16

- **FIX** `@recca/embed-tokens@0.1.0` was incorrectly declared as a
  runtime `dependency` (not on npm registry → `npm install` failed
  with 404). Moved to `devDependencies`; tsup inlines tokens at
  build time, so consumer sites need nothing extra.

Migration from 0.1.0: required upgrade — 0.1.0 is broken at install time.

### 0.1.0 — 2026-05-15

- **INITIAL** Web Components SDK: `<recca-login-button>`,
  `<recca-referral-input>`, `<recca-cabinet-kpi>`, `<recca-bonus-balance>`,
  `<recca-recent-leads>`, `<recca-referral-tree>`, `<recca-action-button>`.
- Shadow DOM isolation, `theme="visitka|light|dark"` prop, origin-gated
  JSON fetches.

---

## `@recca/federation-sdk`

### 1.2.0 — 2026-05-17

- **NEW** `ReferralLink` now includes `short_url:
  https://recca.ru/d/<12-char>` (~30 chars) alongside the long `url`
  (200+ chars). Use `short_url` for sharing in chats / SMS / QR codes;
  use `url` for embedding on your own pages (no extra hop). Attribution
  is equivalent — both eventually deliver the same `signed_ref` to
  the tenant's landing page.
- Backend WV-0219.

Migration from 1.1.0: drop-in additive. Consumers that read `data.url`
keep working; opt into `data.short_url` where relevant.

### 1.1.0 — 2026-05-14

- **NEW** `recca.referralLinks.create(tenantReccaId, {offer_id})`
  server-side endpoint (Flow B headless mint). No browser popup, no
  Recca OAuth — tenant backend mints links on behalf of their members.
- Requires API key with `users:impersonate` scope.

### 1.0.0 — 2026-04-26

- **INITIAL** typed S2S client + webhook signature middleware:
  `recca.users.upsert(...)`, `recca.leads.create(...)`,
  `recca.conversions.register(...)`, `recca.users.getTree(...)`,
  `webhookMiddleware()`.
- WV-0151 M9 (identity bridge) + WV-0151 Block 2 (lead ingestion).

---

## Compatibility matrix (recommended pairings)

| Tenant uses | Min `@recca/embed-components` | Min `@recca/federation-sdk` |
|---|---|---|
| Read-only widgets (KPI/leads/tree) | 0.1.2 | — (not needed) |
| Flow A (`<recca-referral-input>` with popup) | 0.1.2 | — |
| Flow B (`<recca-referral-display>` headless) | 0.1.3 | 1.2.0 |
| Webhooks receiver | — | 1.0.0 |
| Multi-provider upsert (yandex/telegram/phone) | — | 1.0.0 (WV-0220 server-side, SDK passthrough) |

Pin to the **minimum** versions in this table — newer is always
backward-compatible unless explicitly noted otherwise above.

---

## Reporting issues

If something breaks after an upgrade — open an issue with:
- Package + version (before / after)
- Browser / Node version
- Exact error message + stack trace
- Minimum reproducible snippet

`semakin1306@gmail.com` / @reccatestbot (Telegram)