vaquill 0.1.0__tar.gz

vaquill-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+python/dist/
+
+# Node
+node_modules/
+js/dist/
+*.tgz
+js/test/live/.out/
+
+# Local
+.DS_Store
+.env

vaquill-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vaquill
+
+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.

vaquill-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: vaquill
+Version: 0.1.0
+Summary: Python SDK for the Vaquill US primary law Data API.
+Project-URL: Homepage, https://www.vaquill.ai
+Project-URL: Documentation, https://www.vaquill.ai/docs/api-guide/sdks/overview
+Project-URL: Source, https://github.com/Vaquill-AI/vaquill-sdks/tree/main/python
+Project-URL: Issues, https://github.com/Vaquill-AI/vaquill-sdks/issues
+Author: Vaquill
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,cli,law,legal,legal-data,regulations,sdk,statutes,vaquill
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Description-Content-Type: text/markdown
+
+# vaquill
+
+Python SDK for the Vaquill US primary law Data API: statutes, regulations, court rules, constitutions, session laws and law-change alerts.
+
+Server-side use only: an API key (`vq_key_...`) must never ship to a browser.
+Python 3.11 or newer. Sync and async clients with the same methods.
+
+```python
+from vaquill import Vaquill
+
+client = Vaquill()  # reads VAQUILL_API_KEY; VAQUILL_BASE_URL overrides the host
+
+# 2 credits. Even an unresolved citation is charged: the answer is what you pay for.
+result = client.statutes.resolve("42 U.S.C. 1983")
+if result.resolved and result.section:
+    body = client.statutes.get_section_body(result.section.act_id)  # 6 credits
+    print(body.plain)
+
+hits = client.statutes.search(
+    "statute of limitations for medical malpractice", state="ca"
+)  # 4 credits
+for hit in hits.results:
+    print(hit.citation, hit.section_title)
+print(hits.credits_consumed, client.credits_spent)
+```
+
+Async is the same with `AsyncVaquill` and `await`:
+
+```python
+import asyncio
+from vaquill import AsyncVaquill
+
+
+async def main() -> None:
+    async with AsyncVaquill() as client:
+        balance = await client.credits.balance()
+        print(balance.credits_remaining)
+
+
+asyncio.run(main())
+```
+
+## Namespaces
+
+| Namespace | What it does |
+| --- | --- |
+| `client.statutes` | search, resolve, sections and their text, browse, changes, enactments, rulemaking, cross-references, citation extraction |
+| `client.session_laws` | acts as enacted: search, list, record, text, versions, changes |
+| `client.watches` | law-change alerts by webhook or email |
+| `client.boards` | the sources a watch can follow |
+| `client.credits` | `balance()` |
+| `client.pricing` | `get()` the credit price of every endpoint |
+
+All 36 operations, their method names and which ones cost credits are in [docs/OPERATIONS.md](docs/OPERATIONS.md).
+Required arguments come first and may be positional; optional ones are keyword-only `snake_case` (sent to the API as camelCase).
+
+## Errors
+
+Every failure is a `VaquillError`. Status errors carry `status_code`, `request_id` and the parsed body.
+
+```python
+import vaquill
+
+try:
+    client.statutes.resolve("42 U.S.C. 1983")
+except vaquill.InsufficientCreditsError:
+    ...  # never retried; top up credits
+except vaquill.RateLimitError as err:
+    print(err.retry_after_seconds)  # seconds; the client already retried with backoff
+except vaquill.APIStatusError as err:
+    print(err.status_code, err.request_id)
+```
+
+## Pagination and the credit warning
+
+`iter_*` helpers hide the offset, cursor and `sinceId`/`beforeId` styles behind one iterator.
+**On a charged endpoint every page spends credits.** Iterating a whole result set can cost far more than one call, so always set `max_pages` or `max_items`.
+
+```python
+pager = client.statutes.iter_search(
+    "negligence", state="ny", limit=10, max_pages=3
+)  # at most 12 credits
+for hit in pager:
+    print(hit.citation)
+print(pager.truncated)  # True when the guard stopped it with more available
+
+for page in client.statutes.iter_divisions("STATE", state="wa", max_items=100).pages():
+    ...  # whole pages, to control cost yourself
+```
+
+## Spend guard
+
+```python
+client = Vaquill(
+    max_credits=500
+)  # charged calls raise SpendGuardExceeded once 500 credits are used
+client.credits_spent  # running total across this client and any with_options() copy
+client.pricing.get()  # free: the live price list
+```
+
+Charged calls send an `Idempotency-Key` automatically and are only retried when that is safe.
+Pass `idempotency_key="..."` to any call to supply your own.
+
+## Raw responses
+
+```python
+raw = client.with_raw_response.request(
+    "GET",
+    "/api/v1/us/statutes/resolve",
+    cast_to=dict,
+    params={"cite": "42 U.S.C. 1983"},
+    charged=True,
+)
+raw.request_id, raw.rate_limit.remaining, raw.credits_charged_this_call, raw.parse()
+```
+
+`client.raw_request(method, path, ...)` reaches endpoints newer than this SDK and returns plain JSON.
+
+## Webhooks
+
+Verify the raw request body, never re-serialised JSON.
+
+```python
+from vaquill import verify_webhook, WebhookVerificationError
+
+try:
+    event = verify_webhook(raw_body, request_headers, WEBHOOK_SECRET, allow_legacy=False)
+except WebhookVerificationError:
+    ...  # respond 400
+```
+
+A watch is created with `client.watches.create("state", state="wa", webhook_url=..., webhook_secret=...)`.
+See [examples/](examples/) for runnable versions (`resolve_citation.py`, `search_and_paginate.py`, `watch_and_verify_webhook.py`); the test suite runs them against a fake server.
+
+## Command line
+
+Installing the package also installs a `vaquill` command (standard library only, no extra dependencies).
+
+```bash
+export VAQUILL_API_KEY=vq_key_...
+vaquill resolve "42 U.S.C. 1983"                  # 2 credits
+vaquill search "medical malpractice limitations" --state ca --limit 5 --json
+vaquill section USC_42_1983 --body                # 6 credits
+vaquill credits                                   # free
+vaquill webhook verify --secret "$SECRET" --id "$ID" --timestamp "$TS" --signature "$SIG" < body.json
+```
+
+Charged commands print `credits used: N` on stderr, so stdout stays pipeable.
+Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 no credits, 5 rate limited, 6 not found, 7 network.
+Every command, flag and the JSON shape are in [docs/CLI.md](docs/CLI.md).
+
+## Types
+
+Responses are Pydantic v2 models in `vaquill.types`, generated from `openapi/vaquill-us.json` by `scripts/gen_models.py`.
+Unknown fields are kept and unknown enum values never raise: a field typed `Status | str` holds the enum member for values this SDK knows and the plain string for new ones.
+Every top-level response has `credits_consumed`, `request_id` and `idempotent_replayed`.
+
+## Development
+
+```bash
+.venv/bin/python scripts/gen_models.py   # regenerate src/vaquill/types after changing the spec
+.venv/bin/python scripts/gen_async.py    # regenerate src/vaquill/resources/_async after editing a sync resource
+.venv/bin/python -m pytest -q
+```
+
+The sync resources in `src/vaquill/resources/` are the one hand-written definition; the async ones are derived from them mechanically and a test fails on drift.

