docs: add TypeScript docs/examples and reorganize by language

[punitarani]

Summary

The docs and examples were Python-only and flat, even though the repo ships a 1:1 TypeScript port (fli-js). This gives both libraries parallel, first-class coverage, and removes maintainer-internal docs from the public site.

Examples (examples/)

• Reorganized into examples/python/ and examples/typescript/.
• Moved the 11 existing Python scripts under examples/python/.
• New Python examples: multi_city_search.py, advanced_filters_search.py (alliances, airline exclusions, layover bounds, currency/locale) — covering capabilities that had no example.
• New TypeScript example set under examples/typescript/ (one-way, round-trip, dates, multi-city, advanced filters, error handling) with a runnable package.json/tsconfig.json and README.
• Top-level + per-language READMEs; dropped the inaccurate "automatic dependency checking" claim (the scripts never implemented it).

Docs (docs/)

• Moved Python docs under docs/python/ (quickstart, examples, api/) and fixed internal links + example paths.
• Added docs/typescript/ (quickstart + examples).
• Rewrote docs/index.md as a dual-language landing page.
• Updated mkdocs nav for the Python/TypeScript split.
• Removed the internal release runbooks (docs/guides/release.md, docs/guides/release-npm.md) — maintainer-only content that doesn't belong on the public docs site. The release process stays summarized in CLAUDE.md and is fully defined by the release*.yml workflows. Fixed the now-dangling references in CLAUDE.md, AGENTS.md, and publish.yml.

README

• Updated example paths (examples/ → examples/python/), added a TypeScript section, and corrected the example list.

Validation

• mkdocs build succeeds with no warnings; verified Python/TypeScript pages build.
• ruff format --check and ruff check pass on all examples.
• New Python example filters were constructed + encode()-d against the real pydantic models (no network) to confirm field names.
• TypeScript examples written against the verified fli-js source API (triple-nested airports [[[Airport.JFK, 0]]], object-literal PassengerInfo, search() locale options).

Notes

• Tests were intentionally not moved into fli/tests: the wheel packages only ["fli"], so root-level tests/ correctly stays out of the published package.
• Independent of chore: remove stale benchmark scripts #183 and refactor: move demo media from data/ to docs/assets/ #184; touches disjoint files/hunks and can merge in any order.

Test plan

• make docs builds without warnings
• make lint passes
• Spot-run uv run python examples/python/multi_city_search.py
• Spot-run bun run examples/typescript/basic_one_way_search.ts (after bun install)

https://claude.ai/code/session_01VPkFrjXBZkS8Cjzc82X5tp

Greptile Summary

This PR reorganizes the flat examples/ and docs/ trees into parallel python/ and typescript/ subtrees, adding first-class TypeScript coverage to match the existing fli-js npm package, and removes maintainer-only release runbooks from the public docs site.

• Six new TypeScript examples (basic_one_way_search, round_trip_search, date_range_search, multi_city_search, advanced_filters_search, error_handling_with_retries) plus a runnable package.json/tsconfig.json; all verified against the fli-js source (triple-nested airports, object-literal PassengerInfo, SearchOptions locale params, Client constructor fields).
• Two new Python examples (multi_city_search.py, advanced_filters_search.py) covering alliances, airline exclusions, layover bounds, and locale options.
• Docs split into docs/python/ and docs/typescript/ with a rewritten landing page, updated mkdocs.yml nav, and deletion of docs/guides/release*.md runbooks; dangling references in CLAUDE.md, AGENTS.md, and publish.yml cleaned up.

Confidence Score: 4/5

Safe to merge — all TypeScript API usage is verified against the fli-js source; the only issues are cosmetic display and doc staleness concerns.

The TypeScript examples correctly use the triple-nested airport format, object-literal PassengerInfo, and all Client/SearchOptions fields. The Python additions also check out against the Pydantic models. The round_trip_search.ts example prints price without a null guard (will show $null for flights where Google omits a price), and the quickstart uses hardcoded dates that will eventually trigger the past-date validation in FlightSegment's constructor. Neither affects library correctness, only the experience of readers who copy the examples verbatim.

docs/typescript/quickstart.md (hardcoded dates), examples/typescript/round_trip_search.ts (null price display), mkdocs.yml (stale site_description)

Important Files Changed

Filename	Overview
examples/typescript/round_trip_search.ts	New round-trip TS example; outbound.price printed without null guard — can emit Total: $null when Google omits a price
examples/typescript/basic_one_way_search.ts	New one-way search example; API usage matches fli-js source (triple-nested airports, object-literal PassengerInfo, SearchOptions)
examples/typescript/advanced_filters_search.ts	New advanced-filters example; alliances, airlines_exclude, layover_restrictions, and locale options all verified against fli-js models
examples/typescript/error_handling_with_retries.ts	New error-handling example; Client constructor options (timeoutMs, retries, backoffMs) and all four error subtypes verified against source
docs/typescript/quickstart.md	New TypeScript quickstart; hardcoded dates (2026-12-25, 2027-01-02) will trigger FlightSegment's past-date guard once they arrive
mkdocs.yml	Nav restructured for Python/TypeScript split; site_description still says "A Python library" despite the new dual-language coverage
examples/typescript/multi_city_search.ts	New multi-city TS example; TripType.MULTI_CITY, three-leg FlightSegment construction, and itinerary reduction all correct
examples/typescript/date_range_search.ts	New date-range search example; DateSearchFilters usage and DatePrice.date[0] access verified against fli-js source
examples/python/multi_city_search.py	New Python multi-city example; TripType, PassengerInfo, and search API usage match existing codebase patterns
examples/python/advanced_filters_search.py	New Python advanced-filters example; LayoverRestrictions, Alliance, and locale params correctly passed to search()
.github/workflows/publish.yml	Removed stale reference to deleted release runbook docs; remaining logic unchanged

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph docs["docs/"]
        DI[index.md\nDual-language landing]
        subgraph dp["python/"]
            DPQ[quickstart.md]
            DPE[examples.md]
            subgraph dpa["api/"]
                DPM[models.md]
                DPS[search.md]
            end
        end
        subgraph dt["typescript/"]
            DTQ[quickstart.md]
            DTE[examples.md]
        end
        DG[guides/mcp.md]
    end
    subgraph examples["examples/"]
        subgraph ep["python/"]
            EP1[basic_one_way_search.py]
            EP3[multi_city_search.py NEW]
            EP4[advanced_filters_search.py NEW]
            EP5[... 8 more]
        end
        subgraph et["typescript/"]
            ET1[basic_one_way_search.ts NEW]
            ET2[round_trip_search.ts NEW]
            ET3[date_range_search.ts NEW]
            ET4[multi_city_search.ts NEW]
            ET5[advanced_filters_search.ts NEW]
            ET6[error_handling_with_retries.ts NEW]
            ET7[package.json / tsconfig.json NEW]
        end
    end
    DI --> dp
    DI --> dt
    DI --> DG
    DTQ --> et
    DPQ --> ep

