@microsoft/fabric-app-data-cli-proxy

Direct Fabric API proxy for local development and testing

Quick Reference

Package: @microsoft/fabric-app-data-cli-proxy Purpose: IFabricApiProxy implementation that makes direct HTTP calls to Fabric APIs — for Node.js local development and testing. Use when: You are running in Node.js and need to call Fabric APIs directly with a token provider (local dev, CLI, tests). Do NOT use when: Your app runs inside a Fabric iframe (use @microsoft/fabric-app-data-proxy instead — it uses postMessage, not HTTP). Key exports: DirectFabricApiProxy, IFabricTokenProvider, FabricPermission, FabricEndpoints, DEFAULT_ENDPOINTS Peer dependencies: @microsoft/fabric-app-data Install: npm install @microsoft/fabric-app-data-cli-proxy

Ecosystem Context

@microsoft/fabric-app-data-cli-proxy provides a Node.js implementation of IFabricApiProxy from @microsoft/fabric-app-data.

• It is the local-development and test-time counterpart to @microsoft/fabric-app-data-proxy, which is designed for embedded iframe scenarios inside Fabric.
• It acquires access tokens through IFabricTokenProvider
• It is used by @microsoft/fabric-app-data-cli for CLI execution flows that construct DirectFabricApiProxy and pass it into FabricClient.
• It makes direct outbound HTTP calls to Fabric and Power BI REST endpoints instead of using postMessage(...).

Installation

npm install @microsoft/fabric-app-data-cli-proxy

Public API

Package root exports exactly six public symbols:

• DirectFabricApiProxy
• DirectFabricApiProxyConfig
• FabricPermission
• IFabricTokenProvider
• FabricEndpoints
• DEFAULT_ENDPOINTS

DirectFabricApiProxy

import type {
    DaxJsonProxyResponse,
    DaxProxyResponse,
    DaxQueryOptions,
    IFabricApiProxy,
    ILakehouseApiProxy,
    ISemanticModelApiProxy,
    IWarehouseApiProxy,
    SqlParameters,
    SqlProxyResponse,
    SqlQueryOptions,
    WorkspaceId,
} from "@microsoft/fabric-app-data";
import type {
    FabricEndpoints,
    IFabricTokenProvider,
} from "@microsoft/fabric-app-data-cli-proxy";

export interface DirectFabricApiProxyConfig {
    endpoints?: FabricEndpoints;
    sessionId?: string;
}

export class DirectFabricApiProxy implements IFabricApiProxy {
    readonly semanticModel: ISemanticModelApiProxy;
    readonly lakehouse: ILakehouseApiProxy;
    readonly warehouse: IWarehouseApiProxy;

    constructor(
        tokenProvider: IFabricTokenProvider,
        config?: DirectFabricApiProxyConfig,
    );
}

Runtime behavior exposed through IFabricApiProxy

DirectFabricApiProxy exposes three sub-proxies through public properties:

| Property | Type | Current behavior | | --- | --- | --- | | semanticModel | ISemanticModelApiProxy | Implemented. Sends direct HTTP requests to Power BI endpoints for DAX execution. | | lakehouse | ILakehouseApiProxy | Stub implementation. executeSql(...) throws Error("Not implemented — SQL support coming in a future release"). | | warehouse | IWarehouseApiProxy | Stub implementation. executeSql(...) throws Error("Not implemented — SQL support coming in a future release"). |

The currently exposed operation signatures are:

type WorkspaceId = "me" | (string & {});

interface DaxQueryOptions {
    culture?: string;
    schemaOnly?: boolean;
    queryTimeout?: number;
    resultSetRowCountLimit?: number;
}

interface DaxProxyResponse {
    data: ArrayBuffer;
    requestId: string;
}

interface DaxJsonProxyResponse {
    data: unknown;
    requestId: string;
}

interface SqlProxyResponse {
    columns: Array<{ name: string; dataType: string }>;
    rows: unknown[][];
    requestId: string;
}

type SqlParameters = Record<string, string | number | boolean | null>;

interface SqlQueryOptions {
    queryTimeout?: number;
}

interface ISemanticModelApiProxy {
    executeDax(
        workspaceId: WorkspaceId,
        itemId: string,
        query: string,
        options?: DaxQueryOptions,
    ): Promise<DaxProxyResponse>;

    executeDaxJson(
        workspaceId: WorkspaceId,
        itemId: string,
        query: string,
    ): Promise<DaxJsonProxyResponse>;
}

interface ILakehouseApiProxy {
    executeSql(
        workspaceId: WorkspaceId,
        itemId: string,
        sql: string,
        params?: SqlParameters,
        options?: SqlQueryOptions,
    ): Promise<SqlProxyResponse>;
}

interface IWarehouseApiProxy {
    executeSql(
        workspaceId: WorkspaceId,
        itemId: string,
        sql: string,
        params?: SqlParameters,
        options?: SqlQueryOptions,
    ): Promise<SqlProxyResponse>;
}

Behavior details verified from implementation:

