# @gametegra/sdk

SuperApp JS SDK üzerine inşa edilen bu yardımcı paket, oyun geliştiricileri için özel olarak tasarlanmıştır. Oyun odaklı işlevleri (oda yönetimi, skor, veri akışı) ve SuperApp özelliklerini (kullanıcı bilgisi, ödeme vb.) tek bir çatı altında toplar.

## Özellikler

- **Tek Noktadan Erişim**: Hem oyun metodlarına (`createRoom`) hem de SuperApp metodlarına (`getUserInfo`) doğrudan `gameTegra` objesi üzerinden erişebilirsiniz.
- **Otomatik Hazır Olma**: `superappReady` olayını otomatik dinler. Metodları `superapp` hazır olmadan çağırsanız bile kuyruğa alır ve hazır olduğunda çalıştırır.
- **Modüler Yapı**: Oyun mantığı, veri akışı ve SuperApp proxy'leri modüler olarak ayrılmıştır.
- **Kolay Veri Akışı**: `sendData` ve `listenData` ile oyun içi gerçek zamanlı veri iletişimini kolaylaştırır.

## Kurulum

GitHub Packages üzerinden paket yüklemek için **npm kimlik doğrulaması** yapmanız gerekir. Git kimlik bilgileriniz (SSH/HTTPS) npm için geçerli değildir.

### 1. Token Oluşturma

1. GitHub'da **Settings > Developer settings > Personal access tokens > Tokens (classic)** yolunu izleyin.
2. **Generate new token (classic)** deyin.
3. **read:packages** yetkisini seçin ve token'ı oluşturup kopyalayın.

### 2. Proje Ayarı (.npmrc)

Projenizin kök dizininde `.npmrc` dosyası oluşturun (veya varsa düzenleyin) ve şu satırları ekleyin. `TOKEN_BURAYA` kısmına oluşturduğunuz token'ı yapıştırın:

```ini
@gametegra:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=TOKEN_BURAYA
```

> **Güvenlik Notu:** Token'ı doğrudan dosyaya yazmak yerine ortam değişkeni kullanmanız önerilir: `//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}`

### 3. Yükleme

Artık paketi yükleyebilirsiniz:

```bash
npm install @gametegra/sdk
```

## Kullanım

### Başlangıç

```js
import { GameTegraSDK, DEFAULT_METHOD_MAP } from "@gametegra/sdk";
import { gameTegra } from "@gametegra/sdk";
// SDK'nın hazır olmasını bekleyin (Opsiyonel ama önerilir)
gameTegra.onReady(async () => {
  console.log("GameTegra ve SuperApp hazır!");

  // Oyun Metodu Çağırma
  await gameTegra.createRoom({ roomId: "lobby-1" });

  // SuperApp Metodu Çağırma (Doğrudan erişim!)
  const userInfo = await gameTegra.getUserInfo();
  console.log("Kullanıcı:", userInfo);
});
```

### Oyun Metodları

Oyun sunucusu (CustomModule) üzerindeki fonksiyonları tetikler.

| Metod                       | Açıklama                                  |
| --------------------------- | ----------------------------------------- |
| `createRoom(params)`        | Yeni bir oyun odası oluşturur.            |
| `joinRoom(params)`          | Mevcut bir odaya katılır.                 |
| `leaveRoom(params)`         | Odadan ayrılır.                           |
| `getScore(params)`          | Skor bilgisini çeker.                     |
| `loadData(params)`          | Nakama'dan veri okur.                     |
| `saveData(params)`          | Nakama'ya veri yazar.                     |
| `showAd(params)`            | Uygulamada reklam gösterir.               |
| `createLeaderboard(params)` | Yeni bir leaderboard oluşturur.           |
| `getLeaderboard(params)`    | Leaderboard sıralamasını getirir.         |
| `updateLeaderboard(params)` | Leaderboard'a skor kaydeder.              |
| `custom(name, params)`      | Özel bir oyun fonksiyonunu ismen çağırır. |

```js
// Örnek: Odaya katılma
await gameTegra.joinRoom({ roomId: "12345" });
```

```js
// Örnek: Leaderboard oluşturma
await gameTegra.createLeaderboard({
  id: "global_wins",
  authoritative: false,
  sortOrder: "desc",
  operator: "best",
  resetSchedule: "0 0 * * 1",
  metadata: { title: "Haftalık Skorlar" },
});
```

```js
// Örnek: Skor güncelleme
await gameTegra.updateLeaderboard({
  id: "global_wins",
  score: 100,
  subscore: 5,
  metadata: { map: "desert" },
});
```

```js
// Örnek: Sıralama listesini çekme
const leaderboard = await gameTegra.getLeaderboard({
  id: "global_wins",
  limit: 20,
});
```

```js
// Ornek: Veri kaydetme
await gameTegra.saveData({
  key: "login",
  value: { id: 1, credential: "test" },
});
```

```js
// Ornek: Veri okuma (key bos kalirsa koleksiyondaki tum objeleri dondurur)
const data = await gameTegra.loadData({
  collection: "test_data",
  key: "login",
});
```

```js
// Ornek: Reklam gosterme
const data = await gameTegra.showAd({
  placement: "miniapp_open",
  adType: "rewarded", // or "interstitial"
  miniGameId: miniGameId,
  showLoading: true, // optional, defaults to false
});
```

### SuperApp Metodları

SuperApp özelliklerine `window.superapp` demeden doğrudan erişebilirsiniz.

