insforge--insforge/docs/sdks/kotlin/functions.mdx

---
title: Functions SDK Reference
description: Invoke serverless functions with the InsForge Kotlin SDK
---

import KotlinSdkInstallation from '/snippets/kotlin-sdk-installation.mdx';

## Installation

<KotlinSdkInstallation />

---

## invoke()

Invoke a serverless function by slug.

### Parameters

- `slug` (String) - Function slug identifier
- `body` (Any?, optional) - Request body (will be JSON serialized)

### Returns

```kotlin
T // Typed response (reified generic)
```

### Examples

```kotlin
import kotlinx.serialization.Serializable
import kotlinx.serialization.SerialName

// Define response data class
@Serializable
data class HelloResponse(
    val message: String,
    val timestamp: String
)

// Invoke function with typed response
val response = client.functions.invoke<HelloResponse>(
    slug = "hello-world",
    body = mapOf("name" to "World")
)

println(response.message)  // "Hello, World!"
```

### Example with Typed Request

```kotlin
@Serializable
data class GreetingRequest(
    val name: String,
    val greeting: String
)

@Serializable
data class GreetingResponse(
    val message: String,
    val timestamp: String
)

val response = client.functions.invoke<GreetingResponse>(
    slug = "hello-world",
    body = GreetingRequest(name = "Kotlin", greeting = "Hello")
)
```

---

## invokeRaw()

Invoke a function and get the raw HTTP response.

### Example

```kotlin
val response = client.functions.invokeRaw(
    slug = "generate-pdf",
    body = mapOf("documentId" to "doc-123")
)

// Access raw response
val bytes = response.readBytes()
val contentType = response.contentType()
```

---

## Admin Functions

The following methods require admin/service role authentication.

<Warning>
These methods require the client to be initialized with a **service role key** instead of the anon key. Service role keys have elevated privileges and should only be used in secure server-side environments, never in client-side code.

```kotlin
// Initialize client with service role key for admin operations
val adminClient = createInsforgeClient(
    baseUrl = "https://your-app.insforge.app",
    anonKey = "your-service-role-key"  // Use service role key or api key, not anon key
) {
    install(Functions)
}
```
</Warning>

### listFunctions()

List all functions.

```kotlin
val functions = client.functions.listFunctions()

functions.forEach { fn ->
    println("${fn.name} (${fn.slug}) - ${fn.status}")
}
```

### getFunction()

Get specific function details.

```kotlin
val details = client.functions.getFunction("hello-world")

println("Name: ${details.name}")
println("Slug: ${details.slug}")
println("Status: ${details.status}")
println("Code: ${details.code}")
```

### createFunction()

<Note>
Currently, InsForge only supports JavaScript/TypeScript functions running in a Deno environment.
</Note>
Create a new function.

```kotlin
val result = client.functions.createFunction(
    name = "Hello World",
    code = """
        export default async function(req) {
            const body = await req.json()
            return new Response(JSON.stringify({
                message: `Hello, ${'$'}{body.name}!`,
                timestamp: new Date().toISOString()
            }), {
                headers: { "Content-Type": "application/json" }
            })
        }
    """.trimIndent(),
    slug = "hello-world",  // Optional, auto-generated from name if not provided
    description = "A simple greeting function",
    status = "active"  // "draft" or "active"
)

println("Created function: ${result.slug}")
```

### updateFunction()

Update an existing function.

```kotlin
val result = client.functions.updateFunction(
    slug = "hello-world",
    name = "Hello World v2",
    code = """
        export default async function(req) {
            const body = await req.json()
            return new Response(JSON.stringify({
                message: `Hello, ${'$'}{body.name}! Welcome to v2.`,
                version: 2
            }), {
                headers: { "Content-Type": "application/json" }
            })
        }
    """.trimIndent(),
    status = "active"
)
```

### deleteFunction()

Delete a function.

```kotlin
client.functions.deleteFunction("old-function")
```

---

## Error Handling

```kotlin
import dev.insforge.exceptions.InsforgeHttpException

try {
    val response = client.functions.invoke<MyResponse>("my-function")
    println("Success: $response")
} catch (e: InsforgeHttpException) {
    println("HTTP Error ${e.statusCode}: ${e.message}")
    println("Error code: ${e.error}")
    e.nextActions?.let { actions ->
        println("Suggested actions: $actions")
    }
} catch (e: Exception) {
    println("Unexpected error: ${e.message}")
}
```

---

## Models Reference

### FunctionMetadata

```kotlin
@Serializable
data class FunctionMetadata(
    val id: String,
    val slug: String,
    val name: String,
    val description: String? = null,
    val status: String,  // "draft", "active", "error"
    @SerialName("created_at") val createdAt: String? = null,
    @SerialName("updated_at") val updatedAt: String? = null,
    @SerialName("deployed_at") val deployedAt: String? = null
)
```

### FunctionDetails

```kotlin
@Serializable
data class FunctionDetails(
    val id: String,
    val slug: String,
    val name: String,
    val description: String? = null,
    val code: String,
    val status: String,  // "draft", "active", "error"
    @SerialName("created_at") val createdAt: String,
    @SerialName("updated_at") val updatedAt: String? = null,
    @SerialName("deployed_at") val deployedAt: String? = null
)
```