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

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

@@ -26,11 +26,11 @@ udf.func(
 
 `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. |
+| 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 `[]` — audience-scoped connections are declared in the context annotation instead. |
 
 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.
@@ -38,7 +38,8 @@ The handler's typed parameters and return type are extracted into `types.ts` so
 ## 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:
+Pass your app schema as the first generic (`RayfinContext<AppSchema>`) — the same schema you use with `RayfinClient<AppSchema>` — for a fully typed data client.
+A second, optional generic declares the external audiences the function may use; see [Connecting to external resources](./connections/index.md).
 
 ```ts
 import {
@@ -67,14 +68,16 @@ udf.func(
 
 ### `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).                                                                                                                                                                                                                                  |
+| Member                | Description                                                                                                                                                                                                                   |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.getDataClient()` | Returns the Rayfin DB entity data client using the invocation's Rayfin token and the caller's identity and database permissions. Query with `.select([...]).where(...).execute()`, as with `client.data.<Entity>` on the frontend. Typed when a schema generic is supplied; otherwise untyped. |
+| `ctx.Secrets`         | Secret values keyed by the names declared in `rayfin.yml`, each typed `string`. Reading an undeclared name is a compile error. See [Secrets](./secrets.md).                                                                      |
+| `ctx.Tokens`          | Resource access tokens keyed by audience, each typed `string`. Narrowed to the declared audiences; deployed Functions use the app identity. See [Connecting to external resources](./connections/index.md), including local development. |
+| `ctx.baseUrl`         | The Rayfin endpoint URL (readonly).                                                                                                                                                                                           |
+| `ctx.accessToken`     | The invocation's Rayfin token, used for caller-scoped Rayfin DB access (readonly). Not an external resource token from `ctx.Tokens`.                                                                                          |
+| `ctx.publishableKey`  | The Rayfin publishable key (readonly).                                                                                                                                                                                        |
+
+`ctx.getSecret(name)` and `ctx.getToken(audienceType)` are the deprecated predecessors of `ctx.Secrets` and `ctx.Tokens`. They still work, but are flagged by `@typescript-eslint/no-deprecated`.
 
 Use `console.log(...)` / `console.error(...)` for logging.
 
@@ -100,24 +103,25 @@ udf.func(
 
 ## 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:
+To call external Azure or Fabric resources (SQL, Storage, the Fabric REST API, and more) from inside a function, declare the audience in the `RayfinContext` annotation and read the token from `ctx.Tokens`:
 
 ```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);
+  "accessStorage",
+  async (
+    ctx: RayfinContext<AppSchema, AudienceType.Storage>,
+  ): Promise<void> => {
+    const token = ctx.Tokens.Storage;
     // 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.
+The annotation is the declaration — listing the audience is what registers the connection binding, so nothing goes in the third argument.
+See [Application authentication](./index.md#application-authentication) for configuration and identities, and [Connecting to external resources](./connections/index.md) for supported audiences and per-resource guides.
 
 ## Importing data entities
 
@@ -135,6 +139,6 @@ import type { Entry } from "../../data/Entry.js";
 
 - 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.
+- Declare external audiences in the context annotation (`RayfinContext<AppSchema, AudienceType.X>`) and read them with `ctx.Tokens.X` — an audience you did not declare is a compile error.
 - 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/assets/docs/getting-started/project-structure.md

@@ -76,7 +76,7 @@ The root build orders shared, data, and frontend work.
 Focused package commands use npm's workspace selector, such as `npm run -w @rayfin-app/frontend test`.
 
 The base workspace does not contain `packages/functions`, and `services.functions.enabled` is `false`.
-Running `npm run pack:add -- functions` creates the stable functions package, enables its service, composes its build into root orchestration, and installs dependencies from the workspace root.
+Running `npm run pack:add -- functions` creates the stable functions package, enables its service with `auth.type: application`, composes its build into root orchestration, and installs dependencies from the workspace root.
 Capability packs do not use a nested functions lockfile or nested install.
 
 ### Universal App service paths
@@ -102,6 +102,8 @@ services:
 Rayfin resolves each `path` from the application root, then runs that service's `buildCommand` with the service directory as its working directory.
 The static-hosting folder is therefore `packages/frontend/dist`, not a root `dist` directory.
 After the functions pack is applied, functions uses `path: packages/functions` with its package-local `npm run build`.
+Enabled Functions require explicit `services.functions.auth.type: application`; the disabled base configuration above may omit `auth`.
+See [Application authentication](../functions/index.md#application-authentication) for existing-app configuration and downstream permissions.
 
 The Project Rayfin repository keeps this Builder-facing workspace under `samples/universal-app/template`.
 Its parent `samples/universal-app` is only a Rush validation harness that generates an ephemeral target and links that target to repository-local SDK packages.

package/package.json

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

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

@@ -1,39 +0,0 @@
----
-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.