AVAX App Developer Guide

Stručný přehled zdrojů pro vývojáře aplikací distribuovaných přes platformu AVAX.

---

1. Přidání aplikace do katalogu

Co připravit

Položka	Popis
slug	Unikátní ID aplikace, lowercase, pomlčky (fakturace-pro)
Název + popis	Zobrazí se v launcheru
Kategorie	Finance, Účetnictví, Logistika, Obchod, HR, Ostatní
Verze	SemVer (2.1.4)
Soubory	Portable app folder — ne installer.exe
Platforma	win, linux, nebo any (per soubor)

Postup nahrání

# 1. Přihlaš se (získej token)
curl -X POST https://api.avaxis.cz/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@vase-firma.cz", "password": "..."}'

# 2. Vytvoř aplikaci v katalogu (catalog_admin role)
curl -X POST https://api.avaxis.cz/admin/apps \
  -H "Authorization: Bearer {token}" \
  -d '{
    "slug": "moje-app",
    "name": "Moje Aplikace",
    "description": "Popis aplikace...",
    "category": "Finance",
    "visibility": "private"
  }'

# 3. Nahraj verzi a získej presigned URL pro soubory
curl -X POST https://api.avaxis.cz/admin/apps/moje-app/versions \
  -H "Authorization: Bearer {token}" \
  -d '{
    "version": "1.0.0",
    "changelog": "První verze",
    "files": [
      {"path": "app.exe",     "platform": "win",  "checksum": "sha256:...", "size": 5242880},
      {"path": "logo.png",    "platform": "any",  "checksum": "sha256:...", "size": 51200}
    ]
  }'

# 4. Nahraj soubory přes presigned S3 URL (odpověď z kroku 3)
curl -X PUT "{presigned_url}" --data-binary @app.exe

# 5. Nasaď verzi (alpha → beta → stable)
curl -X POST https://api.avaxis.cz/admin/apps/moje-app/versions/1.0.0/promote \
  -H "Authorization: Bearer {token}" \
  -d '{"to_channel": "stable"}'

Kanály nasazení

alpha  →  jen Avaxis interní tým (testování)
beta   →  vybrané beta firmy (ověření v produkci)
stable →  všechny firmy s aktivním předplatným

---

2. S3 úložiště — data aplikace

Každá firma má vyhrazený S3 prostor. Aplikace k němu přistupuje přes backend API (ne přímo na S3 — autorizace je na straně serveru).

Adresářová struktura firmy na S3

companies/{company_id}/
├── apps/{app-slug}/
│   ├── data/          ← pracovní data aplikace (sync)
│   └── logs/          ← logy chyb (upload přes API)
└── backups/{app-slug}/
    ├── {snapshot_id}/
    └── latest.json

Sync API (ukládání dat aplikace)

# Získej manifest pro sync (co se změnilo)
GET /sync/{slug}/manifest

# Nahraj změněné soubory (presigned PUT URL)
POST /sync/{slug}/upload
  Body: { "files": ["data/evidence.db", "data/settings.json"] }
  Response: { "urls": [{ "path": "...", "presigned_url": "...", "expires_in": 900 }] }

# Potvrď sync (spustí zálohu snapshot)
POST /sync/{slug}/commit
  Body: { "uploaded_files": ["data/evidence.db"] }

# Stáhni data (restore nebo nové zařízení)
GET /sync/{slug}/download
  Response: presigned GET URL pro každý soubor

Limity S3

Firma	Výchozí limit	Soft limit
Standard	1 GB	5 GB

---

3. AVAX App SDK

Aplikace musí komunikovat s launcherem přes SDK (Named pipe / Unix socket).

Minimální integrace

# Python (pip install avaxis-sdk)
from avaxis_sdk import AvaxApp

app = AvaxApp(slug="moje-app")
app.connect()   # připojí se k launcheru
app.ready()     # launcher ví že app běží

# Cesty ke složkám
data_dir = app.paths.data      # %APPDATA%/Avaxis/apps/moje-app/data/
settings  = app.paths.settings # %APPDATA%/Avaxis/apps/moje-app/settings/

# Graceful shutdown (povinné pro správný update)
@app.on_shutdown
def save_and_exit():
    save_state()
    app.shutdown_ok()

// .NET (NuGet: Avaxis.SDK)
var app = new AvaxApp("moje-app");
await app.ConnectAsync();
app.Ready();

app.OnShutdown += async () => {
    await SaveStateAsync();
    app.ShutdownOk();
};

Offline JWT (ověření licence bez internetu)

Launcher předá aplikaci offline JWT při spuštění. Aplikace ověří podpis bundlovaným public key — funguje bez připojení k serveru.

# Public key je součástí SDK
from avaxis_sdk import verify_offline_jwt

claims = verify_offline_jwt(token=app.offline_jwt)
# claims: { sub, company_id, apps: ["moje-app"], exp }

---

4. Logy chyb

# 1. Získej presigned URL pro nahrání logu
POST /apps/{slug}/log-upload-url
  Body: { "filename": "error-2025-01-15.log", "size": 102400 }

# 2. Nahraj přes presigned PUT URL
curl -X PUT "{presigned_url}" --data-binary @error.log

Logy jsou přístupné Avaxis support týmu v portálu a slouží k diagnostice.

---

5. Zálohy

Zálohy probíhají automaticky po každém sync/commit. Aplikace může vyžádat okamžitou zálohu:

POST /backup/{slug}/manual

Historie záloh a restore:

GET  /backup/{slug}/history
POST /backup/{slug}/restore/{snapshot_id}

---

6. Kontrola aktualizací (pro vlastní update logiku)

GET /catalog/{slug}/check-update?installed_version=1.0.0&platform=win
Response: {
  "update_available": true,
  "version": "1.1.0",
  "changelog": "...",
  "manifest_url": "https://s3.avaxis.cz/... (presigned, 15 min)"
}

Standardně aktualizace řídí launcher — toto je pro edge case kdy aplikace chce zkontrolovat update sama.

---

7. Dev server pro testování

API:    http://192.168.1.55:8000
Docs:   http://192.168.1.55:8000/docs   (Swagger UI)
S3:     http://192.168.1.55:9000        (MinIO konzole: :9001)

Testovací login:
  E-mail:   admin@test.cz
  Heslo:    Heslo123!
  Firma:    Test Firma s.r.o.
  Role:     company_admin

---

8. Checklist před přidáním do katalogu

• Aplikace obsahuje AVAX SDK a volá app.ready() při startu
• Implementován on_shutdown handler s app.shutdown_ok()
• Data ukládána do app.paths.data (ne do System32 nebo registry)
• Offline JWT ověřen při startu (ochrana licence)
• Logy chyb se nahrávají přes /apps/{slug}/log-upload-url
• Otestováno na alpha kanálu (Avaxis interní firma)
• Verze nasazena na beta (alespoň 1 týden) před stable

---

Verze dokumentu: 2026-04-24 | api.avaxis.cz