[Feature] Zendesk Help Center Integration for Articles

[michnowak]

Is your feature request related to a problem? Please describe.

Users need the ability to integrate their knowledge base content from Zendesk Help Center into the O2S application. Currently, there is no native integration to fetch, display, and search articles from Zendesk, making it difficult for applications that rely on Zendesk as their primary knowledge management system.

Describe the solution you'd like

A complete integration with Zendesk Help Center API that implements the framework's Articles.Service interface and provides the following capabilities:

Core Functionality

• Article Management

  • View individual articles with full content, metadata, and author information
  • List articles with filtering by category, pagination support
  • Full-text search across articles with category filters
  • Multi-language support (en/de/pl with automatic locale mapping)

• Category Management

  • View individual categories with localized content
  • List all available categories
  • Category-based article filtering

• Data Normalization

  • Automatic conversion of Zendesk data structures to standard article model
  • Extract and process article sections from HTML body
  • Handle author information with avatars
  • Process attachments for featured images and thumbnails
  • Generate proper slugs with category paths

Technical Requirements

• Implement all ArticleService methods:

  • getArticle(slug, locale) - retrieve single article
  • getArticleList(filters) - list articles with pagination
  • getCategory(id, locale) - retrieve category details
  • getCategoryList(locale) - list all categories
  • searchArticles(query, filters) - full-text search

• Locale Mapping

  • en → en-us
  • de → de-de
  • pl → pl

• API Client Generation

  • Automated TypeScript type generation from Zendesk OpenAPI spec
  • Use @hey-api/openapi-ts for code generation
  • Automatic updates during package preparation

• Authentication

  • Support Base64-encoded token authentication
  • Configure via environment variables:
    • ZENDESK_API_URL - Zendesk API endpoint
    • ZENDESK_API_TOKEN - Base64-encoded credentials

Field Mapping

Articles

• id, name, description from Zendesk article
• createdAt, updatedAt from timestamps
• sku, variantId from article metadata
• category from article section → category resolution
• images and thumbnail from attachments
• author with avatar from Zendesk user API
• sections parsed from HTML body
• lead extracted from first 300 characters
• tags from label_names
• slug generated as {category-id}-{category-name}/{article-id}-{article-title}

Categories

• id, title, description from Zendesk category
• slug as {category-id}-{category-name}
• createdAt, updatedAt from timestamps

Installation & Configuration

1. Install package: npm install @o2s/integrations.zendesk --workspace=@o2s/configs.integrations
2. Configure in packages/configs/integrations/src/models/articles.ts
3. Set environment variables in API Harmonization server
4. Configure CMS page mappings for categories

Additional context (if applicable)

• Documentation: /apps/docs/docs/integrations/articles/zendesk/
• Integration follows the same patterns as Medusa integration
• Supports Zendesk Help Center API v2
• Includes comprehensive documentation: overview, setup guide, features, and usage examples
• Compatible with O2S frontend SDK
• Handles error cases gracefully (404s, missing data)

---

This repo is using Opire - what does it mean? 👇

💵 Everyone can add rewards for this issue commenting /reward 100 (replace 100 with the amount).
🕵️‍♂️ If someone starts working on this issue to earn the rewards, they can comment /try to let everyone know!
🙌 And when they open the PR, they can comment /claim #663 either in the PR description or in a PR's comment.

🪙 Also, everyone can tip any user commenting /tip 20 @michnowak (replace 20 with the amount, and @michnowak with the user to tip).

📖 If you want to learn more, check out our documentation.

[marcinkrasowski]

Implemented with #623