config.proto

/*
 * Copyright 2023 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
 *
 *     https://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.
 */

// This is the schema for rock-paper-sand's config file. See the examples
// directory in the root of this repo for examples of what the file looks like.
// Note that the config file is a YAML-encoded JSON protobuf, so field_name in
// this file becomes fieldName in the config file. See
// https://protobuf.dev/programming-guides/proto3/#json for more details on the
// mapping between JSON and protobuf.

syntax = "proto3";

package rock_paper_sand;

import "google/protobuf/empty.proto";
import "google/protobuf/struct.proto";

// 0 or more filters, mainly for use as config for filters like `and` and `or`.
message Filters { repeated Filter filters = 1; }

// Ways to match a string field in a filter.
message StringFieldMatcher {
  // Required. How to match the field.
  oneof method {
    // Matches if the field is empty or not.
    bool empty = 1;

    // Matches if the field is exactly equal to the specified string.
    string equals = 2;

    // Matches against the regex using python's re.search() function. See
    // https://docs.python.org/3/library/re.html for the syntax.
    string regex = 3;
  }
}

// Ways to match arbitrary JSON data.
message ArbitraryDataMatcher {
  // Required. How to match the field.
  oneof method {
    // Uses JMESPath <https://jmespath.org/> to match the data. If the JMESPath
    // expression returns true, the item matches; if it returns false or null,
    // it does not match; if it returns anything else, an error is raised.
    string jmespath = 1;
  }
}

// Filters using Wikidata APIs.
message WikidataFilter {
  // Languages to use for labels and descriptions, in order from highest
  // preference to lowest. See
  // https://www.wikidata.org/wiki/Help:Wikimedia_language_codes/lists/all for
  // list.
  repeated string languages = 3;

  // Status of a media item's release/publication.
  enum ReleaseStatus {
    // Unknown or no data.
    RELEASE_STATUS_UNSPECIFIED = 0;

    // Released/published.
    RELEASED = 1;

    // Partially released/published, with more potentially planned to be
    // released in the future. E.g., an ongoing TV show.
    ONGOING = 2;

    // Not released/published. E.g., a movie that hasn't come out yet.
    UNRELEASED = 3;
  }

  // If specified, only items with one of these release statuses will match.
  repeated ReleaseStatus release_statuses = 1;

  // Options for related_media.
  message RelatedMedia {
    // Items to ignore.
    repeated string ignore = 1;

    // Classes to ignore instances of (subclasses of).
    repeated string classes_ignore = 2;

    // Classes to exclude (subclasses of) from the classes_ignore set.
    repeated string classes_ignore_excluded = 3;
  }

  // Filters for top-level media to find potential additional parts that aren't
  // present in the config file, and existing parts that aren't related to the
  // top-level Wikidata item. E.g., this can be used to find sequels to an item,
  // or to find all items in a franchise.
  RelatedMedia related_media = 2;
}

// Filters using the JustWatch API. In general, all specified/non-default fields
// must match the same thing for the filter to match the media item. E.g., if
// providers has "foo" and monetization_types has "bar", the media must be
// available on "foo" with monetization type "bar", not on "foo" with another
// monetization type and also on another service with monetization type "bar".
//
// If any of the fields that match on availability are set, this filter will
// make a key called "justwatch.provider" available for grouping on.
message JustWatchFilter {
  reserved 1;
  reserved "locale";

  // Required. Country code for JustWatch's API. These seem to be a subset of
  // <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>.
  string country = 8;

  // For the conditions below that match on availability, whether they should
  // include already done episodes or not.
  bool include_done = 5;

  // For the conditions below that match on availability, only consider offers
  // that do not end before this number of days.
  optional double available_after_days = 9;

  // For the conditions below that match on availability, only consider offers
  // that end before this number of days. This can be useful to filter for
  // content that's leaving streaming services in the near future, if you want
  // to prioritize watching that.
  optional double not_available_after_days = 7;

  // Which services provide the media. Run `rock-paper-sand justwatch providers`
  // to see the possible values.
  repeated string providers = 2;

  // How the media is monetized. Run `rock-paper-sand justwatch
  // monetizationTypes` to see the possible values.
  repeated string monetization_types = 3;

  // Match if the media is available in any way. It probably makes more sense to
  // use the providers and/or monetization_types fields instead in most cases,
  // but this can be useful to find media that might not be available anywhere
  // online.
  bool any_availability = 4;

  // Match if the media is completely done already. This is different from using
  // the filter {"done": "all"} because it uses JustWatch's API to check
  // specific seasons/episodes. E.g., if a 5 season show has its `done` field
  // set to "1 - 5", the {"done": "all"} filter would not match it because it
  // doesn't know that there are only 5 seasons, but this filter would.
  bool all_done = 6;
}

// A filter for media items.
message Filter {
  // Required. Configuration for the specific filter type.
  oneof filter {
    // Matches all media items.
    google.protobuf.Empty all = 1;

    // References another, named, filter.
    string ref = 2;

    // Inverts another filter.
    Filter not = 3;

    // Intersects other filters.
    Filters and = 4;

    // Unions other filters.
    Filters or = 5;

    // Whether the media item has children.
    bool has_parts = 8;

    // Matches media items that have this dotted number (or "all") included in
    // their `done` field. E.g., setting this to "2.3" (e.g., season 2 episode
    // 3) would match `done` fields of "2" (e.g., all of season 2), "2.2 - 2.3",
    // or "all". Setting this to "2" would match "2 - 3", but would not match
    // "2.2 - 3", because "2" includes "2.1", and "2.2 - 3" is missing that.
    string done = 9;

    // Matches on the name field.
    StringFieldMatcher name = 10;

    // Matches on the custom_data field.
    ArbitraryDataMatcher custom_data = 12;

    // Matches on the custom_availability field.
    StringFieldMatcher custom_availability = 6;

    // Filters using Wikidata APIs.
    WikidataFilter wikidata = 11;

    // Filters using the JustWatch API.
    JustWatchFilter justwatch = 7;
  }
}

