discovery

type AuthBootstrap struct {
	// Collection is the resolved auth-collection slug.
	Collection string
	// Source is "bootstrap" when Stage -1 ran, "configured" when it was
	// skipped because the slug was set, "cached" when it came from
	// auth-resolution.json.
	Source string
	// Candidates are every slug that survived the /init filter, in the order
	// they were tried. They are recorded in diagnostics.auth_candidates[].
	Candidates []string
	// Truncated reports that the candidate set was the anonymous slug list
	// alone.
	Truncated bool
	// Requests is the number of HTTP requests Stage -1 spent.
	Requests int
}

type BlockResolution struct {
	Slugs  []string
	Source string
	// Reason is the plain-words explanation written into
	// publishable_reason when nothing resolved.
	Reason string
}

type BlockSources struct {
	// Configured is the profile's blocks map, keyed by field path.
	Configured map[string][]string
	// ProjectSource is §7.10's local filesystem scan result — every slug:
	// literal found in an object that also has fields:. It is not keyed by
	// field because the scan cannot know which collection a block belongs to.
	ProjectSource []string
	// ProjectSourceFiles are the absolute paths each slug came from, recorded
	// in diagnostics.block_slug_files[].
	ProjectSourceFiles []string
	// Observed are blockType values seen in sampled documents, keyed by field
	// path. On a fresh project this yields nothing — verified that all 12 live
	// pages have layout: [].
	Observed map[string][]string
}

type Capabilities struct {
	GraphQL         GraphQLCapability `json:"graphql"`
	Localization    Localization      `json:"localization"`
	Reorder         *bool             `json:"reorder"`
	OG              *bool             `json:"og"`
	MethodOverride  *bool             `json:"method_override"`
	Jobs            Jobs              `json:"jobs"`
	Preferences     Preferences       `json:"preferences"`
	CustomEndpoints []string          `json:"custom_endpoints"`
}

type Collection struct {
	Slug         string        `json:"slug"`
	Labels       Labels        `json:"labels"`
	GraphQL      *GraphQLNames `json:"graphql"`
	IDType       string        `json:"id_type"`
	IDTypeSource string        `json:"id_type_source"`
	Reachability string        `json:"reachability"`
	Internal     bool          `json:"internal"`

	Publishable       bool    `json:"publishable"`
	PublishableReason *string `json:"publishable_reason"`

	Flags       Flags       `json:"flags"`
	FlagsSource FlagsSource `json:"flags_source"`
	Permissions Permissions `json:"permissions"`

	Stats Stats `json:"stats"`

	FieldsCount  int    `json:"fields_count"`
	FieldsSHA256 string `json:"fields_sha256"`
	FieldsShard  string `json:"fields_shard"`
	FieldsSource string `json:"fields_source"`

	TitleField *string  `json:"title_field"`
	DateFields []string `json:"date_fields"`
	Warnings   []string `json:"warnings"`
}

type Diagnostics struct {
	Requests          int      `json:"requests"`
	ElapsedMS         int64    `json:"elapsed_ms"`
	Bytes             int64    `json:"bytes"`
	GraphQLBatches    int      `json:"graphql_batches"`
	Degraded          []string `json:"degraded"`
	Warnings          []string `json:"warnings"`
	CreatedAndDeleted []string `json:"created_and_deleted"`
	AuthCandidates    []string `json:"auth_candidates"`
	BlockSlugFiles    []string `json:"block_slug_files"`
}

type Discoverer struct {
	// contains filtered or unexported fields
}

