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,172 +1,172 @@
1
- # Public Shop API
2
-
3
- Public unauthenticated storefront endpoints for browsing published products, fetching server-rendered product grid views, and live search bar autocomplete in FluentCart.
4
-
5
- **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/public`
6
- **Policy:** `PublicPolicy` (No authentication required)
7
-
8
- ---
9
-
10
- ## Endpoints Overview
11
-
12
- | Method | Endpoint | Description |
13
- |--------|----------|-------------|
14
- | GET | `/public/products` | Paginated list of published catalog products with taxonomy & price filters |
15
- | GET | `/public/product-views` | Server-rendered HTML product card grid views for blocks & shortcodes |
16
- | GET | `/public/product-search` | Title search returning pre-rendered HTML items for search dropdowns |
17
-
18
- ---
19
-
20
- ## 1. List Products
21
-
22
- `GET /fluent-cart/v2/public/products`
23
-
24
- Retrieve a paginated list of published catalog products. Sensitive administrative fields (`post_content`, `item_cost`, `editing_stage`, `stock`, `manage_stock`, `manage_cost`, `settings`) are omitted from the public response.
25
-
26
- ### Parameters
27
-
28
- | Parameter | Type | Location | Required | Description |
29
- |-----------|------|----------|----------|-------------|
30
- | `per_page` | integer | query | No | Products per page (default: 10) |
31
- | `current_page` | integer | query | No | Page number for offset-based pagination |
32
- | `cursor` | string | query | No | Cursor token for cursor-based pagination |
33
- | `paginate_using` | string | query | No | Set to `cursor` for cursor strategy, omit for offset |
34
- | `order_type` | string | query | No | Sort direction: `ASC` or `DESC` (default: `DESC`) |
35
- | `with` | array | query | No | Eager load relations (e.g., `["detail"]`) |
36
- | `allow_out_of_stock` | boolean | query | No | Include out-of-stock products (default: `false`) |
37
- | `include_ids` | array | query | No | Include specific product IDs (max 100) |
38
- | `exclude_ids` | array | query | No | Exclude specific product IDs (max 100) |
39
- | `product_type` | string | query | No | Filter by type (`physical`, `digital`, `subscription`, `onetime`, `simple`, `simple_variations`) |
40
- | `on_sale` | boolean | query | No | Return only products on sale (`compare_price > item_price`) |
41
- | `default_filters` | object | query | No | Shortcode-level default filters |
42
- | `filters` | object | query | No | Interactive user-applied filter overrides |
43
-
44
- #### Filter Fields (`filters[...]` / `default_filters[...]`)
45
-
46
- | Field | Type | Description |
47
- |-------|------|-------------|
48
- | `wildcard` | string | Search title by keyword |
49
- | `enable_wildcard_for_post_content` | integer | Set to `1` to search product content as well |
50
- | `sort_by` | string | Preset: `name-asc`, `name-desc`, `price-low`, `price-high`, `date-newest`, `date-oldest` |
51
- | `price_range_from` | float | Minimum price filter (decimal dollar amount, e.g. `10.00`) |
52
- | `price_range_to` | float | Maximum price filter (decimal dollar amount, e.g. `99.99`) |
53
- | `{taxonomy_slug}` | string/array | Term IDs array for custom taxonomies (e.g. `product-categories`) |
54
-
55
- ### Response
56
-
57
- > **Price Units:** Product prices in `detail` (`min_price`, `max_price`) are returned as integer **cents**.
58
-
59
- ```json
60
- {
61
- "products": {
62
- "products": {
63
- "total": 24,
64
- "per_page": 10,
65
- "current_page": 1,
66
- "last_page": 3,
67
- "data": [
68
- {
69
- "ID": 42,
70
- "post_title": "Premium T-Shirt",
71
- "post_status": "publish",
72
- "post_excerpt": "High-quality cotton t-shirt",
73
- "guid": "https://example.com/?p=42",
74
- "view_url": "https://example.com/product/premium-t-shirt",
75
- "has_subscription": false,
76
- "thumbnail": "https://example.com/wp-content/uploads/tshirt.jpg",
77
- "detail": {
78
- "id": 15,
79
- "post_id": 42,
80
- "variation_type": "simple",
81
- "min_price": 2500,
82
- "max_price": 2500,
83
- "fulfillment_type": "physical"
84
- }
85
- }
86
- ]
87
- },
88
- "total": 24
89
- }
90
- }
91
- ```
92
-
93
- ### Example
94
-
95
- ```bash
96
- curl -X GET "https://example.com/wp-json/fluent-cart/v2/public/products?per_page=12&filters[sort_by]=price-low&filters[price_range_from]=10&filters[price_range_to]=50"
97
- ```
98
-
99
- ---
100
-
101
- ## 2. Get Product Views (Server-Rendered HTML)
102
-
103
- `GET /fluent-cart/v2/public/product-views`
104
-
105
- Retrieve pre-rendered HTML cards for product grids (used by Gutenberg blocks and shortcodes for AJAX pagination and filtering). Supports all filter parameters from List Products.
106
-
107
- ### Parameters
108
-
109
- | Parameter | Type | Location | Required | Description |
110
- |-----------|------|----------|----------|-------------|
111
- | `per_page` | integer | query | No | Products per page (default: 10) |
112
- | `current_page` | integer | query | No | Current page number (default: 1) |
113
- | `template_provider` | string | query | No | Custom provider ID for `fluent_cart/products_views/preload_collection_{provider}` filter |
114
- | `client_id` | string | query | No | Transient client ID to retrieve cached block markup (`fct_product_loop_client_{client_id}`) |
115
-
116
- #### Server Rendering Pipeline Priority
117
-
118
- 1. **Template Provider:** If `template_provider` is set, calls `fluent_cart/products_views/preload_collection_{provider}` filter.
119
- 2. **Cached Block Markup:** If `client_id` is set, processes matching transient block template with `do_blocks()`.
120
- 3. **Default Renderer:** Falls back to `ProductListRenderer` for standard card markup.
121
-
122
- ### Response
123
-
124
- ```json
125
- {
126
- "products": {
127
- "views": "<div class=\"fct-product-card\">...rendered HTML card list...</div>",
128
- "current_page": 1,
129
- "last_page": 3,
130
- "total": 24,
131
- "per_page": 10,
132
- "from": 1,
133
- "to": 10
134
- }
135
- }
136
- ```
137
-
138
- ### Example
139
-
140
- ```bash
141
- curl -X GET "https://example.com/wp-json/fluent-cart/v2/public/product-views?per_page=12&current_page=2&filters[sort_by]=date-newest"
142
- ```
143
-
144
- ---
145
-
146
- ## 3. Search Products (Live Search Autocomplete)
147
-
148
- `GET /fluent-cart/v2/public/product-search`
149
-
150
- Returns pre-rendered HTML search result items for live storefront search dropdowns.
151
-
152
- ### Parameters
153
-
154
- | Parameter | Type | Location | Required | Description |
155
- |-----------|------|----------|----------|-------------|
156
- | `post_title` | string | query | Yes | Search query string matched against product titles |
157
- | `url_mode` | string | query | No | URL mode passed to `SearchBarRenderer` for permalink generation |
158
- | `termId` | integer | query | No | Taxonomy term (category) ID filter |
159
-
160
- ### Response
161
-
162
- ```json
163
- {
164
- "htmlView": "<div class=\"fct-search-result-item\"><a href=\"https://example.com/product/premium-t-shirt\">Premium T-Shirt</a></div>"
165
- }
166
- ```
167
-
168
- ### Example
169
-
170
- ```bash
171
- curl -X GET "https://example.com/wp-json/fluent-cart/v2/public/product-search?post_title=shirt&termId=5"
172
- ```
1
+ # Public Shop API
2
+
3
+ Public unauthenticated storefront endpoints for browsing published products, fetching server-rendered product grid views, and live search bar autocomplete in FluentCart.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2/public`
6
+ **Policy:** `PublicPolicy` (No authentication required)
7
+
8
+ ---
9
+
10
+ ## Endpoints Overview
11
+
12
+ | Method | Endpoint | Description |
13
+ |--------|----------|-------------|
14
+ | GET | `/public/products` | Paginated list of published catalog products with taxonomy & price filters |
15
+ | GET | `/public/product-views` | Server-rendered HTML product card grid views for blocks & shortcodes |
16
+ | GET | `/public/product-search` | Title search returning pre-rendered HTML items for search dropdowns |
17
+
18
+ ---
19
+
20
+ ## 1. List Products
21
+
22
+ `GET /fluent-cart/v2/public/products`
23
+
24
+ Retrieve a paginated list of published catalog products. Sensitive administrative fields (`post_content`, `item_cost`, `editing_stage`, `stock`, `manage_stock`, `manage_cost`, `settings`) are omitted from the public response.
25
+
26
+ ### Parameters
27
+
28
+ | Parameter | Type | Location | Required | Description |
29
+ |-----------|------|----------|----------|-------------|
30
+ | `per_page` | integer | query | No | Products per page (default: 10) |
31
+ | `current_page` | integer | query | No | Page number for offset-based pagination |
32
+ | `cursor` | string | query | No | Cursor token for cursor-based pagination |
33
+ | `paginate_using` | string | query | No | Set to `cursor` for cursor strategy, omit for offset |
34
+ | `order_type` | string | query | No | Sort direction: `ASC` or `DESC` (default: `DESC`) |
35
+ | `with` | array | query | No | Eager load relations (e.g., `["detail"]`) |
36
+ | `allow_out_of_stock` | boolean | query | No | Include out-of-stock products (default: `false`) |
37
+ | `include_ids` | array | query | No | Include specific product IDs (max 100) |
38
+ | `exclude_ids` | array | query | No | Exclude specific product IDs (max 100) |
39
+ | `product_type` | string | query | No | Filter by type (`physical`, `digital`, `subscription`, `onetime`, `simple`, `simple_variations`) |
40
+ | `on_sale` | boolean | query | No | Return only products on sale (`compare_price > item_price`) |
41
+ | `default_filters` | object | query | No | Shortcode-level default filters |
42
+ | `filters` | object | query | No | Interactive user-applied filter overrides |
43
+
44
+ #### Filter Fields (`filters[...]` / `default_filters[...]`)
45
+
46
+ | Field | Type | Description |
47
+ |-------|------|-------------|
48
+ | `wildcard` | string | Search title by keyword |
49
+ | `enable_wildcard_for_post_content` | integer | Set to `1` to search product content as well |
50
+ | `sort_by` | string | Preset: `name-asc`, `name-desc`, `price-low`, `price-high`, `date-newest`, `date-oldest` |
51
+ | `price_range_from` | float | Minimum price filter (decimal dollar amount, e.g. `10.00`) |
52
+ | `price_range_to` | float | Maximum price filter (decimal dollar amount, e.g. `99.99`) |
53
+ | `{taxonomy_slug}` | string/array | Term IDs array for custom taxonomies (e.g. `product-categories`) |
54
+
55
+ ### Response
56
+
57
+ > **Price Units:** Product prices in `detail` (`min_price`, `max_price`) are returned as integer **cents**.
58
+
59
+ ```json
60
+ {
61
+ "products": {
62
+ "products": {
63
+ "total": 24,
64
+ "per_page": 10,
65
+ "current_page": 1,
66
+ "last_page": 3,
67
+ "data": [
68
+ {
69
+ "ID": 42,
70
+ "post_title": "Premium T-Shirt",
71
+ "post_status": "publish",
72
+ "post_excerpt": "High-quality cotton t-shirt",
73
+ "guid": "https://example.com/?p=42",
74
+ "view_url": "https://example.com/product/premium-t-shirt",
75
+ "has_subscription": false,
76
+ "thumbnail": "https://example.com/wp-content/uploads/tshirt.jpg",
77
+ "detail": {
78
+ "id": 15,
79
+ "post_id": 42,
80
+ "variation_type": "simple",
81
+ "min_price": 2500,
82
+ "max_price": 2500,
83
+ "fulfillment_type": "physical"
84
+ }
85
+ }
86
+ ]
87
+ },
88
+ "total": 24
89
+ }
90
+ }
91
+ ```
92
+
93
+ ### Example
94
+
95
+ ```bash
96
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/public/products?per_page=12&filters[sort_by]=price-low&filters[price_range_from]=10&filters[price_range_to]=50"
97
+ ```
98
+
99
+ ---
100
+
101
+ ## 2. Get Product Views (Server-Rendered HTML)
102
+
103
+ `GET /fluent-cart/v2/public/product-views`
104
+
105
+ Retrieve pre-rendered HTML cards for product grids (used by Gutenberg blocks and shortcodes for AJAX pagination and filtering). Supports all filter parameters from List Products.
106
+
107
+ ### Parameters
108
+
109
+ | Parameter | Type | Location | Required | Description |
110
+ |-----------|------|----------|----------|-------------|
111
+ | `per_page` | integer | query | No | Products per page (default: 10) |
112
+ | `current_page` | integer | query | No | Current page number (default: 1) |
113
+ | `template_provider` | string | query | No | Custom provider ID for `fluent_cart/products_views/preload_collection_{provider}` filter |
114
+ | `client_id` | string | query | No | Transient client ID to retrieve cached block markup (`fct_product_loop_client_{client_id}`) |
115
+
116
+ #### Server Rendering Pipeline Priority
117
+
118
+ 1. **Template Provider:** If `template_provider` is set, calls `fluent_cart/products_views/preload_collection_{provider}` filter.
119
+ 2. **Cached Block Markup:** If `client_id` is set, processes matching transient block template with `do_blocks()`.
120
+ 3. **Default Renderer:** Falls back to `ProductListRenderer` for standard card markup.
121
+
122
+ ### Response
123
+
124
+ ```json
125
+ {
126
+ "products": {
127
+ "views": "<div class=\"fct-product-card\">...rendered HTML card list...</div>",
128
+ "current_page": 1,
129
+ "last_page": 3,
130
+ "total": 24,
131
+ "per_page": 10,
132
+ "from": 1,
133
+ "to": 10
134
+ }
135
+ }
136
+ ```
137
+
138
+ ### Example
139
+
140
+ ```bash
141
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/public/product-views?per_page=12&current_page=2&filters[sort_by]=date-newest"
142
+ ```
143
+
144
+ ---
145
+
146
+ ## 3. Search Products (Live Search Autocomplete)
147
+
148
+ `GET /fluent-cart/v2/public/product-search`
149
+
150
+ Returns pre-rendered HTML search result items for live storefront search dropdowns.
151
+
152
+ ### Parameters
153
+
154
+ | Parameter | Type | Location | Required | Description |
155
+ |-----------|------|----------|----------|-------------|
156
+ | `post_title` | string | query | Yes | Search query string matched against product titles |
157
+ | `url_mode` | string | query | No | URL mode passed to `SearchBarRenderer` for permalink generation |
158
+ | `termId` | integer | query | No | Taxonomy term (category) ID filter |
159
+
160
+ ### Response
161
+
162
+ ```json
163
+ {
164
+ "htmlView": "<div class=\"fct-search-result-item\"><a href=\"https://example.com/product/premium-t-shirt\">Premium T-Shirt</a></div>"
165
+ }
166
+ ```
167
+
168
+ ### Example
169
+
170
+ ```bash
171
+ curl -X GET "https://example.com/wp-json/fluent-cart/v2/public/product-search?post_title=shirt&termId=5"
172
+ ```