feralin 0.1.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.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: dee494448fa406a1ea3043f2a7cd3f41ce05a020587c5eae5aaa84c2a5e770e5
4
+ data.tar.gz: 42708fe238a135a87451671dd1c7b0d936c22b4da4d5fcbfe7bda63c56449e41
5
+ SHA512:
6
+ metadata.gz: 5a742f4009967b55e0a9e6a50f658fe9ebb95dfca408be8e0a4df9dc91b0e297200bcac44e90575c0a802f9cfdeb2a6e4176527c0b58f3b919d2bc09149ab6df
7
+ data.tar.gz: f0449aca1534c23d058d991a550980a67732bff6bb4f9a2ece0c9123361cba65f45e541f2c639a6a7f20263c4ad5708aeec832f47292066fd51145468ef93ddd
data/CHANGELOG.md ADDED
@@ -0,0 +1,9 @@
1
+ # Değişiklikler
2
+
3
+ ## Yayınlanmamış
4
+
5
+ - `track_revenue` → `feralin_purchase`, `group` → `fr_group`, `set_user_properties` → `fr_user_properties`, `capture_error` → `fr_error` (Android SDK ile aynı gövde, ham backtrace yok, 60 sn'de 20 olay, parmak izi başına 3); `app_version:` ve `error_sample_rate:` seçenekleri; Rack `Tracker` aynı yöntemleri isteğin kimliği ve izniyle sunar. Minitest ile sınandı (16 Kasım 2026).
6
+
7
+ ## 0.1.0
8
+
9
+ - İlk sürüm: `Feralin::Client`, Rack middleware, Rails Railtie. Henüz RubyGems'e yayınlanmadı.
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Feralin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,152 @@
1
+ # Feralin Ruby SDK (`feralin`)
2
+
3
+ Feralin toplayıcısına (`POST /v1/batch`) sunucu tarafından olay gönderen Ruby SDK'sı. Rack middleware ve Rails Railtie içerir. Yalnız standart kütüphane kullanır (`net/http`, `json`, `securerandom`); çalışma zamanı bağımlılığı yoktur. Rails ve rack gem'in bağımlılığı değildir.
4
+
5
+ ## Durum
6
+
7
+ Henüz RubyGems'e yayınlanmadı (`BLOCKED_EXTERNAL`: RubyGems hesabı, 2FA ve `feralin` adının doğrulanması gerekir). `gem install feralin` bugün bu paketi kurmaz.
8
+
9
+ Yalnız Ruby 3.3.12 (Windows, `x64-mingw-ucrt`), Rails 8.1.4.1 ve rack 3.2.8 ile koşuldu; `required_ruby_version` 3.0'a izin verse de daha eski Ruby, Rails ve rack sürümleri denenmedi. Puma ve Unicorn altında çalıştırılmadı. Gerçek `Process.fork` testi Windows'ta atlanır; çatallanma orada pid değişimi taklit edilerek sınanır, gerçek çatallanma Linux'ta henüz koşulmadı.
10
+
11
+ ## Kurulum
12
+
13
+ Yayın öncesi, depodan paketleyip kurun:
14
+
15
+ ```bash
16
+ cd sdks/ruby
17
+ gem build feralin.gemspec
18
+ gem install --local feralin-0.1.0.gem
19
+ ```
20
+
21
+ ## En kısa örnek
22
+
23
+ ```ruby
24
+ require "feralin"
25
+
26
+ client = Feralin::Client.new(
27
+ ENV.fetch("FERALIN_PROJECT_KEY"), # yalnız pk_ kabul edilir, sk_ reddedilir
28
+ "https://collect.example.com",
29
+ consent: Feralin::Consent.new(analytics: true)
30
+ )
31
+
32
+ event = client.track("order_completed", { order_id: "ord_1", amount: 249.9 }, user_id: "user_42")
33
+ result = client.flush # fırlatmaz; sonuç result.error içinde
34
+ client.close # kalanı en çok 5 sn içinde gönderir
35
+ ```
36
+
37
+ `flush` sonucu:
38
+
39
+ | Durum | `result` | Kuyruk |
40
+ |---|---|---|
41
+ | 202 | `ok?` doğru, `accepted`, `rejected`, `batch_id` | Boşalır |
42
+ | 4xx (429 hariç), 401 ve 403 dahil | `error` `Feralin::RejectedError` | Olaylar atılır, uygulama düşmez |
43
+ | 5xx, 429, ağ hatası | `error` `Feralin::TemporaryError` | Tutulur, aynı `Idempotency-Key` ile yeniden denenir |
44
+
45
+ Geri çekilme 1 sn ile 30 sn arasında üsteldir, yarım jitter eklenir ve `Retry-After` en az bekleme olarak uyulur. Açık `flush` çağrısı geri çekilmeyi beklemez.
46
+
47
+ `track` doğrulama hatasında `Feralin::InvalidEventError` fırlatır. Özellik değerleri JSON karşılığı olan türler olmalıdır; `Time`, `BigDecimal` ve benzeri nesneleri önce metne veya sayıya çevirin. `user_id` metin olmalıdır (`user.id.to_s`) ve e-posta gibi kişisel veri taşımamalıdır.
48
+
49
+ ## İzin
50
+
51
+ `analytics` doğru değilse olay üretilmez ve `track` `nil` döner; varsayılan `Consent.new` izin vermez. Yalnız gerçek `true` izin sayılır.
52
+
53
+ - `advertising` doğru değilse `fr_click` olaydan çıkarılır.
54
+ - `client.set_consent(Feralin::Consent.new)` bekleyen olayları siler ve olay başına verilen izni de geçersiz kılar.
55
+ - `client.track("olay", nil, consent: izin)` yalnız o olayın iznidir. Çok kullanıcılı sunucuda izin ve kimliği istek başına tutun; `client.identify` süreçteki bütün isteklere uygulanır.
56
+
57
+ ## Rack
58
+
59
+ ```ruby
60
+ # config.ru
61
+ require "feralin"
62
+
63
+ Feralin.client = Feralin::Client.new(ENV.fetch("FERALIN_PROJECT_KEY"), ENV.fetch("FERALIN_COLLECT_URL"))
64
+
65
+ use Feralin::Rack::Middleware,
66
+ consent: ->(env) { Feralin::Consent.new(analytics: env["HTTP_COOKIE"].to_s.include?("analitik=1")) }
67
+
68
+ run ->(env) {
69
+ tracker = env["feralin.tracker"]
70
+ tracker.identify("user_42") # yalnız bu istek için
71
+ tracker.track("order_completed", { order_id: "ord_1" })
72
+ [200, { "content-type" => "text/plain" }, ["ok"]]
73
+ }
74
+ ```
75
+
76
+ - Middleware kendiliğinden olay üretmez; istek yolu ve sorgusu kişisel veri taşıyabilir.
77
+ - İzin çözücüsü hata verir veya `Feralin::Consent` dönmezse izin yok sayılır.
78
+ - `flush_after_request: true`: arka plan göndericisi kapalıyken (`flush_interval: 0`) olayları `rack.response_finished` veya `rack.after_reply` ile yanıttan sonra gönderir. Sunucu bunları sunmuyorsa gönderim yanıttan önce yapılır ve isteği uzatır.
79
+
80
+ ## Rails
81
+
82
+ Gem `Gemfile` içinde olunca Railtie kendiliğinden yüklenir, middleware'i ekler ve kapanışta kuyruğu gönderir.
83
+
84
+ ```ruby
85
+ # config/initializers/feralin.rb
86
+ Rails.application.config.feralin.consent_resolver = lambda do |env|
87
+ Feralin::Consent.new(analytics: ActionDispatch::Request.new(env).cookies["analitik"] == "1")
88
+ end
89
+ ```
90
+
91
+ ```ruby
92
+ class OrdersController < ApplicationController
93
+ def create
94
+ feralin.identify(current_user.public_id)
95
+ feralin.track("order_completed", { order_id: order.public_id })
96
+ end
97
+ end
98
+ ```
99
+
100
+ Anahtar ve adres `FERALIN_PROJECT_KEY` ve `FERALIN_COLLECT_URL` ortam değişkenlerinden veya `config.feralin.project_key` ve `config.feralin.collect_url` ayarlarından okunur. İkisi yoksa uygulama açılır, olay üretilmez ve durum günlüğe yazılır. Diğer ayarlar: `consent` (istemcinin varsayılan izni), `consent_resolver`, `flush_after_request`, `flush_interval`, `batch_size`, `queue_limit`, `timeout`.
101
+
102
+ ## Çatallanma (Puma, Unicorn)
103
+
104
+ Kuyruk süreç başınadır. İstemci çatallanmadan önce oluşturulduysa yavru süreç ilk çağrıda boş kuyrukla ve kendi göndericisiyle başlar; üst süreçte bekleyen olaylar yavrudan gönderilmez.
105
+
106
+ ## Gelir, kimlik ve hata
107
+
108
+ ```ruby
109
+ client.track_revenue("ord_1", 4999, "TRY", product_id: "pro_monthly", user_id: "user_42")
110
+ client.group("acme-team", { plan: "team" }, user_id: "user_42")
111
+ client.set_user_properties({ plan: "pro" }, user_id: "user_42")
112
+ begin
113
+ odeme_al
114
+ rescue StandardError => e
115
+ client.capture_error(e, user_id: "user_42")
116
+ end
117
+ ```
118
+
119
+ - `track_revenue` → `feralin_purchase`: tutar küçük birimde `Integer`, ISO 4217; kurallar diğer SDK'larla aynıdır, sözleşme dışı girdide `InvalidEventError`. `verified` hiçbir zaman gönderilmez. SDK sözleşmesinde iade olayı yoktur.
120
+ - `group` → `fr_group`, `set_user_properties` → `fr_user_properties`: kişisel veriye benzeyen anahtar, doğrulama alanı ve sınır dışı değer istemcide düşer; geçersizse `nil`.
121
+ - `capture_error` → `fr_error` (Android SDK ile aynı gövde): hata sınıfı adı, temizlenmiş en çok 200 karakterlik mesaj, gem ve standart kütüphane dışı ilk beş çerçevenin parmak izi, üst çerçeve (`işlev@dosya.rb`) ve en çok 5 konum (dosya taban adı, satır, işlev). Ham backtrace gitmez; 60 saniyede en çok 20 olay, aynı parmak izi için en çok 3. Kurucu: `app_version:`, `error_sample_rate:`. Fırlatmaz.
122
+ - Rack'te `env["feralin.tracker"]` aynı dört yöntemi isteğin kimliği ve izniyle sunar.
123
+
124
+ ## Desteklenmeyenler
125
+
126
+ - Kalıcı kuyruk: olaylar bellektedir, süreç ölürse kaybolur. Sınır aşılırsa en eski olay atılır.
127
+ - `reset`, global özellikler, otomatik (Rack) hata yakalama, OTel izleme.
128
+ - Sidekiq veya ActiveJob bütünleşmesi. İş sürecinde `Feralin::Client` doğrudan kullanılabilir.
129
+ - Otomatik sayfa veya istek olayı, parmak izi, `fr_click` okuma. `verified`, `tenant_id` ve `project_id` istemciden gönderilmez.
130
+
131
+ ## Geliştirme
132
+
133
+ ```bash
134
+ cd sdks/ruby
135
+ ruby -S rake test
136
+ ```
137
+
138
+ Gerçek rack ve Rails ile tümleşik test (genel gem dizinine dokunmaz):
139
+
140
+ ```bash
141
+ cd sdks/ruby
142
+ GEM_HOME="$PWD/vendor/gems" GEM_PATH="$PWD/vendor/gems" ruby -S gem install railties rack tzinfo-data --no-document
143
+ GEM_HOME="$PWD/vendor/gems" GEM_PATH="$PWD/vendor/gems" ruby -S rake test:rails
144
+ ```
145
+
146
+ `tzinfo-data` yalnız Windows'ta gerekir; Rails orada sistem saat dilimi verisi bulamaz.
147
+
148
+ Gerçek toplayıcıyla uçtan uca test (yalnız test veritabanı verin):
149
+
150
+ ```bash
151
+ DATABASE_URL='postgres://...' COLLECT_ADDR=127.0.0.1:4712 node scripts/sdk-e2e/run.mjs ruby
152
+ ```