syntax = "proto3";

package devvit.plugin.externalendpoints.v1alpha;

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

// External endpoint token / endpoint access permission.
enum Scope {
  SCOPE_UNSPECIFIED = 0;
  // Install allows short-lived callback tokens generated by the app in an
  // outgoing `fetch()` wherever the app is installed (a subreddit or user
  // account).
  SCOPE_INSTALL = 1;
  // Global allows managed tokens.
  SCOPE_GLOBAL = 2;
}

service ExternalEndpoints {
  // Get a callback URL for the specified endpoint with a short-term token.
  // Eg,
  // `https://wsbapp-2th52-external.devvit.net/external/on/image/generated?externalToken=devvit_at_abc123`.
  // Useful for run-as and any ephemeral usage.
  rpc GetCallbackUrl(GetCallbackUrlRequest) returns (GetCallbackUrlResponse);
  // Get the root `/external/` URL of an install for long-term tokens. Eg,
  // `https://wsbapp-2th52-external.devvit.net/external/`. Useful for
  // install-to-install communication.
  rpc GetExternalUrl(GetExternalUrlRequest) returns (GetExternalUrlResponse);
}

message GetCallbackUrlRequest {
  // Name of the external endpoint entry in `devvit.json`
  // `server.externalEndpoints`. eg, `OnImageReady`.
  string entry = 1;
}

message GetCallbackUrlResponse {
  // full callback URL including token
  // e.g. https://wsbapp-2th52-external.devvit.net/external/on/image/generated?externalToken=devvit_at_abc123
  string callback_url = 1;
}

message GetExternalUrlRequest {
  // The account of the install. Eg, `wsbapp`.
  string app_slug = 1;
  // The T5 of the install. Eg, `t5_2th52`.
  string location_id = 2;
}

message GetExternalUrlResponse {
  // URL for the root external endpoint of the install. Eg,
  // `https://wsbapp-2th52-external.devvit.net/external/`.
  string external_url = 1;
}