adapty 0.11.0 → 0.12.0

package/dist/sdk/adapty/analytics/model.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What the six analytics operations share: one answer shape, so one parser reads all of them. Answers pass
+ * through as the server sends them, in snake_case: that object is what --json prints.
+ *
+ * `data.segments` starts with the total (`is_total` true); every other segment is one group, and its `key` is the
+ * raw value that the backend gives for that group. No rows for the window: `segments` is empty.
+ * A number is the backend's number: 0 stays 0, and null means the backend has no value.
+ */
+/** The vocabularies of the query fields, in the order the catalog lists them. */
+export declare const periodUnits: readonly ["day", "week", "month", "quarter", "year"];
+export type PeriodUnit = (typeof periodUnits)[number];
+export declare const revenueBases: readonly ["gross", "proceeds", "net"];
+export type RevenueBasis = (typeof revenueBases)[number];
+export declare const periodTypes: readonly ["renewals", "days"];
+export type PeriodType = (typeof periodTypes)[number];
+export type AnalyticsSegment = {
+    /** The one way to tell the total from a group: a group's `key` can be null too. */
+    is_total: boolean;
+    /**
+     * The raw value that the backend gives for the group, as the dashboard has it; null for the total. Any value is
+     * possible, null, `""` and `"None"` (a "No Data" group) included. It is not promised to be a `--filter` value.
+     */
+    key: null | string;
+    /** The backend title, "No Data" included. */
+    title: string;
+};
+/**
+ * The query that ran: every field of the operation with its default, the filters as sent, the time zone and
+ * where it comes from (`request` for `--timezone`, else `app`).
+ */
+export type ResolvedQuery<Fields> = Fields & {
+    filters: Record<string, string[]>;
+    timezone: string;
+    timezone_source: 'app' | 'request';
+};
+export type AnalyticsMeta<Fields = Record<string, unknown>> = {
+    query: ResolvedQuery<Fields>;
+};
+/** One amount in USD on each revenue basis. */
+export type Money = {
+    gross: number;
+    net: number;
+    proceeds: number;
+};
+export type AnalyticsResponse<Data, Meta> = {
+    data: Data;
+    meta: Meta;
+};
+/** Every data answer has these: the main number and the segments, total first. */
+export type AnalyticsData<Segment extends AnalyticsSegment> = {
+    segments: Segment[];
+    value: null | number;
+};

package/dist/sdk/adapty/analytics/model.js

@@ -0,0 +1,12 @@
+/**
+ * What the six analytics operations share: one answer shape, so one parser reads all of them. Answers pass
+ * through as the server sends them, in snake_case: that object is what --json prints.
+ *
+ * `data.segments` starts with the total (`is_total` true); every other segment is one group, and its `key` is the
+ * raw value that the backend gives for that group. No rows for the window: `segments` is empty.
+ * A number is the backend's number: 0 stays 0, and null means the backend has no value.
+ */
+/** The vocabularies of the query fields, in the order the catalog lists them. */
+export const periodUnits = ['day', 'week', 'month', 'quarter', 'year'];
+export const revenueBases = ['gross', 'proceeds', 'net'];
+export const periodTypes = ['renewals', 'days'];

package/dist/sdk/adapty/analytics/query.d.ts

