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,131 +1,131 @@
1
- # FluentCart REST API
2
-
3
- Complete REST API reference for FluentCart and FluentCart Pro. This documentation covers 367+ endpoints organized by module, with full parameter details, response examples, and authentication guides.
4
-
5
- ---
6
-
7
- ## Getting Started
8
-
9
- **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
10
-
11
- All admin endpoints require authentication. Public and customer portal endpoints have different authentication requirements as noted in each module.
12
-
13
- ### Authentication
14
-
15
- **Admin API** — Use WordPress Application Passwords (HTTP Basic Auth):
16
-
17
- 1. Go to WordPress Dashboard → Users → Your Profile
18
- 2. Scroll to Application Passwords section
19
- 3. Create a new application password
20
- 4. Use the credentials with every request:
21
-
22
- ```bash
23
- curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/orders" \
24
- -u "username:application_password"
25
- ```
26
-
27
- **Customer Portal API** — Uses WordPress cookie-based authentication with nonce verification:
28
-
29
- ```bash
30
- curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/customer-profile/" \
31
- -H "X-WP-Nonce: <nonce>" \
32
- --cookie "wordpress_logged_in_xxx=..."
33
- ```
34
-
35
- **Public API** — No authentication required.
36
-
37
- ### Conventions
38
-
39
- - All monetary values are in **cents** (e.g., `$10.00` = `1000`). Use integer arithmetic.
40
- - All timestamps are in **UTC/GMT**.
41
- - Pagination uses `page` and `per_page` parameters (default: `per_page=10`).
42
- - Responses use standard HTTP status codes (`200`, `400`, `403`, `404`, `422`).
43
- - The REST namespace is `fluent-cart/v2`.
44
-
45
- ---
46
-
47
- ## API Modules
48
-
49
- ### Core Resources
50
-
51
- | Module | Endpoints | Description |
52
- |--------|-----------|-------------|
53
- | Orders | 22 | Order CRUD, payments, refunds, shipping, fulfillment, notes, transactions |
54
- | Products | 59 | Product CRUD, variations, attributes, downloadables, pricing, bundles |
55
- | Customers | 18 | Customer CRUD, addresses, WordPress user association, notes |
56
- | Coupons | 12 | Coupon CRUD, validation, usage tracking |
57
- | Subscriptions | 17 | Subscription lifecycle, billing, cancellations, payment method management |
58
-
59
- ### Configuration
60
-
61
- | Module | Endpoints | Description |
62
- |--------|-----------|-------------|
63
- | Tax | 26 | Tax classes, rates, EU VAT, configuration |
64
- | Shipping | 15 | Shipping zones, methods, classes |
65
- | Settings | 30 | Store settings, payment methods, modules, storage, permissions, checkout fields |
66
- | Email Notifications | 11 | Email template management, previews, test sending |
67
-
68
- ### Analytics & Content
69
-
70
- | Module | Endpoints | Description |
71
- |--------|-----------|-------------|
72
- | Reports | 45 | Revenue, orders, sales, refunds, subscriptions, dashboards, retention |
73
- | Integrations | 17 | Add-ons, global feeds, product integration feeds |
74
- | Files | 5 | File uploads, storage management, editor uploads |
75
- | Labels & Attributes | 13 | Product labels, attribute groups, attribute terms |
76
- | Dashboard | 20 | Dashboard stats, onboarding, activity log, print templates, widgets |
77
-
78
- ### Storefront & Checkout
79
-
80
- | Module | Endpoints | Description |
81
- |--------|-----------|-------------|
82
- | Public Shop | 3 | Public product listing, search, server-rendered views |
83
- | Checkout | 7 | Order placement, payment processing, shipping methods, country info |
84
- | Customer Profile | 21 | Customer portal — orders, downloads, addresses, profile management |
85
-
86
- ### Pro Features
87
-
88
- | Module | Endpoints | Description |
89
- |--------|-----------|-------------|
90
- | Licensing | 24 | License management, activations, public license API, WordPress update API |
91
- | Roles & Permissions | 7 | FluentCart role assignment and management |
92
- | Order Bumps | 5 | Order bump CRUD with display conditions |
93
-
94
- ---
95
-
96
- ## Permission System
97
-
98
- FluentCart uses a policy-based authorization system with 32 granular permissions across 4 built-in roles:
99
-
100
- | Role | Description |
101
- |------|-------------|
102
- | `super_admin` | Full access to all features |
103
- | `manager` | Manage orders, customers, products, and settings |
104
- | `worker` | Day-to-day operations — orders, customers, products |
105
- | `accountant` | Read-only access to orders, customers, and reports |
106
-
107
- Each endpoint documents its required permission (e.g., `orders/view`, `products/edit`, `store/sensitive`).
108
-
109
- ---
110
-
111
- ## Error Handling
112
-
113
- All error responses follow a consistent format:
114
-
115
- ```json
116
- {
117
- "message": "Error description",
118
- "errors": {
119
- "field_name": ["Validation error message"]
120
- }
121
- }
122
- ```
123
-
124
- | Status Code | Meaning |
125
- |-------------|---------|
126
- | `200` | Success |
127
- | `400` | Bad Request — validation failed or invalid parameters |
128
- | `403` | Forbidden — insufficient permissions |
129
- | `404` | Not Found — resource does not exist |
130
- | `422` | Unprocessable Entity — business logic error |
131
- | `429` | Too Many Requests — rate limited |
1
+ # FluentCart REST API
2
+
3
+ Complete REST API reference for FluentCart and FluentCart Pro. This documentation covers 367+ endpoints organized by module, with full parameter details, response examples, and authentication guides.
4
+
5
+ ---
6
+
7
+ ## Getting Started
8
+
9
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
10
+
11
+ All admin endpoints require authentication. Public and customer portal endpoints have different authentication requirements as noted in each module.
12
+
13
+ ### Authentication
14
+
15
+ **Admin API** — Use WordPress Application Passwords (HTTP Basic Auth):
16
+
17
+ 1. Go to WordPress Dashboard → Users → Your Profile
18
+ 2. Scroll to Application Passwords section
19
+ 3. Create a new application password
20
+ 4. Use the credentials with every request:
21
+
22
+ ```bash
23
+ curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/orders" \
24
+ -u "username:application_password"
25
+ ```
26
+
27
+ **Customer Portal API** — Uses WordPress cookie-based authentication with nonce verification:
28
+
29
+ ```bash
30
+ curl -X GET "https://your-site.com/wp-json/fluent-cart/v2/customer-profile/" \
31
+ -H "X-WP-Nonce: <nonce>" \
32
+ --cookie "wordpress_logged_in_xxx=..."
33
+ ```
34
+
35
+ **Public API** — No authentication required.
36
+
37
+ ### Conventions
38
+
39
+ - All monetary values are in **cents** (e.g., `$10.00` = `1000`). Use integer arithmetic.
40
+ - All timestamps are in **UTC/GMT**.
41
+ - Pagination uses `page` and `per_page` parameters (default: `per_page=10`).
42
+ - Responses use standard HTTP status codes (`200`, `400`, `403`, `404`, `422`).
43
+ - The REST namespace is `fluent-cart/v2`.
44
+
45
+ ---
46
+
47
+ ## API Modules
48
+
49
+ ### Core Resources
50
+
51
+ | Module | Endpoints | Description |
52
+ |--------|-----------|-------------|
53
+ | Orders | 22 | Order CRUD, payments, refunds, shipping, fulfillment, notes, transactions |
54
+ | Products | 59 | Product CRUD, variations, attributes, downloadables, pricing, bundles |
55
+ | Customers | 18 | Customer CRUD, addresses, WordPress user association, notes |
56
+ | Coupons | 12 | Coupon CRUD, validation, usage tracking |
57
+ | Subscriptions | 17 | Subscription lifecycle, billing, cancellations, payment method management |
58
+
59
+ ### Configuration
60
+
61
+ | Module | Endpoints | Description |
62
+ |--------|-----------|-------------|
63
+ | Tax | 26 | Tax classes, rates, EU VAT, configuration |
64
+ | Shipping | 15 | Shipping zones, methods, classes |
65
+ | Settings | 30 | Store settings, payment methods, modules, storage, permissions, checkout fields |
66
+ | Email Notifications | 11 | Email template management, previews, test sending |
67
+
68
+ ### Analytics & Content
69
+
70
+ | Module | Endpoints | Description |
71
+ |--------|-----------|-------------|
72
+ | Reports | 45 | Revenue, orders, sales, refunds, subscriptions, dashboards, retention |
73
+ | Integrations | 17 | Add-ons, global feeds, product integration feeds |
74
+ | Files | 5 | File uploads, storage management, editor uploads |
75
+ | Labels & Attributes | 13 | Product labels, attribute groups, attribute terms |
76
+ | Dashboard | 20 | Dashboard stats, onboarding, activity log, print templates, widgets |
77
+
78
+ ### Storefront & Checkout
79
+
80
+ | Module | Endpoints | Description |
81
+ |--------|-----------|-------------|
82
+ | Public Shop | 3 | Public product listing, search, server-rendered views |
83
+ | Checkout | 7 | Order placement, payment processing, shipping methods, country info |
84
+ | Customer Profile | 21 | Customer portal — orders, downloads, addresses, profile management |
85
+
86
+ ### Pro Features
87
+
88
+ | Module | Endpoints | Description |
89
+ |--------|-----------|-------------|
90
+ | Licensing | 24 | License management, activations, public license API, WordPress update API |
91
+ | Roles & Permissions | 7 | FluentCart role assignment and management |
92
+ | Order Bumps | 5 | Order bump CRUD with display conditions |
93
+
94
+ ---
95
+
96
+ ## Permission System
97
+
98
+ FluentCart uses a policy-based authorization system with 32 granular permissions across 4 built-in roles:
99
+
100
+ | Role | Description |
101
+ |------|-------------|
102
+ | `super_admin` | Full access to all features |
103
+ | `manager` | Manage orders, customers, products, and settings |
104
+ | `worker` | Day-to-day operations — orders, customers, products |
105
+ | `accountant` | Read-only access to orders, customers, and reports |
106
+
107
+ Each endpoint documents its required permission (e.g., `orders/view`, `products/edit`, `store/sensitive`).
108
+
109
+ ---
110
+
111
+ ## Error Handling
112
+
113
+ All error responses follow a consistent format:
114
+
115
+ ```json
116
+ {
117
+ "message": "Error description",
118
+ "errors": {
119
+ "field_name": ["Validation error message"]
120
+ }
121
+ }
122
+ ```
123
+
124
+ | Status Code | Meaning |
125
+ |-------------|---------|
126
+ | `200` | Success |
127
+ | `400` | Bad Request — validation failed or invalid parameters |
128
+ | `403` | Forbidden — insufficient permissions |
129
+ | `404` | Not Found — resource does not exist |
130
+ | `422` | Unprocessable Entity — business logic error |
131
+ | `429` | Too Many Requests — rate limited |