npm package: @mantric/core
Description: Unified client SDK for Mantric APIs with ORPC and Better Auth integration
Author: Mantric
Latest version: 0.1.1

# @mantric/core

Unified client SDK for Mantric APIs with ORPC and Better Auth integration. This package provides a simple, type-safe way to connect your frontend applications to Mantric-powered backends.

## Features

- 🚀 **Unified Client**: Single factory function for both API and auth clients
- 🔒 **API Key Security**: Built-in API key authentication for core access
- 🎯 **Framework Agnostic**: Works with React, Vue, Svelte, SolidJS, and vanilla TypeScript
- 📦 **Zero Config**: Automatic type generation and seamless development experience
- 🔄 **Auto Type Updates**: Types automatically sync with backend changes in development

## Installation

```bash
npm install @mantric/core
# or
yarn add @mantric/core
# or
bun add @mantric/core
```

## Quick Start

### 1. Generate API Key

First, generate a shared API key for your project:

```bash
bun run generate-api-key
```

This will output an API key and show you how to configure both your server and client.

### 2. Configure Server

Add the generated API key to your core server's `.env` file:

```env
MANTRIC_API_KEY=your-generated-api-key-here
```

### 3. Use in Your Frontend

```typescript
import { mantricClient } from "@mantric/core";

const config = {
  apiKey: "your-generated-api-key-here",
  serverUrl: "https://your-server.com",
  betterAuthUrl: "https://your-server.com/api/auth", // optional
};

const { apiClient, authClient } = mantricClient(config);

// Use the clients
const data = await apiClient.healthCheck();
```

## Configuration

### MantricConfig

```typescript
interface MantricConfig {
  apiKey: string; // Required: API key for server authentication
  serverUrl: string; // Required: Your Mantric server URL
  betterAuthUrl?: string; // Optional: Better Auth URL for authentication
}
```

## API Client Usage

The `apiClient` is a fully typed ORPC client that provides access to all your backend procedures:

```typescript
// Call procedures
const health = await apiClient.healthCheck();
const privateData = await apiClient.privateData();
const todos = await apiClient.todo.list();

// With TanStack Query (React)
import { createTanstackQueryUtils } from "@orpc/tanstack-query";

const orpc = createTanstackQueryUtils(apiClient);

// Use in components
const { data: todos } = orpc.todo.list.useQuery();
```

## Authentication Client Usage

If Better Auth is configured, use the `authClient` for authentication:

```typescript
// Sign up
await authClient.signUp.email({
  email: "user@example.com",
  password: "password123",
  name: "John Doe",
});

// Sign in
const { data } = await authClient.signIn.email({
  email: "user@example.com",
  password: "password123",
});

// Sign out
await authClient.signOut();

// Get current session
const { data: session } = await authClient.getSession();
```

## Framework Examples

### React with TanStack Query

```typescript
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { mantricClient } from '@mantric/core';
import { createTanstackQueryUtils } from '@orpc/tanstack-query';

const config = {
  apiKey: 'your-api-key',
  serverUrl: 'https://your-server.com'
};

const { apiClient } = mantricClient(config);
const orpc = createTanstackQueryUtils(apiClient);

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourComponents />
    </QueryClientProvider>
  );
}

function YourComponent() {
  const { data: health } = orpc.healthCheck.useQuery();
  return <div>Server status: {health}</div>;
}
```

### Vue

```typescript
import { mantricClient } from "@mantric/mantric-client";

const config = {
  apiKey: "your-api-key",
  serverUrl: "https://your-server.com",
};

const { apiClient, authClient } = mantricClient(config);

// Use in your Vue components
```

### Svelte

```typescript
import { mantricClient } from "@mantric/mantric-client";

const config = {
  apiKey: "your-api-key",
  serverUrl: "https://your-server.com",
};

const { apiClient, authClient } = mantricClient(config);

// Use in your Svelte components
```

## Development Workflow

### Automatic Type Generation

In development mode, types are automatically generated and updated when you make changes to your ORPC backend. No manual intervention required!

### Building for Production

To build the package for publishing:

```bash
bun run build
```

To publish to npm:

```bash
npm publish --access public
```

## Security Features

- **API Key Authentication**: All requests are authenticated with your API key
- **CORS Protection**: Configured to work with your server setup
- **Session Management**: Secure session handling with Better Auth

## Environment Variables

| Variable          | Description         | Required |
| ----------------- | ------------------- | -------- |
| `MANTRIC_API_KEY` | Server-side API key | Yes      |

## License

MIT - See LICENSE file for details.