@sbroenne/dvq 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sbroenne
+
+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,179 @@
+# dvq
+
+`dvq` is a small CLI and Node.js library for querying Dataverse OData endpoints with Azure CLI credentials.
+
+## What exists today
+
+- CLI for running OData paths against `/api/data/v9.2/`
+- Azure authentication via `az login`
+- Pretty-printed JSON output
+- Library helpers for URL building, token acquisition, single requests, and paginated requests
+
+## Install
+
+```bash
+npm install @sbroenne/dvq
+```
+
+Run without installing:
+
+```bash
+npx @sbroenne/dvq --help
+```
+
+## Requirements
+
+- Node.js 20 or later
+- Azure CLI (`az`)
+- Access to a Dataverse environment
+
+Authenticate once before using the CLI or library:
+
+```bash
+az login
+```
+
+For development and release validation, `npm test` runs the unit suite and `npm run test:integration` runs the live Dataverse checks when `.env.integration` is configured.
+
+## Configuration
+
+Set the base environment URL:
+
+```bash
+export DATAVERSE_URL="https://yourorg.crm.dynamics.com"
+```
+
+You can also pass `--url` on the CLI instead of setting `DATAVERSE_URL`.
+
+## CLI quick start
+
+The query is an OData path relative to `/api/data/v9.2/`.
+
+```bash
+dvq "accounts?$top=5"
+```
+
+With an explicit URL:
+
+```bash
+dvq --url "https://yourorg.crm.dynamics.com" "accounts?$select=name&$top=5"
+```
+
+From a file:
+
+```bash
+dvq --file query.odata
+```
+
+From stdin:
+
+```bash
+echo "accounts?$top=5" | dvq --url "https://yourorg.crm.dynamics.com"
+```
+
+Verify auth and connectivity:
+
+```bash
+dvq --whoami
+```
+
+Follow `@odata.nextLink` pages automatically:
+
+```bash
+dvq --all "accounts?$select=name"
+```
+
+## CLI usage
+
+```bash
+dvq [options] [query]
+```
+
+| Option | Argument | Description |
+| --- | --- | --- |
+| `[query]` | OData path | Inline query path after `/api/data/v9.2/` |
+| `-f, --file` | `<path>` | Read the OData path from a file |
+| `-a, --all` | — | Follow `@odata.nextLink` pages up to the built-in safety cap |
+| `-u, --url` | `<url>` | Use this Dataverse base URL instead of `DATAVERSE_URL` |
+| `--whoami` | — | Call `WhoAmI` and print the response |
+| `--version` | — | Print the package version |
+| `--help` | — | Show help text |
+
+Notes:
+
+- If neither `[query]` nor `--file` is given, `dvq` reads stdin when input is piped.
+- Without `--all`, the CLI prints the first JSON response object exactly as returned by Dataverse.
+- With `--all`, the CLI prints a JSON array aggregated across pages.
+
+## Library API
+
+The package currently exports low-level helpers from `src/lib.ts`, not a single high-level `query()` function.
+
+### Common request flow
+
+```ts
+import { buildUrl, fetchOData, getToken } from '@sbroenne/dvq';
+
+const baseUrl = 'https://yourorg.crm.dynamics.com';
+const token = await getToken({ baseUrl });
+const url = buildUrl('accounts?$top=5', baseUrl);
+const data = await fetchOData(url, token);
+
+console.log(data);
+```
+
+### Fetch all pages
+
+```ts
+import { getToken, queryAll } from '@sbroenne/dvq';
+
+const baseUrl = 'https://yourorg.crm.dynamics.com';
+const token = await getToken({ baseUrl });
+const rows = await queryAll('accounts?$select=name', token, baseUrl);
+
+console.log(rows);
+```
+
+### Main exports
+
+| Export | Purpose |
+| --- | --- |
+| `resolveDataverseUrl`, `getDataverseUrl` | Resolve the Dataverse base URL from an explicit value or `DATAVERSE_URL` |
+| `getDataverseScope` | Build the `/.default` scope for Azure auth |
+| `buildUrl` | Build a full Dataverse Web API URL from an OData path |
+| `buildHeaders` | Create request headers for Dataverse JSON calls |
+| `getToken` | Acquire an access token using `AzureCliCredential` |
+| `fetchOData` | Execute one HTTP request and parse the JSON response |
+| `queryAll` | Follow paginated `@odata.nextLink` responses and return one array |
+| `readQueryFile`, `readStdin` | CLI-oriented input helpers |
+| `ODataError` | Error type for non-2xx HTTP responses |
+| `API_PATH`, `DEFAULT_API_PATH`, `MAX_PAGES` | Public constants used by the helpers |
+
+## Errors and behavior
+
+Missing configuration:
+
+```text
+DATAVERSE_URL environment variable is required.
+```
+
+Authentication failure:
+
+```text
+Failed to get token. Run:
+  az login
+```
+
+`queryAll()` stops after `MAX_PAGES` pages and throws if the safety cap is exceeded.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Security
+
+Please do not report suspected vulnerabilities in public issues. See [SECURITY.md](./SECURITY.md) for the current reporting path and maintainer security checklist.
+
+## License
+
+MIT © 2026 sbroenne

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export declare function createProgram(version?: string): Command;
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { Command } from 'commander';
+import { MAX_PAGES, buildUrl, fetchOData, getDataverseUrl, getToken, queryAll, readQueryFile, readStdin, } from './lib.js';
+const require = createRequire(import.meta.url);
+const { version: VERSION } = require('../package.json');
+const HELP_AFTER = `
+Environment:
+  DATAVERSE_URL   Base URL for your Dataverse org (required unless --url is provided)
+
+Prerequisites:
+  az login
+
+Examples:
+  dvq --url https://yourorg.crm.dynamics.com --whoami
+  dvq --file query.odata --all
+  DATAVERSE_URL=https://yourorg.crm.dynamics.com dvq "accounts?\\$top=5"
+  echo "accounts?\\$top=5" | dvq --url https://yourorg.crm.dynamics.com
+`;
+export function createProgram(version = VERSION) {
+    const program = new Command()
+        .name('dvq')
+        .description('Query a Dataverse environment via OData using Azure CLI credentials')
+        .version(version)
+        .option('-f, --file <path>', 'read an OData query path from a file')
+        .option('-a, --all', `follow @odata.nextLink pages (max ${MAX_PAGES})`)
+        .option('-u, --url <url>', 'use this Dataverse base URL for the request')
+        .option('--whoami', 'print the WhoAmI response to verify auth')
+        .argument('[query]', 'inline OData query path (everything after /api/data/v9.2/)')
+        .addHelpText('after', HELP_AFTER);
+    program.action(async (inlineQuery, opts) => {
+        let query = '';
+        if (opts.file) {
+            query = readQueryFile(opts.file);
+        }
+        else if (inlineQuery) {
+            query = inlineQuery;
+        }
+        else if (!opts.whoami && !process.stdin.isTTY) {
+            query = await readStdin();
+        }
+        if (!opts.whoami && !query) {
+            program.help();
+        }
+        const baseUrl = getDataverseUrl(opts.url);
+        const token = await getToken({ baseUrl });
+        if (opts.whoami) {
+            const data = await fetchOData(buildUrl('WhoAmI', baseUrl), token);
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        if (opts.all) {
+            const results = await queryAll(query, token, baseUrl);
+            console.log(JSON.stringify(results, null, 2));
+            return;
+        }
+        const data = await fetchOData(buildUrl(query, baseUrl), token);
+        console.log(JSON.stringify(data, null, 2));
+    });
+    return program;
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    await createProgram().parseAsync(argv, { from: 'user' });
+}
+const isEntrypoint = process.argv[1]
+    ? fileURLToPath(import.meta.url) === process.argv[1]
+    : false;
+if (isEntrypoint) {
+    runCli().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/lib.d.ts

@@ -0,0 +1,41 @@
+export declare const REQUIRED_DATAVERSE_URL_ERROR = "DATAVERSE_URL environment variable is required.";
+export declare const AZ_LOGIN_GUIDANCE = "Failed to get token. Run:\n  az login";
+export declare const API_PATH = "/api/data/v9.2/";
+export declare const DEFAULT_API_PATH = "/api/data/v9.2/";
+export declare const MAX_PAGES = 40;
+export interface ResolveDataverseUrlOptions {
+    env?: NodeJS.ProcessEnv;
+    url?: string | undefined;
+}
+export interface TokenCredentialLike {
+    getToken(scope: string): Promise<{
+        token: string;
+    } | null>;
+}
+interface ODataResponse {
+    value?: unknown[];
+    '@odata.nextLink'?: string;
+    error?: {
+        message?: string;
+    };
+    [key: string]: unknown;
+}
+export declare function resolveDataverseUrl(options?: ResolveDataverseUrlOptions): string;
+export declare function getDataverseUrl(baseUrl?: string, env?: NodeJS.ProcessEnv): string;
+export declare function getDataverseScope(baseUrl?: string, env?: NodeJS.ProcessEnv): string;
+export declare function buildUrl(odataPath: string, baseUrl?: string, env?: NodeJS.ProcessEnv): string;
+export declare function buildHeaders(token: string): Record<string, string>;
+export declare function getToken(options?: {
+    baseUrl?: string;
+    credential?: TokenCredentialLike;
+    env?: NodeJS.ProcessEnv;
+}): Promise<string>;
+export declare class ODataError extends Error {
+    statusCode: number;
+    constructor(statusCode: number, detail: string);
+}
+export declare function fetchOData(url: string, token: string): Promise<ODataResponse>;
+export declare function queryAll(odataPath: string, token: string, baseUrl?: string, env?: NodeJS.ProcessEnv): Promise<unknown[]>;
+export declare function readQueryFile(filePath: string): string;
+export declare function readStdin(): Promise<string>;
+export {};

package/dist/lib.js

@@ -0,0 +1,133 @@
+import * as fs from 'node:fs';
+import { AzureCliCredential } from '@azure/identity';
+export const REQUIRED_DATAVERSE_URL_ERROR = 'DATAVERSE_URL environment variable is required.';
+export const AZ_LOGIN_GUIDANCE = 'Failed to get token. Run:\n  az login';
+export const API_PATH = '/api/data/v9.2/';
+export const DEFAULT_API_PATH = API_PATH;
+export const MAX_PAGES = 40;
+function normalizeOptionalValue(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/') {
+        end -= 1;
+    }
+    return value.slice(0, end);
+}
+function trimLeadingSlashes(value) {
+    let start = 0;
+    while (start < value.length && value[start] === '/') {
+        start += 1;
+    }
+    return value.slice(start);
+}
+function normalizeBaseUrl(value) {
+    return trimTrailingSlashes(value);
+}
+export function resolveDataverseUrl(options = {}) {
+    const explicitUrl = normalizeOptionalValue(options.url);
+    if (explicitUrl) {
+        return normalizeBaseUrl(explicitUrl);
+    }
+    const envUrl = normalizeOptionalValue(options.env?.DATAVERSE_URL);
+    if (envUrl) {
+        return normalizeBaseUrl(envUrl);
+    }
+    throw new Error(REQUIRED_DATAVERSE_URL_ERROR);
+}
+export function getDataverseUrl(baseUrl, env = process.env) {
+    return resolveDataverseUrl({ env, url: baseUrl });
+}
+export function getDataverseScope(baseUrl, env = process.env) {
+    return `${getDataverseUrl(baseUrl, env)}/.default`;
+}
+export function buildUrl(odataPath, baseUrl, env = process.env) {
+    const queryPath = trimLeadingSlashes(odataPath);
+    return `${getDataverseUrl(baseUrl, env)}${API_PATH}${queryPath}`;
+}
+export function buildHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        'OData-MaxVersion': '4.0',
+        'OData-Version': '4.0',
+        Accept: 'application/json',
+        Prefer: 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"',
+    };
+}
+export async function getToken(options = {}) {
+    const credential = options.credential ?? new AzureCliCredential();
+    try {
+        const response = await credential.getToken(getDataverseScope(options.baseUrl, options.env));
+        if (!response?.token) {
+            throw new Error('Missing token response');
+        }
+        return response.token;
+    }
+    catch {
+        throw new Error(AZ_LOGIN_GUIDANCE);
+    }
+}
+export class ODataError extends Error {
+    statusCode;
+    constructor(statusCode, detail) {
+        super(`HTTP ${statusCode}: ${detail}`);
+        this.statusCode = statusCode;
+        this.name = 'ODataError';
+    }
+}
+export async function fetchOData(url, token) {
+    const response = await fetch(url, { headers: buildHeaders(token) });
+    if (!response.ok) {
+        let detail;
+        try {
+            const body = await response.json();
+            detail = body?.error?.message ?? JSON.stringify(body);
+        }
+        catch {
+            detail = response.statusText;
+        }
+        throw new ODataError(response.status, detail);
+    }
+    return response.json();
+}
+export async function queryAll(odataPath, token, baseUrl, env = process.env) {
+    let url = buildUrl(odataPath, baseUrl, env);
+    const results = [];
+    let hasNextPage = false;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const data = await fetchOData(url, token);
+        if (data.value) {
+            results.push(...data.value);
+        }
+        else {
+            return [data];
+        }
+        const nextLink = data['@odata.nextLink'];
+        hasNextPage = Boolean(nextLink);
+        if (!nextLink) {
+            break;
+        }
+        url = nextLink;
+    }
+    if (hasNextPage) {
+        throw new Error(`Query exceeded pagination safety cap (${MAX_PAGES} pages). Narrow the filter or increase MAX_PAGES.`);
+    }
+    return results;
+}
+export function readQueryFile(filePath) {
+    return fs.readFileSync(filePath, 'utf8').trim();
+}
+export function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data.trim()));
+        process.stdin.on('error', reject);
+    });
+}
+//# sourceMappingURL=lib.js.map

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@sbroenne/dvq",
+  "version": "0.1.1",
+  "description": "CLI for querying Dataverse OData endpoints with Azure CLI credentials",
+  "type": "module",
+  "bin": {
+    "dvq": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/lib.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run test:unit",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "format": "prettier --write 'src/**/*.ts'",
+    "prepublishOnly": "npm run lint && npm run build && npm test",
+    "test:unit": "vitest run --exclude src/lib.integration.test.ts",
+    "test:integration": "vitest run src/lib.integration.test.ts",
+    "format:check": "prettier --check 'src/**/*.ts'",
+    "lint:fix": "eslint src/ --fix"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dataverse",
+    "query",
+    "odata",
+    "dynamics365",
+    "cli",
+    "azure"
+  ],
+  "homepage": "https://github.com/sbroenne/dvq",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sbroenne/dvq.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sbroenne/dvq/issues"
+  },
+  "author": "sbroenne",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.13.0",
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.5.0",
+    "eslint": "^10.0.3",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vitest": "^4.1.0"
+  }
+}