Skip to content

README.md

Latest commit

 

History

History
127 lines (90 loc) · 4.61 KB

README.md

File metadata and controls

127 lines (90 loc) · 4.61 KB
Raw

AWS Blocks Kotlin

Maven Central Kotlin Android iOS Desktop

A Gradle plugin and Kotlin Multiplatform runtime that generates type-safe client code from an AWS Blocks spec. It parses your spec at build time and produces Kotlin interfaces, data classes, and a suspending client implementation that calls your backend methods with full type safety across Android, iOS, and JVM.

Quick Start

1. Apply the plugin

In your app module's build.gradle.kts:

plugins {
    id("com.aws.blocks.kotlin") version "<version>"
}

2. Add the runtime dependency

dependencies {
    implementation("com.aws.blocks.kotlin:runtime:<version>")
}

Configuration

All properties are optional. Override them in the awsBlocks block if the defaults don't fit your project:

import com.aws.blocks.plugin.GeneratedVisibility

awsBlocks {
    // Path to the generated spec file (defaults to rootProject.file("blocks.spec.json"))
    apiSpec = rootProject.file("path/to/your/blocks.spec.json")

    // Package name for generated code (defaults to "com.aws.blocks.generated")
    packageName = "com.example.myapp.generated"

    // Visibility of generated types: Public (default) or Internal
    visibility = GeneratedVisibility.Internal

    // Override or add server URLs (optional)
    servers {
        local("http://10.0.2.2:3001")
        sandbox("https://sandbox.example.com")
        prod("https://api.example.com")
        custom("staging", "https://staging.example.com")
    }

    // Only needed to use the OIDC client on Android or iOS, where the relay scheme is
    // registered with the operating system. Must match an entry in the backend's
    // allowedRelayOrigins. JVM binds a loopback address per sign-in and ignores this.
    oidc {
        relayTo = "com.yourcompany.yourapp://auth/callback"
    }
}

Servers defined in the servers block override entries from the spec file that share the same name. New names are added alongside the spec's servers.

On iOS, declare the same relayTo scheme in the app's Info.plist under CFBundleURLTypes — the Gradle plugin cannot reach an Xcode project. Android needs nothing further; the plugin injects the scheme into the merged manifest.

Using the Generated Code

import com.example.myapp.generated.Api
import com.example.myapp.generated.Todo

val api = Api()

// Create a todo
val todo: Todo = api.createTodo(title = "Buy groceries", priority = 1.0)

// List todos with optional sorting
val todos: List<Todo> = api.listTodos(sortBy = ListTodos.SortBy.Priority)

// Update a todo
api.updateTodo(todoId = todo.todoId, updates = UpdateTodo.Updates(completed = true))

When a method returns a transferable whose tag has no runtime binding, the generated client returns UnknownTransferable, a carrier for the raw tag and descriptor, instead of failing code generation. Only bare direct results are covered; a nullable result still fails code generation.

Gradle Tasks

Task Description
awsBlocksCodegen<Variant> Generates Kotlin sources for the given Android variant (e.g. awsBlocksCodegenDebug)
awsBlocksCodegen Generates Kotlin sources (KMP projects: into commonMain, JVM projects: into main)
awsBlocksDumpModel Parses the spec and dumps the intermediate model for debugging

Example

See the example/android directory for a complete Android app, or example/kmp for a Kotlin Multiplatform (Compose) app that uses the plugin with a todo + auth API.

Supported Platforms

Platform Engine Cookie Storage
Android OkHttp EncryptedSharedPreferences
iOS Darwin (URLSession) Keychain Services
JVM OkHttp AES-256-GCM encrypted files

Support by Target

Block Android iOS JVM
General/RPC ✅ ✅ ✅
Realtime ✅ ✅ ✅
File Bucket ✅ ✅ ✅
OIDC ✅ ✅ ✅

Requirements

  • Kotlin 2.1+
  • JDK 17+
  • Gradle 7.4+
  • Android Gradle Plugin 7.1+ (for Android targets)

License

This project is licensed under the Apache License 2.0. See LICENSE for details.