type Field struct {
	Name        string  `json:"name"`
	Path        string  `json:"path"`
	GraphQLPath string  `json:"graphql_path"`
	Parent      *string `json:"parent"`

	PayloadType           string `json:"payload_type"`
	PayloadTypeConfidence string `json:"payload_type_confidence"`

	GraphQLType *string `json:"graphql_type"`
	JSONType    string  `json:"json_type"`

	Required       *bool  `json:"required"`
	RequiredSource string `json:"required_source"`

	HasMany         bool   `json:"has_many"`
	Localized       *bool  `json:"localized"`
	LocalizedSource string `json:"localized_source"`

	ReadOnly bool `json:"read_only"`

	Options       []string `json:"options"`
	OptionsSource string   `json:"options_source"`

	RelationTo       []string `json:"relation_to"`
	RelationToSource string   `json:"relation_to_source"`
	Polymorphic      bool     `json:"polymorphic"`

	// WriteShape is mandatory and non-null on every relationship, upload and
	// polymorphic field and null on every other kind. §9.10's --set coercion
	// reads exactly this key.
	WriteShape *string `json:"write_shape"`

	Queryable bool     `json:"queryable"`
	Operators []string `json:"operators"`

	Sortable           bool   `json:"sortable"`
	SortableConfidence string `json:"sortable_confidence"`

	HookMutated string `json:"hook_mutated"`

	Label string `json:"label"`
}

type Fingerprint struct {
	TopologySHA256 string    `json:"topology_sha256"`
	SchemaSHA256   string    `json:"schema_sha256"`
	CheckedAt      time.Time `json:"checked_at"`
	ServerIdentity string    `json:"server_identity"`
}

type Flags struct {
	Upload            *bool `json:"upload"`
	Auth              *bool `json:"auth"`
	UseAPIKey         *bool `json:"use_api_key"`
	Versions          *bool `json:"versions"`
	Drafts            *bool `json:"drafts"`
	Trash             *bool `json:"trash"`
	Folders           *bool `json:"folders"`
	Duplicate         *bool `json:"duplicate"`
	Orderable         *bool `json:"orderable"`
	EndpointsDisabled *bool `json:"endpoints_disabled"`
}

type FlagsSource struct {
	Upload            string `json:"upload"`
	Auth              string `json:"auth"`
	UseAPIKey         string `json:"use_api_key"`
	Versions          string `json:"versions"`
	Drafts            string `json:"drafts"`
	Trash             string `json:"trash"`
	Folders           string `json:"folders"`
	Duplicate         string `json:"duplicate"`
	Orderable         string `json:"orderable"`
	EndpointsDisabled string `json:"endpoints_disabled"`
}

type Global struct {
	Slug         string        `json:"slug"`
	Labels       Labels        `json:"labels"`
	GraphQL      *GraphQLNames `json:"graphql"`
	Reachability string        `json:"reachability"`
	Internal     bool          `json:"internal"`

	Flags       GlobalFlags       `json:"flags"`
	FlagsSource GlobalFlagsSource `json:"flags_source"`
	Permissions GlobalPermissions `json:"permissions"`

	FieldsCount  int    `json:"fields_count"`
	FieldsSHA256 string `json:"fields_sha256"`
	FieldsShard  string `json:"fields_shard"`
	FieldsSource string `json:"fields_source"`

	Warnings []string `json:"warnings"`
}

type GlobalFlags struct {
	Versions *bool `json:"versions"`
	Drafts   *bool `json:"drafts"`
}

type GlobalFlagsSource struct {
	Versions string `json:"versions"`
	Drafts   string `json:"drafts"`
}

type GlobalPermissions struct {
	Read         bool  `json:"read"`
	Update       bool  `json:"update"`
	ReadVersions bool  `json:"read_versions"`
	FieldLevel   *bool `json:"field_level"`
}

type GraphQLCapability struct {
	Mode          string `json:"mode"`
	Introspection *bool  `json:"introspection"`
	Path          string `json:"path"`
	Detail        string `json:"detail,omitempty"`
	Hint          string `json:"hint,omitempty"`
}

type GraphQLNames struct {
	Singular string `json:"singular"`
	Plural   string `json:"plural,omitempty"`
	Count    string `json:"count,omitempty"`
	Source   string `json:"source"`
}

type IDLadderInput struct {
	// GraphQL is the Stage-1 answer, "" when GraphQL was unavailable.
	GraphQL string
	// SampleID is docs[0].id from GET /{slug}?limit=1&depth=0&select[id]=true.
	SampleID any
	// SampleIDPresent distinguishes "the collection is empty" from "id was
	// null".
	SampleIDPresent bool
	// VersionParentID is docs[0].parent from /{slug}/versions, which is the
	// *document* id while the version's own id is a different row.
	VersionParentID      any
	VersionParentPresent bool
	// Configured is the profile's id_type pin.
	Configured string
}

