// Package datatables gives plugins typed access to site data tables (the Data
// Platform's data_tables/data_table_rows), which the per-plugin Postgres role
// deliberately cannot reach with raw SQL. The CMS implements this interface
// host-side and wires it into CoreServices; row payloads cross the ABI as JSON.
package datatables

import (
	"context"

	"github.com/google/uuid"
)

// DataTables provides read/write access to site data tables for plugins.
type DataTables interface {
	// GetTableByKey resolves a data table by its stable key (e.g. "playgrounds").
	GetTableByKey(ctx context.Context, tableKey string) (*Table, error)
	// GetRow fetches a single row by ID.
	GetRow(ctx context.Context, rowID uuid.UUID) (*Row, error)
	// ListRows pages through a table's rows in sort order. limit <= 0 applies
	// the host default.
	ListRows(ctx context.Context, tableID uuid.UUID, limit, offset int32) ([]Row, error)
	// CreateRow appends a row with the given JSON object payload.
	CreateRow(ctx context.Context, tableID uuid.UUID, dataJSON []byte) (*Row, error)
	// UpdateRowData replaces a row's JSON payload, preserving its sort order.
	UpdateRowData(ctx context.Context, rowID uuid.UUID, dataJSON []byte) (*Row, error)
	// FindRowByField returns the first row whose data->>field equals value, or
	// (nil, nil) when no row matches.
	FindRowByField(ctx context.Context, tableID uuid.UUID, field, value string) (*Row, error)
}

// Table is a plugin-facing view of a data table.
type Table struct {
	ID       uuid.UUID
	TableKey string
	Name     string
	RowCount int32
}

// Row is a plugin-facing view of a data table row. DataJSON is the row's data
// column verbatim (a JSON object).
type Row struct {
	ID        uuid.UUID
	TableID   uuid.UUID
	DataJSON  []byte
	SortOrder int32
}