@virusis/api-client

TypeScript API client generated with NSwag. Fetch tabanli; ApiClientConfig ile base URL ve bearer token saglayarak kullanilir. Config'i tek seferde ayarlayip tum servisleri ortak kullanmak icin setDefaultConfig + getServices / getServicesRx kullan.

TypeScript ve Dart SDK'larini ayni OpenAPI snapshot'indan uretmek ve parity kontrolunu calistirmak icin npm run gen:sdks kullanin. Ayrintilar: SDK generation and parity.

Kurulum

npm install @virusis/api-client
# veya
yarn add @virusis/api-client

Hizli baslangic (tek seferde config + tum servisler):

import { ApiClientConfig, setDefaultConfig, getServices } from "@virusis/api-client";

setDefaultConfig(
  new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
);

const services = getServices(); // camelCase servisler
await services.usersService.getAll();

Populer Framework Ornekleri

Angular

Merkezi config + DI servis:

import { Injectable, Inject } from "@angular/core";
import { ApiClientConfig, setDefaultConfig, getServices } from "@virusis/api-client";

@Injectable({ providedIn: "root" })
export class ApiClientService {
  services = getServices();
  constructor(@Inject("API_BASE_URL") baseUrl: string) {
    setDefaultConfig(
      new ApiClientConfig(baseUrl, () => localStorage.getItem("token"))
    );
  }
}

Provider:

providers: [{ provide: "API_BASE_URL", useValue: "https://api.example.com" }]

Component:

constructor(private api: ApiClientService) {}
ngOnInit() {
  this.api.services.usersService.getAll().then(console.log);
}

React (web)

import { useEffect, useMemo } from "react";
import { ApiClientConfig, UsersClient } from "@virusis/api-client";

export function UsersList() {
  const client = useMemo(() => new UsersClient(
    new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
  ), []);

  useEffect(() => {
    client.getAll().then(console.log);
  }, [client]);

  return null;
}

Vue 3

import { ApiClientConfig, UsersClient } from "@virusis/api-client";
import { onMounted } from "vue";

