void 0.1.6 → 0.7.0

package/skills/void/docs/guide/ai.md

@@ -0,0 +1,235 @@
+---
+outline: deep
+---
+
+# AI
+
+Void provides a typed AI client powered by Cloudflare's [AI Gateway](https://developers.cloudflare.com/ai-gateway/). It supports both [Workers AI](https://developers.cloudflare.com/workers-ai/) models and third-party providers such as OpenAI, Anthropic, and Google through bring-your-own-key credentials. Import `ai` from `void/ai` and run inference directly from your route handlers. Usage is metered through Void.
+
+```ts
+import { ai } from 'void/ai';
+```
+
+## Basic Usage
+
+Call `ai.run()` with a model name and inputs. Model names and input types are fully typed from `@cloudflare/workers-types`.
+
+```ts
+import { defineHandler } from 'void';
+import { ai } from 'void/ai';
+
+export const POST = defineHandler(async (c) => {
+  const { prompt } = await c.req.json();
+
+  const result = await ai.run('@cf/meta/llama-3.1-8b-instruct', {
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return c.json(result);
+});
+```
+
+You can use any model available on [Workers AI](https://developers.cloudflare.com/workers-ai/models/), including text generation, image classification, image-to-text, text-to-image, embeddings, translation, and more. Models that return binary data, such as generated images, are returned as a `Blob` from `ai.run()`.
+
+## Streaming
+
+Use `ai.stream()` to get a streaming response with SSE headers that you can return directly from a route handler:
+
+```ts
+import { defineHandler } from 'void';
+import { ai } from 'void/ai';
+
+export const POST = defineHandler(async (c) => {
+  const { prompt } = await c.req.json();
+
+  return ai.stream('@cf/meta/llama-3.1-8b-instruct', {
+    messages: [{ role: 'user', content: prompt }],
+  });
+});
+```
+
+`ai.stream()` calls `ai.run()` with `stream: true` and wraps the result in a `Response` with `content-type: text/event-stream` and `cache-control: no-cache` headers.
+
+## Listing Models
+
+Use `ai.models()` to list available models:
+
+```ts
+const models = await ai.models();
+
+// Filter by task
+const textModels = await ai.models({ task: 'Text Generation' });
+```
+
+## Markdown Conversion
+
+Use `ai.toMarkdown()` to convert documents to markdown:
+
+```ts
+const result = await ai.toMarkdown([{ name: 'document.pdf', blob: pdfBytes }]);
+```
+
+## Local Development
+
+AI requires Void credentials for local development. Run `void auth login` and `void project link` (or follow the interactive setup during `vite dev`) to connect your project.
+
+Once linked, credentials are injected automatically as worker bindings. You do not need to configure them by hand. All inference traffic goes through the Void AI proxy over HTTPS, so usage is tracked and metered the same way it is in production.
+
+## Usage Limits
+
+Workers AI usage is metered in [**neurons**](https://developers.cloudflare.com/workers-ai/platform/pricing/), which is Cloudflare's unit for inference cost. Usage resets at the start of each billing cycle.
+
+| Plan | Included      | At limit                           |
+| ---- | ------------- | ---------------------------------- |
+| Free | 100,000/month | Blocked until billing cycle resets |
+| Solo | 300,000/month | Overage billed                     |
+| Pro  | 500,000/month | Overage billed                     |
+
+On the **free tier**, AI requests return a `429` error once the limit is reached. On **paid tiers**, usage beyond the included allowance is tracked as overage on your monthly bill.
+
+## Third-Party Providers (BYOK)
+
+You can use models from OpenAI, Anthropic, Google, and other providers by passing a `provider/model` identifier. Bring your own API key, add it as a project secret, and Void handles the rest. Third-party inference is billed directly by the provider, and Void does not mark up API calls. Requests still route through AI Gateway so usage shows up on the dashboard.
+
+### Usage
+
+```ts
+import { defineHandler } from 'void';
+import { ai } from 'void/ai';
+
+export const POST = defineHandler(async (c) => {
+  const { prompt } = await c.req.json();
+
+  const result = await ai.run('openai/gpt-4o', {
+    messages: [{ role: 'user', content: prompt }],
+    max_tokens: 512,
+  });
+
+  return c.json(result);
+});
+```
+
+The same `ai.run()` and `ai.stream()` methods work for both Workers AI and third-party models. The framework detects the provider from the model string and routes the request through [AI Gateway](https://developers.cloudflare.com/ai-gateway/) automatically.
+
+The options follow each provider's conventions. All third-party providers use the OpenAI-compatible chat completions format, including `messages`, `max_tokens`, and `temperature`. TypeScript narrows the input and return types based on the model string: Workers AI models get per-model typed inputs from `@cloudflare/workers-types`, while third-party models such as `"provider/model"` get `ChatCompletionInputs` and `ChatCompletionResponse`.
+
+### Vision
+
+Third-party chat models that accept image inputs can receive OpenAI-compatible multimodal message content:
+
+```ts
+const result = await ai.run('openai/gpt-4o', {
+  messages: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What is in this image?' },
+        {
+          type: 'image_url',
+          image_url: { url: 'data:image/png;base64,...', detail: 'high' },
+        },
+      ],
+    },
+  ],
+});
+```
+
+### Image Generation
+
+Use `ai.image()` for image-generation providers or Workers AI image models. It returns a `Response`, so route handlers can return it directly or parse it as JSON depending on the provider:
+
+```ts
+export const POST = defineHandler(async (c) => {
+  const { prompt } = await c.req.json();
+
+  return ai.image('openai/gpt-image-1.5', {
+    prompt,
+    size: '1024x1024',
+    response_format: 'b64_json',
+  });
+});
+```
+
+For Workers AI text-to-image models, pass the model name and input shape from Cloudflare's model docs:
+
+```ts
+export const POST = defineHandler(async (c) => {
+  const { prompt } = await c.req.json();
+  return ai.image('@cf/black-forest-labs/flux-1-schnell', { prompt });
+});
+```
+
+For image edits, pass the file-like input and select the edit endpoint. Void serializes the file through the proxy and forwards it to AI Gateway as multipart form data:
+
+```ts
+export const POST = defineHandler(async (c) => {
+  const body = await c.req.parseBody();
+
+  return ai.image(
+    'openai/gpt-image-1.5',
+    {
+      prompt: String(body.prompt),
+      image: body.image as Blob,
+    },
+    { endpoint: 'images/edits' },
+  );
+});
+```
+
+### Provider Key Convention
+
+Each provider requires an API key set as a project secret. The env var name is automatically derived from the provider prefix:
+
+| Provider prefix    | Env var               |
+| ------------------ | --------------------- |
+| `openai`           | `OPENAI_API_KEY`      |
+| `anthropic`        | `ANTHROPIC_API_KEY`   |
+| `google-ai-studio` | `GOOGLE_API_KEY`      |
+| `deepseek`         | `DEEPSEEK_API_KEY`    |
+| `groq`             | `GROQ_API_KEY`        |
+| `mistral`          | `MISTRAL_API_KEY`     |
+| `grok`             | `GROK_API_KEY`        |
+| `openrouter`       | `OPENROUTER_API_KEY`  |
+| `perplexity`       | `PERPLEXITY_API_KEY`  |
+| `cohere`           | `COHERE_API_KEY`      |
+| `cerebras`         | `CEREBRAS_API_KEY`    |
+| `huggingface`      | `HUGGINGFACE_API_KEY` |
+| `replicate`        | `REPLICATE_API_KEY`   |
+| `baseten`          | `BASETEN_API_KEY`     |
+| `cartesia`         | `CARTESIA_API_KEY`    |
+| `deepgram`         | `DEEPGRAM_API_KEY`    |
+| `elevenlabs`       | `ELEVENLABS_API_KEY`  |
+| `fal`              | `FAL_API_KEY`         |
+| `ideogram`         | `IDEOGRAM_API_KEY`    |
+| `parallel`         | `PARALLEL_API_KEY`    |
+
+All [AI Gateway providers](https://developers.cloudflare.com/ai-gateway/usage/providers/) that accept a Bearer API key are supported. Providers with non-standard auth (Amazon Bedrock, Azure OpenAI, Google Vertex) are not yet supported.
+
+For production, add your API key as a project secret:
+
+```bash
+void secrets set OPENAI_API_KEY sk-...
+```
+
+For local development, add it to `.env.local` in your project root:
+
+```
+OPENAI_API_KEY=sk-...
+```
+
+If the key is missing at runtime, `ai.run()` throws a descriptive error telling you which env var to set.
+
+### Streaming with Third-Party Models
+
+`ai.stream()` works the same way. The response is always SSE regardless of provider:
+
+```ts
+export const POST = defineHandler(async (c) => {
+  const { prompt } = await c.req.json();
+
+  return ai.stream('anthropic/claude-sonnet-4-20250514', {
+    messages: [{ role: 'user', content: prompt }],
+    max_tokens: 512,
+  });
+});
+```

package/skills/void/docs/guide/app-types.md

@@ -0,0 +1,103 @@
+---
+outline: deep
+---
+
+# Supported App Types
+
+Void supports three types of apps:
+
+1. **Void apps:** Vite apps powered by Void's framework layer, including [API routes](./server-routing.md), [pages mode](./pages-routing/overview.md), [auth](./auth.md), [crons](./jobs.md), and [queues](./queues.md)
+2. **Meta frameworks:** [TanStack Start](https://tanstack.com/start/latest), [React Router](https://reactrouter.com/), [SvelteKit](https://svelte.dev/docs/kit), [Nuxt](https://nuxt.com/), and [Astro](https://astro.build/)
+3. **Static sites:** SPAs, sites built with tools like [VitePress](https://vitepress.dev/), or any directory of static files
+
+The type is auto-detected from your project structure, or you can set it explicitly in [`void.json`](../reference/config.md).
+
+## Void Apps
+
+A Vite app powered by Void's framework layer. In this mode, **Void is both the framework and the platform**. It is opinionated in the backend and deployment story, while still staying frontend-framework-agnostic. You can use it with React, Vue, Svelte, Solid, or any frontend that works with Vite.
+
+All Void features that involve backend logic are available in this mode, including [server routing](./server-routing.md), [pages mode](./pages-routing/overview.md), [authentication](./auth.md), [typed fetch](./typed-fetch.md), [cron jobs](./jobs.md), and [queues](./queues.md).
+
+A Void app can be **API-only** (just `routes/`), a **SPA + API** (frontend in `src/` with API routes), or **full-stack with pages mode** (server-rendered pages in `pages/` with co-located data loading):
+
+<VoidAppFileTree annotations />
+
+Your worker handles API routes, page rendering, and (optionally) [custom SSR](./ssr.md). Static assets are served from the edge via per-worker assets. Cloudflare bindings (D1, KV, R2) are [inferred from your source code](../reference/resource-inference.md) and provisioned automatically.
+
+Void apps can also use [`output: 'static'`](./ssg.md) to pre-render all pages at build time. That gives you a fully static site that can be deployed anywhere, with no Cloudflare Worker required.
+
+**Deploy:** `void deploy` builds via Vite, infers bindings, provisions D1/KV/R2 resources, applies migrations, uploads assets and worker, and makes the site live at `{slug}.void.app`. See [Deployment](./deployment.md) for details.
+
+**Detected when any of these exist:**
+
+- `routes/` directory
+- `pages/` directory
+- `middleware/` directory
+- `crons/` directory
+- `queues/` directory
+- Custom SSR entry (`src/main.ssr.ts` or `src/main.ssr.tsx`)
+
+## Meta Frameworks
+
+Void supports deploying Vite-based meta-framework apps with `void deploy`. The framework owns routing and SSR. Void handles [binding inference](../reference/resource-inference.md), [typed DB queries](./database.md), migrations, and deployment.
+
+| Framework                                           | Detected from package   | Setup guide                                           |
+| --------------------------------------------------- | ----------------------- | ----------------------------------------------------- |
+| [TanStack Start](https://tanstack.com/start/latest) | `@tanstack/react-start` | [Guide](../integrations/frameworks/tanstack-start.md) |
+| [React Router v7](https://reactrouter.com/)         | `@react-router/dev`     | [Guide](../integrations/frameworks/react-router.md)   |
+| [SvelteKit](https://svelte.dev/docs/kit)            | `@sveltejs/kit`         | [Guide](../integrations/frameworks/sveltekit.md)      |
+| [Nuxt](https://nuxt.com/)                           | `nuxt`                  | [Guide](../integrations/frameworks/nuxt.md)           |
+| [Analog](https://analogjs.org/)                     | `@analogjs/platform`    | [Guide](../integrations/frameworks/analog.md)         |
+| [Astro](https://astro.build/)                       | `astro`                 | [Guide](../integrations/frameworks/astro.md)          |
+
+Add `voidPlugin()` to the framework's Vite config to get binding inference, typed DB generation, migration management, auth, cron jobs, queues, and caching. See the [Meta Frameworks Integration](../integrations/frameworks/overview.md) for the full feature matrix, deploy pipeline, and per-framework setup guides.
+
+**Deploy:** `void deploy` runs the framework build, packages the output, and deploys to Void. The framework still owns routing and SSR, while Void handles resource provisioning, migrations, and edge hosting.
+
+**Detected when** any of the above packages is in your dependencies.
+
+## Pre-built Static Sites
+
+Any project that produces static files, whether that is an SPA, a static site, or a plain directory. Assets are served directly from the edge, and a minimal passthrough worker is generated automatically. You do not need to write worker code yourself.
+
+**SPAs** (client-side single-page apps) fall back all non-file paths to `index.html` with a 200 status, so client-side routing works out of the box. Detected when `vite` is a dependency and no backend files exist.
+
+**Static sites** (static site generators like VitePress, Docusaurus, or any pre-built directory) produce per-page HTML files. Detected when a known SSG is a dependency, or when using the `--dir` flag.
+
+At the edge, the resolution order is:
+
+1. Exact file path (`/styles.css` → `styles.css`)
+2. Nested index (`/about` → `about/index.html`)
+3. `404.html` with **status 404** (if the file exists)
+4. Plain 404 response
+
+**Deploy:** `void deploy` or `void deploy --dir <path>` uploads static files directly. Assets are served from the edge with automatic caching.
+
+## Auto-Detection
+
+When running `void deploy` and no `inference.appType` is set in `void.json`, the detection logic runs in this order:
+
+| Priority | Condition                                                                                                       | Type                                        |
+| -------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| 1        | `--dir` flag                                                                                                    | Static (or SPA with `--spa`)                |
+| 2        | Known SSG in dependencies (`vitepress`, `@docusaurus/core`)                                                     | Static, builds with SSG CLI                 |
+| 3        | `@tanstack/react-start`, `@react-router/dev`, `@sveltejs/kit`, `nuxt`, `@analogjs/platform`, or `astro` in deps | Framework                                   |
+| 4        | Backend files exist (`routes/`, `pages/`, `middleware/`, `crons/`, `queues/`, SSR entry)                        | Void app                                    |
+| 5        | `vite` or `vite-plus` in dependencies, no backend files                                                         | SPA, builds with `vite build` or `vp build` |
+| 6        | `dist/index.html` or `./index.html` exists                                                                      | Static (no build step)                      |
+
+## Explicit Configuration
+
+To lock the app type and skip auto-detection, set `inference.appType` in [`void.json`](../reference/config.md):
+
+```json
+{
+  "inference": {
+    "appType": "static",
+    "outputDir": ".vitepress/dist"
+  }
+}
+```
+
+- `inference.appType`: `"void"`, `"framework"`, `"spa"`, or `"static"`
+- `inference.outputDir`: output directory for static app types (relative to project root, defaults to `"dist"`)

package/skills/void/docs/guide/auth.md

@@ -0,0 +1,257 @@
+---
+outline: deep
+---
+
+# Authentication
+
+::: warning ⚠️ Void Apps Only
+Void-managed auth currently works only for Void apps. Meta-framework mode is not supported yet.
+:::
+
+Void uses [Better Auth](https://www.better-auth.com/) as the auth engine for Void apps. Void owns the conventions and wiring; Better Auth owns the auth behavior.
+
+## Quick Start
+
+### 1. Enable auth
+
+Add a provider to `void.json`. Email/password is the default, so the simplest config is:
+
+```json
+{
+  "auth": {
+    "providers": ["email"]
+  }
+}
+```
+
+You can also skip this step entirely. Auth activates automatically when you import from `void/auth` or `void/client`.
+
+### 2. Sign up and sign in
+
+Use the preconfigured auth client from `void/client`:
+
+```tsx
+import { auth } from 'void/client';
+
+// sign up
+await auth.signUp.email({
+  email: 'alice@example.com',
+  password: 's3cret',
+  name: 'Alice',
+});
+
+// sign in
+await auth.signIn.email({
+  email: 'alice@example.com',
+  password: 's3cret',
+});
+```
+
+### 3. Protect a server route
+
+Use `requireAuth` in an API route handler or a page loader to gate access. It returns the authenticated user or throws a `401`:
+
+```ts
+// routes/api/profile.ts
+import { defineHandler } from 'void';
+import { requireAuth } from 'void/auth';
+
+export const GET = defineHandler((c) => {
+  const user = requireAuth(c);
+  return { email: user.email };
+});
+```
+
+In a pages-mode loader, use `getUser` or `getSession` when you want to allow unauthenticated access:
+
+```ts
+// pages/dashboard.server.ts
+import { defineHandler, type InferProps } from 'void';
+import { getUser } from 'void/auth';
+
+export type Props = InferProps<typeof loader>;
+
+export const loader = defineHandler(() => {
+  const user = getUser();
+  return { user };
+});
+```
+
+### 4. Sign out
+
+```tsx
+await auth.signOut();
+```
+
+The rest of this page covers configuration, server helpers, and advanced customization in detail.
+
+## Config
+
+Auth turns on automatically when you:
+
+- import anything from `void/auth`
+- import `auth` from `void/client`
+- add `auth` to `void.json`
+- add a root-level `auth.ts` file
+
+The simplest setup is no config at all. Email/password auth is enabled by default.
+
+Example:
+
+```json
+{
+  "auth": {
+    "providers": ["email", "google", "github"]
+  }
+}
+```
+
+Use `auth.providers` when you want to enable social providers explicitly. Provider credentials come from `AUTH_<PROVIDER>_CLIENT_ID` and `AUTH_<PROVIDER>_CLIENT_SECRET`.
+
+See the full provider list in the [config reference](../reference/config.md#auth).
+
+For example, `github` uses:
+
+- `AUTH_GITHUB_CLIENT_ID`
+- `AUTH_GITHUB_CLIENT_SECRET`
+
+## Client Usage
+
+`void/client` exports a preconfigured Better Auth client:
+
+```ts
+import { auth } from 'void/client';
+
+await auth.signUp.email({
+  email: 'alice@example.com',
+  password: 's3cret',
+  name: 'Alice',
+});
+
+await auth.signIn.email({
+  email: 'alice@example.com',
+  password: 's3cret',
+});
+
+await auth.signOut();
+```
+
+The exact client API comes from Better Auth. Void just preconfigures the client with `basePath: "/api/auth"`.
+
+See the official [Better Auth client docs](https://www.better-auth.com/docs/concepts/client) for the full client API.
+
+Framework-specific clients are selected automatically:
+
+- React pages apps use `better-auth/react`
+- Vue pages apps use `better-auth/vue`
+- Svelte pages apps use `better-auth/svelte`
+- Solid pages apps use `better-auth/solid`
+- other Void apps use `better-auth/client`
+
+For advanced usage, `void/client` also exports `createAuthClient`.
+
+## Server Usage
+
+`void/auth` provides the server-side helpers:
+
+```ts
+import { getSession, getUser, requireAuth } from 'void/auth';
+```
+
+- `getUser()` returns the current `AuthUser | null`
+- `getSession()` returns `{ user, session } | null`
+- `requireAuth(c)` returns the authenticated user or throws `401`
+
+Example:
+
+```ts
+import { defineHandler } from 'void';
+import { requireAuth } from 'void/auth';
+
+export const GET = defineHandler((c) => {
+  const user = requireAuth(c);
+  return { email: user.email };
+});
+```
+
+### `AuthUser`
+
+`AuthUser` maps to Better Auth's core user type:
+
+```ts
+interface AuthUser {
+  id: string;
+  email: string;
+  emailVerified: boolean;
+  name: string;
+  image?: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### `AuthSession`
+
+`AuthSession` maps to Better Auth's core session type:
+
+```ts
+interface AuthSession {
+  id: string;
+  token: string;
+  userId: string;
+  expiresAt: Date;
+  createdAt: Date;
+  updatedAt: Date;
+  ipAddress?: string | null;
+  userAgent?: string | null;
+}
+```
+
+## Behavior
+
+When auth is active, Void configures Better Auth with these conventions:
+
+- mount path: `/api/auth/*`
+- email/password enabled by default unless `auth.providers` is set without `"email"`
+- `auth.providers` can enable any built-in Better Auth social provider
+- deployed apps need an auth secret via `BETTER_AUTH_SECRET`
+- D1/SQLite uses the app `DB` binding
+- PostgreSQL apps (`"database": "pg"`) use the app `HYPERDRIVE` binding
+
+Auth sessions live in the same database system as the rest of the app. `AUTH_KV` is no longer used.
+
+On Void Cloud, Void auto-creates `BETTER_AUTH_SECRET` for auth-enabled apps if you have not set `BETTER_AUTH_SECRET` yourself through project secrets.
+
+Localhost dev uses a built-in fallback secret automatically. Outside the managed Void Cloud deploy flow, set `BETTER_AUTH_SECRET` yourself.
+
+## Customization
+
+For advanced configuration, create `auth.ts` at the project root and export `defineAuth(...)`:
+
+```ts
+import { defineAuth } from "void/auth";
+
+export default defineAuth(({ defaults }) => ({
+  ...defaults,
+  trustedOrigins: ["https://example.com"],
+});
+```
+
+`defaults` already includes Void's conventions. Extend it explicitly instead of expecting a deep merge.
+
+For the full set of available options, see the official [Better Auth options reference](https://www.better-auth.com/docs/reference/options).
+
+## Database and Migrations
+
+Void manages Better Auth migrations as part of the normal Void migration flow:
+
+- local dev bootstraps auth tables automatically
+- deploy runs auth migrations together with app migrations
+- users do not run a separate Better Auth CLI path
+
+## Unsupported Modes
+
+Void-managed Better Auth is supported only for Cloudflare Void apps in v1.
+
+- meta-framework mode should use Better Auth's official framework integrations directly
+- `target: "node" | "bun" | "deno"` should use Better Auth directly