@fastpix/fastpix-node 2.0.7 → 2.0.8

package/dist/esm/sdk/webhooks.d.ts

@@ -0,0 +1,151 @@
+import { ClientSDK } from "../lib/sdks.js";
+import type { CreateLiveStreamResponseDTO } from "../models/createlivestreamresponsedto.js";
+import type { Media } from "../models/media.js";
+import { Buffer } from "node:buffer";
+/**
+* The raw, unparsed webhook request body. Always pass the bytes exactly as they
+* arrived on the wire — verification fails if the body was re-serialized.
+*/
+export type WebhookRawBody = string | Buffer | Uint8Array;
+/**
+* Inbound request headers. Accepts a WHATWG `Headers` instance or a plain object
+* such as Node's `IncomingHttpHeaders` (values may be `string` or `string[]`).
+*/
+export type WebhookHeaders = Headers | Record<string, string | string[] | undefined>;
+/** The `object` envelope field: the resource this event is about. */
+export interface WebhookEventObject {
+    /** The resource type, e.g. "media" or "live-stream". */
+    type: string;
+    /** The affected resource id (equal to `data.id`). */
+    id: string;
+}
+/** The `workspace` envelope field. */
+export interface WebhookWorkspace {
+    id: string;
+    name: string;
+}
+/** Every webhook event type whose `data` payload is a {@link Media}. */
+export type MediaWebhookEventType = "video.media.created" | "video.media.updated" | "video.media.ready" | "video.media.failed" | "video.media.deleted" | "video.media.track.created" | "video.media.track.ready" | "video.media.track.updated" | "video.media.track.deleted" | "video.media.upload.cancelled" | "video.media.subtitle.generated.ready" | "video.media.source.ready" | "video.media.source.deleted" | "video.media.mp4Support.ready";
+/**
+* Every webhook event type whose `data` payload is a
+* {@link CreateLiveStreamResponseDTO}.
+*/
+export type LiveStreamWebhookEventType = "video.live_stream.created" | "video.live_stream.updated" | "video.live_stream.deleted" | "video.live_stream.simulcast_target.updated" | "video.live_stream.simulcast_target.deleted";
+/** Union of all known FastPix webhook event `type` strings. */
+export type WebhookEventType = MediaWebhookEventType | LiveStreamWebhookEventType;
+/**
+* A verified FastPix webhook event.
+*
+* Route on `type`, dedupe on the top-level `id` (the idempotency key — NOT
+* `object.id`), and read the affected resource id from `object.id`
+* (== `data.id`). `data` carries the full entity payload.
+*
+* Two type parameters, both with sensible defaults:
+*   - `TData` — the shape of `data` (defaults to a loose record).
+*   - `TType` — the literal `type` (defaults to any `string`).
+*
+* Most callers don't use these directly: {@link Webhooks.unwrap} returns the
+* discriminated {@link FastpixWebhookEvent} union, which narrows both for you.
+*/
+export interface WebhookEvent<TData = Record<string, unknown>, TType extends string = string> {
+    /** Routing key, e.g. "video.media.updated". */
+    type: TType;
+    /** The resource this event concerns. */
+    object: WebhookEventObject;
+    /** Event id — the idempotency key. Dedupe on this. */
+    id: string;
+    /** The workspace that produced the event. */
+    workspace: WebhookWorkspace;
+    /** Coarse status string, e.g. "media_created". */
+    status: string;
+    /** Full entity payload (has its own id/status/playbackIds/tracks/...). */
+    data: TData;
+    /** ISO-8601 timestamp string. */
+    createdAt: string;
+    /** Delivery attempt metadata. */
+    attempts: unknown[];
+}
+/** A `video.media.*` event. `data` is a {@link Media}. */
+export type MediaWebhookEvent = WebhookEvent<Media, MediaWebhookEventType>;
+/**
+* A `video.live_stream.*` event. `data` is a
+* {@link CreateLiveStreamResponseDTO}.
+*/
+export type LiveStreamWebhookEvent = WebhookEvent<CreateLiveStreamResponseDTO, LiveStreamWebhookEventType>;
+/**
+* The discriminated union of every known FastPix webhook event. This is what
+* {@link Webhooks.unwrap} returns: `switch (event.type)` narrows `event.data`
+* to the right payload type automatically.
+*
+* ```ts
+* const event = fastpix.webhooks.unwrap(body, headers);
+* switch (event.type) {
+*   case "video.media.ready":
+*     event.data.playbackIds; // ✅ typed as Media
+*     break;
+*   case "video.live_stream.created":
+*     event.data.streamKey;   // ✅ typed as CreateLiveStreamResponseDTO
+*     break;
+* }
+* ```
+*/
+export type FastpixWebhookEvent = MediaWebhookEvent | LiveStreamWebhookEvent;
+/**
+* Thrown when a webhook cannot be verified. Catch this to return `400` (bad
+* signature / malformed input) versus `500` (unexpected server error).
+*/
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+* Webhooks resource — verifies and unwraps inbound FastPix webhook deliveries.
+*
+* Accessed as `fastpix.webhooks`. The signing secret defaults to the client's
+* `webhookSecret` option (which itself falls back to
+* `process.env.FASTPIX_WEBHOOK_SECRET`), and can be overridden per call.
+*/
+export declare class Webhooks extends ClientSDK {
+    /**
+     * Verify the signature and return the parsed event.
+     *
+     * This is the single function most integrations need: hand it the raw body and
+     * request headers and it returns a typed {@link WebhookEvent}, throwing
+     * {@link WebhookVerificationError} if anything is wrong.
+     *
+     * @param body    The raw, unparsed request body (string or Buffer/Uint8Array).
+     * @param headers The inbound request headers.
+     * @param secret  Optional override for the webhook signing secret. Defaults to
+     *                the client's `webhookSecret` option.
+     * @returns The verified, parsed webhook event.
+     */
+    unwrap(body: WebhookRawBody, headers: WebhookHeaders, secret?: string | null): FastpixWebhookEvent;
+    /**
+     * Escape hatch: supply your own `data` shape (e.g. for an event type the SDK
+     * doesn't model yet) by passing an explicit type argument.
+     */
+    unwrap<TData>(body: WebhookRawBody, headers: WebhookHeaders, secret?: string | null): WebhookEvent<TData>;
+    /**
+     * Verify the signature without parsing. Throws {@link WebhookVerificationError}
+     * on any failure (missing secret, parsed-instead-of-raw body, missing header,
+     * or signature mismatch). Returns `void` on success.
+     */
+    verifySignature(body: WebhookRawBody, headers: WebhookHeaders, secret?: string | null): void;
+    /**
+     * Compute the base64 HMAC-SHA256 of the raw payload using the base64-decoded
+     * secret as the key. Matches FastPix's signing scheme exactly.
+     */
+    private computeSignature;
+    /**
+     * Constant-time string comparison. Performs a length check first (lengths are
+     * not secret), then delegates to `crypto.timingSafeEqual`.
+     */
+    private timingSafeEqual;
+    /**
+     * Read the `FastPix-Signature` header case-insensitively. If a framework hands
+     * back an array of values, the first one is used.
+     */
+    private extractSignature;
+}
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/esm/sdk/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../../src/sdk/webhooks.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,0CAA0C,CAAC;AAC5F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;EAGE;AACF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAE1D;;;EAGE;AACF,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAElD,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,sCAAsC;AACtC,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,MAAM,MAAM,qBAAqB,GAC7B,qBAAqB,GACrB,qBAAqB,GACrB,mBAAmB,GACnB,oBAAoB,GACpB,qBAAqB,GACrB,2BAA2B,GAC3B,yBAAyB,GACzB,2BAA2B,GAC3B,2BAA2B,GAC3B,8BAA8B,GAC9B,sCAAsC,GACtC,0BAA0B,GAC1B,4BAA4B,GAC5B,8BAA8B,CAAC;AAEnC;;;EAGE;AACF,MAAM,MAAM,0BAA0B,GAClC,2BAA2B,GAC3B,2BAA2B,GAC3B,2BAA2B,GAC3B,4CAA4C,GAC5C,4CAA4C,CAAC;AAEjD,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,0BAA0B,CAAC;AAE/B;;;;;;;;;;;;;EAaE;AACF,MAAM,WAAW,YAAY,CAC3B,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,KAAK,SAAS,MAAM,GAAG,MAAM;IAE7B,+CAA+C;IAC/C,IAAI,EAAE,KAAK,CAAC;IACZ,wCAAwC;IACxC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,SAAS,EAAE,gBAAgB,CAAC;IAC5B,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,IAAI,EAAE,KAAK,CAAC;IACZ,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,YAAY,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC;AAE3E;;;EAGE;AACF,MAAM,MAAM,sBAAsB,GAAG,YAAY,CAC/C,2BAA2B,EAC3B,0BAA0B,CAC3B,CAAC;AAEF;;;;;;;;;;;;;;;;EAgBE;AACF,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,GAAG,sBAAsB,CAAC;AAE7E;;;EAGE;AACF,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAKD;;;;;;EAME;AACF,qBAAa,QAAS,SAAQ,SAAS;IACrC;;;;;;;;;;;;OAYG;IACH,MAAM,CACJ,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,mBAAmB;IACtB;;;OAGG;IACH,MAAM,CAAC,KAAK,EACV,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,YAAY,CAAC,KAAK,CAAC;IAmBtB;;;;OAIG;IACH,eAAe,CACb,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,IAAI;IA6CP;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAmBzB"}

