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;
}

// JpegOutputOptions configures JPEG-specific encoding controls.
message JpegOutputOptions {
  // JPEG quality from 1..100. 0 means server default.
  int32 quality = 1;
}

// SlideRasterOptions defines rendering settings for a raster output tier.
message SlideRasterOptions {
  // Output resolution preset. UNSPECIFIED means server default for the tier.
  ConversionResolution resolution = 1;
  oneof format {
    JpegOutputOptions jpeg = 2;
  }
}

// NotesFormat controls what note representation the server should compute.
enum NotesFormat {
  NOTES_FORMAT_UNSPECIFIED = 0;
  NOTES_FORMAT_PLAIN = 1;
  NOTES_FORMAT_HTML = 2;
}

// HtmlFormattingPolicy configures which formatting features are ignored in HTML mode.
message HtmlFormattingPolicy {
  bool ignore_bold = 1;
  bool ignore_italic = 2;
  bool ignore_underline = 3;
  bool ignore_strikethrough = 4;
  bool ignore_font_size = 5;
  bool ignore_color = 6;
}

// NotesOptions configures note extraction behavior.
message NotesOptions {
  // Output format for extracted notes.
  NotesFormat format = 1;
  // If true, wrap PPTX paragraphs as <p> blocks in HTML mode. If false, emit <br/> only.
  optional bool html_use_paragraph_tags = 2;
  // Formatting policy for HTML mode.
  HtmlFormattingPolicy html_policy = 3;
}

// Slide contains extracted notes and the rendered image URL for one slide.
message Slide {
  int32 index = 1;
  string notes_plain = 2;
  // Full-size rendered image URL.
  string image_url = 3;
  // Thumbnail rendered image URL.
  string thumbnail_image_url = 4;
  // Optional, sanitized HTML version of notes when requested.
  string notes_html = 5;
}

// 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;
  // Full-size raster width in pixels.
  int32 width = 5;
  // Full-size raster height in pixels.
  int32 height = 6;
  // Thumbnail raster width in pixels.
  int32 thumbnail_width = 7;
  // Thumbnail raster height in pixels.
  int32 thumbnail_height = 8;
}

// CreateConversionRequest starts a conversion session.
message CreateConversionRequest {
  string source_filename = 1;
  SlideRasterOptions full = 2;
  SlideRasterOptions thumbnail = 3;
  NotesOptions notes = 4;
}

// 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;
}