samples

wizards-api Samples

Standalone sample projects demonstrating wizards-api usage across different platforms.

Prerequisites

Publish wizards-api to local repositories:

# Maven Local (for JVM/Kotlin samples)
./gradlew :wizards-api:publishToMavenLocal

# npm (for JS samples)
./gradlew :wizards-api:jsNodeProductionLibraryDistribution
cd wizards-api/build/dist/js/productionLibrary
npm link

Samples

JVM (Gradle + Kotlin)

Location: samples/jvm/

Standalone Gradle project using wizards-api-jvm from Maven Local.

cd samples/jvm
./gradlew run

Features:

• Kotlin coroutines with runBlocking
• Stores and events search
• Direct use of WizardsLocator class

---

JS/Node.js with Kotlin (Gradle)

Location: samples/js-node-kotlin/

Install node

nvm install 20
nvm use 20

Kotlin/JS project that compiles to Node.js, using Gradle for build.

cd samples/js-node-kotlin
./gradlew nodeDevelopmentRun

Features:

• Same Kotlin code as JVM
• Gradle-based build
• Coroutines with MainScope

---

JS/Node.js with npm (Pure JavaScript)

Location: samples/js-node-npm/

Install node

nvm install 20
nvm use 20
npm install

Pure JavaScript/Node.js project using the npm package.

cd samples/js-node-npm
npm link @devmugi/wizards-api
npm start

Features:

• Pure JavaScript (ES modules)
• Promise-based API (async/await)
• Uses WizardsLocatorJs facade

JavaScript Usage:

import api from '@devmugi/wizards-api';
const { WizardsLocatorJs } = api.devmugi.mtgcards.wizards.api.js;

const locator = new WizardsLocatorJs();

// Search for stores
const stores = await locator.stores(49.8, 24.0, 25000, 10);
stores.forEach(store => console.log(store.name));

// Search for events
const events = await locator.events(49.8, 24.0);
events.forEach(event => console.log(event.title));

locator.close();

---

JS/Web Browser (Vite)

Location: samples/js-web/

Web browser sample using Vite for development.

Install node

nvm install 20
nvm use 20
npm install

cd samples/js-web
npm link @devmugi/wizards-api
npm run dev

Features:

• Vite dev server with hot reload
• Interactive form UI
• Stores and events search
• Promise-based API (async/await)
• Responsive design

JavaScript Usage:

import api from '@devmugi/wizards-api';
const { WizardsLocatorJs } = api.devmugi.mtgcards.wizards.api.js;

const locator = new WizardsLocatorJs();

// Search for stores
const stores = await locator.stores(49.8, 24.0, 25000, 10);
stores.forEach(store => console.log(store.name));

// Search for events
const events = await locator.events(49.8, 24.0, 50000, 10);
events.forEach(event => console.log(event.title));

locator.close();

---

Android (Jetpack Compose)

Location: samples/android/

Native Android app using Jetpack Compose and wizards-api-android.

Prerequisites:

• Android Studio
• Android SDK 35+
• wizards-api published to mavenLocal

# Publish Android artifact
./gradlew :wizards-api:publishAndroidPublicationToMavenLocal

# Build APK
cd samples/android
./gradlew assembleDebug

# Install on device/emulator
adb install app/build/outputs/apk/debug/app-debug.apk

Features:

• Jetpack Compose UI
• Two buttons: Search Stores / Search Events
• LazyColumn results display
• Coroutines with rememberCoroutineScope
• Minimal architecture (no ViewModel)

Screenshot:

The app shows:

• Header with location (Lviv, Ukraine)
• Two action buttons
• Cards displaying store/event details

---

iOS (SwiftUI)

Location: samples/ios/

Native iOS app using SwiftUI and the WizardsApi framework.

Prerequisites:

• Xcode 15.0+
• iOS 17.0+ (deployment target)
• macOS with Xcode command line tools

# Build framework for simulator
./gradlew :wizards-api:linkReleaseFrameworkIosSimulatorArm64

# Open project
open samples/ios/WizardsApiSample/WizardsApiSample.xcodeproj

# Build and run in Xcode (Cmd+R)

Features:

• SwiftUI interface
• Completion handler-based API (for Kotlin interop)
• Two buttons: Search Stores / Search Events
• Error handling with NSError conversion
• Proper resource cleanup with close()

Swift Usage:

import WizardsApi

let locator = WizardsLocatorIos(enableLogging: false, timeoutMs: 10_000)

locator.stores(
    latitude: 49.8,
    longitude: 24.0,
    maxMeters: 25000,
    pageSize: 10,
    page: 0,
    isPremium: false
) { stores, error in
    if let error = error {
        print("Error: \(error.localizedDescription)")
        return
    }
    stores?.forEach { print($0.name) }
}

// Always close when done
locator.close()

---

API Differences

Feature	Kotlin API	JavaScript API	Swift API
Class	WizardsLocator	WizardsLocatorJs	WizardsLocatorIos
Async	suspend fun	Promise<T>	Completion handler
Collections	List<T>	Array<T>	[T]?
Config	WizardsLocatorConfig	Constructor params	Constructor params
Models	Organization, Event	JsOrganization, JsEvent	Organization, Event
Errors	Kotlin exceptions	WizardsApiError	NSError

Architecture Decision Records

See architecture decision records for detailed design decisions:

Library Architecture

• ADR-001: JavaScript Export Architecture - JS facade, models, error handling

Sample-Specific ADRs

• ADR-002: Android Sample Architecture - Jetpack Compose, state management
• ADR-003: iOS Sample Architecture - SwiftUI, completion handlers, SKIE
• ADR-004: Node.js Kotlin Sample - Gradle, Kotlin/JS, coroutines
• ADR-005: Node.js npm Sample - Pure JS, ES modules, async/await
• ADR-006: Web Browser Sample - Vite, browser APIs, interactive UI