webhooks-cc 0.1.2__tar.gz → 0.2.0__tar.gz

{webhooks_cc-0.1.2 → webhooks_cc-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: webhooks-cc
-Version: 0.1.2
+Version: 0.2.0
 Summary: Python SDK for webhooks.cc: capture, wait for, sign and verify webhooks and test emails
 Project-URL: Homepage, https://webhooks.cc
 Project-URL: Documentation, https://github.com/kroqdotdev/webhooks-cc/tree/main/packages/sdk-python#readme
@@ -53,7 +53,7 @@ with WebhooksCC() as client:
 
 Durations take `"500ms"`, `"30s"`, `"5m"`, `"2h"`, `"7d"`, a `timedelta`, or a number of milliseconds (the unit every webhooks.cc SDK uses, so prefer a string where you mean seconds). Times such as `since` and `Request.received_at` are milliseconds since the epoch.
 
-Matchers combine with `match_all()` and `match_any()`, and any function that takes a `Request` and returns a bool works too: `match_method`, `match_path` (globs with `*` and `**`), `match_header`, `match_query_param`, `match_body_path`, `match_body_subset`, `match_content_type`, `match_verified`, `match_unverified` and `match_email`.
+Matchers combine with `match_all()` and `match_any()`, and any function that takes a `Request` and returns a bool works too: `match_method`, `match_path` (globs: `*` within a segment, `**` across segments, `?` for one character), `match_header`, `match_query_param`, `match_body_path`, `match_body_subset`, `match_content_type`, `match_verified`, `match_unverified` and `match_email`.
 
 ## pytest
 
@@ -87,6 +87,33 @@ link = extract_link(email)          # "https://app.example.com/confirm?token=...
 
 `email.email` holds the parsed message: `subject`, `from_`, `to`, `text`, `html`, attachments, and the SPF, DKIM and DMARC results.
 
+## Email fields, reply text and provider shapes
+
+An endpoint can pick up to 20 named fields out of every email it captures. Each reads the `subject`, `text`, `html`, `from`, `to` or one `header`, and the first group of its RE2 pattern is the value:
+
+```python
+client.endpoints.update(
+    endpoint.slug,
+    email_fields=[{"name": "invoice", "from": "subject", "pattern": r"(INV-\d+)"}],
+)
+email = client.emails.wait_for(endpoint.slug, tag=run)
+email.email_fields  # {"invoice": "INV-2041"}, None for a field that found nothing
+email.reply_text    # what a reply says above the quoted message, without the signature
+```
+
+Forwarding templates read the fields as `{{ fields.invoice }}`. `email_field_issues()` checks a list before you save it (the API checks the patterns themselves).
+
+To test a handler you wrote for an inbound mail provider, render a captured email in that provider's shape and post it there:
+
+```python
+rendered = client.emails.render(email.id, format="postmark")
+response = client.send_to(
+    "http://localhost:8000/inbound/postmark", body=rendered.body, headers=rendered.headers
+)
+```
+
+`format` is `"postmark"`, `"sendgrid"`, `"mailgun"` (pass `mailgun_signing_key` to sign the form as Mailgun does) or `"cloudmailin"`, or `"json"` for the `email.received` JSON.
+
 ## Send signed webhooks to your handler
 
 Test your own webhook handler, on localhost or anywhere else, with requests signed the way the provider signs them:
@@ -118,7 +145,7 @@ valid = verify_signature(
 
 Twilio, Square and HubSpot also need `url`; HubSpot also `method`. Discord takes `public_key`. One function per provider is in `webhooks_cc.verify`.
 
-When webhooks.cc forwards requests or email to your server, check that they came from it with the endpoint's forwarding secret (`client.forwarding.secret(slug)`):
+When webhooks.cc forwards requests or email to your server, check that they came from it with the destination's signing secret (`client.destinations.secret(slug, destination_id)`, or `client.forwarding.secret(slug)` for the endpoint's primary destination):
 
 ```python
 from webhooks_cc import WebhookVerificationError, verify_forwarded_email
@@ -127,10 +154,53 @@ try:
     event = verify_forwarded_email(body, headers, secret)
 except WebhookVerificationError as error:
     return 400 if error.code == "invalid_payload" else 401
-print(event["data"]["subject"])
+print(event["data"]["subject"], event["data"]["replyText"], event["data"].get("fields"))
+```
+
+`verify_forwarded_request()` checks a request forwarded as JSON, `verify_forwarded_json()` a destination's own JSON (it returns the parsed body, whatever its shape), and `verify_relayed_request()` one relayed as it was received.
+
+## Forwarding destinations
+
+An endpoint forwards what it captures to up to 10 destinations, each with its own kinds, filter, format, headers, retries, throttle, delay and signing secret:
+
+```python
+destination = client.destinations.create(
+    endpoint.slug,
+    url="https://hooks.example.com/invoices",
+    email=False,
+    filter={
+        "conditions": [{"field": "body_path", "path": "type", "op": "eq", "value": "invoice.paid"}]
+    },
+    format="template",
+    body_template={
+        "invoice": "{{ json.data.object.id }}",
+        "amount": "{{ json.data.object.amount_paid }}",
+    },
+)
+preview = client.destinations.preview(endpoint.slug, destination_id=destination.id)
+print(preview.filter_passes, preview.delivery.body if preview.delivery else preview.error)
+```
+
+Filters take the conditions of response rules, plus `kind`, `email` (with `name` `subject`, `from`, `to`, `text` or `tag`), `spam_score`, `email_auth` (with `name` `spf`, `dkim` or `dmarc`) and `signature`. `format` may also be an inbound mail provider's shape (`"postmark"`, `"sendgrid"`, `"mailgun"` or `"cloudmailin"`): emails go out as that provider posts them and HTTP requests as received. `mailgun_signing_key` signs the Mailgun form; it is never returned, and `has_mailgun_signing_key` says whether one is saved. `preview()` is a dry run: pass a saved `destination_id`, unsaved fields in `destination` (the names `create()` takes), or both. `update()` changes only the arguments you pass, `test()` sends one delivery now and reports the answer, and `list()` (with `summary=True` for the last 24 hours), `get()`, `delete()`, `reorder()`, `secret()` and `rotate_secret()` do what they say.
+
+## Mock responses and response rules
+
+An endpoint answers with `mock_response` instead of a plain 200 OK, or with the first of its `response_rules` whose conditions match the request (method, path, header, query, body, body_path, content_type or size). Bodies and header values may hold `{{ placeholders }}` filled in from each request, such as `{{ json.id }}`. Check what a sender would get back without sending anything:
+
+```python
+preview = client.endpoints.preview_response(
+    endpoint.slug,
+    response_rules=[
+        {
+            "conditions": [{"field": "body_path", "path": "type", "op": "eq", "value": "ping"}],
+            "response": {"status": 202, "body": '{"pong": "{{ json.id }}"}', "headers": {}},
+        }
+    ],
+)
+print(preview.rule, preview.response.status if preview.response else 200)
 ```
 
-`verify_forwarded_request()` checks a request forwarded as JSON, and `verify_relayed_request()` one relayed as it was received.
+It runs against the endpoint's newest HTTP request unless you pass `request_id`, and uses the saved settings unless you pass `mock_response` or `response_rules` (`None` tries none at all). `client.endpoints.update(slug, response_rules=[...])` saves them.
 
 ## Stream requests as they arrive
 
@@ -141,7 +211,7 @@ for request in client.requests.subscribe(endpoint.slug, timeout="10m", reconnect
 
 ## Errors
 
-API errors raise `WebhooksCCError` with a `status_code`, or one of its subclasses: `UnauthorizedError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retry_after`) and `TimeoutError`, which is also Python's built-in `TimeoutError`. Network failures raise httpx's exceptions. Retries are off unless you pass `retry=RetryOptions(max_attempts=3)`.
+API errors raise `WebhooksCCError` with a `status_code`, or one of its subclasses: `UnauthorizedError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retry_after`) and `TimeoutError`, which is also Python's built-in `TimeoutError`. Network failures raise httpx's exceptions. Retries are off unless you pass `retry=RetryOptions(max_attempts=3)`. They repeat GET, PUT and DELETE calls after a network error, a timeout or a status in `retry_on` (429, 500, 502, 503 and 504 by default), and any call after a 429; a POST or PATCH that failed any other way may have gone through, so it is not repeated, and neither is `requests.clear()` without `before`.
 
 ## Same behaviour as the TypeScript SDK
 

