PowerBI Connect

A TypeScript library for connecting to PowerBI APIs using Azure AD authentication and querying venue analytics datasets. This package provides a comprehensive client for turnover analysis, hourly data analysis, and venue performance comparison.

Installation

npm:

npm install @zxctg/powerbi-connect

pnpm:

pnpm add @zxctg/powerbi-connect

Bun:

bun add @zxctg/powerbi-connect

Local Development

1. Clone the repository:

git clone https://github.com/Zxctg/powerbi-connect.git
cd powerbi-connect

2. Install dependencies:

npm:

npm install

pnpm:

pnpm install

Bun:

bun install

3. Build the project:

npm:

npm run build

pnpm:

pnpm build

Bun:

bun run build

Setup

1. Create a .env file in your project root:

# Azure AD Configuration
CLIENT_ID=your_azure_app_client_id
TENANT_ID=your_azure_tenant_id
CLIENT_SECRET=your_azure_app_client_secret
DATASET_ID=your_powerbi_dataset_id

2. Update the values with your Azure AD application details:
   • CLIENT_ID: Your Azure AD application client ID
   • TENANT_ID: Your Azure AD tenant ID
   • CLIENT_SECRET: Your Azure AD application client secret
   • DATASET_ID: Your PowerBI dataset ID (optional)

Usage

Programmatic Usage

import { createClient } from "@zxctg/powerbi-connect";

// Create client with explicit configuration
const client = createClient({
    clientId: process.env.CLIENT_ID!,
    tenantId: process.env.TENANT_ID!,
    clientSecret: process.env.CLIENT_SECRET!,
    datasetId: process.env.DATASET_ID!,
});

// Authenticate
await client.authenticate();

// Query venue turnover data
const turnoverResults = await client.queryVenueTurnover({
    venueName: "Your Venue",
    startDate: "2024-01-01",
    endDate: "2024-01-31",
});

// Query venue hourly data
const hourlyResults = await client.queryVenueHourlyData({
    venueName: "Your Venue",
    dates: ["2024-01-01"],
    selectedHours: [
        10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 0, 1, 2, 3,
    ],
});

// Compare venue performance between periods
const comparisonResults = await client.queryVenueComparison({
    venueName: "Your Venue",
    period1StartDate: "2024-01-01",
    period1EndDate: "2024-01-31",
    period2StartDate: "2024-02-01",
    period2EndDate: "2024-02-29",
});

// Query visitors (any player with turnover) on a specific date
const dateVisitationResults = await client.queryDateVisitationPlayers({
    venueName: "Your Venue", // Optional - omit to query all venues
    date: "2024-01-15",
});

Interactive CLI

The package includes several interactive CLI commands:

Venue Turnover Analysis

npm:

npm run cli venue-turnover

pnpm:

pnpm cli venue-turnover

Bun:

bun run cli venue-turnover

Venue Hourly Data Analysis

npm:

npm run cli venue-hourly

pnpm:

pnpm cli venue-hourly

Bun:

bun run cli venue-hourly

Venue Performance Comparison

npm:

npm run cli venue-comparison

pnpm:

pnpm cli venue-comparison

Bun:

bun run cli venue-comparison

Date Visitation Analysis

npm:

npm run cli date-visitation

pnpm:

pnpm cli date-visitation

Bun:

bun run cli date-visitation

Examples

Run the example scripts to see the library in action:

npm:

# Turnover analysis example
npm run example:turnover

# Hourly data analysis example
npm run example:hourly

# Integration example (all features)
npm run example:integration

# Comparison analysis example
npm run example:comparison

# Custom fetch client examples
npm run example:custom-fetch

# Date visitation example
npm run example:date-visitation

pnpm:

# Turnover analysis example
pnpm example:turnover

# Hourly data analysis example
pnpm example:hourly

# Integration example (all features)
pnpm example:integration

# Comparison analysis example
pnpm example:comparison

# Custom fetch client examples
pnpm example:custom-fetch

# Date visitation example
pnpm example:date-visitation

Bun:

# Turnover analysis example
bun run example:turnover

# Hourly data analysis example
bun run example:hourly

# Integration example (all features)
bun run example:integration

# Comparison analysis example
bun run example:comparison

# Custom fetch client examples
bun run example:custom-fetch

# Date visitation example
bun run example:date-visitation

Features

• 🏢 Venue Turnover Analysis: Analyze external ID performance, turnover trends, and ADT (Average Daily Turnover)
• 🕐 Venue Hourly Analysis: Hour-by-hour gaming data analysis with flexible time range selection
• 🔄 Venue Comparison: Compare venue performance between two different date periods
• 📊 Rich Analytics: Calculate totals, averages, and percentage changes
• 💾 Export Functionality: Automatic JSON export of all analysis results
• 🎯 Interactive CLI: User-friendly command-line interface with prompts
• 🔐 Azure AD Integration: Secure authentication with PowerBI services