package/dist/esm/sdk/webhooks.js

@@ -0,0 +1,134 @@
+/*
+* FastPix webhook verification and unwrapping.
+*
+* Unlike the other files under `src/sdk/`, this resource is hand-written rather
+* than code-generated, but it follows the exact same conventions: it extends the
+* shared `ClientSDK` base class and reads its configuration from `this._options`
+* (here, the webhook signing secret resolved by the base constructor).
+*
+* Signature scheme (verified against a live FastPix delivery):
+*   - The signature travels in the `FastPix-Signature` header (read lowercase as
+*     `fastpix-signature`). It is a SINGLE base64 value — there is no `t=`/`v1=`
+*     structure to parse. A real digest looks like
+*     "oeDnZHgmhQ3UJ7qUw7uJAzo0O3Dbulfr0w89eoy0lVA=" (44 base64 chars => 32-byte
+*     HMAC-SHA256 output).
+*   - The signing secret is itself base64-encoded; decode it with
+*     `Buffer.from(secret, "base64")` and use those raw bytes as the HMAC key.
+*   - The HMAC-SHA256 is computed over the RAW REQUEST BODY ONLY (no timestamp
+*     prefix) and the digest is encoded as base64 (not hex).
+*   - No timestamp is signed, so there is no replay/tolerance window to enforce.
+*     Callers MUST instead dedupe on the top-level event `id` for idempotency.
+*/
+/// <reference types="node" />
+import { createHmac, timingSafeEqual as nodeTimingSafeEqual } from "node:crypto";
+import { ClientSDK } from "../lib/sdks.js";
+import { Buffer } from "node:buffer";
+/**
+* Thrown when a webhook cannot be verified. Catch this to return `400` (bad
+* signature / malformed input) versus `500` (unexpected server error).
+*/
+export class WebhookVerificationError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "WebhookVerificationError";
+    }
+}
+/** Header name we read, always lower-cased per the HTTP spec. */
+const SIGNATURE_HEADER = "fastpix-signature";
+/**
+* Webhooks resource — verifies and unwraps inbound FastPix webhook deliveries.
+*
+* Accessed as `fastpix.webhooks`. The signing secret defaults to the client's
+* `webhookSecret` option (which itself falls back to
+* `process.env.FASTPIX_WEBHOOK_SECRET`), and can be overridden per call.
+*/
+export class Webhooks extends ClientSDK {
+    unwrap(body, headers, secret) {
+        this.verifySignature(body, headers, secret);
+        const raw = typeof body === "string" ? body : Buffer.from(body).toString("utf8");
+        try {
+            return JSON.parse(raw);
+        }
+        catch (cause) {
+            throw new WebhookVerificationError("Webhook signature verified but the body is not valid JSON.", { cause });
+        }
+    }
+    /**
+     * Verify the signature without parsing. Throws {@link WebhookVerificationError}
+     * on any failure (missing secret, parsed-instead-of-raw body, missing header,
+     * or signature mismatch). Returns `void` on success.
+     */
+    verifySignature(body, headers, secret) {
+        // 1. Resolve the signing secret. Explicit arg wins, then the client option.
+        const signingSecret = secret ?? this._options.webhookSecret;
+        if (!signingSecret) {
+            throw new WebhookVerificationError("Missing webhook secret. Pass one to unwrap()/verifySignature(), set the "
+                + "`webhookSecret` client option, or set the FASTPIX_WEBHOOK_SECRET "
+                + "environment variable.");
+        }
+        // 2. The body MUST be the raw bytes. A plain object means the caller already
+        //    JSON.parsed it, which destroys the exact bytes the signature covers.
+        if (typeof body !== "string"
+            && !Buffer.isBuffer(body)
+            && !(body instanceof Uint8Array)) {
+            throw new WebhookVerificationError("Webhook body must be the raw request payload as a string or Buffer. It "
+                + "looks like the body was already parsed into an object — configure your "
+                + "framework to expose the raw body (e.g. express.raw({ type: "
+                + "'application/json' })).");
+        }
+        // 3. Pull the signature header (single base64 value, no `t=`/`v1=` parts).
+        const provided = this.extractSignature(headers);
+        if (!provided) {
+            throw new WebhookVerificationError(`Missing "FastPix-Signature" header on the webhook request.`);
+        }
+        // 4. Compute the expected signature over the raw body and compare in
+        //    constant time.
+        const expected = this.computeSignature(body, signingSecret);
+        if (!this.timingSafeEqual(provided, expected)) {
+            throw new WebhookVerificationError("Webhook signature mismatch. The payload may have been tampered with, or "
+                + "a different signing secret was used.");
+        }
+    }
+    /**
+     * Compute the base64 HMAC-SHA256 of the raw payload using the base64-decoded
+     * secret as the key. Matches FastPix's signing scheme exactly.
+     */
+    computeSignature(payload, secret) {
+        const key = Buffer.from(secret, "base64");
+        return createHmac("sha256", key).update(payload).digest("base64");
+    }
+    /**
+     * Constant-time string comparison. Performs a length check first (lengths are
+     * not secret), then delegates to `crypto.timingSafeEqual`.
+     */
+    timingSafeEqual(a, b) {
+        const ab = Buffer.from(a);
+        const bb = Buffer.from(b);
+        if (ab.length !== bb.length) {
+            return false;
+        }
+        return nodeTimingSafeEqual(ab, bb);
+    }
+    /**
+     * Read the `FastPix-Signature` header case-insensitively. If a framework hands
+     * back an array of values, the first one is used.
+     */
+    extractSignature(headers) {
+        if (typeof Headers !== "undefined" && headers instanceof Headers) {
+            return headers.get(SIGNATURE_HEADER) ?? undefined;
+        }
+        const record = headers;
+        // Fast path: HTTP servers (e.g. Node) already lower-case header names.
+        let value = record[SIGNATURE_HEADER];
+        if (value === undefined) {
+            for (const key of Object.keys(record)) {
+                if (key.toLowerCase() === SIGNATURE_HEADER) {
+                    value = record[key];
+                    break;
+                }
+            }
+        }
+        return Array.isArray(value) ? value[0] : value;
+    }
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/esm/sdk/webhooks.js.map

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

package/dist/esm/types/primitives.d.ts

@@ -6,6 +6,6 @@ export declare function bigint(): z.ZodMiniType<bigint>;
 export declare function date(): z.ZodMiniType<Date>;
 export declare function literal<T extends string | number | boolean>(value: T): z.ZodMiniType<T>;
 export declare function literalBigInt<T extends bigint>(value: T): z.ZodMiniType<T>;
-export declare function optional<T extends z.ZodMiniType>(t: T): z.ZodMiniUnion<readonly [z.ZodMiniUndefined, z.ZodMiniPipe<z.ZodMiniNull, z.ZodMiniTransform<never, null>>, T]>;
+export declare function optional<T extends z.ZodMiniType>(t: T): z.ZodMiniOptional<z.ZodMiniUnion<readonly [z.ZodMiniPipe<z.ZodMiniNull, z.ZodMiniTransform<never, null>>, T]>>;
 export declare function nullable<T extends z.ZodMiniType>(t: T): z.ZodMiniUnion<readonly [z.ZodMiniNull, z.ZodMiniPipe<z.ZodMiniUndefined, z.ZodMiniTransform<never, undefined>>, T]>;
 //# sourceMappingURL=primitives.d.ts.map

package/dist/esm/types/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/types/primitives.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,CAAC,MAAM,aAAa,CAAC;AAIjC,wBAAgB,MAAM,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAU9C;AAED,wBAAgB,OAAO,IAAI,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAuBhD;AAED,wBAAgB,MAAM,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAyB9C;AAED,wBAAgB,MAAM,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAoB9C;AAED,wBAAgB,IAAI,IAAI,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CA0B1C;AAED,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EACzD,KAAK,EAAE,CAAC,GACP,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAElB;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAU1E;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,mHAQrD;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,wHAQrD"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/types/primitives.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,CAAC,MAAM,aAAa,CAAC;AAIjC,wBAAgB,MAAM,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAU9C;AAED,wBAAgB,OAAO,IAAI,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAuBhD;AAED,wBAAgB,MAAM,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAyB9C;AAED,wBAAgB,MAAM,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAoB9C;AAED,wBAAgB,IAAI,IAAI,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CA0B1C;AAED,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EACzD,KAAK,EAAE,CAAC,GACP,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAElB;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAU1E;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,kHAarD;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC,wHAQrD"}