{webhooks_cc-0.1.2 → webhooks_cc-0.2.0}/README.md

@@ -29,7 +29,7 @@ with WebhooksCC() as client:
 
 Durations take `"500ms"`, `"30s"`, `"5m"`, `"2h"`, `"7d"`, a `timedelta`, or a number of milliseconds (the unit every webhooks.cc SDK uses, so prefer a string where you mean seconds). Times such as `since` and `Request.received_at` are milliseconds since the epoch.
 
-Matchers combine with `match_all()` and `match_any()`, and any function that takes a `Request` and returns a bool works too: `match_method`, `match_path` (globs with `*` and `**`), `match_header`, `match_query_param`, `match_body_path`, `match_body_subset`, `match_content_type`, `match_verified`, `match_unverified` and `match_email`.
+Matchers combine with `match_all()` and `match_any()`, and any function that takes a `Request` and returns a bool works too: `match_method`, `match_path` (globs: `*` within a segment, `**` across segments, `?` for one character), `match_header`, `match_query_param`, `match_body_path`, `match_body_subset`, `match_content_type`, `match_verified`, `match_unverified` and `match_email`.
 
 ## pytest
 
@@ -63,6 +63,33 @@ link = extract_link(email)          # "https://app.example.com/confirm?token=...
 
 `email.email` holds the parsed message: `subject`, `from_`, `to`, `text`, `html`, attachments, and the SPF, DKIM and DMARC results.
 
