Nuvaka › Geliştirici belgeleri › Bağımlılıklar

Bağımlılıklar

Bir uzantı başka uzantılara ihtiyaç duyabilir: ortak bir yardımcı, bir veri servisi, bir tema ya da çeviri paketi. Manifestteki dependencies alanıyla bunu bildirirsin. İki tür bağımlılık var: uses uzantının içine gizli bir kopya olarak kurulur, extends kullanıcının kendi kurduğu bir uzantıya takılır.

Tanım#

"dependencies": [
  { "id": "ali.tepsi", "version": "^1.5.0" },
  { "id": "ali.grafik", "version": "~2.1", "optional": true },
  { "id": "ali.not-defteri", "version": "^3.0.0", "kind": "extends" }
]

kind yazılmazsa uses sayılır. En çok 10 giriş. Sürüm aralığı yazımının tamamı Manifest › dependencies sayfasında. Kısaca: 1.2.3, ^1.2.3, ^1.2, ~1.2.3, ~1.2, 1.x, 1.2.x, * ve >=1.0.0 <2.0.0 gibi karşılaştırıcılar kullanılabilir. Ön sürüm ve || yok.

İki tür: uses ve extends#

Aynı paket bir ağaçta hem uses hem extends olamaz. extends hedefinin içine inilmez: onun kendi bağımlılıkları kendi kurulumuna aittir.

Gizli kopyayı çağırmak (uses)#

Kopya işlevlerini arka plan kodunda nuvaka.expose ile açar. Sahibi bunları nuvaka.deps.call ile çağırır. Kopya çalışmıyorsa ilk çağrıda arka planı başlar. Sonuç JSON olarak döner ve en çok 60 saniye beklenir.

// ali.tepsi — background.js (kopya tarafı)
nuvaka.expose('ozet', async ({ metin }) => {
  const kayit = await nuvaka.storage.get('sayac')   // kopyanın kendi verisi
  return { uzunluk: metin.length, onceki: kayit?.value ?? 0 }
})

// Sahip — arayüz ya da arka plan
const r = await nuvaka.deps.call('ali.tepsi', 'ozet', { metin: 'merhaba' })

• Kopya kendi izinleriyle çalışır. Kullanıcı bu izinleri kurulumda senin uzantının izinleriyle aynı ekranda onaylar.
• Kopya bildirim gönderemez (nuvaka.ui.notify ve nuvaka.push → dependency_no_notify) ve Dosyalarım'dan açılan tek dosya tanıtıcısını kullanamaz.
• Kritik izin sorularında kullanıcı "Tepsi (Not Defteri için) maillerini okumak istiyor" biçiminde sahibi de görür.
• deps.call hataları: not_a_dependency (manifestte uses değil), dependency_missing, dependency_blocked, dependency_unavailable, not_exposed, timeout. nuvaka.info() kopyada owner alanıyla sahibi verir.

Kurallar#

Yükleme reddedilirse hatalar scan.errors içinde "Bağımlılık: …" önekiyle gelir. Yayınlamadan önce ağacı nuvaka-ext deps ile görebilirsin (CLI).

Çözüm#

• Her bağımlılık için aralığı karşılayan en yüksek yayındaki sürüm seçilir. Geri çekilmiş ya da incelemedeki sürümler seçilmez.
• İsteğe bağlı (optional: true) bağımlılık da ağaçta ve 10 paket sayımında yer alır, ama kurulumu zorunlu değildir.
• Ağaç sunucuda çözülür: GET /api/ext/v1/store/{id}/dependencies?version= (anonim). Her paket için kind ve privateCopy gelir.
  • uses paketinde installed* alanları sahibin içindeki kopyaya bakar. ownInstallVersion kullanıcının kendi kurulumudur ve yalnız bilgi amaçlıdır.
  • extends paketinde bu alanlar kullanıcının kendi kurulumuna bakar.