package/dist/esm/types/primitives.js

@@ -105,12 +105,16 @@ export function literalBigInt(value) {
     z.transform(BigInt));
 }
 export function optional(t) {
-    return z.union([
-        z.undefined(),
+    // Wrap in `z.optional` so the object key is treated as optional regardless of
+    // zod version. zod >=4.4.0 changed object parsing so that a missing key whose
+    // value schema is merely a `union` containing `z.undefined()` is treated as
+    // required ("nonoptional"); `z.optional(...)` marks the key optional in every
+    // 4.x. The inner null->undefined pipe is preserved.
+    return z.optional(z.union([
         // Null -> undefined
         z.pipe(z.null(), z.transform(() => unrecognized(undefined))),
         t,
-    ]);
+    ]));
 }
 export function nullable(t) {
     return z.union([

package/dist/esm/types/primitives.js.map

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

package/examples/webhooksServer.example.ts

@@ -0,0 +1,93 @@
+/**
+* Example: receiving FastPix webhooks with Express.
+*
+* To run this example from the examples directory:
+*   npm i express && npm i -D @types/express
+*   npm run build && npx tsx webhooksServer.example.ts
+*
+* Set FASTPIX_WEBHOOK_SECRET in your environment (or .env) to the webhook
+* signing secret from the FastPix dashboard. It is base64-encoded and is NOT
+* your API password.
+*/
+
+import dotenv from "dotenv";
+dotenv.config();
+
+import express from "express";
+import { Fastpix, WebhookVerificationError } from "@fastpix/fastpix-node";
+
+// `security` here is only needed if this same client also makes API calls.
+// Webhook verification uses `webhookSecret` (or FASTPIX_WEBHOOK_SECRET), which
+// is completely separate from the API username/password.
+const fastpix = new Fastpix({
+  webhookSecret: process.env.FASTPIX_WEBHOOK_SECRET, // defaults to this env var anyway
+});
+
+const app = express();
+
+// Don't advertise the framework/version in responses (avoids the
+// "X-Powered-By: Express" header). Recommended for production endpoints.
+app.disable("x-powered-by");
+
+// In-memory idempotency store. In production use a durable store (Redis, a DB
+// table with a unique constraint on the event id, etc.) so dedupe survives
+// restarts and works across instances.
+const processedEventIds = new Set<string>();
+
+app.post(
+  "/webhooks/fastpix",
+  // CRITICAL: capture the RAW body. The signature is computed over the exact
+  // bytes FastPix sent — express.json() would re-serialize and break verification.
+  express.raw({ type: "application/json" }),
+  (req, res) => {
+    const signature = req.header("FastPix-Signature");
+
+    // 1. Endpoint-validation PING.
+    //    When you add/verify an endpoint, FastPix sends a probe with an empty
+    //    body (or "{}") and NO signature. Acknowledge it with 200 BEFORE doing
+    //    any verification, otherwise the endpoint can't be validated.
+    const rawText = req.body?.toString("utf8") ?? "";
+    const isPing = !signature && (rawText.trim() === "" || rawText.trim() === "{}");
+    if (isPing) {
+      return res.status(200).send("ok");
+    }
+
+    // 2. Real event: verify + parse in one call.
+    try {
+      const event = fastpix.webhooks.unwrap(req.body, req.headers);
+
+      // 3. Dedupe on the TOP-LEVEL event id (the idempotency key), not object.id.
+      //    There is no signed timestamp, so idempotency is the only replay guard.
+      if (processedEventIds.has(event.id)) {
+        return res.status(202).send("duplicate ignored");
+      }
+      processedEventIds.add(event.id);
+
+      // 4. Route on `type`; the affected resource id is `object.id` (== data.id).
+      switch (event.type) {
+        case "video.media.created":
+        case "video.media.updated":
+          console.log(`media ${event.object.id} -> ${event.status}`);
+          break;
+        default:
+          console.log(`unhandled event type: ${event.type}`);
+      }
+
+      // Acknowledge fast (202 Accepted) and do heavy work asynchronously.
+      return res.status(202).send("accepted");
+    } catch (err) {
+      // Verification failures are client errors -> 400 so FastPix retries later.
+      if (err instanceof WebhookVerificationError) {
+        console.warn("webhook verification failed:", err.message);
+        return res.status(400).send("invalid signature");
+      }
+      throw err; // unexpected -> let Express return 500
+    }
+  },
+);
+
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => {
+  console.log(`Listening for FastPix webhooks on http://localhost:${port}/webhooks/fastpix`);
+});
+ 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastpix/fastpix-node",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "author": {
     "name": "FastPix-Dev",
     "email": "devs@fastpix.com",
@@ -37,6 +37,7 @@
     "@eslint/js": "^9.19.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.0.2",
+    "dotenv": "^17.4.2",
     "eslint": "^9.19.0",
     "exceljs": "^4.4.0",
     "globals": "^15.14.0",
@@ -48,9 +49,7 @@
     "typescript-eslint": "^8.26.0"
   },
   "dependencies": {
-    "@fastpix/fastpix-node": "^2.0.6",
-    "dotenv": "^17.4.2",
-    "zod": "^3.25.65 || ^4.0.0"
+    "zod": "^3.25.65 || >=4.0.0 <4.4.0"
   },
   "exports": {
     ".": {

package/src/index.ts

@@ -9,3 +9,4 @@ export * as files from "./lib/files.js";
 export { HTTPClient } from "./lib/http.js";
 export type { Fetcher, HTTPClientOptions } from "./lib/http.js";
 export * from "./sdk/sdk.js";
+export * from "./sdk/webhooks.js";

package/src/lib/config.ts

@@ -26,6 +26,18 @@ export type SDKOptions = {
    */
   security?: models.Security | (() => Promise<models.Security>) | undefined;
 
+  /**
+   * The secret used to verify FastPix webhook signatures.
+   *
+   * This is the webhook signing secret shown in the FastPix dashboard, NOT the
+   * API password supplied via `security`. Keep the two separate: `security`
+   * authenticates outbound API requests, while `webhookSecret` verifies inbound
+   * webhook deliveries.
+   *
+   * Defaults to `process.env.FASTPIX_WEBHOOK_SECRET` when not provided.
+   */
+  webhookSecret?: string | null | undefined;
+
   httpClient?: HTTPClient;
   /**
    * Allows overriding the default server used by the SDK
@@ -67,8 +79,8 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 export const SDK_METADATA = {
   language: "typescript",
   openapiDocVersion: "1.0.0",
-  sdkVersion: "2.0.7",
+  sdkVersion: "2.0.8",
   genVersion: "2.781.2",
   userAgent:
-    "fastpix-sdk/typescript 2.0.7 2.781.2 1.0.0 @fastpix/fastpix-node",
+    "fastpix-sdk/typescript 2.0.8 2.781.2 1.0.0 @fastpix/fastpix-node",
 } as const;

package/src/lib/env.ts

@@ -10,14 +10,14 @@ import { dlv } from "./dlv.js";
 export interface Env {
   FASTPIX_USERNAME?: string | undefined;
   FASTPIX_PASSWORD?: string | undefined;
-
+  FASTPIX_WEBHOOK_SECRET?: string | undefined;
   FASTPIX_DEBUG?: boolean | undefined;
 }
 
 export const envSchema: z.ZodMiniType<Env, unknown> = z.object({
   FASTPIX_USERNAME: z.optional(z.string()),
   FASTPIX_PASSWORD: z.optional(z.string()),
-
+  FASTPIX_WEBHOOK_SECRET: z.optional(z.string()),
   FASTPIX_DEBUG: z.optional(z.coerce.boolean()),
 });
 

package/src/lib/sdks.ts

@@ -198,7 +198,15 @@ export class ClientSDK {
     this._baseURL = url;
     this.#httpClient = options.httpClient || defaultHttpClient;
 
-    this._options = { ...options, hooks: this.#hooks };
+    this._options = {
+      ...options,
+      // Resolve the webhook signing secret once, preferring an explicit option
+      // and falling back to the FASTPIX_WEBHOOK_SECRET env var. Kept separate
+      // from `security` (the API password) on purpose. Carried forward here so
+      // any cloned options (e.g. per-resource clients) inherit it.
+      webhookSecret: options.webhookSecret ?? env().FASTPIX_WEBHOOK_SECRET ?? null,
+      hooks: this.#hooks,
+    };
 
     this.#logger = this._options.debugLogger;
     if (!this.#logger && env().FASTPIX_DEBUG) {

package/src/sdk/sdk.ts

@@ -25,6 +25,7 @@ import { SigningKeys } from "./signingkeys.js";
 import { Simulcasts } from "./simulcasts.js";
 import { SimulcastStreams } from "./simulcaststreams.js";
 import { Views } from "./views.js";
+import { Webhooks } from "./webhooks.js";
 
 export class Fastpix extends ClientSDK {
   private _inputVideo?: InputVideo;
@@ -146,4 +147,11 @@ export class Fastpix extends ClientSDK {
     this._errors ??= new Errors(this._options);
     return this._errors;
   }
+
+  private _webhooks?: Webhooks;
+  get webhooks(): Webhooks {
+    this._webhooks ??= new Webhooks(this._options);
+    return this._webhooks;
+  }
+ 
 }