Tags API

// Basic list (all tags)
const { data: tags, meta } = await client.tags.list()
console.log(`Total tags: ${meta.total}`)

tags.forEach(tag => {
  console.log(`- ${tag.name}: ${tag.articleCount} articles`)

  if (tag.color) console.log(` Color: ${tag.color}`)
  if (tag.icon) console.log(` Icon: ${tag.icon}`)
})

// With sorting and limit
const { data: topTags } = await client.tags.list({
  sort: 'articleCount',
  order: 'desc',
  limit: 10
})

const { data: tag } = await client.tags.get('JavaScript')

console.log(`Tag: ${tag.name}`)
console.log(`Articles: ${tag.articleCount}`)
console.log(`Color: ${tag.color}`)

// Tags with spaces are automatically URL-encoded
const { data: mlTag } = await client.tags.get('Machine Learning')

const tagNames = await client.tags.names()

console.log('Available tags:', tagNames.join(', '))
// Output: "JavaScript, TypeScript, Tutorial, Advanced"

// Use for dropdowns or autocomplete
const tagOptions = tagNames.map(name => ({
  label: name,
  value: name
}))

// Get top 5 most used tags
const topTags = await client.tags.popular(5)

topTags.forEach((tag, i) => {
  console.log(`${i + 1}. ${tag.name} (${tag.articleCount} articles)`)
})

// Get all tags sorted by popularity
const allPopularTags = await client.tags.popular()

// Get all tags first
const { data: tags } = await client.tags.list()

// Filter articles by specific tag
const { data: jsArticles } = await client.articles.list({
  tags: ['JavaScript']
})

// Filter by multiple tags (OR logic)
const { data: webArticles } = await client.articles.list({
  tags: ['JavaScript', 'TypeScript', 'HTML']
})

// Articles that are BOTH tutorials AND about JavaScript
const { data: jsTutorials } = await client.articles.list({
  tagsAll: ['JavaScript', 'Tutorial']
})

// Articles without Advanced or Deprecated tags
const { data: beginnerArticles } = await client.articles.list({
  excludeTags: ['Advanced', 'Deprecated']
})

// Complex filter: JavaScript OR TypeScript tutorials that are NOT advanced
const { data: beginnerWebTutorials } = await client.articles.list({
  tags: ['JavaScript', 'TypeScript'],       // OR: at least one of these
  tagsAll: ['Tutorial'],                    // AND: must have this tag
  excludeTags: ['Advanced'],                // NOT: must not have this tag
  published: true
})

// Example: Get the most popular tags and articles for each
const popularTags = await client.tags.popular(3)

for (const tag of popularTags) {
  console.log(`\nTag: ${tag.name} (${tag.articleCount} articles)`)

  const { data: articles } = await client.articles.list({
    tags: [tag.name],
    limit: 5
  })

  articles.forEach(article => {
    console.log(`  - ${article.title}`)
  })
}

import { SimplistClient } from "@simplist/sdk"

const client = new SimplistClient({ apiKey: process.env.SIMPLIST_API_KEY })

export async function TagCloud() {
  const { data: tags } = await client.tags.list()

  return (
    <div className="flex flex-wrap gap-2">
      {tags.map(tag => (
        <a
          key={tag.id}
          href={`/tags/${tag.name}`}
          className="px-3 py-1 rounded-full"
          style={{
            backgroundColor: tag.color || '#gray',
            opacity: 0.7 + (tag.articleCount / 20) * 0.3
          }}
        >
          {tag.name} ({tag.articleCount})
        </a>
      ))}
    </div>
  )
}

export async function PopularTags() {
  const popularTags = await client.tags.popular(5)

  return (
    <aside>
      <h3>Popular Tags</h3>
      <ul>
        {popularTags.map(tag => (
          <li key={tag.id}>
            <a href={`/tags/${tag.name}`}>
              {tag.icon && <Icon name={tag.icon} />}
              {tag.name}
              <span>({tag.articleCount})</span>
            </a>
          </li>
        ))}
      </ul>
    </aside>
  )
}

type TagPageProps = { params: Promise<{ tag: string }> }

export default async function TagPage({ params }: TagPageProps) {
  const { tag } = await params

  const { data: tagData } = await client.tags.get(tag)

  const { data: articles } = await client.articles.list({
    tags: [tagData.name],
    published: true,
  })

  return (
    <div>
      <h1 className="flex items-center gap-2">
        {tagData.icon && <Icon name={tagData.icon} />}
        {tagData.name}
        <span>({tagData.articleCount} articles)</span>
      </h1>

      <ArticleList articles={articles} />
    </div>
  )
}

try {
  const { data: tag } = await client.tags.get('NonExistentTag')
} catch (error) {
  if (error.statusCode === 404) {
    console.error('Tag not found')
  } else {
    console.error('Failed to fetch tag:', error.message)
  }
}