@microsoft/rayfin-guide 1.36.0-alpha.1756 → 1.36.0-alpha.1818

package/assets/docs/app-backend/deploy.md

@@ -62,6 +62,41 @@ npx rayfin up
 
 If you are not signed in, the CLI launches an interactive login flow automatically.
 
+### Prepare Fabric capacity
+
+Before creating the Rayfin item, `rayfin up` checks whether the target workspace already has Fabric capacity.
+If the workspace reports an assigned capacity, Rayfin uses it without changing or reevaluating the assignment.
+
+On a first interactive deployment without a workspace target or `--capacity-id`, Rayfin asks you to choose:
+
+1. `Use new workspace [Recommended]` runs workspace and capacity readiness.
+2. `Select existing workspace` skips capacity readiness and opens the accessible-workspace picker.
+
+Explicit workspace options and recorded deployments continue directly to their existing targeting flow without showing this choice.
+Dry-run invocations do not show the choice.
+An interactive invocation with `--capacity-id <id>` automatically prepares a new workspace and assigns that capacity without showing the workspace choice.
+An untargeted non-interactive invocation automatically prepares a new workspace without prompting.
+Pass `--capacity-id <id>` to use a specific capacity for that new workspace.
+Pass an existing workspace target to deploy there instead.
+
+When the workspace needs capacity, an interactive deployment asks for confirmation before assigning the selected or trial capacity.
+Pass `--yes` to approve a deterministic capacity assignment without the prompt:
+
+```bash
+npx rayfin up --yes
+```
+
+To select a specific existing capacity, pass its Fabric capacity ID.
+This explicitly approves assigning that capacity:
+
+```bash
+npx rayfin up --capacity-id <capacity-guid>
+```
+
+Do not combine `--capacity-id` with `--workspace`, `--workspace-id`, or `--workspace-uri`.
+If multiple premium capacities are available, select one explicitly with `--capacity-id`.
+An existing recorded deployment keeps its current workspace capacity and ignores a newly supplied capacity ID.
+
 ### Choose a unique Fabric item name
 
 By default, `rayfin up` uses the project ID from `rayfin.yml` as the Fabric item name.
@@ -84,7 +119,7 @@ npx rayfin up \
   --output json
 ```
 
-Do not pass `--yes` unless reusing an existing same-named item is intentional.
+The `--yes` option also approves reuse of an existing same-named item, so use it only when both automatic capacity assignment and item reuse are acceptable.
 
 ### What `rayfin up` does
 

package/assets/docs/cli/connectors/add.md

@@ -28,6 +28,15 @@ If you do not already know the workspace and item IDs, run [`connector search`](
 | `-y, --yes`           | no           | Auto-accept overwrite and confirmation prompts (non-interactive).                                                                                                                                                       |
 | `-v, --verbose`       | no           | Verbose diagnostics.                                                                                                                                                                                                    |
 
+## Authentication
+
+`connector add` writes `auth.type: application` for Category A connectors: `fabric-sqlanalytics`, `fabric-warehouse`, and `fabric-sqldatabase`.
+The connector accesses the data source with the app's identity rather than the signed-in end user's identity.
+For per-user data-source access, explicitly set `auth.type: delegated` in `rayfin.yml` before deploying.
+
+Category B connectors continue to require `auth.type: delegated`.
+Existing declarations are not migrated, and omitting `auth.type` remains a validation error.
+
 ## Scoping operations
 
 Without `--operations`, `connector add` writes **every** operation the catalog allows for the type. Prefer scoping at add time over hand-editing YAML afterwards:
@@ -46,7 +55,7 @@ connectors:
       workspaceId: ${WS_ID}
       itemId: ${ITEM_ID}
     auth:
-      type: delegated
+      type: application
     operations:
       - name: read
       - name: update
@@ -97,6 +106,7 @@ With `--json`, the same information is available under `install`:
 
 Running `connector add` against a name already in `rayfin.yml` refreshes the declaration.
 It prompts before overwriting, or requires `--yes` when non-interactive.
+This rewrites `auth.type` to the catalog default, so reapply an explicit `delegated` setting for a Category A connector after re-adding it if needed.
 
 Your generated entity files under `rayfin/connectors/<name>/` are **preserved**.
 Only `metadata.json` is rewritten, by schema discovery.

package/assets/docs/cli/connectors/index.md

@@ -35,7 +35,7 @@ The commands available to a connector, and the code you write against it, depend
 
 |                                       | Category A — GraphQL entity connectors                                                                                                                                           | Category B — function-bridge connectors                |
 | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`, `fabric-graphql`                                                                                                | `fabric-semanticmodel`; `kusto` (**experimental**)      |
