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

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`.

package/assets/docs/functions/invoking-from-frontend.md

@@ -0,0 +1,94 @@
+---
+sidebar_position: 4
+---
+
+# Invoking functions from the frontend
+
+Functions are called through `RayfinClient`. Pass your generated `AppFunctionsSchema` as the client's second type argument so every call is type-checked.
+
+```ts
+import { RayfinClient } from "@microsoft/rayfin-client";
+import type { AppSchema } from "../rayfin/data/schema";
+import type { AppFunctionsSchema } from "../rayfin/functions/src/types.js";
+
+const client = new RayfinClient<AppSchema, AppFunctionsSchema>({
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+});
+
+// Type-safe: parameters and return type are checked against the schema.
+const greeting = await client.functions.greet.invoke({
+  firstName: "Jane",
+  lastName: "Doe",
+});
+
+// For functions whose only parameter is RayfinContext, the input is `Record<string, never>`:
+const entries = await client.functions.getEntries.invoke();
+```
+
+The exact import path for `AppFunctionsSchema` depends on where your frontend lives relative to `rayfin/functions/src/types.ts`.
+
+## Invocation behavior
+
+- `invoke()` resolves to the function's output directly (typed as the schema's `output`) — not an envelope. By the time it resolves you can use the value without checking for `undefined`.
+- On failure it **throws**: a non-empty `errors` array or a non-success status becomes a `FunctionsError`; network problems surface as a `NetworkError`.
+- The server-side `invocationId` is emitted via `console.debug` for correlation with backend telemetry.
+
+### Per-call options
+
+Options always go in the **second** argument slot; the first argument is always the input:
+
+```ts
+// Input function with a per-call timeout:
+await client.functions.longRunning.invoke(params, { timeoutMs: 5_000 });
+
+// No-input function — pass `undefined` first, then options:
+await client.functions.ping.invoke(undefined, { timeoutMs: 5_000 });
+```
+
+`timeoutMs` is clamped to the Fabric UDF host ceiling of 250 seconds (`FUNCTIONS_INVOKE_TIMEOUT_MS`), since the host aborts any invocation at that limit regardless of the client value.
+
+## Local development
+
+By default, invocations route to your deployed backend.
+Bundled Vite templates use `@microsoft/rayfin-local-dev` to keep local function calls on the frontend origin.
+During `vite serve`, the client calls `/.rayfin/api/<name>` and the adapter forwards the request to the exact Functions host selected by `npx rayfin dev`.
+
+For a custom or older Vite project, install the adapter:
+
+```bash
+npm install @microsoft/rayfin-local-dev
+```
+
+Register it in `vite.config.ts`:
+
+```ts
+import { rayfinLocalDev } from "@microsoft/rayfin-local-dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [rayfinLocalDev()],
+});
+```
+
+Then resolve the local base URL when you create the client:
+
+```ts
+import { resolveRayfinFunctionsBaseUrl } from "@microsoft/rayfin-local-dev";
+
+const client = new RayfinClient<AppSchema, AppFunctionsSchema>({
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+  functionsBaseUrl: resolveRayfinFunctionsBaseUrl(),
+});
+```
+
+The helper returns an absolute `/.rayfin` URL on the current browser origin only when the Vite adapter has registered local Functions routing.
+In production it returns `undefined`, so calls use the deployed Fabric backend.
+If the local Functions host becomes unavailable while the adapter is active, the proxy returns HTTP 502 instead of falling back to deployed function code.
+The proxy is reachable wherever the Vite development server is reachable, so keep Vite bound to loopback or restrict its `host` and `allowedHosts` settings to a trusted development network.
+
+`npx rayfin dev` starts the frontend and Functions host together and supplies the selected Functions URL to the adapter.
+`npx rayfin dev functions apply` starts only the Functions host; start your Vite frontend separately to use the same-origin route.
+See [`npx rayfin dev functions apply`](../cli/functions/dev-apply.md) for the local debugging workflow.
+
+For frameworks other than Vite, pass the framework-mapped Functions URL directly during development and leave `functionsBaseUrl` undefined in production.
+For example, use `NEXT_PUBLIC_RAYFIN_FUNCTIONS_URL` with an explicit development guard in Next.js.

package/assets/docs/functions/secrets.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 3
+---
+
+# Secrets
+
+Functions read secret values through `ctx.getSecret(name)` on [`RayfinContext`](./writing-functions.md#rayfincontext-api).
+
+```ts
+import {
+  UserDataFunctions,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "readApiKey",
+  async (ctx: RayfinContext): Promise<string> => {
+    const apiKey = ctx.getSecret("THIRD_PARTY_API_KEY");
+    if (!apiKey) {
+      throw new Error("Missing THIRD_PARTY_API_KEY secret.");
+    }
+    return apiKey;
+  },
+  [],
+);
+```
+
+## How resolution works
+
+`ctx.getSecret(name)` returns `string | undefined`. It resolves in this order:
+
+1. The host-provided secret bag delivered with the invocation.
+2. `process.env[name]` as a fallback.
+
+## Setting secrets
+
+Manage project secrets with the CLI:
+
+```bash
+npx rayfin secret set THIRD_PARTY_API_KEY
+```
+
+These are stored against your deployment and delivered to the function at invocation time.
+See [Managing secrets](../cli/secrets.md) for the full `npx rayfin secret` command group.
+
+## Secrets in local development
+
+The host-provided secret bag is only present for deployed invocations.
+When you debug locally with `npx rayfin dev functions apply`, add the same key under `Values` in `rayfin/functions/local.settings.json` so it flows into `process.env` and is picked up by the `getSecret` fallback:
+
+```jsonc
+{
+  "IsEncrypted": false,
+  "Values": {
+    "AzureWebJobsStorage": "",
+    "FUNCTIONS_WORKER_RUNTIME": "node",
+    "THIRD_PARTY_API_KEY": "local-development-value",
+  },
+}
+```
+
+`local.settings.json` is git-ignored, so these values stay on your machine.
+See [Secrets in local development](../cli/secrets.md#using-secrets-in-local-development) for more.
+
+## Best practices
+
+- Prefer secrets set with `npx rayfin secret set <NAME>` as the source of truth for deployed functions.
+- Use the `process.env` fallback only for local debugging — do not make it your primary production secret source.

package/assets/docs/functions/typegen.md

@@ -0,0 +1,44 @@
+---
+sidebar_position: 2
+---
+
+# Type generation
+
+The Rayfin CLI parses every `udf.func()` call in `rayfin/functions/src/` and generates `rayfin/functions/src/types.ts`.
+That file exports an `AppFunctionsSchema` type mapping each function name to its input and output types.
+
+## The generated schema
+
+For the two functions shown in [Writing functions](./writing-functions.md), typegen emits:
+
+```ts
+export type AppFunctionsSchema = {
+  greet: {
+    input: { firstName: string; lastName: string };
+    output: string;
+  };
+  getEntries: {
+    input: Record<string, never>; // RayfinContext was stripped
+    output: { id: string; message: string }[];
+  };
+};
+```
+
+- Runtime-injected parameters such as `RayfinContext` are excluded from `input`.
+- `Promise<T>` return types are unwrapped to `T` in `output`.
+- The schema is a **closed** object type — only the listed function names are accepted by `client.functions.<name>.invoke(...)`.
+
+## When typegen runs
+
+| Command                          | Behavior                                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `npx rayfin functions init`      | Runs typegen once after scaffolding to seed `types.ts`.                                              |
+| `npx rayfin dev functions apply` | Runs typegen once at startup, then keeps a watcher running (prefixed `[typegen]`) until you stop it. |
+
+There is no standalone `typegen` command — it is driven by the commands above.
+See [`npx rayfin dev functions apply`](../cli/functions/dev-apply.md).
+
+## Rules
+
+- **Never hand-edit `types.ts`.** It is regenerated by `npx rayfin functions init` and by the watcher inside `npx rayfin dev functions apply`; your edits will be overwritten.
+- **Never import Node.js packages into `types.ts`.** It is resolved by the frontend app's TypeScript compiler, which cannot resolve Node built-ins.

package/assets/docs/functions/writing-functions.md

@@ -0,0 +1,140 @@
+---
+sidebar_position: 1
+---
+
+# Writing functions
+
+Functions are declared with the `UserDataFunctions` class from `@microsoft/fabric-user-data-functions` and registered with `udf.func()`.
+
+## Registering a function
+
+Create a single `UserDataFunctions` instance and register each function against it:
+
+```ts
+import { UserDataFunctions } from "@microsoft/fabric-user-data-functions";
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "greet",
+  (firstName: string, lastName: string): string => {
+    return `Hello ${firstName} ${lastName}!`;
+  },
+  [],
+);
+```
+
+`udf.func()` takes three arguments:
+
+| Argument      | Description                                                                                   |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `name`        | The function name. Becomes the invocation route and the key in your generated schema.         |
+| `fn`          | The handler. Its parameter and return types are read by [typegen](./typegen.md).              |
+| `connections` | Optional array of connection bindings. Pass `[]` when the function does not use a connection. |
+
+The handler's typed parameters and return type are extracted into `types.ts` so the frontend can call the function type-safely.
+`Promise<T>` return types are unwrapped to `T` in the generated schema.
+
+## Accessing data and request context
+
+To read your data, tokens, or logging from inside a function, declare a `RayfinContext` parameter.
+Pass your app schema as a generic (`RayfinContext<AppSchema>`) — the same schema you use with `RayfinClient<AppSchema>` — for a fully typed data client:
+
+```ts
+import {
+  UserDataFunctions,
+  type RayfinContext,
+} from "@microsoft/fabric-user-data-functions";
+
+type AppSchema = {
+  Entry: { id: string; message: string; createdAt: string };
+};
+
+const udf = new UserDataFunctions();
+
+udf.func(
+  "getEntries",
+  async (
+    ctx: RayfinContext<AppSchema>,
+  ): Promise<{ id: string; message: string }[]> => {
+    console.log("getEntries invoked");
+    const data = ctx.getDataClient();
+    return await data.Entry.select(["id", "message", "createdAt"]).execute();
+  },
+  [],
+);
+```
+
+### `RayfinContext` API
+
+| Member                       | Description                                                                                                                                                                                                                                                             |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.getDataClient()`        | Returns the typed entity data client. Query with `.select([...]).where(...).execute()`, the same chain as `client.data.<Entity>` on the frontend. Typed when a generic is supplied; untyped (`Record<string, any>`) otherwise.                                          |
+| `ctx.getSecret(name)`        | Returns a secret value, or `undefined` when unset. See [Secrets](./secrets.md).                                                                                                                                                                                         |
+| `ctx.getToken(audienceType)` | Returns the delegated OBO access token (a `string`) for an external resource. Only works for an audience you declared with `udf.connection({ audienceType })` in the third argument — throws otherwise. See [Connecting to external resources](./connections/index.md). |
+| `ctx.baseUrl`                | The Rayfin endpoint URL (readonly).                                                                                                                                                                                                                                     |
+| `ctx.accessToken`            | The auth token for the current request (readonly).                                                                                                                                                                                                                      |
+| `ctx.publishableKey`         | The Rayfin publishable key (readonly).                                                                                                                                                                                                                                  |
+
+Use `console.log(...)` / `console.error(...)` for logging.
+
+> **Import `RayfinContext` from `@microsoft/fabric-user-data-functions`** — not from `@microsoft/rayfin-functions`.
+
+## Mixing parameters and context
+
+A handler can take normal input parameters alongside a `RayfinContext`:
+
+```ts
+udf.func(
+  "addEntry",
+  async (message: string, ctx: RayfinContext<AppSchema>): Promise<void> => {
+    console.log("addEntry invoked");
+    const data = ctx.getDataClient();
+    await data.Entry.create({ message });
+  },
+  [],
+);
+```
+
+`RayfinContext` is injected by the runtime, so typegen strips it from the generated input type — only `message: string` appears in the schema for `addEntry`.
+
+## Connecting to external resources
+
+To call external Azure or Fabric resources (SQL, Storage, Key Vault, Cosmos DB, and more) from inside a function, declare a connection in the third argument of `udf.func()` and read a delegated token from the context:
+
+```ts
+import { AudienceType } from "@microsoft/fabric-user-data-functions";
+
+udf.func(
+  "readSecret",
+  async (ctx: RayfinContext, secretName: string): Promise<string> => {
+    const token = ctx.getToken(AudienceType.KeyVault);
+    // Use `token` with the resource's SDK or REST API.
+    return secretName;
+  },
+  [udf.connection({ audienceType: AudienceType.KeyVault })],
+);
+```
+
+The runtime exchanges the caller's identity for a resource-scoped token, so the function acts **as the calling user**.
+See [Connecting to external resources](./connections/index.md) for the full model, the list of supported audiences, and per-resource guides.
+
+## Importing data entities
+
+Share entity types between your data models and functions with TypeScript project references:
+
+```ts
+import type { Entry } from "../../data/Entry.js";
+```
+
+- Use `import type` — entity classes are only needed for their type shape, not their runtime value. A non-type import would pull the decorator runtime into the functions bundle.
+- The `../../data/` path resolves because `tsconfig.json` sets `"references": [{ "path": ".." }]`.
+- Always use the `.js` extension on relative imports for correct ESM resolution.
+
+## Rules
+
+- Always register functions with `udf.func(name, handler, [])` — do not export bare functions.
+- Use `RayfinContext<AppSchema>` for type-safe data access. Bare `RayfinContext` still works but gives no type safety on `getDataClient()`.
+- Only call `ctx.getToken(audienceType)` for an audience you declared with `udf.connection({ audienceType })` in the third argument of `udf.func()` — calling it for an undeclared audience throws.
+- A function must return a value or `void`. Throwing an error surfaces to the caller as an invocation failure carrying the error message.
+- Use `import type` for data entity imports; never a runtime `import`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.36.0-alpha.1593",
+  "version": "1.36.0-alpha.1601",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [