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,219 @@
1
+ # Dashboard & Utilities API
2
+
3
+ Administrative endpoints for dashboard statistics, onboarding setup, SPA initialization, media attachments, activity logging, order notes, print templates, address locales, and dynamic filter widgets in FluentCart.
4
+
5
+ **Base URL:** `https://your-site.com/wp-json/fluent-cart/v2`
6
+
7
+ ---
8
+
9
+ ## Endpoints Overview
10
+
11
+ | Group | Method | Endpoint | Permission / Policy | Request Class | Description |
12
+ |-------|--------|----------|--------------------|---------------|-------------|
13
+ | **Dashboard** | GET | `/dashboard` | `AdminPolicy` | — | Get onboarding checklist completion status |
14
+ | | GET | `/dashboard/stats` | `dashboard_stats/view` | — | Get 30-day dashboard summary stats cards |
15
+ | **Onboarding** | GET | `/onboarding` | `AdminPolicy` | — | Get onboarding settings, pages, & currencies |
16
+ | | POST | `/onboarding` | `AdminPolicy` | — | Save onboarding settings & trigger dummy products |
17
+ | | POST | `/onboarding/create-pages` | `AdminPolicy` | — | Bulk create all missing store pages |
18
+ | | POST | `/onboarding/create-page` | `AdminPolicy` | `CreatePageRequest` | Create single store page & set page ID |
19
+ | **App Init & Media** | GET | `/app/init` | `AdminPolicy` | — | Initialize admin SPA config, nonces, & strings |
20
+ | | GET | `/app/attachments` | `AdminPolicy` | — | List Media Library images for media picker |
21
+ | | POST | `/app/upload-attachments` | `AdminPolicy` | — | Upload image to WordPress Media Library |
22
+ | **Activity Log** | GET | `/activity` | `AdminPolicy` | — | List paginated activity log entries |
23
+ | | DELETE | `/activity/{id}` | `AdminPolicy` | — | Delete activity log entry |
24
+ | | PUT | `/activity/{id}/mark-read` | `AdminPolicy` | — | Toggle read/unread status of activity log entry |
25
+ | **Order Notes** | POST | `/notes/attach` | `AdminPolicy` | — | Attach or update note on an order |
26
+ | **Print Templates** | GET | `/templates/print-templates` | `AdminPolicy` | — | Get invoice & slip print templates |
27
+ | | PUT | `/templates/print-templates` | `AdminPolicy` | — | Save customized print HTML templates |
28
+ | **Widgets** | GET | `/widgets` | `customers/view` / `orders/view` | — | Get dynamic widget data for single order |
29
+ | **Address Info** | GET | `/address-info/countries` | `UserPolicy` | — | List all countries formatted as select options |
30
+ | | GET | `/address-info/get-country-info` | `UserPolicy` | — | Get country states & localized address locale |
31
+ | **Advanced Filters** | GET | `/advance_filter/get-filter-options` | `orders/view` / `customers/view` / `products/view` / `labels/view` | — | Fetch dynamic options (variations tree / labels) |
32
+ | | GET | `/forms/search_options` | `super_admin` | — | Fetch dynamic form search options |
33
+
34
+ ---
35
+
36
+ ## Admin Dashboard
37
+
38
+ Overview and quick stats widgets for the store admin panel.
39
+
40
+ ### Get Onboarding Checklist Data
41
+
42
+ `GET /fluent-cart/v2/dashboard`
43
+
44
+ **Policy:** `AdminPolicy`
45
+
46
+ #### Checklist Completion Logic
47
+
48
+ | Step Key | Title | Completed When |
49
+ |----------|-------|----------------|
50
+ | `page_setup` | Setup Pages | All generatable store pages (shop, checkout, etc.) have page IDs assigned |
51
+ | `store_info` | Add Details to Store | Both `store_name` and `store_logo` are configured in store settings |
52
+ | `product_info` | Add Your First Product | At least one product exists in database |
53
+ | `setup_payments` | Setup Payment Methods | At least one payment gateway is enabled |
54
+
55
+ #### Response
56
+
57
+ ```json
58
+ {
59
+ "data": {
60
+ "steps": {
61
+ "page_setup": { "title": "Setup Pages", "completed": false },
62
+ "store_info": { "title": "Add Details to Store", "completed": true },
63
+ "product_info": { "title": "Add Your First Product", "completed": false },
64
+ "setup_payments": { "title": "Setup Payment Methods", "completed": true }
65
+ },
66
+ "completed": 2
67
+ }
68
+ }
69
+ ```
70
+
71
+ ---
72
+
73
+ ### Get Dashboard Stats Widgets
74
+
75
+ `GET /fluent-cart/v2/dashboard/stats`
76
+
77
+ **Policy:** `DashboardPolicy` | **Permission:** `dashboard_stats/view`
78
+
79
+ > **Metrics Rules:**
80
+ > - Orders, Revenue, and Refunds are calculated for the **last 30 days only**.
81
+ > - Orders with `on_hold` or `failed` status are excluded.
82
+ > - Net Revenue = `total_paid - total_refund - tax_total - shipping_tax` (converted from cents to decimal dollars).
83
+ > - `has_currency: true` indicates value should be formatted with store currency symbol.
84
+
85
+ #### Response
86
+
87
+ ```json
88
+ {
89
+ "stats": [
90
+ {
91
+ "title": "Total Products",
92
+ "current_count": 45,
93
+ "icon": "Frame",
94
+ "url": "https://example.com/wp-admin/admin.php?page=fluent-cart#/products?active_view=all"
95
+ },
96
+ {
97
+ "title": "Orders",
98
+ "current_count": 128,
99
+ "icon": "AllOrdersIcon",
100
+ "url": "https://example.com/wp-admin/admin.php?page=fluent-cart#/orders"
101
+ },
102
+ {
103
+ "title": "Revenue",
104
+ "current_count": 15420.50,
105
+ "icon": "Currency",
106
+ "url": "https://example.com/wp-admin/admin.php?page=fluent-cart#/reports/revenue",
107
+ "has_currency": true
108
+ },
109
+ {
110
+ "title": "Refund",
111
+ "current_count": 350.00,
112
+ "icon": "Failed",
113
+ "url": "https://example.com/wp-admin/admin.php?page=fluent-cart#/reports/refunds",
114
+ "has_currency": true
115
+ }
116
+ ]
117
+ }
118
+ ```
119
+
120
+ ---
121
+
122
+ ## Onboarding Setup Wizard
123
+
124
+ Endpoints for store page creation and initial setup.
125
+
126
+ **Prefix:** `/fluent-cart/v2/onboarding` | **Policy:** `AdminPolicy`
127
+
128
+ - `GET /onboarding` — Retrieve current pages, currencies, and default settings.
129
+ - `POST /onboarding` — Save onboarding settings (`store_name`, `store_logo`, `currency`). Note: Providing `category` triggers asynchronous dummy product generation.
130
+ - `POST /onboarding/create-pages` — Bulk create missing store pages.
131
+ - `POST /onboarding/create-page` — Create single page (`content`: `shop_page_id` / `checkout_page_id` / `customer_profile_page_id`, `page_name`, `save_settings`: `true`).
132
+
133
+ ---
134
+
135
+ ## SPA App Initialization & Media
136
+
137
+ **Prefix:** `/fluent-cart/v2/app` | **Policy:** `AdminPolicy`
138
+
139
+ - `GET /app/init` — SPA bootstrap endpoint (returns REST base URL, nonces, asset URLs, translations array, and store currency formats).
140
+ - `GET /app/attachments` — List WordPress media library image attachments for the admin media picker.
141
+ - `POST /app/upload-attachments` — Upload image file (`multipart/form-data`) to media library.
142
+
143
+ ---
144
+
145
+ ## System Activity Log
146
+
147
+ Tracks order status changes, payment webhooks, API calls, and errors.
148
+
149
+ **Prefix:** `/fluent-cart/v2/activity` | **Policy:** `AdminPolicy`
150
+
151
+ ### List Activities
152
+
153
+ `GET /fluent-cart/v2/activity`
154
+
155
+ #### Parameters
156
+
157
+ | Parameter | Type | Location | Required | Description |
158
+ |-----------|------|----------|----------|-------------|
159
+ | `search` | string | query | No | Search by ID (prefix with `#`), title, content, or module |
160
+ | `active_view` | string | query | No | Filter tab: `success`, `warning`, `error`, `failed`, `info`, `api` |
161
+ | `sort_by` | string | query | No | Sort column (default: `id`) |
162
+ | `sort_type` | string | query | No | Sort direction (`asc` or `desc`, default: `desc`) |
163
+ | `per_page` | integer | query | No | Results per page (default: 10, max: 200) |
164
+ | `page` | integer | query | No | Page number |
165
+
166
+ ---
167
+
168
+ ### Delete & Toggle Activity Read Status
169
+
170
+ - `DELETE /activity/{id}` — Permanently delete activity entry.
171
+ - `PUT /activity/{id}/mark-read` — Toggle read status (`status`: `read` or `unread`).
172
+
173
+ ---
174
+
175
+ ## Order Notes & Print Templates
176
+
177
+ - `POST /fluent-cart/v2/notes/attach` — Attach note content to order (`order_id`, `note`).
178
+ - `GET /fluent-cart/v2/templates/print-templates` — Retrieve print templates (`invoice_template`, `packing_slip`, `delivery_slip`, `shipping_slip`, `dispatch_slip`).
179
+ - `PUT /fluent-cart/v2/templates/print-templates` — Save customized print HTML templates (sanitized with `wp_kses_post`).
180
+
181
+ ---
182
+
183
+ ## Dynamic Widgets, Address Locales, & Filters
184
+
185
+ ### Get Contextual Widgets
186
+
187
+ `GET /fluent-cart/v2/widgets`
188
+
189
+ **Policy:** `OrderPolicy` | **Permission:** `customers/view` OR `orders/view`
190
+
191
+ - `filter` (query): Widget context (e.g. `single_order_page`). Dispatches to filter hook `fluent_cart/widgets/{filter}`.
192
+ - `data[order_id]` (query): Order ID context.
193
+
194
+ ---
195
+
196
+ ### Address Info & Country Locales
197
+
198
+ `GET /fluent-cart/v2/address-info/countries` — List all countries as select options (`label`, `value`).
199
+ `GET /fluent-cart/v2/address-info/get-country-info` — Get country states array and localized `address_locale` rules (`country_code` OR `timezone` e.g. `America/New_York`).
200
+
201
+ ```json
202
+ {
203
+ "country_code": "US",
204
+ "country_name": "United States",
205
+ "states": [{ "label": "California", "value": "CA" }],
206
+ "address_locale": {
207
+ "state": { "label": "State", "required": true },
208
+ "postcode": { "label": "ZIP Code", "required": true },
209
+ "city": { "label": "City", "required": true }
210
+ }
211
+ }
212
+ ```
213
+
214
+ ---
215
+
216
+ ### Advanced Search & Filter Options
217
+
218
+ - `GET /fluent-cart/v2/advance_filter/get-filter-options` — Load options for advanced filter UI (`remote_data_key`: `product_variations` [returns hierarchical tree], `labels` [flat list], or custom resolved via `fluent_cart/advanced_filter_options_{key}`).
219
+ - `GET /fluent-cart/v2/forms/search_options` — Form search options (`search_for`, `search_by`, `is_super_admin`, resolved via `fluent_cart/get_dynamic_search_{search_for}`).