@microsoft/rayfin-guide 1.1.0 → 1.33.0-beta.1

package/assets/docs/data/permissions.md

@@ -0,0 +1,172 @@
+---
+sidebar_position: 3
+---
+
+# Data permissions
+
+Rayfin uses the `@role` decorator to attach authorization rules directly to your data models.
+Permissions are type-safe, refactor-friendly, and compiled into Data API Builder (DAB) configuration automatically.
+
+## Built-in roles
+
+Rayfin recognizes two built-in roles:
+
+- **anonymous** — public access without authentication.
+- **authenticated** — requires a valid user session.
+
+## The `@role` decorator
+
+Apply `@role` at the class level to control which roles can perform which actions on an entity.
+
+```typescript
+@role(roleName, actions, options?)
+```
+
+| Parameter | Description |
+| --- | --- |
+| `roleName` | The role name (`'anonymous'` or `'authenticated'`). |
+| `actions` | A single action or array of actions: `'create'`, `'read'`, `'update'`, `'delete'`, or `'*'` for all. |
+| `options` | Optional object with `check`, `include`, and `exclude` properties. |
+
+## Basic example
+
+Grant anonymous users read access and restrict authenticated users to their own data:
+
+```typescript
+import { entity, role, uuid, text } from '@microsoft/rayfin-core';
+
+@entity()
+@role('anonymous', 'read')
+@role('authenticated', ['create', 'read', 'update', 'delete'], {
+  check: (claims, item) => claims.sub.eq(item.user_id),
+})
+export class Todo {
+  @uuid() id!: string;
+  @text() title!: string;
+  @text() description?: string;
+  @text() user_id!: string;
+}
+```
+
+In this example, authenticated users can only access Todo items where `user_id` matches their JWT `sub` claim.
+
+## Type-safe policy expressions
+
+The `check` callback provides typed access to both claims and entity fields.
+TypeScript infers the entity type from the decorated class, so you get autocompletion and refactor safety with no extra configuration.
+
+```typescript
+check: (claims, item) => claims.sub.eq(item.user_id)
+```
+
+### Supported claims
+
+| Claim | Description |
+| --- | --- |
+| `claims.sub` | Subject identifier (user ID). |
+| `claims.email` | User email address. |
+| `claims.role` | User role. |
+
+### Expression operators
+
+| Operator | Example | DAB output |
+| --- | --- | --- |
+| `.eq()` | `claims.sub.eq(item.user_id)` | `@claims.sub eq @item.user_id` |
+
+### Logical operators
+
+Combine expressions with `.and()` and `.or()`:
+
+```typescript
+check: (claims, item) =>
+  claims.sub.eq(item.user_id).and(item.isActive.eq(true))
+```
+
+Both sides are parenthesized automatically, so grouping is always explicit:
+
+```typescript
+// (claims.role eq 'admin') or (claims.sub eq @item.owner_id)
+check: (claims, item) =>
+  claims.role.eq('admin').or(claims.sub.eq(item.owner_id))
+```
+
+## Field-level permissions
+
+Control which fields a role can access using `include` or `exclude` in the role options.
+
+### Include specific fields
+
+Only allow the `Title` field during create:
+
+```typescript
+@role('authenticated', 'create', {
+  check: (claims, item) => claims.sub.eq(item.createdBy),
+  include: ['Title'],
+})
+```
+
+### Exclude specific fields
+
+Hide sensitive fields from read operations:
+
+```typescript
+@role('authenticated', 'read', {
+  check: (_claims, item) => item.IsAdmin.eq(false),
+  exclude: ['last_login'],
+})
+```
+
+Field arrays are typed to the entity's actual property names.
+Renaming a field produces a compile-time error in every `include` or `exclude` list that references it.
+
+## Action-specific permissions
+
+Apply different rules per action by using multiple `@role` decorators with single actions:
+
+```typescript
+@entity()
+@role('anonymous', 'read')
+@role('authenticated', 'create', {
+  check: (claims, item) => claims.sub.eq(item.createdBy),
+  include: ['Title'],
+})
+@role('authenticated', 'read', {
+  check: (claims, item) => claims.sub.eq(item.createdBy),
+})
+@role('authenticated', 'update', {
+  check: (claims, item) => claims.sub.eq(item.createdBy),
+  exclude: ['adminContent'],
+})
+export class SecureDocument {
+  @uuid() id!: string;
+  @text() Title!: string;
+  @text({ optional: true }) adminContent?: string;
+  @text() createdBy!: string;
+}
+```
+
+## Storage permissions
+
+The same `@role` decorator works with storage entities.
+When applied to a `@blob()` class, Rayfin generates a storage policy instead of a database policy:
+
+```typescript
+import { blob, role } from '@microsoft/rayfin-core';
+
+@blob()
+@role('authenticated', '*', {
+  check: (claims, item) => claims.sub.eq(item.owner_id),
+})
+export class ProfileImage {
+  owner_id!: string;
+}
+```
+
+## How it works
+
+- The `@role` decorator collects permission metadata at class definition time.
+- When you run `npx rayfin up db apply`, the CLI reads that metadata and generates DAB-compliant permission entries in the configuration.
+- Policy callbacks are compiled into DAB OData-style policy strings (for example `@claims.sub eq @item.user_id`).
+- Field `include`/`exclude` arrays map directly to DAB field permission configuration.
+- Multiple `@role` decorators on the same class are aggregated per role.
+  Conflicting declarations produce a warning at generation time.