@@ -0,0 +1,48 @@
+import type { PeriodUnit } from './model.js';
+import type { Issue } from '../../core/errors.js';
+/** One filter: a dimension key from the catalog and the raw values it keeps (any of them). */
+export type AnalyticsFilter = {
+    dimension: string;
+    values: readonly string[];
+};
+/** What every operation takes. Dates are inclusive days of the query time zone, `YYYY-MM-DD`. */
+export type AnalyticsQueryInput = {
+    appId: string;
+    dateFrom: string;
+    dateTo: string;
+    filters?: readonly AnalyticsFilter[] | undefined;
+    /** An IANA name; the app time zone when left out. Which names exist is the backend's knowledge. */
+    timezone?: string | undefined;
+};
+/** The two operations whose query keeps two periods apart: a chart and a conversion. */
+export type ComparableQueryInput = AnalyticsQueryInput & {
+    compareFrom?: string | undefined;
+    compareTo?: string | undefined;
+};
+/** `date` and `compare_date` are `[start, end]`; every other key is a dimension with its values. */
+export type FiltersRequest = Record<string, string[]>;
+export type QueryRequest = {
+    filters: FiltersRequest;
+    timezone?: string;
+};
+export declare const validateQuery: (input: AnalyticsQueryInput) => Issue[];
+/** A compared period is both ends or neither, and a real range: the backend has no default for half of one. */
+export declare const validateComparableQuery: (input: ComparableQueryInput) => Issue[];
+/**
+ * The fields every operation sends. Filters are a map of dimension to values, as the dashboard sends them: two
+ * filters of one dimension become one list (a value kept by either is kept by the union), each value once.
+ * An absent timezone is left out, so the backend applies the app zone and says so in `meta.query`.
+ */
+export declare const toQueryRequest: (input: ComparableQueryInput) => QueryRequest;
+/** The grouping and the period of one point, as the operations that take them name them. */
+export type GroupingInput = {
+    granularity?: PeriodUnit | undefined;
+    /** A grouping key of the operation (of the chart, for a chart), as the catalog lists it. */
+    groupBy?: string | undefined;
+};
+export type GroupingRequest = {
+    period_unit?: PeriodUnit;
+    segmentation?: string;
+};
+/** The input names meet the API names here, once for every operation; a field left out stays out. */
+export declare const toGroupingRequest: (input: GroupingInput) => GroupingRequest;

package/dist/sdk/adapty/analytics/query.js

@@ -0,0 +1,52 @@
+import { validateDayRange } from '../../core/dates.js';
+/** The period has flags of its own; as a filter it would replace them without a word. */
+const PERIOD_KEYS = new Set(['compare_date', 'date']);
+export const validateQuery = (input) => {
+    const issues = validateDayRange(input.dateFrom, input.dateTo, { from: 'dateFrom', to: 'dateTo' });
+    for (const filter of input.filters ?? []) {
+        if (PERIOD_KEYS.has(filter.dimension)) {
+            issues.push({ message: `${filter.dimension} is not a filter: the period has flags of its own`, path: 'filter' });
+        }
+    }
+    return issues;
+};
+/** A compared period is both ends or neither, and a real range: the backend has no default for half of one. */
+export const validateComparableQuery = (input) => {
+    const issues = validateQuery(input);
+    const { compareFrom, compareTo } = input;
+    if (compareFrom === undefined && compareTo === undefined) {
+        return issues;
+    }
+    if (compareFrom === undefined) {
+        return [...issues, { fields: ['compareTo'], message: 'required with {compareTo}', path: 'compareFrom' }];
+    }
+    if (compareTo === undefined) {
+        return [...issues, { fields: ['compareFrom'], message: 'required with {compareFrom}', path: 'compareTo' }];
+    }
+    return [...issues, ...validateDayRange(compareFrom, compareTo, { from: 'compareFrom', to: 'compareTo' })];
+};
+/**
+ * The fields every operation sends. Filters are a map of dimension to values, as the dashboard sends them: two
+ * filters of one dimension become one list (a value kept by either is kept by the union), each value once.
+ * An absent timezone is left out, so the backend applies the app zone and says so in `meta.query`.
+ */
+export const toQueryRequest = (input) => {
+    const filters = { date: [input.dateFrom, input.dateTo] };
+    if (input.compareFrom !== undefined && input.compareTo !== undefined) {
+        filters.compare_date = [input.compareFrom, input.compareTo];
+    }
+    for (const filter of input.filters ?? []) {
+        const known = filters[filter.dimension] ?? [];
+        filters[filter.dimension] = [...new Set([...known, ...filter.values])];
+    }
+    const body = { filters };
+    if (input.timezone !== undefined) {
+        body.timezone = input.timezone;
+    }
+    return body;
+};
+/** The input names meet the API names here, once for every operation; a field left out stays out. */
+export const toGroupingRequest = (input) => ({
+    ...(input.granularity === undefined ? {} : { period_unit: input.granularity }),
+    ...(input.groupBy === undefined ? {} : { segmentation: input.groupBy }),
+});

package/dist/sdk/adapty/analytics/renewal-periods.d.ts