Loading

Comments Outside Diff (1)

1. mkdocs.yml, line 3 (link)

   The site description still says "A Python library" despite this PR adding a full TypeScript section to the docs.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: mkdocs.yml
   Line: 3
   
   Comment:
   The site description still says "A Python library" despite this PR adding a full TypeScript section to the docs.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
examples/typescript/round_trip_search.ts:52
`outbound.price` is typed `number | null` (`FlightResult.price` can be null when Google doesn't surface a price for premium-cabin results per the JSDoc comment on the type). Printing it directly produces `Total: $null` in those cases.

```suggestion
    console.log(`Total: $${outbound.price ?? "N/A"}`);
```

### Issue 2 of 3
mkdocs.yml:3
The site description still says "A Python library" despite this PR adding a full TypeScript section to the docs.

```suggestion
site_description: Documentation for the Fli library - Python and TypeScript libraries for direct Google Flights API access
```

### Issue 3 of 3
docs/typescript/quickstart.md:36
**Hardcoded travel dates will go stale**

The quickstart uses hardcoded dates (`"2026-12-25"`, `"2027-01-02"`) that will pass, causing `FlightSegment`'s constructor to throw "Travel date cannot be in the past" for anyone who copies the snippet verbatim after those dates arrive. The runnable TypeScript examples use `inDays(N)` to compute dynamic dates — applying the same pattern in the quickstart would keep the samples perpetually valid.

_{Reviews (1): Last reviewed commit: "Merge main into docs-examples-typescript" | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

Context used:

• Context used - CLAUDE.md (source)

[github-actions]

Test Results

    4 files   -   1      4 suites   - 52   1m 17s ⏱️ +21s
  400 tests  - 259    400 ✅  - 259  0 💤 ±0  0 ❌ ±0 
1 600 runs   - 261  1 600 ✅  - 261  0 💤 ±0  0 ❌ ±0 

Results for commit 8054e8a. ± Comparison against base commit e2063b9.

This pull request removes 259 tests.

Airline enum ‑ AIRLINE_NAMES carries the name
Airline enum ‑ CSV-quoted names with embedded commas are unquoted
Airline enum ‑ alliance pseudo-codes are included
Airline enum ‑ digit-prefixed codes use underscore
Airline enum ‑ major carriers are present
Airport CSV quoting ‑ RFC4180 escaped quotes (`""`) decode to a single `"`
Airport CSV quoting ‑ names with embedded commas are unquoted
Airport enum ‑ AIRPORT_NAMES carries the name
Airport enum ‑ common codes are present
Airport enum ‑ enum covers >7000 codes
…

♻️ This comment has been updated with latest results.

[greptile-apps]

outbound.price is typed number | null (FlightResult.price can be null when Google doesn't surface a price for premium-cabin results per the JSDoc comment on the type). Printing it directly produces Total: $null in those cases.

Suggested change

	console.log(`Total: $${outbound.price}`);
	console.log(`Total: $${outbound.price ?? "N/A"}`);

Prompt To Fix With AI

This is a comment left during a code review.
Path: examples/typescript/round_trip_search.ts
Line: 52

Comment:
`outbound.price` is typed `number | null` (`FlightResult.price` can be null when Google doesn't surface a price for premium-cabin results per the JSDoc comment on the type). Printing it directly produces `Total: $null` in those cases.

```suggestion
    console.log(`Total: $${outbound.price ?? "N/A"}`);
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Hardcoded travel dates will go stale

The quickstart uses hardcoded dates ("2026-12-25", "2027-01-02") that will pass, causing FlightSegment's constructor to throw "Travel date cannot be in the past" for anyone who copies the snippet verbatim after those dates arrive. The runnable TypeScript examples use inDays(N) to compute dynamic dates — applying the same pattern in the quickstart would keep the samples perpetually valid.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/typescript/quickstart.md
Line: 36

Comment:
**Hardcoded travel dates will go stale**

The quickstart uses hardcoded dates (`"2026-12-25"`, `"2027-01-02"`) that will pass, causing `FlightSegment`'s constructor to throw "Travel date cannot be in the past" for anyone who copies the snippet verbatim after those dates arrive. The runnable TypeScript examples use `inDays(N)` to compute dynamic dates — applying the same pattern in the quickstart would keep the samples perpetually valid.

How can I resolve this? If you propose a fix, please make it concise.