@sbroenne/dvq 0.1.2 → 0.1.5

package/README.md

@@ -45,6 +45,10 @@ export DATAVERSE_URL="https://yourorg.crm.dynamics.com"
 
 You can also pass `--url` on the CLI instead of setting `DATAVERSE_URL`.
 
+By default, `dvq` requests Dataverse formatted-value annotations so OptionSet labels and other display values are present in responses. Use `--no-formatted-values` to disable that default, or `--header` to add custom request headers when debugging environment-specific behavior.
+
+Use `--verbose` to emit request tracing to stderr. This is useful when you need to see the exact request URL, pagination flow, and sanitized headers without mixing trace output into the JSON response on stdout.
+
 ## CLI quick start
 
 The query is an OData path relative to `/api/data/v9.2/`.
@@ -77,6 +81,24 @@ Verify auth and connectivity:
 dvq --whoami
 ```
 
+Disable formatted-value annotations for a leaner payload or to isolate header-related issues:
+
+```bash
+dvq --url "https://yourorg.crm.dynamics.com" --no-formatted-values "accounts?$top=5"
+```
+
+Add custom request headers:
+
+```bash
+dvq --url "https://yourorg.crm.dynamics.com" -H "ConsistencyLevel: eventual" "accounts?$top=5"
+```
+
+Trace auth, request, and pagination flow to stderr:
+
+```bash
+dvq --verbose --url "https://yourorg.crm.dynamics.com" --all "accounts?$select=name&$top=5"
+```
+
 Follow `@odata.nextLink` pages automatically:
 
 ```bash
@@ -95,6 +117,9 @@ dvq [options] [query]
 | `-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` |
+| `-v, --verbose` | — | Print auth/request/pagination tracing to stderr |
+| `--no-formatted-values` | — | Do not send the default `Prefer` header for formatted values |
+| `-H, --header` | `<name:value>` | Add a request header; may be repeated |
 | `--whoami` | — | Call `WhoAmI` and print the response |
 | `--version` | — | Print the package version |
 | `--help` | — | Show help text |
@@ -104,6 +129,8 @@ 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.
+- By default, `dvq` sends `Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue"`.
+- `--verbose` writes tracing to stderr and never prints the bearer token.
 
 ## Library API
 
@@ -141,10 +168,10 @@ console.log(rows);
 | `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 |
+| `buildHeaders` | Create request headers for Dataverse JSON calls, with optional annotation/header overrides |
 | `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 |
+| `fetchOData` | Execute one HTTP request and parse the JSON response, with optional request overrides |
+| `queryAll` | Follow paginated `@odata.nextLink` responses and return one array, with optional request overrides |
 | `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 |
@@ -162,10 +189,19 @@ Authentication failure:
 ```text
 Failed to get token. Run:
   az login
+Target: https://yourorg.crm.dynamics.com
 ```
 
 `queryAll()` stops after `MAX_PAGES` pages and throws if the safety cap is exceeded.
 
+Dataverse request failures now include the request URL and, when possible, a targeted troubleshooting hint. Example for the header-related 400 seen on some entity reads:
+
+```text
+HTTP 400: Both header name and value should be specified.
+URL: https://yourorg.crm.dynamics.com/api/data/v9.2/msp_accountteams?$top=5
+Hint: Dataverse rejected a request header. Retry with formatted values disabled to isolate the default Prefer header, and review any custom headers.
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md).

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
-import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 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 INVALID_HEADER_GUIDANCE = 'Invalid header. Use the form "Name: Value".';
 const HELP_AFTER = `
 Environment:
   DATAVERSE_URL   Base URL for your Dataverse org (required unless --url is provided)
@@ -15,9 +18,43 @@ Prerequisites:
 Examples:
   dvq --url https://yourorg.crm.dynamics.com --whoami
   dvq --file query.odata --all
+  dvq --verbose --url https://yourorg.crm.dynamics.com --file query.odata
+  dvq --url https://yourorg.crm.dynamics.com --no-formatted-values "accounts?$top=5"
+  dvq --url https://yourorg.crm.dynamics.com -H "ConsistencyLevel: eventual" "accounts?$top=5"
   DATAVERSE_URL=https://yourorg.crm.dynamics.com dvq "accounts?\\$top=5"
   echo "accounts?\\$top=5" | dvq --url https://yourorg.crm.dynamics.com
 `;
