syntax = "proto3";

package billing.documents.v1;

option go_package = "github.com/tech/sendico/pkg/proto/billing/documents/v1;documentsv1";


// ---------------------------
// ENUMS
// ---------------------------

// DocumentType defines supported accounting document kinds.
enum DocumentType {
  DOCUMENT_TYPE_UNSPECIFIED = 0;

  // Invoice issued for the payment
  DOCUMENT_TYPE_INVOICE     = 1;

  // Service acceptance act (common in EU/RU accounting)
  DOCUMENT_TYPE_ACT         = 2;

  // Simple receipt confirmation
  DOCUMENT_TYPE_RECEIPT     = 3;
}


// ---------------------------
// SERVICE
// ---------------------------

// DocumentService provides document metadata for payment lists
// and lazy document generation on demand.
service DocumentService {

  // BatchResolveDocuments is used by BFF when rendering
  // a page of payments. This prevents N+1 calls by resolving
  // document metadata for many payments in a single request.
  rpc BatchResolveDocuments(BatchResolveDocumentsRequest)
      returns (BatchResolveDocumentsResponse);

  // GetDocument returns the actual PDF file.
  // If the document was not generated before, the service
  // generates it lazily, stores it, and returns it.
  rpc GetDocument(GetDocumentRequest)
      returns (GetDocumentResponse);
}


// ---------------------------
// BATCH RESOLVE (for payment tables)
// ---------------------------

// BatchResolveDocumentsRequest contains a list of payment references
// for which document availability should be resolved.
message BatchResolveDocumentsRequest {
  repeated string payment_refs = 1;
}

// DocumentMeta describes document availability for a single payment.
message DocumentMeta {
  // Payment reference
  string payment_ref = 1;

  // Document types that are applicable for this payment
  // based on business rules and payment snapshot.
  repeated DocumentType available_types = 2;

  // Document types that were already generated and stored.
  // Other available types will be generated lazily when requested.
  repeated DocumentType ready_types = 3;
}

// BatchResolveDocumentsResponse returns metadata for all requested payments.
message BatchResolveDocumentsResponse {
  repeated DocumentMeta items = 1;
}


// ---------------------------
// GET DOCUMENT (lazy generation)
// ---------------------------

// GetDocumentRequest requests a specific document for a payment.
message GetDocumentRequest {
  string payment_ref = 1;

  // Type of document to retrieve (invoice, act, receipt, etc.)
  DocumentType type  = 2;
}

// GetDocumentResponse returns the generated PDF content.
message GetDocumentResponse {
  // Raw PDF bytes
  bytes  content   = 1;

  // Suggested filename for download (e.g. invoice_123.pdf)
  string filename  = 2;

  // MIME type, typically "application/pdf"
  string mime_type = 3;
}