@microsoft/rayfin-guide 1.35.0-alpha.1374 → 1.35.0-alpha.1541

package/assets/docs/app-backend/deep-linking.md

@@ -0,0 +1,188 @@
+---
+sidebar_position: 50
+---
+
+# Deep linking and shareable URLs
+
+Deep linking lets a user copy the browser URL and send someone the exact view they were looking at.
+
+A Fabric data app runs inside a cross-origin iframe and has no addressable URL of its own, so it cannot write to the address bar directly.
+The `@microsoft/rayfin-app-state-fabric` package bridges that gap: your app hands the portal a plain JSON object, and the portal encodes it into the URL it owns.
+
+## Availability
+
+Deep linking is rolling out per tenant, so it is not available everywhere yet.
+
+Always call `isSupported()` before showing a share button or any affordance that depends on the URL carrying state.
+It resolves to `undefined` when the host does not support deep linking, and your app should continue to work normally in that case.
+
+## How it works
+
+1. A user opens a link whose portal URL carries encoded state.
+2. The portal seeds that state onto your app's iframe URL before your app loads.
+3. Your app reads it synchronously on startup, so the shared view renders first and no default view flashes.
+4. As the user navigates, your app writes state back through the SDK and the portal updates its address bar.
+5. When the user presses Back or Forward, the portal notifies your app so it can restore the matching view.
+
+The portal owns encoding, versioning, size limits, and browser history.
+Your app owns the shape of the state object.
+
+## Install the package
+
+```bash
+npm install @microsoft/rayfin-app-state-fabric
+```
+
+## Create the client
+
+Create one client for the lifetime of your app and share it, rather than constructing one per component.
+
+```typescript
+import { createFabricAppStateClient } from '@microsoft/rayfin-app-state-fabric';
+
+const appState = createFabricAppStateClient({
+  targetOrigin: 'https://app.fabric.microsoft.com',
+});
+```
+
+Pass `targetOrigin` whenever you know it.
+Without it, messages are posted with `"*"` and inbound events are not origin-checked.
+
+## Read launch state before first render
+
+Read the launch state before your first render so a default view never flashes before the shared one.
+
+```typescript
+const launch = appState.getLaunchStateSync();
+renderApp(launch ?? defaultView);
+```
+
+`getLaunchStateSync()` returns the state without awaiting, which is what you want on the first render path.
+It returns `undefined` when the URL carries no state, which is the normal case for a fresh navigation.
+
+Use `await appState.getLaunchState()` when your startup code can be asynchronous.
+It resolves from the seeded URL on hosts that support it, so awaiting it does not delay first paint.
+
+Treat launch state as untrusted input.
+Anyone can edit a link before sharing it, so validate it exactly as you would a query parameter before using it to drive queries.
+
+## Write state as the user navigates
+
+Choose between the two writers by asking who caused the change.
+
+Use `setState()` when the *user* caused it, such as a click, a filter change, or opening a record.
+It creates a history entry, so Back returns the user to where they were.
+
+```typescript
+await appState.setState({ view: 'sales', region: 'AT' });
+```
+
+Use `replaceState()` when the *app* caused it, or for high-frequency updates such as a slider drag where one history entry per update would make Back unusable.
+
+```typescript
+await appState.replaceState({ view: 'sales', threshold: value });
+```
+
+The whole object is replaced on every write.
+There is no partial or namespaced update, so merge your state before writing it.
+
+## React to Back and Forward
+
+Subscribe to observe changes your app did not initiate, such as the browser Back and Forward buttons or a deep link opened in the current tab.
+
+```typescript
+const unsubscribe = appState.onStateChange((state) => {
+  restore(state ?? defaultView);
+});
+
+// On teardown
+unsubscribe();
+appState.dispose();
+```
+
+The listener receives `undefined` when navigation reaches a URL that carries no state, which means your app should restore its own defaults.
+
+## Check support before showing a share button
+
+```typescript
+const capabilities = await appState.isSupported();
+
+if (capabilities) {
+  showShareButton();
+
+  // Some hosts can update the URL but cannot add history entries.
+  if (!capabilities.canPush) {
+    hideBackForwardHints();
+  }
+}
+```
+
+The host is authoritative.
+It reports its own `maxEncodedBytes`, `maxDepth`, and `canPush`, and those values are the real contract.
+
+## Running standalone
+
+Many apps ship standalone as well as embedded.
+Standalone, your app owns its own address bar and there is no host to talk to, so deep-link state is unavailable by design.
+
+The client is safe to construct either way.
+It never throws at construction and never rewrites a URL it does not own.
+
+Use the same `isSupported()` check to select your standalone path:
+
+```typescript
+const capabilities = await appState.isSupported();
+
+if (capabilities) {
+  await appState.setState({ view: 'sales', region: 'AT' });
+} else {
+  router.push({ path: '/sales', query: { region: 'AT' } });
+}
+```
+
+Standalone, reads return `undefined` and writes reject with `NO_HOST_WINDOW`.
+Reads degrade quietly so startup needs no branching, while writes fail loudly so a missing branch shows up during development.
+
+## Limits and rules
+
+- State must be a plain JSON object. `Date`, `Map`, `Set`, class instances, functions, and `undefined` are rejected rather than silently degraded.
+- State is capped at 4 KiB encoded and 20 levels deep, so shared links survive corporate proxies, mail gateways, and chat clients.
+- For anything larger, store the data yourself and put an identifier in the state.
+- The encoding is versioned but your payload is not, so a link shared before a shape change still arrives in the old shape and your app must tolerate it.
+
+## Security
+
+State travels in a URL, so treat it accordingly.
+
+**It is visible to the user.**
+It appears in the address bar, browser history, bookmarks, screenshots, copied links, and corporate proxy logs.
+Never put secrets, access tokens, or personal data in it.
+When the state is sensitive, use an opaque identifier that maps to server-side data.
+
+**It is untrusted input.**
+Validate launch state before using it, and tolerate state written by a different version of your own app.
+
+## Troubleshooting
+
+**`isSupported()` resolves to `undefined`.**
+Either the app is not embedded in the Fabric portal, or deep linking has not reached this tenant yet.
+Both are expected, and your app should fall back to its own routing.
+
+**Writes reject with `STATE_TOO_LARGE`.**
+The state exceeds the encoded budget the host reported.
+Move the bulk of the data server-side and keep an identifier in the state.
+
+**Writes reject with `INVALID_STATE`.**
+The state contains something JSON cannot round-trip, such as a `Date`, a class instance, `undefined`, or a circular reference.
+The error message names the offending path.
+
+**Writes reject with `NO_HOST_WINDOW`.**
+The app is not running embedded, so there is no portal to write to.
+
+Errors are `FabricAppStateError` values with a stable `code`.
+Branch on the code, never on the message.
+
+## Next steps
+
+- [Fabric Brokered Auth](../auth/fabric.md) — How Fabric SSO authentication works.
+- [Deploy to Microsoft Fabric](./deploy.md) — Detailed deployment commands and troubleshooting.

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

