fluentcart-developer 1.1.0 → 1.1.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 (65) hide show
  1. package/CLAUDE.md +22 -22
  2. package/LICENSE +21 -21
  3. package/README.md +169 -127
  4. package/SKILL.md +127 -127
  5. package/bin/index.js +281 -281
  6. package/package.json +48 -37
  7. package/skills/fluentcart-developer/SKILL.md +172 -172
  8. package/skills/fluentcart-developer/examples/README.md +25 -25
  9. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -32
  10. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -40
  11. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -114
  12. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -149
  13. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -38
  14. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -62
  15. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -787
  16. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -1355
  17. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -266
  18. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -855
  19. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -631
  20. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -963
  21. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -585
  22. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -661
  23. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -194
  24. package/skills/fluentcart-developer/references/database-models-reference.md +604 -604
  25. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -940
  26. package/skills/fluentcart-developer/references/engineering-notes.md +154 -154
  27. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -449
  28. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -1202
  29. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -902
  30. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -1598
  31. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -1319
  32. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -628
  33. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -1177
  34. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -154
  35. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -458
  36. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -224
  37. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -761
  38. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -286
  39. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -794
  40. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -190
  41. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -1121
  42. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -219
  43. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -619
  44. package/skills/fluentcart-developer/references/rest-api-files.md +290 -290
  45. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -324
  46. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -321
  47. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -171
  48. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -200
  49. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -1241
  50. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -131
  51. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -2563
  52. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -172
  53. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -552
  54. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -377
  55. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -147
  56. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -528
  57. package/skills/fluentcart-developer/references/rest-api-shipping.md +799 -799
  58. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -606
  59. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -356
  60. package/skills/fluentcart-developer/references/subscription-customization.md +197 -197
  61. package/skills/fluentcart-developer/scripts/cli.js +1 -1
  62. package/.gitattributes +0 -2
  63. package/CONTRIBUTING.md +0 -73
  64. package/copy-skills.js +0 -43
  65. package/skills.sh.json +0 -13
@@ -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
+ ```