API Reference

PowerBI Client

You can create a client in two ways:

Option 1: Using the factory function (recommended)

import { createClient } from "@zxctg/powerbi-connect";

const client = createClient({
    clientId: "your-client-id",
    tenantId: "your-tenant-id",
    clientSecret: "your-client-secret",
    datasetId: "your-dataset-id",
});

Option 2: Direct instantiation

import { PowerBIClient } from "@zxctg/powerbi-connect";

const client = new PowerBIClient({
    clientId: "your-client-id",
    tenantId: "your-tenant-id",
    clientSecret: "your-client-secret",
    datasetId: "your-dataset-id",
});

Available Methods

• authenticate(): Authenticate with Azure AD
• getAvailableVenues(): Get list of venues from loyalty statistics
• getAvailableHourlyVenues(): Get list of venues from hourly gaming data
• queryVenueTurnover(options): Query venue turnover data
• queryVenueHourlyData(options): Query venue hourly gaming data
• queryVenueComparison(options): Compare venue performance between periods
• queryDateVisitationPlayers(options): Query visitors on a specific date

Types

All TypeScript interfaces are exported for type safety:

import {
    VenueTurnoverOptions,
    VenueHourlyOptions,
    VenueComparisonOptions,
    DateVisitationOptions,
    TurnoverResult,
    HourlyResult,
    ComparisonResult,
    DateVisitationResult,
} from "@zxctg/powerbi-connect";

Development

Building

npm:

npm run build

pnpm:

pnpm build

Bun:

bun run build

Cleaning Build Output

npm:

npm run clean

pnpm:

pnpm clean

Bun:

bun run clean

Project Structure

src/
├── index.ts                    # Main exports
├── powerbi-client.ts          # Core PowerBI client
├── client-factory.ts          # Client factory utilities
└── queries/                   # Query builders
    ├── index.ts              # Query exports
    ├── types.ts              # Shared types
    ├── venue-queries.ts      # Venue listing queries
    ├── turnover-queries.ts   # Turnover analysis queries
    ├── hourly-queries.ts     # Hourly data queries
    ├── comparison-queries.ts # Comparison queries
    └── schema-queries.ts     # Schema discovery queries

examples/
├── cli.ts                    # Interactive CLI
├── turnover-example.ts       # Turnover analysis example
├── hourly-example.ts         # Hourly data example
├── comparison-example.ts     # Comparison analysis example
└── integration-example.ts    # Complete integration example

License

MIT License - see LICENSE file for details.

Custom Fetch Client

The library supports custom fetch client implementations, allowing you to:

• Add request/response logging
• Implement retry logic
• Add custom headers
• Use different HTTP libraries
• Configure proxy settings

Basic Custom Fetch Client

import {
    createClientWithFetch,
    type FetchClient,
} from "@zxctg/powerbi-connect";

// Create a custom fetch client with logging
class LoggingFetchClient implements FetchClient {
    async fetch(url: string, init?: RequestInit): Promise<Response> {
        console.log(`Making request to: ${url}`);
        const response = await fetch(url, init);
        console.log(`Response: ${response.status}`);
        return response;
    }
}

// Use the custom fetch client
const client = createClientWithFetch(
    {
        clientId: process.env.CLIENT_ID!,
        tenantId: process.env.TENANT_ID!,
        clientSecret: process.env.CLIENT_SECRET!,
        datasetId: process.env.DATASET_ID!,
    },
    new LoggingFetchClient()
);

Custom Fetch Client with Retry Logic

class RetryFetchClient implements FetchClient {
    constructor(
        private maxRetries: number = 3,
        private retryDelay: number = 1000
    ) {}

    async fetch(url: string, init?: RequestInit): Promise<Response> {
        let lastError: Error;

        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
            try {
                const response = await fetch(url, init);
                if (response.ok || response.status < 500) {
                    return response;
                }
                throw new Error(`HTTP ${response.status}`);
            } catch (error) {
                lastError = error as Error;
                if (attempt < this.maxRetries) {
                    await new Promise((resolve) =>
                        setTimeout(resolve, this.retryDelay)
                    );
                }
            }
        }

        throw lastError!;
    }
}

const client = createClientWithFetch(config, new RetryFetchClient(3, 2000));

Alternative Configuration Method

You can also pass the fetch client directly in the config:

const client = createClient({
    clientId: process.env.CLIENT_ID!,
    tenantId: process.env.TENANT_ID!,
    clientSecret: process.env.CLIENT_SECRET!,
    datasetId: process.env.DATASET_ID!,
    fetchClient: new LoggingFetchClient(),
});