@microsoft/rayfin-guide 1.36.0-alpha.1593 → 1.36.0-alpha.1620

package/assets/docs/functions/connections/add-fabric-resource.md

@@ -0,0 +1,186 @@
+---
+sidebar_position: 2
+---
+
+# Add a Fabric resource
+
+Connect a function to a **Microsoft Fabric item** — a Lakehouse, Warehouse, SQL Database, OneLake files, or an Eventhouse (KQL) — and call it **as the signed-in user**.
+
+**Before you start:** you need the item's coordinates (SQL endpoint, OneLake path, or Kusto query URI). See [Get Fabric info](./get-fabric-info.md) for how to pull them from the Fabric REST API.
+
+All the patterns below follow the same model: declare the connection, read the token with `ctx.getToken()`, use it. See [Connecting to external resources](./index.md) for the shared model and the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper referenced here.
+
+## SQL databases
+
+Covers Fabric **Lakehouse** (SQL analytics endpoint), **Warehouse**, **SQL Database**, and **Mirrored Database**, using `AudienceType.Sql`. The same `AudienceType.Sql` connection also works for **Azure SQL Database** — use the Azure SQL server FQDN as `server` and the database name as `database` (no item GUID).
+
+- **Package:** `mssql@^12.6.0` (which pulls `tedious >= 19.2.2`). Older `tedious` (`<= 19.1.2`) has a LOGIN7 FeatureExt bug that causes "socket hang up" errors against Fabric endpoints.
+- **Encryption:** `encrypt: true` (not `'strict'`). This matches ODBC `Encrypt=yes`.
+- **Auth:** `azure-active-directory-access-token` with the token from `ctx.getToken(AudienceType.Sql)`.
+
+Install the driver in the functions project:
+
+```bash
+cd rayfin/functions
+npm install mssql@^12.6.0
+```
+
+| Resource               | What to pass as `server`                 | What to pass as `database`                 |
+| ---------------------- | ---------------------------------------- | ------------------------------------------ |
+| **Lakehouse**          | `sqlEndpointProperties.connectionString` | Item GUID (Initial Catalog — **required**) |
+| **Warehouse**          | `properties.connectionString`            | Item GUID                                  |
+| **SQL Database**       | `properties.serverFqdn`                  | `properties.databaseName`                  |
+| **Mirrored Database**  | SQL analytics endpoint                   | Item GUID                                  |
+| **Azure SQL Database** | Azure SQL server FQDN                    | Database name (no item GUID)               |
+
+> **Important:** For Lakehouse, Warehouse, and Mirrored Database you **must** pass the item GUID as `database`. Without it, multi-item workspaces cannot route the query correctly. Get these values via [Get Fabric info](./get-fabric-info.md).
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import sql from "mssql";
+
+const udf = new UserDataFunctions();
+
+// Read these from the Fabric item — see "Get Fabric info".
+const SQL_SERVER = "<endpoint>.datawarehouse.fabric.microsoft.com";
+const DATABASE = "<item-guid-or-db-name>";
+
+udf.func(
+  "queryData",
+  async (
+    ctx: RayfinContext,
+    query: string,
+  ): Promise<Record<string, unknown>[]> => {
+    const token = ctx.getToken(AudienceType.Sql);
+    const pool = await sql.connect({
+      server: SQL_SERVER,
+      database: DATABASE,
+      options: { encrypt: true, trustServerCertificate: false },
+      authentication: {
+        type: "azure-active-directory-access-token",
+        options: { token },
+      },
+    });
+    const result = await pool.request().query(query);
+    await pool.close();
+    return result.recordset;
+  },
+  [udf.connection({ audienceType: AudienceType.Sql })],
+);
+```
+
+## OneLake files
+
+Read and write files in a Lakehouse's OneLake storage using `AudienceType.Storage`.
+
+The OneLake DFS URL has the form `https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<itemId>/Files/<path>` — get it from `oneLakeFilesPath` via [Get Fabric info](./get-fabric-info.md#lakehouse), or construct it from the workspace and item GUIDs.
+
+Call the DFS endpoint directly with the delegated token — no SDK required:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "readFile",
+  async (ctx: RayfinContext, fileUrl: string): Promise<string> => {
+    const token = ctx.getToken(AudienceType.Storage);
+    const res = await fetch(fileUrl, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`OneLake read failed: ${res.status}`);
+    }
+    return await res.text();
+  },
+  [udf.connection({ audienceType: AudienceType.Storage })],
+);
+```
+
+## Eventhouse and KQL
+
+Query a Fabric **Eventhouse** (KQL database) or a standalone Azure Data Explorer cluster using `AudienceType.Kusto`.
+
+Get the cluster's **query URI** from the Eventhouse's `properties.queryServiceUri` — see [Get Fabric info → Eventhouse](./get-fabric-info.md#eventhouse).
+
+`azure-kusto-data` accepts a token provider, so hand it a callback that returns `ctx.getToken`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+import { Client, KustoConnectionStringBuilder } from "azure-kusto-data";
+
+const udf = new UserDataFunctions();
+
+// Read these from the Eventhouse item — see "Get Fabric info".
+const CLUSTER_URI = "https://<cluster>.z5.kusto.fabric.microsoft.com";
+const DATABASE = "<kql-database-name>";
+
+udf.func(
+  "queryKusto",
+  async (ctx: RayfinContext, query: string): Promise<unknown[]> => {
+    const kcsb = KustoConnectionStringBuilder.withTokenProvider(
+      CLUSTER_URI,
+      async () => ctx.getToken(AudienceType.Kusto),
+    );
+    const client = new Client(kcsb);
+    const response = await client.execute(DATABASE, query);
+    return response.primaryResults[0].toJSON().data;
+  },
+  [udf.connection({ audienceType: AudienceType.Kusto })],
+);
+```
+
+Install the SDK in the functions project:
+
+```bash
+cd rayfin/functions
+npm install azure-kusto-data
+```
+
+## Fabric REST API
+
+Call the [Fabric REST API](https://learn.microsoft.com/en-us/rest/api/fabric/) as the calling user — for example to list items or read item metadata from inside a function — using `AudienceType.Fabric`.
+
+The API base is fixed at `https://api.fabric.microsoft.com/v1`; `ctx.getToken(AudienceType.Fabric)` returns a token scoped for it. Send it as a bearer token with `fetch`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+const FABRIC_API = "https://api.fabric.microsoft.com/v1";
+
+udf.func(
+  "listWorkspaceItems",
+  async (ctx: RayfinContext, workspaceId: string): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.Fabric);
+    const res = await fetch(`${FABRIC_API}/workspaces/${workspaceId}/items`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`Fabric API returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.Fabric })],
+);
+```
+
+> This is the same API used in [Get Fabric info](./get-fabric-info.md) — the difference is that there you call it at **authoring time** (with an `az` token) to gather endpoints, whereas here the **function** calls it at runtime with the user's delegated token.

package/assets/docs/functions/connections/add-foundry.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 4
+---
+
+# Add Azure AI Foundry
+
+Call an **Azure AI Foundry** (Azure OpenAI / Azure AI) resource from a function **as the signed-in user**, using `AudienceType.AzureAI`.
+
+Provide the resource **endpoint** (Azure AI Foundry → your resource → _Endpoint_). The token is a standard bearer token — send it with `fetch`, or wrap it with the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper for an Azure AI SDK client.
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+// Use your resource's real endpoint.
+const AI_ENDPOINT = "https://<resource>.services.ai.azure.com";
+
+udf.func(
+  "callAzureAi",
+  async (ctx: RayfinContext, prompt: string): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.AzureAI);
+    const res = await fetch(`${AI_ENDPOINT}/...`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ prompt }),
+    });
+    if (!res.ok) {
+      throw new Error(`Azure AI returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.AzureAI })],
+);
+```
+
+Fill in the request path and body from the specific Azure AI API you are calling.
+
+See [Connecting to external resources](./index.md) for the shared connection model.

package/assets/docs/functions/connections/add-work-iq.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 6
+---
+
+# Add WorkIQ
+
+Call the **WorkIQ** service from a function **as the signed-in user**, using `AudienceType.WorkIQ`.
+
+Provide the **WorkIQ endpoint** you are calling. The token is a standard bearer token — send it with `fetch`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+// Use your real WorkIQ endpoint.
+const WORKIQ_ENDPOINT = "https://workiq.svc.cloud.microsoft/...";
+
+udf.func(
+  "callWorkIq",
+  async (ctx: RayfinContext): Promise<unknown> => {
+    const token = ctx.getToken(AudienceType.WorkIQ);
+    const res = await fetch(WORKIQ_ENDPOINT, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+      throw new Error(`WorkIQ returned ${res.status}`);
+    }
+    return res.json();
+  },
+  [udf.connection({ audienceType: AudienceType.WorkIQ })],
+);
+```
+
+See [Connecting to external resources](./index.md) for the shared connection model.

package/assets/docs/functions/connections/get-fabric-info.md

@@ -0,0 +1,159 @@
+---
+sidebar_position: 1
+---
+
+# Finding resource coordinates
+
+Every connection recipe needs a real endpoint — the SQL server, the OneLake path, the Key Vault URI, the Kusto query URI, and so on.
+This page explains **how to obtain those values from a Fabric item** so you (or an agent authoring a function) can fill them in with real data instead of guessing.
+
+**You only need the workspace and item _display names_ to start** — for example, "lakehouseA in workspaceB". Everything else (the workspace ID, item ID, SQL endpoint, OneLake path, Kusto URI) is derivable from here. Resolve those values rather than asking for anything you can look up.
+
+> **Why this matters:** don't hardcode a guessed endpoint. `ctx.getToken()` gives you an access token, but you still have to point the SDK at the correct URL — and that URL comes from the Fabric item's metadata, not from `process.env`.
+
+## Ways to get coordinates
+
+| Source                      | Best for                                                   | Notes                                                                               |
+| --------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| **Fabric CLI** (e.g. `fab`) | Anyone who already has a Fabric CLI installed              | Wraps the REST API below. If you're already using a Fabric CLI, reach for it first. |
+| **Fabric MCP server**       | Agents running in an MCP-enabled environment               | If a Fabric MCP is configured, its tools wrap the same REST endpoints below.        |
+| **Fabric REST API**         | Automation, agents, reproducible lookups; no extra tooling | Canonical source. Returns endpoints/paths directly. Covered below.                  |
+| **Fabric portal**           | One-off manual lookups                                     | Open the item → **Settings** / **Connection strings** and copy the value.           |
+
+If a Fabric CLI or MCP tool is already available, prefer it — it wraps the same REST endpoints. Otherwise call the REST API directly; the portal is the fallback for a quick manual copy. The rest of this page uses the REST API, since that is the source of truth every other option wraps.
+
+## Calling the Fabric REST API
+
+- **Base URL:** `https://api.fabric.microsoft.com/v1`
+- **Token scope:** `https://api.fabric.microsoft.com/.default`
+- **Auth header:** `Authorization: Bearer <token>`
+
+Get a token at authoring time with the Azure CLI:
+
+```bash
+az account get-access-token \
+  --resource https://api.fabric.microsoft.com \
+  --query accessToken -o tsv
+```
+
+> This is an **authoring-time** lookup — you are gathering coordinates to write into the function. At **runtime** the function itself uses `ctx.getToken(AudienceType.X)` (or, for the Fabric API specifically, `ctx.getToken(AudienceType.Fabric)` — see [Add a Fabric resource → Fabric REST API](./add-fabric-resource.md#fabric-rest-api)).
+
+## Step 1 — find the workspace and item ID
+
+List workspaces you can access:
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces
+```
+
+List items of a given type in a workspace (to resolve a display name to its ID):
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/items?type=Lakehouse
+```
+
+`type` accepts any Fabric item type — `Lakehouse`, `Warehouse`, `SQLDatabase`, `Eventhouse`, `KQLDatabase`, and so on.
+Each entry returns `id`, `displayName`, and `type`. Take the `id` of the item you want.
+
+## Step 2 — GET the item to read its coordinates
+
+Each item type has a typed endpoint that returns the connection coordinates in its `properties` object.
+
+### Lakehouse
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/lakehouses/{lakehouseId}
+```
+
+```json
+{
+  "id": "5b218778-e7a5-4d73-8187-f10824047715",
+  "type": "Lakehouse",
+  "properties": {
+    "oneLakeTablesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{itemId}/Tables",
+    "oneLakeFilesPath": "https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{itemId}/Files",
+    "sqlEndpointProperties": {
+      "connectionString": "xxxxx.datawarehouse.fabric.microsoft.com",
+      "id": "37dc8a41-dea9-465d-b528-3e95043b2356",
+      "provisioningStatus": "Success"
+    }
+  }
+}
+```
+
+- **SQL analytics endpoint** → `properties.sqlEndpointProperties.connectionString` (the server for [SQL databases](./add-fabric-resource.md#sql-databases); use the lakehouse item GUID as `database`).
+- **OneLake Files / Tables** → `properties.oneLakeFilesPath` / `oneLakeTablesPath` (the DFS URLs for [OneLake files](./add-fabric-resource.md#onelake-files)).
+
+### Warehouse
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/warehouses/{warehouseId}
+```
+
+```json
+{
+  "type": "Warehouse",
+  "properties": {
+    "connectionString": "xxxxx.datawarehouse.fabric.microsoft.com"
+  }
+}
+```
+
+- **SQL server** → `properties.connectionString`. Use with [SQL databases](./add-fabric-resource.md#sql-databases); the warehouse item GUID is the `database`.
+
+### SQL Database
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/sqlDatabases/{sqlDatabaseId}
+```
+
+```json
+{
+  "type": "SQLDatabase",
+  "properties": {
+    "connectionString": "Data Source=xxxxx.database.fabric.microsoft.com,1433;Initial Catalog=SQLDatabase1-<guid>;Encrypt=True;TrustServerCertificate=False",
+    "databaseName": "SQLDatabase1-<guid>",
+    "serverFqdn": "xxxxx.database.fabric.microsoft.com,1433"
+  }
+}
+```
+
+- **Server** → `properties.serverFqdn`, **database** → `properties.databaseName`. Both are also embedded in `properties.connectionString`.
+
+### Eventhouse
+
+```http
+GET https://api.fabric.microsoft.com/v1/workspaces/{workspaceId}/eventhouses/{eventhouseId}
+```
+
+```json
+{
+  "type": "Eventhouse",
+  "properties": {
+    "queryServiceUri": "https://xxxxx.z5.kusto.fabric.microsoft.com",
+    "ingestionServiceUri": "https://ingest-xxxxx.z5.kusto.fabric.microsoft.com",
+    "databasesItemIds": ["<kql-database-item-id>"]
+  }
+}
+```
+
+- **Cluster / query URI** → `properties.queryServiceUri`. Use with [Eventhouse and KQL](./add-fabric-resource.md#eventhouse-and-kql). Each KQL database inside the eventhouse is listed in `databasesItemIds`.
+
+## Coordinate lookup table
+
+| You need                       | Item type    | Endpoint                | Field                                               |
+| ------------------------------ | ------------ | ----------------------- | --------------------------------------------------- |
+| SQL server (Lakehouse)         | Lakehouse    | `.../lakehouses/{id}`   | `properties.sqlEndpointProperties.connectionString` |
+| SQL server (Warehouse)         | Warehouse    | `.../warehouses/{id}`   | `properties.connectionString`                       |
+| SQL server + database (SQL DB) | SQL Database | `.../sqlDatabases/{id}` | `properties.serverFqdn` / `properties.databaseName` |
+| OneLake Files / Tables URL     | Lakehouse    | `.../lakehouses/{id}`   | `properties.oneLakeFilesPath` / `oneLakeTablesPath` |
+| Kusto query URI                | Eventhouse   | `.../eventhouses/{id}`  | `properties.queryServiceUri`                        |
+| Item GUID (any item)           | any          | `.../items?type={Type}` | `id`                                                |
+
+For item types not listed here, browse the [Fabric REST API item reference](https://learn.microsoft.com/en-us/rest/api/fabric/) — each item's **Get** operation returns its coordinates under `properties`.
+
+## Notes
+
+- **OneLake paths are constructable.** Every OneLake path follows `https://onelake.dfs.fabric.microsoft.com/{workspaceId}/{itemId}/Files/...` — if you already have the workspace and item GUIDs you can build the URL without a lookup.
+- **The item GUID is the `database` for SQL.** Fabric Lakehouse/Warehouse queries route by item GUID, not display name — see [SQL databases](./add-fabric-resource.md#sql-databases).
+- **Read permission required.** The `Get` endpoints need `Item.Read.All` (or the item-specific read scope) on the delegated token. If a lookup 403s, the signed-in user lacks read access to that item.

package/assets/docs/functions/connections/index.md

@@ -0,0 +1,89 @@
+---
+sidebar_position: 5
+---
+
+# Connecting to external resources
+
+Functions can call external Azure and Fabric resources **as the calling user** using delegated authentication.
+You declare a connection on the function, and at invocation time the runtime exchanges the user's identity for a resource-scoped on-behalf-of (OBO) token.
+
+## The pattern
+
+Declare an audience-scoped connection in the third argument of `udf.func()`, then read its token with `ctx.getToken()`:
+
+```ts
+import {
+  UserDataFunctions,
+  AudienceType,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "myFunction",
+  async (ctx: RayfinContext): Promise<string> => {
+    const token = ctx.getToken(AudienceType.KeyVault);
+    // Use `token` with the resource's SDK or REST API.
+    return "ok";
+  },
+  [udf.connection({ audienceType: AudienceType.KeyVault })],
+);
+```
+
+- `udf.connection({ audienceType })` declares the delegated connection.
+- `ctx.getToken(audienceType)` returns the OBO access token as a `string`. It throws if no connection was declared for that audience.
+- The connection declaration is what makes the token available — declaring the audience and calling `getToken` with the same audience always go together.
+
+## Wrapping the token for Azure SDK clients
+
+Many Azure SDK clients expect a `TokenCredential` rather than a raw token string.
+Define a small adapter that returns the token from the context:
+
+```ts
+import type { TokenCredential, AccessToken } from "@azure/identity";
+
+class ContextTokenCredential implements TokenCredential {
+  constructor(private readonly token: string) {}
+  async getToken(): Promise<AccessToken> {
+    return { token: this.token, expiresOnTimestamp: Date.now() + 3600_000 };
+  }
+}
+```
+
+Pass `new ContextTokenCredential(ctx.getToken(AudienceType.X))` wherever an Azure SDK client asks for a credential.
+The per-resource guides below use this helper.
+
+## Choose a recipe
+
+Find what you want to connect to. Each row links to a task-oriented walkthrough; the `AudienceType` is the value you pass to `udf.connection()` and `ctx.getToken()`. A single audience can back more than one use case (for example `Storage` covers both Fabric OneLake and Azure Blob).
+
+| I want to connect to…                            | `AudienceType` | Recipe                                                               |
+| ------------------------------------------------ | -------------- | -------------------------------------------------------------------- |
+| Fabric Lakehouse / Warehouse / SQL DB / Mirrored | `Sql`          | [Add a Fabric resource](./add-fabric-resource.md#sql-databases)      |
+| Azure SQL Database                               | `Sql`          | [Add a Fabric resource](./add-fabric-resource.md#sql-databases)      |
+| Fabric OneLake files                             | `Storage`      | [Add a Fabric resource](./add-fabric-resource.md#onelake-files)      |
+| Azure Blob / Table / Queue                       | `Storage`      | [Add an Azure resource](./add-azure-resource.md#blob-storage)        |
+| Fabric Eventhouse (KQL)                          | `Kusto`        | [Add a Fabric resource](./add-fabric-resource.md#eventhouse-and-kql) |
+| Azure Data Explorer                              | `Kusto`        | [Add a Fabric resource](./add-fabric-resource.md#eventhouse-and-kql) |
+| Microsoft Fabric REST API                        | `Fabric`       | [Add a Fabric resource](./add-fabric-resource.md#fabric-rest-api)    |
+| Azure Key Vault                                  | `KeyVault`     | [Add an Azure resource](./add-azure-resource.md#key-vault)           |
+| Azure Cosmos DB                                  | `CosmosDB`     | [Add an Azure resource](./add-azure-resource.md#cosmos-db)           |
+| Azure Event Grid                                 | `EventGrid`    | [Add an Azure resource](./add-azure-resource.md#event-grid)          |
+| Azure AI Foundry                                 | `AzureAI`      | [Add Azure AI Foundry](./add-foundry.md)                             |
+| Azure DevOps                                     | `ADO`          | [Add Azure DevOps](./add-ado.md)                                     |
+| WorkIQ                                           | `WorkIQ`       | [Add WorkIQ](./add-work-iq.md)                                       |
+
+To look up a Fabric item's connection coordinates (SQL endpoint, OneLake path, Kusto query URI), see [Get Fabric info](./get-fabric-info.md).
+
+## Rules
+
+- **Use real endpoint URLs** — don't hardcode a guess or read them from `process.env`. For Fabric items, [Get Fabric info](./get-fabric-info.md) shows how to look them up.
+- Declare every connection in the third argument to `udf.func()`.
+- Use `ctx.getToken(AudienceType.X)` — never acquire tokens manually.
+- Install resource SDK packages in `rayfin/functions/package.json`, not the project root.
+
+## Local development
+
+When you run `npx rayfin dev functions apply`, the local host acquires delegated tokens interactively for debugging, so `ctx.getToken()` works against your declared audiences without a deployment.
+See [`npx rayfin dev functions apply`](../../cli/functions/dev-apply.md).

package/assets/docs/functions/index.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 35
+---
+
+# Functions
+
+Rayfin functions are server-side user-defined functions (UDFs) that run in the Fabric runtime and are invocable from your frontend through `RayfinClient`.
+Write trusted backend logic once, get a type-safe client call on the frontend.
+
+## When to use functions
+
+Reach for a function whenever logic should run on the backend rather than in the browser:
+
+- **Sensitive operations** — code that touches secrets, API keys, or privileged data access.
+- **Business logic that must not be tampered with** — anything you would not want a user to inspect or modify in client code.
+- **Server-side validation** — enforce rules that a malicious client could otherwise bypass.
+- **Aggregation and transformation** — shape or combine data before returning it to the client.
+
+If a frontend feature needs trusted server-side behavior, implement it as a function.
+
+## Getting started
+
+Scaffold the functions project with the CLI:
+
+```bash
+npx rayfin functions init
+```
+
+This creates `rayfin/functions/`, installs dependencies, and generates the initial `types.ts`.
+See [`npx rayfin functions init`](../cli/functions/init.md) for the full command reference.
+
+## Project structure
+
+After `npx rayfin functions init`, the functions project lives at `rayfin/functions/`:
+
+```text
+rayfin/
+├── data/                 ← entity classes (shared via TS project references)
+└── functions/
+    ├── src/
+    │   ├── function_app.ts   ← register your functions here
+    │   └── types.ts          ← auto-generated schema (do not edit)
+    ├── package.json
+    ├── tsconfig.json         ← references: [{ "path": ".." }]
+    ├── host.json
+    └── local.settings.json   ← local-only settings (git-ignored)
+```
+
+`tsconfig.json` uses `composite: true` with a project reference to `rayfin/`, so functions can `import type` from your data entities without duplicating definitions.
+
+## Your first function
+
+The scaffold seeds `src/function_app.ts` with a simple example:
+
+```ts
+import { UserDataFunctions } from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "helloWorld",
+  (firstName: string, lastName: string): string => {
+    console.log(`helloWorld invoked for ${firstName} ${lastName}`);
+    return `Hello ${firstName} ${lastName}!`;
+  },
+  [],
+);
+```
+
+The handler's parameter and return types are read by typegen and written into `types.ts` so the frontend can call `client.functions.helloWorld.invoke({ firstName, lastName })` with full type safety.
+
+## The development loop
+
+For local development, prefer `npx rayfin dev`; it starts the frontend and functions together automatically.
+To iterate on functions **without** starting the frontend static app, run only the function host:
+
+```bash
+npx rayfin dev functions apply
+```
+
+This starts a local function host, keeps a typegen watcher running, and publishes its URL for local frontend routing.
+Bundled Vite apps use the same-origin `/.rayfin/api/<name>` route when you run the frontend separately.
+See [`npx rayfin dev functions apply`](../cli/functions/dev-apply.md) for details.
+
+## Next steps
+
+- [Writing functions](./writing-functions.md) — the `udf.func()` API, `RayfinContext`, and data access.
+- [Type generation](./typegen.md) — how `types.ts` is generated and kept in sync.
+- [Connecting to external resources](./connections/index.md) — delegated access to SQL, Storage, Key Vault, and more.
+- [Secrets](./secrets.md) — reading secrets from inside a function.
+- [Invoking functions from the frontend](./invoking-from-frontend.md) — calling functions with `RayfinClient`.