biapp-mcp 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Değişiklik günlüğü
+
+## 0.3.0
+
+- E-posta pazarlama: 11 yeni araç (`eposta_kisiler`, `eposta_gruplari`, `eposta_kampanyalari`, `eposta_kisi_ekle`, `eposta_grup_ac`, `eposta_gruba_ekle`, `eposta_kampanya_hazirla`, `eposta_kampanya_guncelle`, `eposta_deneme_gonder`, `eposta_kampanya_gonder`, `eposta_kampanya_durdur`). 38 araç.
+- Yeni API anahtarı kapsamları: `email:read`, `email:write`, `email:send` (gönderim ayrı kapsam).
+- Menü şablonları: `haftalikMenu` (yapıştırılan gün/yemek metninden) ve `gunlukMenu` (yemek listesi otomatik kategorilenir, firma iletişim düğmeleri). Backend `POST /v1/email/campaigns` artık `templateType` + `content` kabul eder (WeeklyMenu, DailyMenu, Newsletter, Promotion); renk, https adresi, WhatsApp/Instagram/telefon alanları doğrulanır.
+- `eposta_kampanya_gonder` her zaman önizleme + onay ister (`BIAPP_ONAY=dogrudan` dahil); alıcı sayısı değişirse gönderilmez.
+
+## 0.2.0
+
+- Yeni: `teklif_pdf` (yerel dosyaya PDF yazar; `GET /v1/quotes/{id}/pdf`, `quotes:read`) ve `teklif_guncelle` (taslak teklif; `PUT /v1/quotes/{id}`). 27 araç.
+- `teklif_hazirla`: `odemeKosullari`, `opsiyonGun`, `teslimGun` alanları; `gecerlilikGun` (son geçerlilik) ile `opsiyonGun` (belge yazısı) ayrımı açıklandı.
+- `cari_ac`: `vergiDairesi`; aynı ad/telefon/VKN'li kayıt için önizleme uyarısı. `cari_ara` / `urun_ara` Türkçe harf (i/İ/ı/I) duyarsız (backend).
+- Önizleme artık girdinin tüm dolu alanlarını gösterir (`fis_elle`, `z_raporu_elle`, `teklif_hazirla`, `cari_ac`); `gecerliSaat`; süre dolunca hata araç ve girdiyi söyler.
+- `z_raporu_elle`: aynı gün Z varsa uyarı, ikinci kayıt için `ikinciKayitOnayi: true`.
+- `teklif_paylas`: localhost adresinde uyarı. `kasa_hareketi_ekle`: cariye bağlı genel tahsilatın faturayı kapatmadığı uyarısı.
+- Fatura PDF'i kapsam dışı (backend'de fatura PDF ucu yok).
+
+## 0.1.0
+
+İlk sürüm.
+
+- 25 Türkçe araç: 10 okuma, 15 yazma (kasa hareketi, cari, ürün/stok, teklif, fatura/tahsilat, ödeme linki, fiş, Z raporu).
+- Yazma araçları önce önizleme döner; kayıt yalnız aynı girdi ve önizleme kodu (`islemKodu`) ile onaylanınca yapılır (`BIAPP_ONAY=sor`, varsayılan).
+- Açılışta `GET /v1/me` ile anahtarın yetkisine ve kurulu uygulamalara göre araç süzme.
+- Fiş ve Z raporu görseli yükleme: dosya baytlarından JPEG/PNG/WebP/PDF doğrulaması, 15 MB sınırı, özel IP reddi.
+- Silme aracı yok.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BiApp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# biapp-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[BiApp](https://biapp.com.tr)'i bir yapay zekâ asistanıyla sohbet ederek yönetin: "500 TL geldi Ahmet beyden", fiş fotoğrafı yükleme,
+Z raporu girme, cari ve ürün açma, teklif hazırlama, fatura ve tahsilat.
+
+Bu paket bir [MCP](https://modelcontextprotocol.io) sunucusudur (stdio). BiApp'e yalnızca `https://api.biapp.com.tr/api/v1` üzerinden,
+sizin oluşturduğunuz **firma API anahtarıyla** konuşur. Hesap, KDV, bakiye, kredi ve mükerrer kontrolü BiApp'tedir; paket bunları yeniden
+hesaplamaz.
+
+*English summary: an MCP server (stdio) that lets an AI assistant manage a BiApp business account through the company API key: ledger
+entries, receipts, Z reports, contacts, products, quotes, invoices. Turkish only. Writes require a preview-then-confirm step by default.*
+
+## Kurulum
+
+1. BiApp'te **Ayarlar › Entegrasyonlar › API Anahtarları**'ndan bir anahtar oluşturun (`bik_…`). Kapsamları aşağıdaki tablodan seçin;
+   anahtarı yalnızca işletme yöneticisi açabilir ve bir kez gösterilir.
+2. Asistanınıza ekleyin:
+
+**Claude Code**
+
+```bash
+claude mcp add biapp -e BIAPP_API_KEY=bik_... -- npx -y biapp-mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "biapp": {
+      "command": "npx",
+      "args": ["-y", "biapp-mcp"],
+      "env": { "BIAPP_API_KEY": "bik_..." }
+    }
+  }
+}
+```
+
+**Paperclip / diğer MCP istemcileri** (`mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "biapp": {
+      "command": "npx",
+      "args": ["-y", "biapp-mcp"],
+      "env": { "BIAPP_API_KEY": "bik_...", "BIAPP_ONAY": "dogrudan" }
+    }
+  }
+}
+```
+
+Otomasyonda (insan onayı olmayan ajan) `BIAPP_ONAY=dogrudan` açıkça seçilir; aşağıya bakın. Node 20 veya üstü gerekir.
+
+## Ortam değişkenleri
+
+| Değişken | Varsayılan | Anlamı |
+|---|---|---|
+| `BIAPP_API_KEY` | — (zorunlu) | `bik_…` anahtarı. Günlüğe, hataya ya da araç çıktısına yazılmaz. |
+| `BIAPP_API_URL` | `https://api.biapp.com.tr/api` | API adresi. `http://` yalnızca `localhost` için kabul edilir. |
+| `BIAPP_ONAY` | `sor` | `sor`: yazma araçları önce önizleme döner. `dogrudan`: onay adımı yok. |
+| `BIAPP_DOSYA_KOKU` | — | Doluysa fiş/Z yükleme yalnız bu klasörün altındaki dosyaları okur. |
+| `BIAPP_PDF_KLASORU` | `~/Downloads` | `teklif_pdf` dosyayı buraya yazar. |
+| `BIAPP_ZAMAN_ASIMI_SN` | `30` | İstek zaman aşımı (yüklemede en az 90). |
+
+## Araçlar ve gereken kapsam
+
+Araçlar açılışta anahtarınızın kapsamına ve işletmenizde kurulu uygulamalara göre süzülür; yetkisi olmayan araç asistana hiç görünmez.
+
+| Araç | Ne yapar | Kapsam |
+|---|---|---|
+| `isletme_bilgisi` | Firma, para birimi, kurulu uygulamalar, anahtar yetkileri | — |
+| `ozet` | Bugün/hafta/ay patron özeti | `reports:read` |
+| `hesaplar` | Kasa ve banka hesapları | `ledger:read` |
+| `kasa_hareketleri` | Gelir/gider listesi ve toplamı | `ledger:read` |
+| `kasa_hareketi_ekle` | Gelir ya da gider yazar (cariye bağlanabilir) | `ledger:write` |
+| `kasa_hareketi_duzelt` | Elle açılmış hareketi düzeltir | `ledger:write` |
+| `cari_ara` / `cari_ac` | Cari arar (alacaklar dahil) / yeni cari açar | `contacts:read` / `contacts:write` |
+| `urun_ara` / `urun_ac` | Ürün ve stok arar / yeni ürün açar | `products:read` / `products:write` |
+| `stok_hareketi` | Stok girişi, çıkışı, sayımı | `products:write` |
+| `teklifler` | Teklifleri listeler | `quotes:read` |
+| `teklif_pdf` | Teklifin PDF'ini yerel dosyaya yazar, yolunu döner (onay istemez, kayıt değiştirmez) | `quotes:read` |
+| `teklif_hazirla` / `teklif_guncelle` / `teklif_durumu` / `teklif_paylas` | Teklif açar / taslağı günceller / durumunu değiştirir (taslağı iptal: `Rejected`) / paylaşım bağlantısı üretir | `quotes:write` |
+| `faturalar` | Faturalar ve kalan tutar | `invoices:read` |
+| `fatura_kes` | Taslak satış faturası açar | `invoices:write` |
+| `tahsilat_isle` | Faturaya tahsilat yazar | `invoices:write` |
+| `odeme_linki` | Kartla ödeme bağlantısı üretir | `payment-links:write` |
+| `eposta_kisiler` / `eposta_gruplari` / `eposta_kampanyalari` | E-posta kişileri, grupları ve kampanyaları (istatistikli) okur | `email:read` |
+| `eposta_kisi_ekle` / `eposta_grup_ac` / `eposta_gruba_ekle` | Kişi (izin beyanıyla) / grup ekler, kişileri gruba koyar | `email:write` |
+| `eposta_kampanya_hazirla` / `eposta_kampanya_guncelle` | Taslak kampanya açar / günceller (göndermez) | `email:write` |
+| `eposta_deneme_gonder` | Kampanyanın `[TEST]` kopyasını tek adrese yollar (kredi düşmez) | `email:send` |
+| `eposta_kampanya_gonder` | Taslağı hedef kitleye **gönderir** ya da zamanlar (geri alınamaz, kredi düşer) | `email:send` |
+| `eposta_kampanya_durdur` | Giden kampanyayı durdurur / zamanlamayı iptal eder | `email:send` |
+| `fis_yukle` / `fis_elle` / `fisler` | Fiş görseli yükler / elle gider fişi girer / fişleri okur | `receipts:write` / `receipts:write` / `receipts:read` |
+| `z_raporu_yukle` / `z_raporu_elle` / `z_raporlari` | Z görseli yükler / elle Z girer / Z raporlarını okur | `pos-reports:write` / `pos-reports:write` / `pos-reports:read` |
+
+Bilerek **yoktur**: silme, iade, e-Fatura gönderimi, fatura PDF'i (BiApp'te fatura PDF ucu yok; yalnız e-Fatura akışı var), teklifin e-postayla gönderimi, sipariş ve Hızlı Satış, çek/senet. Paylaşım
+bağlantılarını ve ödeme linklerini paket göndermez; bağlantıyı siz iletirsiniz.
+
+## Yazmadan önce onay
+
+`BIAPP_ONAY=sor` (varsayılan) iken her yazma aracı ilk çağrıda **BiApp'e hiçbir şey yazmaz**; bir önizleme ve imzalı bir `islemKodu` döner.
+Asistan önizlemeyi size gösterir, "evet" derseniz aynı girdi ve kodla yeniden çağırır. Girdi değişirse (örneğin tutar) kod geçersiz olur ve
+yeni önizleme gerekir. Kod 30 dakika geçerlidir ve BiApp'e `Idempotency-Key` olarak gider: ağ hatasından sonra yeniden deneme çift kayıt açmaz.
+
+Bu bir güvenlik sınırı değil, bir emniyet kemeridir: onayı asistanın kendisi verebilir. Asıl güvence anahtarın kapsamı ve silme aracının
+olmamasıdır. Yalnız okumasını istiyorsanız anahtara yazma kapsamlarını vermeyin.
+
+## Fiş ve Z raporu
+
+- Sohbete eklediğiniz fotoğraf araca dosya olarak **geçmez**. Asistan fotoğrafı kendisi okuyup `fis_elle` / `z_raporu_elle` ile değerleri
+  yazarsa fotoğraf BiApp'e kaydedilmez (arşivde ve muhasebeci paylaşımında görünmez). Fotoğrafın kendisi için dosya yolu ya da `https`
+  adresi verin (`fis_yukle` / `z_raporu_yukle`) ya da BiApp mobil/Telegram yüklemesini kullanın.
+- Yüklenen görsel Z raporuysa BiApp bunu kendisi ayırır: fiş `Failed` + `Z_REPORT` olur ve Z raporu kaydı açılır (`fisler` aracı `posReportId` gösterir).
+- Yükleme araçları dosyayı baytlarından doğrular (yalnız JPEG, PNG, WebP, PDF; Z raporunda PDF yok), 15 MB'ı geçeni, metin/kod dosyasını ve
+  iç ağ adreslerini reddeder. `BIAPP_DOSYA_KOKU` ile okunabilecek klasörü daraltabilirsiniz.
+- Z raporu yükleme 1 kredi düşer; fiş için önce ücretsiz hak, sonra kredi. Krediniz yoksa kayıt bekler.
+
+## Güvenlik
+
+- Anahtar yalnızca ortam değişkenindendir; hiçbir çıktıya yazılmaz. Telemetri, kullanım toplama ve kendini güncelleme yoktur.
+- Anahtar işletmenizin tüm verisini görür (alt kullanıcı kapsamı anahtarla işlemez). Yalnızca güvendiğiniz bilgisayara ve uygulamaya koyun,
+  gerekirse BiApp'te iptal edin.
+- Araç çıktısındaki metinler (cari notu, ürün açıklaması) veridir; asistan talimatları buna göre verilmiştir, ama bir model yine de
+  yanılabilir. Önemli kayıtları onay adımında kontrol edin.
+
+## Sorun giderme
+
+| Belirti | Neden |
+|---|---|
+| Yalnızca `isletme_bilgisi` var | Anahtar geçersiz/iptal ya da BiApp'e ulaşılamadı; aracı çağırın, nedenini söyler. Düzelttikten sonra bağlantıyı yeniden başlatın. |
+| Kasa araçları görünmüyor | İşletmede Kasa uygulaması kurulu değil ya da anahtarda `ledger:*` kapsamı yok. |
+| "Bu hareket … kaydından geliyor" | Fiş/fatura/Z'den gelen hareketin tutarı kaynak kaydında düzeltilir. |
+| "Bu dosya zaten yüklenmiş" | Aynı görsel daha önce yüklenmiş (mükerrer koruması). |
+
+## Geliştirme
+
+```bash
+npm install
+npm run typecheck && npm test
+BIAPP_E2E=1 BIAPP_API_KEY=bik_... BIAPP_API_URL=http://localhost:5173/api npm test   # yerel BiApp stack'i + test firması gerekir
+```
+
+Uçtan uca senaryolar `[MCP TEST]` önekli veri yazar; yalnızca test firmasında çalıştırın. Görselli senaryo için `BIAPP_E2E_IMAGES=<jpeg yolu>`
+verilir ve yerel backend'in geçici olarak yerel MinIO'ya bağlanması gerekir (canlı depoya yazmasın diye).
+
+## Lisans
+
+MIT
+
+## Teklif alanları
+
+- `gecerlilikGun`: teklifin **son geçerlilik tarihi** (bugün + N gün). Dolunca BiApp teklifi `Expired` yapar.
+- `opsiyonGun`: belgede **"Opsiyon"** olarak yazan metin ("7 gün"); süre dolumunu tetiklemez. İkisi ayrı alandır.
+- `odemeKosullari` ("Peşin", "30 gün vade"…) belgede **Ödeme Koşulları**, `teslimGun` **Teslim Süresi**. Bu bilgiyi `not`'a yazmayın.
+- Gönderilmemiş (Draft) teklif `teklif_guncelle` ile düzeltilir; vazgeçilen taslak `teklif_durumu` ile `Rejected` yapılır (silme yoktur).
+
+## Önizleme ve uyarılar
+
+Önizleme, imzalanan girdinin dolu tüm alanlarını listeler; yanıtta ayrıca `gecerliSaat` ("HH:mm'e kadar", İstanbul) ve varsa `uyarilar` gelir:
+aynı gün Z raporu varsa (`z_raporu_elle`, ikinci kayıt için `ikinciKayitOnayi: true`), aynı ad/telefon/VKN'li cari varsa (`cari_ac`),
+cariye bağlı genel tahsilatın faturaları kapatmayacağı (`kasa_hareketi_ekle`). Süre dolarsa hata, hangi aracın hangi girdiyle yeniden çağrılacağını söyler.
+`teklif_paylas` localhost adresi döndürürse "yalnız yerelde açılır" uyarısı verir ve hazır mesaj üretmez (müşteri adresi sunucuda `App__BaseUrl` ile ayarlanır).
+
+## E-posta pazarlama
+
+E-posta Pazarlama uygulaması kuruluysa 11 araç eklenir. Gönderim ayrı kapsamdadır: `email:send` vermediğiniz anahtarla asistan taslak hazırlayabilir ama gönderemez.
+
+- **Hedef açıkça seçilir:** taslakta `grupIds` ya da `tumKisiler: true` gerekir; "herkes" varsayılmaz.
+- **Gönderim önizlemesi** alıcı sayısını, düşecek krediyi (her 100 alıcı için 10) ve aylık kotayı gösterir. Alıcı sayısı önizleme ile onay arasında değişirse gönderilmez (BiApp de `expectedRecipients` ile 409 döner, kredi düşmez).
+- `eposta_kampanya_gonder` `BIAPP_ONAY=dogrudan` iken bile **her zaman** önizleme ve onay ister.
+- Abonelikten çıkma bağlantısı içerikte yoksa BiApp sona ekler. `{{FIRST_NAME}}`, `{{LAST_NAME}}`, `{{FULL_NAME}}`, `{{COMPANY}}` kişiselleştirir.
+- `eposta_kisi_ekle` kişinin e-posta almayı kabul ettiğini kullanıcının söylemesini ister (`izinOnayi`). Abonelikten çıkmış kişiyi yeniden abone yapan araç yoktur.
+- Gönderim sağlayıcısı (SMTP / Brevo / Resend) BiApp panelinde ayarlıdır; MCP ayar yazmaz. Silme, kişi içe aktarma ve şablon editörü yoktur.
+
+### Menü şablonları (haftalık ve günlük)
+
+`eposta_kampanya_hazirla` / `eposta_kampanya_guncelle`, düz metin ve HTML'in yanında BiApp'in hazır menü şablonlarını doldurur:
+
+- **`haftalikMenu`** (Haftalık Menü): yapıştırılan menü `menuMetni`ne olduğu gibi konur. Günler boş satırla ayrılır, her bloğun ilk satırı gün adı, altındakiler yemektir (Pazartesi… Cuma). `baslik`, `altBaslik` ("3 – 7 Kasım") ve `altYazi` isteğe bağlı.
+- **`gunlukMenu`** (Günlük Menü, kategorili kartlar): kategorisiz yemek listesi `yemekMetni`ne konur (satır başına bir yemek). Çorbalar, Ana Yemekler, Pilav & Makarna, Salata & Yanlar, İçecekler, Tatlılar olarak otomatik gruplanır; gruplama önizlemede görünür ve beğenilmezse `kategoriler` ile elle verilir. `tarih` verilmezse bugün (İstanbul). `firma` ile telefon, WhatsApp (905551234567), Instagram kullanıcı adı, adres, harita, logo ve web adresi eklenir.
+
+Menüyü asistan düzenlemez; olduğu gibi şablona koyar. Her hafta/gün tekrar eden **otomatik** gönderim yoktur: menüyü her seferinde yapıştırırsınız, asistan taslağı hazırlar, deneme postasını yollar ve (isterseniz `zaman` ile ileri tarihe zamanlayarak) gönderir.

package/dist/client.js

@@ -0,0 +1,115 @@
+import { randomUUID } from "node:crypto";
+import { BiappError, describeHttpError, networkError } from "./errors.js";
+const MAX_RETRY_AFTER_MS = 10_000;
+/**
+ * BiApp `api/v1` istemcisi. Yalnız `Authorization: Bearer` gönderir; anahtar hata metnine girmez.
+ * Yeniden deneme: 429'da `Retry-After` kadar bekleyip bir kez; 5xx ve ağ hatasında bir kez (yazmada aynı
+ * `Idempotency-Key` ile, yani çift kayıt açmaz).
+ */
+export class BiappClient {
+    config;
+    fetchImpl;
+    sleep;
+    userAgent;
+    constructor(config, fetchImpl = fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), userAgent = "biapp-mcp") {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+        this.sleep = sleep;
+        this.userAgent = userAgent;
+    }
+    get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    /** İkili yanıt (ör. PDF). */
+    getBytes(path) {
+        return this.request("GET", path, { binary: true });
+    }
+    post(path, opts = {}) {
+        return this.request("POST", path, opts);
+    }
+    put(path, opts = {}) {
+        return this.request("PUT", path, opts);
+    }
+    patch(path, opts = {}) {
+        return this.request("PATCH", path, opts);
+    }
+    url(path, query) {
+        const u = new URL(`${this.config.apiUrl}/v1${path}`);
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined && v !== null && v !== "")
+                u.searchParams.set(k, String(v));
+        }
+        return u.toString();
+    }
+    async request(method, path, opts = {}) {
+        const isWrite = method !== "GET";
+        const key = isWrite && !opts.form ? (opts.idempotencyKey ?? randomUUID()) : undefined;
+        const timeout = opts.timeoutMs ?? (opts.form ? this.config.uploadTimeoutMs : this.config.timeoutMs);
+        const url = this.url(path, opts.query);
+        const attempt = async () => {
+            const headers = {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                Accept: opts.binary ? "application/pdf, application/json" : "application/json",
+                "User-Agent": this.userAgent,
+            };
+            if (key)
+                headers["Idempotency-Key"] = key;
+            let body;
+            if (opts.form)
+                body = opts.form;
+            else if (opts.body !== undefined) {
+                headers["Content-Type"] = "application/json";
+                body = JSON.stringify(opts.body);
+            }
+            return this.fetchImpl(url, { method, headers, body, redirect: "error", signal: AbortSignal.timeout(timeout) });
+        };
+        let res;
+        try {
+            res = await attempt();
+        }
+        catch {
+            await this.sleep(500);
+            try {
+                res = await attempt();
+            }
+            catch {
+                throw networkError();
+            }
+        }
+        if (res.status === 429) {
+            const wait = Math.min(Number(res.headers.get("retry-after")) * 1000 || 2000, MAX_RETRY_AFTER_MS);
+            await this.sleep(wait);
+            try {
+                res = await attempt();
+            }
+            catch {
+                throw networkError();
+            }
+        }
+        else if (res.status >= 500) {
+            await this.sleep(500);
+            try {
+                res = await attempt();
+            }
+            catch {
+                throw networkError();
+            }
+        }
+        if (opts.binary && res.ok)
+            return { status: res.status, data: new Uint8Array(await res.arrayBuffer()) };
+        const text = await res.text();
+        let data = undefined;
+        if (text) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = undefined;
+            }
+        }
+        if (!res.ok)
+            throw describeHttpError(res.status, data);
+        return { status: res.status, data: data };
+    }
+}
+export { BiappError };

