@fedpulse/sdk 1.0.4 → 1.0.6

package/README.md

@@ -1,346 +1,360 @@
-# @fedpulse/sdk
-
-[![npm version](https://img.shields.io/npm/v/@fedpulse/sdk)](https://www.npmjs.com/package/@fedpulse/sdk)
-[![Node.js ≥18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-Official JavaScript / TypeScript SDK for the [FedPulse API](https://fedpulse.dev). Search federal contract opportunities, check vendor exclusions, retrieve entity registrations, and access market intelligence — all with zero runtime dependencies.
-
----
-
-## Features
-
-- **Typed end-to-end** — full TypeScript definitions for every request and response
-- **Dual ESM + CJS** — works in Node.js (ESM / CommonJS), Deno, Bun, and bundlers
-- **Zero runtime dependencies** — only uses Node.js built-ins (`fetch`, `crypto`)
-- **Automatic retry** — exponential back-off with full jitter for 5xx / network errors
-- **In-memory LRU cache** — 256-entry, 60 s TTL on all GET requests
-- **Webhook verification** — HMAC-SHA256 signature + replay-attack protection
-- **Cursor + offset pagination** — async generator helpers for all list endpoints
-
----
-
-## Requirements
-
-- Node.js **≥ 18.0.0** (native `fetch` + `crypto`)
-- A FedPulse API key — generate one at [app.fedpulse.dev/dashboard](https://app.fedpulse.dev/dashboard)
-
----
-
-## Installation
-
-```bash
-npm install @fedpulse/sdk
-```
-
----
-
-## Quick start
-
-```ts
-import { FedPulse } from '@fedpulse/sdk';
-
-const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY! });
-
-// Search opportunities
-const result = await client.opportunities.list({
-  keyword: 'cybersecurity',
-  naics: ['541519', '541512'],
-  postedAfter: '2025-01-01',
-  limit: 25,
-});
-
-console.log(result.data);        // typed OpportunitySummary[]
-console.log(result.pagination);  // { total, page, limit, … }
-```
-
----
-
-## Authentication
-
-Pass your API key to the constructor. It is sent as `Authorization: Bearer <key>` on every request.
-
-```ts
-const client = new FedPulse({ apiKey: 'fp_live_…' });
-```
-
-Never hard-code keys in source — use environment variables.
-
----
-
-## Resources
-
-### `client.opportunities`
-
-```ts
-// List / search opportunities
-await client.opportunities.list({ keyword: 'cloud', naics: ['541512'] });
-
-// Retrieve a single opportunity
-await client.opportunities.get('abc123-notice-id');
-
-// Aggregate statistics
-await client.opportunities.stats({ postedAfter: '2025-01-01' });
-
-// Request a data export (async job)
-await client.opportunities.createExport({ format: 'csv', filter: { keyword: 'AI' } });
-
-// Async generator — walks all pages automatically
-for await (const page of client.opportunities.paginate({ keyword: 'defense' })) {
-  console.log(page.data);
-}
-```
-
-### `client.exclusions`
-
-```ts
-// List all current exclusions
-await client.exclusions.list({ active: true });
-
-// Retrieve one record
-await client.exclusions.get('exclusion-id');
-
-// Bulk check up to 100 entities
-await client.exclusions.check({
-  entities: [
-    { uei: 'ABC123DEF456' },
-    { cage: '1A2B3' },
-    { name: 'Acme Corp' },
-  ],
-});
-
-// Stats
-await client.exclusions.stats();
-
-// Page through all exclusions
-for await (const page of client.exclusions.paginate()) {
-  console.log(page.data);
-}
-```
-
-### `client.entities`
-
-```ts
-// List registered entities
-await client.entities.list({ naics: ['336411'], state: 'VA' });
-
-// Entity by UEI
-await client.entities.get('ABCDEF123456');
-
-// Contracts awarded to an entity
-await client.entities.opportunities('ABCDEF123456', { limit: 50 });
-
-// Exclusion check (never cached)
-await client.entities.exclusionCheck('ABCDEF123456');
-
-// Stats
-await client.entities.stats();
-
-// All pages
-for await (const page of client.entities.paginate({ state: 'TX' })) {
-  console.log(page.data);
-}
-```
-
-### `client.intelligence`
-
-```ts
-// 360° entity intelligence profile
-await client.intelligence.entityProfile('ABCDEF123456');
-
-// Market analysis for a NAICS code
-await client.intelligence.marketAnalysis('541512');
-
-// Single-entity compliance check
-await client.intelligence.complianceCheck({ uei: 'ABCDEF123456' });
-```
-
-### `client.assistance`
-
-Federal grants and assistance listings (CFDA programs).
-
-```ts
-// Search listings
-await client.assistance.list({ keyword: 'broadband', agency: 'USDA' });
-
-// Retrieve one by CFDA program number (format: "XX.XXX")
-await client.assistance.get('10.001');
-
-// Aggregated stats
-await client.assistance.stats();
-
-// Auto-paginate all listings
-for await (const page of client.assistance.paginate({ agency: 'HHS' })) {
-  console.log(page.data);
-}
-```
-
-### `client.analytics`
-
-Per-user API usage analytics — scoped to the authenticated key.
-
-```ts
-// KPI totals (requests today, this month, error rates)
-await client.analytics.summary({ range: '30d' });
-
-// Per-day breakdown for charting (up to 90 days)
-await client.analytics.chart({ range: '30d' });
-
-// Top endpoints by request volume and P95 latency
-await client.analytics.endpoints({ range: '7d' });
-
-// Paginated raw request log
-await client.analytics.logs({ limit: 20 });
-```
-
-### `client.webhooks`
-
-```ts
-// List configured webhooks
-await client.webhooks.list();
-
-// Create
-await client.webhooks.create({ url: 'https://example.com/hook', events: ['opportunity.new'] });
-
-// Update / delete
-await client.webhooks.update('wh_id', { active: false });
-await client.webhooks.delete('wh_id');
-
-// Deliveries log
-await client.webhooks.listDeliveries('wh_id');
-await client.webhooks.getDelivery('wh_id', 'delivery-id');
-```
-
----
-
-## Webhook signature verification
-
-```ts
-import { FedPulse } from '@fedpulse/sdk';
-
-// In your Express / Fastify handler:
-app.post('/webhooks', (req, res) => {
-  const { signatureHeader, timestampHeader } = FedPulse.extractWebhookHeaders(req.headers);
-
-  let event;
-  try {
-    event = FedPulse.verifyWebhook({
-      rawBody: req.body,           // Buffer or string — the raw unparsed body
-      signatureHeader,
-      timestampHeader,
-      secret: process.env.FEDPULSE_WEBHOOK_SECRET!,
-      options: { maxAgeSeconds: 300 },
-    });
-  } catch (err) {
-    return res.status(400).send('Invalid signature');
-  }
-
-  console.log(event.event, event.data);
-  res.sendStatus(200);
-});
-```
-
----
-
-## Pagination helpers
-
-Every list resource exposes a `paginate()` async generator that walks all pages for you:
-
-```ts
-const allOpps: OpportunitySummary[] = [];
-
-for await (const page of client.opportunities.paginate({ keyword: 'cloud' })) {
-  allOpps.push(...page.data);
-}
-```
-
----
-
-## Error handling
-
-All errors extend `FedPulseError`. Import specific classes for precise handling:
-
-```ts
-import {
-  FedPulse,
-  AuthenticationError,
-  PermissionError,
-  NotFoundError,
-  ValidationError,
-  RateLimitError,
-  ServerError,
-  NetworkError,
-  TimeoutError,
-  RetryExhaustedError,
-} from '@fedpulse/sdk';
-
-try {
-  await client.opportunities.get('bad-id');
-} catch (err) {
-  if (err instanceof NotFoundError) {
-    console.log('Not found');
-  } else if (err instanceof RateLimitError) {
-    console.log(`Rate limited. Retry after: ${err.retryAfter}s`);
-  } else if (err instanceof RetryExhaustedError) {
-    console.log(`Failed after ${err.attempts} attempts`, err.lastError);
-  } else if (err instanceof NetworkError) {
-    console.log('Network issue — check internet connection');
-  }
-}
-```
-
-| Class | Status | When thrown |
-|---|---|---|
-| `AuthenticationError` | 401 | Invalid or missing API key |
-| `PermissionError` | 403 | Key lacks required permission |
-| `NotFoundError` | 404 | Resource does not exist |
-| `ValidationError` | 400/422 | Bad request parameters |
-| `RateLimitError` | 429 | Too many requests (check `retryAfter`) |
-| `ServerError` | 5xx | FedPulse server error |
-| `NetworkError` | — | DNS failure, ECONNREFUSED, etc. |
-| `TimeoutError` | — | Request exceeded `timeoutMs` |
-| `RetryExhaustedError` | — | All retry attempts failed |
-
----
-
-## Configuration
-
-```ts
-const client = new FedPulse({
-  apiKey: 'fp_live_…',        // required
-  baseUrl: 'https://api.fedpulse.dev', // optional override
-  timeoutMs: 30_000,          // per-attempt timeout (default: 30 s)
-  maxRetries: 3,              // retries for 5xx / network errors (default: 3)
-  cacheSize: 256,             // LRU cache entries, 0 to disable (default: 256)
-  cacheTtlMs: 60_000,         // cache TTL in ms (default: 60 s)
-});
-```
-
-### Rate limit info
-
-```ts
-const { data } = await client.opportunities.list({ keyword: 'cloud' });
-console.log(client.rateLimit);
-// { limit: 1000, remaining: 987, reset: 1740000000 }
-```
-
-### Clear cache
-
-```ts
-client.clearCache();
-```
-
----
-
-## CommonJS usage
-
-```js
-const { FedPulse } = require('@fedpulse/sdk');
-const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY });
-```
-
----
-
-## License
-
-MIT © [FedPulse](https://fedpulse.dev)
+# @fedpulse/sdk
+
+[![npm version](https://img.shields.io/npm/v/@fedpulse/sdk)](https://www.npmjs.com/package/@fedpulse/sdk)
+[![Node.js ≥18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official JavaScript / TypeScript SDK for the [FedPulse API](https://fedpulse.dev). Search federal contract opportunities, check vendor exclusions, retrieve entity registrations, and access market intelligence — all with zero runtime dependencies.
+
+---
+
+## Features
+
+- **Typed end-to-end** — full TypeScript definitions for every request and response
+- **Dual ESM + CJS** — works in Node.js (ESM / CommonJS), Deno, Bun, and bundlers
+- **Zero runtime dependencies** — only uses Node.js built-ins (`fetch`, `crypto`)
+- **Automatic retry** — exponential back-off with full jitter for 5xx / network errors
+- **In-memory LRU cache** — 256-entry, 60 s TTL on all GET requests
+- **Webhook verification** — HMAC-SHA256 signature + replay-attack protection
+- **Cursor + offset pagination** — async generator helpers for all list endpoints
+
+---
+
+## Requirements
+
+- Node.js **≥ 18.0.0** (native `fetch` + `crypto`)
+- A FedPulse API key — generate one at [app.fedpulse.dev/dashboard](https://app.fedpulse.dev/dashboard)
+
+---
+
+## Installation
+
+```bash
+npm install @fedpulse/sdk
+```
+
+---
+
+## Quick start
+
+```ts
+import { FedPulse } from '@fedpulse/sdk';
+
+const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY! });
+
+// Search opportunities
+const result = await client.opportunities.list({
+  q: 'cybersecurity',
+  naics: ['541519', '541512'],
+  postedAfter: '2025-01-01',
+  limit: 25,
+});
+
+console.log(result.data);        // typed OpportunitySummary[]
+console.log(result.pagination);  // { total, page, limit, … }
+```
+
+---
+
+## Authentication
+
+Pass your API key to the constructor. It is sent as `Authorization: Bearer <key>` on every request.
+
+```ts
+const client = new FedPulse({ apiKey: 'fp_live_…' });
+```
+
+Never hard-code keys in source — use environment variables.
+
+---
+
+## Resources
+
+### `client.opportunities`
+
+```ts
+// List / search opportunities
+await client.opportunities.list({ q: 'cloud', naics: ['541512'] });
+
+// Retrieve a single opportunity
+await client.opportunities.get('abc123-notice-id');
+
+// Aggregate statistics
+await client.opportunities.stats({ postedAfter: '2025-01-01' });
+
+// Request a data export (async job — returns immediately with a job ID; poll exportId for status)
+await client.opportunities.createExport({ format: 'csv', q: 'AI' });
+
+// Async generator — walks all pages automatically
+for await (const page of client.opportunities.paginate({ q: 'defense' })) {
+  console.log(page.data);
+}
+```
+
+### `client.exclusions`
+
+```ts
+// List all current exclusions
+await client.exclusions.list({ activeOnly: true });
+
+// Retrieve one record
+await client.exclusions.get('exclusion-id');
+
+// Bulk check up to 100 entities
+await client.exclusions.check({
+  entities: [
+    { uei: 'ABC123DEF456' },
+    { cage: '1A2B3' },
+    { name: 'Acme Corp' },
+  ],
+});
+
+// Stats
+await client.exclusions.stats();
+
+// Page through all exclusions
+for await (const page of client.exclusions.paginate()) {
+  console.log(page.data);
+}
+```
+
+### `client.entities`
+
+```ts
+// List registered entities
+await client.entities.list({ naics: ['336411'], state: 'VA' });
+
+// Entity by UEI
+await client.entities.get('ABCDEF123456');
+
+// Contracts awarded to an entity
+await client.entities.opportunities('ABCDEF123456', { limit: 50 });
+
+// Exclusion check (never cached)
+await client.entities.exclusionCheck('ABCDEF123456');
+
+// Stats
+await client.entities.stats();
+
+// All pages
+for await (const page of client.entities.paginate({ state: 'TX' })) {
+  console.log(page.data);
+}
+```
+
+### `client.intelligence`
+
+```ts
+// 360° entity intelligence profile
+await client.intelligence.entityProfile('ABCDEF123456');
+
+// Market analysis for a NAICS code
+await client.intelligence.marketAnalysis('541512');
+
+// Single-entity compliance check
+await client.intelligence.complianceCheck({ uei: 'ABCDEF123456' });
+```
+
+### `client.assistance`
+
+Federal grants and assistance listings (CFDA programs).
+
+```ts
+// Search listings
+await client.assistance.list({ q: 'broadband', agency: 'USDA' });
+
+// Retrieve one by CFDA program number (format: "XX.XXX")
+await client.assistance.get('10.001');
+
+// Aggregated stats
+await client.assistance.stats();
+
+// Auto-paginate all listings
+for await (const page of client.assistance.paginate({ agency: 'HHS' })) {
+  console.log(page.data);
+}
+```
+
+### `client.analytics`
+
+Per-user API usage analytics — scoped to the authenticated key.
+
+```ts
+// KPI totals (requests today, this month, error rates)
+await client.analytics.summary({ range: '30d' });
+
+// Per-day breakdown for charting (up to 90 days)
+await client.analytics.chart({ range: '30d' });
+
+// Top endpoints by request volume and P95 latency
+await client.analytics.endpoints({ range: '7d' });
+
+// Paginated raw request log
+await client.analytics.logs({ limit: 20 });
+```
+
+### `client.webhooks`
+
+```ts
+// List configured webhooks
+await client.webhooks.list();
+
+// Get a single webhook
+await client.webhooks.get('00000000-0000-0000-0000-000000000001');
+
+// Create
+await client.webhooks.create({ url: 'https://example.com/hook', events: ['opportunity.new'] });
+
+// Update / delete
+await client.webhooks.update('00000000-0000-0000-0000-000000000001', { is_active: false });
+await client.webhooks.delete('00000000-0000-0000-0000-000000000001');
+
+// Send a test event to the endpoint immediately
+await client.webhooks.test('00000000-0000-0000-0000-000000000001');
+
+// Resume a paused webhook (auto-paused after 5 consecutive failures)
+await client.webhooks.resume('00000000-0000-0000-0000-000000000001');
+
+// Deliveries log
+await client.webhooks.listDeliveries('00000000-0000-0000-0000-000000000001', { status: 'failed' });
+await client.webhooks.getDelivery('00000000-0000-0000-0000-000000000001', '00000000-0000-0000-0000-000000000002');
+
+// Auto-paginate all delivery history
+for await (const page of client.webhooks.deliveryPages('00000000-0000-0000-0000-000000000001', { status: 'failed' })) {
+  console.log(page.data);
+}
+```
+
+---
+
+## Webhook signature verification
+
+```ts
+import { FedPulse } from '@fedpulse/sdk';
+
+// In your Express / Fastify handler:
+app.post('/webhooks', (req, res) => {
+  const { signatureHeader, timestampHeader } = FedPulse.extractWebhookHeaders(req.headers);
+
+  let event;
+  try {
+    event = FedPulse.verifyWebhook({
+      rawBody: req.body,           // Buffer or string — the raw unparsed body
+      signatureHeader,
+      timestampHeader,
+      secret: process.env.FEDPULSE_WEBHOOK_SECRET!,
+      options: { maxAgeSeconds: 300 },
+    });
+  } catch (err) {
+    return res.status(400).send('Invalid signature');
+  }
+
+  console.log(event.event, event.data);
+  res.sendStatus(200);
+});
+```
+
+---
+
+## Pagination helpers
+
+Every list resource exposes a `paginate()` async generator that walks all pages for you:
+
+```ts
+const allOpps: OpportunitySummary[] = [];
+
+for await (const page of client.opportunities.paginate({ q: 'cloud' })) {
+  allOpps.push(...page.data);
+}
+```
+
+---
+
+## Error handling
+
+All errors extend `FedPulseError`. Import specific classes for precise handling:
+
+```ts
+import {
+  FedPulse,
+  AuthenticationError,
+  PermissionError,
+  NotFoundError,
+  ValidationError,
+  RateLimitError,
+  ServerError,
+  NetworkError,
+  TimeoutError,
+  RetryExhaustedError,
+} from '@fedpulse/sdk';
+
+try {
+  await client.opportunities.get('bad-id');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Not found');
+  } else if (err instanceof RateLimitError) {
+    console.log(`Rate limited. Retry after: ${err.retryAfter}s`);
+  } else if (err instanceof RetryExhaustedError) {
+    console.log(`Failed after ${err.attempts} attempts`, err.lastError);
+  } else if (err instanceof NetworkError) {
+    console.log('Network issue — check internet connection');
+  }
+}
+```
+
+| Class | Status | When thrown |
+|---|---|---|
+| `AuthenticationError` | 401 | Invalid or missing API key |
+| `PermissionError` | 403 | Key lacks required permission |
+| `NotFoundError` | 404 | Resource does not exist |
+| `ValidationError` | 400/422 | Bad request parameters |
+| `RateLimitError` | 429 | Too many requests (check `retryAfter`) |
+| `ServerError` | 5xx | FedPulse server error |
+| `NetworkError` | — | DNS failure, ECONNREFUSED, etc. |
+| `TimeoutError` | — | Request exceeded `timeoutMs` |
+| `RetryExhaustedError` | — | All retry attempts failed |
+
+---
+
+## Configuration
+
+```ts
+const client = new FedPulse({
+  apiKey: 'fp_live_…',        // required
+  baseUrl: 'https://api.fedpulse.dev', // optional override
+  timeoutMs: 30_000,          // per-attempt timeout (default: 30 s)
+  maxRetries: 3,              // retries for 5xx / network errors (default: 3)
+  cacheSize: 256,             // LRU cache entries, 0 to disable (default: 256)
+  cacheTtlMs: 60_000,         // cache TTL in ms (default: 60 s)
+});
+```
+
+### Rate limit info
+
+```ts
+const { data } = await client.opportunities.list({ q: 'cloud' });
+console.log(client.rateLimit);
+// { limit: 1000, remaining: 987, reset: 1740000000 }
+```
+
+### Clear cache
+
+```ts
+client.clearCache();
+```
+
+---
+
+## CommonJS usage
+
+```js
+const { FedPulse } = require('@fedpulse/sdk');
+const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY });
+```
+
+---
+
+## License
+
+MIT © [FedPulse](https://fedpulse.dev)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedpulse/sdk",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Official JavaScript/TypeScript SDK for the FedPulse API — federal contracts, exclusions, entities, assistance listings, and market intelligence.",
   "keywords": [
     "fedpulse",