const client = new UsersClient(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token")));

onMounted(async () => {
  const users = await client.getAll();
  console.log(users);
});

React Native

import { ApiClientConfig, UsersClient } from "@virusis/api-client";

const client = new UsersClient(new ApiClientConfig("https://api.example.com", async () => {
  return await getTokenFromSecureStore();
}));
const users = await client.getAll();

Moduler import (kebab-case dosya adlari)

• Servisler (client class'lari Service alias'i ile): @virusis/api-client/clients/<controller>-service
  • Ornek: @virusis/api-client/clients/users-service
• Modeller: @virusis/api-client/models/<model>
  • Ornek: @virusis/api-client/models/user
  • Tip kullanimi: import type { user } from "@virusis/api-client/models/user";

Tek seferde config verip merkezi kullanmak (getServices / getServicesRx)

import { ApiClientConfig, setDefaultConfig, getServices, getServicesRx } from "@virusis/api-client";

setDefaultConfig(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token")));

const services = getServices();     // Promise tabanli
await services.usersService.getAll();

const servicesRx = getServicesRx(); // Rx tabanli
servicesRx.usersService.getAll().subscribe(console.log);

Bu sayede her import'ta ApiClientConfig vermek gerekmiyor; tek seferde ayarlayip tum servisleri kullanabiliyorsun.

Tek isimden secim yapmak istersen getServicesByMode("rx")/getServicesByMode("promise"):

import { ApiClientConfig, setDefaultConfig, getServicesByMode } from "@virusis/api-client";
setDefaultConfig(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token")));
const services = getServicesByMode("rx"); // "rx" -> Observable, "promise" -> Promise
services.authService.login().subscribe(console.log);

RxJS

Promise metotlarini Observable'a cevirmek icin:

import { ApiClientConfig, UsersClient, rxifyClient } from "@virusis/api-client";
const client = rxifyClient(new UsersClient(new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))));
client.getAll().subscribe(console.log);

RxJS hazir factory'ler

Tek tek tanimlamak istemiyorsan, tum client'lari otomatik Rx olarak al:

import { ApiClientConfig, createAllRxClients } from "@virusis/api-client";
const cfg = new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"));
const services = createAllRxClients(cfg);
services.usersService.getAll().subscribe(console.log);

(Alternatif: create<Controller>ServiceRx fonksiyonlari da var.)

Tum Rx client'lari camelCase key ile almak istersen:

import { ApiClientConfig, createAllRxClientsCamel } from "@virusis/api-client";
const services = createAllRxClientsCamel(
  new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
);
// services.usersService.getAll().subscribe(...)

HTTP ozellestirme (headers / credentials)

• Tum cagrilarda withCredentials, ekstra header gibi default'lar icin buildHttpWithDefaults:

import { ApiClientConfig, UsersClient, buildHttpWithDefaults } from "@virusis/api-client";

const cfg = new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"));
const http = buildHttpWithDefaults(cfg, {
  credentials: "include",              // tarayici cookie'lerini gonder
  headers: { "X-Tenant": "acme" },     // tum isteklere ek default header
});

const users = new UsersClient(cfg, undefined, http);
await users.getAll(); // header'lar + Authorization otomatik gider

• Belirli endpoint'i ozel yonetmek istersen http.fetch'i sarmalayarak URL bazli header ekleyebilirsin:

const baseHttp = buildHttpWithDefaults(cfg, { credentials: "include" });
const http = {
  fetch: (url, init) => {
    const extra = url.toString().includes("UserViews")
      ? { headers: { "X-View": "hasVisited" } }
      : undefined;
    return baseHttp.fetch(url, { ...init, ...extra });
  },
};
const client = new UsersClient(cfg, undefined, http);

Varsayilan Authorization (Bearer) ve Accept/Content-Type header'lari ayni sekilde korunur.

Tum client'lari otomatik (Promise tabanli)

import { ApiClientConfig, createAllClientsCamel } from "@virusis/api-client";
const services = createAllClientsCamel(
  new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"))
);
// Ornek: services.usersService.getAll().then(...)

Auth Notu

ApiClientConfig.getToken saglandiginda Authorization header otomatik eklenir.

Flutter (JS koprusu)

dist ciktilarini flutter_js vb. runtime ile yukleyip kullanabilirsin (bkz. docs/flutter.md). Kucuk bundle icin npx esbuild dist/index.js --bundle --platform=browser --outfile=dist/bundle.js.

Komutlar

• npm run generate - NSwag + stub bolme (cross-platform)
• npm run build - TypeScript build
• npm test - Vitest
• npm run check - build + test
• npm run ci - generate + build + test
• npm run pack:local - packages/virusis-api-client-0.1.0.tgz uretir
• npm run release:version -- patch - npm ve Dart paket surumlerini birlikte artirir (minor, major veya tam surum de verilebilir)
• npm run release:dry - npm paketini yayinlamadan kontrol eder
• npm run release - dogrudan yayini engeller; yayin GitHub Actions'taki Release npm and Dart packages workflow'undan yapilir
• npm run fetch:spec - swagger'ı (varsayılan http://localhost:5000/swagger/v1/swagger.json, SPEC_URL ile degistirilebilir) indirip specs/openapi.json kaydeder (cross-platform)
• npm run gen:python - specs/openapi.json ile Python paketi (out/python, virusis_api_client)
• npm run gen:flutter - specs/openapi.json ile Dart/Flutter paketi (dart-dio-next, out/flutter, pubName=virusis_api_client)
• npm run gen:all - python + flutter jenerasyonlarini art arda calistirir
• npm run version:auto - conventional commit log'una gore versiyon + CHANGELOG.md gunceller (tag/commit olusturmaz)

Paket yayini

Paket surumunu npm run release:version -- patch ile hazirlayip degisiklikleri main branch'ine commit et. main branch'inden prod branch'ine acilan PR merge edildiginde Release npm and Dart packages workflow'u otomatik olarak gercek yayini baslatir. Workflow npm ve Dart surumlerini esler, generated TypeScript client dosyalarini clean runner'da yeniden olusturur, test/dry-run yapar, Infisical virusproof/prod ortamindan NPM_TOKEN ve PUB_CREDENTIALS secret'larini alir, iki paketi yayinlar ve vX.Y.Z GitHub Release'i olusturur.

prod branch'i uzerinde workflow manuel olarak dry_run=true ile de calistirilabilir; manuel dry-run registry'lere yazmaz.

GitHub'da yalnizca salt-okuma Infisical erisim token'i INFISICAL_TOKEN olarak tutulur. Registry credential'lari repoya veya GitHub secret'larina yazilmaz.

Npm hesabinda yazma islemleri icin 2FA aciksa Infisical'daki NPM_TOKEN, paket icin read/write yetkili ve bypass 2FA secenegi acik bir granular access token olmalidir. Workflow bu kosulu release commit'inden once kontrol eder.

Detayli dokumanlar:

• Release sisteminin calisma sekli
• Developer release kullanim rehberi

Docker

• Dev: docker compose -f .devcontainer/docker-compose.yml run --rm api-client-dev sh icinde npm run ci/npm test
• Paketleme (dev): docker compose -f .devcontainer/docker-compose.yml run --rm api-client-dev sh -c "npm run pack:local"
• Prod paket kontrolu: docker compose -f .devcontainer/docker-compose.yml run --rm api-client-prod npm run release:dry
• Sadece build+test prod: docker compose -f .devcontainer/docker-compose.yml run --rm api-client-prod npm run ci

Angular'da Rx (provider ile)

Service:

import { Injectable, Inject } from "@angular/core";
import { ApiClientConfig, createAllRxClientsCamel } from "@virusis/api-client";

@Injectable({ providedIn: "root" })
export class ApiClientService {
  services = createAllRxClientsCamel(
    new ApiClientConfig(this.baseUrl, () => localStorage.getItem("token"))
  );

  constructor(@Inject("API_BASE_URL") private baseUrl: string) {}
}

Module:

providers: [{ provide: "API_BASE_URL", useValue: "https://api.example.com" }]

Component:

constructor(private api: ApiClientService) {}
ngOnInit() {
  this.api.services.usersService.getAll().subscribe(console.log);
}

Modelleri kullanma

• Tum model exportlarini tek yerden almak icin:

import { getModels } from "@virusis/api-client";
const Models = getModels();
// Model tipleri
const user: Models.User = { /* ... */ };

• Rx client'larla birlikte:

import { ApiClientConfig, createAllRxClientsCamel, getModels } from "@virusis/api-client";
const cfg = new ApiClientConfig("https://api.example.com", () => localStorage.getItem("token"));
const services = createAllRxClientsCamel(cfg);
const Models = getModels();
services.usersService.getAll().subscribe((data: Models.User[]) => console.log(data));

Base URL notu

• ApiClientConfig.baseUrl zorunlu ve mutlak olmalidir. baseUrl /api ile bitip path de /api/... ile basliyorsa otomatik tek /api/... olacak sekilde birlestirilir; iki kere /api eklenmez.