import { RpcMethod } from './commonTypes'; export type StatisticsDashboardsWidgetsService_Load = RpcMethod; export type StatisticsDashboardsWidgetsService_List = RpcMethod; export type StatisticsDashboardsWidgetsService_Create = RpcMethod; export type StatisticsDashboardsWidgetsService_Update = RpcMethod; export type StatisticsDashboardsWidgetsService_Delete = RpcMethod; export type StatisticsDashboardsWidgetsService_GetLinearChartMetrics = RpcMethod; export type StatisticsDashboardsWidgetsService_GetTotalsChartMetrics = RpcMethod; export type StatisticsDashboardsWidgetsService_GetFunnel = RpcMethod; export type StatisticsDashboardsWidgetsService_GetCategoryTree = RpcMethod; /** * StatisticsDashboardsWidgetsService provides APIs for managing statistics dashboard widgets (charts). * * Dashboard Layout Rules: * - Dashboards typically contain 2 to 12 charts, but can include more if necessary. * - Place the most important and high-level KPIs at the top (using lower order/index_number values). * - The sum of size for charts in any single horizontal row MUST NOT exceed 6. * - Every chart should offer potential insights that can lead to action or decision-making. * * Data Visualization Rules: * - DO NOT combine metrics with different units (Number, Percent, Money) on the same chart. * - DO NOT combine metrics with vastly different scales (e.g., Push Sends and Push Opens). * - If a breakdown is applied to a chart, that chart MUST display ONLY ONE metric. */ export interface StatisticsDashboardsWidgetsService { /** Retrieves a single statistics dashboard widget (chart) by its widget code, including its metrics, filters and visualization settings. Use after list_dashboard_widgets to inspect one chart's full configuration. */ Load: StatisticsDashboardsWidgetsService_Load; /** Lists all widgets (charts) belonging to a statistics dashboard, ordered by index_number. Use to enumerate a dashboard's charts before loading, updating or deleting one. */ List: StatisticsDashboardsWidgetsService_List; /** Adds a new widget (chart) to a statistics dashboard for an application, with its metrics, filters, size and visualization type. Each call creates a distinct widget with a new generated code. */ Create: StatisticsDashboardsWidgetsService_Create; /** Updates an existing dashboard widget identified by its widget code, overwriting the supplied name, type, size, index and chart params. Only non-empty fields are applied; re-sending the same values yields the same widget state. */ Update: StatisticsDashboardsWidgetsService_Update; /** Permanently removes a widget (chart) from its dashboard by widget code. Irreversible; a second call for the same code fails because the widget no longer exists. */ Delete: StatisticsDashboardsWidgetsService_Delete; /** Fetches time-series data points over the requested time range for a chart's metrics, for rendering line and bar charts. Use for LINE/BARS widgets; use get_dashboard_widget_totals for pie/number aggregates and get_dashboard_widget_funnel for funnels. */ GetLinearChartMetrics: StatisticsDashboardsWidgetsService_GetLinearChartMetrics; /** Fetches aggregated total values (one number per metric/breakdown) for the requested time range, for pie charts and single-value NUMBER widgets. Use for PIE/NUMBER widgets instead of the linear (time-series) variant. */ GetTotalsChartMetrics: StatisticsDashboardsWidgetsService_GetTotalsChartMetrics; /** Fetches funnel data (per-step user counts and conversion percentages) where the chart's metrics list defines the sequential funnel steps. Use for FUNNEL widgets to see drop-off between steps. */ GetFunnel: StatisticsDashboardsWidgetsService_GetFunnel; /** * Returns the hierarchical tree of standard metrics plus the application's custom events and account tags that can be selected when configuring a widget. Call first to discover valid metric IDs, event names, value types and available filters before creating or updating a widget. * * GetCategoryTree returns the hierarchical tree of all available metrics, events, and tags that can be selected in widgets. * This includes: * - Standard metrics from the "Metrics tree" (Push Sends, Email Opens, Subscribers, DAU, MAU, etc.) * - Custom events available on the account without their attributes * - Tags available on the account * The response provides metadata like metric IDs, value types (Number/Percent/Money), available filters, and descriptions. * Use this endpoint to discover which metrics, events, and tags are available for use in widget configurations. */ GetCategoryTree: StatisticsDashboardsWidgetsService_GetCategoryTree; } export type WidgetType = 'WIDGET_TYPE_UNKNOWN' | 'LINE' | 'BARS' | 'PIE' | 'NUMBER' | 'FUNNEL' | 'RETENTION'; export type Widget = { /** Chart's title, descriptive of the metrics displayed. Maximum length is 128 characters. */ name: string; /** Unique code identifier for the widget, generated by the system. */ code: string; /** Timestamp when the widget was created. */ created: Date; /** Timestamp when the widget was last updated. */ updated: Date; /** Visual representation of the chart (LINE for linear, BARS for bar, PIE for pie, NUMBER for metric) FUNNEL, RETENTION - temporary unavailable. */ type: WidgetType; /** * Width of the chart in horizontal blocks (2-6). The sum of size for charts in any single horizontal row MUST NOT exceed 6. * For single-value KPI metrics (NUMBER type), prefer size 2 or 3 for compactness. * For trend charts (LINE type), prefer size 4 or 6 to ensure readability of data over time. */ size: string; /** * Optional JSON string representation of chart parameters. Deprecated in favor of widget_params. * If provided, must be valid JSON that can be unmarshaled into Params structure. */ params?: string; /** * Structured chart parameters containing metrics, filters, time ranges, and breakdown configuration. * This is the preferred way to specify widget configuration instead of the params JSON string. */ widgetParams: ChartParams; /** * Display order of the chart within the dashboard (lower number = higher placement). * Place the most important and high-level KPIs at the top (using lower order values) for immediate visibility. */ indexNumber: number; }; export type LoadDashboardWidgetRequest = { /** Unique code identifier of the widget to load. Must exist in the database. */ code?: string; }; export type CreateDashboardWidgetRequest = { /** * Application code where the widget will be created. Validated to ensure the application exists * and the user has access to it. */ application?: string; /** Chart's title, descriptive of the metrics displayed. Required field, maximum length is 128 characters. */ name?: string; /** Visual representation of the chart (linear, bar, pie, metric). Required field, cannot be WIDGET_TYPE_UNKNOWN. */ type?: WidgetType; /** Width of the chart in horizontal blocks (2-6). The sum of size for charts in any single horizontal row MUST NOT exceed 6. */ size?: string; /** * Optional JSON string representation of chart parameters. If provided, must be valid JSON * that can be unmarshaled into Params structure. Deprecated in favor of widget_params. */ params?: string; /** * Structured chart parameters containing metrics, filters, time ranges, and breakdown configuration. * This is the preferred way to specify widget configuration instead of the params JSON string. */ widgetParams?: ChartParams; /** Dashboard code where the widget will be added. Required field, validated to ensure the dashboard exists. */ dashboard?: string; /** Display order of the chart within the dashboard (lower number = higher placement). */ indexNumber?: number; }; export type CreateDashboardWidgetResponse = { /** The newly created widget with generated code and timestamps. */ widget: Widget; }; export type UpdateDashboardWidgetRequest = { /** Application code of the widget. Currently not validated but expected to match the widget's application. */ application?: string; /** Unique code identifier of the widget to update. Required field, validated to ensure the widget exists. */ code?: string; /** New chart title. If provided, maximum length is 128 characters. Only updated if not empty. */ name?: string; /** New visual representation type for the chart. Only updated if not WIDGET_TYPE_UNKNOWN. */ type?: WidgetType; /** New width of the chart in horizontal blocks (2-6). Only updated if not empty. */ size?: string; /** New chart parameters as JSON string. Only updated if not empty. If provided, must be valid JSON. */ params?: string; /** * New structured chart parameters. Only updated if provided. This is the preferred way to update * widget configuration instead of the params JSON string. */ widgetParams?: ChartParams; /** New display order (lower number = higher placement). Only updated if not 0. */ indexNumber?: number; }; export type UpdateDashboardWidgetResponse = {}; export type DeleteDashboardWidgetRequest = { /** * Unique code identifier of the widget to delete. Validated to ensure the widget exists * before deletion. */ code?: string; }; export type DeleteDashboardWidgetResponse = {}; export type TimeInterval = 'TIME_INTERVAL_UNSPECIFIED' | 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'MINUTE'; export type Breakdown = /** * For general counts or when no specific data-driven breakdown is needed. * Applicable to: Any standard metric from the "Metrics tree" (specified by id), Events (by event_name), or Tags (by tag). * selected_breakdowns are automatically chosen by the system. */ 'BREAKDOWN_UNKNOWN' /** * To split data by configured platforms (e.g., SMS, Email). * Applicable to: Standard metrics from the "Metrics tree" (specified by id) and Events (by event_name). NEVER use for Tags. * You MUST include the metric field within breakdown. */ | 'PLATFORMS' /** * To split Event data by its specific attributes. * Applicable to: ONLY custom Events (specified by event_name). NEVER use for standard metrics (IDs) or Tags. * You MUST set breakdown.event_attribute and include metric (with event_name set) within breakdown. */ | 'EVENT_ATTRIBUTE' /** * To split data by values of a specific user tag. * Applicable to: ONLY Tags (specified by tag). NEVER use for standard metrics (IDs) or Events. * You MUST set breakdown.tag and include metric (with tag set) within breakdown. */ | 'TAG_VALUES' /** * To split data by campaigns. Groups metrics by campaign_id and displays campaign names. * Applicable to: Push/Email metrics and Events that support campaign filtering. */ | 'CAMPAIGNS' /** * To split data by messages (push notifications or emails). Groups metrics by message_code. * Applicable to: Push/Email metrics and Events that support message filtering. */ | 'MESSAGES' /** * To split data by journeys. * Applicable to: Metrics that support journey filtering. */ | 'JOURNEYS' /** * To compare cohorts: every prepared segment from fltrs becomes its own series * named after the segment, instead of the segments being merged into one. * Applicable to: Metrics that support segment filtering (events, revenue, push/email). */ | 'SEGMENTS'; export type MathOperator = 'MATH_OPERATOR_UNSPECIFIED' | 'EQ' | 'NOT_EQ' | 'GTE' | 'LTE' | 'BETWEEN' | 'IN' | 'NOT_IN' | 'ANY' | 'NOT_SET'; export type Value_kind_string = { type: 'string'; data: string; }; export type Value_kind_integer = { type: 'integer'; data: number; }; export type Value_kind_decimal = { type: 'decimal'; data: number; }; export type Value_kind_boolean = { type: 'boolean'; data: boolean; }; export type Value_kind_list = { type: 'list'; data: List; }; export type Value_kind_date = { type: 'date'; data: Date; }; export type Value_kind = Value_kind_string | Value_kind_integer | Value_kind_decimal | Value_kind_boolean | Value_kind_list | Value_kind_date; export type Value = { kind: Value_kind; }; export type List = { /** List of string values used in IN/NOT_IN operators for attribute conditions. */ values: string[]; }; export type AttributeCondition = { /** Name of the event attribute or tag to filter by (e.g., "user_level", "purchase_amount", "device_type"). */ name: string; /** Mathematical operator to use for comparison (EQ, NOT_EQ, GTE, LTE, BETWEEN, IN, NOT_IN, ANY, NOT_SET). */ operator: MathOperator; /** * Values to compare against. The number and type of values depends on the operator: * - EQ, NOT_EQ, GTE, LTE: single value * - BETWEEN: two values (min and max) * - IN, NOT_IN: list value * - ANY, NOT_SET: no values needed */ values: Value[]; }; export type EventCalcType = 'EVENT_CALC_TYPE_ALL' | 'EVENT_CALC_TYPE_UNIQUE'; export type Metric = { /** * Metric ID from the category tree. Retrieved via GetCategoryTree endpoint. * Used to identify standard metrics from the "Metrics tree" like "Subscribers" (1101), "Recipients" (1102), "Push Sends" (102), etc. * Mutually exclusive with event_name and tag. */ id: number; /** * Optional event name for event-based metrics (e.g., "SubscriptionCancelled", "AccountRegistered", "SubscriptionPurchased"). * Used when tracking custom events instead of standard metrics. * Mutually exclusive with id and tag. */ eventName?: string; /** * Optional conditions to filter events by their attributes. Multiple conditions are ANDed together. * For example, to count purchases over $100: [{name: "amount", operator: GTE, values: [100]}] * Only applicable when event_name is specified. */ attributeConditions: AttributeCondition[]; /** * Optional tag name for tag-based metrics (e.g., "Subscription Preferences", "User Tier"). * Used when tracking tag values instead of events or standard metrics. * Mutually exclusive with id and event_name. */ tag?: string; /** * Optional calculation type for event metrics: * - EVENT_CALC_TYPE_ALL (0): Count all event occurrences * - EVENT_CALC_TYPE_UNIQUE (1): Count unique users who triggered the event * Only applicable when event_name is specified. */ eventCalcType?: EventCalcType; }; export type TypeFilter = 'Platform' | 'Segment' | 'Push' | 'Email' | 'Campaign' | 'Journey'; export type ChartParams_TimeRange = { /** Start timestamp for the data range (inclusive). */ from: Date; /** End timestamp for the data range (inclusive). */ to: Date; /** * Time interval for grouping data points (HOUR, DAY, WEEK, MONTH, MINUTE). * Determines the granularity of the chart data. */ interval: TimeInterval; }; export type ChartParams_Filters = { /** DEPRECATED: Use fltrs instead. List of platform IDs to filter by (1=iOS, 2=Android, etc.). */ platforms: number[]; /** DEPRECATED: Use fltrs instead. List of message IDs to filter by. */ messagesIds: number[]; /** DEPRECATED: Use fltrs instead. List of campaign codes to filter by. */ campaignsCodes: string[]; /** DEPRECATED: Use fltrs instead. Attribute conditions to filter events. */ attributeConditions: AttributeCondition[]; /** DEPRECATED: Use fltrs instead. Segment code to filter by. */ segment: string; }; export type ChartParams_Filter = { /** Type of filter to apply (Platform, Segment, Push, Email, Campaign, Journey). */ type: TypeFilter; /** * List of platform IDs to filter by (1=iOS, 2=Android, 3=Windows Phone, etc.). * Used when type is Platform. */ platforms: number[]; /** Segment code to filter by user segment. Used when type is Segment. */ segment?: string; /** Push notification message ID to filter by. Used when type is Push. */ pushId?: number; /** Email campaign message ID to filter by. Used when type is Email. */ emailId?: number; /** Campaign code to filter by. Used when type is Campaign. */ campaign?: string; /** Journey code to filter by. Used when type is Journey. */ journey?: string; /** List of journey point IDs to filter by specific points in a journey. Used with type Journey. */ jPoints: string[]; /** Whether this filter is currently disabled. Disabled filters are ignored in queries. */ disabled?: boolean; }; export type ChartParams_BreakdownParams = { /** * Type of breakdown to apply (BREAKDOWN_UNKNOWN, PLATFORMS, EVENT_ATTRIBUTE, TAG_VALUES, CAMPAIGNS, MESSAGES, JOURNEYS, SEGMENTS). * Determines how data is segmented in the response. * CRITICAL RULE: If a breakdown is applied to a chart, that chart MUST display ONLY ONE metric. * The breakdown.type chosen MUST correspond to the metric type being broken down. */ type: Breakdown; /** * Event attribute name to breakdown by. REQUIRED when type is EVENT_ATTRIBUTE. * For example, "ProductName" to break down subscription cancellations by product. * ONLY applicable to custom Events (not standard metrics or Tags). */ eventAttribute?: string; /** * Metric to use for breakdown calculation. * REQUIRED for PLATFORMS breakdown (e.g., metric: {id: 1101} or metric: {event_name: "MyEvent"}). * REQUIRED for EVENT_ATTRIBUTE breakdown (e.g., metric: {event_name: "SubscriptionCancelled"}). * REQUIRED for TAG_VALUES breakdown (e.g., metric: {tag: "Subscription Preferences"}). */ metric: Metric; /** * Pre-selected breakdown values to display. Automatically chosen by the system (do NOT set). * Empty means show all breakdown values determined by the system. */ selectedBreakdowns: string[]; }; export type ChartParams = { /** Time range for the chart data including start, end, and interval. */ timeRange: ChartParams_TimeRange; /** * List of metrics to display in the chart. Each metric represents a data series. * STRICT RULE: DO NOT combine metrics with different units (e.g., 'Number' with 'Percent' or 'Money') on the same chart. * DO NOT combine metrics with vastly different scales (e.g., 'Push Sends' and 'Push Opens' MUST be on separate charts). * If a breakdown is applied, the chart MUST display ONLY ONE metric. */ metrics: Metric[]; /** DEPRECATED: Use fltrs instead. Legacy filter structure. */ filters?: ChartParams_Filters; /** * List of filters to apply to the data. Multiple filters are ANDed together. * DO NOT add any filters unless explicitly provided by the user (e.g., PushID, EmailID, Campaign name, Journey ID, Segment ID). */ fltrs: ChartParams_Filter[]; /** * Optional breakdown configuration to segment data by platform, attribute, tag, campaign, etc. * If a breakdown is applied to a chart, that chart MUST display ONLY ONE metric. */ breakdown?: ChartParams_BreakdownParams; /** Application code to query data from. Required field. */ application: string; /** * Timezone for date calculations (e.g., "America/New_York", "UTC", "Europe/London"). * Used to correctly bucket data into time intervals. */ timezone: string; /** * Scope event metrics by message source: exactly one true narrows the chart to * that source, both true or both false leave it unrestricted. */ includeAllOneTime: boolean; includeAllJourneys: boolean; }; export type GetLinearChartMetricsRequest = { /** * Chart parameters specifying metrics, filters, time range, and breakdown configuration * for the linear chart. Used to fetch time-series data for line/bar charts (chart_type: "linear" or "bar"). * For trend charts, prefer size 4 or 6 to ensure readability of data over time. */ params?: ChartParams; }; export type GetLinearChartMetricsResponse_Breakdown = { /** Breakdown label (e.g., "iOS", "Android", "premium_user"). Empty string for non-breakdown metrics. */ breakdown: string; /** Array of metric values corresponding to each timestamp. Length matches timestamps array. */ values: number[]; /** Calculated total for this breakdown (sum, average, or last value depending on metric type). */ total: number; }; export type GetLinearChartMetricsResponse_Metric = { /** Metric name or description (e.g., "Active Users", "Sessions", "Revenue"). */ metric: string; /** List of breakdowns for this metric. Contains one breakdown per segment (or one total if no breakdown). */ breakdowns: GetLinearChartMetricsResponse_Breakdown[]; }; export type GetLinearChartMetricsResponse = { /** Array of timestamps for the X-axis. All metrics use the same timestamp array. */ timestamps: Date[]; /** List of metrics with their breakdown data. Each metric can have multiple breakdowns. */ metrics: GetLinearChartMetricsResponse_Metric[]; /** * Codes of the requested segments whose snapshot is not prepared. Their filtering * was NOT applied to the returned metrics, so the numbers must not be presented * as filtered by those segments. */ notPreparedSegments: string[]; }; export type GetTotalsChartMetricsRequest = { /** * Chart parameters specifying metrics, filters, and time range for the totals chart. * Used to fetch aggregated totals (single values) for pie charts, number widgets (chart_type: "pie" or "metric"), etc. * For single-value KPI metrics (chart_type: "metric"), prefer size 2 or 3 for compactness. */ params?: ChartParams; }; export type GetTotalsChartMetricsResponse_Breakdown = { /** Breakdown label (e.g., "iOS", "Android", "premium_user"). Empty string for non-breakdown metrics. */ breakdown: string; /** Aggregated total value for this breakdown segment. */ value: number; /** Same as value, provided for consistency with linear chart response. */ total: number; }; export type GetTotalsChartMetricsResponse_Metric = { /** Metric name or description (e.g., "Total Active Users", "Total Revenue"). */ metric: string; /** List of breakdowns for this metric. Contains one breakdown per segment (or one total if no breakdown). */ breakdowns: GetTotalsChartMetricsResponse_Breakdown[]; }; export type GetTotalsChartMetricsResponse = { /** List of metrics with their aggregated total values and breakdowns. */ metrics: GetTotalsChartMetricsResponse_Metric[]; /** * Codes of the requested segments whose snapshot is not prepared. Their filtering * was NOT applied to the returned metrics, so the numbers must not be presented * as filtered by those segments. */ notPreparedSegments: string[]; }; export type GetFunnelRequest = { /** * Chart parameters specifying metrics (funnel steps), filters, and time range for the funnel. * The metrics list represents the sequential steps in the funnel. */ params?: ChartParams; }; export type GetFunnelResponse_Step = { /** Step name or breakdown label (e.g., "Page View", "Add to Cart", "Purchase"). */ breakdown: string; /** Number of users who completed this step. */ count: number; /** Percentage of users from the first step who reached this step (0-100). */ percent: number; }; export type GetFunnelResponse = { /** Sequential list of funnel steps with user counts and conversion percentages. */ steps: GetFunnelResponse_Step[]; }; export type GetCategoryTreeRequest = { /** * Application code to get available metrics for. Required field, validated to ensure * the application exists and the user has access to it. */ application?: string; }; export type GetCategoryTreeResponse_Metric_ValueType = /** Numeric value (e.g., count, quantity). */ 'Number' /** Percentage value (0-100). */ | 'Percent' /** Monetary value (revenue, cost). */ | 'Money'; export type GetCategoryTreeResponse_Metric_TotalCalculationType = /** Sum all values across the time range. */ 'Sum' /** Average values across the time range. */ | 'Avg' /** Use the last/most recent value. */ | 'Last'; export type GetCategoryTreeResponse_Metric = { /** Unique ID for this metric. Used in Metric.id when creating widgets. */ id: number; /** Metric name/label (e.g., "Active Users", "Sessions", "Revenue"). */ metric: string; /** Hierarchy level in the category tree (0 = root category, 1 = subcategory, etc.). */ level: number; /** Nested sub-metrics forming a tree structure. Empty for leaf metrics. */ subMetrics: GetCategoryTreeResponse_Metric[]; /** Value type indicating how to format the metric (Number, Percent, Money). */ type: GetCategoryTreeResponse_Metric_ValueType; /** How to calculate the total value for this metric (Sum, Avg, Last). */ totalType: GetCategoryTreeResponse_Metric_TotalCalculationType; /** List of filter types that can be applied to this metric (Platform, Segment, Push, Email, etc.). */ availableFilters: TypeFilter[]; /** Human-readable description of what this metric represents. */ description: string; }; export type GetCategoryTreeResponse = { /** Root metric containing the entire category tree with all available metrics and events. */ metrics: GetCategoryTreeResponse_Metric; }; export type ListDashboardWidgetRequest = { /** * Dashboard code to list widgets from. Required field, validated to ensure the dashboard * exists and belongs to the user's account. */ dashboardCode?: string; }; export type ListDashboardWidgetResponse = { /** List of widgets in the dashboard, ordered by index_number. */ widgets: Widget[]; };