syntax = "proto3";

package user_subscribe_user_notice;

option go_package = "user_subscribe_user_notice";

import "eventbus/owner.proto";
import "google/protobuf/timestamp.proto";

// UserSubscribeUserNoticeCreate is triggered when a subscription entitlement has notified the user's channel.
message UserSubscribeUserNoticeCreate {
  option (eventbus.owner.ldap_group) = "team-subs";
  // the owner (i.e. twitch viewer) of the subscription entitlement (i.e. viewer who is subscribing)
  string from_user_id = 1;
  // the user/broadcaster that the subscriber is entitled subscription benefits to (i.e. twitch.tv/michael)
  string to_user_id = 2;
  // The information pertaining to the current subscription for the user
  Subscription subscription_info = 3;
  // The details of the user notice that can include:
  // - subscription, in which the user transitioned from unsubscribed to subscribed
  // - resubscription, in which the user shared their resubscription user notice
  // - gifted_subscription, in which the user has been gifted a subscription
  // - tier_upgrade, in which the user upgraded their subscription to a different tier
  // - prime_upgrade, in which the user has transitioned from a prime sub to a paid sub
  // - gift_upgrade, in which the user has transitioned from a gifted sub to a paid sub
  // - pay_it_forward, in which the user has gifted a sub after being gifted a sub themselves
  // - extend_subscription, in which the user has extended their sub before their sub has expired
  oneof user_notice {
    SubscriptionUserNotice subscription = 4;
    SubscriptionUserNotice resubscription = 5;
    GiftedSubscriptionUserNotice gifted_subscription = 6;
    TierUpgradeUserNotice tier_upgrade = 7;
    GiftToPaidUserNotice gift_upgrade = 9;
    PayItForwardUserNotice pay_it_forward = 10;
    ExtendSubscriptionUserNotice extend_subscription = 11;
    PrimeToPaidUserNotice prime_upgrade = 12;
    // Deprecated field. Please use the `gift_upgrade` user notice field instead
    SubscriptionUserNotice deprecated_prime_to_paid = 8 [deprecated = true];
  }
}

// ExtendSubscriptionUserNotice when the user has extended their current sub duration.
message ExtendSubscriptionUserNotice {
  // the amount of months the sub was extended
  int64 benefit_end_month = 1;
  // The tier of sub that was extended
  Tier tier = 2;
  // A custom message that the user has created to share their feelings about that sick sub to the Taco Premium Club
  string custom_message = 3;
  // The amount of months the user extended their subscription by
  int64 quantity = 4;
}

// PayItForwardUserNotice when a user that was gifted a sub then gifts another sub because they're a nice human / creature.
message PayItForwardUserNotice {
  // The gifter who paid it forward
  string prior_gifter_id = 1;
  // Flag to determine if the prior gifter was anonymous
  bool is_prior_gifter_anonymous = 2;
  // The tier of sub that was gifted
  Tier tier = 3;
  // the user who receives the pay it forward sub
  string recipient_id = 4;
}

// TierUpgradeUserNotice when a user changes their sub to a new tier.
message TierUpgradeUserNotice {
  // The previous tier of their sub
  Tier old_tier = 1;
  // The new tier of their sub
  Tier new_tier = 2;
}

// GiftToPaidUserNotice when a user has converted their gifted sub into a paid sub.
message GiftToPaidUserNotice {
  // the original user who gifted the sub to the user
  string original_gifter_id = 1;
  // the tier of sub that the user has started to pay for
  Tier paid_tier = 2;
}

// PrimeToPaidUserNotice when a user has converted their prime sub into a paid sub.
message PrimeToPaidUserNotice {
  // the tier of sub that the user has started to pay for
  Tier paid_tier = 1;
}

// GiftedSubscriptionUserNotice when a user has been gifted a sub to a channel.
message GiftedSubscriptionUserNotice {
  // the ID of the gifter, which could be the anonymous gifter ID
  string gifter_id = 1;
  // If the gift was anonymous. both of these fields are set since it is required to have the anonymous user ID passed from Subs services.
  bool is_anon = 2;
  // The tier of sub that was gifted.
  Tier tier = 3;
  // the user who receives the sub
  string recipient_id = 4;
}

// Subscription information pertaining to the subscription that was updated.
message SubscriptionUserNotice {
  // the cumulative amount of months the user has been subscribed to the user, between lapses in subscription periods
  int64 cumulative_tenure_months = 1;
  // the tier of subscription
  Tier tier = 3;
  // information about the tenure streak, which provides additional information
  TenureStreak streak = 4;
  // how long this subscription will last, in months.
  int64 duration_months = 5;
  // the message shared by the user, including data about emotes.
  SubscribeMessage message = 6;
  // if the sub was purchased with a prime token.
  bool is_prime = 7;
  // a message the user has written to share about their current subscription tenure
  // DEPRECATED - use `message.text` instead.
  string custom_message = 2 [deprecated = true];
}

// Subscription defines a user's entitlement to product for a time period.
message Subscription {
  // the ID Of the subscription
  string id = 1;
  // The product ID of the subscription
  string product_id = 2;
  // The payment ID of the subscription
  string origin_id = 3;
  // The time the benefits of the subscription starts
  google.protobuf.Timestamp benefit_starts_at = 4;
  // The time the benefits of the subscription ends
  google.protobuf.Timestamp benefit_ends_at = 5;
  // The time the benefits were updated
  google.protobuf.Timestamp updated_at = 6;
  // The original time the benefit was created
  google.protobuf.Timestamp created_at = 7;
  // The string that denotes the actor that created the subscription
  string created_by = 8;
}

// TenureStreak is the wrapper around tenure streaks for the user subscribed to the broadcaster.
message TenureStreak {
  // A boolean flag that says if the tenure streak should be shared.
  bool should_share = 1;
  // The consecutive months that the user has been subscribed to the broadcaster.
  int64 months = 2;
}

// Tier the tier value of sub that is attached.
message Tier {
  // the value can be either
  // - an enumerated value (tier 1, 2, 3 subs)
  // - a custom string value (OWL ticket product, legacy ticket products)
  oneof value {
    SubTier numeral = 1;
    string custom = 2;
  }
}

// SubTier is the enumerated values that a sub is normally.
enum SubTier {
  // default case is an invalid sub tier
  SUB_TIER_INVALID = 0;
  // tier 1 subs
  SUB_TIER_1 = 1;
  // tier 2 subs
  SUB_TIER_2 = 2;
  // tier 3 subs
  SUB_TIER_3 = 3;
}

// SubscribeMessage represents the message the user shares with their resub notice.
message SubscribeMessage {
  // a message the user has written to share about their current subscription tenure
  string text = 1;
  // a list of emotes that are included in the message's text
  repeated SubscribeMessageEmote emotes = 2;
}

// SubscribeMessageEmote represents a single usage of an emote in a SubscribeMessage.
message SubscribeMessageEmote {
  // the ID of the emote that was used
  string id = 1;
  // the 0-based index into the SubscribeMessage where this emote code begins
  int64 begin = 2;
  // the 0-based index into the SubscribeMessage where this emote code ends
  int64 end = 3;
}
