"""
Read-only access to the published content of iammatthias.com. Public and unauthenticated. Every list is a Relay connection; every document carries a cid you can cache against. Cost model: each connection returns at most 100 items (`first` is clamped). Field resolution is O(1) except `Document.body`, which resolves image embeds per document — request it only for documents you intend to read. Rate limits are Cloudflare's edge defaults, advertised on REST responses via the RateLimit header; there is no per-client quota or API key.
"""
schema {
  query: Query
}

type Query {
  """Keyword search across titles, tags, and bodies, ranked by relevance."""
  search(
    """Search terms."""
    query: String!

    """Items to return (default 20, max 100)."""
    first: Int = 20

    """Opaque cursor from a previous pageInfo.endCursor."""
    after: String
  ): DocumentConnection!

  """All published documents, newest first."""
  documents(
    """Restrict to one publication."""
    section: SectionSlug

    """Restrict to one tag."""
    tag: String

    """Items to return (default 20, max 100)."""
    first: Int = 20

    """Opaque cursor from a previous pageInfo.endCursor."""
    after: String
  ): DocumentConnection!

  """One document by path or slug."""
  document(
    """Path or slug, e.g. 'posts/1779066375000-farfield'."""
    path: String!
  ): DocumentResult!

  """Every publication with its entry count."""
  sections: [Section!]!
}

type DocumentConnection {
  edges: [DocumentEdge!]!

  """Shortcut past edges when you don't need cursors."""
  nodes: [Document!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type DocumentEdge {
  cursor: String!
  node: Document!

  """Search score; null outside search results."""
  relevance: Int
}

"""
One published piece: an essay, photo series, or recipe. Identified by its content hash (cid), which changes only when the content does.
"""
type Document {
  """CIDv1 content hash. Stable for identical content — cache against this."""
  cid: String!
  slug: String!

  """Former alias for `cid`."""
  id: String! @deprecated(reason: "Renamed to `cid` to match the rest of the API. Retained until 2027-01-01; use `cid`.")
  title: String!
  section: String!
  excerpt: String!
  tags: [String!]!
  publishedAt: String!
  updatedAt: String!

  """Canonical HTML URL."""
  url: String!

  """Markdown twin of the canonical URL."""
  markdownUrl: String!

  """
  Full markdown source with image embeds resolved to public URLs. Costs one extra resolution per document — request it only for documents you intend to read.
  """
  body: String
}

"""Relay-style pagination state."""
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

"""A publication on the site."""
enum SectionSlug {
  art
  posts
  recipes
  melange
  open_source
}

"""Either the document, or a typed error explaining why not."""
union DocumentResult = Document | QueryError

"""A request that failed on its own terms, not in transport."""
type QueryError {
  """Machine-readable code, e.g. NOT_FOUND, INVALID_ARGUMENT."""
  code: String!
  message: String!

  """How to change the request and retry."""
  resolution: String
}

"""A publication: a group of documents sharing a subject."""
type Section {
  slug: String!
  name: String!
  description: String

  """Number of published documents in this section."""
  entryCount: Int!
  url: String!

  """Markdown index of this section."""
  markdownIndexUrl: String!
}