package/assets/docs/data/validation.md

@@ -0,0 +1,165 @@
+---
+sidebar_position: 4
+---
+
+# Form Validation
+
+Rayfin can generate a [Standard Schema](https://standardschema.dev) validator directly from your decorated entity classes.
+This lets you validate form input on the client without adding a separate validation library like Zod or Yup.
+
+## Build a validator from an entity
+
+Use `toStandardSchema` to create a validator from any `@entity()` class.
+The `id` field and relationship navigation properties (`@one`, `@many`) are automatically excluded — you only need to list additional fields your form does not collect.
+
+```typescript
+import { toStandardSchema } from '@microsoft/rayfin-core';
+import { Todo } from '../rayfin/data/Todo.js';
+
+// id is auto-omitted. List fields you want to omit from validation.
+const todoInputSchema = toStandardSchema(Todo, {
+  omit: ['createdAt', 'updatedAt'] as const,
+});
+```
+
+The returned object implements the Standard Schema v1 contract (`~standard`) so it works with any compatible library (TanStack Form, Conform, tRPC v11, and others).
+It also exposes a convenience `.validate()` method for direct use.
+
+## Validate form input
+
+Call `.validate()` with your form values.
+The result is either `{ value }` on success or `{ issues }` on failure.
+
+```typescript
+const result = todoInputSchema.validate({
+  title: title.trim(),
+  isCompleted: false,
+  priority: 'medium',
+});
+
+if (result.issues) {
+  // Map issues to per-field errors by path[0]
+  const errors: Record<string, string> = {};
+  for (const issue of result.issues) {
+    const key = String(issue.path?.[0] ?? '_');
+    if (!errors[key]) errors[key] = issue.message;
+  }
+  // Display errors in the UI
+} else {
+  // result.value is typed as Omit<Todo, 'id' | 'createdAt' | 'updatedAt'>
+  await api.createTodo(result.value);
+}
+```
+
+Validation is synchronous.
+All checks (type guards, string length, regex, enum membership) run in memory with no async overhead.
+
+## Read field constraints for UI hints
+
+Use `getFieldConstraints` to read the decorator constraints for a single field.
+This is useful for displaying character counters, limit labels, or other UI hints without building a full schema.
+
+```typescript
+import { getFieldConstraints } from '@microsoft/rayfin-core';
+import { Todo } from '../rayfin/data/Todo.js';
+
+const titleConstraints = getFieldConstraints(Todo, 'title');
+// { type: 'string', min: 1, max: 50, optional: false }
+
+const maxLength =
+  titleConstraints?.type === 'string' ? titleConstraints.max : undefined;
+```
+
+The field name is type-checked against the entity — typos are caught at compile time.
+
+## What gets validated
+
+The validator checks each field based on its decorator:
+
+| Decorator | Checks |
+| --- | --- |
+| `@text()` | Is a string. Enforces `min`, `max`, and `regex` when specified. |
+| `@uuid()` | Is a string matching the UUID format. |
+| `@email()` | Is a string matching a practical email pattern. |
+| `@int()` | Is a finite integer. Enforces `min` and `max` bounds. |
+| `@decimal()` | Is a finite number. Enforces `min` and `max` bounds. |
+| `@boolean()` | Is a boolean. |
+| `@date()` | Is a `Date` object, ISO string, or numeric timestamp. |
+| `@set()` | Value is one of the declared enum literals. |
+
+Required fields (the default) produce a "required" issue when missing or `null`.
+Optional fields (`{ optional: true }`) are silently skipped when absent.
+Unknown fields not declared on the entity are rejected.
+
+## Auto-omit behavior
+
+`toStandardSchema` automatically excludes:
+
+- The `id` primary key — typically server-generated, never part of a form.
+- Relationship navigation properties (`@one`, `@many`) — not form inputs.
+
+Pass additional field names in the `omit` option for other server-managed fields like timestamps or `user_id`.
+The `omit` array is type-safe — misspelled field names are caught at compile time.
+
+```typescript
+// Only need to list fields beyond id and relationships
+const schema = toStandardSchema(Note, {
+  omit: ['createdAt', 'updatedAt', 'user_id'] as const,
+});
+```
+
+## Complete React example
+
+```tsx
+import { useMemo, useState } from 'react';
+import { toStandardSchema, getFieldConstraints } from '@microsoft/rayfin-core';
+import { Todo } from '../rayfin/data/Todo.js';
+
+export function TodoForm({ onSubmit }) {
+  const [title, setTitle] = useState('');
+  const [error, setError] = useState('');
+
+  const todoInputSchema = useMemo(
+    () => toStandardSchema(Todo, { omit: ['createdAt', 'updatedAt'] as const }),
+    []
+  );
+
+  const titleConstraints = getFieldConstraints(Todo, 'title');
+  const maxLength =
+    titleConstraints?.type === 'string' ? titleConstraints.max : undefined;
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    const result = todoInputSchema.validate({ title: title.trim() });
+    if (result.issues) {
+      setError(result.issues[0].message);
+      return;
+    }
+    setError('');
+    await onSubmit(result.value);
+    setTitle('');
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={title} onChange={(e) => setTitle(e.target.value)} />
+      {maxLength && <span>{title.length}/{maxLength}</span>}
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+      <button type="submit">Add</button>
+    </form>
+  );
+}
+```
+
+## Standard Schema interop
+
+The object returned by `toStandardSchema` implements `StandardSchemaV1` from `@standard-schema/spec`.
+Any library that reads the `~standard` property can consume it directly.
+
+```typescript
+// TanStack Form, Conform, tRPC v11, etc. read ~standard automatically.
+// You can also access it explicitly if needed:
+const result = todoInputSchema['~standard'].validate(formValues);
+```
+
+The `RayfinStandardSchema` and `StandardSchemaV1` types are re-exported from `@microsoft/rayfin-core` so you do not need a direct dependency on `@standard-schema/spec`.

package/assets/docs/getting-started/create-app-with-cli.md

@@ -0,0 +1,118 @@
+---
+sidebar_position: 5
+title: Create app with CLI
+---
+
+
+
+Project Rayfin is a modern **Backend-as-a-Service (BaaS)** platform that helps teams build and ship applications faster.
+It provides ready-to-use backend infrastructure so you can focus on the product experience.
+
+## Create an app from template
+
+Run `npm create @microsoft/rayfin@latest` in a terminal window and select welcome template for Typescript.
+
+## Run the app
+
+1. In a terminal window, run `npx rayfin up` to start the Rayfin backend.
+2. In a second terminal window run `npm run dev` to start the frontend.
+3. When the frontend starts, it will output the page to visit.
+Visit and ensure you can view the Timestamp Tracker.
+4. Click **Send Timestamp** to POST the current time to `/api/graphql/Timestamp`, then use **Refresh list** to pull back the newest 100 entries.
+5. All UI plus data-fetching logic lives in a single file: `src/main.ts`.
+6. To point at a different backend, set `RAYFIN_PUBLIC_API_URL` in `rayfin/.env` and re-run `npm run dev` (defaults to `http://localhost:5168`).
+
+## Update the data model
+
+Add a `message` field to the **Timestamp** entity in `rayfin/data/Timestamp.ts`.
+
+```typescript
+import { entity, authenticated, uuid, text, date } from '@microsoft/rayfin-core';
+
+@entity()
+@authenticated('*')
+export class Timestamp {
+  @uuid() id!: string;
+  @date() timestamp!: Date;
+  @text() message!: string;
+}
+```
+
+## Update the frontend to display the message
+
+In `src/main.ts`, update the creation and query to include the `message` field, add a table header, and display the message in the table rows.
+
+```typescript
+// 1. Update sendTimestamp to include message
+await this.rayfinClient.data.gql.Timestamp.create({
+  timestamp: now,
+  message: 'Hello from Rayfin!',  // Add this
+});
+
+// 2. Update the query to include 'message'
+const items = await this.rayfinClient.data.gql.Timestamp.select([
+  'id',
+  'timestamp',
+  'message',  // Add this
+]);
+
+// 3. Update the row template in the updateTable function
+const rows = this.timestamps
+  .map(
+    (entry) => `
+    <tr>
+      <td class="timestamp-mono">${entry.id}</td>
+      <td>${formatDate(entry.timestamp)}</td>
+      <td>${entry.message}</td>
+    </tr>
+  `
+  );
+
+// 4. Update the table headers in the updateTable function
+<thead>
+  <tr>
+    <th>ID</th>
+    <th>Timestamp</th>
+    <th>Message</th>
+  </tr>
+</thead>
+```
+
+## Apply database changes
+
+After updating your data models, apply the changes to your database.
+
+```bash
+npx rayfin up db apply
+```
+
+## Test your changes
+
+After updating your data models, test your app.
+
+```bash
+npm run dev
+```
+
+> NOTE: Any changes to `rayfin.yml` require you to run `npx rayfin up` again.
+
+## View your local database
+
+1. Identify your container name or ID for the database service.
+Use this command to list all running containers and note the name or ID of your database container.
+
+```bash
+docker ps
+```
+
+1. Access the container's shell and use the container name or ID for the database.
+
+```bash
+docker exec -it <container_name_or_id> bash
+```
+
+1. Once inside the container's shell, use the appropriate command for your database system.
+
+```bash
+psql -U RayfinDB
+```

package/assets/docs/getting-started/create-rayfin-item.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 4
+title: Create an App Backend
+---
+
+This guide walks through creating a new Fabric data app directly in the Microsoft Fabric portal.
+
+## Prerequisites
+
+- A Microsoft account with access to Microsoft Fabric.
+- A Fabric workspace where you have contributor or admin permissions.
+- Fabric data app enabled in your tenant admin settings (see below).
+
+## Enable Fabric data app in tenant admin settings
+
+A Fabric tenant administrator must enable the Fabric data app workload before users can create Rayfin items.
+If you are not a tenant admin, contact your organization's Fabric administrator to complete this step.
+
+1. Sign in to the [Fabric admin portal](https://app.fabric.microsoft.com/admin-portal).
+1. Navigate to **Tenant settings**.
+1. Under **Fabric Apps (preview)**, toggle the setting to **Enabled**.
+1. Choose whether to enable it for the entire organization or specific security groups.
+1. Click **Apply**.
+
+Changes may take a few minutes to propagate.
+Once enabled, users in the allowed scope can create Fabric data apps in their workspaces.
+
+## Step 1: Sign in to the Fabric portal
+
+Open [Microsoft Fabric](https://app.fabric.microsoft.com) in your browser and sign in with your Microsoft account.
+
+## Step 2: Select a workspace
+
+After signing in, select a workspace from the left navigation panel.
+If you do not have an existing workspace, create one:
+
+1. Click **Workspaces** in the left navigation.
+1. Click **New workspace**.
+1. Enter a name for the workspace and select Fabric capacity.
+
+## Step 3: Create a new Fabric data app
+
+1. In the workspace view, click **New item**.
+1. Search for **Fabric data app** in the item type list or scroll to find it.
+1. Select **Fabric data app** to open the creation dialog.
+1. Enter a name for your Fabric data app (for example, `my-rayfin-app`).
+1. Click **Create**.
+
+## Step 4: Open, edit, and deploy your app
+
+After creating the Fabric data app, open the project in VS Code and use GitHub Copilot to build your app.
+
+1. In the Fabric portal, click **Open in VS Code** on your newly created Fabric data app.
+   VS Code opens with the project files loaded.
+1. Use **GitHub Copilot** to make changes to your app.
+   For example, ask Copilot to add a new data model, create a UI component, or update your API endpoints.
+1. When you are ready to deploy, run the following command in the VS Code terminal:
+
+   ```bash
+   npx rayfin up
+   ```
+
+   You can also use the Command Palette and select **Project Rayfin: Up: Deploy to Fabric**.
+1. Once the deployment completes, Fabric provisions your app and displays the **App URL** in the terminal output.
+1. Click the **App URL** to open your deployed application in the browser and verify your changes.
+
+See [Deploy to Microsoft Fabric](../app-backend/deploy.md) to learn more about deployment options.
+
+## Next steps
+
+- Explore [Data Models & Decorators](../data/overview.md) to define your backend schema.
+- Learn how to connect frontends with the [GraphQL guide](../data/graphql.md).
+- Configure authentication with [Rayfin Auth](../auth/overview.md).