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,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
+ ```