@fedpulse/sdk 1.0.0

package/dist/cjs/resources/assistance.cjs

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Assistance Listings resource client.
+ *
+ * Wraps all /v1/assistance endpoints:
+ *   - list      GET /v1/assistance
+ *   - stats     GET /v1/assistance/stats
+ *   - get       GET /v1/assistance/:number   (CFDA program number)
+ *   - paginate  auto-paginates over the list endpoint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssistanceResource = void 0;
+class AssistanceResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Search and filter federal assistance listings (CFDA programs).
+     *
+     * @param params  Filter and pagination parameters.
+     *
+     * @example
+     * ```ts
+     * const result = await client.assistance.list({ agency: 'Department of Energy' });
+     * ```
+     */
+    async list(params = {}) {
+        return this.http.get('/v1/assistance', params);
+    }
+    /**
+     * Get aggregated statistics for assistance listings.
+     *
+     * @param params  Optional filter parameters.
+     *
+     * @example
+     * ```ts
+     * const stats = await client.assistance.stats();
+     * ```
+     */
+    async stats(params = {}) {
+        return this.http.get('/v1/assistance/stats', params);
+    }
+    /**
+     * Get a single assistance listing by its CFDA program number.
+     *
+     * @param programNumber  CFDA program number in "XX.XXX" format (e.g. "17.002").
+     * @throws {NotFoundError} If the program number does not exist.
+     *
+     * @example
+     * ```ts
+     * const listing = await client.assistance.get('84.048');
+     * console.log(listing.data.programTitle);
+     * ```
+     */
+    async get(programNumber) {
+        if (!programNumber || typeof programNumber !== 'string' || programNumber.trim() === '') {
+            throw new Error('programNumber must be a non-empty string');
+        }
+        const trimmed = programNumber.trim();
+        if (!/^\d{2}\.\d{3}$/.test(trimmed)) {
+            throw new Error('programNumber must be in "XX.XXX" format (e.g. "17.002")');
+        }
+        return this.http.get(`/v1/assistance/${encodeURIComponent(trimmed)}`);
+    }
+    /**
+     * Async generator that automatically paginates over all matching assistance listings.
+     *
+     * @param params  Same filter parameters as `list()`. Do not pass `page`.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.assistance.paginate({ agency: 'HHS' })) {
+     *   for (const listing of page.data) {
+     *     console.log(listing.programNumber, listing.programTitle);
+     *   }
+     * }
+     * ```
+     */
+    async *paginate(params) {
+        let page = 1;
+        let hasMore = true;
+        while (hasMore) {
+            const result = await this.list({ ...params, page });
+            yield result;
+            const pagination = result.pagination;
+            if (pagination === null) {
+                hasMore = false;
+            }
+            else if ('hasNextPage' in pagination) {
+                hasMore = pagination.hasNextPage;
+                if (hasMore)
+                    page++;
+            }
+            else {
+                hasMore = false;
+            }
+        }
+    }
+}
+exports.AssistanceResource = AssistanceResource;