vaquill-0.1.0/README.md

@@ -0,0 +1,166 @@
+# vaquill
+
+Python SDK for the Vaquill US primary law Data API: statutes, regulations, court rules, constitutions, session laws and law-change alerts.
+
+Server-side use only: an API key (`vq_key_...`) must never ship to a browser.
+Python 3.11 or newer. Sync and async clients with the same methods.
+
+```python
+from vaquill import Vaquill
+
+client = Vaquill()  # reads VAQUILL_API_KEY; VAQUILL_BASE_URL overrides the host
+
+# 2 credits. Even an unresolved citation is charged: the answer is what you pay for.
+result = client.statutes.resolve("42 U.S.C. 1983")
+if result.resolved and result.section:
+    body = client.statutes.get_section_body(result.section.act_id)  # 6 credits
+    print(body.plain)
+
+hits = client.statutes.search(
+    "statute of limitations for medical malpractice", state="ca"
+)  # 4 credits
+for hit in hits.results:
+    print(hit.citation, hit.section_title)
+print(hits.credits_consumed, client.credits_spent)
+```
+
+Async is the same with `AsyncVaquill` and `await`:
+
+```python
+import asyncio
+from vaquill import AsyncVaquill
+
+
+async def main() -> None:
+    async with AsyncVaquill() as client:
+        balance = await client.credits.balance()
+        print(balance.credits_remaining)
+
+
+asyncio.run(main())
+```
+
+## Namespaces
+
+| Namespace | What it does |
+| --- | --- |
+| `client.statutes` | search, resolve, sections and their text, browse, changes, enactments, rulemaking, cross-references, citation extraction |
+| `client.session_laws` | acts as enacted: search, list, record, text, versions, changes |
+| `client.watches` | law-change alerts by webhook or email |
+| `client.boards` | the sources a watch can follow |
+| `client.credits` | `balance()` |
+| `client.pricing` | `get()` the credit price of every endpoint |
+
+All 36 operations, their method names and which ones cost credits are in [docs/OPERATIONS.md](docs/OPERATIONS.md).
+Required arguments come first and may be positional; optional ones are keyword-only `snake_case` (sent to the API as camelCase).
+
+## Errors
+
+Every failure is a `VaquillError`. Status errors carry `status_code`, `request_id` and the parsed body.
+
+```python
+import vaquill
+
+try:
+    client.statutes.resolve("42 U.S.C. 1983")
+except vaquill.InsufficientCreditsError:
+    ...  # never retried; top up credits
+except vaquill.RateLimitError as err:
+    print(err.retry_after_seconds)  # seconds; the client already retried with backoff
+except vaquill.APIStatusError as err:
+    print(err.status_code, err.request_id)
+```
+
+## Pagination and the credit warning
+
+`iter_*` helpers hide the offset, cursor and `sinceId`/`beforeId` styles behind one iterator.
+**On a charged endpoint every page spends credits.** Iterating a whole result set can cost far more than one call, so always set `max_pages` or `max_items`.
+
+```python
+pager = client.statutes.iter_search(
+    "negligence", state="ny", limit=10, max_pages=3
+)  # at most 12 credits
+for hit in pager:
+    print(hit.citation)
+print(pager.truncated)  # True when the guard stopped it with more available
+
+for page in client.statutes.iter_divisions("STATE", state="wa", max_items=100).pages():
+    ...  # whole pages, to control cost yourself
+```
+
+## Spend guard
+
+```python
+client = Vaquill(
+    max_credits=500
+)  # charged calls raise SpendGuardExceeded once 500 credits are used
+client.credits_spent  # running total across this client and any with_options() copy
+client.pricing.get()  # free: the live price list
+```
+
+Charged calls send an `Idempotency-Key` automatically and are only retried when that is safe.
+Pass `idempotency_key="..."` to any call to supply your own.
+
+## Raw responses
+
+```python
+raw = client.with_raw_response.request(
+    "GET",
+    "/api/v1/us/statutes/resolve",
+    cast_to=dict,
+    params={"cite": "42 U.S.C. 1983"},
+    charged=True,
+)
+raw.request_id, raw.rate_limit.remaining, raw.credits_charged_this_call, raw.parse()
+```
+
+`client.raw_request(method, path, ...)` reaches endpoints newer than this SDK and returns plain JSON.
+
+## Webhooks
+
+Verify the raw request body, never re-serialised JSON.
+
+```python
+from vaquill import verify_webhook, WebhookVerificationError
+
+try:
+    event = verify_webhook(raw_body, request_headers, WEBHOOK_SECRET, allow_legacy=False)
+except WebhookVerificationError:
+    ...  # respond 400
+```
+
+A watch is created with `client.watches.create("state", state="wa", webhook_url=..., webhook_secret=...)`.
+See [examples/](examples/) for runnable versions (`resolve_citation.py`, `search_and_paginate.py`, `watch_and_verify_webhook.py`); the test suite runs them against a fake server.
+
+## Command line
+
+Installing the package also installs a `vaquill` command (standard library only, no extra dependencies).
+
+```bash
+export VAQUILL_API_KEY=vq_key_...
+vaquill resolve "42 U.S.C. 1983"                  # 2 credits
+vaquill search "medical malpractice limitations" --state ca --limit 5 --json
+vaquill section USC_42_1983 --body                # 6 credits
+vaquill credits                                   # free
+vaquill webhook verify --secret "$SECRET" --id "$ID" --timestamp "$TS" --signature "$SIG" < body.json
+```
+
+Charged commands print `credits used: N` on stderr, so stdout stays pipeable.
+Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 no credits, 5 rate limited, 6 not found, 7 network.
+Every command, flag and the JSON shape are in [docs/CLI.md](docs/CLI.md).
+
+## Types
+
+Responses are Pydantic v2 models in `vaquill.types`, generated from `openapi/vaquill-us.json` by `scripts/gen_models.py`.
+Unknown fields are kept and unknown enum values never raise: a field typed `Status | str` holds the enum member for values this SDK knows and the plain string for new ones.
+Every top-level response has `credits_consumed`, `request_id` and `idempotent_replayed`.
+
+## Development
+
+```bash
+.venv/bin/python scripts/gen_models.py   # regenerate src/vaquill/types after changing the spec
+.venv/bin/python scripts/gen_async.py    # regenerate src/vaquill/resources/_async after editing a sync resource
+.venv/bin/python -m pytest -q
+```
+
+The sync resources in `src/vaquill/resources/` are the one hand-written definition; the async ones are derived from them mechanically and a test fails on drift.

