fluentcart-developer 2.3.0 → 2.3.2

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 +160 -12
  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,224 +1,224 @@
1
- # FluentCart Modules, Extensions & Custom Integrations Master Reference
2
-
3
- > Source: https://dev.fluentcart.com/
4
-
5
- Complete architectural guide for developing custom payment gateways, dynamic shipping carriers, fee surcharges, ghost product selling, subscription management, WP-CLI commands, and theme compatibility for FluentCart.
6
-
7
- ---
8
-
9
- ## Table of Contents
10
- 1. [Custom Payment Gateway Development](#1-custom-payment-gateway-development)
11
- 2. [Dynamic Shipping Carrier Integration](#2-dynamic-shipping-carrier-integration)
12
- 3. [Fee Surcharge & Handling Charges System](#3-fee-surcharge--handling-charges-system)
13
- 4. [Ghost Product Selling Architecture](#4-ghost-product-selling-architecture)
14
- 5. [Subscription Engine Customization](#5-subscription-engine-customization)
15
- 6. [Theme Compatibility & Template Overrides](#6-theme-compatibility--template-overrides)
16
- 7. [Gutenberg Blocks, Elementor & Page Builders](#7-gutenberg-blocks-elementor--page-builders)
17
- 8. [WP-CLI Command Reference](#8-wp-cli-command-reference)
18
-
19
- ---
20
-
21
- ## 1. Custom Payment Gateway Development
22
-
23
- To implement a new custom payment gateway (e.g. bKash, Nagad, Razorpay, SSLCommerz, Paddle):
24
-
25
- ### Gateway Registration Filter
26
- ```php
27
- add_filter('fluent_cart/payment_methods', function ($methods) {
28
- $methods['my_custom_gateway'] = \MyExtension\Gateways\CustomGatewayDriver::class;
29
- return $methods;
30
- });
31
- ```
32
-
33
- ### Driver Implementation Standard
34
- Subclass `\FluentCart\App\Services\Payments\BasePaymentMethod`:
35
-
36
- ```php
37
- namespace MyExtension\Gateways;
38
-
39
- use FluentCart\App\Services\Payments\BasePaymentMethod;
40
- use FluentCart\App\Models\Order;
41
-
42
- class CustomGatewayDriver extends BasePaymentMethod
43
- {
44
- protected $gatewayKey = 'my_custom_gateway';
45
-
46
- public function getTitle()
47
- {
48
- return __('Custom Gateway', 'my-extension');
49
- }
50
-
51
- public function getSettingsFields()
52
- {
53
- return [
54
- 'api_key' => [
55
- 'type' => 'input_text',
56
- 'label' => __('API Secret Key', 'my-extension'),
57
- 'placeholder' => 'sk_live_...',
58
- ],
59
- 'sandbox_mode' => [
60
- 'type' => 'checkbox',
61
- 'label' => __('Enable Test Mode', 'my-extension'),
62
- ]
63
- ];
64
- }
65
-
66
- public function makePayment($order, $transaction, $cart)
67
- {
68
- // 1. Convert amount to cents
69
- $amountInCents = $order->total_amount;
70
-
71
- // 2. Execute gateway API HTTP POST
72
- $response = wp_remote_post('https://api.mygateway.com/v1/charge', [
73
- 'headers' => ['Authorization' => 'Bearer ' . $this->getSetting('api_key')],
74
- 'body' => [
75
- 'amount' => $amountInCents,
76
- 'currency' => $order->currency,
77
- 'order_id' => $order->id,
78
- ]
79
- ]);
80
-
81
- if (is_wp_error($response)) {
82
- return [
83
- 'status' => 'failed',
84
- 'message' => $response->get_error_message()
85
- ];
86
- }
87
-
88
- return [
89
- 'status' => 'success',
90
- 'transaction_id' => 'tx_' . time(),
91
- 'redirect_url' => $order->getReceiptUrl()
92
- ];
93
- }
94
- }
95
- ```
96
-
97
- ---
98
-
99
- ## 2. Dynamic Shipping Carrier Integration
100
-
101
- Intercept available shipping rates dynamically via `fluent_cart/shipping_methods`:
102
-
103
- ```php
104
- add_filter('fluent_cart/shipping_methods', function ($methods, $cart) {
105
- $shippingAddress = $cart->shipping_address;
106
-
107
- // Call external shipping rate API (e.g. FedEx / DHL)
108
- $calculatedRateInCents = 1500; // $15.00 in cents
109
-
110
- $methods['custom_express_carrier'] = [
111
- 'id' => 'custom_express_carrier',
112
- 'title' => __('Express Courier Shipping (1-2 Days)', 'my-extension'),
113
- 'cost' => $calculatedRateInCents,
114
- 'tax_status' => 'taxable',
115
- ];
116
-
117
- return $methods;
118
- }, 10, 2);
119
- ```
120
-
121
- ---
122
-
123
- ## 3. Fee Surcharge & Handling Charges System
124
-
125
- Inject dynamic fees (e.g. gift wrap, payment processing surcharge, handling fee):
126
-
127
- ```php
128
- add_filter('fluent_cart/fee_items', function ($fees, $cart) {
129
- // Add dynamic $5.00 handling fee if subtotal is below $50.00 (5000 cents)
130
- if ($cart->subtotal < 5000) {
131
- $fees[] = [
132
- 'id' => 'small_order_fee',
133
- 'title' => __('Minimum Order Handling Surcharge', 'my-extension'),
134
- 'amount' => 500, // $5.00 in cents
135
- 'taxable' => false,
136
- ];
137
- }
138
- return $fees;
139
- }, 10, 2);
140
- ```
141
-
142
- ---
143
-
144
- ## 4. Ghost Product Selling Architecture
145
-
146
- Ghost products allow selling dynamically configured digital goods, custom service passes, or custom memberships without needing pre-existing WooCommerce / CPT product IDs.
147
-
148
- ```php
149
- add_filter('fluent_cart/cart_items', function ($items, $cart) {
150
- // Dynamically append an unlisted ghost product line item to cart
151
- $items[] = [
152
- 'id' => 'ghost_item_' . time(),
153
- 'post_id' => 0, // 0 indicates virtual unlisted product
154
- 'title' => __('Custom Consultation Session', 'my-extension'),
155
- 'unit_price' => 4900, // $49.00 in cents
156
- 'quantity' => 1,
157
- 'is_virtual' => true,
158
- ];
159
- return $items;
160
- }, 10, 2);
161
- ```
162
-
163
- ---
164
-
165
- ## 5. Subscription Engine Customization
166
-
167
- Customize recurring subscription schedules, trial durations, and renewal pricing:
168
-
169
- ```php
170
- // Dynamic Subscription Renewal Price Modifier
171
- add_filter('fluent_cart/subscription_renewal_price', function ($priceInCents, $subscription) {
172
- // Apply 10% loyalty renewal discount for long-term active subscribers
173
- if ($subscription->bill_count >= 12) {
174
- return (int) round($priceInCents * 0.90);
175
- }
176
- return $priceInCents;
177
- }, 10, 2);
178
- ```
179
-
180
- ---
181
-
182
- ## 6. Theme Compatibility & Template Overrides
183
-
184
- ### Template Hierarchy & Path Resolution
185
- FluentCart checks for template overrides in your active theme root:
186
- `your-theme/fluentcart/checkout.php`
187
- `your-theme/fluentcart/receipt.php`
188
- `your-theme/fluentcart/single-product.php`
189
-
190
- ### Disabling Global Theme Styles Conflicts
191
- ```php
192
- add_filter('fluent_cart/disable_default_theme_styles', '__return_true');
193
- ```
194
-
195
- ---
196
-
197
- ## 7. Gutenberg Blocks, Elementor & Page Builders
198
-
199
- ### Shortcodes Catalog
200
- - **Product Catalog Grid:** `[fluent_cart_products category="digital" limit="12"]`
201
- - **Single Product Card:** `[fluent_cart_product id="101"]`
202
- - **Checkout Form:** `[fluent_cart_checkout]`
203
- - **Customer Account Portal:** `[fluent_cart_customer_portal]`
204
- - **Order Receipt Confirmation:** `[fluent_cart_receipt]`
205
-
206
- ---
207
-
208
- ## 8. WP-CLI Command Reference
209
-
210
- FluentCart includes native WP-CLI commands for database migrations, cache purging, and sync tasks:
211
-
212
- ```bash
213
- # Flush FluentCart store cache
214
- wp fluentcart cache flush
215
-
216
- # Run pending database schema migrations
217
- wp fluentcart db migrate
218
-
219
- # Sync customer order counts & lifetime spend metrics
220
- wp fluentcart customer recalculate-metrics
221
-
222
- # Clear expired checkout cart sessions
223
- wp fluentcart cart cleanup
224
- ```
1
+ # FluentCart Modules, Extensions & Custom Integrations Master Reference
2
+
3
+ > Source: https://dev.fluentcart.com/
4
+
5
+ Complete architectural guide for developing custom payment gateways, dynamic shipping carriers, fee surcharges, ghost product selling, subscription management, WP-CLI commands, and theme compatibility for FluentCart.
6
+
7
+ ---
8
+
9
+ ## Table of Contents
10
+ 1. [Custom Payment Gateway Development](#1-custom-payment-gateway-development)
11
+ 2. [Dynamic Shipping Carrier Integration](#2-dynamic-shipping-carrier-integration)
12
+ 3. [Fee Surcharge & Handling Charges System](#3-fee-surcharge--handling-charges-system)
13
+ 4. [Ghost Product Selling Architecture](#4-ghost-product-selling-architecture)
14
+ 5. [Subscription Engine Customization](#5-subscription-engine-customization)
15
+ 6. [Theme Compatibility & Template Overrides](#6-theme-compatibility--template-overrides)
16
+ 7. [Gutenberg Blocks, Elementor & Page Builders](#7-gutenberg-blocks-elementor--page-builders)
17
+ 8. [WP-CLI Command Reference](#8-wp-cli-command-reference)
18
+
19
+ ---
20
+
21
+ ## 1. Custom Payment Gateway Development
22
+
23
+ To implement a new custom payment gateway (e.g. bKash, Nagad, Razorpay, SSLCommerz, Paddle):
24
+
25
+ ### Gateway Registration Filter
26
+ ```php
27
+ add_filter('fluent_cart/payment_methods', function ($methods) {
28
+ $methods['my_custom_gateway'] = \MyExtension\Gateways\CustomGatewayDriver::class;
29
+ return $methods;
30
+ });
31
+ ```
32
+
33
+ ### Driver Implementation Standard
34
+ Subclass `\FluentCart\App\Services\Payments\BasePaymentMethod`:
35
+
36
+ ```php
37
+ namespace MyExtension\Gateways;
38
+
39
+ use FluentCart\App\Services\Payments\BasePaymentMethod;
40
+ use FluentCart\App\Models\Order;
41
+
42
+ class CustomGatewayDriver extends BasePaymentMethod
43
+ {
44
+ protected $gatewayKey = 'my_custom_gateway';
45
+
46
+ public function getTitle()
47
+ {
48
+ return __('Custom Gateway', 'my-extension');
49
+ }
50
+
51
+ public function getSettingsFields()
52
+ {
53
+ return [
54
+ 'api_key' => [
55
+ 'type' => 'input_text',
56
+ 'label' => __('API Secret Key', 'my-extension'),
57
+ 'placeholder' => 'sk_live_...',
58
+ ],
59
+ 'sandbox_mode' => [
60
+ 'type' => 'checkbox',
61
+ 'label' => __('Enable Test Mode', 'my-extension'),
62
+ ]
63
+ ];
64
+ }
65
+
66
+ public function makePayment($order, $transaction, $cart)
67
+ {
68
+ // 1. Convert amount to cents
69
+ $amountInCents = $order->total_amount;
70
+
71
+ // 2. Execute gateway API HTTP POST
72
+ $response = wp_remote_post('https://api.mygateway.com/v1/charge', [
73
+ 'headers' => ['Authorization' => 'Bearer ' . $this->getSetting('api_key')],
74
+ 'body' => [
75
+ 'amount' => $amountInCents,
76
+ 'currency' => $order->currency,
77
+ 'order_id' => $order->id,
78
+ ]
79
+ ]);
80
+
81
+ if (is_wp_error($response)) {
82
+ return [
83
+ 'status' => 'failed',
84
+ 'message' => $response->get_error_message()
85
+ ];
86
+ }
87
+
88
+ return [
89
+ 'status' => 'success',
90
+ 'transaction_id' => 'tx_' . time(),
91
+ 'redirect_url' => $order->getReceiptUrl()
92
+ ];
93
+ }
94
+ }
95
+ ```
96
+
97
+ ---
98
+
99
+ ## 2. Dynamic Shipping Carrier Integration
100
+
101
+ Intercept available shipping rates dynamically via `fluent_cart/shipping_methods`:
102
+
103
+ ```php
104
+ add_filter('fluent_cart/shipping_methods', function ($methods, $cart) {
105
+ $shippingAddress = $cart->shipping_address;
106
+
107
+ // Call external shipping rate API (e.g. FedEx / DHL)
108
+ $calculatedRateInCents = 1500; // $15.00 in cents
109
+
110
+ $methods['custom_express_carrier'] = [
111
+ 'id' => 'custom_express_carrier',
112
+ 'title' => __('Express Courier Shipping (1-2 Days)', 'my-extension'),
113
+ 'cost' => $calculatedRateInCents,
114
+ 'tax_status' => 'taxable',
115
+ ];
116
+
117
+ return $methods;
118
+ }, 10, 2);
119
+ ```
120
+
121
+ ---
122
+
123
+ ## 3. Fee Surcharge & Handling Charges System
124
+
125
+ Inject dynamic fees (e.g. gift wrap, payment processing surcharge, handling fee):
126
+
127
+ ```php
128
+ add_filter('fluent_cart/fee_items', function ($fees, $cart) {
129
+ // Add dynamic $5.00 handling fee if subtotal is below $50.00 (5000 cents)
130
+ if ($cart->subtotal < 5000) {
131
+ $fees[] = [
132
+ 'id' => 'small_order_fee',
133
+ 'title' => __('Minimum Order Handling Surcharge', 'my-extension'),
134
+ 'amount' => 500, // $5.00 in cents
135
+ 'taxable' => false,
136
+ ];
137
+ }
138
+ return $fees;
139
+ }, 10, 2);
140
+ ```
141
+
142
+ ---
143
+
144
+ ## 4. Ghost Product Selling Architecture
145
+
146
+ Ghost products allow selling dynamically configured digital goods, custom service passes, or custom memberships without needing pre-existing WooCommerce / CPT product IDs.
147
+
148
+ ```php
149
+ add_filter('fluent_cart/cart_items', function ($items, $cart) {
150
+ // Dynamically append an unlisted ghost product line item to cart
151
+ $items[] = [
152
+ 'id' => 'ghost_item_' . time(),
153
+ 'post_id' => 0, // 0 indicates virtual unlisted product
154
+ 'title' => __('Custom Consultation Session', 'my-extension'),
155
+ 'unit_price' => 4900, // $49.00 in cents
156
+ 'quantity' => 1,
157
+ 'is_virtual' => true,
158
+ ];
159
+ return $items;
160
+ }, 10, 2);
161
+ ```
162
+
163
+ ---
164
+
165
+ ## 5. Subscription Engine Customization
166
+
167
+ Customize recurring subscription schedules, trial durations, and renewal pricing:
168
+
169
+ ```php
170
+ // Dynamic Subscription Renewal Price Modifier
171
+ add_filter('fluent_cart/subscription_renewal_price', function ($priceInCents, $subscription) {
172
+ // Apply 10% loyalty renewal discount for long-term active subscribers
173
+ if ($subscription->bill_count >= 12) {
174
+ return (int) round($priceInCents * 0.90);
175
+ }
176
+ return $priceInCents;
177
+ }, 10, 2);
178
+ ```
179
+
180
+ ---
181
+
182
+ ## 6. Theme Compatibility & Template Overrides
183
+
184
+ ### Template Hierarchy & Path Resolution
185
+ FluentCart checks for template overrides in your active theme root:
186
+ `your-theme/fluentcart/checkout.php`
187
+ `your-theme/fluentcart/receipt.php`
188
+ `your-theme/fluentcart/single-product.php`
189
+
190
+ ### Disabling Global Theme Styles Conflicts
191
+ ```php
192
+ add_filter('fluent_cart/disable_default_theme_styles', '__return_true');
193
+ ```
194
+
195
+ ---
196
+
197
+ ## 7. Gutenberg Blocks, Elementor & Page Builders
198
+
199
+ ### Shortcodes Catalog
200
+ - **Product Catalog Grid:** `[fluent_cart_products category="digital" limit="12"]`
201
+ - **Single Product Card:** `[fluent_cart_product id="101"]`
202
+ - **Checkout Form:** `[fluent_cart_checkout]`
203
+ - **Customer Account Portal:** `[fluent_cart_customer_portal]`
204
+ - **Order Receipt Confirmation:** `[fluent_cart_receipt]`
205
+
206
+ ---
207
+
208
+ ## 8. WP-CLI Command Reference
209
+
210
+ FluentCart includes native WP-CLI commands for database migrations, cache purging, and sync tasks:
211
+
212
+ ```bash
213
+ # Flush FluentCart store cache
214
+ wp fluentcart cache flush
215
+
216
+ # Run pending database schema migrations
217
+ wp fluentcart db migrate
218
+
219
+ # Sync customer order counts & lifetime spend metrics
220
+ wp fluentcart customer recalculate-metrics
221
+
222
+ # Clear expired checkout cart sessions
223
+ wp fluentcart cart cleanup
224
+ ```