Plugin Development

Invenicum’s plugin system allows you to extend the application’s functionality by creating custom UI components and integrations. Plugins are built using the STAC framework and can interact with Invenicum’s core features through a comprehensive SDK.

Plugin Architecture Overview

Plugins in Invenicum consist of:

STAC UI Definition: Declarative UI components defined in JSON
Plugin Manifest: Metadata about your plugin (name, version, author, etc.)
SDK Actions: JavaScript-like calls to Invenicum’s native functionality
UI Slots: Predefined locations where plugins can render

How Plugins Work

Plugin UI is defined using STAC (Simple Template for App Components)
Plugins are loaded dynamically from GitHub or local storage
The InvenicumSdkParser handles SDK function calls from plugins
Plugins render in designated UI slots throughout the app

Getting Started

Set Up Your Development Environment

You’ll need:

A GitHub account (for publishing)
A text editor or IDE
Basic knowledge of JSON and Flutter concepts
A local Invenicum instance for testing

Understand the STAC Framework

STAC allows you to build UIs declaratively using JSON. Here’s a simple example:

{
  "type": "container",
  "child": {
    "type": "text",
    "data": "Hello from my plugin!"
  }
}

Learn more about STAC at pub.dev/packages/stac.

Create Your Plugin Structure

A plugin consists of a single JSON file with this structure:

{
  "id": "my-custom-plugin",
  "name": "My Custom Plugin",
  "version": "1.0.0",
  "author": "your-github-username",
  "description": "A brief description of what this plugin does",
  "slot": "dashboard_top",
  "ui": {
    // STAC UI definition here
  }
}

Plugin Manifest

Every plugin requires these fields in its manifest:

Field	Type	Required	Description
`id`	String	Yes	Unique identifier for your plugin
`name`	String	Yes	Display name
`version`	String	Yes	Semantic version (e.g., “1.0.0”)
`author`	String	Yes	Your GitHub username
`description`	String	Yes	Brief description (max 200 chars)
`slot`	String	Yes	Where the plugin renders (see UI Slots)
`ui`	Object	Yes	STAC UI definition
`authorAvatar`	String	No	URL to author avatar image
`isPublic`	Boolean	No	Whether plugin is publicly available (default: false)

Example Manifest

{
  "id": "dashboard-stats",
  "name": "Enhanced Dashboard Stats",
  "version": "1.2.0",
  "author": "yourusername",
  "description": "Display advanced statistics on your dashboard with charts and insights",
  "slot": "dashboard_top",
  "authorAvatar": "https://github.com/yourusername.png",
  "isPublic": true,
  "ui": {
    "type": "container",
    "child": {
      "type": "text",
      "data": "Stats go here"
    }
  }
}

UI Slots

Plugins can render in various locations throughout the Invenicum app:

Slot Name	Location	Use Case
`dashboard_top`	Top of dashboard	Summary widgets, important alerts
`dashboard_bottom`	Bottom of dashboard	Charts, recent activity
`asset_detail_top`	Top of asset detail page	Custom asset actions
`asset_detail_bottom`	Bottom of asset detail page	Additional asset information
`sidebar`	App sidebar	Quick actions, navigation

Specify the slot in your manifest:

{
  "slot": "dashboard_top",
  // ... rest of manifest
}

Invenicum SDK Functions

The SDK allows plugins to interact with Invenicum’s core functionality. SDK calls are made through the InvenicumSdkParser (see lib/core/utils/sdk_plugin_parser.dart:21).

Available SDK Methods

`getUserName()`

Get the current user’s name. STAC Action Example:

{
  "type": "action",
  "action": {
    "type": "invenicum_sdk",
    "method": "getUserName",
    "params": {}
  }
}

Implementation (from sdk_plugin_parser.dart:42):

case 'getUserName':
  ToastService.info("Usuario actual: ${userName ?? 'Invitado'}");
  break;

`showAlert(message)`

Display a success toast message to the user. Parameters:

message (String): The message to display

STAC Action Example:

{
  "type": "action",
  "action": {
    "type": "invenicum_sdk",
    "method": "showAlert",
    "params": {
      "message": "Plugin action completed successfully!"
    }
  }
}

Implementation (from sdk_plugin_parser.dart:47):

case 'showAlert':
  ToastService.success(model.params['message'] ?? 'Acción ejecutada');
  break;

`navigate(path)`

Navigate to a specific route in the app. Parameters:

path (String): The route path to navigate to

STAC Action Example:

{
  "type": "action",
  "action": {
    "type": "invenicum_sdk",
    "method": "navigate",
    "params": {
      "path": "/assets/create"
    }
  }
}

