package responses

// PresignUploadResponse is what /api/uploads/presign returns to the client.
//
// Flow: the client makes one PUT request to URL with the raw object bytes
// as the body and Headers as the request headers (verbatim — the signature
// binds them). On success, the client passes ID back via upload_ids[] on
// POST /api/task-completions/ or POST /api/documents/ to claim and attach
// the object.
//
// We use PUT (not POST) because Backblaze B2's S3-compatible endpoint does
// not implement the S3 POST Object form upload — it returns HTTP 501 on
// every request style. PUT works against AWS S3, B2, and MinIO uniformly.
type PresignUploadResponse struct {
	// ID is the pending_uploads.id the client passes back via upload_ids[].
	ID uint `json:"id"`

	// URL is the signed PUT URL. Includes all auth as query parameters.
	URL string `json:"upload_url"`

	// Method is always "PUT" — emitted explicitly so clients don't have to
	// hardcode it. Reserved for the rare case we ever offer alternative
	// upload mechanisms.
	Method string `json:"method"`

	// Headers must be sent verbatim on the PUT request. Currently includes
	// Content-Type and Content-Length; both are signed, and B2 will reject
	// any PUT whose headers don't match.
	Headers map[string]string `json:"headers"`

	// Key is the object key chosen by the server. Echoed for client logging
	// and debugging; the canonical reference is via ID.
	Key string `json:"key"`

	// ExpiresAt is when the signed URL stops working. Clients should retry
	// with a fresh presign rather than relying on long-lived URLs.
	ExpiresAt string `json:"expires_at"`
}