Bluemage/schemas/proto/images/v1/list.proto

syntax = "proto3";

package images.v1;

import "buf/validate/validate.proto";
import "images/v1/types.proto";

message ListImagesRequest {
  option (buf.validate.message).cel = {
    id: "ListBySubredditRequest.after_cannot_exist_with_before"
    message: "after and before cannot be set at the same time"
    expression: "this.after > 0 && this.before > 0"
  };

  // subreddits filter the images to be fetched belonging to the given subreddits names.
  //
  // If empty, images from all subreddits will be fetched.
  repeated string subreddits = 1;
  // devices filter the images to be fetched belonging to the given devices slugs.
  //
  // If empty, images from all devices will be fetched.
  repeated string devices = 2;

  // limit limits the number of images to be fetched.
  //
  // if 0 (or not set), the default limit is 25.
  //
  // if set, the maximum limit is clamped to 100.
  int64 limit = 3 [(buf.validate.field).int64.gte = 0];
  // after lists the image after the given timestamp.
  //
  // using after will return images that are created after the given timestamp.
  //
  // cannot be set (value > 0) with before (value > 0).
  int64 after = 4;
  // before lists the image before the given timestamp.
  //
  // using before will return images that are created before the given timestamp.
  //
  // cannot be set (value > 0) with after (value > 0).
  int64 before = 5;

  // OrderBy orders the images by the given field.
  //
  // if not set, the default order is by created_at DESC,
  // regardless of the sort field.
  OrderBy order_by = 6;

  // sort orders the images by the given sort.
  Sort sort = 7;

  // search searches images by text. ignored if empty.
  //
  // It will look up by following rank and prioritizes matches
  // based on following fields:
  //
  //   - Author's name
  //   - Post Title
  //   - Post ID
  //   - Image filename (url path suffix to get this image from web browser)
  //   - Post url
  //   - Author's url
  string search = 8;

  // nsfw filters the images to be fetched based on the nsfw flag.
  NSFW nsfw = 9;

  // blacklist filters the images to be fetched based on the blacklist flag.
  Blacklist blacklist = 10;
}

message ListImagesResponse {
  repeated GroupedByDeviceImages devices = 1;

  // after is set if there are more images
  // after the last given image.
  optional int64 after = 2;

  // before is set if there are more images
  // before the first image in the result.
  optional int64 before = 3;
}