Implementation (from sdk_plugin_parser.dart:51):

case 'navigate':
  final path = model.params['path'];
  if (path != null) {
    debugPrint("Navegando a: $path");
    // Navigation implementation
  }
  break;

`logout()`

Log out the current user. STAC Action Example:

{
  "type": "action",
  "action": {
    "type": "invenicum_sdk",
    "method": "logout",
    "params": {}
  }
}

Implementation (from sdk_plugin_parser.dart:59):

case 'logout':
  context.read<AuthProvider>().logout();
  ToastService.info("Sesión cerrada");
  break;

Using SDK Functions in Your Plugin

Here’s a complete example of a button that calls an SDK function:

{
  "type": "elevatedButton",
  "data": "Click Me",
  "onPressed": {
    "type": "invenicum_sdk",
    "method": "showAlert",
    "params": {
      "message": "Hello from my plugin!"
    }
  }
}

Building Your First Plugin

Let’s create a simple “Quick Actions” plugin for the dashboard.

Create the Plugin File

Create a new file called quick-actions.json:

{
  "id": "quick-actions",
  "name": "Quick Actions",
  "version": "1.0.0",
  "author": "yourusername",
  "description": "Quick action buttons for common tasks",
  "slot": "dashboard_top",
  "ui": {}
}

Design the UI

Add STAC UI definition:

"ui": {
  "type": "card",
  "child": {
    "type": "column",
    "children": [
      {
        "type": "text",
        "data": "Quick Actions",
        "style": {
          "fontSize": 18,
          "fontWeight": "bold"
        }
      },
      {
        "type": "row",
        "mainAxisAlignment": "spaceEvenly",
        "children": [
          {
            "type": "elevatedButton",
            "data": "Add Asset",
            "onPressed": {
              "type": "invenicum_sdk",
              "method": "navigate",
              "params": {
                "path": "/assets/create"
              }
            }
          },
          {
            "type": "elevatedButton",
            "data": "View Loans",
            "onPressed": {
              "type": "invenicum_sdk",
              "method": "navigate",
              "params": {
                "path": "/loans"
              }
            }
          }
        ]
      }
    ]
  }
}

Test Locally

To test your plugin locally:

Start your Invenicum instance
Go to Settings > Plugins > Developer Mode
Upload your quick-actions.json file
The plugin will appear in the dashboard

Make adjustments as needed and reload.

Publish to GitHub

Once tested:

Create a new GitHub repository for your plugin
Upload your quick-actions.json file
Create a release with a version tag (e.g., v1.0.0)
Copy the raw URL to your plugin file
Submit to the Invenicum marketplace

Advanced Plugin Examples

Interactive Counter Plugin

A plugin with state management:

{
  "id": "counter-widget",
  "name": "Counter Widget",
  "version": "1.0.0",
  "author": "yourusername",
  "description": "A simple counter with increment/decrement buttons",
  "slot": "dashboard_top",
  "ui": {
    "type": "card",
    "child": {
      "type": "column",
      "mainAxisAlignment": "center",
      "children": [
        {
          "type": "text",
          "data": "Counter: 0",
          "id": "counterText"
        },
        {
          "type": "row",
          "mainAxisAlignment": "center",
          "children": [
            {
              "type": "iconButton",
              "icon": "remove",
              "onPressed": {
                "type": "invenicum_sdk",
                "method": "showAlert",
                "params": {
                  "message": "Decrement clicked"
                }
              }
            },
            {
              "type": "iconButton",
              "icon": "add",
              "onPressed": {
                "type": "invenicum_sdk",
                "method": "showAlert",
                "params": {
                  "message": "Increment clicked"
                }
              }
            }
          ]
        }
      ]
    }
  }
}

User Greeting Plugin

A plugin that displays user information:

{
  "id": "user-greeting",
  "name": "User Greeting",
  "version": "1.0.0",
  "author": "yourusername",
  "description": "Personalized greeting for the logged-in user",
  "slot": "dashboard_top",
  "ui": {
    "type": "card",
    "child": {
      "type": "column",
      "children": [
        {
          "type": "text",
          "data": "Welcome back!",
          "style": {
            "fontSize": 24,
            "fontWeight": "bold"
          }
        },
        {
          "type": "elevatedButton",
          "data": "Show My Username",
          "onPressed": {
            "type": "invenicum_sdk",
            "method": "getUserName",
            "params": {}
          }
        }
      ]
    }
  }
}

Plugin Service API

The PluginService (from lib/data/services/plugin_service.dart:22) provides methods for plugin management:

