@blakfy/cookie 2.1.1 → 2.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +194 -120
- package/README.md +594 -480
- package/SECURITY.md +54 -0
- package/dist/cookie-defaults.js +1 -2
- package/dist/cookie-defaults.min.js +1 -2
- package/dist/cookie.d.ts +171 -0
- package/dist/cookie.js +2863 -2376
- package/dist/cookie.js.map +4 -4
- package/dist/cookie.min.js +2 -3
- package/{ARCHITECTURE.md → docs/architecture.md} +187 -186
- package/{COMPLIANCE.md → docs/compliance.md} +199 -191
- package/{MIGRATION.md → docs/migration.md} +172 -156
- package/docs/release.md +176 -0
- package/{TCF-CERTIFICATION.md → docs/tcf-certification.md} +115 -106
- package/package.json +145 -61
- package/status.json +30 -30
|
@@ -1,186 +1,187 @@
|
|
|
1
|
-
# Blakfy Cookie — v2.0 Architecture
|
|
2
|
-
|
|
3
|
-
> Tek script ile yüklenen, sıfır bağımlılık, çok motorlu uyumluluk sağlayan widget tabanlı cookie consent sistemi. Vanilla + Next.js destekli, jsDelivr CDN üzerinden otomatik güncellenir.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## Tasarım İlkeleri
|
|
8
|
-
|
|
9
|
-
| İlke
|
|
10
|
-
|
|
11
|
-
| **Dağıtım**
|
|
12
|
-
| **Sıfır bağımlılık**
|
|
13
|
-
| **Geriye uyumluluk**
|
|
14
|
-
| **Boyut bütçesi**
|
|
15
|
-
| **Re-consent disiplini** | Sadece `data-blakfy-version` (policyVersion) re-consent tetikler
|
|
16
|
-
| **Branding**
|
|
17
|
-
| **Compliance kapsamı**
|
|
18
|
-
|
|
19
|
-
---
|
|
20
|
-
|
|
21
|
-
## Klasör Yapısı
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
blakfy-cookie/
|
|
25
|
-
├── src/ # v2 kaynak ağacı
|
|
26
|
-
│ ├── core/ # consent state, cookie I/O, audit, events
|
|
27
|
-
│ ├── compliance/ # motor + yasal uyumluluk modülleri
|
|
28
|
-
│ │ ├── google-cmv2.js
|
|
29
|
-
│ │ ├── microsoft-uet.js
|
|
30
|
-
│ │ ├── yandex-metrica.js
|
|
31
|
-
│ │ ├── tcf-v2.js
|
|
32
|
-
│ │ ├── ccpa.js
|
|
33
|
-
│ │ ├── gpc.js
|
|
34
|
-
│ │ └── dnt.js
|
|
35
|
-
│ ├── i18n/ # 23 dil, BCP47 detect
|
|
36
|
-
│ ├── ui/ # banner, modal, status-bar, badge, focus-trap
|
|
37
|
-
│ ├── gating/ # script + iframe unblocker, observer, cleaner
|
|
38
|
-
│ ├── presets/ # 18 hazır araç entegrasyonu
|
|
39
|
-
│ ├── geo/ # jurisdiction tespiti (GDPR/CCPA/LGPD)
|
|
40
|
-
│ ├── api.js # window.BlakfyCookie public API
|
|
41
|
-
│ └── index.js # entry
|
|
42
|
-
├── packages/
|
|
43
|
-
│ └── cookie-next/ # Next.js wrapper (npm: @blakfy/cookie-next)
|
|
44
|
-
├── dist/ # CDN servis edilen build çıktısı
|
|
45
|
-
├── examples/ # vanilla + nextjs + wordpress
|
|
46
|
-
├── tests/ # Vitest (jsdom)
|
|
47
|
-
├── scripts/ # esbuild build script'i
|
|
48
|
-
├── .github/workflows/ # test.yml + release.yml
|
|
49
|
-
├── legacy/ # v1.x kaynak (geri dönüş güvenliği)
|
|
50
|
-
├── ARCHITECTURE.md # bu dosya
|
|
51
|
-
├── COMPLIANCE.md # uyumluluk detayları
|
|
52
|
-
├── TCF-CERTIFICATION.md # IAB Europe başvuru süreci
|
|
53
|
-
├── CHANGELOG.md
|
|
54
|
-
├── MIGRATION.md # v1 → v2 (genelde sıfır iş)
|
|
55
|
-
└── README.md # AI-friendly kurulum kılavuzu
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## Veri Akışı
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
┌─────────────────────────────────────────────────────┐
|
|
64
|
-
│ 1. Bootstrap (cookie-defaults.min.js, <head> ilk) │
|
|
65
|
-
│ - GCM v2 default 'denied' │
|
|
66
|
-
│ - UET default 'denied' │
|
|
67
|
-
│ - Yandex cookies engelli │
|
|
68
|
-
│ - GPC/DNT header okundu, opt-out flag set │
|
|
69
|
-
└─────────────────────┬───────────────────────────────┘
|
|
70
|
-
↓
|
|
71
|
-
┌─────────────────────────────────────────────────────┐
|
|
72
|
-
│ 2. Widget (cookie.min.js, <body> sonu) │
|
|
73
|
-
│ ───────────────────────────────────────── │
|
|
74
|
-
│ a) src/geo/jurisdiction tespit (GDPR/CCPA/...) │
|
|
75
|
-
│ b) src/core/consent-store cookie oku │
|
|
76
|
-
│ c) Yoksa → src/ui/banner render │
|
|
77
|
-
│ (sağ alt köşede badge dahil) │
|
|
78
|
-
│ d) src/gating/observer DOM tara │
|
|
79
|
-
│ e) Aktif preset'leri kaydet │
|
|
80
|
-
└─────────────────────┬───────────────────────────────┘
|
|
81
|
-
↓
|
|
82
|
-
┌─────────────────────────────────────────────────────┐
|
|
83
|
-
│ 3. Kullanıcı kararı │
|
|
84
|
-
│ - acceptAll / rejectAll / save preferences │
|
|
85
|
-
│ ↓ │
|
|
86
|
-
│ src/core/consent-store cookie yaz │
|
|
87
|
-
│ src/compliance/* her motora sinyal gönder │
|
|
88
|
-
│ src/gating/script-unblocker tag'leri aktive et │
|
|
89
|
-
│ src/core/audit endpoint POST │
|
|
90
|
-
│ window.BlakfyCookie.onChange listener'ları emit │
|
|
91
|
-
└─────────────────────────────────────────────────────┘
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
---
|
|
95
|
-
|
|
96
|
-
## Public API Yüzeyi
|
|
97
|
-
|
|
98
|
-
### v1 Uyumluluğu (kırılmaz)
|
|
99
|
-
|
|
100
|
-
```js
|
|
101
|
-
window.BlakfyCookie.open() / acceptAll() / rejectAll()
|
|
102
|
-
window.BlakfyCookie.getConsent("analytics")
|
|
103
|
-
window.BlakfyCookie.getState() / onChange(fn) / setLocale("ar")
|
|
104
|
-
window.BlakfyCookie.version
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
### v2 Yeni API
|
|
108
|
-
|
|
109
|
-
```js
|
|
110
|
-
// Tag-gating
|
|
111
|
-
BlakfyCookie.onConsent("marketing", granted => {})
|
|
112
|
-
BlakfyCookie.registerCleanup({ category, cookies, storage })
|
|
113
|
-
BlakfyCookie.unblock("marketing")
|
|
114
|
-
BlakfyCookie.scan()
|
|
115
|
-
BlakfyCookie.usePreset("google-analytics")
|
|
116
|
-
|
|
117
|
-
// IAB TCF v2.2
|
|
118
|
-
window.__tcfapi("getTCData", 2, callback)
|
|
119
|
-
BlakfyCookie.tcf.getTCString()
|
|
120
|
-
|
|
121
|
-
// CCPA / CPRA
|
|
122
|
-
BlakfyCookie.ccpa.optOut() / isOptedOut()
|
|
123
|
-
|
|
124
|
-
// Jurisdiction
|
|
125
|
-
BlakfyCookie.getJurisdiction()
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
---
|
|
129
|
-
|
|
130
|
-
## Re-consent Politikası
|
|
131
|
-
|
|
132
|
-
Tek tetikleyici: `data-blakfy-version` (politika versiyonu) değişimi.
|
|
133
|
-
|
|
134
|
-
```js
|
|
135
|
-
// Cookie okuma
|
|
136
|
-
if (s.version !== config.policyVersion) return null;
|
|
137
|
-
// blakfy version (kütüphane sürümü) artık karşılaştırılmıyor — v1 bug fix
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
Yani sen `cookie.js`'i `v2.0.0 → v2.0.1` güncellersen kullanıcılar etkilenmez. Sadece sen `data-blakfy-version="1.0" → "2.0"` yaparsan re-consent tetiklenir.
|
|
141
|
-
|
|
142
|
-
---
|
|
143
|
-
|
|
144
|
-
## Branding (Anti-Tampering)
|
|
145
|
-
|
|
146
|
-
3 katmanlı koruma:
|
|
147
|
-
|
|
148
|
-
1. **CSS:** `.blakfy-badge { display: flex !important; opacity: 1 !important; pointer-events: auto !important; }`
|
|
149
|
-
2. **DOM:** `MutationObserver` widget kökünü izler. Badge silinirse 50ms sonra geri ekler. `data-*` attribute manipulation görmezden gelinir.
|
|
150
|
-
3. **Kod:** Badge HTML build sırasında sabitlenir, config'den okumaz.
|
|
151
|
-
|
|
152
|
-
Test: `tests/badge-anti-tamper.test.js` — silme, CSS injection, attribute tampering senaryoları.
|
|
153
|
-
|
|
154
|
-
---
|
|
155
|
-
|
|
156
|
-
## Boyut Bütçesi
|
|
157
|
-
|
|
158
|
-
| Katman
|
|
159
|
-
|
|
160
|
-
| Core (consent + UI + i18n + badge) | ≤ 14 KB
|
|
161
|
-
| Compliance toplamı (lazy)
|
|
162
|
-
| 18 Preset (lazy)
|
|
163
|
-
| **TOPLAM (her şey aktif)**
|
|
164
|
-
|
|
165
|
-
`scripts/build.js` her release'de boyut kontrolü yapar; bütçeyi aşan PR'lar CI'da fail olur.
|
|
166
|
-
|
|
167
|
-
---
|
|
168
|
-
|
|
169
|
-
## Geliştirme Akışı
|
|
170
|
-
|
|
171
|
-
```bash
|
|
172
|
-
npm install # workspace + cookie-next deps
|
|
173
|
-
npm run dev # esbuild watch
|
|
174
|
-
npm test # Vitest jsdom
|
|
175
|
-
npm run build # dist/cookie.min.js + cookie-defaults.min.js
|
|
176
|
-
npm run build:next # tsup → packages/cookie-next/dist
|
|
177
|
-
npm run size # bundle size guard
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
Release:
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
git
|
|
184
|
-
|
|
185
|
-
#
|
|
186
|
-
|
|
1
|
+
# Blakfy Cookie — v2.0 Architecture
|
|
2
|
+
|
|
3
|
+
> Tek script ile yüklenen, sıfır bağımlılık, çok motorlu uyumluluk sağlayan widget tabanlı cookie consent sistemi. Vanilla + Next.js destekli, jsDelivr CDN üzerinden otomatik güncellenir.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Tasarım İlkeleri
|
|
8
|
+
|
|
9
|
+
| İlke | Karar | Neden |
|
|
10
|
+
| ------------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| **Dağıtım** | npm registry + jsDelivr `npm/@blakfy/cookie@2` major-pin | Kullanıcılar `@2`'ye bağlanır; her npm publish edince jsDelivr otomatik servise alır. `@latest` yasak (immutable versioning). |
|
|
12
|
+
| **Sıfır bağımlılık** | Vanilla JS, IIFE, ES5 syntax (cookie.js); ESM build (cookie-next) | Eski tarayıcılar, çoklu stack |
|
|
13
|
+
| **Geriye uyumluluk** | v1 API kontratı v2'de korunur | Mevcut `@1` entegrasyonları kırılmaz, yeni metotlar additive |
|
|
14
|
+
| **Boyut bütçesi** | Core ≤ 24 KB minified+gzip (gerçek: ~23 KB) | Site performansı; rakipler 50-150 KB |
|
|
15
|
+
| **Re-consent disiplini** | Sadece `data-blakfy-version` (policyVersion) re-consent tetikler | `cookie.js` bump'ı kullanıcıyı etkilemez |
|
|
16
|
+
| **Branding** | "Powered by Blakfy Studio" badge — kapatılamaz, anti-tampering korumalı | Marka koruması |
|
|
17
|
+
| **Compliance kapsamı** | Google CMv2 + Microsoft UET + Yandex Metrica + IAB TCF v2.2 + CCPA + GPC + DNT | Üç büyük arama motoru + AB + ABD yasal uyumluluk |
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Klasör Yapısı
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
blakfy-cookie/
|
|
25
|
+
├── src/ # v2 kaynak ağacı
|
|
26
|
+
│ ├── core/ # consent state, cookie I/O, audit, events
|
|
27
|
+
│ ├── compliance/ # motor + yasal uyumluluk modülleri
|
|
28
|
+
│ │ ├── google-cmv2.js
|
|
29
|
+
│ │ ├── microsoft-uet.js
|
|
30
|
+
│ │ ├── yandex-metrica.js
|
|
31
|
+
│ │ ├── tcf-v2.js
|
|
32
|
+
│ │ ├── ccpa.js
|
|
33
|
+
│ │ ├── gpc.js
|
|
34
|
+
│ │ └── dnt.js
|
|
35
|
+
│ ├── i18n/ # 23 dil, BCP47 detect
|
|
36
|
+
│ ├── ui/ # banner, modal, status-bar, badge, focus-trap
|
|
37
|
+
│ ├── gating/ # script + iframe unblocker, observer, cleaner
|
|
38
|
+
│ ├── presets/ # 18 hazır araç entegrasyonu
|
|
39
|
+
│ ├── geo/ # jurisdiction tespiti (GDPR/CCPA/LGPD)
|
|
40
|
+
│ ├── api.js # window.BlakfyCookie public API
|
|
41
|
+
│ └── index.js # entry
|
|
42
|
+
├── packages/
|
|
43
|
+
│ └── cookie-next/ # Next.js wrapper (npm: @blakfy/cookie-next)
|
|
44
|
+
├── dist/ # CDN servis edilen build çıktısı
|
|
45
|
+
├── examples/ # vanilla + nextjs + wordpress
|
|
46
|
+
├── tests/ # Vitest (jsdom)
|
|
47
|
+
├── scripts/ # esbuild build script'i
|
|
48
|
+
├── .github/workflows/ # test.yml + release.yml
|
|
49
|
+
├── legacy/ # v1.x kaynak (geri dönüş güvenliği)
|
|
50
|
+
├── ARCHITECTURE.md # bu dosya
|
|
51
|
+
├── COMPLIANCE.md # uyumluluk detayları
|
|
52
|
+
├── TCF-CERTIFICATION.md # IAB Europe başvuru süreci
|
|
53
|
+
├── CHANGELOG.md
|
|
54
|
+
├── MIGRATION.md # v1 → v2 (genelde sıfır iş)
|
|
55
|
+
└── README.md # AI-friendly kurulum kılavuzu
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Veri Akışı
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
┌─────────────────────────────────────────────────────┐
|
|
64
|
+
│ 1. Bootstrap (cookie-defaults.min.js, <head> ilk) │
|
|
65
|
+
│ - GCM v2 default 'denied' │
|
|
66
|
+
│ - UET default 'denied' │
|
|
67
|
+
│ - Yandex cookies engelli │
|
|
68
|
+
│ - GPC/DNT header okundu, opt-out flag set │
|
|
69
|
+
└─────────────────────┬───────────────────────────────┘
|
|
70
|
+
↓
|
|
71
|
+
┌─────────────────────────────────────────────────────┐
|
|
72
|
+
│ 2. Widget (cookie.min.js, <body> sonu) │
|
|
73
|
+
│ ───────────────────────────────────────── │
|
|
74
|
+
│ a) src/geo/jurisdiction tespit (GDPR/CCPA/...) │
|
|
75
|
+
│ b) src/core/consent-store cookie oku │
|
|
76
|
+
│ c) Yoksa → src/ui/banner render │
|
|
77
|
+
│ (sağ alt köşede badge dahil) │
|
|
78
|
+
│ d) src/gating/observer DOM tara │
|
|
79
|
+
│ e) Aktif preset'leri kaydet │
|
|
80
|
+
└─────────────────────┬───────────────────────────────┘
|
|
81
|
+
↓
|
|
82
|
+
┌─────────────────────────────────────────────────────┐
|
|
83
|
+
│ 3. Kullanıcı kararı │
|
|
84
|
+
│ - acceptAll / rejectAll / save preferences │
|
|
85
|
+
│ ↓ │
|
|
86
|
+
│ src/core/consent-store cookie yaz │
|
|
87
|
+
│ src/compliance/* her motora sinyal gönder │
|
|
88
|
+
│ src/gating/script-unblocker tag'leri aktive et │
|
|
89
|
+
│ src/core/audit endpoint POST │
|
|
90
|
+
│ window.BlakfyCookie.onChange listener'ları emit │
|
|
91
|
+
└─────────────────────────────────────────────────────┘
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Public API Yüzeyi
|
|
97
|
+
|
|
98
|
+
### v1 Uyumluluğu (kırılmaz)
|
|
99
|
+
|
|
100
|
+
```js
|
|
101
|
+
window.BlakfyCookie.open() / acceptAll() / rejectAll();
|
|
102
|
+
window.BlakfyCookie.getConsent("analytics");
|
|
103
|
+
window.BlakfyCookie.getState() / onChange(fn) / setLocale("ar");
|
|
104
|
+
window.BlakfyCookie.version;
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### v2 Yeni API
|
|
108
|
+
|
|
109
|
+
```js
|
|
110
|
+
// Tag-gating
|
|
111
|
+
BlakfyCookie.onConsent("marketing", (granted) => {});
|
|
112
|
+
BlakfyCookie.registerCleanup({ category, cookies, storage });
|
|
113
|
+
BlakfyCookie.unblock("marketing");
|
|
114
|
+
BlakfyCookie.scan();
|
|
115
|
+
BlakfyCookie.usePreset("google-analytics");
|
|
116
|
+
|
|
117
|
+
// IAB TCF v2.2
|
|
118
|
+
window.__tcfapi("getTCData", 2, callback);
|
|
119
|
+
BlakfyCookie.tcf.getTCString();
|
|
120
|
+
|
|
121
|
+
// CCPA / CPRA
|
|
122
|
+
BlakfyCookie.ccpa.optOut() / isOptedOut();
|
|
123
|
+
|
|
124
|
+
// Jurisdiction
|
|
125
|
+
BlakfyCookie.getJurisdiction(); // "GDPR" | "CCPA" | "LGPD" | "default"
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Re-consent Politikası
|
|
131
|
+
|
|
132
|
+
Tek tetikleyici: `data-blakfy-version` (politika versiyonu) değişimi.
|
|
133
|
+
|
|
134
|
+
```js
|
|
135
|
+
// Cookie okuma
|
|
136
|
+
if (s.version !== config.policyVersion) return null; // re-consent
|
|
137
|
+
// blakfy version (kütüphane sürümü) artık karşılaştırılmıyor — v1 bug fix
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Yani sen `cookie.js`'i `v2.0.0 → v2.0.1` güncellersen kullanıcılar etkilenmez. Sadece sen `data-blakfy-version="1.0" → "2.0"` yaparsan re-consent tetiklenir.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## Branding (Anti-Tampering)
|
|
145
|
+
|
|
146
|
+
3 katmanlı koruma:
|
|
147
|
+
|
|
148
|
+
1. **CSS:** `.blakfy-badge { display: flex !important; opacity: 1 !important; pointer-events: auto !important; }`
|
|
149
|
+
2. **DOM:** `MutationObserver` widget kökünü izler. Badge silinirse 50ms sonra geri ekler. `data-*` attribute manipulation görmezden gelinir.
|
|
150
|
+
3. **Kod:** Badge HTML build sırasında sabitlenir, config'den okumaz.
|
|
151
|
+
|
|
152
|
+
Test: `tests/badge-anti-tamper.test.js` — silme, CSS injection, attribute tampering senaryoları.
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## Boyut Bütçesi
|
|
157
|
+
|
|
158
|
+
| Katman | Hedef (gzip) |
|
|
159
|
+
| ---------------------------------- | ------------ |
|
|
160
|
+
| Core (consent + UI + i18n + badge) | ≤ 14 KB |
|
|
161
|
+
| Compliance toplamı (lazy) | ≤ 6 KB |
|
|
162
|
+
| 18 Preset (lazy) | ≤ 4 KB |
|
|
163
|
+
| **TOPLAM (her şey aktif)** | **≤ 22 KB** |
|
|
164
|
+
|
|
165
|
+
`scripts/build.js` her release'de boyut kontrolü yapar; bütçeyi aşan PR'lar CI'da fail olur.
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Geliştirme Akışı
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
npm install # workspace + cookie-next deps
|
|
173
|
+
npm run dev # esbuild watch
|
|
174
|
+
npm test # Vitest jsdom
|
|
175
|
+
npm run build # dist/cookie.min.js + cookie-defaults.min.js
|
|
176
|
+
npm run build:next # tsup → packages/cookie-next/dist
|
|
177
|
+
npm run size # bundle size guard
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Release:
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
git tag v2.0.0
|
|
184
|
+
git push --tags
|
|
185
|
+
# GitHub Actions → tests + build + npm publish + GitHub Release
|
|
186
|
+
# jsDelivr @2 anında güncellenir
|
|
187
|
+
```
|