package/dist/config.js

@@ -0,0 +1,43 @@
+export const VARSAYILAN_API_URL = "https://api.biapp.com.tr/api";
+export class ConfigError extends Error {
+}
+function isLocalHost(host) {
+    return host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost");
+}
+export function loadConfig(env = process.env) {
+    const apiKey = (env.BIAPP_API_KEY ?? "").trim();
+    if (!apiKey) {
+        throw new ConfigError("BIAPP_API_KEY tanımlı değil. BiApp > Ayarlar > Entegrasyonlar'dan bir API anahtarı oluşturup ortam değişkeni olarak verin.");
+    }
+    if (!apiKey.startsWith("bik_")) {
+        throw new ConfigError("BIAPP_API_KEY 'bik_' ile başlamalı; BiApp > Entegrasyonlar'daki anahtarı kopyaladığınızdan emin olun.");
+    }
+    const rawUrl = (env.BIAPP_API_URL ?? "").trim() || VARSAYILAN_API_URL;
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new ConfigError("BIAPP_API_URL geçerli bir adres değil.");
+    }
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLocalHost(parsed.hostname))) {
+        throw new ConfigError("BIAPP_API_URL https olmalı (http yalnız localhost için kabul edilir).");
+    }
+    const apiUrl = rawUrl.replace(/\/+$/, "");
+    const onayRaw = (env.BIAPP_ONAY ?? "sor").trim().toLowerCase();
+    if (onayRaw !== "sor" && onayRaw !== "dogrudan") {
+        throw new ConfigError("BIAPP_ONAY 'sor' ya da 'dogrudan' olmalı.");
+    }
+    const timeoutSn = Number(env.BIAPP_ZAMAN_ASIMI_SN ?? "");
+    const timeoutMs = Number.isFinite(timeoutSn) && timeoutSn > 0 ? timeoutSn * 1000 : 30_000;
+    const fileRoot = (env.BIAPP_DOSYA_KOKU ?? "").trim();
+    return {
+        apiKey,
+        apiUrl,
+        onay: onayRaw,
+        fileRoot: fileRoot || undefined,
+        pdfDir: (env.BIAPP_PDF_KLASORU ?? "").trim() || undefined,
+        timeoutMs,
+        uploadTimeoutMs: Math.max(timeoutMs, 90_000),
+    };
+}

