officeconvert/proto/officeconvertapi/v1/conversion.proto

syntax = "proto3";

package officeconvertapi.v1;

import "google/protobuf/timestamp.proto";

option go_package = "gitea.auvem.com/end-internal/officeconvert/gen/go/officeconvertapi/v1;officeconvertapiv1";

// ConversionService orchestrates presentation conversion jobs.
service ConversionService {
  // CreateConversion allocates a short-lived session and upload URL for a PPTX.
  rpc CreateConversion(CreateConversionRequest) returns (CreateConversionResponse) {}

  // StartConversion marks upload completion and starts server-side conversion.
  rpc StartConversion(StartConversionRequest) returns (StartConversionResponse) {}

  // GetConversionStatus returns state transitions for a conversion session.
  rpc GetConversionStatus(GetConversionStatusRequest) returns (GetConversionStatusResponse) {}

  // GetSlideDeck fetches the final slide deck data after successful conversion.
  rpc GetSlideDeck(GetSlideDeckRequest) returns (GetSlideDeckResponse) {}

  // DeleteConversion deletes session resources before automatic expiration.
  rpc DeleteConversion(DeleteConversionRequest) returns (DeleteConversionResponse) {}
}

// ConversionStatus represents the lifecycle state of a conversion request.
enum ConversionStatus {
  CONVERSION_STATUS_UNSPECIFIED = 0;
  CONVERSION_STATUS_PENDING = 1;
  CONVERSION_STATUS_RUNNING = 2;
  CONVERSION_STATUS_SUCCEEDED = 3;
  CONVERSION_STATUS_FAILED = 4;
}

// ConversionPhase represents the active stage for a running conversion.
enum ConversionPhase {
  CONVERSION_PHASE_UNSPECIFIED = 0;
  CONVERSION_PHASE_INACTIVE = 1;
  CONVERSION_PHASE_EXTRACTING_NOTES = 2;
  CONVERSION_PHASE_PPTX_TO_PDF = 3;
  CONVERSION_PHASE_PDF_TO_IMAGES = 4;
  CONVERSION_PHASE_UPLOADING_RESULTS = 5;
}

// ConversionResolution represents preset output quality targets.
enum ConversionResolution {
  CONVERSION_RESOLUTION_UNSPECIFIED = 0;
  CONVERSION_RESOLUTION_SD = 1;
  CONVERSION_RESOLUTION_HD = 2;
  CONVERSION_RESOLUTION_FHD = 3;
  CONVERSION_RESOLUTION_QHD = 4;
  CONVERSION_RESOLUTION_UHD = 5;
}

// Slide contains extracted notes and the rendered image URL for one slide.
message Slide {
  int32 index = 1;
  string notes_plain = 2;
  string image_url = 3;
}

// SlideDeck is the final structured conversion artifact.
message SlideDeck {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
  string source_filename = 2;
  repeated Slide slides = 3;
  google.protobuf.Timestamp created_at = 4;
  int32 width = 5;
  int32 height = 6;
}

// CreateConversionRequest starts a conversion session.
message CreateConversionRequest {
  string source_filename = 1;
  ConversionResolution resolution = 2;
}

// CreateConversionResponse returns upload details for the session.
message CreateConversionResponse {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
  string upload_bucket = 2;
  string upload_object_key = 3;
  string upload_url = 4;
  google.protobuf.Timestamp expires_at = 5;
}

// StartConversionRequest requests conversion of an already uploaded PPTX.
message StartConversionRequest {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
}

// StartConversionResponse returns the first known status after enqueue.
message StartConversionResponse {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
  ConversionStatus status = 2;
}

// GetConversionStatusRequest asks for a specific conversion status.
message GetConversionStatusRequest {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
}

// GetConversionStatusResponse returns current status and optional error info.
message GetConversionStatusResponse {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
  ConversionStatus status = 2;
  string error_message = 3;
  google.protobuf.Timestamp updated_at = 4;
  ConversionPhase phase = 5;
  int32 current_progress = 6;
  int32 max_progress = 7;
}

// GetSlideDeckRequest fetches a completed deck.
message GetSlideDeckRequest {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
}

// GetSlideDeckResponse contains the converted slide deck.
message GetSlideDeckResponse {
  SlideDeck slide_deck = 1;
}

// DeleteConversionRequest requests immediate cleanup.
message DeleteConversionRequest {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
}

// DeleteConversionResponse confirms cleanup details.
message DeleteConversionResponse {
  // Session identifier: KSUID in standard base62 text form. Well-formed values are at most 27 characters (see https://github.com/segmentio/ksuid).
  string conversion_id = 1;
  bool deleted = 2;
}