fluentcart-developer 2.3.0 → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +59 -59
  2. package/dist/cards/fluentcart/tools.d.ts.map +1 -1
  3. package/dist/cards/fluentcart/tools.js +2301 -2161
  4. package/dist/cards/fluentcart/tools.js.map +1 -1
  5. package/dist/skills/fluentcart-developer/.claude-plugin/plugin.json +12 -12
  6. package/dist/skills/fluentcart-developer/.mcp.json +11 -11
  7. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  8. package/dist/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  9. package/dist/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  10. package/dist/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  11. package/dist/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  12. package/dist/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  13. package/dist/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  14. package/dist/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  15. package/dist/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  16. package/dist/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  17. package/dist/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  18. package/dist/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  19. package/dist/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  20. package/dist/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  21. package/dist/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  22. package/dist/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  23. package/dist/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  24. package/dist/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  25. package/dist/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  26. package/dist/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  27. package/dist/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  28. package/dist/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  29. package/dist/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  30. package/dist/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  31. package/dist/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  32. package/dist/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  33. package/dist/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  34. package/dist/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  35. package/dist/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  36. package/dist/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  37. package/dist/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  38. package/dist/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  39. package/dist/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  40. package/dist/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  41. package/dist/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  42. package/dist/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  43. package/dist/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  44. package/dist/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  45. package/dist/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  46. package/dist/skills/fluentcart-developer/scripts/cli.js +1 -1
  47. package/dist/version.d.ts +1 -1
  48. package/dist/version.js +1 -1
  49. package/package.json +65 -65
