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

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/assets/docs/getting-started/project-structure.md

@@ -24,6 +24,92 @@ your-project/
 └── README.md
 ```
 
+## Universal App workspace
+
+Universal Apps generated by the Rayfin Copilot plugin use an npm workspace while preserving the same root workflow:
+
+```text
+your-universal-app/
+├── package.json
+├── tsconfig.base.json
+├── tsconfig.json
+├── rayfin/
+│   └── rayfin.yml
+└── packages/
+    ├── frontend/
+    │   ├── src/
+    │   ├── package.json
+    │   └── vite.config.ts
+    ├── data/
+    │   ├── src/index.ts
+    │   └── package.json
+    └── shared/
+        ├── src/index.ts
+        └── package.json
+```
+
+The workspace root owns the application identity, npm workspace declaration, orchestration scripts, applied capability-pack record, TypeScript project references, and `rayfin/rayfin.yml`.
+It coordinates the packages but does not own application runtime code.
+
+| Package | Stable name | Ownership |
+| --- | --- | --- |
+| `packages/frontend` | `@rayfin-app/frontend` | React, Vite, Fabric authentication, browser UI, and static output |
+| `packages/data` | `@rayfin-app/data` | Rayfin entity registration and data schema exports |
+| `packages/shared` | `@rayfin-app/shared` | Isomorphic contracts shared across runtime boundaries |
+| `packages/functions` | `@rayfin-app/functions` | Opt-in trusted server workflows created by the functions capability pack |
+
+Only the generated root package name is personalized.
+The stable member names, cross-package dependency keys, and import specifiers are not renamed.
+
+Use root commands for the complete app workflow:
+
+```bash
+npm run build
+npm run typecheck
+npm run lint
+npm test
+npm run preview
+npm run pack:add -- <pack>
+```
+
+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.
+Capability packs do not use a nested functions lockfile or nested install.
+
+### Universal App service paths
+
+Universal App service paths point to the package that owns each deployable surface:
+
+```yaml
+services:
+  data:
+    enabled: false
+    path: packages/data
+    buildCommand: npm run build
+  staticHosting:
+    enabled: true
+    path: packages/frontend
+    folder: dist
+    buildCommand: npm run build:fabric
+    assetAccess: protected
+  functions:
+    enabled: false
+```
+
+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`.
+
+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.
+The Copilot plugin bundles the inner template only; the harness and generated target are not distributed.
+
+Existing flat Universal Apps remain supported by plugin validation and do not need to adopt this layout.
+This workspace template does not add automatic workspace discovery, a migration command, support for package managers other than npm, or functions by default.
+
 ## Key files
 
 ### rayfin/rayfin.yml
@@ -103,6 +189,8 @@ services:
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `false` | Enable the data service. |
 | `dialect` | `"mssql"` \| `"postgresql"` | `"mssql"` | Database dialect. Fabric deployments support MSSQL only. |
+| `path` | `string` | Project root | Data project directory relative to the application root. |
+| `buildCommand` | `string` | — | Command run from the resolved data service path before packaging. |
 
 #### `services.auth`
 
@@ -171,9 +259,10 @@ Configure an email provider for magic links, password resets, and email verifica
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `enabled` | `boolean` | `false` | Enable static content hosting. |
+| `path` | `string` | — | Frontend project directory relative to the application root. |
 | `root` | `string` | — | Root directory of the frontend project (relative to the project root). |
-| `folder` | `string` | `"dist"` | Directory containing built static assets (relative to `root`). |
-| `buildCommand` | `string` | — | Shell command to run before packaging (e.g. `npm run build`). |
+| `folder` | `string` | `"dist"` | Directory containing built static assets, relative to `path` or legacy `root`. |
+| `buildCommand` | `string` | — | Shell command run from the resolved static-hosting path before packaging (for example, `npm run build`). |
 | `indexDocument` | `string` | — | Default document served for the root path (e.g. `index.html`). |
 
 > **Tip:** All string values support environment variable interpolation with `${VAR}` and `${VAR:-default}` syntax.

package/package.json

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