query-orchestration/internal/customschema/models.go

package customschema

import (
	"encoding/json"
	"time"

	"github.com/google/uuid"
)

// Schema is the full representation of a client_metadata_schemas row as
// returned by service methods that operate on a single schema. The status
// is represented as a plain string ("active", "superseded", "retired") so
// HTTP handlers can serialize it without pulling in the repository enum.
type Schema struct {
	ID          uuid.UUID
	ClientID    string
	Name        string
	Description string
	SchemaDef   json.RawMessage
	Version     int
	Status      string
	CreatedAt   time.Time
	CreatedBy   string
}

// SchemaSummary is a list-view row. Derived from ListClientMetadataSchemasRow
// and augmented with DocumentCount and CanDelete (canDelete is true iff
// DocumentCount == 0, mirroring plan Section 7.1).
type SchemaSummary struct {
	Schema        Schema
	DocumentCount int64
	CanDelete     bool
}

// CreateSchemaInput carries the body of POST /super-admin/custom-schemas.
// v4 rule: the actor (Cognito subject) is passed as a separate argument
// to CreateSchema, NOT carried as a field on this struct. Do not add a
// CreatedBy field here.
type CreateSchemaInput struct {
	ClientID    string
	Name        string
	Description string
	SchemaDef   json.RawMessage
}

// CreateSchemaVersionInput carries the body of
// POST /super-admin/custom-schemas/{schemaId}/versions. Actor is passed
// as a separate argument to CreateSchemaVersion, not a field here. Name
// and ClientID are intentionally absent — both are derived from the
// parent schema row inside the version-creation transaction.
type CreateSchemaVersionInput struct {
	Description string
	SchemaDef   json.RawMessage
}

// CustomMetadata is the full representation of a document_custom_metadata
// row returned to handlers. The v4 join in GetCurrentDocumentCustomMetadata
// / GetDocumentCustomMetadataByVersion decorates each row with the document's
// currently-bound schema id, schema name, and schema version so handlers
// can populate their responses in a single round-trip.
//
// SchemaID, SchemaName, and SchemaVersion are pointer types because the LEFT
// JOIN on client_metadata_schemas returns NULL when a document's binding has
// been cleared (rare edge case: metadata already exists but the admin used
// schema/assign with a nil schemaID on an otherwise empty document). In the
// common case all three are populated.
type CustomMetadata struct {
	ID            uuid.UUID
	DocumentID    uuid.UUID
	Metadata      json.RawMessage
	Version       int
	SchemaID      *uuid.UUID
	SchemaName    *string
	SchemaVersion *int
	CreatedAt     time.Time
	CreatedBy     string
}

// MetadataVersion is a terse history row for GET /custom-metadata/history.
// No metadata payload, no schema decoration — just the audit fields that
// let a caller decide which version to fetch in full.
type MetadataVersion struct {
	Version   int
	CreatedAt time.Time
	CreatedBy string
}

// SetMetadataInput carries the body of POST /custom-metadata. v4 rule: the
// actor (Cognito subject) is passed as a separate argument to
// SetDocumentMetadata, NOT carried as a field here. Do not add a CreatedBy
// field.
type SetMetadataInput struct {
	DocumentID uuid.UUID
	Metadata   json.RawMessage
}

// AssignSchemaResult is returned by AssignSchema so the handler can build
// the DocumentSchemaAssignResponse in one shot. When schemaID == nil (the
// "clear binding" case), all three schema pointers are nil.
type AssignSchemaResult struct {
	DocumentID     uuid.UUID
	CustomSchemaID *uuid.UUID
	SchemaName     *string
	SchemaVersion  *int
}

// ListFilters drives ListSchemas.
//
// Status semantics:
//   - zero value ("") means the default "active" filter.
//   - StatusAny == true means "return schemas of every status" and maps to
//     the underlying query's include_all_statuses = true. When StatusAny is
//     true the Status field is ignored.
//
// IncludeAllVersions == false collapses results to MAX(version) per
// (client_id, name). Limit/Offset drive pagination.
type ListFilters struct {
	Name               string
	Status             string
	StatusAny          bool
	IncludeAllVersions bool
	Limit              int32
	Offset             int32
}