WPKit on every platform

1. Artefakty i source sety1. Artifacts and source sets

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("rip.nerd.wpkit:wpkit-core:3.0.0")
        }
        androidMain.dependencies {
            // Optional legacy Views/Paging/Parse adapter.
            implementation("rip.nerd.wpkit:wpkit:3.0.0")
        }
    }
}

wpkit-core jest pełnym artefaktem KMP. wpkit jest opcjonalnym adapterem Android. Gradle wybiera wariant i silnik Ktor automatycznie; nie wpisuj ręcznie sufiksów -android, -jvm, -ios* ani -wasm-js. Snapshot obu używa 3.0.1-SNAPSHOT.

wpkit-core is the complete KMP artifact. wpkit is an optional Android adapter. Gradle selects the variant and Ktor engine automatically; never add -android, -jvm, -ios* or -wasm-js suffixes manually. Both snapshots use 3.0.1-SNAPSHOT.

2. Publiczny WordPress REST w commonMain2. Public WordPress REST in commonMain

class NewsRepository(baseUrl: String) : AutoCloseable {
    private val client = WordPressClient(WPConfig(baseUrl = baseUrl, perPage = 20))

    suspend fun firstPage(): WPPage<Post> = client.postsPage(page = 1)
    suspend fun search(text: String): List<Post> = client.posts(search = text)
    suspend fun categories(): List<Category> = client.categories()

    override fun close() = client.close()
}

Kod jest ten sam na Androidzie, iOS, Desktop i Web. Silniki to odpowiednio Ktor Android, Darwin, CIO i JS. ATS, CORS i zaufanie certyfikatów pozostają polityką hosta.

The code is identical on Android, iOS, Desktop and Web. Its engines are Ktor Android, Darwin, CIO and JS respectively. ATS, CORS and certificate trust remain host policies.

3. Workspace, konto i tokeny3. Workspace, accounts and tokens

val client = WordPressClient(
    WPConfig(
        baseUrl = "https://example.com",
        workspaceToken = runtimeWorkspaceToken
    )
)
val accounts = WPAccountManager(client, platformAccountStore)
val login = accounts.login(username, password)

workspaceToken pochodzi z konfiguracji runtime lub backendu, nigdy z repozytorium. WPAccountStore przechowuje sesje, WPTokenStore rotowane lease, a WPOutboxStore operacje offline. Implementacje in-memory służą do testów.

workspaceToken comes from runtime configuration or a backend, never source control. WPAccountStore stores sessions, WPTokenStore rotating leases, and WPOutboxStore offline mutations. In-memory implementations are for tests.

4. Android

val accounts = WPAccountManager(
    client = WordPressClient(WPConfig("https://example.com")),
    store = encryptedAndroidAccountStore
)

Zaimplementuj magazyn kont i tokenów przez szyfrowany storage aplikacji, a outbox przez Room, DataStore lub KitsuneDB. Views, Paging 3 i Parse wymagają dodatkowego wpkit w androidMain; sam wpkit-core ich nie pobiera.

Implement account and token storage using encrypted application storage, and the outbox using Room, DataStore or KitsuneDB. Views, Paging 3 and Parse require the additional wpkit dependency in androidMain; wpkit-core does not pull them.

5. iOS / Apple

val client = WordPressClient(WPConfig("https://example.com"))
val accounts = WPAccountManager(client, keychainAccountStore)
val outbox = WPOutbox(applicationSupportOutboxStore)

Nie ma osobnego wrappera wpkit-ios. Sesje zapisuj w Keychain, a niesekretny outbox w Application Support albo SQLDelight. Aplikacyjna implementacja WPAccountStore kontroluje access group i synchronizację Keychain.

There is no separate wpkit-ios wrapper. Store sessions in Keychain and non-secret outbox data in Application Support or SQLDelight. The application-owned WPAccountStore controls Keychain access groups and synchronization policy.

6. JVM / Desktop

val publicClient = WordPressClient(WPConfig("https://example.com"))
val page = publicClient.postsPage(search = "KMP")

Tokeny zapisuj w systemowym keyring/credential vault. Bez bezpiecznego magazynu udostępniaj tylko publiczne endpointy albo sesję wyłącznie w pamięci.

Store tokens in the operating-system keyring or credential vault. Without secure storage, expose public endpoints only or keep a memory-only session.

7. Web / Wasm

val client = WordPressClient(WPConfig("https://cms.example.com"))
val posts = client.posts(page = 1)

Publiczne endpointy działają, gdy WordPress zezwala na origin przez CORS. Dla logowania preferuj backend-for-frontend i bezpieczne cookie HttpOnly. Nie zapisuj tokenu sesji w localStorage. IndexedDB wymaga świadomej implementacji store i własnego modelu zagrożeń.

Public endpoints work when WordPress allows the origin through CORS. Prefer a backend-for-frontend and secure HttpOnly cookies for login. Do not store session tokens in localStorage. IndexedDB requires an explicit store implementation and application threat model.

8. Własny magazyn i outbox8. Custom storage and outbox

class AppAccountStore(private val vault: SessionVault) : WPAccountStore {
    override suspend fun load(): WPAccountSession? = vault.read()
    override suspend fun save(session: WPAccountSession) = vault.write(session)
    override suspend fun clear() = vault.clear()
}

class AppOutboxStore(private val database: MutationDatabase) : WPOutboxStore {
    override suspend fun load(): List<WPOutboxMutation> = database.readAll()
    override suspend fun replace(mutations: List<WPOutboxMutation>) =
        database.replace(mutations)
}

Outbox zachowuje kolejność i idempotency key. Callback flush rozróżnia zastosowanie, oczekiwanie i konflikt; biblioteka nie udaje sukcesu offline.

The outbox preserves ordering and idempotency keys. Its flush callback distinguishes applied, waiting and conflicting mutations; the library never fakes offline success.

9. Demo i testy9. Demo and tests

Demo Android pokazuje publiczne REST, Workspace oraz starsze integracje. DiceX używa wpkit-core w commonMain na Android/iOS/Desktop/Web. CI kompiluje wszystkie targety, a testy iOS uruchamia runner macOS.

The Android demo covers public REST, Workspace and legacy integrations. DiceX uses wpkit-core in commonMain on Android/iOS/Desktop/Web. CI compiles every target and runs iOS tests on a macOS runner.