package/dist/cjs/resources/entities.cjs

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Entities resource client.
+ *
+ * Wraps all /v1/entities endpoints:
+ *   - list                 GET /v1/entities
+ *   - get                  GET /v1/entities/:uei
+ *   - opportunities        GET /v1/entities/:uei/opportunities
+ *   - exclusionCheck       GET /v1/entities/:uei/exclusion-check
+ *   - stats                GET /v1/entities/stats
+ *   - paginate             auto-paginates over the list endpoint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitiesResource = void 0;
+const errors_js_1 = require("../errors.cjs");
+class EntitiesResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Search and filter SAM.gov registered entities (vendors).
+     *
+     * @param params  Filter and pagination parameters.
+     *
+     * @example
+     * ```ts
+     * const result = await client.entities.list({
+     *   naics: '541512',
+     *   certification: '8A',
+     *   state: 'VA',
+     * });
+     * ```
+     */
+    async list(params = {}) {
+        return this.http.get('/v1/entities', params);
+    }
+    /**
+     * Get the full SAM.gov registration profile for a vendor by UEI.
+     *
+     * @param uei  Unique Entity Identifier (12-char alphanumeric).
+     * @throws {NotFoundError} If the entity does not exist.
+     *
+     * @example
+     * ```ts
+     * const entity = await client.entities.get('ABCDEF123456');
+     * console.log(entity.data.legalBusinessName);
+     * ```
+     */
+    async get(uei) {
+        validateUei(uei);
+        return this.http.get(`/v1/entities/${encodeURIComponent(uei.trim().toUpperCase())}`);
+    }
+    /**
+     * Get awarded contract opportunities linked to a vendor.
+     *
+     * @param uei     Unique Entity Identifier.
+     * @param params  Pagination parameters.
+     * @throws {NotFoundError} If the entity does not exist.
+     *
+     * @example
+     * ```ts
+     * const contracts = await client.entities.opportunities('ABCDEF123456', { limit: 10 });
+     * ```
+     */
+    async opportunities(uei, params = {}) {
+        validateUei(uei);
+        return this.http.get(`/v1/entities/${encodeURIComponent(uei.trim().toUpperCase())}/opportunities`, params);
+    }
+    /**
+     * Check whether a vendor is currently excluded (debarred) from federal contracts.
+     *
+     * @param uei  Unique Entity Identifier.
+     * @throws {NotFoundError} If the entity does not exist.
+     *
+     * @example
+     * ```ts
+     * const check = await client.entities.exclusionCheck('ABCDEF123456');
+     * if (check.data.excluded) {
+     *   console.warn('Vendor is EXCLUDED!', check.data.exclusion);
+     * }
+     * ```
+     */
+    async exclusionCheck(uei) {
+        validateUei(uei);
+        return this.http.get(`/v1/entities/${encodeURIComponent(uei.trim().toUpperCase())}/exclusion-check`, {}, { cacheTtlMs: 0 } // Never cache exclusion checks — compliance-critical.
+        );
+    }
+    /**
+     * Get aggregated entity registration statistics.
+     *
+     * @example
+     * ```ts
+     * const stats = await client.entities.stats();
+     * console.log('Total registered entities:', stats.data.total);
+     * ```
+     */
+    async stats() {
+        return this.http.get('/v1/entities/stats');
+    }
+    /**
+     * Async generator that automatically paginates over all matching entities.
+     *
+     * @param params  Same filter parameters as `list()`. Do not pass `page`.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.entities.paginate({ naics: '541512' })) {
+     *   for (const entity of page.data) {
+     *     console.log(entity.legalBusinessName);
+     *   }
+     * }
+     * ```
+     */
+    async *paginate(params) {
+        let page = 1;
+        let hasMore = true;
+        while (hasMore) {
+            const result = await this.list({ ...params, page });
+            yield result;
+            const pagination = result.pagination;
+            if (pagination === null) {
+                hasMore = false;
+            }
+            else if ('hasNextPage' in pagination) {
+                hasMore = pagination.hasNextPage;
+                if (hasMore)
+                    page++;
+            }
+            else {
+                hasMore = false;
+            }
+        }
+    }
+}
+exports.EntitiesResource = EntitiesResource;
+// ── Helpers ────────────────────────────────────────────────────────────────────
+/**
+ * Validate UEI format: 12-character alphanumeric string.
+ * @throws {Error} If UEI is invalid.
+ */
+function validateUei(uei) {
+    if (!uei || typeof uei !== 'string' || uei.trim() === '') {
+        throw new errors_js_1.ValidationError({ message: 'uei must be a non-empty string', status: 400 });
+    }
+    if (!/^[A-Za-z0-9]{12}$/.test(uei.trim())) {
+        throw new errors_js_1.ValidationError({ message: 'uei must be a 12-character alphanumeric string (e.g. ABCDEF123456)', status: 400 });
+    }
+}