+| **Types**                             | `fabric-sqlanalytics`, `fabric-warehouse`, `fabric-sqldatabase`                                                                                                                  | `fabric-semanticmodel`; `kusto` (**experimental**)      |
 | **App surface**                       | Generated entity files with typed CRUD through the data client                                                                                                                   | Named operations carrying raw queries                  |
 | **Operations**                        | `read` only for `fabric-sqlanalytics` (Lakehouse SQL endpoints are read-only); `read`, `create`, `update`, `delete` for `fabric-warehouse` and `fabric-sqldatabase` (narrowable) | `executeQuery` only                                    |
 | **Auth**                              | `delegated` or configured per project                                                                                                                                            | Must be `delegated`                                    |

package/assets/docs/cli/connectors/inspect.md

@@ -54,11 +54,44 @@ Applies to `--entity` mode only.
 
 Applies to `--entity` and `--query` modes.
 
-- **SQL** — must start with `SELECT` or `WITH`; must be a single statement (a trailing `;` is fine, an embedded one is not); rejects `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `EXEC`/`EXECUTE`, and `INTO` anywhere outside a string literal.
+- **SQL** — must start with `SELECT` or `WITH`; an embedded `;` is rejected while a trailing `;` is allowed; rejects `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, `EXEC`/`EXECUTE`, and `INTO` anywhere outside a string literal.
+- **SQL result contract** — the query must produce one result set. If Tedious emits a second result set, inspection rejects the query instead of combining rows with a different column contract.
 - **DAX** — must start with `EVALUATE`.
 - `--query <path>` must resolve to a `.sql` or `.dax` file inside the project root; paths outside it are rejected. The project root is the directory containing `rayfin/rayfin.yml` when one is found. Direct mode (no `--name`) falls back to the current working directory if no `rayfin.yml` exists, so `--query` never requires a Rayfin project.
 - `--rows <n>` caps the sample size — maximum 100. The default is mode-specific: entity listing (neither `--entity` nor `--query`) defaults to **100**, while `--entity` and `--query` sampling default to **10**. The result reports `truncated: true` when the source had more rows than the cap; inspect fetches one row beyond the cap to detect that, then discards it.
 
