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,190 +1,190 @@
1
- # Customer Profile API
2
-
3
- Customer-facing frontend REST API endpoints for customer portal dashboards, profile details, order histories, upgrade path choices, transaction billing invoice editing, signed digital downloads, and checkout/profile address books in FluentCart.
4
-
5
- **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
6
- **Policy:** `CustomerFrontendPolicy` (Requires logged-in customer; verifies authenticated WP user matches requested customer record)
7
-
8
- > All monetary values (`ltv`, `total_amount`, `subtotal`, `unit_price`) are in **cents** (`$10.00` = `1000`).
9
-
10
- ---
11
-
12
- ## Endpoints Overview
13
-
14
- | Group | Method | Endpoint | Description |
15
- |-------|--------|----------|-------------|
16
- | **Customer Details** | GET | `/customers/{customerId}` | Get authenticated customer details |
17
- | | PUT | `/customers/{customerId}` | Update authenticated customer profile |
18
- | | GET | `/customers/{customerId}/orders` | Paginated customer order history (customer prefix) |
19
- | **Checkout Addresses** | GET | `/customers/{addressId}/update-address-select` | Select address & apply to active checkout cart (`fct_cart_hash`) |
20
- | | POST | `/customers/add-address` | Create new address during checkout (prefixed fields) |
21
- | | PUT | `/customers/{customerId}/address` | Update address during checkout |
22
- | | DELETE | `/customers/{customerId}/address` | Delete address during checkout |
23
- | | POST | `/customers/{customerId}/address/make-primary` | Set primary billing or shipping address |
24
- | **Portal Overview** | GET | `/customer-profile/` | Portal dashboard overview (recent 5 orders & UI section hooks) |
25
- | | GET | `/customer-profile/profile` | Get customer profile & saved billing/shipping address books |
26
- | | POST | `/customer-profile/update` | Update name, email, or change password |
27
- | **Portal Addresses** | POST | `/customer-profile/create-address` | Add new address from portal profile |
28
- | | POST | `/customer-profile/edit-address` | Edit address from portal profile |
29
- | | POST | `/customer-profile/make-primary-address` | Set primary address from portal profile |
30
- | | POST | `/customer-profile/delete-address` | Delete address (Guards against primary or last address) |
31
- | **Portal Orders** | GET | `/customer-profile/orders` | Paginated customer orders (excludes child subscription renewals) |
32
- | | GET | `/customer-profile/orders/{order_uuid}` | Get full order details, items, transactions, & downloads |
33
- | | GET | `/customer-profile/orders/{order_uuid}/upgrade-paths` | Get plan upgrade/downgrade variation choices & prorations |
34
- | | GET | `/customer-profile/orders/{transaction_uuid}/billing-address` | Get transaction billing address for invoice editing |
35
- | | PUT | `/customer-profile/orders/{transaction_uuid}/billing-address` | Save transaction billing address & VAT/Tax ID |
36
- | **Downloads** | GET | `/customer-profile/downloads` | List downloadable files with time-limited signed token links |
37
-
38
- ---
39
-
40
- ## Customer Details & Checkout Addresses
41
-
42
- ### Get & Update Customer Details
43
-
44
- - `GET /fluent-cart/v2/customers/{customerId}?with[]=billing_address`
45
- - `PUT /fluent-cart/v2/customers/{customerId}` — Updates `email`, `first_name`, `last_name`, `full_name`, `city`, `state`, `postcode`, `country`.
46
-
47
- ---
48
-
49
- ### Checkout Address Management
50
-
51
- - `GET /fluent-cart/v2/customers/{customerAddressId}/update-address-select?fct_cart_hash={hash}` — Select address for active cart. Returns updated checkout summary HTML fragments.
52
- - `POST /fluent-cart/v2/customers/add-address` — Add address during checkout. Fields use type prefix (`billing_address_1`, `shipping_city`, etc.).
53
- - `PUT /fluent-cart/v2/customers/{customerId}/address` — Update checkout address (`address.id`).
54
- - `DELETE /fluent-cart/v2/customers/{customerId}/address` — Delete checkout address (`address.id`).
55
- - `POST /fluent-cart/v2/customers/{customerId}/address/make-primary` — Set primary address (`address.id`, `address.type`).
56
-
57
- ---
58
-
59
- ## Customer Portal Management
60
-
61
- ### Dashboard & Profile Overview
62
-
63
- `GET /fluent-cart/v2/customer-profile/`
64
-
65
- Returns customer dashboard overview with the 5 most recent orders and extension hook sections (`sections_parts`).
66
-
67
- ```json
68
- {
69
- "message": "Success",
70
- "dashboard_data": {
71
- "orders": [
72
- {
73
- "created_at": "2025-06-15 10:30:00",
74
- "invoice_no": "INV-000101",
75
- "total_amount": 4999,
76
- "uuid": "abc-123-def",
77
- "type": "one-time",
78
- "status": "completed"
79
- }
80
- ]
81
- },
82
- "sections_parts": { "before_orders_table": "", "after_orders_table": "" }
83
- }
84
- ```
85
-
86
- ---
87
-
88
- ### Update Profile & Password
89
-
90
- `POST /fluent-cart/v2/customer-profile/update`
91
-
92
- Updates customer details and associated WordPress user name/password.
93
-
94
- #### Parameters
95
-
96
- | Parameter | Type | Required | Description |
97
- |-----------|------|----------|-------------|
98
- | `first_name` | string | No | Customer first name |
99
- | `last_name` | string | No | Customer last name |
100
- | `email` | string | Yes | Valid email address |
101
- | `current_password` | string | No | Required for password change |
102
- | `new_password` | string | No | New password string |
103
- | `confirm_new_password` | string | No | Confirm new password |
104
-
105
- ---
106
-
107
- ### Portal Address Management
108
-
109
- - `POST /customer-profile/create-address` — Add portal address (`type`, `name`, `label`, `address_1`, `city`, `state`, `postcode`, `country`, `is_primary`).
110
- - `POST /customer-profile/edit-address` — Edit portal address (`id`, `type`, `name`, `address_1`, etc.).
111
- - `POST /customer-profile/make-primary-address` — Set primary address (`addressId`, `type`).
112
- - `POST /customer-profile/delete-address` — Delete address (`addressId`).
113
-
114
- > **Delete Guards:**
115
- > - Primary addresses cannot be deleted (`"Primary address cannot be deleted!"`).
116
- > - At least one address must remain (`"At least one address must remain. Address deletion failed!"`).
117
-
118
- ---
119
-
120
- ## Customer Orders & Upgrades
121
-
122
- ### List & View Customer Orders
123
-
124
- `GET /fluent-cart/v2/customer-profile/orders`
125
-
126
- List orders (paginated, excludes child renewal orders, supports `search`).
127
-
128
- `GET /fluent-cart/v2/customer-profile/orders/{order_uuid}`
129
-
130
- Retrieve full order details including line items, transactions, subscriptions, and download links.
131
-
132
- > **Renewal Order Redirect:** If `order_uuid` belongs to a renewal order, returns:
133
- > `{ "message": "This is a renewal order. Please check the parent order details.", "parent_order": { "uuid": "parent-abc-123" } }`
134
-
135
- ---
136
-
137
- ### Plan Upgrade Paths
138
-
139
- `GET /fluent-cart/v2/customer-profile/orders/{order_uuid}/upgrade-paths?variation_id={id}`
140
-
141
- Returns available plan upgrade/downgrade options and prorated price calculation.
142
-
143
- ```json
144
- {
145
- "upgradePaths": [
146
- {
147
- "variation_id": 15,
148
- "title": "Premium Plugin - 5 Sites",
149
- "price": 9999,
150
- "billing_interval": "year",
151
- "upgrade_type": "upgrade",
152
- "prorated_amount": 5000
153
- }
154
- ]
155
- }
156
- ```
157
-
158
- ---
159
-
160
- ### Transaction Billing Address & Invoice Editing
161
-
162
- `GET /fluent-cart/v2/customer-profile/orders/{transaction_uuid}/billing-address`
163
- `PUT /fluent-cart/v2/customer-profile/orders/{transaction_uuid}/billing-address`
164
-
165
- Retrieve or update billing address details and `vat_tax_id` for invoice generation.
166
-
167
- ---
168
-
169
- ## Digital Product Downloads
170
-
171
- `GET /fluent-cart/v2/customer-profile/downloads`
172
-
173
- Retrieve downloadable files for completed orders. `download_url` contains time-limited signed tokens generated via `Helper::generateDownloadFileLink()`.
174
-
175
- ```json
176
- {
177
- "message": "Success",
178
- "downloads": {
179
- "data": [
180
- {
181
- "file_size": "2.5 MB",
182
- "title": "premium-plugin-v2.0.1.zip",
183
- "download_url": "https://example.com/?fct_download=eyJ0eXAi..."
184
- }
185
- ],
186
- "total": 1,
187
- "per_page": 10
188
- }
189
- }
190
- ```
1
+ # Customer Profile API
2
+
3
+ Customer-facing frontend REST API endpoints for customer portal dashboards, profile details, order histories, upgrade path choices, transaction billing invoice editing, signed digital downloads, and checkout/profile address books in FluentCart.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
6
+ **Policy:** `CustomerFrontendPolicy` (Requires logged-in customer; verifies authenticated WP user matches requested customer record)
7
+
8
+ > All monetary values (`ltv`, `total_amount`, `subtotal`, `unit_price`) are in **cents** (`$10.00` = `1000`).
9
+
10
+ ---
11
+
12
+ ## Endpoints Overview
13
+
14
+ | Group | Method | Endpoint | Description |
15
+ |-------|--------|----------|-------------|
16
+ | **Customer Details** | GET | `/customers/{customerId}` | Get authenticated customer details |
17
+ | | PUT | `/customers/{customerId}` | Update authenticated customer profile |
18
+ | | GET | `/customers/{customerId}/orders` | Paginated customer order history (customer prefix) |
19
+ | **Checkout Addresses** | GET | `/customers/{addressId}/update-address-select` | Select address & apply to active checkout cart (`fct_cart_hash`) |
20
+ | | POST | `/customers/add-address` | Create new address during checkout (prefixed fields) |
21
+ | | PUT | `/customers/{customerId}/address` | Update address during checkout |
22
+ | | DELETE | `/customers/{customerId}/address` | Delete address during checkout |
23
+ | | POST | `/customers/{customerId}/address/make-primary` | Set primary billing or shipping address |
24
+ | **Portal Overview** | GET | `/customer-profile/` | Portal dashboard overview (recent 5 orders & UI section hooks) |
25
+ | | GET | `/customer-profile/profile` | Get customer profile & saved billing/shipping address books |
26
+ | | POST | `/customer-profile/update` | Update name, email, or change password |
27
+ | **Portal Addresses** | POST | `/customer-profile/create-address` | Add new address from portal profile |
28
+ | | POST | `/customer-profile/edit-address` | Edit address from portal profile |
29
+ | | POST | `/customer-profile/make-primary-address` | Set primary address from portal profile |
30
+ | | POST | `/customer-profile/delete-address` | Delete address (Guards against primary or last address) |
31
+ | **Portal Orders** | GET | `/customer-profile/orders` | Paginated customer orders (excludes child subscription renewals) |
32
+ | | GET | `/customer-profile/orders/{order_uuid}` | Get full order details, items, transactions, & downloads |
33
+ | | GET | `/customer-profile/orders/{order_uuid}/upgrade-paths` | Get plan upgrade/downgrade variation choices & prorations |
34
+ | | GET | `/customer-profile/orders/{transaction_uuid}/billing-address` | Get transaction billing address for invoice editing |
35
+ | | PUT | `/customer-profile/orders/{transaction_uuid}/billing-address` | Save transaction billing address & VAT/Tax ID |
36
+ | **Downloads** | GET | `/customer-profile/downloads` | List downloadable files with time-limited signed token links |
37
+
38
+ ---
39
+
40
+ ## Customer Details & Checkout Addresses
41
+
42
+ ### Get & Update Customer Details
43
+
44
+ - `GET /fluent-cart/v2/customers/{customerId}?with[]=billing_address`
45
+ - `PUT /fluent-cart/v2/customers/{customerId}` — Updates `email`, `first_name`, `last_name`, `full_name`, `city`, `state`, `postcode`, `country`.
46
+
47
+ ---
48
+
49
+ ### Checkout Address Management
50
+
51
+ - `GET /fluent-cart/v2/customers/{customerAddressId}/update-address-select?fct_cart_hash={hash}` — Select address for active cart. Returns updated checkout summary HTML fragments.
52
+ - `POST /fluent-cart/v2/customers/add-address` — Add address during checkout. Fields use type prefix (`billing_address_1`, `shipping_city`, etc.).
53
+ - `PUT /fluent-cart/v2/customers/{customerId}/address` — Update checkout address (`address.id`).
54
+ - `DELETE /fluent-cart/v2/customers/{customerId}/address` — Delete checkout address (`address.id`).
55
+ - `POST /fluent-cart/v2/customers/{customerId}/address/make-primary` — Set primary address (`address.id`, `address.type`).
56
+
57
+ ---
58
+
59
+ ## Customer Portal Management
60
+
61
+ ### Dashboard & Profile Overview
62
+
63
+ `GET /fluent-cart/v2/customer-profile/`
64
+
65
+ Returns customer dashboard overview with the 5 most recent orders and extension hook sections (`sections_parts`).
66
+
67
+ ```json
68
+ {
69
+ "message": "Success",
70
+ "dashboard_data": {
71
+ "orders": [
72
+ {
73
+ "created_at": "2025-06-15 10:30:00",
74
+ "invoice_no": "INV-000101",
75
+ "total_amount": 4999,
76
+ "uuid": "abc-123-def",
77
+ "type": "one-time",
78
+ "status": "completed"
79
+ }
80
+ ]
81
+ },
82
+ "sections_parts": { "before_orders_table": "", "after_orders_table": "" }
83
+ }
84
+ ```
85
+
86
+ ---
87
+
88
+ ### Update Profile & Password
89
+
90
+ `POST /fluent-cart/v2/customer-profile/update`
91
+
92
+ Updates customer details and associated WordPress user name/password.
93
+
94
+ #### Parameters
95
+
96
+ | Parameter | Type | Required | Description |
97
+ |-----------|------|----------|-------------|
98
+ | `first_name` | string | No | Customer first name |
99
+ | `last_name` | string | No | Customer last name |
100
+ | `email` | string | Yes | Valid email address |
101
+ | `current_password` | string | No | Required for password change |
102
+ | `new_password` | string | No | New password string |
103
+ | `confirm_new_password` | string | No | Confirm new password |
104
+
105
+ ---
106
+
107
+ ### Portal Address Management
108
+
109
+ - `POST /customer-profile/create-address` — Add portal address (`type`, `name`, `label`, `address_1`, `city`, `state`, `postcode`, `country`, `is_primary`).
110
+ - `POST /customer-profile/edit-address` — Edit portal address (`id`, `type`, `name`, `address_1`, etc.).
111
+ - `POST /customer-profile/make-primary-address` — Set primary address (`addressId`, `type`).
112
+ - `POST /customer-profile/delete-address` — Delete address (`addressId`).
113
+
114
+ > **Delete Guards:**
115
+ > - Primary addresses cannot be deleted (`"Primary address cannot be deleted!"`).
116
+ > - At least one address must remain (`"At least one address must remain. Address deletion failed!"`).
117
+
118
+ ---
119
+
120
+ ## Customer Orders & Upgrades
121
+
122
+ ### List & View Customer Orders
123
+
124
+ `GET /fluent-cart/v2/customer-profile/orders`
125
+
126
+ List orders (paginated, excludes child renewal orders, supports `search`).
127
+
128
+ `GET /fluent-cart/v2/customer-profile/orders/{order_uuid}`
129
+
130
+ Retrieve full order details including line items, transactions, subscriptions, and download links.
131
+
132
+ > **Renewal Order Redirect:** If `order_uuid` belongs to a renewal order, returns:
133
+ > `{ "message": "This is a renewal order. Please check the parent order details.", "parent_order": { "uuid": "parent-abc-123" } }`
134
+
135
+ ---
136
+
137
+ ### Plan Upgrade Paths
138
+
139
+ `GET /fluent-cart/v2/customer-profile/orders/{order_uuid}/upgrade-paths?variation_id={id}`
140
+
141
+ Returns available plan upgrade/downgrade options and prorated price calculation.
142
+
143
+ ```json
144
+ {
145
+ "upgradePaths": [
146
+ {
147
+ "variation_id": 15,
148
+ "title": "Premium Plugin - 5 Sites",
149
+ "price": 9999,
150
+ "billing_interval": "year",
151
+ "upgrade_type": "upgrade",
152
+ "prorated_amount": 5000
153
+ }
154
+ ]
155
+ }
156
+ ```
157
+
158
+ ---
159
+
160
+ ### Transaction Billing Address & Invoice Editing
161
+
162
+ `GET /fluent-cart/v2/customer-profile/orders/{transaction_uuid}/billing-address`
163
+ `PUT /fluent-cart/v2/customer-profile/orders/{transaction_uuid}/billing-address`
164
+
165
+ Retrieve or update billing address details and `vat_tax_id` for invoice generation.
166
+
167
+ ---
168
+
169
+ ## Digital Product Downloads
170
+
171
+ `GET /fluent-cart/v2/customer-profile/downloads`
172
+
173
+ Retrieve downloadable files for completed orders. `download_url` contains time-limited signed tokens generated via `Helper::generateDownloadFileLink()`.
174
+
175
+ ```json
176
+ {
177
+ "message": "Success",
178
+ "downloads": {
179
+ "data": [
180
+ {
181
+ "file_size": "2.5 MB",
182
+ "title": "premium-plugin-v2.0.1.zip",
183
+ "download_url": "https://example.com/?fct_download=eyJ0eXAi..."
184
+ }
185
+ ],
186
+ "total": 1,
187
+ "per_page": 10
188
+ }
189
+ }
190
+ ```