CMSProvider

This is an abstract class that defines the contract for all server-side CMS providers. Its primary role is to fetch data from a specific CMS and transform it into the standardized format that Archibald expects.

Methods to Implement

getPage

This method should handle calls to your CMS API to fetch page data. It must return a promise that resolves to a DefaultResponse<Page>.

• Signature: getPage(options: RequestOptions): Promise<DefaultResponse<Page>>

getPreviewContext

This method should handle calls to your CMS API to fetch preview context data.

• Signature: getPreviewContext(options: RequestOptions): Promise<DefaultResponse<Preview>>

---

Deep Dive

Description: The CMSProvider is the heart of a CMS integration. It's where the actual communication with the third-party CMS happens. It isolates all CMS-specific logic, such as authentication, API calls, and data transformation, from the rest of the Archibald application.

• How To: Create a class that extends CMSProvider and implement the getPage method. Inside this method, use fetch or a dedicated SDK to get data from your CMS, then map the response to the Page interface defined by Archibald.

  // Correct: Implementing a simple provider.
  import { CMSProvider, Page, DefaultResponse } from '@archibald/cms';
  
  export class CustomCMSProvider extends CMSProvider {
      constructor(private config: { apiUrl: string }) { super(); }
  
      public async getPage(options: { path: string }): Promise<DefaultResponse<Page | null>> {
          const response = await fetch(`${this.config.apiUrl}/pages?path=${options.path}`);
          const rawData = await response.json();
          
          // It's a best practice to use a separate mapper for complex transformations.
          const transformedData = this.mapToArchibaldPage(rawData);
  
          return { data: transformedData, error: null };
      }
  
      private mapToArchibaldPage(data: any): Page {
          // ... transformation logic
          return { /* ... mapped data ... */ };
      }
  }

• Best Practice: Never let raw, untransformed data from the CMS leak out of the provider. The provider's core responsibility is to act as an anti-corruption layer, ensuring that the rest of the application only ever deals with the standardized Archibald data model (Page, Component, Slot, etc.). This makes your application resilient to changes in the CMS API and allows you to swap out CMS providers with minimal effort.

  // Avoid: Returning raw data from the provider.
  public async getPage(options: { path: string }): Promise<any> {
      const response = await fetch(`${this.config.apiUrl}/pages?path=${options.path}`);
      // Don't just return the raw JSON. This creates a leaky abstraction.
      return response.json(); 
  }