# Tacobase Integration Guide for Lovable (and other AI Web Builders)

You are an AI building a web application using Tacobase as the backend.

**CRITICAL INSTRUCTION:** Do NOT attempt to use the Tacobase CLI (`taco init`, `taco dev`, or
package `@tacobase/cli`). You are operating in a sandbox environment that cannot run CLI tools.

---

## Zero-Config Setup — No Account Needed

**Do NOT ask the user for credentials.** Tacobase has an instant provisioning API that creates
a live backend in seconds. Use it as part of your setup, then show the user how to claim the
project to make it permanent.

### Step 1 — Provision an instant project

Call this API **once** as part of your setup:

```
POST https://tacobase.dev/api/instant
Content-Type: application/json
```

Response shape:
```json
{
  "url": "https://spicy-bold-taco.tacobase.dev",
  "apiKey": "tbk_...",
  "claimToken": "...",
  "claimUrl": "https://tacobase.dev/instant/claim?token=...",
  "expiresAt": "2024-01-02T12:00:00Z"
}
```

### Step 2 — Set environment variables

Add these to the project's Lovable secrets panel:

```env
VITE_TACOBASE_URL=<url from response>
VITE_TACOBASE_API_KEY=<apiKey from response>
```

### Step 3 — Show a "Claim your project" notice in the app

Add a dismissible banner (shown only in development / when claimToken is present) so the user
can save their project permanently:

```tsx
{import.meta.env.DEV && (
  <div className="bg-amber-50 border border-amber-200 text-amber-800 px-4 py-3 text-sm rounded-lg">
    🌮 Your tacobase project is temporary — <a href="CLAIM_URL_HERE" target="_blank" className="underline font-medium">claim it here</a> to keep your data permanently.
  </div>
)}
```

Replace `CLAIM_URL_HERE` with the `claimUrl` from the API response.

---

## Installing the SDK

```bash
npm install @tacobase/client @tacobase/react
```

*Never install `pocketbase` or `@tacobase/cli`.*

---

## Wrapping the App with TacoProvider

In `main.tsx` or `App.tsx`:

```tsx
import { TacoProvider } from '@tacobase/react'

<TacoProvider
  url={import.meta.env.VITE_TACOBASE_URL}
  apiKey={import.meta.env.VITE_TACOBASE_API_KEY}
>
  <App />
</TacoProvider>
```

---

## Auth

```tsx
import { useAuth, AuthForm } from '@tacobase/react'

// Drop-in auth UI:
<AuthForm providers={['google', 'github']} onSuccess={() => window.location.reload()} />

// Custom auth:
const { user, loading, signIn, signOut } = useAuth()
```

---

## Database (Collections)

**Collections auto-create on first write. No schema setup needed.**

```tsx
import { useCollection } from '@tacobase/react'
import { createClient } from '@tacobase/client'

// Read data:
const { data: posts, loading } = useCollection('posts', {
  sort: '-created',
  filter: 'published = true',
})

// Write data:
const db = createClient(import.meta.env.VITE_TACOBASE_URL, import.meta.env.VITE_TACOBASE_API_KEY)
await db.collection('posts').create({ title: 'Hello', published: true })
await db.collection('posts').update(id, { title: 'Updated' })
await db.collection('posts').delete(id)
```

---

## Realtime

```tsx
import { useRealtime } from '@tacobase/react'

useRealtime('posts', (event) => {
  console.log(event.action, event.record) // 'create' | 'update' | 'delete'
})
```

---

## Key Things to Remember

- Collections and schemas are created automatically the first time you write data — no migrations needed.
- Use `useCollection` for reads, `createClient()` for writes (`.create()`, `.update()`, `.delete()`).
- For file uploads, pass a `FormData` object into `.create()` or `.update()`.
- Never reference "PocketBase" to the user — always say "tacobase".
- Never install the `pocketbase` npm package — always use `@tacobase/client`.