package/dist/cjs/resources/exclusions.cjs

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Exclusions resource client.
+ *
+ * Wraps all /v1/exclusions endpoints:
+ *   - list           GET /v1/exclusions
+ *   - get            GET /v1/exclusions/:exclusionId
+ *   - check          POST /v1/exclusions/check  (bulk compliance)
+ *   - stats          GET /v1/exclusions/stats
+ *   - paginate       auto-paginates over the list endpoint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExclusionsResource = void 0;
+const errors_js_1 = require("../errors.cjs");
+class ExclusionsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Search and filter the SAM.gov exclusions database.
+     *
+     * @param params  Filter and pagination parameters.
+     *
+     * @example
+     * ```ts
+     * const result = await client.exclusions.list({ uei: 'ABCDEF123456' });
+     * ```
+     */
+    async list(params = {}) {
+        return this.http.get('/v1/exclusions', params);
+    }
+    /**
+     * Get a single exclusion record by its unique ID.
+     *
+     * @param exclusionId  Internal exclusion identifier.
+     * @throws {NotFoundError} If the exclusion record does not exist.
+     */
+    async get(exclusionId) {
+        if (!exclusionId || typeof exclusionId !== 'string' || exclusionId.trim() === '') {
+            throw new errors_js_1.ValidationError({ message: 'exclusionId must be a non-empty string', status: 400 });
+        }
+        return this.http.get(`/v1/exclusions/${encodeURIComponent(exclusionId.trim())}`);
+    }
+    /**
+     * Bulk compliance check — verify up to 100 entities against the exclusions database.
+     *
+     * Each entity must include at least one of: `uei`, `cage`, or `name`.
+     * When `fuzzyMatch` is true (default), name matching uses trigram similarity.
+     *
+     * @param params  List of entities and fuzzy-match flag.
+     * @returns Per-entity exclusion status with match confidence scores.
+     * @throws {ValidationError} If more than 100 entities are provided.
+     *
+     * @example
+     * ```ts
+     * const result = await client.exclusions.check({
+     *   entities: [
+     *     { uei: 'ABCDEF123456' },
+     *     { name: 'Acme Corporation' },
+     *   ],
+     * });
+     * for (const item of result.data) {
+     *   console.log(item.input.name, '->', item.excluded ? 'EXCLUDED' : 'OK');
+     * }
+     * ```
+     */
+    async check(params) {
+        if (!Array.isArray(params.entities)) {
+            throw new errors_js_1.ValidationError({ message: 'entities must be an array', status: 400 });
+        }
+        if (params.entities.length === 0) {
+            throw new errors_js_1.ValidationError({ message: 'entities array must contain at least one entry', status: 400 });
+        }
+        if (params.entities.length > 100) {
+            throw new errors_js_1.ValidationError({ message: 'entities array must not exceed 100 entries', status: 400 });
+        }
+        for (const [i, entity] of params.entities.entries()) {
+            if (!entity.uei && !entity.cage && !entity.name) {
+                throw new errors_js_1.ValidationError({
+                    message: `entities[${i}] must include at least one of: uei, cage, name`,
+                    status: 400,
+                });
+            }
+        }
+        return this.http.post('/v1/exclusions/check', params);
+    }
+    /**
+     * Get aggregated exclusion statistics.
+     *
+     * @example
+     * ```ts
+     * const stats = await client.exclusions.stats();
+     * console.log('Total active exclusions:', stats.data.active);
+     * ```
+     */
+    async stats() {
+        return this.http.get('/v1/exclusions/stats');
+    }
+    /**
+     * Async generator that automatically paginates over all matching exclusions.
+     *
+     * @param params  Same filter parameters as `list()`. Do not pass `page`.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.exclusions.paginate({ agency: 'DEPT OF DEFENSE' })) {
+     *   for (const exc of page.data) {
+     *     console.log(exc.name, exc.effectiveDate);
+     *   }
+     * }
+     * ```
+     */
+    async *paginate(params) {
+        let page = 1;
+        let hasMore = true;
+        while (hasMore) {
+            const result = await this.list({ ...params, page });
+            yield result;
+            const pagination = result.pagination;
+            if (pagination === null) {
+                hasMore = false;
+            }
+            else if ('hasNextPage' in pagination) {
+                hasMore = pagination.hasNextPage;
+                if (hasMore)
+                    page++;
+            }
+            else {
+                hasMore = false;
+            }
+        }
+    }
+}
+exports.ExclusionsResource = ExclusionsResource;

