br-error-contract

Name: br-error-contract
Author: Lonsdale201

21stars1forks

How to install br-error-contract?

lonsdale201/wp-agent-skills/br-error-contract

$npx -y skills add Lonsdale201/wp-agent-skills --skill br-error-contract

Installs into the current project.

Summary

Produce and consume better-route 1.1 structured errors. Use for ApiException, Response, ErrorNormalizer, ResponseNormalizer, WP_Error conversion, OAuth RFC 6749 error_format, status/code/details/headers, Retry-After, validation_failed, idempotency/rate/optimistic-lock/Woo errors,

Files · 1

View on GitHub

SKILL.md

1	# better-route: error contract
2
3	Throw `ApiException` for deliberate caller-visible failures. Let unexpected throwables be scrubbed.
4
5	```php
6	use BetterRoute\Http\ApiException;
7
8	throw new ApiException(
9	message: 'Order is temporarily locked.',
10	status: 409,
11	errorCode: 'order_locked',
12	details: ['orderId' => $id],
13	headers: ['Retry-After' => '5'],
14	);
15	```
16
17	The default envelope is:
18
19	```json
20	{
21	"error": {
22	"code": "order_locked",
23	"message": "Order is temporarily locked.",
24	"requestId": "req_...",
25	"details": {"orderId": 42}
26	}
27	}
28	```
29
30	Clients should branch on `error.code`, not message text.
31
32	## Normalization
33
34	\| Source \| Status/code/message/details \|
35	\|---\|---\|
36	\| `ApiException` \| Uses intentional values and headers. \|
37	\| `InvalidArgumentException` \| `400 invalid_request`, `Invalid request.`, empty details. \|
38	\| Other throwable \| `500 internal_error`, `Unexpected error.`, empty details. \|
39	\| `WP_Error` \| Uses its code/message and valid `data.status`; details expose only allowlisted `data.params`. \|
40
41	Unexpected exception class names and raw messages never reach the caller. Log internally; do not convert an unexpected exception to `ApiException` with its raw message.
42
43	`WP_Error` messages remain caller-visible for compatibility. Do not put SQL, paths, secrets, or debug data in a returned `WP_Error` message. Arbitrary error data is intentionally not copied into `details`; only the core REST validation `params` map is allowed.
44
45	## 1.1 validation
46
47	`ApiException` requires:
48
49	- status 400–599;
50	- non-empty error code matching `[A-Za-z0-9._:-]+`;
51	- valid HTTP header token names;
52	- header values without CR/LF.
53
54	`Response` accepts status 100–599 and applies the same header-name/value validation. Invalid configuration throws `InvalidArgumentException` before any header is emitted.
55
56	Use the fifth `headers` constructor argument for error metadata such as rate-limit headers. Do not call `header()` directly in a handler.
57
58	## OAuth error format
59
60	Opt in per route only when the client requires RFC 6749 shape:
61
62	```php
63	$router->post('/oauth/token', $handler)
64	->publicRoute()
65	->meta(['error_format' => 'oauth_rfc6749']);
66	```
67
68	```json
69	{
70	"error": "invalid_grant",
71	"error_description": "Authorization code is invalid."
72	}
73	```
74
75	Set `details.error_uri` to emit `error_uri`. Set `details.requestId` to boolean `true` to emit `request_id`; it is not included by default in OAuth format. ApiException headers are preserved.
76
77	## Common codes
78
79	- `400 validation_failed` with `details.fieldErrors`
80	- `400 unknown_parameter`
81	- `400 idempotency_key_required` / `idempotency_key_invalid`
82	- `401 invalid_token` / `invalid_signature`
83	- `403 insufficient_scope` / `forbidden` / `cors_origin_denied`
84	- `404 not_found`
85	- `409 idempotency_conflict` / `idempotency_in_progress`
86	- `409 coupon_exists` / `woo_line_items_locked` / `version_unavailable`
87	- `412 optimistic_lock_failed` or `precondition_failed`
88	- `428 precondition_required`
89	- `429 rate_limited` with `Retry-After` and `X-RateLimit-*`
90	- `503 hpos_required` / `woo_unavailable`
91
92	## Handler pattern
93
94	```php
95	$router->get('/orders/(?P<id>\d+)', static function ($request): array {
96	$id = (int) $request->get_param('id');
97	$order = wc_get_order($id);
98
99	if (!$order) {
100	throw new ApiException('Order not found.', 404, 'not_found', ['id' => $id]);
101	}
102
103	return ['data' => map_order($order)];
104	})->permission(static fn (): bool => current_user_can('manage_woocommerce'));
105	```
106
107	Do not return an ad hoc `['success' => false]` response; it bypasses the stable envelope. A returned `WP_REST_Response` is passed through, so its body is your responsibility.
108
109	## Review checklist
110
111	- Use ApiException only for sanitized caller-facing failures.
112	- Keep unexpected throwable details server-side.
113	- Validate clients against error codes and tolerate added detail keys.
114	- Never expect arbitrary WP_Error data in details.
115	- Assert 429 headers survive through WordPress and CORS exposure.
116	- Test OAuth and default formats independently.
117	- Reject response/error header injection in custom code.
118
119	## Related skills
120
121	- Use `br-write-schema` for validation detail shape.
122	- Use `br-rate-limiting`, `br-idempotency`, and `br-optimistic-locking` for subsystem errors.
123
124	## References
125
126	- Verified source