| Metod                           | Açıklama                        |
| ------------------------------- | ------------------------------- |
| `getUserInfo()` | Kullanıcı bilgilerini döner. |
| `requestLocation()` | Konum bilgisini döner. |
| `capturePhoto()` | Kameradan fotoğraf çeker. |
| `pickImage()` | Galeriden görsel seçer. |
| `captureScreenshot(options?)` | MiniApp/MiniGame WebView'inin o anda görünen ekranını yakalar. |
| `startPurchase(params)` | Payment package `code` ile ödeme işlemini başlatır. |
| `pay(params)` | `startPurchase` için geriye uyumlu alias. |
| `requestOrientation(params)` | Ekran yönü isteği gönderir. |
| `searchMiniapps(query)` | Mini uygulama arar. |
| `openMiniApp(params)` | Başka bir mini uygulamayı açar. |
| `showLoading() / hideLoading()` | Yükleniyor ekranını yönetir. |

Ekran görüntüsü native host tarafından alınır; bu nedenle DOM, Canvas ve WebGL
içeriğini kapsar. Bu özellik `capturePhoto()` metodundan farklı olarak kamerayı
açmaz. Çağrı mevcut CustomMethod hattı üzerinden iletilir; SuperApp JS SDK'ye
ayrı bir metot eklenmesi gerekmez. Uyumlu host uygulamasında kullanım:

```js
await gameTegra.waitUntilReady();

const screenshot = await gameTegra.captureScreenshot({
  format: "png",
});

console.log(screenshot.dataUrl, screenshot.width, screenshot.height);
```

`getUserInfo()` response `data` alanı `name`, `email` ve `age` döner. `surname`
alanı yoktur; `age` seçilmediyse `null`, child menüsünden seçildiyse o sayısal
değer olur.

```js
// Ornek: Odeme
await gameTegra.startPurchase({
  code: "com.gametegra.diamond.100",
  amount: 100,
  currency: "DIAMOND",
});
```

### Veri Akışı (Streaming)

Gerçek zamanlı veri gönderip almak için kullanılır.

```js
// Veri Dinleme
const stream = await gameTegra.listenData({ channel: "game-events" });
stream.on("data", (data) => {
  console.log("Gelen veri:", data);
});

// Veri Gönderme
await gameTegra.sendData({
  channel: "game-events",
  payload: { action: "move", x: 10, y: 20 },
});
```

## Yaşam Döngüsü Olayları

`gameTegraReady` olayı hem `window` hem de `document` üzerinde yayımlanır. Bu sayede SDK'nın tamamen yüklendiğinden ve SuperApp ile bağlantı kurduğundan emin olabilirsiniz.

```js
document.addEventListener("gameTegraReady", (event) => {
  const { gameTegra, superapp } = event.detail;
  console.log("GameTegra hazır", gameTegra);

  // Artık güvenle işlem yapabilirsiniz
  gameTegra.joinRoom({ roomId: "public" });
  superapp.getUserInfo().then(console.log);
});
```

Event Detay İçeriği:

```ts
type ReadyDetail = {
  ready: true;
  superapp: SuperAppInstance;
  gameTegra: GameTegraSDK;
  /** @deprecated Use gameTegra instead */
  supergame: GameTegraSDK;
};
```

## İleri Seviye: Metod Haritalama (setMethodMap)

Eğer SuperApp tarafındaki fonksiyon isimleri ile sizin kodunuzdaki isimler farklıysa veya yeni eklenen bir fonksiyonu SDK güncellemeden kullanmak isterseniz `setMethodMap` kullanabilirsiniz.

> **Not:** `setMethodMap` mevcut harita ile yeni gönderdiğinizi **birleştirir (merge)**. Yani varsayılan metodları (`createRoom` vb.) kaybetmezsiniz, tekrar tanımlamanıza gerek yoktur.

**Senaryo:** SuperApp tarafında fonksiyonun adı `v2_start_tournament_beta` ama siz kodunuzda `startTournament` olarak kullanmak istiyorsunuz.

```js
// Haritalamayı yap (Mevcutlar korunur, bu yenisi eklenir)
gameTegra.setMethodMap({
  startTournament: "v2_start_tournament_beta",
});

// Artık kısa ismiyle çağırabilirsiniz
await gameTegra.custom("startTournament", { id: 1 });
```

## Hazır Olma Garantisi

Tüm metodlar `superapp` hazır olana kadar bekler. Ancak uygulamanızın başlangıcında her şeyin yüklendiğinden emin olmak isterseniz:

```js
await gameTegra.waitUntilReady();
// Buradan sonra her şey güvenli
```

## Test Oyunları

SDK ile birlikte gelen örnek oyunlar:

- `testgame` ve `testgame/game2`: Oda/maç akışını ve veri gönderimini test eden örnekler.
- `testgame/gyro`: `gameTegra.readGyroscope()` metodunu dinleyen yeni gyro demo. Çalıştırmak için:
  1. `cd testgame/gyro`
  2. `npm install`
  3. Mobilde test edecekseniz `npm run dev -- --host`

## Geriye Uyumluluk

v0.3.0 ile birlikte `supergame` ismi `gameTegra` olarak değiştirilmiştir. Eski `supergame` ismi hala kullanılabilir ancak **deprecated** olarak işaretlenmiştir:

```js
// Yeni (Önerilen)
import { gameTegra } from "@gametegra/sdk";

// Eski (Deprecated, hala çalışır)
import { supergame } from "@gametegra/sdk";
```