type Identity struct {
	AuthMode             string  `json:"auth_mode"`
	AuthCollection       *string `json:"auth_collection"`
	AuthCollectionSource string  `json:"auth_collection_source"`
	UserID               any     `json:"user_id"`
	Verified             bool    `json:"verified"`
	CanAccessAdmin       bool    `json:"can_access_admin"`
	Strategy             string  `json:"strategy"`
	KeyFingerprint       string  `json:"key_fingerprint"`
}

type IntroArg struct {
	Name string   `json:"name"`
	Type *TypeRef `json:"type"`
}

type IntroEnumValue struct {
	Name string `json:"name"`
}

type IntroField struct {
	Name string     `json:"name"`
	Args []IntroArg `json:"args"`
	Type *TypeRef   `json:"type"`
}

type IntroInputField struct {
	Name string   `json:"name"`
	Type *TypeRef `json:"type"`
}

type IntroType struct {
	Kind          string            `json:"kind"`
	Name          string            `json:"name"`
	Fields        []IntroField      `json:"fields"`
	InputFields   []IntroInputField `json:"inputFields"`
	EnumValues    []IntroEnumValue  `json:"enumValues"`
	PossibleTypes []IntroTypeName   `json:"possibleTypes"`
}

type IntroTypeName struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
}

type Jobs struct {
	Collection  *string `json:"collection"`
	StatsGlobal *string `json:"stats_global"`
}

type Kind struct {
	PayloadType string
	Confidence  string
	JSONType    string
	HasMany     bool
	ReadOnly    bool
	Polymorphic bool

	Options       []string
	OptionsSource string

	RelationTo       []string
	RelationToSource string

	// Blocks is the UNION member list for a blocks field. These are
	// interfaceNames, NOT blockType slugs — §7.10 resolves the real slugs from
	// project source.
	BlockInterfaces []string

	// Children is the named type whose fields should be walked as nested
	// group/array entries, or "" when there are none.
	Children string
	// Leaves are type names this inference needs resolved to be complete.
	Leaves []string
}

type Labels struct {
	Singular string `json:"singular"`
	Plural   string `json:"plural"`
	Source   string `json:"source"`
}

type LearnedFailure struct {
	Operator   string    `json:"operator"`
	Collection string    `json:"collection"`
	Evidence   string    `json:"evidence"`
	LearnedAt  time.Time `json:"learned_at"`
}

type Limitation struct {
	Code       string `json:"code"`
	Entity     string `json:"entity,omitempty"`
	Field      string `json:"field,omitempty"`
	Detail     string `json:"detail,omitempty"`
	Mitigation string `json:"mitigation"`
}

type LocaleAnalysis struct {
	// Candidates are the true locale codes, or nil when the sample proved
	// nothing. These are real codes, unlike the formatName()-mangled names the
	// GraphQL LocaleInputType enum exposes.
	Candidates []string
	// Localized are the field names that came back as a locale map.
	Localized []string
	// NotLocalized are the field names that did not, on a document where at
	// least one sibling did — which is the only evidence REST offers for a
	// per-field false.
	NotLocalized []string
}

type LocaleInput struct {
	// Configured is the profile's locales pin.
	Configured []string
	// Analysis is the locale=all sample result.
	Analysis LocaleAnalysis
	// EnumNames are LocaleInputType's enumValues, which are
	// formatName()-mangled and are therefore NEVER usable as codes.
	EnumNames []string
	// GraphQLReachable reports whether the cross-validation could run at all.
	GraphQLReachable bool
}

