blitz-api-py 2.1.0__tar.gz → 3.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/CHANGELOG.md +18 -0
  2. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/PKG-INFO +47 -13
  3. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/README.md +45 -11
  4. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/__init__.py +5 -2
  5. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_base_client.py +7 -5
  6. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_client_async.py +13 -2
  7. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_client_sync.py +13 -2
  8. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_exceptions.py +54 -4
  9. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_async.py +1 -1
  10. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_base.py +8 -3
  11. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_sync.py +1 -1
  12. blitz_api_py-3.0.0/src/blitz_api/_version.py +1 -0
  13. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/__init__.py +8 -0
  14. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/account.py +1 -1
  15. blitz_api_py-3.0.0/src/blitz_api/resources/_async/changelog.py +53 -0
  16. blitz_api_py-3.0.0/src/blitz_api/resources/_async/company.py +55 -0
  17. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/account.py +1 -1
  18. blitz_api_py-3.0.0/src/blitz_api/resources/_sync/changelog.py +55 -0
  19. blitz_api_py-3.0.0/src/blitz_api/resources/_sync/company.py +57 -0
  20. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/__init__.py +14 -0
  21. blitz_api_py-3.0.0/src/blitz_api/types/_models.py +74 -0
  22. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/account.py +5 -3
  23. blitz_api_py-3.0.0/src/blitz_api/types/changelog.py +58 -0
  24. blitz_api_py-3.0.0/src/blitz_api/types/company.py +31 -0
  25. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/enrichment.py +10 -10
  26. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/filters.py +23 -0
  27. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/search.py +2 -2
  28. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/utils.py +2 -2
  29. blitz_api_py-2.1.0/src/blitz_api/_version.py +0 -1
  30. blitz_api_py-2.1.0/src/blitz_api/types/_models.py +0 -23
  31. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/.gitignore +0 -0
  32. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/LICENSE +0 -0
  33. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/pyproject.toml +0 -0
  34. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_client.py +0 -0
  35. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_compat.py +0 -0
  36. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_constants.py +0 -0
  37. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit.py +0 -0
  38. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit_async.py +0 -0
  39. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  40. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/py.typed +0 -0
  41. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  42. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/enrichment.py +0 -0
  43. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/jobs.py +0 -0
  44. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/search.py +0 -0
  45. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/utils.py +0 -0
  46. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  47. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/enrichment.py +0 -0
  48. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
  49. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/search.py +0 -0
  50. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  51. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/enums.py +0 -0
  52. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/jobs.py +0 -0
  53. {blitz_api_py-2.1.0 → blitz_api_py-3.0.0}/src/blitz_api/types/shared.py +0 -0
@@ -1,5 +1,23 @@
1
1
  # Changelog
2
2
 