@@ -1,154 +1,154 @@
1
- # FluentCart Core Complete Developer Guide
2
-
3
- > Source: Official FluentCart Developer Guide Documentation
4
-
5
- Welcome to the complete developer guide for **FluentCart** — the self-hosted e-commerce plugin for WordPress. This guide covers core principles, architecture, extension points, codebase structure, and quick start instructions for developing custom add-ons, modules, and integrations.
6
-
7
- ---
8
-
9
- ## 🚀 Overview
10
-
11
- ### What is FluentCart?
12
- FluentCart is a **Self-Hosted E-commerce Plugin for WordPress** that helps businesses manage online stores, process payments, handle orders, and manage customers natively inside WordPress.
13
-
14
- Unlike cloud-based SaaS solutions, FluentCart runs entirely on your WordPress site, ensuring total data privacy, unlimited products, zero order transaction surcharges, and complete operational control.
15
-
16
- ### Why Extend FluentCart?
17
- FluentCart is engineered from the ground up for deep extensibility:
18
-
19
- - **315+ Action and Filter Hooks** for intercepting and customizing core execution flows.
20
- - **Modular Architecture** allowing clean separation of payment gateways, shipping methods, and custom modules.
21
- - **RESTful API** offering complete programmatic access to e-commerce resources.
22
- - **WordPress-Native Standards** following modern PHP, PSR coding standards, and WordPress conventions.
23
-
24
- ---
25
-
26
- ## 📦 FluentCart Core vs. Pro Version Comparison
27
-
28
- | Feature Category | Core (Free Version) | Pro (Premium Version) |
29
- |---|---|---|
30
- | **Product & Catalog** | Unlimited products, simple & variable pricing | Advanced variations & ghost products |
31
- | **Order Processing** | Complete order management & receipts | Automated post-order workflows & order operation logs |
32
- | **Customer Management** | Customer profiles, LTV tracking & addresses | Custom customer meta, advanced segmentation |
33
- | **Payments & Shipping** | Core payment gateways & shipping zones | Dynamic shipping carriers, custom payment integrations |
34
- | **Coupons & Discounts** | Standard discount codes & conditions | Stackable coupons, auto-applied promos & Order Bumps |
35
- | **Software Licensing** | N/A | Full software license keys, site activations & updates |
36
- | **Subscriptions** | N/A | Recurring billing cycles, trial periods & grace periods |
37
- | **Roles & Permissions** | Basic WordPress capability checks | Granular team roles & permission management |
38
-
39
- ---
40
-
41
- ## 🏗 Core Development Concepts
42
-
43
- ### 1. Data Architecture
44
- FluentCart uses a clean, normalized database structure with integer monetary values stored in **cents**:
45
-
46
- - **Orders (`fct_orders`):** Central record for order status, customer links, totals, and payment status.
47
- - **Customers (`fct_customers`):** Profiles linked to WordPress users or guest transactions.
48
- - **Products (WordPress Posts):** Core product metadata stored as custom post types, supplemented by `fct_product_details` and `fct_product_variations`.
49
- - **Transactions (`fct_order_transactions`):** Payment charges, refunds, and gateway interaction records.
50
- - **Subscriptions (`fct_subscriptions`):** Recurring billing metadata, billing cycles, and next billing schedules.
51
-
52
- ### 2. Extension Points
53
- - **WordPress Action Hooks:** Execute custom code on events (e.g. `fluent_cart/order_paid_done`).
54
- - **WordPress Filter Hooks:** Modify data in-flight (e.g. `fluent_cart/fee_items`).
55
- - **Module System:** Register custom payment gateways, shipping carriers, and storage drivers.
56
- - **REST API:** Build external applications, dashboards, or headless checkout experiences.
57
-
58
- ---
59
-
60
- ## 📁 Application Codebase Directory Structure
61
-
62
- ```
63
- fluent-cart/
64
- ├── app/ # Core application logic
65
- │ ├── Hooks/ # WordPress action/filter handlers
66
- │ │ ├── Handlers/ # Action/Filter handler classes
67
- │ │ ├── actions.php # Action hook definitions
68
- │ │ └── filters.php # Filter hook definitions
69
- │ ├── Http/ # HTTP layer
70
- │ │ ├── Controllers/ # Admin & REST API controllers
71
- │ │ ├── Middleware/ # Request authentication & authorization
72
- │ │ └── Routes/ # API and admin route definitions
73
- │ ├── Models/ # Eloquent ORM database models (45+ models)
74
- │ │ ├── Order.php # Order model
75
- │ │ ├── Customer.php # Customer model
76
- │ │ ├── Product.php # Product model
77
- │ │ └── ... # Core & Pro model files
78
- │ ├── Services/ # Core business logic services
79
- │ │ ├── Payment/ # Payment processing drivers
80
- │ │ ├── Shipping/ # Shipping calculation engines
81
- │ │ └── Helper.php # Global helper utility functions
82
- │ ├── Views/ # Admin PHP template views
83
- │ ├── Events/ # Internal application events
84
- │ ├── Listeners/ # Event listeners
85
- │ └── Modules/ # Module registration system
86
- │
87
- ├── api/ # REST API resources & endpoint controllers
88
- │ ├── Orders.php # Order management REST endpoints
89
- │ ├── Customers.php # Customer management REST endpoints
90
- │ ├── Products.php # Product catalog REST endpoints
91
- │ └── Resource/ # JSON response resource transformers
92
- │
93
- ├── resources/ # Frontend application assets
94
- │ ├── admin/ # Vue.js admin single-page application & Gutenberg blocks
95
- │ ├── public/ # Storefront cart, checkout & portal components
96
- │ └── styles/ # Core SCSS/CSS design tokens
97
- │
98
- ├── database/ # Database schema migrations & seeders
99
- │ ├── Migrations/ # Table migration files (34+ migrations)
100
- │ └── DBMigrator.php # Database migration manager
101
- │
102
- └── fluent-cart.php # Main WordPress plugin bootstrap entry file
103
- ```
104
-
105
- ---
106
-
107
- ## ⚡ Quick Start Extension Blueprints
108
-
109
- ### 1. Registering a Custom Extension
110
- ```php
111
- <?php
112
- /**
113
- * Plugin Name: FluentCart Custom Extension
114
- * Description: Extension module for FluentCart e-commerce.
115
- * Version: 1.0.0
116
- * Author: Developer
117
- */
118
-
119
- if (!defined('ABSPATH')) {
120
- exit; // Prevent direct execution access
121
- }
122
-
123
- // Attach listener to WordPress plugins_loaded hook
124
- add_action('plugins_loaded', function () {
125
- // Verify that FluentCart plugin is active
126
- if (!defined('FLUENT_CART')) {
127
- return; // Exit early if FluentCart is missing
128
- }
129
-
130
- // Initialize custom hook listeners and extension modules here
131
- });
132
- ```
133
-
134
- ### 2. Post-Payment Asynchronous Task Listener
135
- ```php
136
- // Intercept order paid event asynchronously via Action Scheduler
137
- add_action('fluent_cart/order_paid_done', function ($payload) {
138
- // Extract Order model instance from payload array
139
- $order = $payload['order'];
140
-
141
- // Extract Customer model instance from payload array
142
- $customer = $payload['customer'];
143
-
144
- // Convert total order amount from integer cents to decimal format
145
- $orderTotal = \FluentCart\App\Helpers\Helper::toDecimal($order->total_amount);
146
-
147
- // Log payment details into FluentCart system activity log
148
- fluent_cart_add_log(
149
- 'Order Completed',
150
- "Order #{$order->id} for {$customer->email} completed. Amount: ${orderTotal}",
151
- 'info'
152
- );
153
- }, 10, 1);
154
- ```
1
+ # FluentCart Core Complete Developer Guide
2
+
3
+ > Source: Official FluentCart Developer Guide Documentation
4
+
5
+ Welcome to the complete developer guide for **FluentCart** — the self-hosted e-commerce plugin for WordPress. This guide covers core principles, architecture, extension points, codebase structure, and quick start instructions for developing custom add-ons, modules, and integrations.
6
+
7
+ ---
8
+
9
+ ## 🚀 Overview
10
+
11
+ ### What is FluentCart?
12
+ FluentCart is a **Self-Hosted E-commerce Plugin for WordPress** that helps businesses manage online stores, process payments, handle orders, and manage customers natively inside WordPress.
13
+
14
+ Unlike cloud-based SaaS solutions, FluentCart runs entirely on your WordPress site, ensuring total data privacy, unlimited products, zero order transaction surcharges, and complete operational control.
15
+
16
+ ### Why Extend FluentCart?
17
+ FluentCart is engineered from the ground up for deep extensibility:
18
+
19
+ - **315+ Action and Filter Hooks** for intercepting and customizing core execution flows.
20
+ - **Modular Architecture** allowing clean separation of payment gateways, shipping methods, and custom modules.
21
+ - **RESTful API** offering complete programmatic access to e-commerce resources.
22
+ - **WordPress-Native Standards** following modern PHP, PSR coding standards, and WordPress conventions.
23
+
24
+ ---
25
+
26
+ ## 📦 FluentCart Core vs. Pro Version Comparison
27
+
28
+ | Feature Category | Core (Free Version) | Pro (Premium Version) |
29
+ |---|---|---|
30
+ | **Product & Catalog** | Unlimited products, simple & variable pricing | Advanced variations & ghost products |
31
+ | **Order Processing** | Complete order management & receipts | Automated post-order workflows & order operation logs |
32
+ | **Customer Management** | Customer profiles, LTV tracking & addresses | Custom customer meta, advanced segmentation |
33
+ | **Payments & Shipping** | Core payment gateways & shipping zones | Dynamic shipping carriers, custom payment integrations |
34
+ | **Coupons & Discounts** | Standard discount codes & conditions | Stackable coupons, auto-applied promos & Order Bumps |
35
+ | **Software Licensing** | N/A | Full software license keys, site activations & updates |
36
+ | **Subscriptions** | N/A | Recurring billing cycles, trial periods & grace periods |
37
+ | **Roles & Permissions** | Basic WordPress capability checks | Granular team roles & permission management |
38
+
39
+ ---
40
+
41
+ ## 🏗 Core Development Concepts
42
+
43
+ ### 1. Data Architecture
44
+ FluentCart uses a clean, normalized database structure with integer monetary values stored in **cents**:
45
+
46
+ - **Orders (`fct_orders`):** Central record for order status, customer links, totals, and payment status.
47
+ - **Customers (`fct_customers`):** Profiles linked to WordPress users or guest transactions.
48
+ - **Products (WordPress Posts):** Core product metadata stored as custom post types, supplemented by `fct_product_details` and `fct_product_variations`.
49
+ - **Transactions (`fct_order_transactions`):** Payment charges, refunds, and gateway interaction records.
50
+ - **Subscriptions (`fct_subscriptions`):** Recurring billing metadata, billing cycles, and next billing schedules.
51
+
52
+ ### 2. Extension Points
53
+ - **WordPress Action Hooks:** Execute custom code on events (e.g. `fluent_cart/order_paid_done`).
54
+ - **WordPress Filter Hooks:** Modify data in-flight (e.g. `fluent_cart/fee_items`).
55
+ - **Module System:** Register custom payment gateways, shipping carriers, and storage drivers.
56
+ - **REST API:** Build external applications, dashboards, or headless checkout experiences.
57
+
58
+ ---
59
+
60
+ ## 📁 Application Codebase Directory Structure
61
+
62
+ ```
63
+ fluent-cart/
64
+ ├── app/ # Core application logic
65
+ │ ├── Hooks/ # WordPress action/filter handlers
66
+ │ │ ├── Handlers/ # Action/Filter handler classes
67
+ │ │ ├── actions.php # Action hook definitions
68
+ │ │ └── filters.php # Filter hook definitions
69
+ │ ├── Http/ # HTTP layer
70
+ │ │ ├── Controllers/ # Admin & REST API controllers
71
+ │ │ ├── Middleware/ # Request authentication & authorization
72
+ │ │ └── Routes/ # API and admin route definitions
73
+ │ ├── Models/ # Eloquent ORM database models (45+ models)
74
+ │ │ ├── Order.php # Order model
75
+ │ │ ├── Customer.php # Customer model
76
+ │ │ ├── Product.php # Product model
77
+ │ │ └── ... # Core & Pro model files
78
+ │ ├── Services/ # Core business logic services
79
+ │ │ ├── Payment/ # Payment processing drivers
80
+ │ │ ├── Shipping/ # Shipping calculation engines
81
+ │ │ └── Helper.php # Global helper utility functions
82
+ │ ├── Views/ # Admin PHP template views
83
+ │ ├── Events/ # Internal application events
84
+ │ ├── Listeners/ # Event listeners
85
+ │ └── Modules/ # Module registration system
86
+ │
87
+ ├── api/ # REST API resources & endpoint controllers
88
+ │ ├── Orders.php # Order management REST endpoints
89
+ │ ├── Customers.php # Customer management REST endpoints
90
+ │ ├── Products.php # Product catalog REST endpoints
91
+ │ └── Resource/ # JSON response resource transformers
92
+ │
93
+ ├── resources/ # Frontend application assets
94
+ │ ├── admin/ # Vue.js admin single-page application & Gutenberg blocks
95
+ │ ├── public/ # Storefront cart, checkout & portal components
96
+ │ └── styles/ # Core SCSS/CSS design tokens
97
+ │
98
+ ├── database/ # Database schema migrations & seeders
99
+ │ ├── Migrations/ # Table migration files (34+ migrations)
100
+ │ └── DBMigrator.php # Database migration manager
101
+ │
102
+ └── fluent-cart.php # Main WordPress plugin bootstrap entry file
103
+ ```
104
+
105
+ ---
106
+
107
+ ## ⚡ Quick Start Extension Blueprints
108
+
109
+ ### 1. Registering a Custom Extension
110
+ ```php
111
+ <?php
112
+ /**
113
+ * Plugin Name: FluentCart Custom Extension
114
+ * Description: Extension module for FluentCart e-commerce.
115
+ * Version: 1.0.0
116
+ * Author: Developer
117
+ */
118
+
119
+ if (!defined('ABSPATH')) {
120
+ exit; // Prevent direct execution access
121
+ }
122
+
123
+ // Attach listener to WordPress plugins_loaded hook
124
+ add_action('plugins_loaded', function () {
125
+ // Verify that FluentCart plugin is active
126
+ if (!defined('FLUENT_CART')) {
127
+ return; // Exit early if FluentCart is missing
128
+ }
129
+
130
+ // Initialize custom hook listeners and extension modules here
131
+ });
132
+ ```
133
+
134
+ ### 2. Post-Payment Asynchronous Task Listener
135
+ ```php
136
+ // Intercept order paid event asynchronously via Action Scheduler
137
+ add_action('fluent_cart/order_paid_done', function ($payload) {
138
+ // Extract Order model instance from payload array
139
+ $order = $payload['order'];
140
+
141
+ // Extract Customer model instance from payload array
142
+ $customer = $payload['customer'];
143
+
144
+ // Convert total order amount from integer cents to decimal format
145
+ $orderTotal = \FluentCart\App\Helpers\Helper::toDecimal($order->total_amount);
146
+
147
+ // Log payment details into FluentCart system activity log
148
+ fluent_cart_add_log(
149
+ 'Order Completed',
150
+ "Order #{$order->id} for {$customer->email} completed. Amount: ${orderTotal}",
151
+ 'info'
152
+ );
153
+ }, 10, 1);
154
+ ```