SuperFlow 1.0.6

SuperFlow

SuperFlow is a robust .NET library designed to orchestrate bots and automate processes through a flexible FlowEngine and a system of Steps and Actions. SuperFlow empowers developers to create scalable, maintainable, and testable automation workflows with ease.

🌟 Features

• FlowEngine: Manage and execute Steps sequentially or in parallel, handling states and transitions seamlessly.
• Steps: Define discrete units of work (e.g., downloading a captcha, processing data, calling an API) reusable across different flows.
• Actions: Perform generic and reusable operations such as making HTTP requests, sending Telegram messages, resolving captchas, publishing to AWS SNS, and receiving from AWS SQS.
• FlowContext: A shared container that travels through Steps, allowing injection of services like DbContext, HttpClientFactory, configuration parameters, and intermediate data.
• Dependency Injection: Integrates smoothly with IServiceCollection, facilitating service and configuration management.
• Resilience: Incorporates Polly for handling retries, circuit breakers, and other resilience strategies.
• AWS Integration: Seamlessly publish messages to AWS SNS and subscribe to AWS SQS queues for robust messaging capabilities.
• Unit Testing: Designed for testability, enabling easy mocking of HTTP requests and other external dependencies.
• Continuous Integration: Automated builds and deployments using GitHub Actions, ensuring reliable and consistent releases.

📦 Installation

Install SuperFlow via NuGet:

Using .NET CLI

dotnet add package SuperFlow

Using Package Manager

Install-Package SuperFlow

🚀 Quick Start

A simple example to get you started with SuperFlow, including the new AWS SNS and SQS tools:

1. Configure Dependency Injection

using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Configuration; using SuperFlow.Core; using SuperFlow.Core.Default.Tools.CaptchaTool; using SuperFlow.Core.Default.Tools.SNSTool; using SuperFlow.Core.Default.Tools.SQSTool; using SuperFlow.Core.Default.Tools.RequestTool; using SuperFlow.Core.Default.Tools.TelegramTool; using SuperFlow.Core.Tools; using System.Collections.Generic; using System.Net.Http; using System.Threading.Tasks;

public class Program { public static async Task Main() { // 1. Set up the service collection var services = new ServiceCollection();

    // 2. Configure appsettings.json
    var configuration = new ConfigurationBuilder()
        .AddJsonFile("appsettings.json")
        .Build();

    // 3. Add SuperFlow Core and tools to the service container
    services.AddSuperFlowCore(configuration);

    // 4. Register HttpClient
    services.AddHttpClient("GenericClient");

    // 5. Build service provider
    var serviceProvider = services.BuildServiceProvider();

    // 6. Register Actions
    ActionRegistry.RegisterAction(new RequestAction("HttpRequestAction", new RequestActionConfig
    {
        BaseUrl = "https://api.example.com",
        DefaultHeaders = new Dictionary<string, string>
        {
            { "Authorization", "Bearer YOUR_API_KEY" }
        }
    }, serviceProvider.GetRequiredService<IHttpClientFactory>()));

    ActionRegistry.RegisterAction(new TelegramAction("SendTelegramAction", new TelegramConfig
    {
        BotApiKey = "YOUR_TELEGRAM_BOT_API_KEY",
        DefaultChatId = "YOUR_DEFAULT_CHAT_ID"
    }));

    ActionRegistry.RegisterAction(new CaptchaAction("SolveCaptchaAction", new CaptchaActionConfig
    {
        SolveTimeoutSeconds = 70,
        MaxRetries = 3,
        Providers = new List<ICaptchaProvider>
        {
            new TwoCaptchaProvider(new HttpClient(), new[] { "YOUR_2CAPTCHA_API_KEY" }),
            new CapMonsterProvider(new HttpClient(), "YOUR_CAPMONSTER_API_KEY")
            // Add more providers as needed
        }
    }));

    ActionRegistry.RegisterAction(new SNSTool("PublishToSNS", serviceProvider.GetRequiredService<ISNSSender>()));
    ActionRegistry.RegisterAction(new SQSTool("ReceiveFromSQS", serviceProvider.GetRequiredService<ISQSReceiver>()));

    // 7. Create FlowEngine
    var engine = serviceProvider.GetRequiredService<FlowEngine>();

    // 8. Register Steps
    engine.RegisterStep(new StepDownloadCaptcha("DownloadCaptcha"), isInitial: true);
    engine.RegisterStep(new StepSolveCaptcha("SolveCaptcha"));
    engine.RegisterStep(new StepPublishToSNS("PublishToSNS"));
    engine.RegisterStep(new StepReceiveFromSQS("ReceiveFromSQS"));
    engine.RegisterStep(new StepSendTelegramMessage("SendMessage"));

    // 9. Define Transitions
    engine.SetTransition("DownloadCaptcha", "OK", "SolveCaptcha");
    engine.SetTransition("SolveCaptcha", "OK", "PublishToSNS");
    engine.SetTransition("PublishToSNS", "SNS_MESSAGE_PUBLISHED", "ReceiveFromSQS");
    engine.SetTransition("ReceiveFromSQS", "SQS_MESSAGE_RECEIVED", "SendMessage");