• semanticModel.executeDax(...) calls ${powerBiApi}/groups/${workspaceId}/datasets/${itemId}/executeDaxQueries.
• semanticModel.executeDaxJson(...) calls ${powerBiApi}/groups/${workspaceId}/datasets/${itemId}/executeQueries.
• If workspaceId === "me", the /groups/${workspaceId} segment is omitted.
• executeDax(...) requests FabricPermission.SemanticModelRead.
• executeDaxJson(...) requests FabricPermission.PowerBIDatasetRead.

DirectFabricApiProxyConfig

export interface DirectFabricApiProxyConfig {
    endpoints?: FabricEndpoints;
    sessionId?: string;
}

| Property | Type | Meaning | | --- | --- | --- | | endpoints | FabricEndpoints | Override production endpoint bases for alternate environments. | | sessionId | string | Optional session-scoped telemetry correlation ID. |

FabricPermission

export enum FabricPermission {
    SemanticModelRead = "SemanticModelRead",
    PowerBIDatasetRead = "PowerBIDatasetRead",
    LakehouseRead = "LakehouseRead",
    WarehouseRead = "WarehouseRead",
    SqlConnect = "SqlConnect",
}

| Member | Meaning | | --- | --- | | SemanticModelRead | Read semantic-model data via DAX Arrow queries. | | PowerBIDatasetRead | Read semantic-model data via the legacy JSON endpoint. | | LakehouseRead | Resolve a lakehouse item through Fabric REST APIs. | | WarehouseRead | Resolve a warehouse item through Fabric REST APIs. | | SqlConnect | Connect to a Fabric SQL endpoint via TDS. |

IFabricTokenProvider

export interface IFabricTokenProvider {
    getToken(
        permission: FabricPermission,
        options?: { forceRefresh?: boolean },
    ): Promise<string>;
}

The proxy depends on this interface for token acquisition. On an HTTP 401 response, the internal HTTP client retries once with options: { forceRefresh: true }.

FabricEndpoints

export interface FabricEndpoints {
    fabricApi: string;
    powerBiApi: string;
}

| Property | Meaning | | --- | --- | | fabricApi | Fabric REST API base URL. | | powerBiApi | Power BI REST API base URL used for DAX execution. |

DEFAULT_ENDPOINTS

export const DEFAULT_ENDPOINTS: FabricEndpoints = {
    fabricApi: "https://api.fabric.microsoft.com/v1",
    powerBiApi: "https://api.powerbi.com/v1.0/myorg",
};

Key Constraints & Gotchas

This is the Node.js proxy, NOT the embedded proxy

// ✅ DO: Use DirectFabricApiProxy for local dev / Node.js
import { DirectFabricApiProxy } from "@microsoft/fabric-app-data-cli-proxy";

// ❌ DON'T: Use this package inside a Fabric iframe — use @microsoft/fabric-app-data-proxy instead

Token provider is always required

// ✅ DO: Pass a token provider to the constructor
const proxy = new DirectFabricApiProxy(tokenProvider);

// ❌ DON'T: Try to create without a token provider — it will fail

Only semantic model DAX is implemented

• semanticModel.executeDax(...) and semanticModel.executeDaxJson(...) work.
• lakehouse.executeSql(...) and warehouse.executeSql(...) throw Error("Not implemented").

401 retry is limited

• On HTTP 401, the client retries once with forceRefresh: true.
• No retry policy for 429 or 5xx errors.

workspaceId: "me" omits the /groups/ path segment

• When workspaceId === "me", the request URL omits /groups/{workspaceId} for My Workspace access.

Minimal Usage Examples

Create a proxy with a token provider and pass it to FabricClient

import { FabricClient } from "@microsoft/fabric-app-data";
import { DirectFabricApiProxy } from "@microsoft/fabric-app-data-cli-proxy";
import { MsalNodeTokenProvider } from "@powerbi/lyra-fabric-auth";

const tokenProvider = new MsalNodeTokenProvider();
const proxy = new DirectFabricApiProxy(tokenProvider);

const fabric = new FabricClient({
    proxy,
    semanticModels: {
        salesModel: {
            workspaceId: "00000000-0000-0000-0000-000000000000",
            itemId: "11111111-1111-1111-1111-111111111111",
        },
    },
});

Custom endpoint configuration

import { DirectFabricApiProxy } from "@microsoft/fabric-app-data-cli-proxy";
import { MsalNodeTokenProvider } from "@powerbi/lyra-fabric-auth";

const tokenProvider = new MsalNodeTokenProvider();

const proxy = new DirectFabricApiProxy(tokenProvider, {
    endpoints: {
        fabricApi: "https://dailyapi.fabric.microsoft.com/v1",
        powerBiApi: "https://dailyapi.powerbi.com/v1.0/myorg",
    },
    sessionId: "local-dev-session",
});

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

Security

Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations.

Please do not report security vulnerabilities through public GitHub issues.

For security reporting information, locations, contact information, and policies, please review the latest guidance for Microsoft repositories at https://aka.ms/SECURITY.md.

Code of conduct

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

See full Microsoft Open Source Code of Conduct