+## Email fields, reply text and provider shapes
+
+An endpoint can pick up to 20 named fields out of every email it captures. Each reads the `subject`, `text`, `html`, `from`, `to` or one `header`, and the first group of its RE2 pattern is the value:
+
+```python
+client.endpoints.update(
+    endpoint.slug,
+    email_fields=[{"name": "invoice", "from": "subject", "pattern": r"(INV-\d+)"}],
+)
+email = client.emails.wait_for(endpoint.slug, tag=run)
+email.email_fields  # {"invoice": "INV-2041"}, None for a field that found nothing
+email.reply_text    # what a reply says above the quoted message, without the signature
+```
+
+Forwarding templates read the fields as `{{ fields.invoice }}`. `email_field_issues()` checks a list before you save it (the API checks the patterns themselves).
+
+To test a handler you wrote for an inbound mail provider, render a captured email in that provider's shape and post it there:
+
+```python
+rendered = client.emails.render(email.id, format="postmark")
+response = client.send_to(
+    "http://localhost:8000/inbound/postmark", body=rendered.body, headers=rendered.headers
+)
+```
+
+`format` is `"postmark"`, `"sendgrid"`, `"mailgun"` (pass `mailgun_signing_key` to sign the form as Mailgun does) or `"cloudmailin"`, or `"json"` for the `email.received` JSON.
+
 ## Send signed webhooks to your handler
 
 Test your own webhook handler, on localhost or anywhere else, with requests signed the way the provider signs them:
@@ -94,7 +121,7 @@ valid = verify_signature(
 
 Twilio, Square and HubSpot also need `url`; HubSpot also `method`. Discord takes `public_key`. One function per provider is in `webhooks_cc.verify`.
 
-When webhooks.cc forwards requests or email to your server, check that they came from it with the endpoint's forwarding secret (`client.forwarding.secret(slug)`):
+When webhooks.cc forwards requests or email to your server, check that they came from it with the destination's signing secret (`client.destinations.secret(slug, destination_id)`, or `client.forwarding.secret(slug)` for the endpoint's primary destination):
 
 ```python
 from webhooks_cc import WebhookVerificationError, verify_forwarded_email
@@ -103,10 +130,53 @@ try:
     event = verify_forwarded_email(body, headers, secret)
 except WebhookVerificationError as error:
     return 400 if error.code == "invalid_payload" else 401
-print(event["data"]["subject"])
+print(event["data"]["subject"], event["data"]["replyText"], event["data"].get("fields"))
+```
+
+`verify_forwarded_request()` checks a request forwarded as JSON, `verify_forwarded_json()` a destination's own JSON (it returns the parsed body, whatever its shape), and `verify_relayed_request()` one relayed as it was received.
+
+## Forwarding destinations
+
+An endpoint forwards what it captures to up to 10 destinations, each with its own kinds, filter, format, headers, retries, throttle, delay and signing secret:
+
+```python
+destination = client.destinations.create(
+    endpoint.slug,
+    url="https://hooks.example.com/invoices",
+    email=False,
+    filter={
+        "conditions": [{"field": "body_path", "path": "type", "op": "eq", "value": "invoice.paid"}]
+    },
+    format="template",
+    body_template={
+        "invoice": "{{ json.data.object.id }}",
+        "amount": "{{ json.data.object.amount_paid }}",
+    },
+)
+preview = client.destinations.preview(endpoint.slug, destination_id=destination.id)
+print(preview.filter_passes, preview.delivery.body if preview.delivery else preview.error)
+```
+
+Filters take the conditions of response rules, plus `kind`, `email` (with `name` `subject`, `from`, `to`, `text` or `tag`), `spam_score`, `email_auth` (with `name` `spf`, `dkim` or `dmarc`) and `signature`. `format` may also be an inbound mail provider's shape (`"postmark"`, `"sendgrid"`, `"mailgun"` or `"cloudmailin"`): emails go out as that provider posts them and HTTP requests as received. `mailgun_signing_key` signs the Mailgun form; it is never returned, and `has_mailgun_signing_key` says whether one is saved. `preview()` is a dry run: pass a saved `destination_id`, unsaved fields in `destination` (the names `create()` takes), or both. `update()` changes only the arguments you pass, `test()` sends one delivery now and reports the answer, and `list()` (with `summary=True` for the last 24 hours), `get()`, `delete()`, `reorder()`, `secret()` and `rotate_secret()` do what they say.
+
+## Mock responses and response rules
+
+An endpoint answers with `mock_response` instead of a plain 200 OK, or with the first of its `response_rules` whose conditions match the request (method, path, header, query, body, body_path, content_type or size). Bodies and header values may hold `{{ placeholders }}` filled in from each request, such as `{{ json.id }}`. Check what a sender would get back without sending anything:
+
+```python
+preview = client.endpoints.preview_response(
+    endpoint.slug,
+    response_rules=[
+        {
+            "conditions": [{"field": "body_path", "path": "type", "op": "eq", "value": "ping"}],
+            "response": {"status": 202, "body": '{"pong": "{{ json.id }}"}', "headers": {}},
+        }
+    ],
+)
+print(preview.rule, preview.response.status if preview.response else 200)
 ```
 
-`verify_forwarded_request()` checks a request forwarded as JSON, and `verify_relayed_request()` one relayed as it was received.
+It runs against the endpoint's newest HTTP request unless you pass `request_id`, and uses the saved settings unless you pass `mock_response` or `response_rules` (`None` tries none at all). `client.endpoints.update(slug, response_rules=[...])` saves them.
 
 ## Stream requests as they arrive
 
@@ -117,7 +187,7 @@ for request in client.requests.subscribe(endpoint.slug, timeout="10m", reconnect
 
 ## Errors
 
-API errors raise `WebhooksCCError` with a `status_code`, or one of its subclasses: `UnauthorizedError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retry_after`) and `TimeoutError`, which is also Python's built-in `TimeoutError`. Network failures raise httpx's exceptions. Retries are off unless you pass `retry=RetryOptions(max_attempts=3)`.
+API errors raise `WebhooksCCError` with a `status_code`, or one of its subclasses: `UnauthorizedError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retry_after`) and `TimeoutError`, which is also Python's built-in `TimeoutError`. Network failures raise httpx's exceptions. Retries are off unless you pass `retry=RetryOptions(max_attempts=3)`. They repeat GET, PUT and DELETE calls after a network error, a timeout or a status in `retry_on` (429, 500, 502, 503 and 504 by default), and any call after a 429; a POST or PATCH that failed any other way may have gone through, so it is not repeated, and neither is `requests.clear()` without `before`.
 
 ## Same behaviour as the TypeScript SDK
 