vaquill-0.1.0/docs/CLI.md

@@ -0,0 +1,103 @@
+# Command line
+
+`vaquill` is installed with the package.
+It uses only the standard library and the SDK client, so it adds no dependencies.
+Run `vaquill COMMAND --help` for the flags of any command.
+
+## Authentication and global options
+
+The key comes from `--api-key` or the `VAQUILL_API_KEY` variable.
+It is never stored on disk and never printed: error text and `--debug` logs have any `vq_key_` value replaced with `vq_key_[redacted]`.
+
+| Option | Meaning |
+| --- | --- |
+| `--api-key KEY` | API key. Prefer the variable, because a flag is visible in the process list. |
+| `--base-url URL` | API host. Defaults to `VAQUILL_BASE_URL`, then `https://api.vaquill.ai`. |
+| `--timeout SECONDS` | Per-request timeout. |
+| `--max-retries N` | Retries after the first attempt (default 2). |
+| `--max-credits N` | Spend guard: a charged call is refused once N credits have been used in this run. |
+| `--json` | Print the response as JSON on stdout. |
+| `--no-color` | Never use colour. |
+| `--debug` | Log requests to stderr and show a traceback on failure. |
+
+Global options work before or after the command name.
+
+## Commands
+
+| Command | What it does | Cost |
+| --- | --- | --- |
+| `search QUERY [--corpus-type T ...] [--state S] [--limit N] [--offset N]` | Search statutes, regulations and rules | charged |
+| `resolve CITATION` | Resolve a citation to its section | charged |
+| `section ACT_ID [--body]` | A section's metadata, or its text with `--body` | charged |
+| `coverage` | What the corpus holds per jurisdiction | free |
+| `credits` | Your credit balance | free |
+| `pricing` | The credit price of every endpoint | free |
+| `watches list [--limit N] [--offset N]` | List watches | free |
+| `watches create CORPUS_TYPE [--state S] [--channel C] [--webhook-url U] [--webhook-secret S] [--email E]` | Create a watch | free |
+| `watches delete WATCH_ID` | Delete a watch | free |
+| `watches changes WATCH_ID [--limit N] [--since-id N] [--before-id N] [--order asc\|desc]` | Changes a watch recorded | free |
+| `watches deliveries WATCH_ID [--limit N]` | Recent deliveries and delivery health | free |
+| `webhook verify --secret S --id I --timestamp T --signature SIG [--file F] [--tolerance N]` | Verify a Standard Webhooks signature offline | none |
+| `version` | Print the SDK and Python versions | none |
+| `api METHOD PATH [--query K=V ...] [--data JSON] [--limit N] [--charged]` | Call any endpoint and print the JSON | see below |
+
+Prices are not repeated here: run `vaquill pricing` for the live table.
+
+## Output
+
+Human output is a compact table or a list of `key  value` lines, clipped to the terminal width.
+Colour is used only when stdout (or stderr, for messages) is a terminal and `NO_COLOR` is unset and `--no-color` is absent.
+
+`--json` prints the response model dumped by alias, so the keys are the API's camelCase names (`creditsConsumed`, `actId`).
+The shape is the same as the SDK's `model_dump(mode="json", by_alias=True)`.
+`watches delete` prints `{"deleted": true, "id": "..."}`, `version` prints `{"version": ..., "python": ...}` and `webhook verify` prints `{"valid": true, "event": ...}`.
+
+Messages never go to stdout.
+Charged commands print `credits used: N` on stderr after the result, so `vaquill search ... --json | jq` stays clean.
+
+## Pages and cost
+
+The CLI never paginates or loops by itself.
+`search`, `watches list` and `watches changes` make exactly one request.
+When the server reports more results, a notice on stderr names the flag that continues (`--offset N`, `--before-id N`, `--since-id N`).
+Each continued search call is charged again.
+
+## The `api` command
+
+`vaquill api GET /api/v1/watches --query limit=5` sends one request and prints the JSON body.
+`--query` can repeat, and a repeated key becomes a repeated query parameter.
+`--data` takes a JSON string, or `-` to read it from stdin.
+`--limit N` sets the `limit` query parameter.
+The CLI cannot know which paths are charged, so pass `--charged` for one that is.
+That adds an idempotency key, applies `--max-credits` and counts the credits in `credits used`.
+When the body says `hasMore`, a notice names the next page value if the body has one (`nextCursor` or `nextOffset`).
+
+## Webhook verification
+
+```bash
+vaquill webhook verify --secret "$WEBHOOK_SECRET" \
+  --id "$WEBHOOK_ID" --timestamp "$WEBHOOK_TIMESTAMP" --signature "$WEBHOOK_SIGNATURE" \
+  --file body.json
+```
+
+It makes no network call and needs no API key.
+The body must be the exact bytes received: a trailing newline added by `echo` makes the signature fail, so use `--file`, a redirect (`< body.json`) or `printf %s`.
+`--secret` falls back to the `VAQUILL_WEBHOOK_SECRET` variable.
+Timestamps more than `--tolerance` seconds (default 300) from the current time are rejected.
+Only Standard Webhooks headers are accepted; the legacy header has no replay protection.
+The signature is checked before the body is parsed, so a body that is not a Vaquill event still passes with `"event": null`.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Any other error, including a failed webhook verification |
+| 2 | Usage error (bad flag, unreadable file, invalid JSON) |
+| 3 | Authentication: missing or malformed key, HTTP 401 or 403 |
+| 4 | Insufficient credits (HTTP 402) or the `--max-credits` guard |
+| 5 | Rate limited, including the daily cap (HTTP 429) |
+| 6 | Not found (HTTP 404) |
+| 7 | Network failure or timeout |
+
+A failure prints one line to stderr, `error: MESSAGE (status N, code C, request id R)`, and no traceback unless `--debug` is set.

