Beefreesdk

Cursor-Regel für die BeeFree-SDK-Integration: Konventionen für Initialisierung, Einbindung und Template-Handling.

Original-Beschreibung der Autoren: Guidelines and best practices for building applications with Beefree SDK, including installation, authentication, configuration, customization, and template management

Die Regel

---
description: "Guidelines and best practices for building applications with [Beefree SDK](https://docs.beefree.io/beefree-sdk), including installation, authentication, configuration, customization, and template management"
globs: **/*.{ts,tsx,js,jsx,html,css}
alwaysApply: false
---
# Beefree SDK Guidelines
Guidelines and best practices for building applications with [Beefree SDK](https://docs.beefree.io/beefree-sdk), including installation, authentication, configuration, customization, and template management.

## Installation Guidelines

### Package Installation
- Install the Beefree SDK package using npm or yarn:
  ```bash
  npm install @beefree.io/sdk
  # or
  yarn add @beefree.io/sdk

Dependencies

• Beefree SDK requires the following core dependencies:

  {
    "dependencies": {
      "@beefree.io/sdk": "^9.0.2-fix-optional-url-config.0",
      "axios": "^1.10.0",
      "express": "^5.1.0",
      "cors": "^2.8.5",
      "dotenv": "^17.2.0"
    }
  }

Environment Setup

• Create a .env file in your project root with your Beefree credentials:

  BEE_CLIENT_ID=your_client_id_here
  BEE_CLIENT_SECRET=your_client_secret_here

Authentication Guidelines

Proxy Server Setup

• ALWAYS use a proxy server for authentication to protect your credentials
• Create a proxy server file (e.g., proxy-server.js) to handle authentication:

  import express from 'express';
  import cors from 'cors';
  import axios from 'axios';
  import dotenv from 'dotenv';
  
  dotenv.config();
  
  const app = express();
  const PORT = 3001;
  
  app.use(cors());
  app.use(express.json());
  
  const BEE_CLIENT_ID = process.env.BEE_CLIENT_ID;
  const BEE_CLIENT_SECRET = process.env.BEE_CLIENT_SECRET;
  
  // V2 Auth Endpoint
  app.post('/proxy/bee-auth', async (req, res) => {
    try {
      const { uid } = req.body;
      
      const response = await axios.post(
        'https://auth.getbee.io/loginV2',
        {
          client_id: BEE_CLIENT_ID,
          client_secret: BEE_CLIENT_SECRET,
          uid: uid || 'demo-user'
        },
        { headers: { 'Content-Type': 'application/json' } }
      );
      
      res.json(response.data);
    } catch (error) {
      console.error('Auth error:', error.message);
      res.status(500).json({ error: 'Failed to authenticate' });
    }
  });
  
  app.listen(PORT, () => {
    console.log(`Proxy server running on http://localhost:${PORT}`);
  });

Authentication Process

• Use the V2 authentication endpoint: https://auth.getbee.io/loginV2
• Pass the ENTIRE API response to the Beefree SDK, not just the token
• Example authentication call:

  const token = await fetch('http://localhost:3001/proxy/bee-auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ uid: 'demo-user' })
  }).then(res => res.json());

Container Setup Guidelines

HTML Container

• Create a dedicated container element for the Beefree SDK:

  <div id="beefree-sdk-container"></div>

CSS Styling

• Style the container to ensure proper display:

  #beefree-sdk-container {
    position: absolute;
    top: 0px;
    bottom: 0px;
    left: 0px;
    right: 0px;
    height: 600px;
    width: 90%;
    margin: 20px auto;
    border: 1px solid #ddd;
    border-radius: 8px;
  }

React Container

• For React applications, the following code snippet shows an example using refs to manage the container:

  const containerRef = useRef<HTMLDivElement>(null);
  
  return (
    <div
      id="beefree-react-demo"
      ref={containerRef}
      style={{
        height: '600px',
        width: '90%',
        margin: '20px auto',
        border: '1px solid #ddd',
        borderRadius: '8px'
      }}
    />
  );

Configuration Guidelines

Required Configuration Parameters

• ALWAYS include the container parameter in your configuration:

  const beeConfig = {
    container: 'beefree-sdk-container', // Required
    language: 'en-US'
  };

Optional Configuration Parameters

• Customize your SDK with optional parameters:

  const beeConfig = {
    container: 'beefree-sdk-container', // Required
    language: 'en-US',
    specialLinks: [
      {
        type: "unsubscribe",
        label: "Unsubscribe",
        link: "http://[unsubscribe]/",
      },
      {
        type: "subscribe",
        label: "Subscribe",
        link: "http://[subscribe]/",
      },
    ],
    mergeTags: [
      {
        name: "First Name",
        value: "[first_name]",
      },
      {
        name: "Last Name",
        value: "[last_name]",
      },
      {
        name: "Email",
        value: "[email]",
      },
    ]
  };

Callback Functions

• Implement essential callback functions for proper functionality:

  const beeConfig = {
    container: 'beefree-sdk-container',
    onSave: function (jsonFile, htmlFile) {
      console.log("Template saved:", jsonFile);
      // Implement custom save logic here
    },
    onAutoSave: function (jsonFile) {
      console.log("Auto-saving template...");
      localStorage.setItem("email.autosave", jsonFile);
    },
    onSend: function (htmlFile) {
      console.log("Email ready to send:", htmlFile);
      // Implement custom send logic here
    },
    onError: function (errorMessage) {
      console.error("Beefree SDK error:", errorMessage);
      // Handle errors appropriately
    }
  };

SDK Initialization Guidelines

Basic Initialization

• Initialize the Beefree SDK with proper error handling:

  async function initializeBeefree(authResponse) {
    try {
      const bee = new BeefreeSDK(authResponse);
      bee.start(beeConfig, {});
      console.log('Beefree SDK initialized successfully');
    } catch (error) {
      console.error('Failed to initialize Beefree SDK:', error);
    }
  }

React Integration

• Fo … (hier gekürzt — Kopieren/Download liefert die vollständige Regel)

## So nutzt du sie

Die Regel kopieren (Button oben) oder als Datei herunterladen und im Projekt unter `.cursor/rules/` ablegen — Cursor lädt sie beim nächsten Start automatisch. Ältere Cursor-Versionen lesen alternativ eine einzelne `.cursorrules`-Datei im Projektstamm; dort einfach den Regel-Text ohne den Kopfblock zwischen den `---`-Zeilen einfügen.

Der Regel-Text ist englisch — Cursor versteht ihn unabhängig von der Sprache, in der Sie mit dem Editor chatten.


## Im Detail

Cursor-Regel für die Integration des BeeFree SDK, mit dem sich ein Drag-and-Drop-E-Mail- bzw. Content-Editor in eigene Web-Apps einbetten lässt. Sie gibt Cursor Konventionen zur SDK-Initialisierung, zum Einbinden per iframe/JS-Bridge und zum Umgang mit Templates und Callbacks vor. Sinnvoll für Entwickler, die BeeFree in ein bestehendes Produkt wie ein Newsletter-Tool oder CMS integrieren und dabei nicht jedes Mal die SDK-Doku nachschlagen wollen. Da es eine sehr spezifische Drittanbieter-Integration betrifft, lohnt sich die Regel nur, wenn BeeFree tatsächlich im Projekt eingesetzt wird.

## Praxis-Tipp

Prompt z. B. „Binde das BeeFree SDK in eine React-Komponente ein und lade ein gespeichertes Template per API“ — Cursor kennt dann Initialisierungsreihenfolge und Callback-Namen.

## Lizenz & Quelle

- **Lizenz:** CC0 1.0
- **Quelle:** [PatrickJS/awesome-cursorrules (GitHub)](https://github.com/PatrickJS/awesome-cursorrules)

Lade …