> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evox.wraithesports.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Event ve host-RPC referansı

> Plugin'in aldığı eventlerin ve hosta gönderebileceği RPC çağrılarının tam listesi.

Bu sayfa evoX plugin protokolünün tam yüzeyidir: hosttan plugin'e gelen **eventler** ve plugin'den hosta giden **host-RPC** çağrıları. Tüm isimler `@evox/plugin-protocol` içindeki gerçek sözleşmedir; renderer/plugin payload'ı authoritative değildir, kimlik ve context host tarafından türetilir.

## Sözleşme kuralları

* Her binding örneği yalnız kendi `bindingInstanceId` context'i için geçerlidir. `action.willDisappear` sonrası display çağrısı `CONTEXT_EXPIRED` ile reddedilir.
* Host-assigned `session.plugin.pluginId` tek authoritative kimliktir; event/RPC payload'ıyla başka kimlik seçilmez.
* RPC çağrıları capability gerektirir. Declared/granted olmayan çağrı `CAPABILITY_DENIED` döner (bkz. [Capability API'leri](/sdk/capabilities)).
* Hata davranışı fail-closed'dır; kodlar için [Hata kodları](/sdk/errors).

## Alınan eventler (host → plugin)

`client.on(<event>, handler)` ile kaydedilir. Handler'lar `client.start()` handshake'inden önce kaydedilmelidir.

### Plugin yaşam döngüsü

| Event            | Ne zaman                                                         |
| ---------------- | ---------------------------------------------------------------- |
| `plugin.start`   | Session kuruldu, `host.hello` alındı; plugin çalışmaya hazır     |
| `plugin.stop`    | Session kapatılıyor; handler cleanup ve `client.dispose()` çağır |
| `plugin.suspend` | Plugin geçici askıya alındı; yeni istek gönderme                 |
| `plugin.resume`  | Askıdan döndü; normal işleme devam                               |

### Cihaz

| Event                 | Ne zaman                                                           |
| --------------------- | ------------------------------------------------------------------ |
| `device.connected`    | Bir cihaz bağlandı; payload cihaz kimliği ve boyut bilgisini taşır |
| `device.disconnected` | Cihaz kaldırıldı                                                   |

### Action binding

| Event                    | Ne zaman                                                                                           |
| ------------------------ | -------------------------------------------------------------------------------------------------- |
| `action.willAppear`      | Action örneği bir tuş/dial'a görünür oldu (uygulama açılışı, profil/sayfa geçişi, kullanıcı atadı) |
| `action.willDisappear`   | Action örneği artık görünmüyor (profil/sayfa değişimi, atama silindi)                              |
| `action.keyDown`         | Kullanıcı tuşa bastı                                                                               |
| `action.keyUp`           | Kullanıcı tuşu bıraktı                                                                             |
| `action.dialDown`        | Kullanıcı dial'a bastı                                                                             |
| `action.dialUp`          | Kullanıcı basılı dial'ı bıraktı                                                                    |
| `action.dialRotate`      | Kullanıcı dial'ı çevirdi; payload yön/adım bilgisini taşır                                         |
| `action.settingsChanged` | Bu binding'in ayarları değişti; güncel `settings` payload'da                                       |

Her event `event.context` içinde `actionId` ve `bindingInstanceId` taşır. Plugin'in tanımadığı `actionId` ignore edilmelidir.

```js theme={null}
client.on('action.keyDown', async (event) => {
  if (event.context?.actionId !== 'counter') return;
  await client.setTitle(event.context.bindingInstanceId, '1');
});

client.on('action.willDisappear', (event) => {
  counters.delete(event.context?.bindingInstanceId);
});
```

## Host-RPC çağrıları (plugin → host)

SDK client üzerinden çağrılır; her biri `Promise` döner ve fail-closed hata verir.

### Tuş/ekran gösterimi — `key.display` capability

| SDK metodu                        | RPC               | Açıklama                                                                                     |
| --------------------------------- | ----------------- | -------------------------------------------------------------------------------------------- |
| `client.setTitle(context, title)` | `key.setTitle`    | Binding başlığını değiştirir                                                                 |
| `client.setImage(context, image)` | `key.setImage`    | Binding görselini değiştirir (manifest-hash `assetId` veya bounded PNG/JPEG/WebP descriptor) |
| `client.setState(context, state)` | `key.setState`    | Çok durumlu action için durumu değiştirir (0'dan başlar)                                     |
| `client.showSuccess(context)`     | `key.showSuccess` | Geçici başarı işareti gösterir                                                               |
| `client.showError(context)`       | `key.showError`   | Geçici hata işareti gösterir                                                                 |

```js theme={null}
await client.setTitle(context.bindingInstanceId, 'Hazır');
await client.showSuccess(context.bindingInstanceId);
```

Raw dosya yolu veya external URL kabul edilmez.

### Ayar kalıcılığı

| SDK metodu                                 | RPC              | Açıklama                                                                    |
| ------------------------------------------ | ---------------- | --------------------------------------------------------------------------- |
| `client.getSettings(context?)`             | `settings.get`   | Binding'e (veya context'siz plugin geneline) ait kalıcı ayarı okur          |
| `client.patchSettings(settings, context?)` | `settings.patch` | Ayarı kısmi günceller; değişiklik `action.settingsChanged` ile geri yayılır |

<Warning>Token/password/client secret'ı normal ayara yazmayın. Credential için secret/OAuth API'lerini kullanın.</Warning>

### Plugin-scoped depolama — `storage.private` capability

| SDK metodu                      | RPC              | Açıklama                                 |
| ------------------------------- | ---------------- | ---------------------------------------- |
| `client.storageGet(key)`        | `storage.get`    | Plugin'e özel bounded kotalı değeri okur |
| `client.storageSet(key, value)` | `storage.set`    | Değeri yazar                             |
| `client.storageDelete(key)`     | `storage.delete` | Değeri siler                             |

### Ağ ve credential — `network.fetch` / `secret.manage` / `oauth`

| SDK metodu                                 | RPC                           | Açıklama                                                                                                                                   |
| ------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `client.networkFetch(input)`               | `network.fetch`               | Declared HTTPS host/method/byte scope'unda istek                                                                                           |
| `client.networkFetchWithCredential(input)` | `network.fetchWithCredential` | Host, `{kind:'secret',name}` / `{kind:'oauth',provider}` referansını vault'tan çözüp izinli isteğe enjekte eder; raw token plugin'e dönmez |
| `client.hasSecret(name)`                   | `secret.has`                  | Secret var mı (byte döndürmez)                                                                                                             |
| `client.deleteSecret(name)`                | `secret.delete`               | Secret'ı siler                                                                                                                             |
| `client.beginOAuth(provider)`              | `oauth.begin`                 | OAuth akışını başlatır                                                                                                                     |
| `client.getOAuthStatus(provider)`          | `oauth.status`                | OAuth durumunu okur (token byte'ı dönmez)                                                                                                  |

### Sistem — `system.openExternal` / `system.openPath`

| RPC                   | Capability            | Açıklama                                |
| --------------------- | --------------------- | --------------------------------------- |
| `system.openExternal` | `system.openExternal` | HTTPS URL'yi varsayılan tarayıcıda açar |
| `system.openPath`     | `system.openPath`     | İzinli bir yolu sistemde açar           |

Bu iki çağrı protokolde tanımlı ve capability korumalıdır; ayrı bir SDK kısayol metodu olmadan generic istek yolundan kullanılır.

## Notlar

* Bu referans mevcut protokol sürümünü yansıtır; capability adları ve limitler [Capability API'leri](/sdk/capabilities) sayfasında normatiftir.
* Public dağıtım sınırı ve T1/T2/T3 farkları için [Güven katmanları](/sdk/trust-tiers) ve [Dağıtım durumu](/sdk/distribution-status).