+## SQL column types and values
+
+SQL inspection reads column types from Tedious result metadata, including when a query returns zero rows.
+It never guesses a column type from row values.
+Plain output lists each column as `name (type)` before populated or empty results.
+If the contract exceeds the terminal width, it folds between column entries.
+
+The `columns[].type` field in JSON uses this normalized vocabulary:
+
+| Normalized type    | Tedious metadata types                                                   |
+| ------------------ | ------------------------------------------------------------------------ |
+| `integer`          | `TinyInt`, `SmallInt`, `Int`, `BigInt`, `IntN`                          |
+| `decimal`          | `Decimal`, `Numeric`, money types, and their nullable forms              |
+| `floating-point`   | `Real`, `Float`, `FloatN`                                                |
+| `text`             | Character and Unicode text types, plus `Xml`                             |
+| `boolean`          | `Bit`, `BitN`                                                            |
+| `date`             | `Date`                                                                   |
+| `time`             | `Time`                                                                   |
+| `datetime`         | `SmallDateTime`, `DateTime`, `DateTimeN`, `DateTime2`, `DateTimeOffset` |
+| `uniqueidentifier` | `UniqueIdentifier`                                                       |
+| `binary`           | `Binary`, `VarBinary`, `Image`                                           |
+| `unknown`          | `Null`, `Variant`, `UDT`, `TVP`, and unrecognized or custom types       |
+
+Plain output renders SQL `date` values as `YYYY-MM-DD`, so the calendar value does not shift with the local time zone.
+SQL `time` values render as the UTC time portion `HH:mm:ss.sss`, without Tedious' internal 1970 date anchor.
+SQL `datetime` and `datetime2` are timezone-naive values that Tedious represents using a JavaScript `Date`; plain and JSON output therefore use an ISO value with `Z` by driver convention.
+SQL `datetimeoffset` is also returned as a JavaScript `Date`, so its original offset is not preserved.
+SQL `bigint` row values are strings, while decimal and numeric row values are JavaScript numbers and can carry JavaScript precision limitations.
+Binary and buffer-backed custom values render as terminal-safe `0x` hexadecimal in plain output and use the existing column-width truncation marker when needed.
+JSON row serialization is unchanged: JavaScript `Date` values remain ISO strings, while `columns[].type` now reports the metadata-derived normalized type instead of `unknown`.
+Queries that produce a second SQL result set are rejected when the driver emits its second column contract, including newline-separated batches without semicolons.
+
 ## Examples
 
 ```bash

package/assets/docs/cli/functions/deploy.md

@@ -14,6 +14,10 @@ npx rayfin up functions deploy [-v | --verbose] [--skip-build] [--json]
 
 `npx rayfin up` already deploys functions as part of a full deployment. Use `up functions deploy` when you want to run **only** the functions step — for example to retry after a functions deploy failed, or to push a functions-only change without redeploying the rest of the app.
 
+This standalone command uploads function code; it does not validate or apply `services.functions.auth.type` from YAML or migrate the remote Functions auth mode.
+After setting `services.functions.auth.type: application` for an existing app, run a full `npx rayfin up` to apply project settings.
+See [Application authentication](../../functions/index.md#application-authentication).
+
 ## Prerequisites
 
 Run `npx rayfin up` at least once first. This command deploys to an existing remote item, so a remote endpoint must already exist. If there is no active deployment, run a full `npx rayfin up`.
@@ -35,4 +39,4 @@ Run `npx rayfin up` at least once first. This command deploys to an existing rem
 
 - [`functions init`](./init.md) — scaffold and enable functions.
 - [`dev functions apply`](./dev-apply.md) — run and debug functions locally before deploying.
-- [Managing Secrets](../secrets.md) — push secrets that deployed functions read via `ctx.getSecret`.
+- [Managing Secrets](../secrets.md) — push secrets that deployed functions read via `ctx.Secrets`.

package/assets/docs/cli/functions/dev-apply.md

@@ -42,6 +42,11 @@ This command does not start the frontend.
 Run the Vite frontend separately to invoke local functions through `/.rayfin/api/<name>`, or use `npx rayfin dev` to start both together.
 If the local Functions host is unavailable, the Vite adapter returns HTTP 502 instead of invoking deployed function code.
 
+This standalone command does not validate or apply the project's Functions auth setting.
+Full `npx rayfin up` and normal `npx rayfin dev` perform that validation when applying project settings.
+Run a full `npx rayfin up` to apply [`services.functions.auth.type: application`](../../functions/index.md#application-authentication) to the remote app.
+For local token identity, see [Local development](../../functions/connections/index.md#local-development).
+
 ## Automatic recompilation
 
 Both `npx rayfin dev functions apply` and `npx rayfin dev` build the functions package once, then run its `build:watch` script alongside the local Functions host if the script is configured.
@@ -67,7 +72,7 @@ With debugging enabled (default), attach your debugger to the inspector port (`9
 
 ## Secrets in local development
 