{webhooks_cc-0.1.2 → webhooks_cc-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webhooks-cc"
-version = "0.1.2"
+version = "0.2.0"
 description = "Python SDK for webhooks.cc: capture, wait for, sign and verify webhooks and test emails"
 readme = "README.md"
 license = "MIT"

{webhooks_cc-0.1.2 → webhooks_cc-0.2.0}/src/webhooks_cc/__init__.py

@@ -16,13 +16,23 @@ your own handlers, and verify provider and forwarding signatures.
 Every signature check for each provider is in :mod:`webhooks_cc.verify`.
 """
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
-from .client import Emails, Endpoints, Forwarding, Requests, RetryOptions, WebhooksCC
+from .client import (
+    Destinations,
+    Emails,
+    Endpoints,
+    Forwarding,
+    Requests,
+    RetryOptions,
+    WebhooksCC,
+)
 from .durations import Duration, parse_duration
 from .email import (
     DEFAULT_EMAIL_DOMAIN,
+    INBOUND_EMAIL_FORMATS,
     email_address,
+    email_field_issues,
     extract_code,
     extract_link,
     is_valid_email_tag,
@@ -53,14 +63,31 @@ from .matchers import (
 )
 from .models import (
     BuiltRequest,
+    DeliveryCounts,
+    Destination,
+    DestinationFilter,
+    DestinationFormat,
+    DestinationHeader,
+    DestinationPreview,
+    DestinationRequest,
+    DestinationSummary,
+    DestinationTestResult,
     EmailAddress,
     EmailAttachment,
     EmailCapture,
     EmailExtracts,
+    EmailField,
     Endpoint,
     ExtractedLink,
+    PreviewedDelivery,
+    PreviewedResponse,
+    PreviewRequest,
+    PreviewRule,
+    RenderedEmail,
     Request,
     RequestPage,
+    ResponsePreview,
+    SenderTime,
     SendTestEmailResult,
     TeamShare,
     UsageInfo,
@@ -76,6 +103,7 @@ from .testing import capture_during, capture_email_during, temporary_endpoint
 from .verify import (
     RelayedRequestInfo,
     verify_forwarded_email,
+    verify_forwarded_json,
     verify_forwarded_request,
     verify_relayed_request,
     verify_signature,
@@ -83,15 +111,27 @@ from .verify import (
 
 __all__ = [
     "DEFAULT_EMAIL_DOMAIN",
+    "INBOUND_EMAIL_FORMATS",
     "TEMPLATE_METADATA",
     "TEMPLATE_PROVIDERS",
     "VERIFY_PROVIDERS",
     "BuiltRequest",
+    "DeliveryCounts",
+    "Destination",
+    "DestinationFilter",
+    "DestinationFormat",
+    "DestinationHeader",
+    "DestinationPreview",
+    "DestinationRequest",
+    "DestinationSummary",
+    "DestinationTestResult",
+    "Destinations",
     "Duration",
     "EmailAddress",
     "EmailAttachment",
     "EmailCapture",
     "EmailExtracts",
+    "EmailField",
     "Emails",
     "Endpoint",
     "Endpoints",
@@ -99,13 +139,20 @@ __all__ = [
     "Forwarding",
     "Matcher",
     "NotFoundError",
+    "PreviewRequest",
+    "PreviewRule",
+    "PreviewedDelivery",
+    "PreviewedResponse",
     "RateLimitError",
     "RelayedRequestInfo",
+    "RenderedEmail",
     "Request",
     "RequestPage",
     "Requests",
+    "ResponsePreview",
     "RetryOptions",
     "SendTestEmailResult",
+    "SenderTime",
     "TeamShare",
     "TemplateProviderInfo",
     "TimeoutError",
@@ -119,6 +166,7 @@ __all__ = [
     "capture_during",
     "capture_email_during",
     "email_address",
+    "email_field_issues",
     "extract_code",
     "extract_link",
     "is_email_request",
@@ -138,6 +186,7 @@ __all__ = [
     "parse_duration",
     "temporary_endpoint",
     "verify_forwarded_email",
+    "verify_forwarded_json",
     "verify_forwarded_request",
     "verify_relayed_request",
     "verify_signature",

{webhooks_cc-0.1.2 → webhooks_cc-0.2.0}/src/webhooks_cc/_crypto.py

@@ -13,9 +13,11 @@ import hmac
 import json
 import math
 import re
-from collections.abc import Mapping, Sequence
+from collections.abc import Iterable, Mapping, Sequence
 from typing import Any, Literal
 
+from ._js import js_trim
+
 HashName = Literal["sha256", "sha1"]
 
 _BASE64_ALPHABET = re.compile(r"^[A-Za-z0-9+/]*$")
@@ -69,7 +71,7 @@ def from_base64(value: str) -> bytes:
 
 
 def hex_to_bytes(value: str) -> bytes:
-    normalized = value.strip()
+    normalized = js_trim(value)
     if not _HEX.match(normalized) or len(normalized) % 2 != 0:
         raise ValueError("Expected a hex-encoded value")
     return bytes.fromhex(normalized)
@@ -217,7 +219,9 @@ def js_string(value: Any) -> str:
 def js_json(value: Any) -> str:
     """Serialize like JavaScript's ``JSON.stringify(value)``.
 
-    Compact, keys in their order, non-ASCII characters left as they are.
+    Compact, keys in the order a JavaScript object keeps them (array-index keys
+    such as ``"2"`` first, ascending, then the rest as inserted), non-ASCII
+    characters left as they are.
     """
     parts: list[str] = []
     _write_json(value, parts)
@@ -238,11 +242,11 @@ def _write_json(value: Any, out: list[str]) -> None:
     elif isinstance(value, Mapping):
         out.append("{")
         first = True
-        for key, item in value.items():
+        for key, item in _js_key_order(value.items()):
             if not first:
                 out.append(",")
             first = False
-            out.append(json.dumps(str(key), ensure_ascii=False))
+            out.append(json.dumps(key, ensure_ascii=False))
             out.append(":")
             _write_json(item, out)
         out.append("}")
@@ -257,6 +261,22 @@ def _write_json(value: Any, out: list[str]) -> None:
         raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
 
 
+def _is_array_index(key: str) -> bool:
+    """Whether a JavaScript object treats ``key`` as an array index (0 to 2**32 - 2)."""
+    if not (key.isascii() and key.isdigit()) or (len(key) > 1 and key[0] == "0"):
+        return False
+    return int(key) < 2**32 - 1
+
+
+def _js_key_order(items: Iterable[tuple[Any, Any]]) -> list[tuple[str, Any]]:
+    """Members in the order a JavaScript object enumerates them."""
+    members = [(str(key), item) for key, item in items]
+    indexes = sorted((m for m in members if _is_array_index(m[0])), key=lambda m: int(m[0]))
+    if not indexes:
+        return members
+    return indexes + [m for m in members if not _is_array_index(m[0])]
+
+
 def json_body(value: Any) -> str:
     """A request body: strings are sent as they are, anything else as JSON."""
     return value if isinstance(value, str) else js_json(value)

webhooks_cc-0.2.0/src/webhooks_cc/_js.py

@@ -0,0 +1,66 @@
+"""Text read the way JavaScript reads it.
+
+The TypeScript SDK is the reference, so where it trims a string, reads a number
+or matches ``\\s`` and ``\\d``, this port must treat the same characters the same
+way. Python's own rules differ: ``str.strip()`` and ``\\s`` also take
+``\\x1c``-``\\x1f`` and ``\\x85`` but not ``\\ufeff``, and ``\\d`` and ``float()``
+accept digits from every script.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from typing import Any
+
+# What String.prototype.trim(), Number() and a regular expression's \s treat as whitespace.
+JS_WHITESPACE = "".join(
+    chr(code)
+    for code in (
+        *(0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x20, 0xA0, 0x1680),
+        *range(0x2000, 0x200B),
+        *(0x2028, 0x2029, 0x202F, 0x205F, 0x3000, 0xFEFF),
+    )
+)
+
+# A regular-expression class equal to JavaScript's \s.
+JS_SPACE = f"[{re.escape(JS_WHITESPACE)}]"
+
+_JS_DECIMAL = re.compile(r"[+-]?(?:Infinity|(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?)")
+# One digit class per base: int() would also take a second prefix ("0x0x10").
+_JS_RADIX = re.compile(r"0(?:[xX]([0-9a-fA-F]+)|[oO]([0-7]+)|[bB]([01]+))")
+
+
+def js_trim(value: str) -> str:
+    """JavaScript's ``value.trim()``."""
+    return value.strip(JS_WHITESPACE)
+
+
+def js_to_number(value: str | None) -> float:
+    """JavaScript's ``Number(value)`` for a string: NaN when it is not a number, 0 when blank."""
+    if value is None:
+        return math.nan
+    text = js_trim(value)
+    if text == "":
+        return 0.0
+    if _JS_DECIMAL.fullmatch(text):
+        return float(text.replace("Infinity", "inf"))
+    radix_match = _JS_RADIX.fullmatch(text)
+    if radix_match:
+        hex_digits, octal_digits, binary_digits = radix_match.groups()
+        if hex_digits is not None:
+            return float(int(hex_digits, 16))
+        if octal_digits is not None:
+            return float(int(octal_digits, 8))
+        return float(int(binary_digits, 2))
+    return math.nan
+
+
+def _reject_constant(name: str) -> Any:
+    raise ValueError(f"{name} is not JSON")
+
+
+def json_parse(text: str | bytes) -> Any:
+    """JavaScript's ``JSON.parse``: ``json.loads`` without NaN and Infinity, which it refuses."""
+    return json.loads(text, parse_constant=_reject_constant)