$ nuvaka-ext deps [email protected]
tarikgkhsn.fatura 1.3.0
  ✓ ali.tepsi 1.5.6  (^1.5.0)
    ✓ ali.http-yardimci 2.0.1  (2.x) ← ali.tepsi
  ✓ ali.grafik 2.1.5  (~2.1) [isteğe bağlı]
Toplam paket (kök dahil): 4 / 10
Kurulabilir

Kurulum#

Kurulum ekranı ağacı gösterir: her paketin türü, sürümü, istediği izinler ve geliştiricisinin bırakıp bırakmadığı.

• extends hedefleri önce: hedef kullanıcının araç kutusunda yoksa ya da sürümü aralığı tutmuyorsa önce o kurulur ya da güncellenir.
• Sonra uzantının kendisi. Gizli kopyaları sunucu kendisi kurar (PUT installs/{id}, withDependencies: true). Kopyaların izinleri aynı ekranda, sahip → kopya diye gruplu sorulur ve dependencyGrants ile gider.
• Yalnız bunu kur seçeneği, yalnız isteğe bağlı bağımlılıklar eksikse sunulur.
• Zorunlu bir bağımlılık şu an kurulamıyorsa (engelli ya da aralığı karşılayan sürüm yok) kurulum başlamaz ve nedeni gösterilir. 409 dependencies_unavailable döner.
• Sunucu yanıtları: 409 dependencies_required (eksik; kind: "extends" ise hedefi önce kur), 409 extends_version_mismatch (hedefin kurulu sürümü uymuyor; latestSatisfying ile güncellenebilir).

Kodunda isteğe bağlı bağımlılığın kurulu olmayabileceğini hesaba kat: nuvaka.deps.call dependency_missing verebilir.

Ayarlar#

Kullanıcı Uygulamalar ekranında senin uzantının ayarlarında aşağı açılan bir Bağımlılıklar bölümü görür.

• Gizli kopyaların izinlerini ve ayarlarını buradan değiştirir: PATCH /api/ext/v1/installs/{bağımlılık}?owner={sahip} { settings?, grants? }.
• Kopyanın durdurulması ve güncellenmesi sahibine bağlıdır.
• extends hedeflerinin yalnız durumu gösterilir. Kendi ayarları kendi sayfasındadır.

Kaldırma#

• Uzantı kaldırılınca içindeki gizli kopyalar da gider. Verileri sahibinin verisiyle aynı kurala tabidir (keepData).
• uses kopyaları bağımsız olduğu için hiçbir kaldırmayı engellemez.
• Kullanıcının kendi kurulumlarından biri bir uzantıyı zorunlu olarak extends ediyorsa kaldırırken uyarılır: "X başka uygulamalarca kullanılıyor". Kullanıcı yine de kaldırabilir. Bağlı uzantılar "bağımlılığı eksik" olarak işaretlenir.

Güncelleme#

• Yeni sürüm yeni bir zorunlu kopya ya da kurulu olmayan bir extends hedefi istiyorsa otomatik güncelleme durur ve kullanıcıya sorulur (newDependencies). Onaylanana kadar eski sürüm çalışır.
• Kopyaların sürümü değişecekse güncelleme kartında gösterilir (copyVersionChanges). Onayda withDependencies: true kopyaları da yeni sürümlerine getirir.
• Aynısı contributes değiştiğinde de geçerlidir (Çekirdek eklentileri).
• Kırıcı değişiklikleri ana sürümle (2.0.0) çıkar. ^1.x isteyen uzantıların kopyaları 1.x'te kalır. Başka bir uzantının içindeki 2.x kopyası onları etkilemez.

Kurulu uzantının bağımlılık durumu#

Bırakılan bağımlılıklar#

Başka uzantıların bağlı olduğu bir paket silinemez, ama geliştiricisi onu bırakabilir. Paket son sürümüyle mağazada kalır, bağlı uzantılar çalışmaya devam eder ve geliştiricilerine bildirim gider. Başka bir geliştirici paketi sahiplenmek isteyebilir; ayrıntı: Bırakılan paketler ve sahiplik.

Nuvaka Apps API v1 · son güncelleme 2026-09-27