# EdgeBase Elixir Admin SDK

Trusted server-side Elixir SDK for EdgeBase.

Use `edgebase_admin` from Phoenix apps, Plug services, background jobs, and other trusted Elixir runtimes that hold a Service Key. It exposes admin auth, database access, raw SQL, storage, push, analytics, functions, and native edge resources.

This package uses a functional Elixir API. Most entry points return structs, and most service calls expose both non-bang and bang forms.

## Documentation Map

Use this README for a fast overview, then jump into the docs when you need depth:

- [SDK Overview](https://edgebase.fun/docs/sdks)
  Install commands and the public SDK matrix
- [Admin SDK](https://edgebase.fun/docs/sdks/client-vs-server)
  Trusted-server boundaries and admin-only capabilities
- [Admin SDK Reference](https://edgebase.fun/docs/admin-sdk/reference)
  Cross-language examples for auth, database, storage, functions, push, and analytics
- [Admin User Management](https://edgebase.fun/docs/authentication/admin-users)
  Create, update, delete, and manage users with a Service Key
- [Database Admin SDK](https://edgebase.fun/docs/database/admin-sdk)
  Table queries, filters, pagination, batch writes, and raw SQL
- [Storage](https://edgebase.fun/docs/storage/upload-download)
  Uploads, downloads, metadata, and signed URLs
- [Analytics Admin SDK](https://edgebase.fun/docs/analytics/admin-sdk)
  Request metrics, event tracking, and event queries
- [Push Admin SDK](https://edgebase.fun/docs/push/admin-sdk)
  Push send, topic broadcast, token inspection, and logs
- [Native Resources](https://edgebase.fun/docs/server/native-resources)
  KV, D1, Vectorize, and other trusted edge-native resources

## For AI Coding Assistants

This package includes an `llms.txt` file for AI-assisted development.

Use it when you want an agent or code assistant to:

- keep Service Keys on trusted servers
- use the actual Elixir function names
- distinguish between non-bang functions that return `{:ok, ...}` and bang functions that raise on error
- avoid copying promise-based examples into Elixir

You can find it:

- in this repository: [llms.txt](https://github.com/edge-base/edgebase/blob/main/packages/sdk/elixir/packages/admin/llms.txt)
- in your environment after install, inside the `EdgeBaseAdmin` package directory as `llms.txt`

## Installation

```elixir
{:edgebase_admin, "~> 0.1.4"}
```

If you consume the monorepo directly, use the path dependency already configured in this repository.

## Quick Start

```elixir
admin = EdgeBaseAdmin.new(
  "https://your-project.edgebase.fun",
  service_key: System.fetch_env!("EDGEBASE_SERVICE_KEY")
)

auth = EdgeBaseAdmin.admin_auth(admin)
{:ok, user} = EdgeBaseAdmin.AdminAuth.get_user(auth, "user-123")

{:ok, rows} = EdgeBaseAdmin.sql(
  admin,
  "SELECT id, title FROM posts WHERE status = ?",
  namespace: "shared",
  params: ["published"]
)

push = EdgeBaseAdmin.push(admin)
{:ok, _} = EdgeBaseAdmin.Push.send(push, "user-123", %{
  "title" => "Deployment finished",
  "body" => "Your content is live."
})
```

## Core API

Once you create an admin client, these are the main surfaces you will use:

- `EdgeBaseAdmin.new/2`
  Main admin entry point
- `EdgeBaseAdmin.db/3`
  Server-side database access
- `EdgeBaseAdmin.storage/1`
  Storage client
- `EdgeBaseAdmin.admin_auth/1`
  Admin user management
- `EdgeBaseAdmin.auth/1`
  Alias for `admin_auth/1`
- `EdgeBaseAdmin.functions/1`
  Call app functions from trusted code
- `EdgeBaseAdmin.analytics/1`
  Query analytics and track server-side events
- `EdgeBaseAdmin.kv/2`, `EdgeBaseAdmin.d1/2`, `EdgeBaseAdmin.vector/2`
  Native edge resources
- `EdgeBaseAdmin.vectorize/2`
  Alias for `vector/2`
- `EdgeBaseAdmin.push/1`
  Push notifications
- `EdgeBaseAdmin.sql/3`, `EdgeBaseAdmin.sql!/3`
  Raw SQL execution
- `EdgeBaseAdmin.broadcast/4`, `EdgeBaseAdmin.broadcast!/4`
  Server-side broadcast
- `EdgeBaseAdmin.destroy/1`
  No-op cleanup hook

## Database Access

```elixir
db = EdgeBaseAdmin.db(admin, "app")
posts = EdgeBaseCore.DbRef.table(db, "posts")
```

For instance databases, pass the instance id as the third argument:

```elixir
EdgeBaseAdmin.db(admin, "workspace", "ws-123")
EdgeBaseAdmin.db(admin, "user", "user-123")
```

## Admin Users

```elixir
auth = EdgeBaseAdmin.admin_auth(admin)

{:ok, created} =
  EdgeBaseAdmin.AdminAuth.create_user(auth, %{
    "email" => "admin@example.com",
    "password" => "secure-pass-123",
    "displayName" => "June"
  })

{:ok, _} = EdgeBaseAdmin.AdminAuth.set_custom_claims(auth, created["id"], %{
  "role" => "moderator"
})

{:ok, users} = EdgeBaseAdmin.AdminAuth.list_users(auth, limit: 20)
```

## Raw SQL

```elixir
rows =
  EdgeBaseAdmin.sql!(admin, "SELECT 1 AS ok", namespace: "shared")

workspace_rows =
  EdgeBaseAdmin.sql!(admin, "SELECT * FROM documents WHERE status = ?",
    namespace: "workspace",
    instance_id: "ws-123",
    params: ["published"]
  )
```

## Push And Analytics

```elixir
push = EdgeBaseAdmin.push(admin)

{:ok, _} =
  EdgeBaseAdmin.Push.send(push, "user-123", %{
    "title" => "Hello",
    "body" => "From the admin SDK"
  })

analytics = EdgeBaseAdmin.analytics(admin)
{:ok, overview} = EdgeBaseAdmin.Analytics.overview(analytics, %{ "range" => "7d" })
```

## Choose The Right Package

| Package | Use it for |
| --- | --- |
| `edgebase_admin` | Trusted server-side Elixir code with Service Key access |
| `edgebase_core` | Lower-level primitives for custom integrations |

## License

MIT