People who liked this also viewed

6 picks

Type

br-error-contract

21stars1forks

View on GitHub

How to install br-error-contract?

lonsdale201/wp-agent-skills/br-error-contract

$npx -y skills add Lonsdale201/wp-agent-skills --skill br-error-contract

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# better-route: error contract
2
3	Throw `ApiException` for deliberate caller-visible failures. Let unexpected throwables be scrubbed.
4
5	```php
6	use BetterRoute\Http\ApiException;
7
8	throw new ApiException(
9	message: 'Order is temporarily locked.',
10	status: 409,
11	errorCode: 'order_locked',
12	details: ['orderId' => $id],
13	headers: ['Retry-After' => '5'],
14	);
15	```
16
17	The default envelope is:
18
19	```json
20	{
21	"error": {
22	"code": "order_locked",
23	"message": "Order is temporarily locked.",
24	"requestId": "req_...",
25	"details": {"orderId": 42}
26	}
27	}
28	```
29
30	Clients should branch on `error.code`, not message text.
31
32	## Normalization
33
34	\| Source \| Status/code/message/details \|
35	\|---\|---\|
36	\| `ApiException` \| Uses intentional values and headers. \|
37	\| `InvalidArgumentException` \| `400 invalid_request`, `Invalid request.`, empty details. \|
38	\| Other throwable \| `500 internal_error`, `Unexpected error.`, empty details. \|
39	\| `WP_Error` \| Uses its code/message and valid `data.status`; details expose only allowlisted `data.params`. \|
40
41	Unexpected exception class names and raw messages never reach the caller. Log internally; do not convert an unexpected exception to `ApiException` with its raw message.
42
43	`WP_Error` messages remain caller-visible for compatibility. Do not put SQL, paths, secrets, or debug data in a returned `WP_Error` message. Arbitrary error data is intentionally not copied into `details`; only the core REST validation `params` map is allowed.
44
45	## 1.1 validation
46
47	`ApiException` requires:
48
49	- status 400–599;
50	- non-empty error code matching `[A-Za-z0-9._:-]+`;
51	- valid HTTP header token names;
52	- header values without CR/LF.
53
54	`Response` accepts status 100–599 and applies the same header-name/value validation. Invalid configuration throws `InvalidArgumentException` before any header is emitted.
55
56	Use the fifth `headers` constructor argument for error metadata such as rate-limit headers. Do not call `header()` directly in a handler.
57
58	## OAuth error format
59
60	Opt in per route only when the client requires RFC 6749 shape:
61
62	```php
63	$router->post('/oauth/token', $handler)
64	->publicRoute()
65	->meta(['error_format' => 'oauth_rfc6749']);
66	```
67
68	```json
69	{
70	"error": "invalid_grant",
71	"error_description": "Authorization code is invalid."
72	}
73	```
74
75	Set `details.error_uri` to emit `error_uri`. Set `details.requestId` to boolean `true` to emit `request_id`; it is not included by default in OAuth format. ApiException headers are preserved.
76
77	## Common codes
78
79	- `400 validation_failed` with `details.fieldErrors`
80	- `400 unknown_parameter`
81	- `400 idempotency_key_required` / `idempotency_key_invalid`
82	- `401 invalid_token` / `invalid_signature`
83	- `403 insufficient_scope` / `forbidden` / `cors_origin_denied`
84	- `404 not_found`
85	- `409 idempotency_conflict` / `idempotency_in_progress`
86	- `409 coupon_exists` / `woo_line_items_locked` / `version_unavailable`
87	- `412 optimistic_lock_failed` or `precondition_failed`
88	- `428 precondition_required`
89	- `429 rate_limited` with `Retry-After` and `X-RateLimit-*`
90	- `503 hpos_required` / `woo_unavailable`
91
92	## Handler pattern
93
94	```php
95	$router->get('/orders/(?P<id>\d+)', static function ($request): array {
96	$id = (int) $request->get_param('id');
97	$order = wc_get_order($id);
98
99	if (!$order) {
100	throw new ApiException('Order not found.', 404, 'not_found', ['id' => $id]);
101	}
102
103	return ['data' => map_order($order)];
104	})->permission(static fn (): bool => current_user_can('manage_woocommerce'));
105	```
106
107	Do not return an ad hoc `['success' => false]` response; it bypasses the stable envelope. A returned `WP_REST_Response` is passed through, so its body is your responsibility.
108
109	## Review checklist
110
111	- Use ApiException only for sanitized caller-facing failures.
112	- Keep unexpected throwable details server-side.
113	- Validate clients against error codes and tolerate added detail keys.
114	- Never expect arbitrary WP_Error data in details.
115	- Assert 429 headers survive through WordPress and CORS exposure.
116	- Test OAuth and default formats independently.
117	- Reject response/error header injection in custom code.
118
119	## Related skills
120
121	- Use `br-write-schema` for validation detail shape.
122	- Use `br-rate-limiting`, `br-idempotency`, and `br-optimistic-locking` for subsystem errors.
123
124	## References
125
126	- Verified source

People who liked this also viewed

6 picks

Type