3
+ ## [3.0.0](https://github.com/api-blitz/blitz-api-py/compare/v2.2.0...v3.0.0) (2026-09-02)
4
+
5
+
6
+ ### ⚠ BREAKING CHANGES
7
+
8
+ * `KeyInfo.remaining_credits` is renamed to `KeyInfo.records_remaining`.
9
+
10
+ ### Features
11
+
12
+ * records vocabulary rename + fair_usage envelope on every response ([698fd6d](https://github.com/api-blitz/blitz-api-py/commit/698fd6dc95bbe6120c55064255820898b708da42))
13
+
14
+ ## [2.2.0](https://github.com/api-blitz/blitz-api-py/compare/v2.1.0...v2.2.0) (2026-08-13)
15
+
16
+
17
+ ### Features
18
+
19
+ * add company and changelog resources with new endpoints ([0dd4ae0](https://github.com/api-blitz/blitz-api-py/commit/0dd4ae0df510352c72143f00431e66b947409758))
20
+
3
21
  ## [2.1.0](https://github.com/api-blitz/blitz-api-py/compare/v2.0.0...v2.1.0) (2026-07-23)
4
22
 
5
23
 
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 2.1.0
3
+ Version: 3.0.0
4
4
  Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
5
5
  Project-URL: Homepage, https://blitz-api.ai
6
6
  Project-URL: Documentation, https://docs.blitz-api.ai
@@ -53,7 +53,7 @@ and enrichment.
53
53
 
54
54
  > **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
55
55
  > loop streams every match up to the server-side limit (people: 50k results), which can be
56
- > a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
56
+ > a lot of records. Bound spend with **`max_items`** (a client-side total cap on
57
57
  > `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
58
58
  > [Pagination](#pagination).
59
59
 
@@ -65,6 +65,7 @@ and enrichment.
65
65
  - [Authentication](#authentication)
66
66
  - [Endpoints](#endpoints)
67
67
  - [Pagination](#pagination)
68
+ - [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
68
69
  - [Configuration](#configuration)
69
70
  - [Error handling](#error-handling)
70
71
  - [Forward compatibility](#forward-compatibility)
@@ -89,7 +90,7 @@ from blitz_api.types import Industry, JobLevel
89
90
  with BlitzAPI() as client:
90
91
  # Health-check the key before a batch job.
91
92
  info = client.account.key_info()
92
- print(info.valid, info.remaining_credits, info.max_requests_per_seconds)
93
+ print(info.valid, info.records_remaining, info.max_requests_per_seconds)
93
94
 
94
95
  # LinkedIn profile URL -> verified work email.
95
96
  email = client.enrichment.email(
@@ -117,7 +118,7 @@ from blitz_api import AsyncBlitzAPI
117
118
  async def main() -> None:
118
119
  async with AsyncBlitzAPI() as client:
119
120
  result = await client.enrichment.company(
120
- company_linkedin_url="https://www.linkedin.com/company/openai",
121
+ company_linkedin_url="https://www.linkedin.com/company/placeholder-co",
121
122
  )
122
123
  print(result.company.name if result.company else None)
123
124
 
@@ -127,7 +128,7 @@ asyncio.run(main())
127
128
  ## Example: find, enrich, collect
128
129
 
129
130
  A complete flow — find people, enrich each one's verified work email, collect the
130
- contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
131
+ contacts. `max_items` caps the total fetched so the run can't surprise you with records.
131
132
 
132
133
  ```python
133
134
  from blitz_api import BlitzAPI
@@ -140,7 +141,7 @@ leads = client.search.people(
140
141
  company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
141
142
  people={"job_level": [JobLevel.VP]},
142
143
  max_results=25,
143
- ).collect(max_items=25) # client-side total cap — bounds credit spend
144
+ ).collect(max_items=25) # client-side total cap — bounds record spend
144
145
 
145
146
  # 2. Enrich each lead's verified work email from their LinkedIn profile URL.
146
147
  contacts: list[dict[str, str | None]] = []
@@ -193,15 +194,17 @@ always call the API from your backend.
193
194
 
194
195
  ## Endpoints
195
196
 
196
- All methods are grouped into five namespaces:
197
+ All methods are grouped into seven namespaces:
197
198
 
198
199
  | Namespace | Methods |
199
200
  | --- | --- |
200
201
  | `client.account` | `key_info()` |
201
202
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
202
203
  | `client.jobs` | `search()`, `company()` |
204
+ | `client.company` | `tam_by_jobs()` |
203
205
  | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
204
206
  | `client.utils` | `current_date()` |
207
+ | `client.changelog` | `list()` |
205
208
 
206
209
  Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
207
210
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
@@ -215,9 +218,9 @@ fetches each subsequent page for you. `search.people`/`search.companies` and
215
218
  all behave identically here.
216
219
 
217
220
  > **`max_results` is the page size, not a total.** It's results per page, and the API
218
- > **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
221
+ > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
219
222
  > loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
220
- > employee finder: 10k; jobs: 5k), which can be a lot of credits. Bound it with **`max_items`** on
223
+ > employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
221
224
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
222
225
  > `break` out of the loop, or drive pages manually.
223
226
 
@@ -254,6 +257,37 @@ nxt = page.get_next_page() # None once exhausted
254
257
  The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
255
258
  exported from `blitz_api`.
256
259
 
260
+ ## Usage & rate limit (`fair_usage`)
261
+
262
+ Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
263
+ the plan, your rate-limit headroom, and a request id to quote to support. It's on every
264
+ response model and on every page, so you can meter a long run without extra `key_info()`
265
+ calls.
266
+
267
+ ```python
268
+ result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
269
+ if result.fair_usage is not None:
270
+ print(result.fair_usage.records_used) # what this call cost
271
+ print(result.fair_usage.records_remaining) # a number, or "unlimited"
272
+ print(result.fair_usage.next_reset_at) # None on an unlimited plan
273
+ print(result.fair_usage.request_id) # quote this to support
274
+ if result.fair_usage.rate_limit is not None: # absent on account.key_info()
275
+ print(result.fair_usage.rate_limit.remaining_this_second)
276
+
277
+ # Pages carry the block of the request that fetched them.
278
+ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
279
+ print(page.fair_usage.records_used if page.fair_usage else None)
280
+ ```
281
+
282
+ `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
283
+ resets without a second call:
284
+
285
+ ```python
286
+ except InsufficientRecordsError as err:
287
+ if err.fair_usage is not None:
288
+ print("resets at", err.fair_usage.next_reset_at)
289
+ ```
290
+
257
291
  ## Configuration
258
292
 
259
293
  ```python
@@ -286,15 +320,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
286
320
 
287
321
  ```python
288
322
  from blitz_api import (
289
- BlitzError, AuthenticationError, InsufficientCreditsError,
323
+ BlitzError, AuthenticationError, InsufficientRecordsError,
290
324
  NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
291
325
  APITimeoutError, APIResponseValidationError,
292
326
  )
293
327
 
294
328
  try:
295
329
  client.enrichment.email(person_linkedin_url="...")
296
- except InsufficientCreditsError:
297
- ... # 402 — out of credits
330
+ except InsufficientRecordsError as err:
331
+ ... # 402 — out of records; err.fair_usage.next_reset_at
298
332
  except AuthenticationError:
299
333
  ... # 401 — bad key
300
334
  except APIStatusError as err:
@@ -22,7 +22,7 @@ and enrichment.
22
22
 
23
23
  > **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
24
24
  > loop streams every match up to the server-side limit (people: 50k results), which can be
25
- > a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
25
+ > a lot of records. Bound spend with **`max_items`** (a client-side total cap on
26
26
  > `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
27
27
  > [Pagination](#pagination).
28
28
 
@@ -34,6 +34,7 @@ and enrichment.
34
34
  - [Authentication](#authentication)
35
35
  - [Endpoints](#endpoints)
36
36
  - [Pagination](#pagination)
37
+ - [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
37
38
  - [Configuration](#configuration)
38
39
  - [Error handling](#error-handling)
39
40
  - [Forward compatibility](#forward-compatibility)
@@ -58,7 +59,7 @@ from blitz_api.types import Industry, JobLevel
58
59
  with BlitzAPI() as client:
59
60
  # Health-check the key before a batch job.
60
61
  info = client.account.key_info()
61
- print(info.valid, info.remaining_credits, info.max_requests_per_seconds)
62
+ print(info.valid, info.records_remaining, info.max_requests_per_seconds)
62
63
 
63
64
  # LinkedIn profile URL -> verified work email.
64
65
  email = client.enrichment.email(
@@ -86,7 +87,7 @@ from blitz_api import AsyncBlitzAPI
86
87
  async def main() -> None:
87
88
  async with AsyncBlitzAPI() as client:
88
89
  result = await client.enrichment.company(
89
- company_linkedin_url="https://www.linkedin.com/company/openai",
90
+ company_linkedin_url="https://www.linkedin.com/company/placeholder-co",
90
91
  )
91
92
  print(result.company.name if result.company else None)
92
93
 
@@ -96,7 +97,7 @@ asyncio.run(main())
96
97
  ## Example: find, enrich, collect
97
98
 
98
99
  A complete flow — find people, enrich each one's verified work email, collect the
99
- contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
100
+ contacts. `max_items` caps the total fetched so the run can't surprise you with records.
100
101
 
101
102
  ```python
102
103
  from blitz_api import BlitzAPI
@@ -109,7 +110,7 @@ leads = client.search.people(
109
110
  company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
110
111
  people={"job_level": [JobLevel.VP]},
111
112
  max_results=25,
112
- ).collect(max_items=25) # client-side total cap — bounds credit spend
113
+ ).collect(max_items=25) # client-side total cap — bounds record spend
113
114
 
114
115
  # 2. Enrich each lead's verified work email from their LinkedIn profile URL.
115
116
  contacts: list[dict[str, str | None]] = []
@@ -162,15 +163,17 @@ always call the API from your backend.
162
163
 
163
164
  ## Endpoints
164
165
 
165
- All methods are grouped into five namespaces:
166
+ All methods are grouped into seven namespaces:
166
167
 
167
168
  | Namespace | Methods |
168
169
  | --- | --- |
169
170
  | `client.account` | `key_info()` |
170
171
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
171
172
  | `client.jobs` | `search()`, `company()` |
173
+ | `client.company` | `tam_by_jobs()` |
172
174
  | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
173
175
  | `client.utils` | `current_date()` |
176
+ | `client.changelog` | `list()` |
174
177
 
175
178
  Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
176
179
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
@@ -184,9 +187,9 @@ fetches each subsequent page for you. `search.people`/`search.companies` and
184
187
  all behave identically here.
185
188
 
186
189
  > **`max_results` is the page size, not a total.** It's results per page, and the API
187
- > **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
190
+ > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
188
191
  > loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
189
- > employee finder: 10k; jobs: 5k), which can be a lot of credits. Bound it with **`max_items`** on
192
+ > employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
190
193
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
191
194
  > `break` out of the loop, or drive pages manually.
192
195
 
@@ -223,6 +226,37 @@ nxt = page.get_next_page() # None once exhausted
223
226
  The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
224
227
  exported from `blitz_api`.
225
228
 
229
+ ## Usage & rate limit (`fair_usage`)
230
+
231
+ Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
232
+ the plan, your rate-limit headroom, and a request id to quote to support. It's on every
233
+ response model and on every page, so you can meter a long run without extra `key_info()`
234
+ calls.
235
+
236
+ ```python
237
+ result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
238
+ if result.fair_usage is not None:
239
+ print(result.fair_usage.records_used) # what this call cost
240
+ print(result.fair_usage.records_remaining) # a number, or "unlimited"
241
+ print(result.fair_usage.next_reset_at) # None on an unlimited plan
242
+ print(result.fair_usage.request_id) # quote this to support
243
+ if result.fair_usage.rate_limit is not None: # absent on account.key_info()
244
+ print(result.fair_usage.rate_limit.remaining_this_second)
245
+
246
+ # Pages carry the block of the request that fetched them.
247
+ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
248
+ print(page.fair_usage.records_used if page.fair_usage else None)
249
+ ```
250
+
251
+ `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
252
+ resets without a second call:
253
+
254
+ ```python
255
+ except InsufficientRecordsError as err:
256
+ if err.fair_usage is not None:
257
+ print("resets at", err.fair_usage.next_reset_at)
258
+ ```
259
+
226
260
  ## Configuration
227
261
 
228
262
  ```python
@@ -255,15 +289,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
255
289
 
256
290
  ```python
257
291
  from blitz_api import (
258
- BlitzError, AuthenticationError, InsufficientCreditsError,
292
+ BlitzError, AuthenticationError, InsufficientRecordsError,
259
293
  NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
260
294
  APITimeoutError, APIResponseValidationError,
261
295
  )
262
296
 
263
297
  try:
264
298
  client.enrichment.email(person_linkedin_url="...")
265
- except InsufficientCreditsError:
266
- ... # 402 — out of credits
299
+ except InsufficientRecordsError as err:
300
+ ... # 402 — out of records; err.fair_usage.next_reset_at
267
301
  except AuthenticationError:
268
302
  ... # 401 — bad key
269
303
  except APIStatusError as err:
@@ -23,7 +23,8 @@ from ._exceptions import (
23
23
  APITimeoutError,
24
24
  AuthenticationError,
25
25
  BlitzError,
26
- InsufficientCreditsError,
26
+ InsufficientCreditsError, # pyright: ignore[reportDeprecated]
27
+ InsufficientRecordsError,
27
28
  NotFoundError,
28
29
  RateLimitError,
29
30
  ServerError,
@@ -54,10 +55,12 @@ __all__ = [
54
55
  "APIResponseValidationError",
55
56
  "APIStatusError",
56
57
  "AuthenticationError",
57
- "InsufficientCreditsError",
58
+ "InsufficientRecordsError",
58
59
  "NotFoundError",
59
60
  "RateLimitError",
60
61
  "ServerError",
62
+ # deprecated alias (removed in 3.0.0)
63
+ "InsufficientCreditsError",
61
64
  # commonly-used types (full set under blitz_api.types)
62
65
  "Industry",
63
66
  "CompanyFilter",
@@ -16,7 +16,7 @@ from typing import Any, TypeVar, cast
16
16
  from urllib.parse import urljoin
17
17
 
18
18
  import httpx
19
- from pydantic import ValidationError
19
+ from pydantic import BaseModel, ValidationError
20
20
 
21
21
  from . import _constants as C
22
22
  from ._exceptions import (
@@ -24,20 +24,22 @@ from ._exceptions import (
24
24
  APIStatusError,
25
25
  AuthenticationError,
26
26
  BlitzError,
27
- InsufficientCreditsError,
27
+ InsufficientRecordsError,
28
28
  NotFoundError,
29
29
  RateLimitError,
30
30
  ServerError,
31
31
  )
32
- from .types._models import BlitzModel
33
32
 
34
- ResponseT = TypeVar("ResponseT", bound=BlitzModel)
33
+ # Bound to ``pydantic.BaseModel`` (not ``BlitzModel``) so the request pipeline can also
34
+ # validate a ``RootModel`` — used for ``changelog.list``'s top-level JSON array
35
+ # (``ChangelogResponse``), which is a ``BaseModel`` but not a ``BlitzModel``.
36
+ ResponseT = TypeVar("ResponseT", bound=BaseModel)
35
37
 
36
38
  # Status code -> exception class. Anything not listed that is still non-2xx
37
39
  # falls back to a generic APIStatusError (or ServerError for any 5xx).
38
40
  _STATUS_EXCEPTIONS: dict[int, type[APIStatusError]] = {
39
41
  401: AuthenticationError,
40
- 402: InsufficientCreditsError,
42
+ 402: InsufficientRecordsError,
41
43
  404: NotFoundError,
42
44
  429: RateLimitError,
43
45
  }
@@ -16,6 +16,8 @@ from ._pagination_base import BasePage
16
16
  from ._rate_limit import AsyncRateLimiter
17
17
  from .resources import (
18
18
  AsyncAccountResource,
19
+ AsyncChangelogResource,
20
+ AsyncCompanyResource,
19
21
  AsyncEnrichmentResource,
20
22
  AsyncJobsResource,
21
23
  AsyncSearchResource,
@@ -86,6 +88,7 @@ class AsyncBlitzAPI(BaseClient):
86
88
  *,
87
89
  body: Any | None,
88
90
  cast_to: type[ResponseT],
91
+ params: dict[str, Any] | None = None,
89
92
  timeout: TimeoutParam = None,
90
93
  ) -> ResponseT:
91
94
  url = self._build_url(path)
@@ -98,11 +101,11 @@ class AsyncBlitzAPI(BaseClient):
98
101
  try:
99
102
  if timeout is None:
100
103
  response = await self._http_client.request(
101
- method, url, headers=headers, json=json_body
104
+ method, url, headers=headers, json=json_body, params=params
102
105
  )
103
106
  else:
104
107
  response = await self._http_client.request(
105
- method, url, headers=headers, json=json_body, timeout=timeout
108
+ method, url, headers=headers, json=json_body, params=params, timeout=timeout
106
109
  )
107
110
  except httpx.TimeoutException as exc:
108
111
  if self._should_retry_exception(exc) and attempt < self.max_retries:
@@ -160,6 +163,10 @@ class AsyncBlitzAPI(BaseClient):
160
163
  def jobs(self) -> AsyncJobsResource:
161
164
  return AsyncJobsResource(self)
162
165
 
166
+ @cached_property
167
+ def company(self) -> AsyncCompanyResource:
168
+ return AsyncCompanyResource(self)
169
+
163
170
  @cached_property
164
171
  def enrichment(self) -> AsyncEnrichmentResource:
165
172
  return AsyncEnrichmentResource(self)
@@ -167,3 +174,7 @@ class AsyncBlitzAPI(BaseClient):
167
174
  @cached_property
168
175
  def utils(self) -> AsyncUtilsResource:
169
176
  return AsyncUtilsResource(self)
177
+
178
+ @cached_property
179
+ def changelog(self) -> AsyncChangelogResource:
180
+ return AsyncChangelogResource(self)
@@ -18,6 +18,8 @@ from ._pagination_base import BasePage
18
18
  from ._rate_limit import RateLimiter
19
19
  from .resources import (
20
20
  AccountResource,
21
+ ChangelogResource,
22
+ CompanyResource,
21
23
  EnrichmentResource,
22
24
  JobsResource,
23
25
  SearchResource,
@@ -88,6 +90,7 @@ class BlitzAPI(BaseClient):
88
90
  *,
89
91
  body: Any | None,
90
92
  cast_to: type[ResponseT],
93
+ params: dict[str, Any] | None = None,
91
94
  timeout: TimeoutParam = None,
92
95
  ) -> ResponseT:
93
96
  url = self._build_url(path)
@@ -100,11 +103,11 @@ class BlitzAPI(BaseClient):
100
103
  try:
101
104
  if timeout is None:
102
105
  response = self._http_client.request(
103
- method, url, headers=headers, json=json_body
106
+ method, url, headers=headers, json=json_body, params=params
104
107
  )
105
108
  else:
106
109
  response = self._http_client.request(
107
- method, url, headers=headers, json=json_body, timeout=timeout
110
+ method, url, headers=headers, json=json_body, params=params, timeout=timeout
108
111
  )
109
112
  except httpx.TimeoutException as exc:
110
113
  if self._should_retry_exception(exc) and attempt < self.max_retries:
@@ -162,6 +165,10 @@ class BlitzAPI(BaseClient):
162
165
  def jobs(self) -> JobsResource:
163
166
  return JobsResource(self)
164
167
 
168
+ @cached_property
169
+ def company(self) -> CompanyResource:
170
+ return CompanyResource(self)
171
+
165
172
  @cached_property
166
173
  def enrichment(self) -> EnrichmentResource:
167
174
  return EnrichmentResource(self)
@@ -169,3 +176,7 @@ class BlitzAPI(BaseClient):
169
176
  @cached_property
170
177
  def utils(self) -> UtilsResource:
171
178
  return UtilsResource(self)
179
+
180
+ @cached_property
181
+ def changelog(self) -> ChangelogResource:
182
+ return ChangelogResource(self)
@@ -8,20 +8,46 @@
8
8
  ├── APIResponseValidationError # a 2xx body was not valid JSON / not the expected shape
9
9
  └── APIStatusError # a non-2xx HTTP response was received
10
10
  ├── AuthenticationError # 401
11
- ├── InsufficientCreditsError # 402
11
+ ├── InsufficientRecordsError # 402
12
12
  ├── NotFoundError # 404
13
13
  ├── RateLimitError # 429 (after retries are exhausted)
14
14
  └── ServerError # 5xx (after retries are exhausted)
15
15
 
16
16
  Catch :class:`BlitzError` to handle anything this SDK raises.
17
+
18
+ ``InsufficientCreditsError`` remains available as a deprecated alias of
19
+ :class:`InsufficientRecordsError`; it is scheduled for removal in 3.0.0.
17
20
  """
18
21
 
19
22
  from __future__ import annotations
20
23
 
21
- from typing import TYPE_CHECKING, Any
24
+ from typing import TYPE_CHECKING, Any, cast
25
+
26
+ from pydantic import ValidationError
27
+
28
+ from .types._models import FairUsage
22
29
 
23
30
  if TYPE_CHECKING:
24
31
  import httpx
32
+ from typing_extensions import deprecated
33
+
34
+
35
+ def _parse_fair_usage(body: Any) -> FairUsage | None:
36
+ """Pull the ``fair_usage`` block out of an error body, if the API sent one.
37
+
38
+ The API attaches it to ``402`` responses, so a caller who runs out of records can
39
+ read ``next_reset_at`` off the exception. Never raises: a malformed block just
40
+ yields ``None`` rather than masking the original API error.
41
+ """
42
+ if not isinstance(body, dict):
43
+ return None
44
+ raw = cast("dict[str, Any]", body).get("fair_usage")
45
+ if not isinstance(raw, dict):
46
+ return None
47
+ try:
48
+ return FairUsage.model_validate(raw)
49
+ except ValidationError:
50
+ return None
25
51
 
26
52
 
27
53
  class BlitzError(Exception):
@@ -75,6 +101,8 @@ class APIStatusError(BlitzError):
75
101
  body: The parsed JSON body, or the raw text if it was not JSON.
76
102
  message: A human-readable message extracted from the body when present.
77
103
  request_id: The value of the ``x-request-id`` response header, if any.
104
+ fair_usage: The :class:`~blitz_api.types.FairUsage` block from the body, when
105
+ the API sent one (it does on ``402``); ``None`` otherwise.
78
106
  response: The underlying :class:`httpx.Response`.
79
107
  """
80
108
 
@@ -91,14 +119,19 @@ class APIStatusError(BlitzError):
91
119
  self.status_code = response.status_code
92
120
  self.body = body
93
121
  self.request_id = response.headers.get("x-request-id")
122
+ self.fair_usage = _parse_fair_usage(body)
94
123
 
95
124
 
96
125
  class AuthenticationError(APIStatusError):
97
126
  """401 — the API key is missing or invalid."""
98
127
 
99
128
 
100
- class InsufficientCreditsError(APIStatusError):
101
- """402 — the key is valid but the account is out of credits."""
129
+ class InsufficientRecordsError(APIStatusError):
130
+ """402 — the key is valid but the account is out of records.
131
+
132
+ The API attaches the usage block to this response, so :attr:`~APIStatusError.fair_usage`
133
+ tells you when the balance resets (``fair_usage.next_reset_at``).
134
+ """
102
135
 
103
136
 
104
137
  class NotFoundError(APIStatusError):
@@ -111,3 +144,20 @@ class RateLimitError(APIStatusError):
111
144
 
112
145
  class ServerError(APIStatusError):
113
146
  """5xx — the API failed (raised only after retries are exhausted)."""
147
+
148
+
149
+ # --- Deprecated aliases ------------------------------------------------------
150
+
151
+ if TYPE_CHECKING:
152
+
153
+ @deprecated(
154
+ "InsufficientCreditsError is renamed to InsufficientRecordsError and will be "
155
+ "removed in 3.0.0."
156
+ )
157
+ class InsufficientCreditsError(InsufficientRecordsError):
158
+ """Deprecated alias for :class:`InsufficientRecordsError`."""
159
+
160
+ else:
161
+ # A true alias, not a subclass: the client raises ``InsufficientRecordsError``, so a
162
+ # subclass here would stop ``except InsufficientCreditsError`` from catching it.
163
+ InsufficientCreditsError = InsufficientRecordsError
@@ -54,7 +54,7 @@ class AsyncPaginator(BasePage, Generic[ItemT]):
54
54
  """Drain every item across all pages into a list, optionally capped at ``max_items``.
55
55
 
56
56
  Convenience over a manual iteration loop; pair with ``max_items`` so an unbounded result
57
- set can't exhaust memory — or credits, since the API bills per result returned.
57
+ set can't exhaust memory — or records, since the API bills per result returned.
58
58
  """
59
59
  items: list[ItemT] = []
60
60
  async for item in self._auto_paging_items(max_items):
@@ -13,11 +13,16 @@ from typing import Any
13
13
 
14
14
  from pydantic import PrivateAttr
15
15
 
16
- from .types._models import BlitzModel
16
+ from .types._models import BlitzResponse
17
17
 
18
18
 
19
- class BasePage(BlitzModel):
20
- """Common pagination context. Subclasses add the page fields + iteration."""
19
+ class BasePage(BlitzResponse):
20
+ """Common pagination context. Subclasses add the page fields + iteration.
21
+
22
+ Inherits ``fair_usage`` from :class:`~blitz_api.types._models.BlitzResponse`: each
23
+ page carries the usage block of the request that fetched *it*, so during
24
+ auto-pagination ``page.fair_usage`` reflects that page, not the whole walk.
25
+ """
21
26
 
22
27
  # Bound by the client after a page is parsed, so the page can fetch the next one.
23
28
  _client: Any = PrivateAttr(default=None)
@@ -56,7 +56,7 @@ class Paginator(BasePage, Generic[ItemT]):
56
56
  """Drain every item across all pages into a list, optionally capped at ``max_items``.
57
57
 
58
58
  Convenience over a manual iteration loop; pair with ``max_items`` so an unbounded result
59
- set can't exhaust memory — or credits, since the API bills per result returned.
59
+ set can't exhaust memory — or records, since the API bills per result returned.
60
60
  """
61
61
  items: list[ItemT] = []
62
62
  for item in self._auto_paging_items(max_items):
@@ -0,0 +1 @@
1
+ __version__ = "3.0.0" # x-release-please-version
@@ -7,11 +7,15 @@ The ``Async*`` classes are hand-written in ``resources/_async``; the sync classe
7
7
  from __future__ import annotations
8
8
 
9
9
  from ._async.account import AsyncAccountResource
10
+ from ._async.changelog import AsyncChangelogResource
11
+ from ._async.company import AsyncCompanyResource
10
12
  from ._async.enrichment import AsyncEnrichmentResource
11
13
  from ._async.jobs import AsyncJobsResource
12
14
  from ._async.search import AsyncSearchResource
13
15
  from ._async.utils import AsyncUtilsResource
14
16
  from ._sync.account import AccountResource
17
+ from ._sync.changelog import ChangelogResource
18
+ from ._sync.company import CompanyResource
15
19
  from ._sync.enrichment import EnrichmentResource
16
20
  from ._sync.jobs import JobsResource
17
21
  from ._sync.search import SearchResource
@@ -24,8 +28,12 @@ __all__ = [
24
28
  "AsyncSearchResource",
25
29
  "JobsResource",
26
30
  "AsyncJobsResource",
31
+ "CompanyResource",
32
+ "AsyncCompanyResource",
27
33
  "EnrichmentResource",
28
34
  "AsyncEnrichmentResource",
29
35
  "UtilsResource",
30
36
  "AsyncUtilsResource",
37
+ "ChangelogResource",
38
+ "AsyncChangelogResource",
31
39
  ]
@@ -18,7 +18,7 @@ class AsyncAccountResource:
18
18
  self._client = client
19
19
 
20
20
  async def key_info(self, *, timeout: TimeoutParam = None) -> KeyInfo:
21
- """Check the API key's validity, credit balance, and rate limit.
21
+ """Check the API key's validity, record balance, and rate limit.
22
22
 
23
23
  A cheap health check to run before a batch job.
24
24
  """