vaquill-0.1.0/docs/OPERATIONS.md

@@ -0,0 +1,89 @@
+# Operations
+
+All 36 operations of the frozen contract (`openapi/vaquill-us.json`, `info.version` 1.0.0), the SDK method for each, and which ones spend credits.
+Each method exists on `Vaquill` and, with `await`, on `AsyncVaquill`.
+`tests/test_operations.py` fails if this table and the spec disagree.
+
+## Charged rule
+
+An operation is **charged** when the spec declares the `Idempotency-Key` header parameter on it.
+That is 25 operations.
+The SDK passes `charged=True` for exactly those: it sends an auto-generated `Idempotency-Key`, retries ambiguous failures safely, checks the `max_credits` spend guard before the call and adds the response's `creditsConsumed` to `client.credits_spent` after it.
+The TypeScript SDK applies the same rule.
+
+Free operations: `list_statutes_coverage`, `list_boards`, the watches operations except `get_watch_change_diff`, `get_credit_balance` and `get_pricing`.
+Prices are not hard-coded here. Call `client.pricing.get()` (free) for the live matrix.
+Some charged calls return `creditsConsumed: 0` (for example a body that is not held); read the figure from the response.
+
+## Naming
+
+The method name is the `operationId` with the namespace noun removed (`search_statutes` is `statutes.search`, `get_session_law_body` is `session_laws.get_body`).
+Where the verb carries meaning it is kept (`get_section`, `get_sections_batch`).
+`get_section_neighbors` is `statutes.neighbors` (the path is `/related`).
+
+## Call shape
+
+* Required parameters (path parameters first, then required query or body members) come first and may be passed by position.
+* Optional parameters are keyword-only, in `snake_case`. The wire name is the API's camelCase (`title_number` is sent as `titleNumber`).
+* Unset optional parameters are not sent, so the server default applies.
+* Every method also accepts `timeout`, `max_retries`, `idempotency_key` and `headers` as keyword arguments.
+* Array parameters take a list. Query arrays are sent as repeated keys.
+
+## Methods
+
+| operationId | SDK method | Route | Cost |
+| --- | --- | --- | --- |
+| `get_section_cited_by` | `client.statutes.cited_by` | GET `/us/statutes/section/{act_id}/cited-by` | charged |
+| `count_statute_sections` | `client.statutes.count` | POST `/us/statutes/count` | charged |
+| `list_statutes_coverage` | `client.statutes.coverage` | GET `/us/statutes/coverage` | free |
+| `get_section_cross_state` | `client.statutes.cross_state` | GET `/us/statutes/section/{act_id}/cross-state` | charged |
+| `get_section_definitions` | `client.statutes.definitions` | GET `/us/statutes/section/{act_id}/definitions` | charged |
+| `list_statute_divisions` | `client.statutes.divisions` | GET `/us/statutes/divisions` | charged |
+| `get_section_enactments` | `client.statutes.enactments` | GET `/us/statutes/section/{act_id}/enactments` | charged |
+| `get_section_rulemaking` | `client.statutes.section_rulemaking` | GET `/us/statutes/section/{act_id}/rulemaking` | charged |
+| `get_part_rulemaking` | `client.statutes.part_rulemaking` | GET `/us/statutes/part/{title}/{part}/rulemaking` | charged |
+| `extract_statute_citations` | `client.statutes.extract_citations` | POST `/us/statutes/extract-citations` | charged |
+| `get_section` | `client.statutes.get_section` | GET `/us/statutes/section/{act_id}` | charged |
+| `get_section_body` | `client.statutes.get_section_body` | GET `/us/statutes/section/{act_id}/body` | charged |
+| `get_sections_batch` | `client.statutes.get_sections_batch` | POST `/us/statutes/sections` | charged |
+| `get_section_neighbors` | `client.statutes.neighbors` | GET `/us/statutes/section/{act_id}/related` | charged |
+| `resolve_statute_citation` | `client.statutes.resolve` | GET `/us/statutes/resolve` | charged |
+| `resolve_statute_citations_batch` | `client.statutes.resolve_batch` | POST `/us/statutes/resolve` | charged |
+| `search_statutes` | `client.statutes.search` | POST `/us/statutes/search` | charged |
+| `get_section_changes` | `client.statutes.section_changes` | GET `/us/statutes/section/{act_id}/changes` | charged |
+| `get_session_law_changes` | `client.session_laws.changes` | GET `/us/session-laws/changes` | charged |
+| `get_session_law` | `client.session_laws.get` | GET `/us/session-laws/{session_law_id}` | charged |
+| `get_session_laws_batch` | `client.session_laws.get_batch` | POST `/us/session-laws/batch` | charged |
+| `get_session_law_body` | `client.session_laws.get_body` | GET `/us/session-laws/{session_law_id}/body` | charged |
+| `list_session_laws` | `client.session_laws.list` | GET `/us/session-laws/list` | charged |
+| `search_session_laws` | `client.session_laws.search` | POST `/us/session-laws/search` | charged |
+| `get_session_law_versions` | `client.session_laws.versions` | GET `/us/session-laws/{session_law_id}/versions` | charged |
+| `get_watch_change_diff` | `client.watches.change_diff` | GET `/watches/{watch_id}/changes/{change_id}/diff` | charged |
+| `list_watch_changes` | `client.watches.changes` | GET `/watches/{watch_id}/changes` | free |
+| `create_watch` | `client.watches.create` | POST `/watches` | free |
+| `delete_watch` | `client.watches.delete` | DELETE `/watches/{watch_id}` | free |
+| `list_watch_deliveries` | `client.watches.deliveries` | GET `/watches/{watch_id}/deliveries` | free |
+| `list_watches` | `client.watches.list` | GET `/watches` | free |
+| `test_watch` | `client.watches.test` | POST `/watches/{watch_id}/test` | free |
+| `update_watch` | `client.watches.update` | PATCH `/watches/{watch_id}` | free |
+| `list_boards` | `client.boards.list` | GET `/boards` | free |
+| `get_credit_balance` | `client.credits.balance` | GET `/credits/balance` | free |
+| `get_pricing` | `client.pricing.get` | GET `/api-credits/pricing` | free |
+
+## Auto-pagination
+
+Each helper returns a `SyncPaginator` (or `AsyncPaginator`).
+Iterate it for items, call `.pages()` for whole pages, read `.truncated` after iterating.
+All accept `max_pages` and `max_items`. On a charged helper every page spends credits, so always set one of them.
+
+| Helper | Wraps | Paging | Cost |
+| --- | --- | --- | --- |
+| `client.statutes.iter_search` | `search_statutes` | offset (`nextOffset`) | charged |
+| `client.statutes.iter_divisions` | `list_statute_divisions` | cursor (`nextCursor`) | charged |
+| `client.statutes.iter_section_changes` | `get_section_changes` | `beforeId` (newest first) or `sinceId` (`order="asc"`) | charged |
+| `client.session_laws.iter_search` | `search_session_laws` | offset (`hasMore`) | charged |
+| `client.session_laws.iter_list` | `list_session_laws` | cursor (`nextCursor`) | charged |
+| `client.session_laws.iter_changes` | `get_session_law_changes` | `sinceId` | charged |
+| `client.watches.iter_list` | `list_watches` | offset | free |
+| `client.watches.iter_changes` | `list_watch_changes` | `beforeId` or `sinceId` (`order="asc"`) | free |
+| `client.boards.iter_list` | `list_boards` | offset (`hasMore`) | free |