@@ -0,0 +1,23 @@
+import type { PeriodType, RevenueBasis } from './model.js';
+import type { AnalyticsQueryInput, QueryRequest } from './query.js';
+import type { Issue } from '../../core/errors.js';
+/** What LTV and cohorts share: revenue on a basis, counted per renewal or per day. */
+export type RenewalPeriodsInput = AnalyticsQueryInput & {
+    periodType?: PeriodType | undefined;
+    /** Whole days, 0 or more; only with `periodType: 'days'`. The backend list applies when left out. */
+    renewalDays?: readonly number[] | undefined;
+    revenueBasis?: RevenueBasis | undefined;
+};
+/** The fields of the resolved query that LTV and cohorts share. */
+export type RenewalPeriodsQuery = {
+    period_type: PeriodType;
+    renewal_days: null | number[];
+    revenue_basis: RevenueBasis;
+};
+export type RenewalPeriodsRequest = QueryRequest & {
+    period_type?: PeriodType;
+    renewal_days?: number[];
+    revenue_basis?: RevenueBasis;
+};
+export declare const validateRenewalPeriods: (input: RenewalPeriodsInput) => Issue[];
+export declare const toRenewalPeriodsRequest: (input: RenewalPeriodsInput) => RenewalPeriodsRequest;

package/dist/sdk/adapty/analytics/renewal-periods.js

@@ -0,0 +1,27 @@
+import { toQueryRequest, validateQuery } from './query.js';
+export const validateRenewalPeriods = (input) => {
+    const issues = validateQuery(input);
+    if (input.renewalDays !== undefined && input.periodType !== 'days') {
+        issues.push({ fields: ['periodType'], message: 'needs {periodType} days', path: 'renewalDays' });
+    }
+    // The backend reads the list as given: whole days, ascending, each once; anything else it refuses
+    const days = input.renewalDays ?? [];
+    const ordered = days.every((day, index) => index === 0 || day > (days[index - 1] ?? day));
+    if (days.some(day => !Number.isInteger(day) || day < 0) || !ordered) {
+        issues.push({ message: 'must be whole days, 0 or more, in ascending order, each day once', path: 'renewalDays' });
+    }
+    return issues;
+};
+export const toRenewalPeriodsRequest = (input) => {
+    const body = toQueryRequest(input);
+    if (input.revenueBasis !== undefined) {
+        body.revenue_basis = input.revenueBasis;
+    }
+    if (input.periodType !== undefined) {
+        body.period_type = input.periodType;
+    }
+    if (input.renewalDays !== undefined) {
+        body.renewal_days = [...input.renewalDays];
+    }
+    return body;
+};

package/dist/sdk/adapty/analytics/resource.d.ts

@@ -0,0 +1,29 @@
+import type { CatalogResponse } from './catalog.js';
+import type { ChartInput, ChartResponse } from './chart.js';
+import type { CohortInput, CohortResponse } from './cohort.js';
+import type { ConversionInput, ConversionResponse } from './conversion.js';
+import type { FunnelInput, FunnelResponse } from './funnel.js';
+import type { LtvInput, LtvResponse } from './ltv.js';
+import type { RetentionInput, RetentionResponse } from './retention.js';
+import type { FilterValuesInput, FilterValuesResponse } from './values.js';
+import type { Http } from '../../core/http/index.js';
+/**
+ * Every path of the analytics of an app in one place. The catalog and the values are GETs and keep the
+ * transport's retry. The six operations are POSTs that run analytics queries under the rate limits of each route
+ * (2 requests per second per app and 360 per minute for all callers together, as the Export API): sent once,
+ * never retried, and a 429 reaches the caller with the server's wait.
+ *
+ * The validating methods are async on purpose — a broken rule then arrives as a rejected promise, like a
+ * network failure, and one await covers both.
+ */
+export declare const analytics: (http: Http) => {
+    catalog: (appId: string) => Promise<CatalogResponse>;
+    chart: (input: ChartInput) => Promise<ChartResponse>;
+    cohort: (input: CohortInput) => Promise<CohortResponse>;
+    conversion: (input: ConversionInput) => Promise<ConversionResponse>;
+    funnel: (input: FunnelInput) => Promise<FunnelResponse>;
+    ltv: (input: LtvInput) => Promise<LtvResponse>;
+    retention: (input: RetentionInput) => Promise<RetentionResponse>;
+    values: (input: FilterValuesInput) => Promise<FilterValuesResponse>;
+};
+export type AnalyticsApi = ReturnType<typeof analytics>;

