br-woo-routes

Name: br-woo-routes
Author: Lonsdale201

21stars1forks

How to install br-woo-routes?

lonsdale201/wp-agent-skills/br-woo-routes

$npx -y skills add Lonsdale201/wp-agent-skills --skill br-woo-routes

Installs into the current project.

Summary

Expose WooCommerce 10.x orders, products, customers, and coupons with better-route 1.1 WooRouteRegistrar. Use for BetterRoute::wooRouteRegistrar, HPOS guards, actions, permissions, strict list/body validation, pagination meta, stable sorting, protected metadata, atomic idempotenc

Files · 1

View on GitHub

SKILL.md

1	# better-route: WooCommerce routes
2
3	Register Woo routes during `rest_api_init` and retain the returned Router when contracts are needed.
4
5	```php
6	use BetterRoute\BetterRoute;
7
8	add_action('rest_api_init', static function (): void {
9	$woo = BetterRoute::wooRouteRegistrar()->register('myapp/v1', [
10	'basePath' => 'woo',
11	'requireHpos' => true,
12	'deleteMode' => 'trash',
13	'actions' => [
14	'customers' => ['list', 'get'],
15	'coupons' => [],
16	],
17	'permissions' => [
18	'orders.list' => 'manage_woocommerce',
19	'orders.create' => 'manage_woocommerce',
20	],
21	]);
22	});
23	```
24
25	Routes cover orders, products, customers, and coupons under `/wp-json/myapp/v1/woo` by default.
26
27	## Actions and permissions
28
29	Each resource supports `list`, `get`, `create`, `update`, and `delete`; update registers both PUT and PATCH.
30
31	- Omit `actions.<resource>` for full CRUD.
32	- Pass `[]` to disable that resource.
33	- Invalid action names or a non-array value throw.
34
35	Permission keys use `<resource>.<action>`. A value may be bool, capability string, any-of capability list, or callable receiving the request and optionally the registrar. Unrecognized/empty rules deny. Defaults are `manage_woocommerce`.
36
37	Customer writes also enforce native user capabilities inside the service:
38
39	- create: `create_users`;
40	- update: `edit_user` for the target;
41	- delete: `delete_user` for the target.
42
43	Customer list/get expose users with the `customer` role only; a general WordPress user directory is intentionally not provided.
44
45	## Lists
46
47	```http
48	GET /wp-json/myapp/v1/woo/orders?status=processing&sort=-date_created&page=1&per_page=50&fields=id,total,status
49	```
50
51	Lists return pagination in the JSON envelope:
52
53	```json
54	{"data": [], "meta": {"page": 1, "perPage": 50, "total": 0}}
55	```
56
57	Do not expect `X-WP-Total` or `X-WP-TotalPages`; Better Route Woo pagination is in `meta`.
58
59	`per_page > maxPerPage` returns `400 validation_failed`; it is not clamped. `sort=-field` means DESC. Services add an ID tie-breaker so equal primary sort values paginate deterministically.
60
61	Strict parsers reject unknown parameters but accept WordPress globals `_locale`, `_fields`, `_embed`, `_envelope`, and `_jsonp`, including `wp.apiFetch`'s `_locale=user`.
62
63	Resource filters/sorts differ:
64
65	- orders: status, customer_id, search; stable order/date/total options supported by parser;
66	- products: status, type, sku, search, stock_status; derived price sorting is not supported;
67	- customers: role, email, search;
68	- coupons: code, search.
69
70	Use each parser's allowlist rather than forwarding arbitrary Woo query vars.
71
72	## Strict write payloads in 1.1
73
74	All services reject unknown top-level fields and enforce field types before setters/save.
75
76	Orders:
77
78	- validate the complete payload before persistence;
79	- reject unknown billing/shipping/line-item keys;
80	- require `product_id` for line items and validate product/variation existence and relationship;
81	- require non-negative finite quantities/totals where applicable;
82	- refuse line-item replacement after stock reduction with `409 woo_line_items_locked`;
83	- run create/update inside `wc_transaction_query('start'/'commit'/'rollback')`.
84
85	Products:
86
87	- treat `price` as read-only;
88	- write `regular_price` and `sale_price` instead;
89	- validate all fields before applying setters/save.
90
91	Customers:
92
93	- require `email` on create;
94	- reject `username` on update because WordPress usernames are immutable through this API;
95	- reject unknown address keys and non-string address values;
96	- omit expensive `orders_count` and `total_spent` from list defaults to avoid N+1 work; request them explicitly when needed.
97
98	Coupons:
99
100	- require `code` on create;
101	- strictly validate monetary, boolean, list, date, and metadata fields;
102	- enforce normalized code uniqueness on create and update under a MySQL named lock;
103	- exclude the current coupon ID when checking an update; conflicts return `409 coupon_exists`.
104
105	Money response fields are decimal strings, not JSON floats.
106
107	## Metadata
108
109	Use the actual helper APIs:
110
111	```php
112	$meta = MetaDataHelper::normalizeIncoming($payload['meta_data'] ?? null);
113	MetaDataHelper::applyToTarget($object, $meta);
114	$serialized = MetaDataHelper::serialize($object->get_meta_data());
115	```
116
117	Incoming metadata may be a key/value map or a

