# EdgeBase Elixir Core SDK

Shared low-level Elixir primitives for EdgeBase.

`edgebase_core` is the foundation used by `edgebase_admin`. It provides the HTTP client, DB and document references, table query helpers, storage helpers, field operation markers, and the shared error type used by higher-level SDKs.

Most application code should install [`edgebase_admin`](https://hex.pm/packages/edgebase_admin) instead. Use this package directly when you are building custom wrappers, generated bindings, or internal integrations.

## Documentation Map

Use this README for the 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
- [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
- [Admin SDK Reference](https://edgebase.fun/docs/admin-sdk/reference)
  Cross-language examples that sit on top of this core package

## 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 the server
- 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/core/llms.txt)
- in your environment after install, inside the `EdgeBaseCore` package directory as `llms.txt`

## Installation

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

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

## Quick Start

```elixir
client =
  EdgeBaseCore.new_http_client(
    "https://your-project.edgebase.fun",
    service_key: System.fetch_env!("EDGEBASE_SERVICE_KEY")
  )

db = EdgeBaseCore.DbRef.new(client, "shared")
posts = EdgeBaseCore.DbRef.table(db, "posts")
{:ok, rows} = EdgeBaseCore.TableRef.get_list(posts)

storage = EdgeBaseCore.StorageClient.new(client)
bucket = EdgeBaseCore.StorageClient.bucket(storage, "avatars")
{:ok, _} = EdgeBaseCore.StorageBucket.upload(bucket, "user-1.jpg", "binary-data", content_type: "image/jpeg")

marker = EdgeBaseCore.FieldOps.increment(1)
```

## Included Surfaces

- `EdgeBaseCore.new_http_client/2`
- `EdgeBaseCore.HttpClient`
- `EdgeBaseCore.DbRef`, `EdgeBaseCore.DocRef`, `EdgeBaseCore.TableRef`
- `EdgeBaseCore.StorageClient`, `EdgeBaseCore.StorageBucket`
- `EdgeBaseCore.FieldOps.increment/1` and `delete_field/0`
- `EdgeBaseCore.Error`

## Choose The Right Package

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

## License

MIT