syntax = "proto3";

package devvit.plugin.telemetry;

option go_package = "github.snooguts.net/reddit/reddit-devplatform-monorepo/go-common/generated/devvit/plugin/telemetry";
option java_package = "com.reddit.devvit.plugin.telemetry";

// TelemetryPlugin allows apps to emit journey-based telemetry events for analytics and ranking.
service TelemetryPlugin {
  // Starts a new telemetry journey.
  rpc StartJourney(StartJourneyRequest) returns (StartJourneyResponse);

  // Records progress within a journey.
  rpc JourneyProgress(JourneyProgressRequest) returns (JourneyProgressResponse);

  // Records an interaction within a journey.
  rpc JourneyInteraction(JourneyInteractionRequest) returns (JourneyInteractionResponse);

  // Ends a telemetry journey.
  rpc EndJourney(EndJourneyRequest) returns (EndJourneyResponse);

  // Signals that the app is ready and visible to the user.
  rpc AppReady(AppReadyRequest) returns (AppReadyResponse);
}

// Request to start a new telemetry journey.
message StartJourneyRequest {
  // Request is currently empty as journey ID is generated by the server.
}

// Response for starting a journey.
message StartJourneyResponse {
  // Unique identifier for the journey.
  // Example: "journey_1234567890"
  string journey_id = 1;
}

// Request to record progress within a journey.
message JourneyProgressRequest {
  // Unique identifier for the journey.
  // Example: "journey_1234567890"
  string journey_id = 1;
  // Normalized progress value between 0.0 and 1.0.
  // Example: 0.5
  float progress = 2;
  // The action that occurred during the progress update.
  // Example: "level_complete"
  optional string action = 3;
  // Additional details about the action.
  // Example: "level_3"
  optional string action_details = 4;
}

// Response for recording journey progress.
message JourneyProgressResponse {}

// Request to record an interaction within a journey.
message JourneyInteractionRequest {
  // Unique identifier for the journey.
  // Example: "journey_1234567890"
  string journey_id = 1;
  // The action that occurred during the interaction.
  // Example: "word_complete"
  string action = 2;
  // Additional details about the action.
  // Example: "apple"
  string action_details = 3;
}

// Response for recording a journey interaction.
message JourneyInteractionResponse {}

// Game-specific result data for journey completion.
message GameResult {
  // Indicates if the user won the game.
  // Example: true
  bool win = 1;
  // The final score achieved in the game.
  // Example: 1000
  int64 score = 2;
}

// Request to end a telemetry journey.
message EndJourneyRequest {
  // Unique identifier for the journey.
  // Example: "journey_1234567890"
  string journey_id = 1;
  // Indicates if the journey objective was completed.
  // Example: true
  bool complete = 2;
  // Game-specific result data. Only applicable for game journeys.
  optional GameResult game = 3;
}

// Response for ending a journey.
message EndJourneyResponse {}

// Request to signal that the app is ready.
message AppReadyRequest {
  // Milliseconds elapsed from runtime initialization to app ready, measured by the platform runtime.
  // Example: 350
  int64 startup_time_ms = 1;
}

// Response for the app ready signal.
message AppReadyResponse {}