People who liked this also viewed

6 picks

Type

br-woo-routes

21stars1forks

View on GitHub

How to install br-woo-routes?

lonsdale201/wp-agent-skills/br-woo-routes

$npx -y skills add Lonsdale201/wp-agent-skills --skill br-woo-routes

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# better-route: WooCommerce routes
2
3	Register Woo routes during `rest_api_init` and retain the returned Router when contracts are needed.
4
5	```php
6	use BetterRoute\BetterRoute;
7
8	add_action('rest_api_init', static function (): void {
9	$woo = BetterRoute::wooRouteRegistrar()->register('myapp/v1', [
10	'basePath' => 'woo',
11	'requireHpos' => true,
12	'deleteMode' => 'trash',
13	'actions' => [
14	'customers' => ['list', 'get'],
15	'coupons' => [],
16	],
17	'permissions' => [
18	'orders.list' => 'manage_woocommerce',
19	'orders.create' => 'manage_woocommerce',
20	],
21	]);
22	});
23	```
24
25	Routes cover orders, products, customers, and coupons under `/wp-json/myapp/v1/woo` by default.
26
27	## Actions and permissions
28
29	Each resource supports `list`, `get`, `create`, `update`, and `delete`; update registers both PUT and PATCH.
30
31	- Omit `actions.<resource>` for full CRUD.
32	- Pass `[]` to disable that resource.
33	- Invalid action names or a non-array value throw.
34
35	Permission keys use `<resource>.<action>`. A value may be bool, capability string, any-of capability list, or callable receiving the request and optionally the registrar. Unrecognized/empty rules deny. Defaults are `manage_woocommerce`.
36
37	Customer writes also enforce native user capabilities inside the service:
38
39	- create: `create_users`;
40	- update: `edit_user` for the target;
41	- delete: `delete_user` for the target.
42
43	Customer list/get expose users with the `customer` role only; a general WordPress user directory is intentionally not provided.
44
45	## Lists
46
47	```http
48	GET /wp-json/myapp/v1/woo/orders?status=processing&sort=-date_created&page=1&per_page=50&fields=id,total,status
49	```
50
51	Lists return pagination in the JSON envelope:
52
53	```json
54	{"data": [], "meta": {"page": 1, "perPage": 50, "total": 0}}
55	```
56
57	Do not expect `X-WP-Total` or `X-WP-TotalPages`; Better Route Woo pagination is in `meta`.
58
59	`per_page > maxPerPage` returns `400 validation_failed`; it is not clamped. `sort=-field` means DESC. Services add an ID tie-breaker so equal primary sort values paginate deterministically.
60
61	Strict parsers reject unknown parameters but accept WordPress globals `_locale`, `_fields`, `_embed`, `_envelope`, and `_jsonp`, including `wp.apiFetch`'s `_locale=user`.
62
63	Resource filters/sorts differ:
64
65	- orders: status, customer_id, search; stable order/date/total options supported by parser;
66	- products: status, type, sku, search, stock_status; derived price sorting is not supported;
67	- customers: role, email, search;
68	- coupons: code, search.
69
70	Use each parser's allowlist rather than forwarding arbitrary Woo query vars.
71
72	## Strict write payloads in 1.1
73
74	All services reject unknown top-level fields and enforce field types before setters/save.
75
76	Orders:
77
78	- validate the complete payload before persistence;
79	- reject unknown billing/shipping/line-item keys;
80	- require `product_id` for line items and validate product/variation existence and relationship;
81	- require non-negative finite quantities/totals where applicable;
82	- refuse line-item replacement after stock reduction with `409 woo_line_items_locked`;
83	- run create/update inside `wc_transaction_query('start'/'commit'/'rollback')`.
84
85	Products:
86
87	- treat `price` as read-only;
88	- write `regular_price` and `sale_price` instead;
89	- validate all fields before applying setters/save.
90
91	Customers:
92
93	- require `email` on create;
94	- reject `username` on update because WordPress usernames are immutable through this API;
95	- reject unknown address keys and non-string address values;
96	- omit expensive `orders_count` and `total_spent` from list defaults to avoid N+1 work; request them explicitly when needed.
97
98	Coupons:
99
100	- require `code` on create;
101	- strictly validate monetary, boolean, list, date, and metadata fields;
102	- enforce normalized code uniqueness on create and update under a MySQL named lock;
103	- exclude the current coupon ID when checking an update; conflicts return `409 coupon_exists`.
104
105	Money response fields are decimal strings, not JSON floats.
106
107	## Metadata
108
109	Use the actual helper APIs:
110
111	```php
112	$meta = MetaDataHelper::normalizeIncoming($payload['meta_data'] ?? null);
113	MetaDataHelper::applyToTarget($object, $meta);
114	$serialized = MetaDataHelper::serialize($object->get_meta_data());
115	```
116
117	Incoming metadata may be a key/value map or a

People who liked this also viewed

6 picks

Type