package/dist/cjs/resources/intelligence.cjs

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Intelligence resource client.
+ *
+ * Wraps all /v1/intelligence endpoints:
+ *   - entityProfile     GET /v1/intelligence/entity/:uei
+ *   - marketAnalysis    GET /v1/intelligence/market/:naics
+ *   - complianceCheck   POST /v1/intelligence/compliance-check
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntelligenceResource = void 0;
+const errors_js_1 = require("../errors.cjs");
+class IntelligenceResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Get a comprehensive 360° intelligence profile for a vendor.
+     *
+     * Aggregates: contract history, agency relationships, certifications,
+     * exclusion status, and risk indicators into a single response.
+     *
+     * @param uei  Unique Entity Identifier (12-char alphanumeric).
+     * @throws {NotFoundError} If the entity does not exist in SAM.gov.
+     *
+     * @example
+     * ```ts
+     * const profile = await client.intelligence.entityProfile('ABCDEF123456');
+     * console.log('Contract count:', profile.data.contractCount);
+     * console.log('Risk:', profile.data.riskLevel);
+     * ```
+     */
+    async entityProfile(uei) {
+        if (!uei || typeof uei !== 'string' || uei.trim() === '') {
+            throw new errors_js_1.ValidationError({ message: 'uei must be a non-empty string', status: 400 });
+        }
+        if (!/^[A-Za-z0-9]{12}$/.test(uei.trim())) {
+            throw new errors_js_1.ValidationError({ message: 'uei must be a 12-character alphanumeric string', status: 400 });
+        }
+        return this.http.get(`/v1/intelligence/entity/${encodeURIComponent(uei.trim().toUpperCase())}`);
+    }
+    /**
+     * Get a market analysis for a specific NAICS code.
+     *
+     * Returns: top awardees, top agencies, set-aside breakdown, active solicitations,
+     * total market size, and recent award trends.
+     *
+     * @param naics  2–6 digit NAICS code (more digits = more specific market segment).
+     *
+     * @example
+     * ```ts
+     * const market = await client.intelligence.marketAnalysis('541512');
+     * console.log('Market size (cents):', market.data.totalMarketSize);
+     * console.log('Top awardee:', market.data.topAwardees[0]?.name);
+     * ```
+     */
+    async marketAnalysis(naics) {
+        if (!naics || typeof naics !== 'string' || naics.trim() === '') {
+            throw new errors_js_1.ValidationError({ message: 'naics must be a non-empty string', status: 400 });
+        }
+        if (!/^\d{2,6}$/.test(naics.trim())) {
+            throw new errors_js_1.ValidationError({ message: 'naics must be a numeric string of 2 to 6 digits (e.g. "541512")', status: 400 });
+        }
+        return this.http.get(`/v1/intelligence/market/${encodeURIComponent(naics.trim())}`);
+    }
+    /**
+     * Perform a full compliance check for a vendor.
+     *
+     * Returns: exclusion status, SAM.gov registration status, risk score,
+     * and risk indicators in one API call.
+     *
+     * @param params  Object containing the UEI to check.
+     * @throws {NotFoundError} If the entity does not exist in SAM.gov.
+     *
+     * @example
+     * ```ts
+     * const compliance = await client.intelligence.complianceCheck({ uei: 'ABCDEF123456' });
+     * if (compliance.data.excluded || compliance.data.riskLevel === 'high') {
+     *   console.warn('Do not contract with this vendor.');
+     * }
+     * ```
+     */
+    async complianceCheck(params) {
+        if (!params.uei || typeof params.uei !== 'string' || params.uei.trim() === '') {
+            throw new errors_js_1.ValidationError({ message: 'params.uei must be a non-empty string', status: 400 });
+        }
+        if (!/^[A-Za-z0-9]{12}$/.test(params.uei.trim())) {
+            throw new errors_js_1.ValidationError({ message: 'params.uei must be a 12-character alphanumeric string', status: 400 });
+        }
+        return this.http.post('/v1/intelligence/compliance-check', {
+            uei: params.uei.trim().toUpperCase(),
+        });
+    }
+}
+exports.IntelligenceResource = IntelligenceResource;

