Merge pull request #12 from codee-sh/improvement/update-githubs

docs: Enhance README and documentation for automation features and ru…

Author: kriss145

README.md

@@ -4,15 +4,13 @@ A comprehensive automation plugin for Medusa v2 that provides a flexible rule-ba
 
 ## Features
 
-- **Automation Triggers**: Create automations triggered by events, schedules, or manual actions
-- **Automation Management**: Create, edit, and delete automation triggers with automatic cleanup of related data
-- **Rule-Based Conditions**: Define complex conditions using rule attributes (e.g., inventory levels, order status)
-- **Multiple Action Types**: Execute various actions including email notifications, Slack messages, SMS, push notifications, and custom actions
-- **Event Subscribers**: Built-in subscribers for common Medusa events (inventory updates, order events, payment events)
-- **Admin Panel**: Manage automations directly from Medusa Admin
-- **Flexible Rules**: Support for multiple rule types and operators (equals, greater than, less than, contains, etc.)
-- **Slack Notifications**: Rich Slack notifications with Block Kit support including headers, action buttons, and dividers
-- **Extensible Actions**: Add custom action handlers to extend automation capabilities
+- **Automation Triggers**: Create automations triggered by events, schedules, or manual actions ([see details](#automation-triggers))
+- **Rule-Based Conditions**: Define complex conditions with support for arrays, relations, and multiple data types ([see details](#rules-and-conditions))
+- **Rich Attribute Support**: Pre-configured attributes for Products, Variants, Tags, Categories, and Inventory ([see available attributes](./docs/configuration.md#available-attributes-reference))
+- **Multiple Action Types**: Execute various actions including email notifications, Slack messages, SMS, push notifications, and custom actions ([see details](#actions))
+- **Event Subscribers**: Built-in subscribers for common Medusa events ([see available events](./docs/configuration.md#available-subscribers))
+- **Admin Panel**: Manage automations directly from Medusa Admin ([see details](#admin-panel))
+- **Extensible**: Add custom action handlers and extend automation capabilities
 - **Type-Safe**: Full TypeScript support with exported types and workflows
 
 ## Compatibility
@@ -50,6 +48,8 @@ The plugin includes database migrations for automation models. Run migrations to
 medusa migrations run
 ```
 
+See [Database Migrations](./docs/configuration.md#database-migrations) for more details about the created tables.
+
 ### 3. Access Admin Panel
 
 Navigate to **Notifications > Automations** in your Medusa Admin dashboard, or directly access:
@@ -63,17 +63,20 @@ Navigate to **Notifications > Automations** in your Medusa Admin dashboard, or d
 ### Automation Triggers
 
 Automations are triggered by:
-- **Events**: Medusa events (e.g., `inventory.inventory-level.updated`, `order.placed`)
+- **Events**: Medusa events (e.g., `inventory.inventory-level.updated`, `product.updated`)
 - **Schedule**: Time-based triggers with configurable intervals (In progress)
 - **Manual**: Triggered manually from the admin panel
 
+See [Available Subscribers](./docs/configuration.md#available-subscribers) in the configuration documentation for a complete list of supported events.
+
 ### Rules and Conditions
 
-Each automation can have multiple rules that define when actions should be executed:
+Each automation can have multiple rules that define when actions should be executed. Rules support primitive fields, relations (arrays), nested objects, and various operators for complex conditions.
 
-- **Rule Attributes**: Available attributes for conditions
-- **Operators**: Comparison operators (equals, greater than, less than, contains, in, etc.)
-- **Rule Values**: Values to compare against
+For detailed information, see:
+- [Available Attributes Reference](./docs/configuration.md#available-attributes-reference) - Complete list of attributes for each event type
+- [Rule Operators](./docs/configuration.md#rule-operators) - All supported operators with examples
+- [Rule Values](./docs/configuration.md#rule-values) - Supported data types and usage
 
 ### Actions
 
@@ -83,7 +86,7 @@ When automation rules pass, actions are executed. Supported action types include
 - **Slack**: Send Slack messages with Block Kit formatting
 - **Custom**: Extend with custom action handlers
 
-See [Configuration Documentation](./docs/configuration.md) for details on built-in subscribers, available actions, and extending functionality.
+See [Actions](./docs/configuration.md#actions) and [Slack Notification Provider](./docs/configuration.md#slack-notification-provider) in the configuration documentation for details on configuring and extending actions.
 
 ## Admin Panel
 

docs/admin.md

@@ -37,16 +37,25 @@ Automations can be triggered by:
 
 Each automation can have multiple rules that define conditions:
 
-- **Rule Attributes**: Select from available attributes (e.g., `inventory_level.available_quantity`)
-- **Operators**: Choose comparison operators (equals, greater than, less than, contains, in, etc.)
-- **Values**: Set values to compare against
+- **Rule Attributes**: Select from available attributes including:
+  - Primitive fields: `product.title`, `inventory_level.available_quantity`
+  - Relations: `product.tags.id`, `product.categories.name` (arrays)
+  - Nested objects: `inventory_level.inventory_item.*`
+- **Operators**: Choose comparison operators:
+  - **Basic**: `equals`, `not equals`, `greater than`, `less than`, `greater than or equal`, `less than or equal`
+  - **Array operations**: `in`, `not in`, `contains`, `not contains`
+  - **Null checks**: `empty`, `not empty`
+- **Values**: Set values to compare against:
+  - **Single values**: Enter a single string or number (e.g., `10`, `"Electronics"`)
+  - **Array values**: Use the chip input to add multiple values (e.g., tag IDs, category names)
+  - **No value**: For `empty` and `not empty` operators, no value input is required
 
 #### Actions
 
 When all rules pass, actions are executed:
 
-- **Channels**: Configure delivery channels (email, slack, admin, etc.)
-- **Metadata**: Add custom metadata for actions
+- **Channels**: Configure delivery channels (email, slack etc.)
+- **Metadata**: Add custom config for actions
 
 ## Using the Admin Panel
 
@@ -60,13 +69,19 @@ When all rules pass, actions are executed:
    - If schedule: Set interval in minutes
    - Set a name and description
 4. **Add Rules**:
-   - Select rule attributes from available options
-   - Choose operators
-   - Set comparison values
-   - Add multiple rules as needed
+   - Select rule attributes from available options (including relations and nested objects)
+   - Choose operators based on your needs:
+     - Use `in` or `not in` for checking if a value exists in an array
+     - Use `contains` or `not contains` for partial matches in arrays
+     - Use `empty` or `not empty` to check for null/empty values
+   - Set comparison values:
+     - For array operators (`in`, `not in`, `contains`, `not contains`): Use the chip input to add multiple values
+     - For basic operators: Enter a single value
+     - For `empty`/`not empty`: No value input needed
+   - Add multiple rules as needed (all rules must pass for the automation to trigger)
 5. **Configure Actions**:
    - Set delivery channels
-   - Add metadata if needed
+   - Add config if needed
 6. **Save**: Save the automation configuration
 
 ### Editing an Automation
@@ -91,21 +106,37 @@ Create an automation that sends a notification when inventory levels drop below
 - **Rule**: `inventory_level.available_quantity` is less than `10`
 - **Action**: Send email notification
 
-### High Stock Alert
+### Product Tag Automation
 
-Create an automation for when inventory exceeds a certain level:
+Create an automation that triggers when a product has specific tags:
+
+- **Trigger**: Event `product.product.updated`
+- **Rule**: `product.tags.id` is `in` `[tag-premium, tag-featured]` (use chip input for multiple tag IDs)
+- **Action**: Send Slack notification
+
+### Category-Based Automation
+
+Create an automation for products in specific categories:
+
+- **Trigger**: Event `product.product.created`
+- **Rule**: `product.categories.name` contains `"Electronics"` (or use `in` operator with multiple category names)
+- **Action**: Send email notification
+
+### Empty Inventory Check
+
+Create an automation that triggers when inventory is empty:
 
 - **Trigger**: Event `inventory.inventory-level.updated`
-- **Rule**: `inventory_level.stocked_quantity` is greater than `1000`
-- **Action**: Send admin notification
+- **Rule**: `inventory_level.available_quantity` is `empty`
+- **Action**: Send Slack notification
 
-### Scheduled Inventory Report
+### High Stock Alert
 
-Create a scheduled automation that runs periodically:
+Create an automation for when inventory exceeds a certain level:
 
-- **Trigger**: Schedule with interval of `1440` minutes (daily)
-- **Rules**: Configure conditions for what to include in the report
-- **Action**: Generate and send inventory report
+- **Trigger**: Event `inventory.inventory-level.updated`
+- **Rule**: `inventory_level.stocked_quantity` is greater than `1000`
+- **Action**: Send Slack notification
 
 ## Best Practices
 
@@ -114,4 +145,10 @@ Create a scheduled automation that runs periodically:
 3. **Monitor Performance**: Keep an eye on automation execution and performance
 4. **Use Appropriate Triggers**: Choose the right trigger type for your use case
 5. **Combine Rules**: Use multiple rules to create complex conditions
-6. **Document Automations**: Add descriptions to explain automation purpose
+6. **Document Automations**: Add descriptions to explain automation purpose
+7. **Choose the Right Operator**: 
+   - Use `in`/`not in` for exact matches in arrays (e.g., checking if product has specific tags)
+   - Use `contains`/`not contains` for partial matches (e.g., checking if category name contains a substring)
+   - Use `empty`/`not empty` for null checks
+8. **Use Array Values Correctly**: When using array operators (`in`, `not in`, `contains`, `not contains`), use the chip input to add multiple values
+9. **Leverage Relations**: Use relation-based attributes (e.g., `product.tags.id`, `product.categories.name`) to create powerful automations based on related data