Merge pull request #93 from epilot-dev/feat/add-external-catalog-app-docs-beta

feat: Add External Catalog Product documentation and integration details

Author: alexmarqs

apps/about-apps/components/external-product-catalog.md

@@ -0,0 +1,120 @@
+---
+title: External Catalog Product
+hide_title: true
+sidebar_position: 7
+---
+
+<h1 align="center">External Catalog Product</h1>
+
+<p align="center">Integrate external product catalogs with epilot</p>
+
+> If you do not have access to this integration in your organization, please contact our support team for assistance.
+
+## Configuration
+
+To add a **External Catalog Product** component, you need to create a new App or update an existing App.
+
+<img src="/img/apps/external-product-catalog/external-catalog-option-menu.png" width="400" />
+
+All development is performed using the built-in configuration editor accessible from the component editor.
+
+The editor provides you with autocomplete and validation of the configuration. That way you can start with the example provided in this documentation and fine-tune your external catalog product without ever leaving the editor.
+
+<img src="/img/apps/external-product-catalog/component-editor.png" width="700" />
+
+## Hooks
+
+Hooks allow changing or adding functionality to external catalog products.
+They typically rely on your API for the execution of any necessary logic and expect a certain response.
+
+### Supported Hooks / Catalog Types
+
+The interface supports two types of data exchange, depending on the block being used in the journey:
+- **Products**: Returns an array of products.
+- **Product Recommendations**: Returns a source product and a list of offer products.
+
+### Template Variables
+
+You can use template variables throughout your configuration to dynamically inject values from various sources. Template variables use the `{{Variable.path}}` syntax.
+
+#### Available Variables
+
+- **`Options.*`**: Access values from the app options configured during installation
+  - Example: `{{Options.api_url}}`, `{{Options.api_key}}`
+
+- **`AuthResponse.*`**: Access data from the authentication response data
+  - Example: `{{AuthResponse.access_token}}`
+  - Use this to extract tokens or other authentication data returned by your auth endpoint
+
+- **`Context.*`**: Access properties from the current context (e.g. Journey Context)
+  - Example: `{{Context.journey_id}}`, `{{Context.journey_url.params.xxx}}`
+
+### Example
+
+Below is an example of a configuration for the `products` hook, assuming a typical OAuth2 authentication flow, where the client credentials are stored in the app options.
+
+```json
+{
+  "hooks": [
+    {
+      "id": "prod-catalog",
+      "type": "products",
+      "name": {
+        "en": "Prod Products",
+        "de": "Prod Produkte"
+      },
+      "auth": {
+        "url": "{{Options.oauth_api_url}}/auth/token",
+        "method": "POST",
+        "headers": {
+          "Authorization": "Basic {{Options.oauth_client_id | append: \":\" | append: Options.oauth_client_secret | base64_encode}}",
+          "Content-Type": "application/x-www-form-urlencoded"
+        },
+        "body": {
+          "grant_type": "client_credentials",
+          "scope": "{{Options.oauth_scope}}"
+        }
+      },
+      "call": {
+        "url": "{{Options.base_api_url}}/products",
+        "method": "POST",
+        "headers": {
+          "Authorization": "Bearer {{AuthResponse.access_token}}"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Security Considerations
+
+- **Credentials Storage**: Store sensitive credentials (like API keys) as app options rather than hardcoding them
+- **Token Expiration**: Ensure your authentication tokens have appropriate expiration times
+- **HTTPS**: Always use HTTPS URLs for authentication endpoints and redirects
+- **Access Control**: Implement proper authorization checks on your authentication endpoint to ensure only authorized clients can obtain tokens
+
+## Usage in Journeys
+
+After your External Catalog Product component is configured and the app is installed, it can be used within epilot's Journeys. Currently we support seamless integration of the external catalog product into the journey via Product Blocks and Product Recommendations Blocks (beta).
+
+When a journey creator adds a **Product Block** or **Product Recommendations Block** in a journey, they can select the integration as the source for products. Only hooks that are supported for the selected block type will be available (e.g. only `products` hook for Product Block, only `productRecommendations` hook for Product Recommendations Block).
+
+<img src="/img/apps/external-product-catalog/journey-product-block-config.png" width="500" />
+
+This allows the journey to dynamically fetch products and pricing from your external catalog in journeys.
+
+## Integration Interface
+
+To ensure seamless communication between epilot and your external catalog, your integration must respect the **External Catalog Integration Interface**.
+
+### Specification
+
+The integration works as a request to your service endpoint with the following request and response:
+
+1.  **Request**: A payload containing the `context` of the journey or a custom one defined by you/epilot.
+2.  **Response**: A list of products or product recommendations in a specific format.
+
+For detailed information on the request and response schemas, please refer to the [External Catalog Integration Interface documentation](https://docs.api.epilot.io/pricing-api-external-catalog).
+
+

apps/about-apps/components/overview.md

@@ -43,6 +43,14 @@ Portal Extensions enhance epilot's customer and installer portals with new secti
 Use cases: Custom dashboard widgets, specialized tools, data visualizations
 ```
 
+### [External Catalog Product](/apps/about-apps/components/external-product-catalog)
+
+External Catalog Product components integrate third-party product catalogs into epilot. They enable Product Blocks to fetch and display products and pricing from external systems, allowing customers to browse and select items from external catalogs directly within their journey experience.
+
+```
+Use cases: Custom product catalogs, journey products, journey product recommendations
+```
+
 ## On the Horizon
 
 The epilot platform continues to evolve, with new component types planned for future releases:
@@ -92,6 +100,17 @@ Ready to create your own component? Each component type has specific requirement
       </div>
     </div>
   </div>
+  <div className="row" style={{marginTop: '1.5rem'}}>
+    <div className="col col--6">
+      <div className="card" style={{height: '100%'}}>
+        <div className="card__body">
+          <h3>External Product Catalog</h3>
+          <p>Integrate third-party product catalogs into epilot</p>
+          <a href="/apps/about-apps/components/external-product-catalog" className="button button--primary button--block">Start Building</a>
+        </div>
+      </div>
+    </div>
+  </div>
 </div>
 
 By understanding how components work and which types are available, you can create powerful extensions that enhance the epilot platform while maintaining a seamless user experience.

apps/overview.md

@@ -36,6 +36,8 @@ See the [App Components](/apps/about-apps/components/overview) section for detai
 
 **Portal Extensions**: Components that enhance epilot's customer and installer portals with additional functionality and visualizations.
 
+**External Catalog Product**: Components that integrate third-party product catalogs into epilot.
+
 ### Upcoming Component Types (Roadmap)
 
 1. **Custom Automation Tasks**: Define custom automation tasks that can be triggered within epilot's automation workflows.