# Traffic Toolkit PRO - Chrome Extension

**Wersja:** 8.5.0 (Template Constants + Error Boundaries + Phase 1+2 Complete)
**Typ:** Chrome Extension (Manifest V3)

## Ekosystem tri-table (3 repo)

Projekt żyje w **trzech** repo (ten sam autor), każdy na innej **warstwie** CRM Spolecznosci.net. Warstwy układają się pionowo: **szablon** definiuje pola kreacji → **kreacja** je wypełnia i wskazuje pliki/bundle → **pliki/CDN** hostują media.

| Repo | Warstwa CRM | Rola | Tech |
|------|-------------|------|------|
| [tri-table_szablony](https://github.com/emilszymecki/tri-table_szablony) | `/adserver/templates` — **definicje szablonów** | wersjonuje w Git + transferuje definicje szablonów adservera (pola + kod) między CRM/wersjami | Tampermonkey userscript |
| [tritable_paczki](https://github.com/emilszymecki/tritable_paczki) | `/campaings/.../edit` — **kreacje** + `/adserver/{files,bundles}` (CDN) | buduje paczki ZIP, scrap/play/upload kreacji przez `dev-browser` na zalogowanej Chrome | Node.js CLI (zero deps) |
| [tri_table_kreacje](https://github.com/emilszymecki/Rozszerzenia_Chrome/tree/main/Chrome_rozszerzenia/tri_table_kreacje) | `/campaings/.../edit` — **kreacje** (przodek) | in-page UI: scrap → JSON, transformery (+AI Gemini), apply do kreacji; **wypierany przez tritable_paczki** | Chrome MV3 |

**← Jesteś tutaj: `tri_table_kreacje`** (warstwa kreacji, **przodek** całej architektury). Następca to CLI [`tritable_paczki`](https://github.com/emilszymecki/tritable_paczki), który przejął rdzeń (apply algorithm z `automation.js`, transformery, schema fetching) i dołożył upload paczek/bundli + CDN. Ta wtyczka jest stopniowo wypierana.

Świadoma granica: **żaden z trzech nie ustawia parametrów kampanii** (budżet/daty/targetowanie/sekcje) — wszystkie operują na poziomie **kreacja/szablon**.

## Opis

Automatyzacja kreacji reklamowych w CRM Społeczności.

**Features v8.5.0:**
- ✅ **Template ID Constants** (CONFIG.TEMPLATE_IDS - eliminacja magic strings)
- ✅ **Error Boundaries** (try/catch w main.js + automation.js - graceful failures)
- ✅ **Build Validation** (syntax check + backup/restore system)
- ✅ **Factory Pattern** (createImageTransformerStrategy - eliminacja duplication)
- ✅ **FP Composition** (pipe & compose w fp-utils.js)
- ✅ **Strategy Pattern** (FIELD_APPLIERS - declarative field handling)
- ✅ **Split createUI** (283 → 12 lines, -96%)
- ✅ **Clean Architecture** (18 modułów, Single Responsibility - Issue #1)
- ✅ **Immutable State** (time-travel debugging, undo/getHistory - Issue #3)
- ✅ **Logger Registry** (namespace isolation, per-module loggers - Issue #4)
- ✅ **Deprecation Warnings** (migration path dla 11 globals - Issue #8)
- ✅ **JSON Diff view** (partial deep grouping - pokazuje tylko zmiany)
- ✅ **Dev JSON button** (kopiuje merged schema do clipboard + console.log)
- ✅ **Collapsible Full JSON** (power users mogą edytować ręcznie)
- ✅ **State management jako PRIMARY source** dla runAuto()
- ✅ Schema-based architecture (API jako source of truth)
- ✅ 7 transformerów (adform, dcm, postitial, klikalny_obrazek, obrazek)
- ✅ Sortowanie pół według typu (selecty przed CodeMirror)
- ✅ 200ms delay między polami (fix race condition z CRM mutation observer)
- ✅ Skip wypełniania gdy wartość już OK (optymalizacja)
- ✅ Select2 integration (select_file)
- ✅ 18 modułów z build process

---

## Instalacja

### Chrome Developer Mode (zalecane dla developmentu)

1. **Otwórz Chrome Extensions:**
   ```
   chrome://extensions
   ```

2. **Włącz Developer Mode:**
   - Prawy górny róg: przełącznik "Developer mode"

3. **Load Unpacked:**
   - Kliknij "Load unpacked"
   - Wybierz folder: `/path/to/extension/`

4. **Gotowe!**
   - Extension pojawi się na liście
   - Odśwież stronę CRM

---

## Użycie

1. **Otwórz CRM:**
   ```
   https://crm.spolecznosci.pl/campaings/advertisement/edit/[ID]
   ```

2. **Panel Traffic Toolkit pojawi się automatycznie**
   - Location: Na górze strony (przed kreacjami)

3. **Workflow:**
   - Wybierz transformer (np. "Obrazek")
   - Wypełnij dynamic fields (Obrazek + Click Link)
   - Kliknij "Zmień" → sprawdź JSON w `#ttk-output`
   - Kliknij "AUTO" → kreacja gotowa!

4. **Obserwuj logi:**
   ```
   📋 Sortowanie X pól według typu...
   → field_name (type) = value
   → field_name (type) = value [skip]  ← już OK, skipowane
   ```

---

## Debugging

### Chrome DevTools

1. **Otwórz Console:**
   - `F12` lub `Ctrl+Shift+J`

2. **Szukaj logów:**
   ```
   ⚡ Traffic Toolkit PRO v8.5.0 - Inicjalizacja...
   ✅ Traffic Toolkit PRO v8.5.0 załadowany!
   ⚠️ TTK Deprecation Warning  ← jeśli używasz starych globals
   🛡️ Error boundaries active  ← v8.5.0: graceful error handling
   ```

3. **Sprawdź API:**
   ```javascript
   window.trafficToolkit          // API v8.5.0 (structured namespaces)
   window.campaignData            // DEPRECATED - użyj window.trafficToolkit.campaignData

   // Time-travel debugging
   window.trafficToolkit.toolkitState.undo()       // Cofnij ostatnią zmianę
   window.trafficToolkit.toolkitState.getHistory() // Zobacz historię

   // v8.5.0: Template constants
   CONFIG.TEMPLATE_IDS            // Named template IDs (no magic strings)
   ```

4. **Debug Panel:**
   - `Ctrl+Shift+D` - otwiera panel z pełnym stanem

### Typowe problemy

**Problem:** Extension się nie ładuje
- **Fix:** Sprawdź czy URL pasuje: `https://crm.spolecznosci.pl/campaings/advertisement/edit/*`
- **Fix:** Reload extension: `chrome://extensions` → reload

**Problem:** UI panel się nie pojawia
- **Fix:** Sprawdź Console czy są błędy
- **Fix:** Reload strony CRM (`F5`)

**Problem:** CodeMirror pola się nie wypełniają
- **Fix:** Sprawdź logi - czy widzisz `→ param_id_XXXX (textarea+CM)`
- **Fix:** Zwiększ `TEMPLATE_SELECT` timeout w `config.js` (domyślnie 2000ms)

---

## Update Extension

### Metoda 1: Development (z build process)

1. Edytuj kod w `extension/modules/` (np. `automation.js`)
2. Uruchom build: `node build.js` (łączy moduły → `content.js`)
3. Otwórz `chrome://extensions` i kliknij reload
4. Reload strony CRM (`F5`)

### Metoda 2: Szybka zmiana (bez modułów)

1. Edytuj bezpośrednio `extension/content.js`
2. Otwórz `chrome://extensions` i kliknij reload
3. Reload strony CRM
4. ⚠️ **Uwaga:** Zmiany zostaną nadpisane przy następnym build!

---

## Architektura v8.4.1

```
extension/
├── manifest.json       # Chrome Extension config (Manifest V3)
├── content.js          # Built file (~5291 linii, zbudowany z 18 modułów)
├── modules/            # Kod źródłowy (18 modułów)
│   ├── README.md       # Dokumentacja modułów
│   ├── config.js       # CONFIG, CAMPAIGN_FORMATS, TEMPLATE_IDS (v8.5.0)
│   ├── fp-utils.js     # FP utilities (curry, pipe, compose - v8.5.0)
│   ├── logger.js       # Logger Registry
│   ├── dom-helpers.js  # DOM + CodeMirror
│   ├── schema-api.js   # Schema fetching (with TTL cache)
│   ├── schema-serializer.js # Serialization (immutable prune)
│   ├── utils.js        # DEPRECATED wrapper
│   ├── state.js        # Reactive + immutable
│   ├── templates.js    # CRM_TEMPLATES
│   ├── transformers.js # TRANSFORMER_STRATEGIES
│   ├── automation.js   # runAuto + schema application (with error boundaries)
│   ├── main.js         # Init + deprecations + error boundaries (v8.5.0)
│   └── ...             # + 6 innych modułów
└── README.md           # Ta instrukcja

build.js                # Build script (łączy moduły → content.js + validation)
```

**Content Script:**
- Inject do: `https://crm.spolecznosci.pl/campaings/advertisement/edit/*`
- Run at: `document_idle` (po załadowaniu DOM)
- World: `MAIN` (dostęp do `window`, nie isolated world)
- Permissions: Brak (same-origin fetch)

**Schema-Based Architecture:**
- API zwraca pełną strukturę formularza (`fetchFormCreationSchema`)
- Transformery zwracają tylko overrides (nie pełen JSON)
- Merge: `{...schema} + {...overrides} = JSON`
- Aplikacja z sortowaniem pól i 200ms delay

---

## Key Features v8.4.1

### 1. Immutable State + Time-Travel Debugging (Issue #3)
- **Immutability:** Wszystkie zmiany stanu używają spread operator
- **History stack:** Każda zmiana zapisywana w historii
- **undo():** Cofnij ostatnią zmianę (time-travel debugging)
- **getHistory():** Zobacz pełną historię zmian

**Debug API:**
```javascript
window.trafficToolkit.toolkitState.undo();       // Cofnij
window.trafficToolkit.toolkitState.getHistory(); // Historia
```

### 2. Logger Registry Pattern (Issue #4)
- **Per-module loggers:** Każdy moduł ma własny logger z namespace
- **Namespace isolation:** Łatwe filtrowanie w konsoli
- **Centralized error handling:** Wszystkie błędy w jednym miejscu

**Example:**
```javascript
// W konsoli zobaczysz: [automation] Starting...
[automation] ℹ️ Starting automation...
[ui] 🎨 Rendering fields...
```

### 3. Clean Architecture (Issue #1)
- **18 modułów** (was 12 in v8.1) - Split God Module utils.js
- **Single Responsibility:** Każdy moduł jedna odpowiedzialność
- **5 nowych modułów:**
  - `fp-utils.js` - FP utilities (curry), zero deps
  - `logger.js` - Logger Registry + toast
  - `dom-helpers.js` - DOM + CodeMirror
  - `schema-api.js` - Schema fetching
  - `schema-serializer.js` - Serialization

### 4. Deprecation Warnings (Issue #8)
- **11 window globals** mają deprecation warnings
- **Backward compatible:** Stare API nadal działa
- **One-time warnings:** Styled console output, pokazuje się raz
- **Clear migration path:** `window.trafficToolkit.*`

**Example warning:**
```
⚠️ TTK Deprecation Warning
window.runAuto is deprecated and will be removed in v9.0
Use instead: window.trafficToolkit.runAuto
```

---

## Key Features v8.0

### 1. Schema-Based Architecture
- API jako source of truth
- Transformery uproszczone (tylko overrides)
- Brak ręcznego budowania JSON

### 2. Sortowanie pól według typu
- Selecty PIERWSZE (mogą triggerować re-render)
- CodeMirror NA KOŃCU (żeby nie zostały wyczyszczone)
- Priorytet: select → radio → checkbox → input → textarea → CodeMirror

### 3. 200ms delay między polami
- Fix race condition z CRM mutation observer
- CRM "Injecting copy buttons" nie nadpisuje wartości

### 4. Skip wypełniania gdy wartość OK
- Porównanie `currentValue === desiredValue`
- Brak niepotrzebnych CRM events
- Logi: `[skip]` gdy skipowane

### 5. CodeMirror handling
- `element.nextElementSibling.CodeMirror.doc.setValue()`
- Minimalna metoda (bez refresh/events)
- Czeka 2000ms na init po zmianie template

---

## Deprecated w v8.0

**Moduły wyczyszczone:**
- `api.js` - funkcje w `utils.js`
- `schemas.js` - logika w `applySchemaToCreation()`

**Funkcje usunięte:**
- `fetchTemplateParams()` → `fetchFormCreationSchema()`
- `applyJsonToCreation()` → `applySchemaToCreation()`
- `createTransformerResponse()` - dead code

---

## Support

**GitHub:** https://github.com/emilszymecki/temper_extension_elements

**Docs:** Zobacz główny `CLAUDE.md` w root repo

---

**Ostatnia aktualizacja:** v8.5.0 (Styczeń 2025, Phase 1+2 Complete: Quick Wins + Production Hardening)
**Build:** 5291 linii, 212.26 KB (was 5189 lines, 208.17 KB in v8.4.1)
**Moduły:** 18 sztuk
**Typ:** Chrome Extension (Manifest V3)