vaquill-0.1.0/examples/resolve_citation.py

@@ -0,0 +1,26 @@
+"""Resolve a citation to its section, then read the section text.
+
+VAQUILL_API_KEY=vq_key_... python examples/resolve_citation.py
+"""
+
+from __future__ import annotations
+
+from vaquill import InsufficientCreditsError, Vaquill
+from vaquill.types import StatuteResolveResponse
+
+
+def main(client: Vaquill, cite: str = "42 U.S.C. 1983") -> StatuteResolveResponse | None:
+    try:
+        result = client.statutes.resolve(cite)  # 2 credits, even when it does not resolve
+    except InsufficientCreditsError:
+        print("Out of credits. Top up in the developer dashboard.")
+        return None
+    print(f"{cite}: resolved={result.resolved} charged={result.credits_consumed} credits")
+    if result.resolved and result.section is not None and result.section.act_id:
+        body = client.statutes.get_section_body(result.section.act_id)  # 6 credits
+        print((body.plain or body.content or "")[:200])
+    return result
+
+
+if __name__ == "__main__":
+    main(Vaquill(max_credits=20))

vaquill-0.1.0/examples/search_and_paginate.py

@@ -0,0 +1,29 @@
+"""Search, then page through results with a cost guard.
+
+Every page of a charged endpoint spends credits, so always bound the iteration.
+
+    VAQUILL_API_KEY=vq_key_... python examples/search_and_paginate.py
+"""
+
+from __future__ import annotations
+
+from vaquill import Vaquill
+from vaquill.types import StatuteResult
+
+
+def main(client: Vaquill) -> list[StatuteResult]:
+    first = client.statutes.search("statute of limitations for medical malpractice", state="ca")
+    rows_on_page = len(first.results or [])
+    print(f"{rows_on_page} rows on page one, cost {first.credits_consumed} credits")
+
+    # 2 pages x 4 credits at most. `truncated` tells you more existed.
+    pager = client.statutes.iter_search(
+        "statute of limitations for medical malpractice", state="ca", limit=10, max_pages=2
+    )
+    rows = list(pager)
+    print(f"read {len(rows)} rows, truncated={pager.truncated}, spent={client.credits_spent}")
+    return rows
+
+
+if __name__ == "__main__":
+    main(Vaquill(max_credits=50))