nextflight 0.3.0__tar.gz

nextflight-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aly Reda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nextflight-0.3.0/PKG-INFO

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: nextflight
+Version: 0.3.0
+Summary: Parse Next.js App Router 'Flight' (__next_f.push) payloads embedded in server-rendered HTML -- works on any Next.js 13+ site.
+Author: Aly Reda
+License: MIT
+Project-URL: Homepage, https://github.com/Aly-Reda/nextflight
+Project-URL: Issues, https://github.com/Aly-Reda/nextflight/issues
+Keywords: nextjs,scraping,scrapy,flight,rsc,react-server-components,web-scraping,zyte
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nextflight
+
+A general-purpose parser for the data Next.js (App Router) embeds in
+`<script>self.__next_f.push([...])</script>` tags — the React Server
+Components "Flight" wire format. Works on **any** Next.js 13+ App Router
+site, not just one particular project.
+
+Instead of hardcoding array indices like `data[3]["children"][0][3]...`,
+which break the moment a site's component tree reshuffles on redeploy,
+`nextflight` resolves the `$`-sigil references Next.js uses internally
+and lets you *search* for the shape of data you want.
+
+## Install
+
+```bash
+pip install nextflight
+```
+
+## Quick start
+
+The core workflow is two steps: hand it any HTML, see what keys are on
+the page, then fetch the resolved JSON for whichever key you want.
+
+```python
+from nextflight import extract
+
+# Step 1: send any HTML, get the list of keys (one per __next_f.push chunk)
+page = extract(html_text)
+print(page.keys())          # e.g. ['0', '1', '3f', '20', ...]
+
+# Step 2: fetch the resolved JSON for a specific key
+data = page["3f"]           # same as page.resolve_chunk("3f")
+```
+
+Chunk ids are arbitrary per build though (a redeploy can renumber them),
+so in practice you'll usually skip straight to *searching* for the shape
+of data you want instead of a specific id:
+
+```python
+from nextflight import extract
+
+page = extract(html_text)
+
+# Find the first object anywhere in the page that has all of these keys,
+# wherever this build's component tree happened to put it:
+listing = page.find_by_keys({"sections", "meta"})
+
+# Find every node with a given @type (or any custom key):
+products = page.find_by_type("Product")
+
+# Or search with a fully custom predicate:
+items = page.find_all(lambda n: isinstance(n, dict) and "price" in n)
+
+# Or grab everything, fully dereferenced, and inspect by hand:
+everything = page.resolve_all()
+```
+
+### Command line
+
+For quick, no-script exploration of a page you've already saved (or a live URL):
+
+```bash
+nextflight page.html --keys sections,meta
+nextflight https://example.com/product/123 --type Product
+nextflight page.html --all > everything.json
+```
+
+### In a Scrapy / Zyte spider
+
+```python
+import scrapy
+from nextflight import extract
+
+class MySpider(scrapy.Spider):
+    name = "my_spider"
+
+    def parse(self, response):
+        page = extract(response.text)
+
+        items = page.find_all(
+            lambda n: isinstance(n, dict) and "price" in n and "title" in n
+        )
+        for item in items:
+            yield {
+                "title": item.get("title"),
+                "price": item.get("price"),
+                "url": response.url,
+            }
+```
+
+### Fetching a URL directly (no Scrapy needed)
+
+```python
+from nextflight import FlightExtractor
+
+page = FlightExtractor.from_url("https://example.com/product/123")
+product = page.find_by_keys({"price", "title"})
+```
+
+(`from_url` uses only the stdlib for quick one-off exploration. For
+production crawling — retries, proxies, JS rendering, robots.txt — fetch
+the page with your own HTTP client / Scrapy / Zyte and pass
+`response.text` to `FlightExtractor(...)` / `extract(...)` instead.)
+
+## API
+
+- **`extract(html) -> FlightExtractor`** — shorthand constructor. `html`
+  accepts a plain string, bytes, or a response-like object (Scrapy's
+  `Response`, `requests.Response`, etc.) — pass `response` straight from a
+  `parse()` method without writing `response.text` yourself.
+- **`FlightExtractor(html, *, strict: bool = False)`**
+  - `.keys() -> list[str]` — every chunk id found on the page, in order.
+  - `page["3f"]` / `.resolve_chunk("3f")` — the resolved JSON for one
+    specific chunk id (`page[...]` raises `KeyError` if it doesn't exist;
+    `resolve_chunk` returns `None`). `"3f" in page` and `for k in page`
+    also work, like a dict.
+  - `.resolve_all() -> dict` — every chunk, fully dereferenced.
+  - `.find_all(predicate, root=None, max_results=None) -> list` — walk the
+    resolved tree and collect every node matching `predicate`.
+  - `.find_one(predicate, root=None) -> Any | None`
+  - `.find_by_keys(required_keys, root=None) -> dict | None` — find the
+    first dict containing all of `required_keys`.
+  - `.find_all_by_keys(required_keys, root=None) -> list` — like
+    `find_by_keys` but returns every match, for pages with repeated
+    cards/listings that share the same shape.
+  - `.find_by_type(type_value, key="@type", root=None) -> list` — find
+    every dict whose `key` field equals `type_value`.
+  - `.find_text(pattern, root=None) -> list` — regex-search every string
+    value on the page and return the distinct whole values that contain a
+    match (emails, prices, phone numbers, SKUs, ...) without needing to
+    know which object they live on.
+  - `.get("path.to.value", default=None) -> Any` — tolerant dotted-path
+    lookup into the resolved page (dict keys and/or list indices), once
+    you already know roughly where something lives on this site.
+  - `.stats() -> dict` — quick diagnostic snapshot (chunk count, ids,
+    value type counts, page size) for exploring a new site.
+  - `.to_json(path=None, indent=2) -> str | None` — dump the fully
+    resolved page to a file, or return it as a JSON string.
+  - `.from_url(url, timeout=15.0, headers=None) -> FlightExtractor`
+    (classmethod) — fetch and parse a URL using only the stdlib.
+  - `strict=True` raises `FlightParseError` on a row that's neither valid
+    JSON nor a recognizable `$`-reference marker, instead of silently
+    keeping it as a raw string (useful while developing a new scraper;
+    leave off in production so a handful of odd rows never take down
+    extraction of everything else on the page).
+- **`find_json_ld(html, type_=None) -> list`** — parse any
+  `<script type="application/ld+json">` blocks on the page, optionally
+  filtered by `@type`. Also accepts response-like objects.
+- **CLI**: `nextflight <file-or-url> [--keys a,b | --all-by-keys a,b | --type Product | --text PATTERN | --get path.to.value | --stats | --all] [--save out.json]`
+
+No runtime dependencies — stdlib only (`json`, `re`, `urllib`, `argparse`)
+— so it's safe to drop into any existing Scrapy/Zyte project without
+touching the rest of your dependency tree.
+
+### Upgrading from `nextjs-flight-extractor` / `NextFlightExtractor`
+
+The old names still work but emit a `DeprecationWarning`:
+
+| Old (0.1.x)                          | New (0.2.x+)                     |
+|---------------------------------------|----------------------------------|
+| `from nextjs_flight_extractor import NextFlightExtractor` | `from nextflight import FlightExtractor` |
+| `extractor.find_first(...)`           | `page.find_one(...)`            |
+| `extract_json_ld(html, schema_type=…)`| `find_json_ld(html, type_=…)`   |
+
+## Why not just `str.split('\n')`?
+
+Two of the Flight row kinds break that assumption:
+
+- **Text rows** (`id:T<hexByteLen>,<raw text>`) are byte-length-prefixed
+  blobs, not newline-terminated, and can contain literal newlines or run
+  directly into the next row's id with zero separator.
+- **Module / preload rows** (`id:I[...]` / `:HL[...]`) need bracket-aware
+  parsing.
+
+`nextflight` implements the real row grammar, quote/escape aware, so it
+holds up on both well-formed and truncated payloads (e.g. from a proxy
+that cuts a response off mid-chunk).
+
+## Building / publishing
+
+### Manual (twine)
+
+```bash
+pip install build twine
+python -m build              # produces dist/*.whl and dist/*.tar.gz
+twine check dist/*           # validate metadata before uploading
+twine upload dist/*          # publish to PyPI (or use --repository testpypi for a dry run)
+```
+
+### Automatic (GitHub Actions + PyPI Trusted Publishing)
+
+This repo ships with `.github/workflows/ci.yml`, which:
+- runs the test suite on every push/PR across Python 3.9–3.12,
+- builds and validates the sdist/wheel,
+- publishes to PyPI automatically whenever a tag like `v0.2.1` is pushed.
+
+Publishing uses PyPI's **Trusted Publisher** flow — no API token stored in
+GitHub secrets. One-time setup:
+
+1. On [pypi.org](https://pypi.org), go to your project → *Publishing* →
+   *Add a new publisher* (or, for a brand-new project name, do this from
+   your PyPI account's "Trusted Publishers" management page before the
+   project exists yet).
+2. Fill in: Owner = your GitHub username/org, Repository = this repo's
+   name, Workflow name = `ci.yml`, Environment name = `pypi`.
+3. In your GitHub repo, go to *Settings → Environments*, create an
+   environment named `pypi` (optionally require a manual approval before
+   deploys, for extra safety).
+4. Release a new version:
+   ```bash
+   # bump version in pyproject.toml and src/nextflight/__init__.py first
+   git commit -am "Release v0.2.2"
+   git tag v0.2.2
+   git push origin main --tags
+   ```
+   The workflow builds, tests, and publishes automatically.
+
+
+## License
+
+MIT

nextflight-0.3.0/README.md

@@ -0,0 +1,221 @@
+# nextflight
+
+A general-purpose parser for the data Next.js (App Router) embeds in
+`<script>self.__next_f.push([...])</script>` tags — the React Server
+Components "Flight" wire format. Works on **any** Next.js 13+ App Router
+site, not just one particular project.
+
+Instead of hardcoding array indices like `data[3]["children"][0][3]...`,
+which break the moment a site's component tree reshuffles on redeploy,
+`nextflight` resolves the `$`-sigil references Next.js uses internally
+and lets you *search* for the shape of data you want.
+
+## Install
+
+```bash
+pip install nextflight
+```
+
+## Quick start
+
+The core workflow is two steps: hand it any HTML, see what keys are on
+the page, then fetch the resolved JSON for whichever key you want.
+
+```python
+from nextflight import extract
+
+# Step 1: send any HTML, get the list of keys (one per __next_f.push chunk)
+page = extract(html_text)
+print(page.keys())          # e.g. ['0', '1', '3f', '20', ...]
+
+# Step 2: fetch the resolved JSON for a specific key
+data = page["3f"]           # same as page.resolve_chunk("3f")
+```
+
+Chunk ids are arbitrary per build though (a redeploy can renumber them),
+so in practice you'll usually skip straight to *searching* for the shape
+of data you want instead of a specific id:
+
+```python
+from nextflight import extract
+
+page = extract(html_text)
+
+# Find the first object anywhere in the page that has all of these keys,
+# wherever this build's component tree happened to put it:
+listing = page.find_by_keys({"sections", "meta"})
+
+# Find every node with a given @type (or any custom key):
+products = page.find_by_type("Product")
+
+# Or search with a fully custom predicate:
+items = page.find_all(lambda n: isinstance(n, dict) and "price" in n)
+
+# Or grab everything, fully dereferenced, and inspect by hand:
+everything = page.resolve_all()
+```
+
+### Command line
+
+For quick, no-script exploration of a page you've already saved (or a live URL):
+
+```bash
+nextflight page.html --keys sections,meta
+nextflight https://example.com/product/123 --type Product
+nextflight page.html --all > everything.json
+```
+
+### In a Scrapy / Zyte spider
+
+```python
+import scrapy
+from nextflight import extract
+
+class MySpider(scrapy.Spider):
+    name = "my_spider"
+
+    def parse(self, response):
+        page = extract(response.text)
+
+        items = page.find_all(
+            lambda n: isinstance(n, dict) and "price" in n and "title" in n
+        )
+        for item in items:
+            yield {
+                "title": item.get("title"),
+                "price": item.get("price"),
+                "url": response.url,
+            }
+```
+
+### Fetching a URL directly (no Scrapy needed)
+
+```python
+from nextflight import FlightExtractor
+
+page = FlightExtractor.from_url("https://example.com/product/123")
+product = page.find_by_keys({"price", "title"})
+```
+
+(`from_url` uses only the stdlib for quick one-off exploration. For
+production crawling — retries, proxies, JS rendering, robots.txt — fetch
+the page with your own HTTP client / Scrapy / Zyte and pass
+`response.text` to `FlightExtractor(...)` / `extract(...)` instead.)
+
+## API
+
+- **`extract(html) -> FlightExtractor`** — shorthand constructor. `html`
+  accepts a plain string, bytes, or a response-like object (Scrapy's
+  `Response`, `requests.Response`, etc.) — pass `response` straight from a
+  `parse()` method without writing `response.text` yourself.
+- **`FlightExtractor(html, *, strict: bool = False)`**
+  - `.keys() -> list[str]` — every chunk id found on the page, in order.
+  - `page["3f"]` / `.resolve_chunk("3f")` — the resolved JSON for one
+    specific chunk id (`page[...]` raises `KeyError` if it doesn't exist;
+    `resolve_chunk` returns `None`). `"3f" in page` and `for k in page`
+    also work, like a dict.
+  - `.resolve_all() -> dict` — every chunk, fully dereferenced.
+  - `.find_all(predicate, root=None, max_results=None) -> list` — walk the
+    resolved tree and collect every node matching `predicate`.
+  - `.find_one(predicate, root=None) -> Any | None`
+  - `.find_by_keys(required_keys, root=None) -> dict | None` — find the
+    first dict containing all of `required_keys`.
+  - `.find_all_by_keys(required_keys, root=None) -> list` — like
+    `find_by_keys` but returns every match, for pages with repeated
+    cards/listings that share the same shape.
+  - `.find_by_type(type_value, key="@type", root=None) -> list` — find
+    every dict whose `key` field equals `type_value`.
+  - `.find_text(pattern, root=None) -> list` — regex-search every string
+    value on the page and return the distinct whole values that contain a
+    match (emails, prices, phone numbers, SKUs, ...) without needing to
+    know which object they live on.
+  - `.get("path.to.value", default=None) -> Any` — tolerant dotted-path
+    lookup into the resolved page (dict keys and/or list indices), once
+    you already know roughly where something lives on this site.
+  - `.stats() -> dict` — quick diagnostic snapshot (chunk count, ids,
+    value type counts, page size) for exploring a new site.
+  - `.to_json(path=None, indent=2) -> str | None` — dump the fully
+    resolved page to a file, or return it as a JSON string.
+  - `.from_url(url, timeout=15.0, headers=None) -> FlightExtractor`
+    (classmethod) — fetch and parse a URL using only the stdlib.
+  - `strict=True` raises `FlightParseError` on a row that's neither valid
+    JSON nor a recognizable `$`-reference marker, instead of silently
+    keeping it as a raw string (useful while developing a new scraper;
+    leave off in production so a handful of odd rows never take down
+    extraction of everything else on the page).
+- **`find_json_ld(html, type_=None) -> list`** — parse any
+  `<script type="application/ld+json">` blocks on the page, optionally
+  filtered by `@type`. Also accepts response-like objects.
+- **CLI**: `nextflight <file-or-url> [--keys a,b | --all-by-keys a,b | --type Product | --text PATTERN | --get path.to.value | --stats | --all] [--save out.json]`
+
+No runtime dependencies — stdlib only (`json`, `re`, `urllib`, `argparse`)
+— so it's safe to drop into any existing Scrapy/Zyte project without
+touching the rest of your dependency tree.
+
+### Upgrading from `nextjs-flight-extractor` / `NextFlightExtractor`
+
+The old names still work but emit a `DeprecationWarning`:
+
+| Old (0.1.x)                          | New (0.2.x+)                     |
+|---------------------------------------|----------------------------------|
+| `from nextjs_flight_extractor import NextFlightExtractor` | `from nextflight import FlightExtractor` |
+| `extractor.find_first(...)`           | `page.find_one(...)`            |
+| `extract_json_ld(html, schema_type=…)`| `find_json_ld(html, type_=…)`   |
+
+## Why not just `str.split('\n')`?
+
+Two of the Flight row kinds break that assumption:
+
+- **Text rows** (`id:T<hexByteLen>,<raw text>`) are byte-length-prefixed
+  blobs, not newline-terminated, and can contain literal newlines or run
+  directly into the next row's id with zero separator.
+- **Module / preload rows** (`id:I[...]` / `:HL[...]`) need bracket-aware
+  parsing.
+
+`nextflight` implements the real row grammar, quote/escape aware, so it
+holds up on both well-formed and truncated payloads (e.g. from a proxy
+that cuts a response off mid-chunk).
+
+## Building / publishing
+
+### Manual (twine)
+
+```bash
+pip install build twine
+python -m build              # produces dist/*.whl and dist/*.tar.gz
+twine check dist/*           # validate metadata before uploading
+twine upload dist/*          # publish to PyPI (or use --repository testpypi for a dry run)
+```
+
+### Automatic (GitHub Actions + PyPI Trusted Publishing)
+
+This repo ships with `.github/workflows/ci.yml`, which:
+- runs the test suite on every push/PR across Python 3.9–3.12,
+- builds and validates the sdist/wheel,
+- publishes to PyPI automatically whenever a tag like `v0.2.1` is pushed.
+
+Publishing uses PyPI's **Trusted Publisher** flow — no API token stored in
+GitHub secrets. One-time setup:
+
+1. On [pypi.org](https://pypi.org), go to your project → *Publishing* →
+   *Add a new publisher* (or, for a brand-new project name, do this from
+   your PyPI account's "Trusted Publishers" management page before the
+   project exists yet).
+2. Fill in: Owner = your GitHub username/org, Repository = this repo's
+   name, Workflow name = `ci.yml`, Environment name = `pypi`.
+3. In your GitHub repo, go to *Settings → Environments*, create an
+   environment named `pypi` (optionally require a manual approval before
+   deploys, for extra safety).
+4. Release a new version:
+   ```bash
+   # bump version in pyproject.toml and src/nextflight/__init__.py first
+   git commit -am "Release v0.2.2"
+   git tag v0.2.2
+   git push origin main --tags
+   ```
+   The workflow builds, tests, and publishes automatically.
+
+
+## License
+
+MIT

nextflight-0.3.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nextflight"
+version = "0.3.0"
+description = "Parse Next.js App Router 'Flight' (__next_f.push) payloads embedded in server-rendered HTML -- works on any Next.js 13+ site."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { name = "Aly Reda" }
+]
+keywords = ["nextjs", "scraping", "scrapy", "flight", "rsc", "react-server-components", "web-scraping", "zyte"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# Stdlib only -- no runtime dependencies, so it's safe to drop into any
+# Scrapy / Zyte project without touching the rest of your dependency tree.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Aly-Reda/nextflight"
+Issues = "https://github.com/Aly-Reda/nextflight/issues"
+
+[project.scripts]
+nextflight = "nextflight.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

nextflight-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nextflight-0.3.0/src/nextflight/__init__.py

@@ -0,0 +1,68 @@
+"""
+nextflight
+==========
+
+Generic parser for the React Server Components "Flight" wire format that
+Next.js 13+ (App Router) embeds in ``<script>self.__next_f.push([...])</script>``
+tags. Works on any Next.js App Router site.
+
+    from nextflight import extract
+
+    page = extract(html_text)
+    listing = page.find_by_keys({"sections", "meta"})
+"""
+
+import warnings
+
+from .extractor import (
+    FlightExtractor,
+    FlightParseError,
+    extract,
+    find_json_ld,
+)
+
+__all__ = [
+    "FlightExtractor",
+    "FlightParseError",
+    "extract",
+    "find_json_ld",
+    "NextFlightExtractor",  # deprecated alias, see below
+    "extract_json_ld",      # deprecated alias, see below
+]
+
+__version__ = "0.3.0"
+
+
+# ---------------------------------------------------------------------- #
+# Backwards-compatible aliases for the pre-rename API (nextjs_flight_extractor
+# 0.1.x). These will be removed in a future major version -- switch to
+# FlightExtractor / find_json_ld when convenient.
+# ---------------------------------------------------------------------- #
+class NextFlightExtractor(FlightExtractor):
+    """Deprecated alias for :class:`FlightExtractor`. Use ``FlightExtractor`` instead."""
+
+    def __init__(self, *args, **kwargs):
+        warnings.warn(
+            "NextFlightExtractor is deprecated, use nextflight.FlightExtractor instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)
+
+    def find_first(self, *args, **kwargs):
+        warnings.warn(
+            "find_first() is deprecated, use find_one() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.find_one(*args, **kwargs)
+
+
+def extract_json_ld(html: str, schema_type=None) -> list:
+    """Deprecated alias for :func:`find_json_ld`. Use ``find_json_ld`` instead."""
+    warnings.warn(
+        "extract_json_ld() is deprecated, use nextflight.find_json_ld() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return find_json_ld(html, type_=schema_type)

nextflight-0.3.0/src/nextflight/cli.py

@@ -0,0 +1,86 @@
+"""
+Command-line entry point for quick exploration:
+
+    nextflight page.html --keys sections,meta
+    nextflight https://example.com/product/123 --keys price,title
+    nextflight page.html --all > everything.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .extractor import FlightExtractor
+
+
+def _load_html(source: str) -> str:
+    if source.startswith("http://") or source.startswith("https://"):
+        extractor = FlightExtractor.from_url(source)
+        return extractor.html
+    with open(source, "r", encoding="utf-8") as f:
+        return f.read()
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="nextflight",
+        description="Extract Next.js Flight (__next_f.push) data from a page.",
+    )
+    parser.add_argument("source", help="Path to an HTML file, or a URL to fetch.")
+    parser.add_argument(
+        "--keys", help="Comma-separated keys: find the first object containing all of them."
+    )
+    parser.add_argument(
+        "--all-by-keys", dest="all_by_keys",
+        help="Comma-separated keys: find EVERY object containing all of them (not just the first).",
+    )
+    parser.add_argument(
+        "--type", dest="type_value",
+        help='Find every object whose "@type" (or --type-key) equals this value.',
+    )
+    parser.add_argument("--type-key", default="@type", help='Key to match --type against (default "@type").')
+    parser.add_argument("--text", dest="text_pattern", help="Regex: list every distinct string value on the page that matches it.")
+    parser.add_argument("--get", dest="get_path", help='Dotted path into the resolved page, e.g. "3f.props.price".')
+    parser.add_argument("--all", action="store_true", help="Dump every resolved chunk.")
+    parser.add_argument("--stats", action="store_true", help="Print a quick diagnostic summary instead of data.")
+    parser.add_argument("--save", dest="save_path", help="Write output to this file instead of stdout.")
+    parser.add_argument("--indent", type=int, default=2, help="JSON indent for output (default 2).")
+    args = parser.parse_args(argv)
+
+    html = _load_html(args.source)
+    extractor = FlightExtractor(html)
+
+    if args.keys:
+        keys = {k.strip() for k in args.keys.split(",") if k.strip()}
+        result = extractor.find_by_keys(keys)
+    elif args.all_by_keys:
+        keys = {k.strip() for k in args.all_by_keys.split(",") if k.strip()}
+        result = extractor.find_all_by_keys(keys)
+    elif args.type_value:
+        result = extractor.find_by_type(args.type_value, key=args.type_key)
+    elif args.text_pattern:
+        result = extractor.find_text(args.text_pattern)
+    elif args.get_path:
+        result = extractor.get(args.get_path)
+    elif args.stats:
+        result = extractor.stats()
+    elif args.all:
+        result = extractor.resolve_all()
+    else:
+        parser.error("Provide one of --keys, --all-by-keys, --type, --text, --get, --stats, or --all.")
+        return 2
+
+    output = json.dumps(result, indent=args.indent, ensure_ascii=False, default=str)
+    if args.save_path:
+        with open(args.save_path, "w", encoding="utf-8") as f:
+            f.write(output)
+    else:
+        sys.stdout.write(output)
+        sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())