    // 10. Create FlowContext and Execute
    var context = new FlowContext { ServiceProvider = serviceProvider };
    await engine.RunAsync(context);

    Console.WriteLine("Flow completed successfully.");
}

}

// Example Step Implementations

public class StepDownloadCaptcha : BaseStep { public StepDownloadCaptcha(string name) : base(name) { }

public override async Task<StepResult> ExecuteAsync(FlowContext context)
{
    // Use RequestAction to download captcha image
    var requestAction = ActionRegistry.GetAction("HttpRequestAction");
    var response = await requestAction.ExecuteAsync(context, new { Method = "GET", Endpoint = "get-captcha.jpg" });

    // Assume response.Body contains the image bytes in Base64
    byte[] captchaImage = Convert.FromBase64String(response.Body);
    context.Data["CaptchaImage"] = captchaImage;

    return new StepResult { IsSuccess = true, ResultCode = "OK" };
}

}

public class StepSolveCaptcha : BaseStep { public StepSolveCaptcha(string name) : base(name) { }

public override async Task<StepResult> ExecuteAsync(FlowContext context)
{
    var captchaAction = ActionRegistry.GetAction("SolveCaptchaAction");
    byte[] captchaImage = context.Data["CaptchaImage"] as byte[] ?? throw new Exception("Captcha image not found.");

    var result = await captchaAction.ExecuteAsync(context, new { ImageData = captchaImage });
    context.Data["CaptchaSolution"] = result.CaptchaText;

    return new StepResult { IsSuccess = true, ResultCode = "OK" };
}

}

public class StepPublishToSNS : BaseStep { public StepPublishToSNS(string name) : base(name) { }

public override async Task<StepResult> ExecuteAsync(FlowContext context)
{
    var snsTool = ActionRegistry.GetAction("PublishToSNS") as IFlowTool;
    if (snsTool == null)
        throw new InvalidOperationException("SNSTool not registered.");

    var parameters = new SNSToolParameters
    {
        Message = $"Captcha solved: {context.Data["CaptchaSolution"]}",
        Subject = "Captcha Solution"
    };

    var result = await snsTool.ExecuteAsync(context, parameters);
    context.Data["SNSResponse"] = (result as SNSToolResult)?.MessageId;

    return new StepResult
    {
        IsSuccess = true,
        ResultCode = "SNS_MESSAGE_PUBLISHED",
        Message = "Message published to SNS successfully.",
        Data = result
    };
}

}

public class StepReceiveFromSQS : BaseStep { public StepReceiveFromSQS(string name) : base(name) { }

public override async Task<StepResult> ExecuteAsync(FlowContext context)
{
    var sqsTool = ActionRegistry.GetAction("ReceiveFromSQS") as IFlowTool;
    if (sqsTool == null)
        throw new InvalidOperationException("SQSTool not registered.");

    var parameters = new SQSToolParameters
    {
        Operation = "receive",
        ReceiveTimeoutSeconds = 10
    };

    var result = await sqsTool.ExecuteAsync(context, parameters);
    context.Data["SQSMessage"] = (result as SQSToolResult)?.Body;

    return new StepResult
    {
        IsSuccess = true,
        ResultCode = "SQS_MESSAGE_RECEIVED",
        Message = "Message received from SQS successfully.",
        Data = result
    };
}

}

public class StepSendTelegramMessage : BaseStep { public StepSendTelegramMessage(string name) : base(name) { }

public override async Task<StepResult> ExecuteAsync(FlowContext context)
{
    var telegramAction = ActionRegistry.GetAction("SendTelegramAction") as IFlowTool;
    if (telegramAction == null)
        throw new InvalidOperationException("TelegramAction not registered.");

    string message = context.Data["SQSMessage"] as string ?? "Default message.";

    var result = await telegramAction.ExecuteAsync(context, new { Message = $"Received message: {message}" });
    context.Data["TelegramResponse"] = result;

    return new StepResult { IsSuccess = true, ResultCode = "OK", Message = "Telegram message sent successfully.", Data = result };
}

}

2. Configure appsettings.json

Ensure your appsettings.json includes the necessary configurations for the tools:

{ "CaptchaTool": { // Configuration settings for CaptchaTool }, "RequestTool": { // Configuration settings for RequestTool }, "TelegramTool": { "BotApiKey": "YOUR_TELEGRAM_BOT_API_KEY", "DefaultChatId": "YOUR_DEFAULT_CHAT_ID" }, "SNSTool": { "TopicName": "your_sns_topic_name" }, "SQSTool": { "QueueName": "your_sqs_queue_name" }, "AWS": { "Region": "us-east-1", "AccessKey": "YOUR_AWS_ACCESS_KEY", "SecretKey": "YOUR_AWS_SECRET_KEY" } // Other configurations as needed }

Important: Never expose your API keys or secret keys in the code or repositories. Use secure methods like environment variables or AWS Secrets Manager to manage sensitive information.

📝 License

Distributed under the MIT License. See LICENSE for more information. 🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

📫 Contact

https://x.com/PaifferDev

Project Link: https://github.com/PaifferDev/SuperFlow

Thank you for using SuperFlow!

If you find this library useful, please give it a ⭐ on GitHub and consider leaving a review on NuGet.