// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.ads.admanager.v1;

import "google/ads/admanager/v1/creative_placeholder.proto";
import "google/ads/admanager/v1/date_range.proto";
import "google/ads/admanager/v1/forecasting_enums.proto";
import "google/ads/admanager/v1/goal_enums.proto";
import "google/ads/admanager/v1/targeting.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Ads.AdManager.V1";
option go_package = "google.golang.org/genproto/googleapis/ads/admanager/v1;admanager";
option java_multiple_files = true;
option java_outer_classname = "ForecastMessagesProto";
option java_package = "com.google.ads.admanager.v1";
option php_namespace = "Google\\Ads\\AdManager\\V1";
option ruby_package = "Google::Ads::AdManager::V1";

// Forecasting options for ProspectiveLineItem availability forecasts.
message AvailabilityForecastOptions {
  // Optional. When specified, forecast result for the availability line item
  // will also include breakdowns by its targeting in
  // [AvailabilityForecast.targetingCriteriaBreakdowns][].
  optional bool targeting_criteria_breakdown_included = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. When specified, the forecast result for the availability line
  // item will also include contending line items in
  // [AvailabilityForecast.contendingLineItems][].
  optional bool contending_line_items_included = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Configurations of forecast breakdowns.
  optional ForecastBreakdownOptions breakdown = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// Describes predicted inventory availability for a ProspectiveLineItem.
// Inventory has three threshold values along a line of possible inventory.
// From least to most, these are:
//
//   Available units -- How many units can be booked without affecting any
//   other line items.
//       Booking more than this number can cause lower and same priority line
//       items to underdeliver.
//   Possible units -- How many units can be booked without affecting any
//   higher priority line
//       items. Booking more than this number can cause the line item to
//       underdeliver.
//   Matched (forecast) units -- How many units satisfy all specified
//   criteria.
//
// Underdelivery is caused by overbooking. However, if more impressions are
// served than are predicted, the extra available inventory might enable all
// inventory is able to be met without overbooking.
message AvailabilityForecast {
  // Uniquely identifies this availability forecast. This value is read-only and
  // is assigned by Google when the forecast is created. The attribute will be
  // either the resource name of the
  // [LineItem][google.ads.admanager.v1.LineItem] object it represents, or null
  // if the forecast represents a prospective line item. Format:
  // `networks/{network_code}/lineItems/{line_item_id}`
  optional string line_item = 1 [(google.api.resource_reference) = {
    type: "admanager.googleapis.com/LineItem"
  }];

  // The resource name for the [Order][google.ads.admanager.v1.Order] object
  // that this line item belongs to, or null if the forecast represents a
  // prospective line item without an
  // [LineItem.order][google.ads.admanager.v1.LineItem.order] set.
  // Format:
  // `networks/{network_code}/orders/{order_id}`
  optional string order = 2 [
    (google.api.resource_reference) = { type: "admanager.googleapis.com/Order" }
  ];

  // The unit with which the goal or cap of the LineItem is defined. Will be the
  // same value as [Goal.unitType][] for both a set line item or a
  // prospective one.
  optional UnitTypeEnum.UnitType unit_type = 3;

  // The number of units, defined by [Goal.unitType][], that can
  // be booked without affecting the delivery of any reserved line items.
  // Exceeding this value won't cause an overbook, but lower priority line items
  // may not run.
  optional int64 available_units = 4;

  // The number of units, defined by [Goal.unitType][], that have already been
  // served if the reservation is already running.
  optional int64 delivered_units = 5;

  // The number of units, defined by [Goal.unitType][], that match the specified
  // targeting and delivery settings.
  optional int64 matched_units = 6;

  // The maximum number of units, defined by [Goal.unitType][], that could be
  // booked by taking inventory away from lower priority line items and some
  // same priority line items.
  //
  // Booking this number may cause lower priority line items and some same
  // priority line items to underdeliver.
  optional int64 possible_units = 7;

  // The number of reserved units, defined by [Goal.unitType][], requested. This
  // can be an absolute or percentage value.
  optional int64 reserved_units = 8;

  // The breakdowns for each time window defined in
  // [ForecastBreakdownOptions.timeWindows][].
  //
  // If no breakdown was requested through
  // [AvailabilityForecastOptions.breakdown][google.ads.admanager.v1.AvailabilityForecastOptions.breakdown],
  // this field will be empty.
  repeated ForecastBreakdown breakdowns = 9;

  // The forecast result broken down by the targeting of the forecasted line
  // item.
  repeated TargetingCriteriaBreakdown targeting_criteria_breakdowns = 10;

  // List of ContendingLineItem contending line items for this forecast.
  repeated ContendingLineItem contending_line_items = 11;

  // Views of this forecast, with alternative unit types.
  repeated AlternativeUnitTypeForecast alternative_unit_type_forecasts = 12;

  // The forecast result broken down by demographics.
  repeated GrpDemographicBreakdown demographic_breakdowns = 14;
}

// Forecasting options for line item delivery forecasts.
message DeliveryForecastOptions {
  // Optional. The resource names of line items to be ignored while performing
  // the delivery simulation. Format:
  // `networks/{network_code}/lineItems/{line_item_id}`
  repeated string ignored_line_items = 1 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/LineItem"
    }
  ];
}

