@microsoft/rayfin-connector-fabric-semanticmodel 1.34.0-alpha.1148

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @microsoft/rayfin-connector-fabric-semanticmodel
+
+> **Experimental** — this package is experimental and may change substantially in the near future.
+> Mount the typed connectors runtime via the experimental subpath of
+> `@microsoft/rayfin-client` (see snippet below) rather than the stable
+> `RayfinClient` entry.
+
+Typed marker for the Rayfin `fabric-semanticmodel` connector category.
+
+This package contributes nothing at runtime — it only exports the types
+needed to make `client.connectors.<name>.executeQuery(...)` strongly typed
+when `<name>` points at a `fabric-semanticmodel` connector in `rayfin.yml`.
+
+## Usage
+
+Declare your app's connector schema:
+
+```ts
+// rayfin/connectors/schema.ts
+import type { ConnectorsSchema } from '@microsoft/rayfin-client/experimental';
+import type { FabricSemanticModel } from '@microsoft/rayfin-connector-fabric-semanticmodel';
+
+export type AppConnectorsSchema = {
+  salesModel: FabricSemanticModel<'executeQuery'>;
+};
+
+// Optional compile-time guard:
+const _check: ConnectorsSchema = null as unknown as AppConnectorsSchema;
+void _check;
+```
+
+Pass it as the third type parameter of `ConnectorsRayfinClient`:
+
+```ts
+import { ConnectorsRayfinClient } from '@microsoft/rayfin-client/experimental';
+import type { AppConnectorsSchema } from '../rayfin/connectors/schema';
+
+const client = new ConnectorsRayfinClient<
+  DataSchema,
+  FunctionsSchema,
+  AppConnectorsSchema
+>({
+  baseUrl: import.meta.env.VITE_RAYFIN_BASE_URL,
+  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
+});
+```
+
+Then call:
+
+```ts
+const response = await client.connectors.salesModel.executeQuery({
+  query: 'EVALUATE TOPN(10, Sales)',
+});
+console.log(response.output.tables[0]?.rows);
+```
+
+The connector's `workspaceId` and `itemId` come from the `connectors.salesModel.config`
+block in `rayfin.yml` — the client never sees them.
+
+## Normalising the response
+
+The wire response mirrors Power BI's `executeQueries` shape (rows are
+keyed by qualified column name) and surfaces FuncSet adapter metadata
+such as `requestId`, structured `queryError` / `responseError`, and the
+dataset's sensitivity label. Use `toQueryResult` to fold it into a
+column-aligned, discriminated-union result that's easy to render:
+
+```ts
+import { toQueryResult } from '@microsoft/rayfin-connector-fabric-semanticmodel';
+
+const response = await client.connectors.salesModel.executeQuery({
+  query: 'EVALUATE TOPN(10, Sales)',
+});
+
+const result = toQueryResult(response);
+if (result.status === 'success') {
+  console.log(result.table.columns, result.table.rows);
+} else {
+  console.error(result.error.category, result.error.message);
+}
+```
+
+Column `dataType` defaults to `'unknown'` until the FuncSet adapter
+surfaces type metadata from an Arrow-capable endpoint.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { ExecuteQueryInput, FabricSemanticModelColumn, FabricSemanticModelError, FabricSemanticModelInformationProtectionLabel, FabricSemanticModelOutput, FabricSemanticModelTable, FabricSemanticModelTabularResponse, } from './types.js';
+export type { FabricSemanticModel, FabricSemanticModelOperation, FabricSemanticModelOperationCatalog, } from './marker.js';
+export { toQueryResult } from './queryResult.js';
+export type { QueryColumn, QueryError, QueryErrorCategory, QueryTable, SemanticModelQueryResult, } from './queryResult.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+export { toQueryResult } from './queryResult.js';
+//# sourceMappingURL=index.js.map