package/dist/sdk/adapty/analytics/resource.js

@@ -0,0 +1,72 @@
+import { ApiError } from '../../core/errors.js';
+import { assertValid } from '../../core/validation.js';
+import { toChartRequest, validateChart } from './chart.js';
+import { toCohortRequest, validateCohort } from './cohort.js';
+import { toConversionRequest, validateConversion } from './conversion.js';
+import { toFunnelRequest, validateFunnel } from './funnel.js';
+import { toLtvRequest, validateLtv } from './ltv.js';
+import { toRetentionRequest, validateRetention } from './retention.js';
+import { validateFilterValues } from './values.js';
+const base = (appId) => `/apps/${appId}/analytics`;
+const isObject = (value) => typeof value === 'object' && value !== null;
+const dataOf = (body) => (isObject(body) ? body.data : undefined);
+/** A data answer: `data.segments` is the list every view reads. */
+const hasSegments = (data) => isObject(data) && Array.isArray(data.segments);
+/**
+ * The transport hands back whatever a success body parsed to, and a proxy's HTML page parses to a string.
+ * Passed on, it would reach the views and exit 0 under --json, so a success without the `{ data }` envelope is
+ * an error, as in the attribution resource.
+ */
+const envelope = async (pending, isData = isObject) => {
+    const body = await pending;
+    if (!isData(dataOf(body))) {
+        throw new ApiError({
+            code: 'malformed_response',
+            details: body,
+            message: 'The Developer API answered with a success status but not with its response envelope, '
+                + 'so the answer was cut short or came from something in between. Nothing was read.',
+            status: 200,
+        });
+    }
+    return body;
+};
+/**
+ * Every path of the analytics of an app in one place. The catalog and the values are GETs and keep the
+ * transport's retry. The six operations are POSTs that run analytics queries under the rate limits of each route
+ * (2 requests per second per app and 360 per minute for all callers together, as the Export API): sent once,
+ * never retried, and a 429 reaches the caller with the server's wait.
+ *
+ * The validating methods are async on purpose — a broken rule then arrives as a rejected promise, like a
+ * network failure, and one await covers both.
+ */
+export const analytics = (http) => ({
+    catalog: (appId) => envelope(http.get(`${base(appId)}/catalog`)),
+    chart: async (input) => {
+        assertValid(validateChart(input));
+        return envelope(http.post(`${base(input.appId)}/metrics`, toChartRequest(input), { idempotent: false }), hasSegments);
+    },
+    cohort: async (input) => {
+        assertValid(validateCohort(input));
+        return envelope(http.post(`${base(input.appId)}/cohort`, toCohortRequest(input), { idempotent: false }), hasSegments);
+    },
+    conversion: async (input) => {
+        assertValid(validateConversion(input));
+        return envelope(http.post(`${base(input.appId)}/conversion`, toConversionRequest(input), { idempotent: false }), hasSegments);
+    },
+    funnel: async (input) => {
+        assertValid(validateFunnel(input));
+        return envelope(http.post(`${base(input.appId)}/funnel`, toFunnelRequest(input), { idempotent: false }), hasSegments);
+    },
+    ltv: async (input) => {
+        assertValid(validateLtv(input));
+        return envelope(http.post(`${base(input.appId)}/ltv`, toLtvRequest(input), { idempotent: false }), hasSegments);
+    },
+    retention: async (input) => {
+        assertValid(validateRetention(input));
+        return envelope(http.post(`${base(input.appId)}/retention`, toRetentionRequest(input), { idempotent: false }), hasSegments);
+    },
+    values: async (input) => {
+        assertValid(validateFilterValues(input));
+        return envelope(http.get(`${base(input.appId)}/values`, { query: { dimension: input.dimension } }));
+    },
+});

package/dist/sdk/adapty/analytics/retention.d.ts