package/dist/confirm.js

@@ -0,0 +1,50 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/** Önizleme kodunun geçerlilik süresi. */
+export const GECERLILIK_DK = 30;
+/** Anahtarları sıralı, `undefined` atılmış JSON: aynı girdi her zaman aynı metni verir. */
+export function canonical(value) {
+    if (value === undefined)
+        return "null";
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map((v) => canonical(v)).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+}
+function mac(apiKey, tool, payload, nonce, exp) {
+    const secret = createHash("sha256").update(`biapp-mcp:${apiKey}`).digest();
+    return createHmac("sha256", secret).update(`${tool}|${canonical(payload)}|${nonce}|${exp}`).digest("hex");
+}
+/**
+ * Durumsuz önizleme kodu: `nonce.bitisSn.hmac`. Süreç yeniden başlasa da doğrulanır; aynı anahtar, araç ve girdi ister.
+ * Kod aynı zamanda `Idempotency-Key` olarak gider (200 karakter sınırının çok altında).
+ */
+export function signIslemKodu(apiKey, tool, payload, now = Date.now()) {
+    const nonce = randomBytes(8).toString("hex");
+    const exp = Math.floor(now / 1000) + GECERLILIK_DK * 60;
+    return `${nonce}.${exp}.${mac(apiKey, tool, payload, nonce, exp)}`;
+}
+export function verifyIslemKodu(apiKey, tool, payload, kod, now = Date.now()) {
+    if (!kod)
+        return { ok: false, neden: "islemKodu yok. Önce onay vermeden çağırıp önizleme alın, kullanıcıya gösterin." };
+    const parts = kod.split(".");
+    if (parts.length !== 3)
+        return { ok: false, neden: "islemKodu geçersiz. Önizlemeyi yeniden alın." };
+    const [nonce, expRaw, given] = parts;
+    const exp = Number(expRaw);
+    if (!Number.isInteger(exp))
+        return { ok: false, neden: "islemKodu geçersiz. Önizlemeyi yeniden alın." };
+    const expected = mac(apiKey, tool, payload, nonce, exp);
+    const a = Buffer.from(given, "hex");
+    const b = Buffer.from(expected, "hex");
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        return { ok: false, neden: "Girdi önizlemedekiyle aynı değil (ya da kod başka araca ait). Yeni önizleme alıp kullanıcıya gösterin." };
+    }
+    if (Math.floor(now / 1000) > exp) {
+        return { ok: false, neden: "Önizlemenin süresi doldu. Yeni önizleme alıp kullanıcıya yeniden onaylatın." };
+    }
+    return { ok: true };
+}

