fluentcart-developer 1.1.0

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 (66) hide show
  1. package/.gitattributes +2 -0
  2. package/CLAUDE.md +22 -0
  3. package/CONTRIBUTING.md +73 -0
  4. package/LICENSE +21 -0
  5. package/README.md +127 -0
  6. package/SKILL.md +127 -0
  7. package/bin/index.js +281 -0
  8. package/copy-skills.js +43 -0
  9. package/package.json +38 -0
  10. package/skills/fluentcart-developer/SKILL.md +172 -0
  11. package/skills/fluentcart-developer/examples/README.md +25 -0
  12. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/fluent-cart/checkout.php +32 -0
  13. package/skills/fluentcart-developer/examples/fluentcart-starter-child-theme/functions.php +40 -0
  14. package/skills/fluentcart-developer/examples/sample-custom-addon/fluentcart-custom-addon.php +114 -0
  15. package/skills/fluentcart-developer/examples/sample-custom-payment-gateway/fluentcart-custom-gateway-example.php +149 -0
  16. package/skills/fluentcart-developer/examples/sample-fee-surcharge-plugin/fluentcart-fee-surcharge.php +38 -0
  17. package/skills/fluentcart-developer/examples/sample-shipping-carrier/fluentcart-custom-shipping-carrier.php +62 -0
  18. package/skills/fluentcart-developer/references/action-hooks-admin-templates.md +787 -0
  19. package/skills/fluentcart-developer/references/action-hooks-cart-checkout.md +1355 -0
  20. package/skills/fluentcart-developer/references/action-hooks-customers-users.md +266 -0
  21. package/skills/fluentcart-developer/references/action-hooks-licenses.md +855 -0
  22. package/skills/fluentcart-developer/references/action-hooks-orders.md +631 -0
  23. package/skills/fluentcart-developer/references/action-hooks-payments-integrations.md +963 -0
  24. package/skills/fluentcart-developer/references/action-hooks-products-coupons.md +585 -0
  25. package/skills/fluentcart-developer/references/action-hooks-subscriptions.md +661 -0
  26. package/skills/fluentcart-developer/references/database-models-query-builder.md +194 -0
  27. package/skills/fluentcart-developer/references/database-models-reference.md +604 -0
  28. package/skills/fluentcart-developer/references/database-schema-reference.md +940 -0
  29. package/skills/fluentcart-developer/references/engineering-notes.md +154 -0
  30. package/skills/fluentcart-developer/references/fee-system-guide.md +449 -0
  31. package/skills/fluentcart-developer/references/filter-hooks-cart-checkout.md +1202 -0
  32. package/skills/fluentcart-developer/references/filter-hooks-customers-subscriptions.md +902 -0
  33. package/skills/fluentcart-developer/references/filter-hooks-integrations-advanced.md +1598 -0
  34. package/skills/fluentcart-developer/references/filter-hooks-orders-payments.md +1319 -0
  35. package/skills/fluentcart-developer/references/filter-hooks-products-pricing.md +628 -0
  36. package/skills/fluentcart-developer/references/filter-hooks-settings-configuration.md +1177 -0
  37. package/skills/fluentcart-developer/references/fluentcart-developer-guide.md +154 -0
  38. package/skills/fluentcart-developer/references/ghost-product-selling.md +458 -0
  39. package/skills/fluentcart-developer/references/modules-and-extensions-reference.md +224 -0
  40. package/skills/fluentcart-developer/references/paddle-gateway-case-study.md +1925 -0
  41. package/skills/fluentcart-developer/references/payment-gateway-integration.md +761 -0
  42. package/skills/fluentcart-developer/references/rest-api-checkout.md +286 -0
  43. package/skills/fluentcart-developer/references/rest-api-coupons.md +794 -0
  44. package/skills/fluentcart-developer/references/rest-api-customer-profile.md +190 -0
  45. package/skills/fluentcart-developer/references/rest-api-customers.md +1121 -0
  46. package/skills/fluentcart-developer/references/rest-api-dashboard-utilities.md +219 -0
  47. package/skills/fluentcart-developer/references/rest-api-email-notifications.md +619 -0
  48. package/skills/fluentcart-developer/references/rest-api-files.md +290 -0
  49. package/skills/fluentcart-developer/references/rest-api-integrations.md +324 -0
  50. package/skills/fluentcart-developer/references/rest-api-labels-attributes.md +321 -0
  51. package/skills/fluentcart-developer/references/rest-api-licensing.md +171 -0
  52. package/skills/fluentcart-developer/references/rest-api-order-bumps.md +200 -0
  53. package/skills/fluentcart-developer/references/rest-api-orders.md +1241 -0
  54. package/skills/fluentcart-developer/references/rest-api-overview.md +131 -0
  55. package/skills/fluentcart-developer/references/rest-api-products.md +2563 -0
  56. package/skills/fluentcart-developer/references/rest-api-public-shop.md +172 -0
  57. package/skills/fluentcart-developer/references/rest-api-reference.md +552 -0
  58. package/skills/fluentcart-developer/references/rest-api-reports.md +377 -0
  59. package/skills/fluentcart-developer/references/rest-api-roles-permissions.md +147 -0
  60. package/skills/fluentcart-developer/references/rest-api-settings.md +528 -0
  61. package/skills/fluentcart-developer/references/rest-api-shipping.md +800 -0
  62. package/skills/fluentcart-developer/references/rest-api-subscriptions.md +606 -0
  63. package/skills/fluentcart-developer/references/rest-api-tax.md +356 -0
  64. package/skills/fluentcart-developer/references/subscription-customization.md +197 -0
  65. package/skills/fluentcart-developer/scripts/cli.js +1 -0
  66. package/skills.sh.json +13 -0