+function collectHeader(value, previous = []) {
+    previous.push(value);
+    return previous;
+}
+export function parseHeaders(headerValues = []) {
+    return headerValues.reduce((headers, headerValue) => {
+        const separatorIndex = headerValue.indexOf(':');
+        if (separatorIndex <= 0) {
+            throw new Error(`${INVALID_HEADER_GUIDANCE} Received: ${headerValue}`);
+        }
+        const name = headerValue.slice(0, separatorIndex).trim();
+        const value = headerValue.slice(separatorIndex + 1).trim();
+        if (!name || !value) {
+            throw new Error(`${INVALID_HEADER_GUIDANCE} Received: ${headerValue}`);
+        }
+        headers[name] = value;
+        return headers;
+    }, {});
+}
+function toRequestOptions(opts) {
+    const logger = opts.verbose
+        ? (message) => {
+            console.error(`[dvq] ${message}`);
+        }
+        : undefined;
+    return {
+        includeFormattedValues: opts.formattedValues,
+        headers: parseHeaders(opts.header),
+        logger,
+    };
+}
 export function createProgram(version = VERSION) {
     const program = new Command()
         .name('dvq')
@@ -26,6 +63,9 @@ export function createProgram(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('-v, --verbose', 'print request tracing to stderr')
+        .option('--no-formatted-values', 'do not request OData formatted value annotations')
+        .option('-H, --header <name:value>', 'add a request header; may be repeated', collectHeader, [])
         .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);
@@ -44,18 +84,22 @@ export function createProgram(version = VERSION) {
             program.help();
         }
         const baseUrl = getDataverseUrl(opts.url);
-        const token = await getToken({ baseUrl });
+        const requestOptions = toRequestOptions(opts);
+        const token = await getToken({
+            baseUrl,
+            logger: requestOptions.logger,
+        });
         if (opts.whoami) {
-            const data = await fetchOData(buildUrl('WhoAmI', baseUrl), token);
+            const data = await fetchOData(buildUrl('WhoAmI', baseUrl), token, requestOptions);
             console.log(JSON.stringify(data, null, 2));
             return;
         }
         if (opts.all) {
-            const results = await queryAll(query, token, baseUrl);
+            const results = await queryAll(query, token, baseUrl, process.env, requestOptions);
             console.log(JSON.stringify(results, null, 2));
             return;
         }
-        const data = await fetchOData(buildUrl(query, baseUrl), token);
+        const data = await fetchOData(buildUrl(query, baseUrl), token, requestOptions);
         console.log(JSON.stringify(data, null, 2));
     });
     return program;
