> ## Documentation Index > Fetch the complete documentation index at: https://docs.tagada.io/llms.txt > Use this file to discover all available pages before exploring further. # Internal Developer Knowledge > Critical deprecated APIs, must-know architecture patterns, and active migration paths for the Tagada codebase This page distills the most important internal knowledge for developers working on the Tagada platform. It covers deprecated APIs you should stop using, architecture patterns you must understand, and migrations currently in progress. *** ## Deprecated APIs These APIs have replacements and should not be used in new code. Existing usages should be migrated when touching the relevant files. ### Plugin SDK (`@tagadapay/plugin-sdk`) | Deprecated | Use Instead | Notes | | -------------------------------------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `useOffer()` / `useOfferQuery()` | `usePreviewOffer()` | Lighter footprint, auto-applies stepConfig.paymentInitiator (MIT/CIT). Kept exported for backwards compatibility. | | `useFunnelLegacy()` / `useSimpleFunnel()` | `TagadaProvider` + `useFunnel()` | Legacy hooks maintain duplicate session logic | | `onSuccess` / `onFailure` (payment callbacks) | `onPaymentSuccess` / `onPaymentFailed` | Removal planned for next SDK major version | | `staticResources` (on step config, funnel config, hooks) | `resources` | Applies to `RuntimeStepConfig`, `LocalFunnelConfig`, `UseStepConfigResult` | | `getAssignedStaticResources()` | `getAssignedResources()` | Same rename as above | | `getPreviewParams()` | `getSDKParams()` | In `previewMode.ts` | | `transformToCheckout()` | `transformToCheckoutSession()` | In `offers.ts` | | `@tagadapay/plugin-sdk/react` subpath | `@tagadapay/plugin-sdk/v2` or root | `./react` is the Legacy V1 surface (SWR-based). V2 uses TanStack Query. | | `/config/resources.static.json` | `/config/funnel.local.json` | Old static resource config path for local dev | ### Node SDK (`@tagadapay/node-sdk`) | Deprecated | Use Instead | Why | | ----------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `checkout.init()` | `checkout.createSession()` | `init()` follows HTTP 302 redirects and can parse HTML as JSON. `createSession()` returns a clean `checkoutToken`. | | `plugins.deploymentDetails()` | `plugins.retrieveDeployment()` | Simplified signature (no `storeId` required) | ### CRM App | Deprecated | Use Instead | Location | | -------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- | | `FlowStep` type | `FunnelNode` | `storefront/types.ts` | | `StepConfig.paymentFlowId` (top-level) | `stepConfig.payment.paymentFlowId` | Nested under `payment` object | | `useAnalyticsV4` | Per-metric hooks (`useRebillRevenueData`, etc.) | `lib/api/analytics.ts` -- v4 is a monolithic hook being split | | `payment-guard.tsx` | `payment-method-valid-guard.tsx` | Guard component rename | ### Studio App | Deprecated | Use Instead | Notes | | ------------------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- | | `setActionHandler()` on DataStore | `registerAction(type, handler)` | Per-action-type registry. `setActionHandler` is a single catch-all fallback. | | Bundle mode `'esbuild'` | `'standalone'` | Name was misleading (no tree-shaking involved) | | Bundle modes `'interactive'` / `'esbuild-bundle'` | `'runtime'` / `'islands'` / `'treeshake'` / `'standalone'` | Legacy bundle modes with limited SDK support | *** ## Must-Know Architecture Patterns These are non-obvious patterns that every developer touching the codebase must understand. ### CRM App The CRM is a **Vite SPA with React Router** -- not Next.js. Server-side API and tRPC routers live on the main Tagada app at `/api/crm/trpc`, not inside `crm-app`. **Auth and org switching:** * Clerk provides auth. JWT is passed as `Authorization: Bearer` to tRPC. * Org context is synced via `OrgRouteWrapper` -- when the user switches org, `useResetQueries()` invalidates all queries to avoid stale data from the previous org. **Funnel dual model:** * Funnels have both `nodes`/`edges` (V2 graph model) and legacy `steps` (flat list), kept in sync via `useFunnelData`. * Always **deep-copy** nodes/edges before mutating -- they come from React Query cache. * Never copy `url` when cloning steps -- the backend recomputes URLs from mount points. * Split-test variants each have their own `stepConfig`. **Plugin lifecycle:** * `instantiate` creates a plugin instance but does **NOT** mount it to a funnel step. * The user must explicitly configure and publish. Code should not assume instantiation = live. ### Studio App **Two operating modes:** * **Embedded** (inside CRM iframe): communicates via Builder Protocol (`postMessage`), skips localStorage hydration to avoid stale data. * **Standalone** (direct URL): authenticated via Clerk, full localStorage persistence for work-in-progress recovery. **DataStore (commerce layer):** * Vanilla Zustand store (works outside React for island hydration). * **MockResolver** provides static fixtures for design mode. **TagadaResolver** makes real API calls in live mode. * Use `registerAction(type, handler)` to register action handlers. The old `setActionHandler` catch-all is deprecated. **Current bundle modes:** | Mode | Output | Best For | | ------------ | --------------------------------------------- | ------------------------------------ | | `runtime` | Monolithic JS (\~3.5 MB) | Development, testing | | `islands` | Static HTML + hydrated commerce (\~620 KB JS) | **Production** (fastest first paint) | | `treeshake` | Per-component JS loading | Templates using few components | | `standalone` | Single self-contained HTML | Plugin deployment, previews | The modes `interactive`, `esbuild-bundle`, and `esbuild` are **legacy** and should not be used. **Template parsing:** * `parseTemplateFile()` accepts 3 formats for backward compatibility: `StudioTemplateFile` wrapper, legacy `{ version, template }`, and raw `FunnelTemplate`. * Legacy page types `upsell` / `downsell` auto-normalize to `offer`. *** ## Active Migration Paths These transitions are in progress. New code should target the "After" column. | Area | Before (Legacy) | After (Current) | Bridge | | -------------------------- | ------------------------------------- | ----------------------------------------------- | ------------------------------------------------ | | **Funnel model** | `steps` (flat list) | `nodes` + `edges` (graph) | `useFunnelData` syncs both representations | | **Step config: payment** | `StepConfig.paymentFlowId` | `stepConfig.payment.paymentFlowId` | Both read in CRM; write to nested form | | **Step config: resources** | `staticResources` | `resources` | SDK reads both with fallback | | **Analytics hooks** | `useAnalyticsV4` (monolithic) | Per-metric hooks (`useRebillRevenueData`, etc.) | v4 still works; new dashboards use per-metric | | **Conditions** | `LegacyCondition` (flat) | JSONLogic structured conditions | `ConditionBuilder` + `isLegacyCondition()` | | **Plugin SDK surface** | V1 (`./react`, SWR) | V2 (`./v2` or root, TanStack Query) | V1 still published; new plugins use V2 | | **Funnel hooks** | `useFunnelLegacy` / `useSimpleFunnel` | `TagadaProvider` + `useFunnel` | Legacy hooks re-exported for backward compat | | **Payment callbacks** | `onSuccess` / `onFailure` | `onPaymentSuccess` / `onPaymentFailed` | Both work today; old names removed in next major |