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,200 +1,200 @@
1
- # Order Bumps API (Pro)
2
-
3
- Create and manage checkout order bump promotions in FluentCart Pro to offer relevant add-ons or discounted upsell products directly on the checkout form.
4
-
5
- **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/order_bump`
6
- **Policy:** `OrderBumpPolicy` | **Permission:** `store/sensitive` (Requires FluentCart Pro)
7
-
8
- > All monetary values (e.g., fixed discount amounts, product prices) are in integer **cents** (`$10.00` = `1000`).
9
-
10
- ---
11
-
12
- ## Endpoints Overview
13
-
14
- | Method | Endpoint | Permission | Description |
15
- |--------|----------|------------|-------------|
16
- | GET | `/order_bump` | `store/sensitive` | List order bumps with tab filters (`active`, `draft`) |
17
- | POST | `/order_bump` | `store/sensitive` | Create a new order bump offer (minimal initial payload) |
18
- | GET | `/order_bump/{id}` | `store/sensitive` | Retrieve order bump details, config, & product variant |
19
- | PUT | `/order_bump/{id}` | `store/sensitive` | Update configuration, conditions, status, & priority |
20
- | DELETE | `/order_bump/{id}` | `store/sensitive` | Permanently delete an order bump promotion |
21
-
22
- ---
23
-
24
- ## Endpoints Specification
25
-
26
- ### 1. List Order Bumps
27
-
28
- `GET /fluent-cart/v2/order_bump`
29
-
30
- Retrieve a paginated list of order bumps. Each entry eagerly loads its associated `product_variant` and parent `product`.
31
-
32
- #### Parameters
33
-
34
- | Parameter | Type | Required | Description |
35
- |-----------|------|----------|-------------|
36
- | `active_view` | string | No | Filter by tab: `active` or `draft` |
37
- | `search` | string | No | Partial title or description search |
38
- | `sort_by` | string | No | Sort column (default: `id`) |
39
- | `sort_type` | string | No | `asc` or `desc` (default: `desc`) |
40
- | `page` | integer | No | Page number |
41
- | `per_page` | integer | No | Items per page |
42
-
43
- #### Response
44
-
45
- ```json
46
- {
47
- "order_bumps": {
48
- "total": 5,
49
- "per_page": 15,
50
- "current_page": 1,
51
- "last_page": 1,
52
- "data": [
53
- {
54
- "id": 1,
55
- "hash": "a1b2c3d4e5f6...",
56
- "type": "order_bump",
57
- "status": "active",
58
- "src_object_id": 42,
59
- "title": "Add Extended Warranty",
60
- "description": "<p>Protect your purchase with our 2-year warranty plan.</p>",
61
- "conditions": [],
62
- "config": {
63
- "discount": {
64
- "discount_type": "percentage",
65
- "discount_amount": 10
66
- },
67
- "display_conditions_if": "",
68
- "call_to_action": "Yes, add warranty!"
69
- },
70
- "priority": 1,
71
- "product_variant": {
72
- "id": 42,
73
- "product_id": 10,
74
- "title": "Extended Warranty - 2 Year",
75
- "price": 2999,
76
- "product": { "id": 10, "title": "Extended Warranty", "status": "publish" }
77
- }
78
- }
79
- ]
80
- }
81
- }
82
- ```
83
-
84
- ---
85
-
86
- ### 2. Create Order Bump
87
-
88
- `POST /fluent-cart/v2/order_bump`
89
-
90
- Creates an order bump with initial title and product variation ID.
91
-
92
- #### Parameters
93
-
94
- | Parameter | Type | Required | Description |
95
- |-----------|------|----------|-------------|
96
- | `title` | string | Yes | Display title for the order bump |
97
- | `src_object_id` | integer | Yes | Product variation ID offered in the bump |
98
-
99
- > **Auto-Generated Defaults:** Creates with `type: "order_bump"`, unique MD5 `hash`, empty `conditions: []`, and empty `config: {}`.
100
-
101
- #### Response
102
-
103
- ```json
104
- {
105
- "message": "Order bump created successfully",
106
- "id": 5
107
- }
108
- ```
109
-
110
- ---
111
-
112
- ### 3. Get Single Order Bump
113
-
114
- `GET /fluent-cart/v2/order_bump/{id}`
115
-
116
- Returns the order bump configuration and its linked product variant.
117
-
118
- #### Default Config Fallback
119
-
120
- If no custom config has been saved yet, returns:
121
-
122
- ```json
123
- {
124
- "discount": {
125
- "discount_type": "percentage",
126
- "discount_amount": 0
127
- },
128
- "display_conditions_if": "",
129
- "call_to_action": ""
130
- }
131
- ```
132
-
133
- ---
134
-
135
- ### 4. Update Order Bump
136
-
137
- `PUT /fluent-cart/v2/order_bump/{id}`
138
-
139
- Update configuration, display conditions, status, and sort priority.
140
-
141
- #### Parameters
142
-
143
- | Parameter | Type | Required | Description |
144
- |-----------|------|----------|-------------|
145
- | `title` | string | Yes | Display title (max 194 chars) |
146
- | `src_object_id` | integer | Yes | Product variation ID for the bump offer |
147
- | `status` | string | No | `active` or `draft` (max 50 chars) |
148
- | `src_object_type` | string | No | Source object type slug (max 50 chars) |
149
- | `description` | string | No | HTML offer description (sanitized with `wp_kses_post`) |
150
- | `config` | object | No | Configuration object (see structure below) |
151
- | `conditions` | array | No | Display rule objects array |
152
- | `priority` | integer | No | Display order (lower numbers display first, min `1`) |
153
-
154
- #### Config Object Structure
155
-
156
- ```json
157
- {
158
- "config": {
159
- "discount": {
160
- "discount_type": "percentage",
161
- "discount_amount": 10
162
- },
163
- "display_conditions_if": "all",
164
- "call_to_action": "Yes, add 2-year warranty to my order!"
165
- }
166
- }
167
- ```
168
-
169
- > **Discount Types:**
170
- > - `percentage`: `discount_amount` is a number from `0` to `100`.
171
- > - `fixed`: `discount_amount` is specified in **cents** (e.g. `500` = `$5.00`).
172
-
173
- ---
174
-
175
- ### 5. Delete Order Bump
176
-
177
- `DELETE /fluent-cart/v2/order_bump/{id}`
178
-
179
- ---
180
-
181
- ## Data Model & Database Schema
182
-
183
- Order bumps are stored in the `fct_order_promotions` table filtered by `type = 'order_bump'`.
184
-
185
- | Column | Data Type | Description |
186
- |--------|-----------|-------------|
187
- | `id` | BIGINT (PK) | Auto-increment primary key |
188
- | `hash` | VARCHAR | Auto-generated unique MD5 hash |
189
- | `parent_id` | BIGINT | Parent promotion ID (nullable) |
190
- | `type` | VARCHAR | Always `order_bump` |
191
- | `status` | VARCHAR | `active` or `draft` |
192
- | `src_object_id` | BIGINT | Product variation ID (`fct_product_variations.id`) |
193
- | `src_object_type` | VARCHAR | Identifier type |
194
- | `title` | VARCHAR | Display title |
195
- | `description` | TEXT | HTML description |
196
- | `conditions` | TEXT (JSON) | JSON array of display rule conditions |
197
- | `config` | TEXT (JSON) | JSON object containing discount & CTA text |
198
- | `priority` | INT | Sort ordering index |
199
- | `created_at` | DATETIME | GMT creation timestamp |
200
- | `updated_at` | DATETIME | GMT update timestamp |
1
+ # Order Bumps API (Pro)
2
+
3
+ Create and manage checkout order bump promotions in FluentCart Pro to offer relevant add-ons or discounted upsell products directly on the checkout form.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/order_bump`
6
+ **Policy:** `OrderBumpPolicy` | **Permission:** `store/sensitive` (Requires FluentCart Pro)
7
+
8
+ > All monetary values (e.g., fixed discount amounts, product prices) are in integer **cents** (`$10.00` = `1000`).
9
+
10
+ ---
11
+
12
+ ## Endpoints Overview
13
+
14
+ | Method | Endpoint | Permission | Description |
15
+ |--------|----------|------------|-------------|
16
+ | GET | `/order_bump` | `store/sensitive` | List order bumps with tab filters (`active`, `draft`) |
17
+ | POST | `/order_bump` | `store/sensitive` | Create a new order bump offer (minimal initial payload) |
18
+ | GET | `/order_bump/{id}` | `store/sensitive` | Retrieve order bump details, config, & product variant |
19
+ | PUT | `/order_bump/{id}` | `store/sensitive` | Update configuration, conditions, status, & priority |
20
+ | DELETE | `/order_bump/{id}` | `store/sensitive` | Permanently delete an order bump promotion |
21
+
22
+ ---
23
+
24
+ ## Endpoints Specification
25
+
26
+ ### 1. List Order Bumps
27
+
28
+ `GET /fluent-cart/v2/order_bump`
29
+
30
+ Retrieve a paginated list of order bumps. Each entry eagerly loads its associated `product_variant` and parent `product`.
31
+
32
+ #### Parameters
33
+
34
+ | Parameter | Type | Required | Description |
35
+ |-----------|------|----------|-------------|
36
+ | `active_view` | string | No | Filter by tab: `active` or `draft` |
37
+ | `search` | string | No | Partial title or description search |
38
+ | `sort_by` | string | No | Sort column (default: `id`) |
39
+ | `sort_type` | string | No | `asc` or `desc` (default: `desc`) |
40
+ | `page` | integer | No | Page number |
41
+ | `per_page` | integer | No | Items per page |
42
+
43
+ #### Response
44
+
45
+ ```json
46
+ {
47
+ "order_bumps": {
48
+ "total": 5,
49
+ "per_page": 15,
50
+ "current_page": 1,
51
+ "last_page": 1,
52
+ "data": [
53
+ {
54
+ "id": 1,
55
+ "hash": "a1b2c3d4e5f6...",
56
+ "type": "order_bump",
57
+ "status": "active",
58
+ "src_object_id": 42,
59
+ "title": "Add Extended Warranty",
60
+ "description": "<p>Protect your purchase with our 2-year warranty plan.</p>",
61
+ "conditions": [],
62
+ "config": {
63
+ "discount": {
64
+ "discount_type": "percentage",
65
+ "discount_amount": 10
66
+ },
67
+ "display_conditions_if": "",
68
+ "call_to_action": "Yes, add warranty!"
69
+ },
70
+ "priority": 1,
71
+ "product_variant": {
72
+ "id": 42,
73
+ "product_id": 10,
74
+ "title": "Extended Warranty - 2 Year",
75
+ "price": 2999,
76
+ "product": { "id": 10, "title": "Extended Warranty", "status": "publish" }
77
+ }
78
+ }
79
+ ]
80
+ }
81
+ }
82
+ ```
83
+
84
+ ---
85
+
86
+ ### 2. Create Order Bump
87
+
88
+ `POST /fluent-cart/v2/order_bump`
89
+
90
+ Creates an order bump with initial title and product variation ID.
91
+
92
+ #### Parameters
93
+
94
+ | Parameter | Type | Required | Description |
95
+ |-----------|------|----------|-------------|
96
+ | `title` | string | Yes | Display title for the order bump |
97
+ | `src_object_id` | integer | Yes | Product variation ID offered in the bump |
98
+
99
+ > **Auto-Generated Defaults:** Creates with `type: "order_bump"`, unique MD5 `hash`, empty `conditions: []`, and empty `config: {}`.
100
+
101
+ #### Response
102
+
103
+ ```json
104
+ {
105
+ "message": "Order bump created successfully",
106
+ "id": 5
107
+ }
108
+ ```
109
+
110
+ ---
111
+
112
+ ### 3. Get Single Order Bump
113
+
114
+ `GET /fluent-cart/v2/order_bump/{id}`
115
+
116
+ Returns the order bump configuration and its linked product variant.
117
+
118
+ #### Default Config Fallback
119
+
120
+ If no custom config has been saved yet, returns:
121
+
122
+ ```json
123
+ {
124
+ "discount": {
125
+ "discount_type": "percentage",
126
+ "discount_amount": 0
127
+ },
128
+ "display_conditions_if": "",
129
+ "call_to_action": ""
130
+ }
131
+ ```
132
+
133
+ ---
134
+
135
+ ### 4. Update Order Bump
136
+
137
+ `PUT /fluent-cart/v2/order_bump/{id}`
138
+
139
+ Update configuration, display conditions, status, and sort priority.
140
+
141
+ #### Parameters
142
+
143
+ | Parameter | Type | Required | Description |
144
+ |-----------|------|----------|-------------|
145
+ | `title` | string | Yes | Display title (max 194 chars) |
146
+ | `src_object_id` | integer | Yes | Product variation ID for the bump offer |
147
+ | `status` | string | No | `active` or `draft` (max 50 chars) |
148
+ | `src_object_type` | string | No | Source object type slug (max 50 chars) |
149
+ | `description` | string | No | HTML offer description (sanitized with `wp_kses_post`) |
150
+ | `config` | object | No | Configuration object (see structure below) |
151
+ | `conditions` | array | No | Display rule objects array |
152
+ | `priority` | integer | No | Display order (lower numbers display first, min `1`) |
153
+
154
+ #### Config Object Structure
155
+
156
+ ```json
157
+ {
158
+ "config": {
159
+ "discount": {
160
+ "discount_type": "percentage",
161
+ "discount_amount": 10
162
+ },
163
+ "display_conditions_if": "all",
164
+ "call_to_action": "Yes, add 2-year warranty to my order!"
165
+ }
166
+ }
167
+ ```
168
+
169
+ > **Discount Types:**
170
+ > - `percentage`: `discount_amount` is a number from `0` to `100`.
171
+ > - `fixed`: `discount_amount` is specified in **cents** (e.g. `500` = `$5.00`).
172
+
173
+ ---
174
+
175
+ ### 5. Delete Order Bump
176
+
177
+ `DELETE /fluent-cart/v2/order_bump/{id}`
178
+
179
+ ---
180
+
181
+ ## Data Model & Database Schema
182
+
183
+ Order bumps are stored in the `fct_order_promotions` table filtered by `type = 'order_bump'`.
184
+
185
+ | Column | Data Type | Description |
186
+ |--------|-----------|-------------|
187
+ | `id` | BIGINT (PK) | Auto-increment primary key |
188
+ | `hash` | VARCHAR | Auto-generated unique MD5 hash |
189
+ | `parent_id` | BIGINT | Parent promotion ID (nullable) |
190
+ | `type` | VARCHAR | Always `order_bump` |
191
+ | `status` | VARCHAR | `active` or `draft` |
192
+ | `src_object_id` | BIGINT | Product variation ID (`fct_product_variations.id`) |
193
+ | `src_object_type` | VARCHAR | Identifier type |
194
+ | `title` | VARCHAR | Display title |
195
+ | `description` | TEXT | HTML description |
196
+ | `conditions` | TEXT (JSON) | JSON array of display rule conditions |
197
+ | `config` | TEXT (JSON) | JSON object containing discount & CTA text |
198
+ | `priority` | INT | Sort ordering index |
199
+ | `created_at` | DATETIME | GMT creation timestamp |
200
+ | `updated_at` | DATETIME | GMT update timestamp |