@@ -0,0 +1,286 @@
1
+ # Checkout API
2
+
3
+ Public storefront checkout endpoints for submitting orders, calculating cart summaries, loading payment gateway UI configurations, querying shipping method availability, and authenticating users.
4
+
5
+ **Base URLs:**
6
+ - Checkout: `https://your-site.com/wp-json/fluent-cart/v2/checkout`
7
+ - User Login: `https://your-site.com/wp-json/fluent-cart/v2/user/login`
8
+
9
+ **Policy:** `PublicPolicy` (No authentication required for most endpoints)
10
+
11
+ > All monetary values (shipping charges, unformatted totals) are in **cents** (`$10.00` = `1000`).
12
+
13
+ ---
14
+
15
+ ## Endpoints Overview
16
+
17
+ | Group | Method | Endpoint | Auth / Headers | Description |
18
+ |-------|--------|----------|----------------|-------------|
19
+ | **Checkout** | POST | `/checkout/place-order` | Optional | Submit order, validate cart, & initiate payment (Rate limit: 5 req/60s) |
20
+ | | GET | `/checkout/get-order-info` | Optional | Get gateway-specific payment UI init config (Stripe Elements, PayPal) |
21
+ | | GET | `/checkout/get-checkout-summary-view` | Session/Cookie | Retrieve cart HTML view & totals for selected shipping method |
22
+ | | GET | `/checkout/get-available-shipping-methods` | Public | List shipping methods for timezone or country/state |
23
+ | | GET | `/checkout/get-shipping-methods-list-view` | Public | Get server-rendered HTML list of shipping methods |
24
+ | | GET | `/checkout/get-country-info` | Public | Get country states & localized address field rules |
25
+ | **Authentication** | POST | `/user/login` | `X-WP-Nonce` Header | Authenticate user during checkout & set WP auth cookie |
26
+
27
+ ---
28
+
29
+ ## Checkout Endpoints
30
+
31
+ ### 1. Place Order
32
+
33
+ `POST /fluent-cart/v2/checkout/place-order`
34
+
35
+ Validates cart, registers/matches customer, creates draft order, and dispatches to selected payment gateway.
36
+
37
+ > **Rate Limit:** 5 requests per 60 seconds per IP/User.
38
+
39
+ #### Body Parameters
40
+
41
+ | Parameter | Type | Required | Description |
42
+ |-----------|------|----------|-------------|
43
+ | `billing_email` | string | Yes | Customer email address (auto-populated for logged-in users) |
44
+ | `billing_full_name` | string | Conditional | Full name (required if store uses full name mode) |
45
+ | `billing_first_name` | string | Conditional | First name (required if store uses separate name mode) |
46
+ | `billing_last_name` | string | Conditional | Last name (required if separate name mode & required field) |
47
+ | `billing_country` | string | Conditional | ISO country code (e.g. `US`, `GB`). Defaults to store country |
48
+ | `billing_address_1` | string | Conditional | Street address line 1 |
49
+ | `billing_address_2` | string | No | Street address line 2 (apt, suite, unit) |
50
+ | `billing_city` | string | Conditional | City name |
51
+ | `billing_state` | string | Conditional | State/province code (required if country has states) |
52
+ | `billing_postcode` | string | Conditional | Postal/ZIP code |
53
+ | `billing_phone` | string | No | Customer phone number |
54
+ | `billing_tax_id` | string | No | Tax ID / VAT registration number |
55
+ | `billing_address_id` | integer | No | Saved customer billing address ID |
56
+ | `ship_to_different` | string | No | `yes` to specify separate shipping address. Default: `no` |
57
+ | `shipping_full_name` | string | Conditional | Shipping recipient name (required when `ship_to_different` is `yes`) |
58
+ | `shipping_country` | string | Conditional | Shipping country code (required when `ship_to_different` is `yes`) |
59
+ | `shipping_address_1` | string | Conditional | Shipping street address |
60
+ | `shipping_address_2` | string | No | Shipping address line 2 |
61
+ | `shipping_city` | string | Conditional | Shipping city |
62
+ | `shipping_state` | string | Conditional | Shipping state/province code |
63
+ | `shipping_postcode` | string | Conditional | Shipping postal code |
64
+ | `shipping_phone` | string | No | Shipping phone number |
65
+ | `shipping_address_id` | integer | No | Saved customer shipping address ID |
66
+ | `fc_selected_shipping_method` | integer | Conditional | Shipping method ID (required for physical items) |
67
+ | `payment_method` | string | Yes | Payment gateway slug (e.g., `stripe`, `paypal`, `cod`, `square`) |
68
+ | `order_notes` | string | No | Customer order notes (max 200 chars) |
69
+ | `agree_terms` | string | Conditional | Terms agreement flag (required if store setting enabled) |
70
+ | `allow_create_account` | string | No | `yes` to register WP user account (when store mode is `user_choice`) |
71
+ | `user_tz` | string | No | Customer IANA timezone string (default: `UTC`) |
72
+
73
+ #### Responses
74
+
75
+ ##### Redirect-Based Gateways (PayPal, Hosted Stripe)
76
+
77
+ ```json
78
+ {
79
+ "status": "success",
80
+ "redirect_url": "https://checkout.stripe.com/pay/cs_...",
81
+ "message": "Order placed successfully"
82
+ }
83
+ ```
84
+
85
+ ##### On-Site Gateways (Stripe Elements)
86
+
87
+ ```json
88
+ {
89
+ "status": "success",
90
+ "payment_args": {
91
+ "client_secret": "pi_..._secret_...",
92
+ "checkout_mode": "onsite"
93
+ },
94
+ "order_id": 42,
95
+ "message": "Order placed successfully"
96
+ }
97
+ ```
98
+
99
+ ##### Free / COD Orders
100
+
101
+ ```json
102
+ {
103
+ "status": "success",
104
+ "redirect_url": "https://your-site.com/checkout/order-received/?order=abc123",
105
+ "message": "Order placed successfully"
106
+ }
107
+ ```
108
+
109
+ #### Example
110
+
111
+ ```bash
112
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/checkout/place-order" \
113
+ -H "Content-Type: application/json" \
114
+ -H "X-WP-Nonce: your_nonce_here" \
115
+ -d '{
116
+ "billing_email": "john@example.com",
117
+ "billing_full_name": "John Doe",
118
+ "billing_country": "US",
119
+ "billing_address_1": "123 Main St",
120
+ "billing_city": "New York",
121
+ "billing_state": "NY",
122
+ "billing_postcode": "10001",
123
+ "payment_method": "stripe",
124
+ "user_tz": "America/New_York"
125
+ }'
126
+ ```
127
+
128
+ ---
129
+
130
+ ### 2. Get Order Info
131
+
132
+ `GET /fluent-cart/v2/checkout/get-order-info`
133
+
134
+ Retrieve payment-gateway-specific setup parameters for frontend payment form initialization.
135
+
136
+ #### Parameters
137
+
138
+ | Parameter | Type | Location | Required | Description |
139
+ |-----------|------|----------|----------|-------------|
140
+ | `method` | string | query | Yes | Gateway slug (e.g. `stripe`, `paypal`, `square`, `airwallex`) |
141
+
142
+ #### Response Example (Stripe On-Site)
143
+
144
+ ```json
145
+ {
146
+ "status": "success",
147
+ "message": "Order info retrieved!",
148
+ "data": {
149
+ "client_secret": "seti_..._secret_...",
150
+ "publishable_key": "pk_live_..."
151
+ },
152
+ "payment_args": {
153
+ "checkout_mode": "onsite",
154
+ "appearance": { "theme": "stripe" }
155
+ }
156
+ }
157
+ ```
158
+
159
+ ---
160
+
161
+ ### 3. Get Checkout Summary
162
+
163
+ `GET /fluent-cart/v2/checkout/get-checkout-summary-view`
164
+
165
+ Retrieve server-rendered HTML item summary and updated pricing totals when changing shipping methods or options.
166
+
167
+ #### Parameters
168
+
169
+ | Parameter | Type | Location | Required | Description |
170
+ |-----------|------|----------|----------|-------------|
171
+ | `shipping_method_id` | integer | query | No | ID of selected shipping method |
172
+
173
+ #### Response
174
+
175
+ ```json
176
+ {
177
+ "items": {
178
+ "views": "<div class=\"fct-checkout-items\">...rendered HTML...</div>",
179
+ "subtotal": "$50.00",
180
+ "has_subscriptions": false,
181
+ "shipping_charge": 500,
182
+ "unformatted_total": 5500,
183
+ "total": "$55.00",
184
+ "shipping_charge_formated": "$5.00",
185
+ "shipping_method_id": "3"
186
+ }
187
+ }
188
+ ```
189
+
190
+ ---
191
+
192
+ ### 4. Available Shipping Methods Endpoints
193
+
194
+ - `GET /fluent-cart/v2/checkout/get-available-shipping-methods` — Returns JSON list of methods (`timezone` or `country_code`, `state`).
195
+ - `GET /fluent-cart/v2/checkout/get-shipping-methods-list-view` — Returns pre-rendered HTML list (`view`) for direct insertion into checkout UI.
196
+
197
+ #### Response
198
+
199
+ ```json
200
+ {
201
+ "available_shipping_methods": [
202
+ {
203
+ "id": 1,
204
+ "title": "Standard Shipping",
205
+ "charge_type": "flat_rate",
206
+ "charge_amount": 500,
207
+ "status": "active",
208
+ "countries": ["US", "CA"],
209
+ "states": []
210
+ }
211
+ ],
212
+ "country_code": "US"
213
+ }
214
+ ```
215
+
216
+ ---
217
+
218
+ ### 5. Get Country Info
219
+
220
+ `GET /fluent-cart/v2/checkout/get-country-info`
221
+
222
+ Retrieve localization details for a country (`data.country_code`, `data.states` array, and localized `data.address_locale` field requirements).
223
+
224
+ #### Response
225
+
226
+ ```json
227
+ {
228
+ "data": {
229
+ "country_code": "US",
230
+ "states": [
231
+ { "label": "California", "value": "CA" },
232
+ { "label": "New York", "value": "NY" }
233
+ ],
234
+ "address_locale": {
235
+ "state": { "label": "State", "required": true },
236
+ "postcode": { "label": "ZIP Code", "required": true },
237
+ "city": { "label": "City", "required": true }
238
+ }
239
+ }
240
+ }
241
+ ```
242
+
243
+ ---
244
+
245
+ ## User Authentication
246
+
247
+ ### Customer Login
248
+
249
+ `POST /fluent-cart/v2/user/login`
250
+
251
+ Authenticates WordPress user during checkout and sets authentication cookies.
252
+
253
+ > **Header Required:** `X-WP-Nonce` header is required to prevent CSRF attacks.
254
+
255
+ #### Parameters
256
+
257
+ | Parameter | Type | Location | Required | Description |
258
+ |-----------|------|----------|----------|-------------|
259
+ | `user_login` | string | body | Yes | WordPress username or email address |
260
+ | `password` | string | body | Yes | Account password |
261
+ | `remember_me` | string | body | No | `on` to persist login session |
262
+
263
+ #### Response
264
+
265
+ ```json
266
+ {
267
+ "success": true,
268
+ "data": {
269
+ "message": "Login successful",
270
+ "redirect_url": "https://your-site.com/customer-profile/#/profile"
271
+ }
272
+ }
273
+ ```
274
+
275
+ #### Example
276
+
277
+ ```bash
278
+ curl -X POST "https://example.com/wp-json/fluent-cart/v2/user/login" \
279
+ -H "Content-Type: application/json" \
280
+ -H "X-WP-Nonce: your_nonce_here" \
281
+ -d '{
282
+ "user_login": "john@example.com",
283
+ "password": "securepassword123",
284
+ "remember_me": "on"
285
+ }'
286
+ ```