package/dist/errors.js

@@ -0,0 +1,63 @@
+/** Asistana anlatılabilir hata; `message` Türkçe ve eyleme dönüktür, anahtar içermez. */
+export class BiappError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "BiappError";
+    }
+}
+function asBody(raw) {
+    return raw && typeof raw === "object" ? raw : {};
+}
+export function describeHttpError(status, raw) {
+    const body = asBody(raw);
+    const text = typeof body.error === "string" ? body.error : undefined;
+    const code = typeof body.code === "string" ? body.code : undefined;
+    if (status === 401) {
+        return new BiappError("BiApp anahtarı geçersiz ya da iptal edilmiş. BiApp > Ayarlar > Entegrasyonlar'dan yenileyin.", status, code);
+    }
+    if (status === 403) {
+        if (typeof body.scope === "string") {
+            return new BiappError(`Bu anahtarın '${body.scope}' yetkisi yok; BiApp > Entegrasyonlar'da anahtara ekleyin.`, status, "SCOPE");
+        }
+        if (typeof body.app === "string") {
+            return new BiappError(`'${body.app}' uygulaması kurulu değil; BiApp mağazasından kurun.`, status, "APP");
+        }
+        return new BiappError(text ?? "Bu işlem için yetki yok.", status, code);
+    }
+    if (status === 404) {
+        return new BiappError("Kayıt bulunamadı (başka işletmeye ait olabilir).", status, code);
+    }
+    if (status === 409) {
+        if (code === "LEDGER_LOCKED") {
+            return new BiappError(`${text ?? "Bu hareket başka bir kayıttan geliyor."} Tutarı kaynak kaydında düzeltin; açıklama değiştirilebilir.`, status, code);
+        }
+        if (code === "NO_ACTING_USER") {
+            return new BiappError("Bu anahtar adına kayıt açacak aktif kullanıcı yok. Anahtarı bir yönetici açmalı.", status, code);
+        }
+        return new BiappError(text ?? "Kayıt çakışması.", status, code);
+    }
+    if (status === 400 && (code === "DUPLICATE_RECEIPT" || code === "DUPLICATE_POS_REPORT")) {
+        const dup = body.duplicateOfReceiptId ?? body.duplicateOfReportId;
+        return new BiappError(`Bu dosya zaten yüklenmiş${dup ? ` (kayıt ${dup})` : ""}.`, status, code);
+    }
+    if (status === 402) {
+        return new BiappError("Krediniz yok; kayıt bekliyor. Kredi yüklenince işlenir.", status, code);
+    }
+    if (status === 400 || status === 422) {
+        return new BiappError(text ?? "İstek geçersiz.", status, code);
+    }
+    if (status === 429) {
+        return new BiappError("Çok sık istek gönderildi; biraz bekleyip yeniden deneyin.", status, code);
+    }
+    if (status >= 500) {
+        return new BiappError("BiApp şu an yanıt vermiyor; birazdan yeniden deneyin.", status, code);
+    }
+    return new BiappError(text ?? `Beklenmeyen yanıt (${status}).`, status, code);
+}
+export function networkError() {
+    return new BiappError("BiApp'e ulaşılamadı. İnternet bağlantısını ve BIAPP_API_URL'yi kontrol edin.", 0, "NETWORK");
+}