type Localization struct {
	Enabled *bool `json:"enabled"`
	// EnabledSource is the story behind `enabled`, which §7.8.3 requires of
	// every derived fact: "graphql-arg" / "graphql-arg-absent" when the plural
	// Query field settled it, "locale-all" when a ?locale=all sample proved it
	// positively, "configured" when the profile pinned locale codes, and
	// "unknown" while it is still nil.
	EnabledSource string   `json:"enabled_source"`
	Locales       []string `json:"locales"`
	// Default is Payload's localization.defaultLocale. No API exposes it, so
	// it is null unless something actually established it — it is NEVER the
	// first entry of a sorted locale list (§21.3 rule 1: a defaulted value is
	// not a discovered fact).
	Default         *string `json:"default"`
	DefaultSource   string  `json:"default_source"`
	LocalesSource   string  `json:"locales_source"`
	FallbackDefault *string `json:"fallback_default"`
	LocaleCount     *int    `json:"locale_count"`
}

type Manifest struct {
	ManifestVersion int       `json:"manifest_version"`
	Generation      string    `json:"generation"`
	CLIVersion      string    `json:"cli_version"`
	GeneratedAt     time.Time `json:"generated_at"`
	ExpiresAt       time.Time `json:"expires_at"`

	Meta        ManifestMeta `json:"meta"`
	Fingerprint Fingerprint  `json:"fingerprint"`
	Source      Source       `json:"source"`
	Identity    Identity     `json:"identity"`

	Capabilities Capabilities `json:"capabilities"`

	Collections []*Collection `json:"collections"`
	Globals     []*Global     `json:"globals"`

	Unreachable             []Unreachable         `json:"unreachable"`
	Limitations             []Limitation          `json:"limitations"`
	UnsupportedOperators    []UnsupportedOperator `json:"unsupported_operators"`
	LearnedOperatorFailures []LearnedFailure      `json:"learned_operator_failures"`

	Diagnostics Diagnostics `json:"diagnostics"`
}

type ManifestMeta struct {
	Scope          string    `json:"scope"`
	Profiles       []string  `json:"profiles"`
	BaseURL        string    `json:"base_url"`
	APIPath        string    `json:"api_path"`
	GraphQLPath    string    `json:"graphql_path"`
	HeaderNames    []string  `json:"header_names"`
	KeyFingerprint string    `json:"key_fingerprint"`
	CreatedAt      time.Time `json:"created_at"`
	ConfirmedAt    time.Time `json:"confirmed_at"`
}

type Options struct {
	Client *payload.Client

	BaseURL string

	APIPath       string
	APIPathSource string
	// GraphQLRoute is routes.graphQL, defaulting to /graphql. graphql_path is
	// DERIVED from api_path + this (§1 conflict 34), never an independent
	// literal.
	GraphQLRoute      string
	GraphQLPath       string
	GraphQLPathSource string

	AuthMode       string
	AuthCollection string
	// AuthCollectionSource is "configured" when the slug was pinned.
	AuthCollectionSource string
	// CachedAuthCollection is a slug already resolved for this
	// (normURL, keyFP) pair by a previous run (§7.0e). When set, Stage -1 is
	// skipped entirely.
	CachedAuthCollection string
	// CredentialAbsent reports anonymous operation. Stage 0's /me request is
	// then not made at all and discovery continues.
	CredentialAbsent bool
	KeyFingerprint   string

	Concurrency int

	Profile     string
	Profiles    []string
	ScopeKey    string
	HeaderNames []string

	CLIVersion string
	Generation string
	Now        func() time.Time
	TTL        time.Duration

	// Deep widens Stage 3 to every collection and adds the document census.
	Deep bool
	// AllowWriteProbes enables §7.7's empty-POST harvest. It creates a real
	// document in any collection with no required fields, so it is off by
	// default and the flag name is deliberately unpleasant.
	AllowWriteProbes bool
	// NoLabels skips §7.5 probe 8, which is the only DELETE verb discovery
	// ever issues.
	NoLabels bool
	// NoProbes disables Stage 3 entirely.
	NoProbes bool

	ConfiguredIDType  string
	ConfiguredLocales []string
	ConfiguredBlocks  map[string][]string
	CustomEndpoints   []string

	PayloadVersion       string
	PayloadVersionSource string
	DBAdapter            string
	DBAdapterSource      string

	// ProjectBlockSlugs are §7.10's `slug:` literals found on the local
	// filesystem, and ProjectBlockSlugFiles the absolute files they came from.
	ProjectBlockSlugs     []string
	ProjectBlockSlugFiles []string
	// ProjectAuthSlugs are auth-collection slug literals from the project's
	// own payload.config.ts, used only to widen Stage -1's candidate set.
	ProjectAuthSlugs []string
	// ProjectRoutes are `routes:` literals, named in the endpoint_not_payload
	// hint when nothing accepted.
	ProjectRoutes []string

	Logger *slog.Logger
}