@@ -0,0 +1,32 @@
+import type { AnalyticsData, AnalyticsMeta, AnalyticsResponse, AnalyticsSegment } from './model.js';
+import type { AnalyticsQueryInput, GroupingInput, GroupingRequest, QueryRequest } from './query.js';
+import type { Issue } from '../../core/errors.js';
+export type RetentionInput = AnalyticsQueryInput & Pick<GroupingInput, 'groupBy'> & {
+    /** Count from the trial instead of from the first paid period. */
+    useTrial?: boolean | undefined;
+};
+type RetentionRequest = Pick<GroupingRequest, 'segmentation'> & QueryRequest & {
+    use_trial?: boolean;
+};
+/** One retention period: `x` is the backend period number. */
+export type RetentionPoint = {
+    title: string;
+    value: number;
+    value_relative: number;
+    x: number;
+};
+/** `value` and `first_value` are the subscribers of the first period. */
+export type RetentionSegment = AnalyticsSegment & {
+    first_value: number;
+    value: number;
+    values: RetentionPoint[];
+};
+export type RetentionData = AnalyticsData<RetentionSegment>;
+export type RetentionMeta = AnalyticsMeta<{
+    segmentation: null | string;
+    use_trial: boolean;
+}>;
+export type RetentionResponse = AnalyticsResponse<RetentionData, RetentionMeta>;
+export declare const validateRetention: (input: RetentionInput) => Issue[];
+export declare const toRetentionRequest: (input: RetentionInput) => RetentionRequest;
+export {};

package/dist/sdk/adapty/analytics/retention.js

@@ -0,0 +1,6 @@
+import { toGroupingRequest, toQueryRequest, validateQuery } from './query.js';
+export const validateRetention = (input) => validateQuery(input);
+export const toRetentionRequest = (input) => {
+    const body = { ...toQueryRequest(input), ...toGroupingRequest(input) };
+    return input.useTrial === undefined ? body : { ...body, use_trial: input.useTrial };
+};

package/dist/sdk/adapty/analytics/values.d.ts

@@ -0,0 +1,20 @@
+import type { Issue } from '../../core/errors.js';
+/** The values one filter takes for an app: what `filters.<dimension>` accepts, and the `key` of its groups. */
+export type FilterValuesInput = {
+    appId: string;
+    /** A filter key, as the catalog `dimensions` lists it; the backend refuses any other. */
+    dimension: string;
+};
+/** `group` is the parent in the dashboard list (the region of a country, ...); null at the top level. */
+export type FilterValue = {
+    group: null | string;
+    label: string;
+    value: string;
+};
+export type FilterValuesResponse = {
+    data: FilterValue[];
+    meta: {
+        dimension: string;
+    };
+};
+export declare const validateFilterValues: (input: FilterValuesInput) => Issue[];

package/dist/sdk/adapty/analytics/values.js

@@ -0,0 +1 @@
+export const validateFilterValues = (input) => (input.dimension.trim() === '' ? [{ message: 'must not be empty', path: 'dimension' }] : []);

package/dist/sdk/adapty/index.d.ts

@@ -1,14 +1,17 @@
 import type { AccessLevelsApi } from './access-levels.js';
+import type { AnalyticsApi } from './analytics/index.js';
 import type { AppsApi } from './apps/index.js';
 import type { AuthApi } from './auth/index.js';
 import type { FeedbackApi } from './feedback/index.js';
 import type { MigrationApi } from './migrations/index.js';
 import type { Clock } from '../core/clock.js';
 import type { RetryAttempt } from '../core/http/index.js';
+export { periodTypes, periodUnits, revenueBases, validateChart, validateCohort, validateConversion, validateFilterValues, validateFunnel, validateLtv, validateRetention, } from './analytics/index.js';
 export { platforms } from './apps/index.js';
 export { developerErrorParser } from './errors.js';
 export { sentiments } from './feedback/index.js';
 export type { AccessLevel, AccessLevelList, AccessLevelsApi } from './access-levels.js';
+export type { AnalyticsFilter, AnalyticsSegment, CatalogChart, CatalogOperation, CatalogOption, CatalogResponse, CatalogSegmentation, ChartInput, ChartResponse, CohortInput, CohortResponse, ConversionInput, ConversionResponse, FilterValue, FilterValuesInput, FilterValuesResponse, FunnelInput, FunnelResponse, LtvInput, LtvResponse, PeriodUnit, RetentionInput, RetentionResponse, } from './analytics/index.js';
 export type { AppDetail, AppsApi, AppSummary, CreateAppInput, UpdateAppInput } from './apps/index.js';
 export type { AuthApi, AuthUser, IssuedToken } from './auth/index.js';
 export type { FeedbackApi, SendFeedbackInput, Sentiment } from './feedback/index.js';