@@ -266,7 +266,7 @@ services:
 
 ### Static deploy exceeds size limit
 
-The compressed archive must not exceed 100 MB. Optimize your build output by excluding source maps and large development assets, or move binary files to Rayfin storage.
+The compressed archive must not exceed 100 MB. Optimize your build output by excluding source maps and large development assets.
 
 ### GraphQL returns "Internal server error" after deploy
 

package/assets/docs/app-backend/deployment-pipelines.md

@@ -0,0 +1,101 @@
+---
+sidebar_position: 46
+---
+
+# Fabric Deployment Pipelines
+
+Microsoft Fabric's **Deployment Pipelines** feature promotes an AppBackend between dev/test/prod-style workspace stages without rebuilding it — the same pre-built artifact moves forward as-is.
+This page covers what that means for a Rayfin app and how to check whether yours is ready for it.
+
+## What actually moves
+
+An AppBackend's exported definition is a portable package of pre-built artifacts, not source code:
+
+```text
+MyAppBackend.AppBackend/
+├── .platform            Fabric-managed item metadata
+├── rayfin.yml            Services config (auth, data, storage, staticHosting) — promotes as-is
+├── dab-config.json       Pre-generated DAB entity schema — promotes as-is (dialect-locked)
+└── static-app.zip        Compiled SPA bundle — promotes as-is (byte-identical across stages)
+```
+
+### `rayfin.config.json` — generated per stage, not promoted
+
+When you deploy with `rayfin up`, the CLI writes a `rayfin.config.json` file into `StaticAssets/` alongside the compiled SPA, containing that stage's API URL, publishable key, and Fabric item metadata.
+`resolveRayfinConfig()` reads this file automatically at runtime when it's present, and falls back to whatever `apiUrl`/`publishableKey` defaults you pass in — typically your `VITE_RAYFIN_*` env vars — when it's not, which is the local-dev case before you've ever run `rayfin up`.
+
+This is exactly why `rayfin.config.json` is **deliberately excluded** from the exported definition above: Fabric regenerates it fresh in the target workspace on every Import, using that stage's own API URL, publishable key, and item metadata, so a stale Dev config can never leak into Prod as your app moves through the pipeline.
+
+## Read your backend config with `resolveRayfinConfig()`
+
+Because the compiled SPA bundle moves unchanged between stages, resolve your backend URL and key through `resolveRayfinConfig()` before constructing `RayfinClient` / `RayfinServerClient`, rather than constructing the client from your env vars directly.
+Your `VITE_RAYFIN_API_URL` / `VITE_RAYFIN_PUBLISHABLE_KEY` env vars still belong in your app — `rayfin dev` depends on them — just pass them into `resolveRayfinConfig()` as defaults instead of using them to build the client yourself:
+
+```ts
+import { RayfinClient, resolveRayfinConfig } from '@microsoft/rayfin-client';
+
+const resolved = await resolveRayfinConfig({
+  apiUrl: import.meta.env.VITE_RAYFIN_API_URL,
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+});
+const client = new RayfinClient<Schema>({ ...resolved, authStorage: true });
+```
+
+`resolveRayfinConfig()` prefers `rayfin.config.json` when it's present — every deployed stage — and falls back to the `apiUrl`/`publishableKey` defaults you pass in only when the file is absent, which is the local-dev case. Constructing the client directly from build-time values, skipping `resolveRayfinConfig()`, bakes in whatever you pass and never checks for `rayfin.config.json`, so a promoted bundle would keep pointing at the source environment's backend.
+
+For your backend URL and key alone, call `resolveRayfinConfig()`, not `loadRayfinConfig()` directly — `loadRayfinConfig()` is the lower-level primitive `resolveRayfinConfig()` calls internally to fetch `rayfin.config.json`, and `resolveRayfinConfig()` is the one that overlays the result over your defaults and returns what you should construct the client with.
+If your app also needs Fabric coordinates for its auth broker, pass them alongside `apiUrl`/`publishableKey` in `resolveRayfinConfig()`'s defaults — see [Fabric auth coordinates](#fabric-auth-coordinates-need-clientruntimeconfig) below.
+
+If you're not sure whether your app already resolves config before constructing the client, check for direct construction:
+
+```bash
+grep -rn "new RayfinClient(\|new RayfinServerClient(" src/
+```
+
+Any match there should be preceded by a `resolveRayfinConfig()` call, with its result spread into the constructor as shown above — your existing `VITE_RAYFIN_*` reads can stay, just pass them in as `resolveRayfinConfig()`'s defaults instead of using them to construct the client directly.
+
+## Fabric auth coordinates need `client.runtimeConfig`
+
+If your app embeds in Fabric and drives its own auth flow against the Fabric secure-embed broker, `resolveRayfinConfig()`'s `apiUrl`/`publishableKey` alone aren't enough — your auth wiring also needs the Fabric coordinates (`workspaceId`, `itemId`, `portalUrl`) from the same `rayfin.config.json`.
+
+`client.runtimeConfig` is a single `RayfinRuntimeConfig` bag holding every value `rayfin.config.json` can supply (`apiUrl`, `publishableKey`, `workspaceId`, `itemId`, `portalUrl`, `tenantId`) — all fields optional, since neither the remote config nor your defaults are guaranteed to provide every one. Pass your build-time `VITE_FABRIC_*` values into `resolveRayfinConfig()`'s defaults alongside `apiUrl`/`publishableKey`, and read the resolved coordinates off `client.runtimeConfig` after construction:
+
+```ts
+const resolved = await resolveRayfinConfig({
+  apiUrl: import.meta.env.VITE_RAYFIN_API_URL,
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+  workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
+  itemId: import.meta.env.VITE_FABRIC_ITEM_ID,
+  portalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
+});
+const client = new RayfinClient<Schema>({ ...resolved, authStorage: true });
+
+const { workspaceId, itemId, portalUrl } = client.runtimeConfig ?? {};
+```
+
+`resolveRayfinConfig()` resolves `runtimeConfig` from the same `rayfin.config.json` fetch it already makes for `apiUrl`/`publishableKey`, overlaying remote values over your defaults per-field — no extra request. `resolveFabricConfig()`, which made its own independent fetch for just the Fabric fields, has been removed as redundant — always resolve through `client.runtimeConfig` instead.
+
+Reading `workspaceId`/`itemId`/`portalUrl` directly from `VITE_FABRIC_*` env vars — without going through `client.runtimeConfig` — bakes in whatever stage the bundle was *built* in.
+Since deployment pipelines promote the same compiled bundle across stages without rebuilding, that mismatch only shows up after a promotion: your API calls correctly hit the new stage's backend (via `resolveRayfinConfig()`'s `rayfin.config.json` read), but your auth broker still points at the *old* stage's workspace/item, because it never read from the runtime config at all.
+
+If you're not sure whether your app resolves Fabric coordinates this way, check for direct reads of `VITE_FABRIC_*` that don't go through `runtimeConfig`/`client.runtimeConfig`:
+
+```bash
+grep -rn "VITE_FABRIC_" src/
+```
+
+Any match not passed through `runtimeConfig`/`client.runtimeConfig` should be updated as shown above.
+
+## Out of scope today
+
+- **Functions** (`rayfin/functions/`) — not covered by this pattern yet.
+- **Secrets** — a separate concern from config-file promotion.
+- **Source-code / Git integration** — Deployment Pipelines move built artifacts, not source. [Git integration](https://learn.microsoft.com/en-us/fabric/cicd/git-integration/intro-to-git-integration) is a related but distinct Fabric feature for source-controlling item definitions.
+
+## Related Fabric platform concepts
+
+These are Fabric platform features, not something the Rayfin CLI/SDK controls — see Fabric's own [CI/CD documentation](https://learn.microsoft.com/en-us/fabric/cicd/) for depth:
+
+- **Git integration** — links a workspace to a Git branch for source control of Fabric item definitions.
+- **Deployment pipelines** — promotes items between dev/test/prod-style workspace stages; the feature this page covers.
+- **Variable libraries** — Fabric-managed, stage-scoped values usable across items; not currently wired to `rayfin.config.json` generation, but conceptually related.

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

@@ -67,7 +67,6 @@ The endpoint exposes paths for each service:
 | --- | --- |
 | `/api/graphql` | Data API (GraphQL) — used by `RayfinClient` for CRUD operations |
 | `/auth` | Authentication service |
-| `/storage` | File storage |
 
 Your frontend application uses this endpoint via the `VITE_RAYFIN_API_URL` environment variable, which is generated into `.env.local` from `rayfin/.env` after deployment.
 
@@ -123,4 +122,5 @@ Learn more about [Workspace roles](https://learn.microsoft.com/fabric/fundamenta
 - [Pricing and capacity usage](./pricing.md) — Understand what consumes Fabric capacity and how billing works.
 - [Create a Fabric data app](../getting-started/create-rayfin-item.md) — Step-by-step guide to creating your first item in the Fabric portal.
 - [Deploy to Microsoft Fabric](./deploy.md) — Detailed deployment commands and troubleshooting.
+- [Deep linking and shareable URLs](./deep-linking.md) — Let users share a link that reopens the exact view they were looking at.
 - [Fabric Brokered Auth](../auth/fabric.md) — How Fabric SSO authentication works.

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

@@ -10,7 +10,7 @@ npx rayfin connector add --type <type> --workspace-id <ws-id> --item-id <item-id
 
 `connector add` declares a connector in `rayfin/rayfin.yml` and scaffolds its supporting files.
 
-The CLI verifies the Fabric item, derives a connector `name` from the item's display name (override with `--name`), writes the entry to `rayfin.yml`, scaffolds `rayfin/connectors/<name>/schema.ts`, and runs schema discovery. `rayfin/connectors/<name>/metadata.json` is written so a subset of entities can be generated later.
+The CLI verifies the Fabric item, derives a connector `name` from the item's display name (override with `--name`), writes the entry to `rayfin.yml`, and scaffolds `rayfin/connectors/<name>/schema.ts`. For Category A connectors it also runs schema discovery and writes `rayfin/connectors/<name>/metadata.json` so a subset of entities can be generated later.
 
 If you do not already know the workspace and item IDs, run [`connector search`](./search.md) first — its `--json` output includes a ready-to-run `addCommand` for each result.
 
@@ -58,15 +58,39 @@ Rules:
 
 ## Category B connectors
 
-For `kusto` and `fabric-semanticmodel`, `connector add` writes the `rayfin.yml` entry but there are no GraphQL entities to discover, so no entity files are generated and no row-level security applies:
+For `kusto` and `fabric-semanticmodel`, `connector add` writes the `rayfin.yml` entry and generates a complete typed `schema.ts`, but there are no GraphQL entities to discover, so no entity files are generated and no row-level security applies:
 
-- `executeQuery` is the only allowed operation.
+- `fabric-semanticmodel` allows `executeQuery`; `kusto` allows `executeQuery` and `executeCommand`. Check `rayfin connector types --json` for the current set.
 - `auth.type` must be `delegated`.
 - The connector is pinned to an adapter version.
 - There is no `metadata.json` entity list to generate from.
 
 After adding, exercise the connector with [`connector invoke`](./invoke.md) rather than writing entity code.
 
+## Installing the packages
+
+`connector add` scaffolds files but installs nothing, and the generated `schema.ts` imports packages a fresh app does not declare.
+On success the command prints the exact, version-pinned install to run:
+
+```text
+📦 Install the packages this connector needs:
+   npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha
+```
+
+Run it verbatim.
+**Do not drop the version.** Connector packages ship in lockstep with the CLI, but their npm `latest` and `preview` tags lag the published release, so an unversioned install resolves to an older connector that hard-pins its own `@microsoft/rayfin-data` — leaving two Rayfin version lines in one app.
+
+With `--json`, the same information is available under `install`:
+
+```json
+{
+  "install": {
+    "packages": ["@microsoft/rayfin-connector-kusto@1.35.0-alpha"],
+    "command": "npm install @microsoft/rayfin-connector-kusto@1.35.0-alpha"
+  }
+}
+```
+
 ## Related commands
 
 ```bash