Falkor Plugin SDK

The Falkor Plugin SDK is a TypeScript toolkit for building and managing plugins within the Falkor ecosystem (Falkor GitHub). It uses Elysia as the web framework and is optimized for the Bun runtime.

🚀 Key Features

• Streamlined Plugin API – Build plugins easily with a clean and intuitive interface for the Falkor ecosystem.
• Built-in Handlers – Includes default setup for search and return routes.
• TypeScript Support – Full typings and type safety throughout the SDK.
• CORS Integration – Out-of-the-box support via @elysiajs/cors.
• Debug Logging – Optional debug mode with color-coded console output for easier development.

📦 Installation

Install via your favorite package manager:

npm install @team-falkor/plugin-sdk

yarn add @team-falkor/plugin-sdk

pnpm add @team-falkor/plugin-sdk

bun add @team-falkor/plugin-sdk

⚡ Quick Start

Here's an example of how to create a plugin for Falkor using the SDK:

import { createPlugin } from "falkor-plugin-sdk";

createPlugin({
  setup: {
    id: "my.awesome.plugin",
    version: "1.0.0",
    multiple_choice: false,
    name: "my-plugin",
    description: "My awesome Falkor plugin",
    logo: "https://yourdomain.com/logo.png",
    banner: "https://yourdomain.com/banner.png", // Optional
    api_url: "htpps://yourdomain.com",
    setup_url: `/setup.json?search=["config-option-1", "config-option-2"]`, // used for auto updating the plugin
  },
  port: 3000,
  handleSearch: async (query) => {
    // Your search logic here
    return { results: [{}] };
  },
  handleReturn: async (data) => {
    // Handle return data here
    // You have to return an array of links but you can send as many links as you want
    return ["link1", "link2"];
  },
  options: {
    debug: true, // Enable debug mode for verbose logs
  },
});

📚 API Reference

createPlugin(options)

Creates and starts a new plugin server for Falkor.

Parameters

• setup (object) – Plugin metadata and configuration:

  • id: Unique identifier for the plugin.
  • version: Version number for compatibility checks.
  • multiple_choice: If true, the plugin requires additional requests to fetch sources.
  • name: Display name of the plugin.
  • description: Short description of the plugin functionality.
  • logo: URL to the plugin's logo (square image).
  • banner: URL to the plugin's banner (optional).
  • api_url: Optional base URL for your plugin API.
  • author: Optional information about the plugin author.
  • setup_path: Path to access the setup data, default is /setup.json.

• port (number) – The port on which the plugin server will run.

• handleSearch (function) – Async function to handle search requests.

• handleReturn (function) – Async function to handle return data.

• options (object) – Additional configuration:

  • debug (boolean): Enable debug mode for detailed logging.

🛠 Development

To run the development server with hot reload, use:

bun run dev

Ensure you have bun installed globally.

🤝 Contributing

We welcome contributions! If you have suggestions or improvements, feel free to open issues or submit pull requests.

📄 License

This project is licensed under the MIT License.