// The forecast of delivery for a list of [ProposalLineItem][] or
// [LineItem][google.ads.admanager.v1.LineItem] objects to be reserved at the
// same time.
message DeliveryForecastResult {
  // The delivery forecasts of the forecasted line items.
  repeated LineItemDeliveryForecast line_item_delivery_forecasts = 1;
}

// Configuration of forecast breakdown.
message ForecastBreakdownOptions {
  // Optional. The boundaries of time windows to configure time breakdown.
  //
  // By default, the time window of the forecasted
  // [LineItem][google.ads.admanager.v1.LineItem] is assumed if none are
  // explicitly specified in this field. But if set, at least two DateTimes are
  // needed to define the boundaries of minimally one time window.
  //
  // Also, the time boundaries are required to be in the same time zone, in
  // strictly ascending order.
  repeated google.protobuf.Timestamp time_windows = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. For each time window, these are the breakdown targets. If none
  // specified, the targeting of the forecasted
  // [LineItem][google.ads.admanager.v1.LineItem] is assumed.
  repeated ForecastBreakdownTarget targets = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Specifies inventory targeted by a breakdown entry.
message ForecastBreakdownTarget {
  // An optional name for this breakdown target, to be populated in the
  // corresponding [ForecastBreakdownEntry.displayName][] field.
  optional string display_name = 1;

  // If specified, the targeting for this breakdown.
  // Format: `networks/{network_code}/targetings/{targeting}`
  optional Targeting targeting = 2;

  // If specified, restrict the breakdown to only inventory matching this
  // creative.
  optional CreativePlaceholder creative_placeholder = 3;
}

// Represents the breakdown entries for a list of targetings and creatives.
message ForecastBreakdown {
  // The starting time of the represented breakdown.
  google.protobuf.Timestamp start_time = 1;

  // The end time of the represented breakdown.
  google.protobuf.Timestamp end_time = 2;

  // The forecast breakdown entries in the same order as in the
  // [ForecastBreakdownOptions.targets][google.ads.admanager.v1.ForecastBreakdownOptions.targets]
  // field.
  repeated ForecastBreakdownEntry named_entries = 3;
}

// A single forecast breakdown entry.
message ForecastBreakdownEntry {
  // The optional name of this entry, as specified in the corresponding
  // [ForecastBreakdownTarget.displayName][] field.
  optional string display_name = 1;

  // The forecast of this entry.
  DeliveryForecast forecast = 2;
}

// Represents a single delivery data point, with both available and forecast
// number.
message DeliveryForecast {
  // The number of units matching the specified targeting and delivery settings.
  optional int64 matched = 1;

  // The number of units that can be booked without affecting the delivery of
  // any reserved [LineItem][google.ads.admanager.v1.LineItem]s.
  optional int64 available = 2;

  // The number of units that can be booked without affecting the delivery of
  // any reserved [LineItem][google.ads.admanager.v1.LineItem] or lower priority
  // [LineItem][google.ads.admanager.v1.LineItem].
  optional int64 possible = 3;
}

// A single targeting criteria breakdown result.
message TargetingCriteriaBreakdown {
  // The dimension of this breakdown
  optional ForecastingTargetingDimensionEnum.ForecastingTargetingDimension
      targeting_dimension = 1;

  // The unique ID of the targeting criteria.
  optional int64 targeting_criteria_id = 2;

  // The name of the targeting criteria.
  optional string targeting_criteria = 3;

  // When true, the breakdown is negative.
  optional bool excluded = 4;

  // The available units for this breakdown.
  optional int64 available_units = 5;

  // The matched units for this breakdown.
  optional int64 matched_units = 6;
}

// Describes contending line items for a forecast.
message ContendingLineItem {
  // The resource name of the contending line item.
  // Format:
  // `networks/{network_code}/lineItems/{line_item_id}`
  optional string line_item = 1 [(google.api.resource_reference) = {
    type: "admanager.googleapis.com/LineItem"
  }];

  // The number of impressions contended for by both the forecasted line item
  // and this line item.
  optional int64 contending_units = 2;
}

// Views of this forecast, with alternative unit types.
message AlternativeUnitTypeForecast {
  // The alternative unit type being presented.
  optional UnitTypeEnum.UnitType unit_type = 1;

  // The number of units matching the specified targeting and delivery settings.
  optional int64 matched_units = 2;

  // The number of units that can be booked without affecting the delivery of
  // any reserved line items.
  optional int64 available_units = 3;

  // The number of units that can be booked without affecting the delivery of
  // any reserved line items or lower priority line items.
  optional int64 possible_units = 4;
}

// GRP forecast breakdown counts associated with a gender and age demographic.
message GrpDemographicBreakdown {
  // The number of units matching the demographic breakdown that can be booked
  // without affecting the delivery of any reserved line items.
  optional int64 available_units = 1;

  // The number of units matching the demographic and matching specified
  // targeting and delivery settings.
  optional int64 matched_units = 2;

  // The GrpUnitType associated with this demographic breakdown.
  optional ForecastingGrpUnitEnum.ForecastingGrpUnit unit_type = 3;

  // The GrpGender associated with this demographic breakdown.
  optional ForecastingGrpGenderEnum.ForecastingGrpGender gender = 4;

  // The GrpAge associated with this demographic breakdown.
  optional ForecastingGrpAgeEnum.ForecastingGrpAge age = 5;
}

// The forecasted delivery of a [ProposalLineItem][] or
// [LineItem][google.ads.admanager.v1.LineItem].
message LineItemDeliveryForecast {
  // Uniquely identifies this line item delivery forecast. This value is
  // read-only and will be either the resource name of the
  // [LineItem][google.ads.admanager.v1.LineItem] resource it represents, or
  // unset if the forecast represents a prospective line item. Format:
  // `networks/{network_code}/lineItems/{line_item_id}`
  optional string line_item = 1 [(google.api.resource_reference) = {
    type: "admanager.googleapis.com/LineItem"
  }];

  // The resource name of the [Order][google.ads.admanager.v1.Order] object that
  // this line item belongs to, or null if the forecast represents a prospective
  // line item without an
  // [LineItem.order][google.ads.admanager.v1.LineItem.order] set.
  // Format: `networks/{network_code}/orders/{order_id}`
  optional string order = 2 [
    (google.api.resource_reference) = { type: "admanager.googleapis.com/Order" }
  ];

  // The unit with which the goal or cap of the LineItem is defined. Will be the
  // same value as [Goal.unitType][] for both a set line item or a prospective
  // one.
  optional UnitTypeEnum.UnitType unit_type = 3;

  // The number of units, defined by [Goal.unitType][], that will be delivered
  // by the line item. Delivery of existing line items that are of same or lower
  // priorities may be impacted.
  optional int64 predicted_delivery_units = 4;

  // The number of units, defined by [Goal.unitType][], that have already been
  // served if the reservation is already running.
  optional int64 delivered_units = 5;

  // The number of units, defined by [Goal.unitType][], that match the
  // specified LineItem#targeting and delivery settings.
  optional int64 matched_units = 6;
}

// Represents a chronological sequence of daily values.
message TimeSeries {
  // The date range of the time series.
  DateRange time_series_date_range = 1;

  // The daily values constituting the time series.
  //
  // The number of time series values must equal the number of days spanned by
  // the time series date range, inclusive. For example, a timeSeriesDateRange
  // of 2001-08-15 to 2001-08-17 contains one value for the 15th, one value for
  // the 16th, and one value for the 17th.
  repeated int64 values = 2;
}

// [ExistingLineItemList][google.ads.admanager.v1.ExistingLineItemList] is a
// wrapper around a repeated field of string representing a
// [LineItem][google.ads.admanager.v1.LineItem] resource name.
message ExistingLineItemList {
  // Required. The list of [LineItem][google.ads.admanager.v1.LineItem] resource
  // names to be forecasted. Format:
  // `networks/{network_code}/lineItems/{line_item_id}`
  repeated string line_items = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "admanager.googleapis.com/LineItem"
    }
  ];
}