// A filter with a name.
message NamedFilter {
  // Required, must be unique. Name of the filter.
  string name = 1;

  // Required. Filter.
  Filter filter = 2;
}

// Configuration for grouping the result of a filter by a key.
message GroupBy {
  // Required. Key to group by. See filter documentation for the available keys.
  string key = 1;
}

// A report about the media.
message Report {
  // Required, must be unique. Name of the report.
  string name = 2;

  // Sends an email with these headers when the report changes. Should include a
  // To header or similar for the email to be sent anywhere. If empty, no email
  // notifications are sent for this report.
  map<string, string> email_headers = 3;

  // The body of any email notifications.
  string email_body = 4;

  // A section of a report.
  message Section {
    // Required, must be unique. Name of the section.
    string name = 1;

    // In notification emails, whether to show a full diff on changes (false) or
    // a brief note that there were some changes (true).
    bool collapse_diff = 3;

    // Required. Which media items to include in this section.
    Filter filter = 2;

    // How to group the result of the filter.
    GroupBy group_by = 4;
  }

  // Sections to include in the report.
  repeated Section sections = 1;
}

// Lint configuration.
message Lint {
  reserved 3;
  reserved "require_unique_justwatch_id";

  // Media sorting options.
  message Sort {
    // Whether sorting should be case sensitive or not.
    bool case_sensitive = 1;
  }

  // If present, requires that the media list be sorted by name at the top
  // level.
  Sort sort = 1;

  // If present, the name of a report that should be empty if there are no
  // issues.
  string issues_report = 2;

  // If present, a JSON Schema to validate MediaItem.custom_data fields. See
  // https://json-schema.org/ for details.
  google.protobuf.Value custom_data_jsonschema = 4;
}

// A (possibly composite) item of media, e.g., a movie, TV show, or book, or
// fictional universe in which media is set.
message MediaItem {
  reserved 5 to 6;
  reserved "extra_information", "justwatch_id";

  // Required. Name of the item.
  string name = 1;

  // Any additional information that might be useful to a human reading the
  // data.
  string comment = 2;

  // Any JSON data you want. The default value if this isn't specified is null.
  google.protobuf.Value custom_data = 10;

  // Whether the item has already been watched/read/etc., and if so, how much.
  // For simple items, this should either be the empty string (not done) or the
  // string "all" (done). For TV shows, this is a comma-separated list of ranges
  // of season and episode numbers. Examples:
  //
  // "" / absent: Not done.
  // "all": All done.
  // "1 - 5": Seasons 1 to 5 done.
  // "1 - 2.2, 2.4 - 5": Seasons 1 to 5 done, except for season 2 episode 3.
  // "1 - 5, all": All done. This could be useful in a few cases:
  //    1. The show only has 5 seasons, and this can prevent an API call to
  //       check that each time.
  //    2. The show only has 5 seasons, and there isn't an API that can provide
  //       that information, so adding "all" makes it clear that the show is
  //       entirely done.
  //    3. The show has more than 5 seasons, but the user wants to pretend that
  //       seasons after 5 don't exist. E.g., to remove the show from a to-watch
  //       report section despite not having watched all of it.
  //
  // Note that there can be reasons to set this field to values other than
  // what's actually done. E.g., if you want to rewatch something, you might set
  // this field to what's done the second time, and use the comment field to
  // track what's actually been watched already.
  string done = 7;

  // Info about where the media is available, e.g., "bookshelf 5 shelf 2" or a
  // URL.
  string custom_availability = 4;

  // Primary Wikidata item URL or QID, e.g.,
  // "https://www.wikidata.org/wiki/Q3107329" or "Q3107329".
  string wikidata = 9;

  // Additional Wikidata items. E.g., a media item with parts might have both a
  // Wikidata item for a fictional universe and a Wikidata item for a media
  // franchise.
  repeated string wikidata_additional = 13;

  // Wikidata items to ignore when checking for related media.
  repeated string wikidata_ignore = 11;

  // Wikidata classes to ignore instances of (subclasses of) when checking for
  // related media.
  repeated string wikidata_classes_ignore = 12;

  // Wikidata classes to exclude (subclasses of) from the
  // wikidata_classes_ignore set.
  repeated string wikidata_classes_ignore_excluded = 14;

  // JustWatch URL or ID, e.g.,
  // "https://www.justwatch.com/us/tv-show/monty-pythons-flying-circus" or
  // "ts22164". The `rock-paper-sand justwatch node` command can be used to find
  // IDs for episodes of a show/season, because individual episodes don't seem
  // to have URLs.
  string justwatch = 8;

  // Parts of a media item. E.g., if the outer item is a fictional universe, the
  // parts could be movies in that universe.
  repeated MediaItem parts = 3;
}

// Top-level config.
message Config {
  // Filters, which can be referenced by other filters or in reports.
  repeated NamedFilter filters = 1;

  // Reports.
  repeated Report reports = 2;

  // Lint configuration.
  Lint lint = 4;

  // Media.
  repeated MediaItem media = 3;
}