-Locally there is no deployed secret bag, so `ctx.getSecret(name)` falls back to `process.env`. To provide a secret, add it under `Values` in `rayfin/functions/local.settings.json`; the functions host loads those entries into `process.env`. See [Managing Secrets](../secrets.md#using-secrets-in-local-development).
+Locally there is no deployed secret bag, so `ctx.Secrets.<NAME>` falls back to `process.env`. To provide a secret, add it under `Values` in `rayfin/functions/local.settings.json`; the functions host loads those entries into `process.env`. See [Managing Secrets](../secrets.md#using-secrets-in-local-development).
 
 ## Next step
 
@@ -80,3 +85,4 @@ npx rayfin up functions deploy
 ```
 
 See [`up functions deploy`](./deploy.md).
+The standalone deployment uploads function code; it does not apply YAML auth settings or migrate the remote Functions auth mode.

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

@@ -7,6 +7,8 @@ sidebar_position: 4
 Rayfin functions are server-side user-defined functions (UDFs) that run in the Fabric runtime and are invocable from your frontend through `RayfinClient`. Use them for logic that must run on the backend — secrets and API keys, privileged data access, server-side validation, and anything that should not be exposed or tampered with in client code.
 
 The functions project lives at `rayfin/functions/` and is enabled by the `services.functions.enabled` flag in `rayfin.yml` (set for you the first time you run [`functions init`](./init.md)).
+Enabled Functions also require explicit `services.functions.auth.type: application`, which new scaffolds set.
+See [Application authentication](../../functions/index.md#application-authentication) for existing-app configuration and downstream resource permissions.
 
 Each command has its own reference page:
 
@@ -34,8 +36,8 @@ functions init  →  write UDFs in src/function_app.ts  →  dev functions apply
 - `rayfin/functions/src/function_app.ts` — where you register UDFs with `udf.func()`.
 - `rayfin/functions/src/types.ts` — auto-generated `AppFunctionsSchema`; regenerated by `functions init` (one-shot) and by the watcher inside `dev functions apply`.
 - `rayfin/functions/{package.json,host.json,tsconfig.json,local.settings.json}` — the functions app manifest, host config, TypeScript project references, and local settings.
-- `rayfin.yml` — the `services.functions` block (`enabled`, `buildCommand`).
+- `rayfin.yml` — the `services.functions` block (`enabled`, `auth.type`, `buildCommand`).
 
 ## Secrets
 
-Functions read secrets at runtime with `ctx.getSecret(name)`, backed by the host secret bag with a `process.env` fallback. Manage remote secrets with `npx rayfin secret set` — or bulk-set them from a file with `npx rayfin secret set --env-file` — see [Managing Secrets](../secrets.md).
+Functions read secrets at runtime as typed properties on `ctx.Secrets`, backed by the host secret bag with a `process.env` fallback. Manage remote secrets with `npx rayfin secret set` — or bulk-set them from a file with `npx rayfin secret set --env-file` — see [Managing Secrets](../secrets.md).

package/assets/docs/cli/functions/init.md

@@ -24,12 +24,15 @@ Run this from a directory that already contains a `rayfin/` project (i.e. you ha
 ## What it does
 
 1. **Scaffolds** `rayfin/functions/` with a starter function app, `host.json`, `tsconfig.json`, `package.json`, and `local.settings.json`.
-2. **Enables the service** in `rayfin.yml` by setting `services.functions.enabled: true` and `services.functions.buildCommand: 'npm run build'`.
+2. **Enables the scaffolded service** in `rayfin.yml` by setting `services.functions.enabled: true`, `services.functions.auth.type: application`, and `services.functions.buildCommand: 'npm run build'`.
 3. **Installs dependencies** for the functions project.
 4. **Builds** the project.
 5. **Generates types** — runs a one-shot typegen to produce `rayfin/functions/src/types.ts` (the `AppFunctionsSchema`).
 6. **Installs AI agent files** so assistants understand the functions surface.
 
+Enabled Functions require explicit application authentication.
+For existing apps, see [Application authentication](../../functions/index.md#application-authentication) for the configuration and full-deployment requirement.
+
 ## Runtime version
 
 Fresh and forced scaffolds pin `@microsoft/fabric-user-data-functions` to the exact version of the running Rayfin CLI, matching connector scaffolding.
@@ -60,6 +63,9 @@ rayfin/
 - **Without `--force`** on an existing project, it preserves your `function_app.ts` and only refreshes dependencies, build, and generated types.
 - **With `--force`**, it overwrites the scaffold (a warning is shown before your files are replaced).
 
+Re-running without `--force` does not rewrite the existing Functions auth setting.
+Set `services.functions.auth.type: application` explicitly in an existing app rather than relying on a re-run to migrate it.
+
 ## Next step
 
 Start the local host and typegen watcher:

package/assets/docs/cli/index.md

@@ -89,7 +89,7 @@ Connectors let a Rayfin app read from — and, for some types, write to — Micr
 
 ### Secrets
 
-Secrets are encrypted values stored on your deployed Rayfin item and read at runtime — for example by [functions](./functions/index.md) via `ctx.getSecret`. See [Managing Secrets](./secrets.md) for the full guide.
+Secrets are encrypted values stored on your deployed Rayfin item and read at runtime — for example by [functions](./functions/index.md) via `ctx.Secrets`. See [Managing Secrets](./secrets.md) for the full guide.
 
 | Command | Description |
 | --- | --- |
@@ -129,18 +129,30 @@ export RAYFIN_TELEMETRY_OPTOUT=1
 
 ## Diagnostic logs
 
-`npx rayfin up` and workflow-based `npx rayfin dev` record detailed diagnostics under `~/.rayfin/logs/` even when `--verbose` is absent, including when using `--json` or `--output json`.
+`npx rayfin up`, workflow-based `npx rayfin dev`, and `npx rayfin dev functions apply` record detailed diagnostics under `~/.rayfin/logs/` even when `--verbose` is absent, including when using `--json` or `--output json`.
 After a failure, open the file identified by `Diagnostic log:` to inspect the original invocation without rerunning it.
 JSON failures include the same path in the `diagnosticLog` field of the single result object.
 `dev` JSON failures also include a `hint` with recovery guidance, including provider/configuration preflight errors and unexpected failures.
 
-Adding `--verbose` also mirrors diagnostic records to stderr while `up` or `dev` runs.
+Adding `--verbose` also mirrors diagnostic records to stderr while these commands run.
 The CLI rejects combining `--verbose` with `--json` or `--output json`; detailed diagnostics are still recorded in the log file without `--verbose`.
-This capability applies to workflow-based `up` and `dev` sessions, not standalone subcommands or Docker maintenance flags such as `dev --stop`.
-
-`dev` preserves normal frontend and Functions terminal output and flushes its log after cleanup on Ctrl-C, runtime failure, or normal completion.
+Other standalone subcommands and Docker maintenance flags such as `dev --stop` do not record these logs.
+
+Local Functions sessions show function endpoints, the debugger address, application output, and warnings or errors by default.
+Recognized host startup and configuration detail, HTTP request metadata, and successful initial build output are kept in diagnostics; use `--verbose` to mirror that detail to the terminal.
+When the initial build fails, human output includes a bounded tail of compiler output, and JSON errors include it in `buildOutput`.
+The tail retains up to 100 complete lines and 64 KiB, with an explicit marker when earlier output is omitted.
+Verbose mode does not replay the same compiler output a second time.
+Terminal output preserves stack-frame paths and line numbers, while masking credentials and email addresses.
+Application lines up to 16 KiB are preserved; oversized lines are replaced with an explicit truncation marker.
+Persistent diagnostic logs continue to apply their separate privacy and size limits.
+Failed HTTP responses show their status and, when request metadata is available, the method and path without query strings.
+Unrecognized output remains visible.
+Frontend output is unchanged.
+Both `dev` and `dev functions apply` flush their logs after cleanup on Ctrl-C, runtime failure, or normal completion.
 Piped runtime and build output is captured with a 1 MiB limit per stream.
-Interactive runtimes that inherit the terminal keep their keyboard and TTY behavior; their console output is not captured, and the log records that limitation alongside lifecycle events.
+Interactive Functions sessions keep standard input attached for keyboard interaction, while stdout and stderr are piped for filtering and diagnostic capture.
+Other interactive runtimes that inherit the terminal keep their keyboard and TTY behavior; their console output is not captured, and the log records that limitation alongside lifecycle events.
 
 Logs stay on your machine and are independent of telemetry opt-out.
 The log directory is shared across projects on your machine, so the retention limits below apply across all projects using it.

package/assets/docs/cli/secrets.md

@@ -4,7 +4,7 @@ sidebar_position: 50
 
 # Managing Secrets
 
-Secrets are encrypted values — API keys, connection strings, tokens — that your app needs at runtime but must never ship in client code. They are stored securely on your deployed Rayfin item and read on the server by [functions](./functions/index.md) via `ctx.getSecret(name)`.
+Secrets are encrypted values — API keys, connection strings, tokens — that your app needs at runtime but must never ship in client code. They are stored securely on your deployed Rayfin item and read on the server by [functions](./functions/index.md) via `ctx.Secrets`.
 
 Manage secrets with the `npx rayfin secret` command group:
 
@@ -105,18 +105,28 @@ Deleting a secret that does not exist reports a not-found error — run `npx ray
 
 ## Reading secrets from functions
 
-Server-side functions read secrets at runtime with `ctx.getSecret(name)`, which resolves against the deployed item's secret bag and falls back to `process.env`. Set a secret with `npx rayfin secret set <name>`, then read it by the same name inside your handler:
+Server-side functions read secrets at runtime as typed properties on `ctx.Secrets`, which resolve against the deployed item's secret bag and fall back to `process.env`. Set a secret with `npx rayfin secret set <name>`, then read it by the same name inside your handler:
 
 ```ts
-udf.func("summarize", async (ctx, input: { text: string }) => {
-  const apiKey = ctx.getSecret("OPENAI_KEY");
-  // ... call the API with apiKey
-});
+import { type RayfinContext } from "@microsoft/fabric-user-data-functions";
+
+udf.func(
+  "summarize",
+  async (ctx: RayfinContext<AppSchema>, input: { text: string }) => {
+    const apiKey = ctx.Secrets.OPENAI_KEY;
+    // ... call the API with apiKey
+  },
+  [],
+);
 ```
 
+The `RayfinContext<AppSchema>` annotation is what makes this type-safe. An unannotated `ctx` is contextually `any`, so `ctx.Secrets.OPENAI_KEY` compiles whether or not the secret is declared — and the annotation is also how typegen recognises the parameter as the injected context rather than a request-body argument.
+
+Setting the secret is what types it: the CLI regenerates `rayfin/functions/src/secrets.generated.ts`, so `ctx.Secrets.OPENAI_KEY` is a `string` and an undeclared name is a compile error. See [Secrets](../functions/secrets.md) for the full model.
+
 ## Using secrets in local development
 
-When you run functions locally with [`npx rayfin dev functions apply`](./functions/dev-apply.md), there is no deployed secret bag, so `ctx.getSecret(name)` falls back to `process.env`. To make a secret available locally, add it under `Values` in `rayfin/functions/local.settings.json` — the Azure Functions host loads those entries into `process.env`:
+When you run functions locally with [`npx rayfin dev functions apply`](./functions/dev-apply.md), there is no deployed secret bag, so `ctx.Secrets.<NAME>` falls back to `process.env`. To make a secret available locally, add it under `Values` in `rayfin/functions/local.settings.json` — the Azure Functions host loads those entries into `process.env`:
 
 ```json
 {
@@ -166,6 +176,6 @@ If `secret delete` reports the secret was not found:
 
 ## See also
 
-- [Functions](./functions/index.md) — read secrets from server-side functions with `ctx.getSecret`.
+- [Functions](./functions/index.md) — read secrets from server-side functions with `ctx.Secrets`.
 - [CLI quickstart](./quickstart.md)
 - [Environment configuration](./env-interpolation.md)

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

@@ -4,10 +4,14 @@ sidebar_position: 5
 
 # Add Azure DevOps
 
-Call the [Azure DevOps REST API](https://learn.microsoft.com/en-us/rest/api/azure/devops/) from a function **as the signed-in user**, using `AudienceType.ADO`.
+Call the [Azure DevOps REST API](https://learn.microsoft.com/en-us/rest/api/azure/devops/) from a deployed function using `AudienceType.ADO`.
+
+Grant the [application identity](../index.md#application-authentication) access to your Azure DevOps organization and the permissions required by the project or resource you call.
 
 Provide your Azure DevOps **organization** (and project, if the call needs one) — e.g. `https://dev.azure.com/<org>`. The token is a standard bearer token — send it with `fetch`:
 
+`AppSchema` below is your app's data schema — the same type you pass to `RayfinClient<AppSchema>`. See [Writing functions](../writing-functions.md#accessing-data-and-request-context).
+
 ```ts
 import {
   UserDataFunctions,
@@ -22,8 +26,8 @@ const ORG = "https://dev.azure.com/<org>";
 
 udf.func(
   "listProjects",
-  async (ctx: RayfinContext): Promise<unknown> => {
-    const token = ctx.getToken(AudienceType.ADO);
+  async (ctx: RayfinContext<AppSchema, AudienceType.ADO>): Promise<unknown> => {
+    const token = ctx.Tokens.ADO;
     const res = await fetch(`${ORG}/_apis/projects?api-version=7.1`, {
       headers: { Authorization: `Bearer ${token}` },
     });
@@ -32,7 +36,7 @@ udf.func(
     }
     return res.json();
   },
-  [udf.connection({ audienceType: AudienceType.ADO })],
+  [],
 );
 ```
 

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

@@ -4,58 +4,24 @@ sidebar_position: 3
 
 # Add an Azure resource
 
-Connect a function to an **Azure service** — Key Vault, Cosmos DB, Blob Storage, or Event Grid — and call it **as the signed-in user**.
+Connect a deployed function to **Azure Blob Storage**.
 
-These are Azure resources, not Fabric items, so their endpoints come from the **Azure portal** (there is no Fabric lookup). Each pattern declares the connection, reads the token with `ctx.getToken()`, and wraps it with the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper for the Azure SDK. See [Connecting to external resources](./index.md) for the shared model.
+Grant the [application identity](../index.md#application-authentication) the storage data permissions required by your operations.
 
-## Key Vault
+The storage account is an Azure resource, not a Fabric item, so its endpoint comes from the **Azure portal** (there is no Fabric lookup).
+The pattern declares the audience in the `RayfinContext` annotation, reads the token from `ctx.Tokens`, and wraps it with the [`ContextTokenCredential`](./index.md#wrapping-the-token-for-azure-sdk-clients) helper for the Azure SDK.
+See [Connecting to external resources](./index.md) for the shared model.
 
-Read secrets from Azure Key Vault using `AudienceType.KeyVault`.
+`AppSchema` below is your app's data schema — the same type you pass to `RayfinClient<AppSchema>`.
+See [Writing functions](../writing-functions.md#accessing-data-and-request-context).
 
-```bash
-cd rayfin/functions
-npm install @azure/keyvault-secrets @azure/identity
-```
-
-```ts
-import {
-  UserDataFunctions,
-  AudienceType,
-  type RayfinContext,
-} from "@microsoft/fabric-user-data-functions";
-import { SecretClient } from "@azure/keyvault-secrets";
-
-const udf = new UserDataFunctions();
-
-udf.func(
-  "getVaultSecret",
-  async (
-    ctx: RayfinContext,
-    kvUrl: string,
-    secretName: string,
-  ): Promise<string> => {
-    const credential = new ContextTokenCredential(
-      ctx.getToken(AudienceType.KeyVault),
-    );
-    const client = new SecretClient(kvUrl, credential);
-    const secret = await client.getSecret(secretName);
-    return secret.value ?? "";
-  },
-  [udf.connection({ audienceType: AudienceType.KeyVault })],
-);
-```
-
-Provide the vault URL (e.g. `https://my-vault.vault.azure.net/`).
-
-> To read secrets stored with Rayfin itself (rather than an external Key Vault), use [`ctx.getSecret()`](../secrets.md) instead — no connection required.
-
-## Cosmos DB
+## Blob Storage
 
-Connect to Azure Cosmos DB using `AudienceType.CosmosDB`. Pass the credential as `aadCredentials`:
+Connect to Azure Blob / Table / Queue storage using `AudienceType.Storage`:
 
 ```bash
 cd rayfin/functions
-npm install @azure/cosmos
+npm install @azure/storage-blob @azure/identity
 ```
 
 ```ts
@@ -64,53 +30,17 @@ import {
   AudienceType,
   type RayfinContext,
 } from "@microsoft/fabric-user-data-functions";
-import { CosmosClient } from "@azure/cosmos";
+import { BlobServiceClient } from "@azure/storage-blob";
 
 const udf = new UserDataFunctions();
 
-udf.func(
-  "readItems",
-  async (
-    ctx: RayfinContext,
-    endpoint: string,
-    databaseId: string,
-    containerId: string,
-  ): Promise<unknown[]> => {
-    const credential = new ContextTokenCredential(
-      ctx.getToken(AudienceType.CosmosDB),
-    );
-    const client = new CosmosClient({ endpoint, aadCredentials: credential });
-    const { resources } = await client
-      .database(databaseId)
-      .container(containerId)
-      .items.readAll()
-      .fetchAll();
-    return resources;
-  },
-  [udf.connection({ audienceType: AudienceType.CosmosDB })],
-);
-```
-
-Provide the account endpoint and the database / container names.
-
-## Blob Storage
-
-Connect to Azure Blob / Table / Queue storage using `AudienceType.Storage`:
-
-```bash
-cd rayfin/functions
-npm install @azure/storage-blob
-```
-
-```ts
-import { BlobServiceClient } from "@azure/storage-blob";
-
 udf.func(
   "listBlobs",
-  async (ctx: RayfinContext, accountUrl: string): Promise<string[]> => {
-    const credential = new ContextTokenCredential(
-      ctx.getToken(AudienceType.Storage),
-    );
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
+    accountUrl: string,
+  ): Promise<string[]> => {
+    const credential = new ContextTokenCredential(ctx.Tokens.Storage);
     const service = new BlobServiceClient(accountUrl, credential);
     const names: string[] = [];
     for await (const container of service.listContainers()) {
@@ -118,54 +48,10 @@ udf.func(
     }
     return names;
   },
-  [udf.connection({ audienceType: AudienceType.Storage })],
+  [],
 );
 ```
 
 Provide the storage account URL (e.g. `https://<account>.blob.core.windows.net`).
 
 > `AudienceType.Storage` also covers **OneLake** files — that Fabric case is documented in [Add a Fabric resource → OneLake files](./add-fabric-resource.md#onelake-files).
-
-## Event Grid
-
-Publish events to an Azure Event Grid topic using `AudienceType.EventGrid`. The topic endpoint is in the Azure portal → your topic → **Overview** → _Topic Endpoint_.
-
-```bash
-cd rayfin/functions
-npm install @azure/eventgrid
-```
-
-```ts
-import {
-  UserDataFunctions,
-  AudienceType,
-  type RayfinContext,
-} from "@microsoft/fabric-user-data-functions";
-import { EventGridPublisherClient } from "@azure/eventgrid";
-
-const udf = new UserDataFunctions();
-
-const TOPIC_ENDPOINT =
-  "https://<topic>.<region>.eventgrid.azure.net/api/events";
-
-udf.func(
-  "publishEvent",
-  async (ctx: RayfinContext, subject: string): Promise<string> => {
-    const client = new EventGridPublisherClient(
-      TOPIC_ENDPOINT,
-      "EventGrid",
-      new ContextTokenCredential(ctx.getToken(AudienceType.EventGrid)),
-    );
-    await client.send([
-      {
-        eventType: "Rayfin.Function.Event",
-        subject,
-        dataVersion: "1.0",
-        data: { source: "user-data-function" },
-      },
-    ]);
-    return "published";
-  },
-  [udf.connection({ audienceType: AudienceType.EventGrid })],
-);
-```