package/dist/marker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Typed marker for the `fabric-semanticmodel` connector
+ * category. Contributes the operation catalog that the typed
+ * `client.connectors.<name>` proxy uses to type its operations.
+ */
+import type { ConnectorMarker, OperationDef } from '@microsoft/rayfin-connectors';
+import type { ExecuteQueryInput, FabricSemanticModelTabularResponse } from './types.js';
+/**
+ * Union of all operation names this connector category supports.
+ */
+export type FabricSemanticModelOperation = 'executeQuery';
+/**
+ * The full catalog of typed operations for `fabric-semanticmodel`.
+ */
+export interface FabricSemanticModelOperationCatalog {
+    executeQuery: OperationDef<ExecuteQueryInput, FabricSemanticModelTabularResponse>;
+}
+/**
+ * Type marker for a `fabric-semanticmodel` connector instance.
+ *
+ * Pick which operations you want to expose via the union type parameter
+ * (defaults to all of them).
+ *
+ * @example
+ * ```ts
+ * type AppConnectorsSchema = {
+ *   salesModel: FabricSemanticModel<'executeQuery'>;
+ * };
+ * ```
+ */
+export type FabricSemanticModel<TOps extends FabricSemanticModelOperation = FabricSemanticModelOperation> = ConnectorMarker<Pick<FabricSemanticModelOperationCatalog, TOps>>;
+//# sourceMappingURL=marker.d.ts.map

package/dist/marker.js

@@ -0,0 +1,7 @@
+/**
+ * Typed marker for the `fabric-semanticmodel` connector
+ * category. Contributes the operation catalog that the typed
+ * `client.connectors.<name>` proxy uses to type its operations.
+ */
+export {};
+//# sourceMappingURL=marker.js.map

package/dist/queryResult.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Helper that normalises a {@link FabricSemanticModelTabularResponse} into
+ * a UI-friendly {@link SemanticModelQueryResult}.
+ *
+ * The normalised shape is a discriminated union on `status`, with
+ * column-aligned rows (`unknown[][]`), categorised errors, and the Power
+ * BI `requestId` preserved for traceability.
+ */
+import type { FabricSemanticModelTabularResponse } from './types.js';
+/**
+ * A single column's metadata in a normalised query result.
+ */
+export interface QueryColumn {
+    /** Column name, e.g. `"Sales[Amount]"` or `"[Total]"`. */
+    name: string;
+    /**
+     * Power-BI-style dataType, e.g. `"Int64"`, `"String"`, `"DateTime"`.
+     *
+     * The Power BI JSON `executeQueries` endpoint does not return column
+     * types, so this defaults to `"unknown"` until the FuncSet adapter is
+     * upgraded to surface real type information.
+     */
+    dataType: string;
+}
+/**
+ * A normalised, table-renderer-friendly query result table.
+ *
+ * Unlike the raw wire shape (which uses `Record<string, unknown>` rows),
+ * this shape uses column-aligned `unknown[][]` rows so consumers can feed
+ * them directly into data-grid components.
+ */
+export interface QueryTable {
+    /** Column definitions in display order. */
+    columns: QueryColumn[];
+    /** Row-major data. Each row is an array of values aligned with `columns`. */
+    rows: unknown[][];
+}
+/**
+ * Categorisation for query errors, useful for retry/UX strategies.
+ *
+ * - `'api'` — transport, auth, or dataset-level failure.
+ * - `'query'` — DAX query error (syntax, semantic, etc.).
+ * - `'overflow'` — Power BI row/byte cap exceeded; data may be truncated.
+ * - `'unknown'` — could not categorise.
+ */
+export type QueryErrorCategory = 'api' | 'query' | 'overflow' | 'unknown';
+/**
+ * Structured error in a normalised query result.
+ */
+export interface QueryError {
+    /** Error category. */
+    category: QueryErrorCategory;
+    /** Human-readable message. */
+    message: string;
+    /** Error code, when known. */
+    code?: string;
+}
+/**
+ * Discriminated union representing a normalised query result.
+ */
+export type SemanticModelQueryResult = {
+    status: 'success';
+    table: QueryTable;
+    /** Power BI `RequestId` header value, or empty string when unavailable. */
+    requestId: string;
+} | {
+    status: 'error';
+    error: QueryError;
+    requestId: string;
+};
+/**
+ * Normalise a {@link FabricSemanticModelTabularResponse} into a
+ * {@link SemanticModelQueryResult}.
+ *
+ * Error precedence (highest first):
+ *
+ * 1. Non-empty `response.errors[]` (FuncSet/transport failure) → `'api'`.
+ * 2. `response.output.responseError` (dataset-level) → `'api'`.
+ * 3. `response.output.queryError` (per-query) → `'query'`.
+ * 4. `response.output.tables[0].error` (per-table) → `'overflow'`.
+ *
+ * On success, column metadata is taken from `tables[0].columns` if the
+ * adapter provided it; otherwise column names are inferred from
+ * `Object.keys(rows[0])` and dataTypes default to `'unknown'`.
+ */
+export declare function toQueryResult(response: FabricSemanticModelTabularResponse): SemanticModelQueryResult;
+//# sourceMappingURL=queryResult.d.ts.map