@@ -36,6 +39,7 @@ export type AdaptyOptions = {
 };
 export type Adapty = {
     accessLevels: AccessLevelsApi;
+    analytics: AnalyticsApi;
     apps: AppsApi;
     auth: AuthApi;
     feedback: FeedbackApi;

package/dist/sdk/adapty/index.js

@@ -1,11 +1,13 @@
 import { systemClock } from '../core/clock.js';
 import { createHttp } from '../core/http/index.js';
 import { accessLevels } from './access-levels.js';
+import { analytics } from './analytics/index.js';
 import { apps } from './apps/index.js';
 import { auth } from './auth/index.js';
 import { developerErrorParser } from './errors.js';
 import { feedback } from './feedback/index.js';
 import { migrations } from './migrations/index.js';
+export { periodTypes, periodUnits, revenueBases, validateChart, validateCohort, validateConversion, validateFilterValues, validateFunnel, validateLtv, validateRetention, } from './analytics/index.js';
 export { platforms } from './apps/index.js';
 export { developerErrorParser } from './errors.js';
 export { sentiments } from './feedback/index.js';
@@ -46,6 +48,7 @@ export const createAdapty = (options = {}) => {
     const wizard = createHttp({ ...transport, trailingSlash: false });
     return {
         accessLevels: accessLevels(http),
+        analytics: analytics(http),
         apps: apps(http),
         auth: auth(http),
         feedback: feedback(http),

package/dist/sdk/attribution/index.d.ts

@@ -2,7 +2,7 @@ import type { AttributionApi } from './resource.js';
 import type { Clock } from '../core/clock.js';
 import type { RetryAttempt } from '../core/http/index.js';
 export { attributionErrorParser } from './errors.js';
-export { granularities, ISO_DATE, reportGroupBy, revenueBases, sortDirections, validateReport } from './report.js';
+export { granularities, reportGroupBy, revenueBases, sortDirections, validateReport } from './report.js';
 export { validateValues } from './values.js';
 export type { Dimension, DimensionCatalog, DimensionIdentity, Metric, MetricCatalog, MetricUnit, ReportLimits, } from './catalog.js';
 export type { Granularity, ReportData, ReportFilter, ReportGroupBy, ReportInput, ReportMeta, ReportRow, ReportSort, RevenueBasis, SortDirection, } from './report.js';

package/dist/sdk/attribution/index.js

@@ -3,7 +3,7 @@ import { createHttp, defaultRetryPolicy, defaultShouldRetry } from '../core/http
 import { attributionErrorParser } from './errors.js';
 import { attribution } from './resource.js';
 export { attributionErrorParser } from './errors.js';
-export { granularities, ISO_DATE, reportGroupBy, revenueBases, sortDirections, validateReport } from './report.js';
+export { granularities, reportGroupBy, revenueBases, sortDirections, validateReport } from './report.js';
 export { validateValues } from './values.js';
 /** Exported because the adapter compares the resolved URL with it and warns when they differ. */
 export const DEFAULT_ATTRIBUTION_API_URL = 'https://api-ua.adapty.io/api/v1/cli';

package/dist/sdk/attribution/report.d.ts

@@ -57,8 +57,6 @@ export type ReportMeta = {
     /** The query as the backend resolved it: timezone, currency and defaults filled in. */
     query: Record<string, unknown>;
 };
-/** The `YYYY-MM-DD` shape alone, shared with the adapter's date flag parser. */
-export declare const ISO_DATE: RegExp;
 /** Shared with values: both read a day range, and both are refused the same way. */
 export declare const validateDateRange: (input: {
     dateFrom: string;

package/dist/sdk/attribution/report.js

@@ -1,35 +1,11 @@
+import { validateDayRange } from '../core/dates.js';
 /** In the order the backend documents them, so a flag's help reads the same way. */
 export const reportGroupBy = ['date', 'campaign', 'adset', 'ad', 'keyword', 'channel', 'country', 'store'];
 export const granularities = ['day', 'week', 'month', 'quarter', 'year'];
 export const revenueBases = ['gross', 'proceeds', 'net'];
 export const sortDirections = ['asc', 'desc'];
-/** The `YYYY-MM-DD` shape alone, shared with the adapter's date flag parser. */
-export const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-/** The shape alone lets 2026-02-30 through; a round trip through Date does not. */
-const isIsoDate = (value) => {
-    if (!ISO_DATE.test(value)) {
-        return false;
-    }
-    const date = new Date(`${value}T00:00:00Z`);
-    return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
-};
 /** Shared with values: both read a day range, and both are refused the same way. */
-export const validateDateRange = (input) => {
-    const issues = [];
-    const fromValid = isIsoDate(input.dateFrom);
-    const toValid = isIsoDate(input.dateTo);
-    if (!fromValid) {
-        issues.push({ message: 'must be a date in YYYY-MM-DD form', path: 'dateFrom' });
-    }
-    if (!toValid) {
-        issues.push({ message: 'must be a date in YYYY-MM-DD form', path: 'dateTo' });
-    }
-    // ISO days order as strings, but only two real days are worth comparing
-    if (fromValid && toValid && input.dateTo < input.dateFrom) {
-        issues.push({ message: 'must not be before the start date', path: 'dateTo' });
-    }
-    return issues;
-};
+export const validateDateRange = (input) => validateDayRange(input.dateFrom, input.dateTo, { from: 'dateFrom', to: 'dateTo' });
 /**
  * The rules a report can break without asking the server. Which metric and dimension names exist
  * is the catalog's knowledge, so the backend checks those. An Issue path names an input field

package/dist/sdk/core/dates.d.ts

@@ -0,0 +1,15 @@
+import type { Issue } from './errors.js';
+/**
+ * Days as the backends take them: `YYYY-MM-DD`, an inclusive range of two. Shared by every product that
+ * reads a day range, so a range is checked, and refused, in the same words everywhere.
+ */
+/** The `YYYY-MM-DD` shape alone, shared with the adapter's date flag parser. */
+export declare const ISO_DATE: RegExp;
+/**
+ * Both ends real days, the end not before the start. `paths` names the two input fields, so the adapter
+ * can name the two flags the user typed.
+ */
+export declare const validateDayRange: (from: string, to: string, paths: {
+    from: string;
+    to: string;
+}) => Issue[];

package/dist/sdk/core/dates.js

@@ -0,0 +1,34 @@
+/**
+ * Days as the backends take them: `YYYY-MM-DD`, an inclusive range of two. Shared by every product that
+ * reads a day range, so a range is checked, and refused, in the same words everywhere.
+ */
+/** The `YYYY-MM-DD` shape alone, shared with the adapter's date flag parser. */
+export const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** The shape alone lets 2026-02-30 through; a round trip through Date does not. */
+const isIsoDate = (value) => {
+    if (!ISO_DATE.test(value)) {
+        return false;
+    }
+    const date = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(date.getTime()) && date.toISOString().startsWith(value);
+};
+/**
+ * Both ends real days, the end not before the start. `paths` names the two input fields, so the adapter
+ * can name the two flags the user typed.
+ */
+export const validateDayRange = (from, to, paths) => {
+    const issues = [];
+    const fromValid = isIsoDate(from);
+    const toValid = isIsoDate(to);
+    if (!fromValid) {
+        issues.push({ message: 'must be a date in YYYY-MM-DD form', path: paths.from });
+    }
+    if (!toValid) {
+        issues.push({ message: 'must be a date in YYYY-MM-DD form', path: paths.to });
+    }
+    // ISO days order as strings, but only two real days are worth comparing
+    if (fromValid && toValid && to < from) {
+        issues.push({ message: 'must not be before the start date', path: paths.to });
+    }
+    return issues;
+};

package/dist/sdk/core/errors.d.ts

@@ -44,6 +44,9 @@ export declare class CancelledError extends SdkError {
     constructor();
 }
 export type Issue = {
+    /** The other input fields that `message` names, each written there as `{fieldName}`. */
+    fields?: readonly string[] | undefined;
+    /** Plain words; another input field appears as `{fieldName}`, listed in `fields`, for the adapter to write. */
     message: string;
     /** The input field the problem belongs to. No path: the input as a whole is wrong. */
     path?: string | undefined;