type Permissions struct {
	Create       bool  `json:"create"`
	Read         bool  `json:"read"`
	Update       bool  `json:"update"`
	Delete       bool  `json:"delete"`
	ReadVersions bool  `json:"read_versions"`
	Unlock       bool  `json:"unlock"`
	FieldLevel   *bool `json:"field_level"`
}

type Preferences struct {
	Collection *string `json:"collection"`
}

type Result struct {
	Manifest *Manifest
	// Shards are keyed by the cache-relative shard path, e.g.
	// "fields/pages.json", so a caller can hand them straight to cache.Set.
	Shards map[string]*Shard

	AuthCollection       string
	AuthCollectionSource string
	// AuthResolved reports that Stage -1 ran and produced a slug worth
	// persisting to auth-resolution.json.
	AuthResolved bool

	APIPath           string
	APIPathSource     string
	GraphQLPath       string
	GraphQLPathSource string

	Warnings []output.Warning
}

type Schema struct {
	// Types are the resolved __type results, keyed by type name.
	Types map[string]*IntroType
	// SlugBySingular maps a GraphQL singular type name back to its slug, so a
	// monomorphic relationship target is reported as a slug, never as a type
	// name an agent cannot pass on the command line.
	SlugBySingular map[string]string
}

type Shard struct {
	Generation string  `json:"generation"`
	Slug       string  `json:"slug"`
	SHA256     string  `json:"sha256"`
	Fields     []Field `json:"fields"`
	// JoinFields lists read-only join fields, which must be requested with
	// joins[field][limit] rather than selected like a normal field.
	JoinFields []string `json:"join_fields"`
	// Blocks maps a blocks field's path to its resolved blockType slugs. It is
	// null — not an empty map — when no source could resolve them, which is
	// the difference between "this project has no blocks" and "PayCLI does not
	// know" (§7.10).
	Blocks       map[string][]string `json:"blocks"`
	BlocksSource string              `json:"blocks_source"`
	// RequiredPaths is the flattened list of paths whose required is true.
	RequiredPaths []string `json:"required_paths"`
}

type Source struct {
	BaseURL              string  `json:"base_url"`
	APIPath              string  `json:"api_path"`
	APIPathSource        string  `json:"api_path_source"`
	GraphQLPath          string  `json:"graphql_path"`
	GraphQLPathSource    string  `json:"graphql_path_source"`
	PoweredBy            string  `json:"powered_by"`
	PayloadVersion       *string `json:"payload_version"`
	PayloadVersionSource string  `json:"payload_version_source"`
	DBAdapter            string  `json:"db_adapter"`
	DBAdapterSource      string  `json:"db_adapter_source"`
}

type Stats struct {
	TotalDocs *int `json:"total_docs"`
	Sampled   bool `json:"sampled"`
}

type TopologyProjection struct {
	Collections map[string][]string `json:"c"`
	Globals     map[string][]string `json:"g"`
	Admin       bool                `json:"admin"`
}

type TypeRef struct {
	Kind   string   `json:"kind"`
	Name   string   `json:"name"`
	OfType *TypeRef `json:"ofType"`
}

type Unreachable struct {
	Slug   string `json:"slug"`
	Kind   string `json:"kind"`
	Reason string `json:"reason"`
	Detail string `json:"detail"`
}

type UnsupportedOperator struct {
	Operator   string `json:"operator"`
	Collection string `json:"collection,omitempty"`
	Reason     string `json:"reason"`
}