syntax = "proto3";

package worldmonitor.intelligence.v1;

import "buf/validate/validate.proto";
import "sebuf/http/annotations.proto";

// SearchGdeltDocumentsRequest specifies filters for searching GDELT news articles.
message SearchGdeltDocumentsRequest {
  // Search query string.
  string query = 1 [
    (buf.validate.field).required = true,
    (buf.validate.field).string.min_len = 1,
    (sebuf.http.query) = { name: "query" }
  ];
  // Maximum number of articles to return. Defaults to 10 when omitted or <= 0. The
  // handler caps returned results at 20, so values above 20 (though accepted, up to the
  // validation limit of 250) still return at most 20 articles.
  int32 max_records = 2 [
    (buf.validate.field).int32.gte = 1,
    (buf.validate.field).int32.lte = 250,
    (sebuf.http.query) = { name: "max_records" }
  ];
  // Time span filter (e.g., "15min", "1h", "24h").
  // Accepted but currently ignored; no-op until this handler supports the parameter.
  string timespan = 3 [(sebuf.http.query) = { name: "timespan" }, (sebuf.http.unimplemented) = true];
  // Tone filter appended to query (e.g., "tone>5" for positive, "tone<-5" for negative).
  // Left empty to skip tone filtering.
  // Accepted but currently ignored; no-op until this handler supports the parameter.
  string tone_filter = 4 [(sebuf.http.query) = { name: "tone_filter" }, (sebuf.http.unimplemented) = true];
  // Sort mode: "DateDesc" (default), "ToneDesc", "ToneAsc", "HybridRel".
  // Accepted but currently ignored; no-op until this handler supports the parameter.
  string sort = 5 [(sebuf.http.query) = { name: "sort" }, (sebuf.http.unimplemented) = true];
}

// GdeltArticle represents a single article from the GDELT document API.
message GdeltArticle {
  // Article headline.
  string title = 1;
  // Article URL.
  string url = 2;
  // Source domain name.
  string source = 3;
  // Publication date string.
  string date = 4;
  // Article image URL.
  string image = 5;
  // Article language code.
  string language = 6;
  // GDELT tone score (negative = negative tone, positive = positive tone).
  double tone = 7;
}

// SearchGdeltDocumentsResponse contains GDELT article search results.
message SearchGdeltDocumentsResponse {
  // Matching articles.
  repeated GdeltArticle articles = 1;
  // Echo of the search query.
  string query = 2;
  // Error message if the search failed.
  string error = 3;
}
