@fedpulse/sdk 1.0.0

package/dist/esm/webhooks-verify.js

@@ -0,0 +1,179 @@
+/**
+ * Webhook signature verification for FedPulse webhook deliveries.
+ *
+ * FedPulse signs every outgoing webhook POST with HMAC-SHA256.
+ * Use these utilities to verify that incoming requests are genuinely from
+ * FedPulse and have not been tampered with or replayed.
+ *
+ * ## Signing algorithm:
+ *   signed_body = `${timestampSeconds}.${rawPayloadJson}`
+ *   signature   = HMAC-SHA256(rawSecret, signed_body) → hex
+ *
+ * ## Delivery headers (all present on every POST):
+ *   X-FedPulse-Signature   : `sha256={hex_hmac}`
+ *   X-FedPulse-Timestamp   : Unix epoch seconds (string)
+ *   X-FedPulse-Event       : Event type (e.g. "opportunity.new")
+ *   X-FedPulse-Delivery-Id : UUIDv4 delivery identifier
+ *
+ * ## Replay protection:
+ *   Reject deliveries where |now − timestamp| > maxAgeSeconds (default 300s).
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { FedPulseError } from './errors.js';
+// ── Constants ─────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_AGE_SECONDS = 300; // 5 minutes — matches API server policy.
+// ── Error types ────────────────────────────────────────────────────────────────
+/** Thrown when webhook signature verification fails. */
+export class WebhookVerificationError extends FedPulseError {
+    constructor(message) {
+        super({ message, status: 0, code: 'WEBHOOK_VERIFICATION_FAILED' });
+        this.name = 'WebhookVerificationError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+// ── Public API ─────────────────────────────────────────────────────────────────
+/**
+ * Verify a FedPulse webhook delivery and parse the payload.
+ *
+ * This function performs three checks:
+ *   1. **Format check** — headers are present and in the expected format.
+ *   2. **Timestamp check** — delivery is not older than `maxAgeSeconds`.
+ *   3. **Signature check** — HMAC-SHA256 matches using constant-time comparison.
+ *
+ * Throws `WebhookVerificationError` on any failure.
+ * Returns the parsed, verified `WebhookPayload<T>`.
+ *
+ * @param input  Headers, raw body, and secret.
+ * @returns Parsed and verified webhook payload.
+ *
+ * @throws {WebhookVerificationError} If the signature is invalid, the timestamp
+ *   is out of range, or the headers are malformed.
+ *
+ * @example
+ * ```ts
+ * // Express.js example (use bodyParser.raw() to get the raw buffer):
+ * app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
+ *   let payload;
+ *   try {
+ *     payload = FedPulse.verifyWebhook({
+ *       rawBody: req.body,
+ *       signatureHeader: req.headers['x-fedpulse-signature'] as string,
+ *       timestampHeader: req.headers['x-fedpulse-timestamp'] as string,
+ *       secret: process.env.FEDPULSE_WEBHOOK_SECRET!,
+ *     });
+ *   } catch (err) {
+ *     return res.status(400).send('Invalid signature');
+ *   }
+ *   console.log('Event:', payload.event, 'Data:', payload.data);
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+export function verifyWebhook(input) {
+    const { rawBody, signatureHeader, timestampHeader, secret, options } = input;
+    const maxAgeSeconds = options?.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS;
+    // ── 1. Validate input presence ─────────────────────────────────────────────
+    if (!signatureHeader || typeof signatureHeader !== 'string') {
+        throw new WebhookVerificationError('Missing X-FedPulse-Signature header. Ensure the request is from FedPulse.');
+    }
+    if (!timestampHeader || typeof timestampHeader !== 'string') {
+        throw new WebhookVerificationError('Missing X-FedPulse-Timestamp header. Ensure the request is from FedPulse.');
+    }
+    if (!secret || typeof secret !== 'string' || secret.trim() === '') {
+        throw new WebhookVerificationError('Webhook secret must be a non-empty string.');
+    }
+    if (rawBody === undefined || rawBody === null) {
+        throw new WebhookVerificationError('rawBody is required. Pass the exact bytes received from the HTTP request.');
+    }
+    // ── 2. Parse and validate timestamp ────────────────────────────────────────
+    const timestampSeconds = Number(timestampHeader);
+    if (!Number.isFinite(timestampSeconds) || timestampSeconds <= 0) {
+        throw new WebhookVerificationError(`X-FedPulse-Timestamp is not a valid Unix timestamp: "${timestampHeader}"`);
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const ageSeconds = Math.abs(nowSeconds - timestampSeconds);
+    if (ageSeconds > maxAgeSeconds) {
+        throw new WebhookVerificationError(`Webhook delivery is too old (age: ${ageSeconds}s, max: ${maxAgeSeconds}s). ` +
+            'This may indicate a replay attack. Ensure your server clock is synchronised.');
+    }
+    // ── 3. Parse and validate signature header ─────────────────────────────────
+    if (!signatureHeader.startsWith('sha256=')) {
+        throw new WebhookVerificationError(`Unsupported signature algorithm. Expected "sha256=..." prefix, got: "${signatureHeader}"`);
+    }
+    const receivedHex = signatureHeader.slice('sha256='.length);
+    if (!receivedHex || !/^[0-9a-f]+$/i.test(receivedHex)) {
+        throw new WebhookVerificationError('X-FedPulse-Signature contains an invalid hex string');
+    }
+    // ── 4. Compute expected signature ──────────────────────────────────────────
+    const bodyString = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+    const signedPayload = `${timestampSeconds}.${bodyString}`;
+    const expectedHex = createHmac('sha256', secret)
+        .update(signedPayload, 'utf8')
+        .digest('hex');
+    // ── 5. Constant-time comparison ────────────────────────────────────────────
+    // Pad both to the same length to avoid length-based timing differences, then
+    // use timingSafeEqual to prevent timing attacks.
+    const receivedBuf = Buffer.from(receivedHex.toLowerCase(), 'hex');
+    const expectedBuf = Buffer.from(expectedHex, 'hex');
+    if (receivedBuf.length !== expectedBuf.length ||
+        !timingSafeEqual(receivedBuf, expectedBuf)) {
+        throw new WebhookVerificationError('Webhook signature does not match. The request may have been tampered with.');
+    }
+    // ── 6. Parse and return payload ────────────────────────────────────────────
+    let payload;
+    try {
+        payload = JSON.parse(bodyString);
+    }
+    catch {
+        throw new WebhookVerificationError('Webhook body is not valid JSON despite a valid signature.');
+    }
+    if (payload === null ||
+        typeof payload !== 'object' ||
+        !('event' in payload) ||
+        !('timestamp' in payload) ||
+        !('data' in payload)) {
+        throw new WebhookVerificationError('Webhook payload does not match the expected envelope shape ' +
+            '{ event, timestamp, apiVersion, data }.');
+    }
+    return payload;
+}
+/**
+ * Extract the FedPulse webhook headers from a plain headers object.
+ *
+ * Normalises both lowercase and original-casing variants so you don't
+ * have to worry about header casing differences between frameworks.
+ *
+ * @param headers  A plain object or Map of request headers.
+ * @returns  Extracted signature and timestamp values.
+ *
+ * @example
+ * ```ts
+ * // Works with Express, Fastify, Koa, Next.js API routes, etc.
+ * const { signatureHeader, timestampHeader } = extractWebhookHeaders(req.headers);
+ * const payload = FedPulse.verifyWebhook({ rawBody, signatureHeader, timestampHeader, secret });
+ * ```
+ */
+export function extractWebhookHeaders(headers) {
+    const get = (key) => {
+        let value;
+        if (headers instanceof Headers) {
+            value = headers.get(key);
+        }
+        else {
+            // Case-insensitive lookup for plain objects.
+            const lowerKey = key.toLowerCase();
+            const entry = Object.entries(headers).find(([k]) => k.toLowerCase() === lowerKey);
+            value = entry?.[1];
+        }
+        if (Array.isArray(value))
+            return value[0] ?? '';
+        return value ?? '';
+    };
+    return {
+        signatureHeader: get('x-fedpulse-signature'),
+        timestampHeader: get('x-fedpulse-timestamp'),
+        event: get('x-fedpulse-event'),
+        deliveryId: get('x-fedpulse-delivery-id'),
+    };
+}
+//# sourceMappingURL=webhooks-verify.js.map

package/dist/esm/webhooks-verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks-verify.js","sourceRoot":"","sources":["../../src/webhooks-verify.ts"],"names":[],"mappings":"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"}

package/dist/types/client.d.cts

@@ -0,0 +1,136 @@
+/**
+ * FedPulse SDK — main client class.
+ *
+ * Instantiate this class with your API key to access all FedPulse
+ * data resources and the webhook verification utility.
+ *
+ * @example
+ * ```ts
+ * import { FedPulse } from '@fedpulse/sdk';
+ *
+ * const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY! });
+ *
+ * // Search contracts
+ * const { data } = await client.opportunities.list({ q: 'cloud', naics: '541512' });
+ *
+ * // Compliance check
+ * const { data: status } = await client.exclusions.check({ entities: [{ uei: 'ABCDEF123456' }] });
+ *
+ * // Verify an incoming webhook
+ * const payload = FedPulse.verifyWebhook({ rawBody, signatureHeader, timestampHeader, secret });
+ * ```
+ */
+import { HttpClient } from './http.cjs';
+import type { HttpClientOptions } from './http.cjs';
+import { OpportunitiesResource } from './resources/opportunities.cjs';
+import { ExclusionsResource } from './resources/exclusions.cjs';
+import { EntitiesResource } from './resources/entities.cjs';
+import { IntelligenceResource } from './resources/intelligence.cjs';
+import { AssistanceResource } from './resources/assistance.cjs';
+import { AnalyticsResource } from './resources/analytics.cjs';
+import { WebhooksResource } from './resources/webhooks.cjs';
+import { extractWebhookHeaders, WebhookVerificationError } from './webhooks-verify.cjs';
+import type { VerifyWebhookInput } from './webhooks-verify.cjs';
+import type { WebhookPayload } from './types/webhooks.cjs';
+import type { RateLimitInfo } from './types/common.cjs';
+export type { HttpClientOptions };
+/**
+ * Configuration options for the FedPulse SDK client.
+ */
+export interface FedPulseOptions extends Omit<HttpClientOptions, 'apiKey'> {
+    /**
+     * Your FedPulse API key.
+     * Generate one at https://app.fedpulse.dev/dashboard.
+     *
+     * **Security:** Never hardcode this value. Use environment variables:
+     * ```ts
+     * const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY! });
+     * ```
+     */
+    apiKey: string;
+}
+/**
+ * The FedPulse SDK client.
+ *
+ * All API interactions go through the resource properties on this class.
+ * The static `verifyWebhook` method can be used independently of a client instance.
+ */
+export declare class FedPulse {
+    /** Low-level HTTP client (exposed for advanced usage only). */
+    readonly http: HttpClient;
+    /** Federal contract opportunities (/v1/opportunities). */
+    readonly opportunities: OpportunitiesResource;
+    /** SAM.gov exclusions and bulk compliance checks (/v1/exclusions). */
+    readonly exclusions: ExclusionsResource;
+    /** SAM.gov registered entities / vendors (/v1/entities). */
+    readonly entities: EntitiesResource;
+    /** 360° entity intelligence and market analysis (/v1/intelligence). */
+    readonly intelligence: IntelligenceResource;
+    /** Federal assistance listings / CFDA programs (/v1/assistance). */
+    readonly assistance: AssistanceResource;
+    /** Per-user API usage analytics (/v1/analytics). */
+    readonly analytics: AnalyticsResource;
+    /** Webhook subscription management (/v1/webhooks). */
+    readonly webhooks: WebhooksResource;
+    constructor(options: FedPulseOptions);
+    /**
+     * Most recent rate-limit info observed from API responses.
+     *
+     * Updated after every API call. Useful for monitoring your rate-limit usage.
+     *
+     * @example
+     * ```ts
+     * await client.opportunities.list({ limit: 25 });
+     * console.log('Remaining requests:', client.rateLimit?.remaining);
+     * ```
+     */
+    get rateLimit(): RateLimitInfo | null;
+    /**
+     * Clear the in-memory response cache.
+     *
+     * Useful after writes that may invalidate cached GET responses.
+     */
+    clearCache(): void;
+    /**
+     * Verify an incoming FedPulse webhook delivery.
+     *
+     * Validates the HMAC-SHA256 signature, checks the timestamp against replay
+     * attacks, and returns the parsed payload on success.
+     *
+     * **IMPORTANT:** Pass the raw request body bytes — do not parse to JSON first.
+     *
+     * @param input  Headers, raw body, and signing secret.
+     * @returns Parsed, verified webhook payload.
+     * @throws {WebhookVerificationError} If signature/timestamp is invalid.
+     *
+     * @example
+     * ```ts
+     * // Express.js with `express.raw({ type: 'application/json' })`:
+     * const payload = FedPulse.verifyWebhook<{ noticeId: string }>({
+     *   rawBody: req.body,               // Buffer from express.raw()
+     *   signatureHeader: req.headers['x-fedpulse-signature'] as string,
+     *   timestampHeader: req.headers['x-fedpulse-timestamp'] as string,
+     *   secret: process.env.FEDPULSE_WEBHOOK_SECRET!,
+     * });
+     * console.log(payload.event, payload.data.noticeId);
+     * ```
+     */
+    static verifyWebhook<T = unknown>(input: VerifyWebhookInput): WebhookPayload<T>;
+    /**
+     * Extract FedPulse webhook headers from a request headers object.
+     *
+     * Handles case-insensitive lookup across Express, Fastify, Next.js, etc.
+     *
+     * @param headers  Headers object (plain object or `Headers` instance).
+     * @returns  Signature header, timestamp header, event type, and delivery ID.
+     *
+     * @example
+     * ```ts
+     * const { signatureHeader, timestampHeader } = FedPulse.extractWebhookHeaders(req.headers);
+     * const payload = FedPulse.verifyWebhook({ rawBody, signatureHeader, timestampHeader, secret });
+     * ```
+     */
+    static extractWebhookHeaders(headers: Record<string, string | string[] | undefined> | Headers): ReturnType<typeof extractWebhookHeaders>;
+}
+export { WebhookVerificationError };
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts

@@ -0,0 +1,136 @@
+/**
+ * FedPulse SDK — main client class.
+ *
+ * Instantiate this class with your API key to access all FedPulse
+ * data resources and the webhook verification utility.
+ *
+ * @example
+ * ```ts
+ * import { FedPulse } from '@fedpulse/sdk';
+ *
+ * const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY! });
+ *
+ * // Search contracts
+ * const { data } = await client.opportunities.list({ q: 'cloud', naics: '541512' });
+ *
+ * // Compliance check
+ * const { data: status } = await client.exclusions.check({ entities: [{ uei: 'ABCDEF123456' }] });
+ *
+ * // Verify an incoming webhook
+ * const payload = FedPulse.verifyWebhook({ rawBody, signatureHeader, timestampHeader, secret });
+ * ```
+ */
+import { HttpClient } from './http.js';
+import type { HttpClientOptions } from './http.js';
+import { OpportunitiesResource } from './resources/opportunities.js';
+import { ExclusionsResource } from './resources/exclusions.js';
+import { EntitiesResource } from './resources/entities.js';
+import { IntelligenceResource } from './resources/intelligence.js';
+import { AssistanceResource } from './resources/assistance.js';
+import { AnalyticsResource } from './resources/analytics.js';
+import { WebhooksResource } from './resources/webhooks.js';
+import { extractWebhookHeaders, WebhookVerificationError } from './webhooks-verify.js';
+import type { VerifyWebhookInput } from './webhooks-verify.js';
+import type { WebhookPayload } from './types/webhooks.js';
+import type { RateLimitInfo } from './types/common.js';
+export type { HttpClientOptions };
+/**
+ * Configuration options for the FedPulse SDK client.
+ */
+export interface FedPulseOptions extends Omit<HttpClientOptions, 'apiKey'> {
+    /**
+     * Your FedPulse API key.
+     * Generate one at https://app.fedpulse.dev/dashboard.
+     *
+     * **Security:** Never hardcode this value. Use environment variables:
+     * ```ts
+     * const client = new FedPulse({ apiKey: process.env.FEDPULSE_API_KEY! });
+     * ```
+     */
+    apiKey: string;
+}
+/**
+ * The FedPulse SDK client.
+ *
+ * All API interactions go through the resource properties on this class.
+ * The static `verifyWebhook` method can be used independently of a client instance.
+ */
+export declare class FedPulse {
+    /** Low-level HTTP client (exposed for advanced usage only). */
+    readonly http: HttpClient;
+    /** Federal contract opportunities (/v1/opportunities). */
+    readonly opportunities: OpportunitiesResource;
+    /** SAM.gov exclusions and bulk compliance checks (/v1/exclusions). */
+    readonly exclusions: ExclusionsResource;
+    /** SAM.gov registered entities / vendors (/v1/entities). */
+    readonly entities: EntitiesResource;
+    /** 360° entity intelligence and market analysis (/v1/intelligence). */
+    readonly intelligence: IntelligenceResource;
+    /** Federal assistance listings / CFDA programs (/v1/assistance). */
+    readonly assistance: AssistanceResource;
+    /** Per-user API usage analytics (/v1/analytics). */
+    readonly analytics: AnalyticsResource;
+    /** Webhook subscription management (/v1/webhooks). */
+    readonly webhooks: WebhooksResource;
+    constructor(options: FedPulseOptions);
+    /**
+     * Most recent rate-limit info observed from API responses.
+     *
+     * Updated after every API call. Useful for monitoring your rate-limit usage.
+     *
+     * @example
+     * ```ts
+     * await client.opportunities.list({ limit: 25 });
+     * console.log('Remaining requests:', client.rateLimit?.remaining);
+     * ```
+     */
+    get rateLimit(): RateLimitInfo | null;
+    /**
+     * Clear the in-memory response cache.
+     *
+     * Useful after writes that may invalidate cached GET responses.
+     */
+    clearCache(): void;
+    /**
+     * Verify an incoming FedPulse webhook delivery.
+     *
+     * Validates the HMAC-SHA256 signature, checks the timestamp against replay
+     * attacks, and returns the parsed payload on success.
+     *
+     * **IMPORTANT:** Pass the raw request body bytes — do not parse to JSON first.
+     *
+     * @param input  Headers, raw body, and signing secret.
+     * @returns Parsed, verified webhook payload.
+     * @throws {WebhookVerificationError} If signature/timestamp is invalid.
+     *
+     * @example
+     * ```ts
+     * // Express.js with `express.raw({ type: 'application/json' })`:
+     * const payload = FedPulse.verifyWebhook<{ noticeId: string }>({
+     *   rawBody: req.body,               // Buffer from express.raw()
+     *   signatureHeader: req.headers['x-fedpulse-signature'] as string,
+     *   timestampHeader: req.headers['x-fedpulse-timestamp'] as string,
+     *   secret: process.env.FEDPULSE_WEBHOOK_SECRET!,
+     * });
+     * console.log(payload.event, payload.data.noticeId);
+     * ```
+     */
+    static verifyWebhook<T = unknown>(input: VerifyWebhookInput): WebhookPayload<T>;
+    /**
+     * Extract FedPulse webhook headers from a request headers object.
+     *
+     * Handles case-insensitive lookup across Express, Fastify, Next.js, etc.
+     *
+     * @param headers  Headers object (plain object or `Headers` instance).
+     * @returns  Signature header, timestamp header, event type, and delivery ID.
+     *
+     * @example
+     * ```ts
+     * const { signatureHeader, timestampHeader } = FedPulse.extractWebhookHeaders(req.headers);
+     * const payload = FedPulse.verifyWebhook({ rawBody, signatureHeader, timestampHeader, secret });
+     * ```
+     */
+    static extractWebhookHeaders(headers: Record<string, string | string[] | undefined> | Headers): ReturnType<typeof extractWebhookHeaders>;
+}
+export { WebhookVerificationError };
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAEL,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAIlC;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,QAAQ,CAAC;IACxE;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;;;GAKG;AACH,qBAAa,QAAQ;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B,0DAA0D;IAC1D,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAC;IAE9C,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IAExC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAEpC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAE5C,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IAExC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IAEtC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;gBAExB,OAAO,EAAE,eAAe;IAYpC;;;;;;;;;;OAUG;IACH,IAAI,SAAS,IAAI,aAAa,GAAG,IAAI,CAEpC;IAED;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAMlB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,kBAAkB,GAAG,cAAc,CAAC,CAAC,CAAC;IAI/E;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,qBAAqB,CAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,OAAO,GAC/D,UAAU,CAAC,OAAO,qBAAqB,CAAC;CAG5C;AAED,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/dist/types/errors.d.cts

@@ -0,0 +1,139 @@
+/**
+ * FedPulse SDK error classes.
+ *
+ * All errors thrown by the SDK extend FedPulseError so callers can use
+ * `instanceof FedPulseError` to distinguish SDK errors from other exceptions.
+ */
+/**
+ * Base class for all FedPulse SDK errors.
+ */
+export declare class FedPulseError extends Error {
+    /** HTTP status code returned by the API, or 0 for network errors. */
+    readonly status: number;
+    /** Machine-readable error code from the API (e.g. NOT_FOUND, RATE_LIMIT_EXCEEDED). */
+    readonly code: string;
+    /** Request ID for debugging — correlates with API logs. */
+    readonly requestId: string | undefined;
+    /** Additional structured details from the API response. */
+    readonly details: unknown | undefined;
+    constructor({ message, status, code, requestId, details, }: {
+        message: string;
+        status: number;
+        code: string;
+        requestId?: string;
+        details?: unknown;
+    });
+}
+/**
+ * Thrown when the API returns 401 Unauthorized.
+ * Usually caused by missing, invalid, or revoked API key / JWT.
+ */
+export declare class AuthenticationError extends FedPulseError {
+    constructor(params: {
+        message: string;
+        requestId?: string;
+        details?: unknown;
+    });
+}
+/**
+ * Thrown when the API returns 403 Forbidden.
+ * Usually caused by insufficient plan permissions or missing key scope.
+ */
+export declare class PermissionError extends FedPulseError {
+    constructor(params: {
+        message: string;
+        code?: string;
+        requestId?: string;
+        details?: unknown;
+    });
+}
+/**
+ * Thrown when the API returns 404 Not Found.
+ */
+export declare class NotFoundError extends FedPulseError {
+    constructor(params: {
+        message: string;
+        requestId?: string;
+        details?: unknown;
+    });
+}
+/**
+ * Thrown when the API returns 422 Unprocessable Entity or 400 Bad Request
+ * due to invalid request parameters or body.
+ */
+export declare class ValidationError extends FedPulseError {
+    constructor(params: {
+        message: string;
+        status?: number;
+        requestId?: string;
+        details?: unknown;
+    });
+}
+/**
+ * Thrown when the API returns 429 Too Many Requests.
+ * The `retryAfter` property indicates when the rate limit resets (Unix seconds).
+ */
+export declare class RateLimitError extends FedPulseError {
+    /** Unix epoch seconds when the rate limit window resets. */
+    readonly retryAfter: number | undefined;
+    constructor(params: {
+        message: string;
+        retryAfter?: number;
+        requestId?: string;
+        details?: unknown;
+    });
+}
+/**
+ * Thrown when the API returns a 5xx server error.
+ */
+export declare class ServerError extends FedPulseError {
+    constructor(params: {
+        message: string;
+        status?: number;
+        code?: string;
+        requestId?: string;
+        details?: unknown;
+    });
+}
+/**
+ * Thrown when a network-level failure occurs (DNS, TCP, timeout, ECONNREFUSED).
+ * The `cause` property contains the original error.
+ */
+export declare class NetworkError extends FedPulseError {
+    /** The underlying network error. */
+    readonly cause: Error;
+    constructor(params: {
+        message: string;
+        cause: Error;
+    });
+}
+/**
+ * Thrown when a request exceeds the configured timeout.
+ */
+export declare class TimeoutError extends FedPulseError {
+    constructor(params: {
+        message: string;
+        requestId?: string;
+    });
+}
+/**
+ * Thrown when the SDK's retry budget is exhausted.
+ * The `lastError` property contains the final underlying error.
+ */
+export declare class RetryExhaustedError extends FedPulseError {
+    readonly lastError: FedPulseError;
+    readonly attempts: number;
+    constructor(params: {
+        lastError: FedPulseError;
+        attempts: number;
+    });
+}
+/**
+ * Factory — parses a raw API error response object into the correct error subtype.
+ *
+ * @param status   HTTP response status code.
+ * @param body     Parsed JSON body (may be the error envelope or anything).
+ * @param headers  Response headers map (used for Retry-After).
+ */
+export declare function createApiError(status: number, body: unknown, headers: Record<string, string | null>): FedPulseError;
+//# sourceMappingURL=errors.d.ts.map