Key Methods

Install a Plugin

Future<void> installPlugin(Map<String, dynamic> pluginData) async {
  await _dio.post('/plugins/install', data: pluginData);
}

Toggle Plugin Active State

Future<void> toggleUserPlugin(String pluginId, bool isActive) async {
  await _dio.put(
    '/plugins/user/toggle',
    data: {'pluginId': pluginId, 'isActive': isActive},
  );
}

Get Installed Plugins

Future<List<Map<String, dynamic>>> getMyPlugins() async {
  final response = await _dio.get('/plugins/installed');
  return List<Map<String, dynamic>>.from(response.data);
}

Get Community Plugins

Future<List<Map<String, dynamic>>> getCommunityPlugins() async {
  final response = await _dio.get('/plugins/community');
  return List<Map<String, dynamic>>.from(response.data);
}

Plugin Model Structure

Plugins are represented by the StorePlugin model (from lib/data/models/store_plugin_model.dart:1):

class StorePlugin {
  final String id;
  final String name;
  final String author;
  final String version;
  final String description;
  final String slot;
  final Map<String, dynamic>? ui;
  final String? authorAvatar;
  final int downloadCount;
  final bool hasUpdate;
  final String latestVersion;
  final bool isMine;
  final bool isActive;
  final bool isPublic;
}

Testing Your Plugin

Local Testing

Developer Mode: Enable developer mode in plugin settings
Upload: Upload your plugin JSON file
Verify: Check that it appears in the correct slot
Test Actions: Click buttons and verify SDK calls work
Check Console: Look for debug messages in Flutter DevTools

Testing Checklist

Plugin loads without errors
UI renders correctly in the target slot
All SDK function calls work as expected
Plugin doesn’t crash the app
Manifest data is accurate
Version number follows semantic versioning
Plugin works on multiple screen sizes

Publishing to Marketplace

Prepare for Release

Test thoroughly
Write clear documentation
Add screenshots (optional)
Ensure manifest is complete

Create GitHub Repository

Create a new public repository
Add your plugin JSON file
Include a README with usage instructions
Add a LICENSE file

Create a Release

Go to Releases in your GitHub repo
Click “Create a new release”
Tag version (e.g., v1.0.0) matching your plugin version
Write release notes
Publish release

Submit to Marketplace

Copy the raw URL to your plugin JSON
In Invenicum, go to Plugins > Marketplace > Submit Plugin
Paste the URL and submit
Your plugin will be reviewed and published

Best Practices

Keep It Simple

Plugins should do one thing well. Don’t try to cram too much functionality into a single plugin.

Follow Naming Conventions

Use descriptive, unique plugin IDs
Follow semantic versioning (MAJOR.MINOR.PATCH)
Keep names under 50 characters

Optimize Performance

Keep UI hierarchies shallow
Avoid excessive nesting
Don’t make plugins too large

Provide Good UX

Use clear, actionable button labels
Provide feedback for user actions
Handle errors gracefully

Document Your Plugin

Write a clear description
Include usage instructions in your GitHub README
Add comments explaining complex logic

Troubleshooting

Plugin Doesn’t Load

Verify JSON is valid (use a JSON validator)
Check that all required manifest fields are present
Ensure the slot value is valid

SDK Functions Don’t Work

Verify the type is set to "invenicum_sdk"
Check that the method name is correct (case-sensitive)
Ensure params is an object, not an array

UI Doesn’t Render Correctly

Check STAC documentation for proper widget structure
Verify property names match STAC specifications
Test with simpler UI first, then add complexity

Next Steps

Template Creation

Learn how to create custom asset templates

Contributing Guide

Contribute to Invenicum core development

Architecture

Contributing

Documentation Index

​Plugin Architecture Overview

​How Plugins Work

​Getting Started

​Plugin Manifest

​Example Manifest

​UI Slots

​Invenicum SDK Functions

​Available SDK Methods

​getUserName()

​showAlert(message)

​navigate(path)

​logout()

​Using SDK Functions in Your Plugin

​Building Your First Plugin

​Advanced Plugin Examples

​Interactive Counter Plugin

​User Greeting Plugin

​Plugin Service API

​Key Methods

​Install a Plugin

​Toggle Plugin Active State

​Get Installed Plugins

​Get Community Plugins

​Plugin Model Structure

​Testing Your Plugin

​Local Testing

​Testing Checklist

​Publishing to Marketplace

​Best Practices

​Troubleshooting

​Plugin Doesn’t Load

​SDK Functions Don’t Work

​UI Doesn’t Render Correctly

​Next Steps