API and Network Utilities

/**
 * HTTP header name for the Lightdash request method
 */
const LightdashRequestMethodHeader: string;

/**
 * HTTP header name for the Lightdash version
 */
const LightdashVersionHeader: string;

/**
 * Extracts and validates the request method from a header value
 * @param headerValue - The header value to parse
 * @returns The validated request method or UNKNOWN if invalid
 */
function getRequestMethod(headerValue: string | undefined): RequestMethod;

import {
  LightdashRequestMethodHeader,
  LightdashVersionHeader,
  getRequestMethod,
  RequestMethod,
} from '@lightdash/common';

// Extract request method from headers
const headers = {
  [LightdashRequestMethodHeader]: 'dashboard',
  [LightdashVersionHeader]: '1.0.0',
};

const method = getRequestMethod(headers[LightdashRequestMethodHeader]);
// Returns: RequestMethod.DASHBOARD

// If header is missing or invalid, returns RequestMethod.UNKNOWN
const unknownMethod = getRequestMethod(undefined);
// Returns: RequestMethod.UNKNOWN

/**
 * Renders a URL template with values from query results
 * @param templatedUrl - URL template string with Liquid syntax placeholders
 * @param value - Current cell's result value
 * @param row - Complete row data for accessing other fields
 * @returns Rendered URL with values substituted
 */
function renderTemplatedUrl(
  templatedUrl: string,
  value: ResultValue,
  row: Record<string, Record<string, ResultValue>>
): string;

/**
 * Extracts field dependencies from a URL template
 * @param templatedUrl - URL template string with Liquid syntax placeholders
 * @returns Array of field IDs referenced in the template
 */
function getTemplatedUrlRowDependencies(templatedUrl: string): string[];

import {
  renderTemplatedUrl,
  getTemplatedUrlRowDependencies,
} from '@lightdash/common';

// Template with value reference
const template1 = 'https://example.com/user/${value.raw}';
const url1 = renderTemplatedUrl(template1, { raw: 123, formatted: '123' }, row);
// Returns: "https://example.com/user/123"

// Template with row references
const template2 = 'https://example.com/order/${row.orders_id.raw}/customer/${row.customers_name.formatted}';
const url2 = renderTemplatedUrl(template2, value, {
  orders_id: { raw: 456, formatted: '456' },
  customers_name: { raw: 'john', formatted: 'John' },
});
// Returns: "https://example.com/order/456/customer/John"

// Extract dependencies from template
const deps = getTemplatedUrlRowDependencies(template2);
// Returns: ["orders_id", "customers_name"]

/**
 * Creates a URL search parameter string with UUID validation
 * @param key - Parameter key name
 * @param value - UUID value (null/undefined returns empty string)
 * @returns URL parameter string or empty string if invalid
 */
function setUuidParam(key: string, value?: string | null): string;

import { setUuidParam } from '@lightdash/common';

const param = setUuidParam('projectUuid', '123e4567-e89b-12d3-a456-426614174000');
// Returns: "projectUuid=123e4567-e89b-12d3-a456-426614174000"

const invalidParam = setUuidParam('projectUuid', 'invalid-uuid');
// Returns: ""

/**
 * Recursively extracts all filter rules from a filter group
 * @param filterGroup - The filter group to extract from
 * @returns Array of all filter rules in the group
 */
function getFilterRulesFromGroup(filterGroup: FilterGroup | undefined): FilterRule[];

/**
 * Gets all filter rules from all filter types (dimensions, metrics, tableCalculations)
 * @param filters - The filters object
 * @returns Array of all filter rules
 */
function getTotalFilterRules(filters: Filters): FilterRule[];

/**
 * Counts the total number of filter rules across all filter types
 * @param filters - The filters object
 * @returns Total count of filter rules
 */
function countTotalFilterRules(filters: Filters): number;

/**
 * Checks if filters contain nested groups (groups within groups)
 * @param filters - The filters object to check
 * @returns true if nested groups exist
 */
function hasNestedGroups(filters: Filters): boolean;

/**
 * Gets the items from a filter group (either 'and' or 'or' array)
 * @param filterGroup - The filter group
 * @returns Array of filter group items
 */
function getItemsFromFilterGroup(filterGroup: FilterGroup | undefined): FilterGroupItem[];

/**
 * Gets the property name ('and' or 'or') for a filter group
 * @param filterGroup - The filter group
 * @returns 'and' or 'or'
 */
function getFilterGroupItemsPropertyName(filterGroup: FilterGroup | undefined): 'and' | 'or';

/**
 * Determines the filter type from a dimension, metric, or table calculation type
 * @param type - The field type
 * @returns The corresponding filter type (STRING, NUMBER, DATE, BOOLEAN)
 */
function getFilterTypeFromItemType(
  type: DimensionType | MetricType | TableCalculationType
): FilterType;

import {
  getFilterRulesFromGroup,
  getTotalFilterRules,
  countTotalFilterRules,
  hasNestedGroups,
} from '@lightdash/common';

// Count all filter rules
const count = countTotalFilterRules(metricQuery.filters);
console.log(`Total filters: ${count}`);

// Check for complex filter structures
if (hasNestedGroups(metricQuery.filters)) {
  console.log('Query has nested filter groups');
}

// Extract all dimension filter rules
const dimensionRules = getFilterRulesFromGroup(metricQuery.filters.dimensions);
dimensionRules.forEach(rule => {
  console.log(`Filter on ${rule.target.fieldId}: ${rule.operator}`);
});