@@ -63,10 +107,14 @@ export function createProgram(version = VERSION) {
 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) {
+export function isCliEntrypoint(metaUrl, argv = process.argv) {
+    const entrypoint = argv[1];
+    if (!entrypoint) {
+        return false;
+    }
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(resolve(entrypoint));
+}
+if (import.meta.main ?? isCliEntrypoint(import.meta.url)) {
     runCli().catch((error) => {
         const message = error instanceof Error ? error.message : String(error);
         console.error(message);

package/dist/lib.d.ts

@@ -3,6 +3,12 @@ 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 type TraceLogger = (message: string) => void;
+export interface RequestOptions {
+    includeFormattedValues?: boolean;
+    headers?: Record<string, string>;
+    logger?: TraceLogger;
+}
 export interface ResolveDataverseUrlOptions {
     env?: NodeJS.ProcessEnv;
     url?: string | undefined;
@@ -20,22 +26,35 @@ interface ODataResponse {
     };
     [key: string]: unknown;
 }
+export declare function getODataErrorHint(statusCode: number, detail: string): string | undefined;
+export declare function formatODataErrorMessage(statusCode: number, detail: string, options?: {
+    requestUrl?: string;
+    hint?: string;
+}): string;
+export declare function formatAuthFailureMessage(baseUrl: string): string;
 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 buildHeaders(token: string, options?: RequestOptions): Record<string, string>;
 export declare function getToken(options?: {
     baseUrl?: string;
     credential?: TokenCredentialLike;
     env?: NodeJS.ProcessEnv;
+    logger?: TraceLogger;
 }): Promise<string>;
 export declare class ODataError extends Error {
     statusCode: number;
-    constructor(statusCode: number, detail: string);
+    detail: string;
+    hint?: string;
+    requestUrl?: string;
+    constructor(statusCode: number, detail: string, options?: {
+        hint?: string;
+        requestUrl?: 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 fetchOData(url: string, token: string, options?: RequestOptions): Promise<ODataResponse>;
+export declare function queryAll(odataPath: string, token: string, baseUrl?: string, env?: NodeJS.ProcessEnv, options?: RequestOptions): Promise<unknown[]>;
 export declare function readQueryFile(filePath: string): string;
 export declare function readStdin(): Promise<string>;
 export {};

package/dist/lib.js

@@ -5,6 +5,50 @@ 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 formatDiagnosticBlock(label, value) {
+    return `${label}: ${value}`;
+}
+function trace(logger, message) {
+    logger?.(message);
+}
+function sanitizeHeadersForLogging(headers) {
+    return Object.fromEntries(Object.entries(headers).map(([name, value]) => [
+        name,
+        name.toLowerCase() === 'authorization' ? '<redacted>' : value,
+    ]));
+}
+export function getODataErrorHint(statusCode, detail) {
+    if (statusCode === 400) {
+        if (detail.includes('Both header name and value should be specified.')) {
+            return 'Dataverse rejected a request header. Retry with formatted values disabled to isolate the default Prefer header, and review any custom headers.';
+        }
+        return 'Check the OData path, entity set names, filter syntax, and any request headers. For CLI debugging, retry with --no-formatted-values to isolate header-related issues.';
+    }
+    if (statusCode === 401 || statusCode === 403) {
+        return 'Run az login again and verify that the selected account has access to this Dataverse environment.';
+    }
+    if (statusCode === 404) {
+        return 'Verify the entity set name, record ID, and OData path.';
+    }
+    if (statusCode === 429) {
+        return 'The environment is throttling requests. Retry after a delay or narrow the query.';
+    }
+    return undefined;
+}
+export function formatODataErrorMessage(statusCode, detail, options = {}) {
+    const lines = [`HTTP ${statusCode}: ${detail}`];
+    if (options.requestUrl) {
+        lines.push(formatDiagnosticBlock('URL', options.requestUrl));
+    }
+    const hint = options.hint ?? getODataErrorHint(statusCode, detail);
+    if (hint) {
+        lines.push(formatDiagnosticBlock('Hint', hint));
+    }
+    return lines.join('\n');
+}
+export function formatAuthFailureMessage(baseUrl) {
+    return [AZ_LOGIN_GUIDANCE, formatDiagnosticBlock('Target', baseUrl)].join('\n');
+}
 function normalizeOptionalValue(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
@@ -47,38 +91,61 @@ export function buildUrl(odataPath, baseUrl, env = process.env) {
     const queryPath = trimLeadingSlashes(odataPath);
     return `${getDataverseUrl(baseUrl, env)}${API_PATH}${queryPath}`;
 }
-export function buildHeaders(token) {
-    return {
+export function buildHeaders(token, options = {}) {
+    const headers = {
         Authorization: `Bearer ${token}`,
         'OData-MaxVersion': '4.0',
         'OData-Version': '4.0',
         Accept: 'application/json',
-        Prefer: 'odata.include-annotations="OData.Community.Display.V1.FormattedValue"',
+    };
+    if (options.includeFormattedValues !== false) {
+        headers.Prefer =
+            'odata.include-annotations="OData.Community.Display.V1.FormattedValue"';
+    }
+    return {
+        ...headers,
+        ...options.headers,
     };
 }
 export async function getToken(options = {}) {
+    const baseUrl = getDataverseUrl(options.baseUrl, options.env);
     const credential = options.credential ?? new AzureCliCredential();
+    const scope = getDataverseScope(baseUrl);
+    trace(options.logger, `Auth target: ${baseUrl}`);
+    trace(options.logger, `Auth scope: ${scope}`);
     try {
-        const response = await credential.getToken(getDataverseScope(options.baseUrl, options.env));
+        const response = await credential.getToken(scope);
         if (!response?.token) {
             throw new Error('Missing token response');
         }
+        trace(options.logger, 'Token acquired successfully');
         return response.token;
     }
     catch {
-        throw new Error(AZ_LOGIN_GUIDANCE);
+        trace(options.logger, 'Token acquisition failed');
+        throw new Error(formatAuthFailureMessage(baseUrl));
     }
 }
 export class ODataError extends Error {
     statusCode;
-    constructor(statusCode, detail) {
-        super(`HTTP ${statusCode}: ${detail}`);
+    detail;
+    hint;
+    requestUrl;
+    constructor(statusCode, detail, options = {}) {
+        super(formatODataErrorMessage(statusCode, detail, options));
         this.statusCode = statusCode;
         this.name = 'ODataError';
+        this.detail = detail;
+        this.hint = options.hint ?? getODataErrorHint(statusCode, detail);
+        this.requestUrl = options.requestUrl;
     }
 }
-export async function fetchOData(url, token) {
-    const response = await fetch(url, { headers: buildHeaders(token) });
+export async function fetchOData(url, token, options = {}) {
+    const headers = buildHeaders(token, options);
+    trace(options.logger, `GET ${url}`);
+    trace(options.logger, `Headers ${JSON.stringify(sanitizeHeadersForLogging(headers))}`);
+    const response = await fetch(url, { headers });
+    trace(options.logger, `Response ${response.status} ${response.statusText}`);
     if (!response.ok) {
         let detail;
         try {
@@ -88,27 +155,39 @@ export async function fetchOData(url, token) {
         catch {
             detail = response.statusText;
         }
-        throw new ODataError(response.status, detail);
+        trace(options.logger, `Error detail ${detail}`);
+        throw new ODataError(response.status, detail, {
+            hint: getODataErrorHint(response.status, detail),
+            requestUrl: url,
+        });
     }
-    return response.json();
+    const data = await response.json();
+    trace(options.logger, 'Response body parsed successfully');
+    return data;
 }
-export async function queryAll(odataPath, token, baseUrl, env = process.env) {
+export async function queryAll(odataPath, token, baseUrl, env = process.env, options = {}) {
     let url = buildUrl(odataPath, baseUrl, env);
     const results = [];
     let hasNextPage = false;
+    trace(options.logger, `Starting paged query for ${odataPath}`);
     for (let page = 0; page < MAX_PAGES; page += 1) {
-        const data = await fetchOData(url, token);
+        trace(options.logger, `Fetching page ${page + 1}`);
+        const data = await fetchOData(url, token, options);
         if (data.value) {
             results.push(...data.value);
+            trace(options.logger, `Collected ${results.length} rows total`);
         }
         else {
+            trace(options.logger, 'Received a non-collection response; returning wrapped result');
             return [data];
         }
         const nextLink = data['@odata.nextLink'];
         hasNextPage = Boolean(nextLink);
         if (!nextLink) {
+            trace(options.logger, `Pagination complete after ${page + 1} page(s)`);
             break;
         }
+        trace(options.logger, 'Following @odata.nextLink');
         url = nextLink;
     }
     if (hasNextPage) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sbroenne/dvq",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "CLI for querying Dataverse OData endpoints with Azure CLI credentials",
   "type": "module",
   "bin": {