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