package/dist/queryResult.js

@@ -0,0 +1,129 @@
+/**
+ * Helper that normalises a {@link FabricSemanticModelTabularResponse} into
+ * a UI-friendly {@link SemanticModelQueryResult}.
+ *
+ * The normalised shape is a discriminated union on `status`, with
+ * column-aligned rows (`unknown[][]`), categorised errors, and the Power
+ * BI `requestId` preserved for traceability.
+ */
+/**
+ * Normalise a {@link FabricSemanticModelTabularResponse} into a
+ * {@link SemanticModelQueryResult}.
+ *
+ * Error precedence (highest first):
+ *
+ * 1. Non-empty `response.errors[]` (FuncSet/transport failure) → `'api'`.
+ * 2. `response.output.responseError` (dataset-level) → `'api'`.
+ * 3. `response.output.queryError` (per-query) → `'query'`.
+ * 4. `response.output.tables[0].error` (per-table) → `'overflow'`.
+ *
+ * On success, column metadata is taken from `tables[0].columns` if the
+ * adapter provided it; otherwise column names are inferred from
+ * `Object.keys(rows[0])` and dataTypes default to `'unknown'`.
+ */
+export function toQueryResult(response) {
+    const requestId = response.output?.requestId ?? '';
+    // 1. FuncSet/transport error — invocation didn't return a clean Power BI payload.
+    if (Array.isArray(response.errors) && response.errors.length > 0) {
+        return {
+            status: 'error',
+            error: toApiError(response.errors[0]),
+            requestId,
+        };
+    }
+    // 2. Top-level response error (dataset/auth).
+    if (response.output?.responseError) {
+        return {
+            status: 'error',
+            error: toCategorisedError(response.output.responseError, 'api'),
+            requestId,
+        };
+    }
+    // 3. Per-query error.
+    if (response.output?.queryError) {
+        return {
+            status: 'error',
+            error: toCategorisedError(response.output.queryError, 'query'),
+            requestId,
+        };
+    }
+    // 4. Per-table error → overflow (row/byte cap exceeded).
+    const firstTable = response.output?.tables?.[0];
+    if (firstTable?.error) {
+        return {
+            status: 'error',
+            error: toCategorisedError(firstTable.error, 'overflow'),
+            requestId,
+        };
+    }
+    // 5. Success — build a column-aligned table.
+    const rawRows = firstTable?.rows ?? [];
+    const wireColumns = firstTable?.columns;
+    const columns = wireColumns
+        ? wireColumns.map((c) => ({
+            name: c.name,
+            dataType: c.dataType ?? 'unknown',
+        }))
+        : (rawRows.length > 0 ? Object.keys(rawRows[0]) : []).map((name) => ({
+            name,
+            dataType: 'unknown',
+        }));
+    const rows = rawRows.map((row) => columns.map((col) => row[col.name] ?? null));
+    return {
+        status: 'success',
+        table: { columns, rows },
+        requestId,
+    };
+}
+function toCategorisedError(err, category) {
+    return {
+        category,
+        message: err.message,
+        ...(err.code !== undefined ? { code: err.code } : {}),
+    };
+}
+/**
+ * Convert an opaque FuncSet error entry to a {@link QueryError}.
+ *
+ * The FuncSet adapter emits JSON-encoded `RuntimeError` messages for
+ * non-200 Power BI responses (see the Python UDF), so this helper tries
+ * to parse a JSON envelope of the form
+ * `{ httpStatus, code, message, requestId }` out of the entry's
+ * `message` field. Falls back to the raw string when parsing fails.
+ */
+function toApiError(entry) {
+    if (typeof entry === 'object' && entry !== null) {
+        const obj = entry;
+        const rawMessage = typeof obj.message === 'string' ? obj.message : undefined;
+        if (rawMessage !== undefined) {
+            const parsed = tryParseJson(rawMessage);
+            if (parsed && typeof parsed === 'object') {
+                const p = parsed;
+                const code = typeof p.code === 'string'
+                    ? p.code
+                    : typeof p.httpStatus === 'number'
+                        ? String(p.httpStatus)
+                        : undefined;
+                return {
+                    category: 'api',
+                    message: typeof p.message === 'string' ? p.message : rawMessage,
+                    ...(code !== undefined ? { code } : {}),
+                };
+            }
+            return { category: 'api', message: rawMessage };
+        }
+    }
+    if (typeof entry === 'string') {
+        return { category: 'api', message: entry };
+    }
+    return { category: 'api', message: 'Connector returned an error.' };
+}
+function tryParseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=queryResult.js.map

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Runtime + type shapes for `fabric-semanticmodel`
+ * operation payloads.
+ */
+/**
+ * Input payload for the `executeQuery` operation.
+ *
+ * The Builder only sends the DAX `query`. The connector's target
+ * `workspaceId` and `itemId` are declared once under
+ * `connectors.<name>.config` in `rayfin.yml`; the BaaS host injects them
+ * into the request server-side from that config before forwarding to the
+ * FuncSet adapter. The Builder does not (and cannot) send them on the
+ * wire — the YAML is the single source of truth.
+ */
+export interface ExecuteQueryInput {
+    /** A DAX query string. */
+    query: string;
+}
+/**
+ * Tabular query response from the `executeQuery` operation.
+ *
+ * The wire envelope wraps the Power BI executeQueries result with metadata
+ * surfaced by the FuncSet adapter (`requestId`, structured errors,
+ * sensitivity label). `output.tables[]` is the underlying Power BI shape.
+ *
+ * See {@link toQueryResult} for a normalised, UI-friendly view.
+ */
+export interface FabricSemanticModelTabularResponse {
+    /** FuncSet invocation status, e.g. `"Succeeded"`. */
+    status: string;
+    /** The tabular payload. */
+    output: FabricSemanticModelOutput;
+    /** Errors collected by FuncSet during invocation. Empty array on success. */
+    errors: unknown[];
+}
+/**
+ * Tabular payload from the connector. Mirrors the Power BI
+ * `DatasetExecuteQueriesResponse` shape augmented by the FuncSet adapter.
+ */
+export interface FabricSemanticModelOutput {
+    /** Tables returned for the query. Power BI returns exactly one table per query. */
+    tables: FabricSemanticModelTable[];
+    /**
+     * Power BI server-assigned request id (from the `RequestId` response
+     * header). Use it when reporting issues to the platform team.
+     */
+    requestId?: string;
+    /**
+     * Per-query error — for example, `"More than one result table in a query"`.
+     * `null` (or omitted) when the query succeeded.
+     */
+    queryError?: FabricSemanticModelError | null;
+    /**
+     * Top-level response error — for example, dataset-level authorisation
+     * failures. `null` (or omitted) when the response succeeded.
+     */
+    responseError?: FabricSemanticModelError | null;
+    /**
+     * Sensitivity label associated with the dataset, if any. Useful for
+     * compliance UIs that need to badge data with its classification.
+     */
+    informationProtectionLabel?: FabricSemanticModelInformationProtectionLabel;
+}
+/**
+ * A single result table from the query.
+ *
+ * Today only `rows` is populated by the FuncSet adapter (Power BI's JSON
+ * `executeQueries` endpoint does not return column metadata). The optional
+ * `columns` field is reserved for a future adapter upgrade that surfaces
+ * Arrow-derived dataTypes.
+ */
+export interface FabricSemanticModelTable {
+    /** Row data. Keys are fully-qualified column names, e.g. `"Sales[Amount]"`. */
+    rows: Array<Record<string, unknown>>;
+    /**
+     * Per-table error — set by Power BI when row/byte caps are exceeded
+     * (e.g. `"More than 1000000 rows in a query result"`). When present, the
+     * row data is truncated.
+     */
+    error?: FabricSemanticModelError;
+    /**
+     * Reserved for future use. When the FuncSet adapter starts surfacing
+     * column metadata (names + dataTypes) from an Arrow-capable endpoint,
+     * this field will be populated. Until then, column dataTypes are
+     * inferred as `'unknown'` by {@link toQueryResult}.
+     */
+    columns?: FabricSemanticModelColumn[];
+}
+/**
+ * Column metadata, when available from the adapter.
+ */
+export interface FabricSemanticModelColumn {
+    /** Column name, e.g. `"Sales[Amount]"` or `"[Total]"`. */
+    name: string;
+    /**
+     * Power-BI-style dataType, e.g. `"Int64"`, `"String"`, `"Double"`,
+     * `"Decimal"`, `"DateTime"`, or `"Boolean"`. Omitted when the adapter
+     * cannot determine the type.
+     */
+    dataType?: string;
+}
+/**
+ * Structured error returned by Power BI. Mirrors the
+ * `DatasetExecuteQueriesError` shape.
+ */
+export interface FabricSemanticModelError {
+    /** Power BI error code, e.g. `"DatasetExecuteQueriesError"`. */
+    code?: string;
+    /** Human-readable error message. */
+    message: string;
+}
+/**
+ * Sensitivity label associated with the dataset.
+ */
+export interface FabricSemanticModelInformationProtectionLabel {
+    /** Label GUID. */
+    id: string;
+    /** Display name, e.g. `"General"`, `"Confidential"`. */
+    name: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * Runtime + type shapes for `fabric-semanticmodel`
+ * operation payloads.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@microsoft/rayfin-connector-fabric-semanticmodel",
+  "version": "1.34.0-alpha.1148",
+  "description": "Typed connector marker for the Fabric semantic-model (Power BI dataset) connector category. Pair with @microsoft/rayfin-client to type `client.connectors.<name>.executeQuery(...)`.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/__tests__/**",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "eslint": "^9.28.0",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3",
+    "@vitest/coverage-v8": "~3.2.4",
+    "rimraf": "~6.0.1"
+  },
+  "dependencies": {
+    "@microsoft/rayfin-connectors": "1.34.0-alpha.1148"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com",
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/project-rayfin.git",
+    "directory": "packages/typescript-sdk/connector-fabric-semanticmodel"
+  },
+  "keywords": [
+    "rayfin",
+    "fabric",
+    "semantic-model",
+    "powerbi",
+    "dax"
+  ],
+  "author": "Microsoft",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && node ../scripts/fix-esm-extensions.mjs ./dist",
+    "build:watch": "tsc --watch",
+    "clean": "rimraf dist && rimraf .tsbuildinfo",
+    "test": "vitest run --passWithNoTests"
+  }
+}