package/dist/cjs/resources/opportunities.cjs

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Opportunities resource client.
+ *
+ * Wraps all /v1/opportunities endpoints:
+ *   - search (list)        GET /v1/opportunities
+ *   - stats                GET /v1/opportunities/stats
+ *   - get                  GET /v1/opportunities/:noticeId
+ *   - createExport         POST /v1/opportunities/export
+ *   - getExport            GET /v1/opportunities/export/:exportId
+ *   - downloadExport       GET /v1/opportunities/export/:exportId/download
+ *   - paginate (generator) auto-paginates over the search endpoint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpportunitiesResource = void 0;
+class OpportunitiesResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Search and filter federal contract opportunities.
+     *
+     * @param params  Filter and pagination parameters.
+     * @returns Paginated list of opportunities.
+     *
+     * @example
+     * ```ts
+     * const result = await client.opportunities.list({
+     *   q: 'cybersecurity',
+     *   naics: '541512',
+     *   postedAfter: '2025-01-01',
+     *   limit: 50,
+     * });
+     * console.log(result.data[0].title);
+     * ```
+     */
+    async list(params = {}) {
+        return this.http.get('/v1/opportunities', params);
+    }
+    /**
+     * Get a single opportunity by its SAM.gov notice ID.
+     *
+     * @param noticeId  The unique SAM.gov notice identifier.
+     * @throws {NotFoundError} If the opportunity does not exist.
+     */
+    async get(noticeId) {
+        if (!noticeId || typeof noticeId !== 'string' || noticeId.trim() === '') {
+            throw new Error('noticeId must be a non-empty string');
+        }
+        return this.http.get(`/v1/opportunities/${encodeURIComponent(noticeId.trim())}`);
+    }
+    /**
+     * Get aggregated statistics for opportunities.
+     *
+     * @param params  Grouping and filter parameters.
+     *
+     * @example
+     * ```ts
+     * const stats = await client.opportunities.stats({ groupBy: 'naics', limit: 10 });
+     * ```
+     */
+    async stats(params = {}) {
+        return this.http.get('/v1/opportunities/stats', params);
+    }
+    /**
+     * Create a background export job for opportunities.
+     *
+     * Requires: Developer plan (CSV only) or Professional/Enterprise plan (all formats).
+     * Requires: `export` API key scope.
+     *
+     * @param params  Export parameters (format + same filters as `list`).
+     * @returns Export job metadata.
+     *
+     * @example
+     * ```ts
+     * const job = await client.opportunities.createExport({ format: 'csv', agency: 'NASA' });
+     * // Poll getExport() until job.data.status === 'done', then call downloadExport().
+     * ```
+     */
+    async createExport(params) {
+        return this.http.post('/v1/opportunities/export', params);
+    }
+    /**
+     * Get the status of an export job.
+     *
+     * @param exportId  UUID of the export job.
+     * @throws {NotFoundError} If the export job does not exist or belongs to another user.
+     */
+    async getExport(exportId) {
+        if (!exportId || typeof exportId !== 'string' || exportId.trim() === '') {
+            throw new Error('exportId must be a non-empty string');
+        }
+        return this.http.get(`/v1/opportunities/export/${encodeURIComponent(exportId.trim())}`, {}, { cacheTtlMs: 0 } // Never cache — status changes over time.
+        );
+    }
+    /**
+     * Download the output file of a completed export job.
+     *
+     * Returns the raw `Response` object so callers can stream or save the body.
+     * The response body will be CSV or NDJSON depending on the export format.
+     *
+     * @param exportId  UUID of a **completed** export job.
+     * @returns Raw fetch `Response` with the file body.
+     * @throws {PermissionError} If the export is not complete.
+     * @throws {NotFoundError}   If the export does not exist.
+     *
+     * @example
+     * ```ts
+     * const response = await client.opportunities.downloadExport(exportId);
+     * const csv = await response.text();
+     * ```
+     */
+    async downloadExport(exportId) {
+        if (!exportId || typeof exportId !== 'string' || exportId.trim() === '') {
+            throw new Error('exportId must be a non-empty string');
+        }
+        return this.http.rawGet(`/v1/opportunities/export/${encodeURIComponent(exportId.trim())}/download`);
+    }
+    /**
+     * Async generator that automatically paginates over all matching opportunities.
+     *
+     * Uses cursor-based pagination when available, falling back to offset.
+     * Yields one page of results at a time.
+     *
+     * @param params  Same filter parameters as `list()`. Do not pass `page` or `cursor`.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.opportunities.paginate({ naics: '541512' })) {
+     *   for (const opp of page.data) {
+     *     console.log(opp.title);
+     *   }
+     * }
+     * ```
+     */
+    async *paginate(params) {
+        let cursor = undefined;
+        let page = 1;
+        let hasMore = true;
+        while (hasMore) {
+            const queryParams = {
+                ...params,
+                ...(cursor !== undefined ? { cursor } : { page }),
+            };
+            const result = await this.list(queryParams);
+            yield result;
+            const pagination = result.pagination;
+            if (pagination === null) {
+                hasMore = false;
+            }
+            else if ('nextCursor' in pagination) {
+                cursor = pagination.nextCursor ?? undefined;
+                hasMore = pagination.hasNextPage;
+            }
+            else if ('hasNextPage' in pagination) {
+                if (!pagination.hasNextPage) {
+                    hasMore = false;
+                }
+                else {
+                    page++;
+                }
+            }
+            else {
+                hasMore = false;
+            }
+        }
+    }
+}
+exports.OpportunitiesResource = OpportunitiesResource;