@fastpix/fastpix-node 1.0.1 → 2.0.0

package/src/sdk/views.ts

@@ -0,0 +1,173 @@
+import { viewsGetDataViewlistCurrentViewsFilter } from "../funcs/viewsGetDataViewlistCurrentViewsFilter.js";
+import { viewsGetDataViewlistCurrentViewsGetTimeseriesViews } from "../funcs/viewsGetDataViewlistCurrentViewsGetTimeseriesViews.js";
+import { viewsGetVideoViewDetails } from "../funcs/viewsGetVideoViewDetails.js";
+import { viewsListByTopContent } from "../funcs/viewsListByTopContent.js";
+import { viewsListVideoViews } from "../funcs/viewsListVideoViews.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class Views extends ClientSDK {
+  /**
+   * List video views
+   *
+   * @remarks
+   * Retrieves a list of video views that fall within the specified filters and have been completed within a defined timespan. It allows you to analyse viewer interactions with your video content effectively.
+   *
+   * #### How it works
+   *
+   *   1. Make a `GET` request to this endpoint with the desired query parameters.
+   *
+   *   2. Specify the timespan for which you want to retrieve the video views using the `timespan[]` parameter.
+   *
+   *   3. Filter the views based on dimensions such as browser, device, video title, viewer ID, etc., using the `filterby[]` parameter. Get the dimensions by calling <a href="https://docs.fastpix.io/reference/list_dimensions">list the dimensions</a> endpoint.
+   *
+   *   4. Paginate the results using the `limit` and `offset` parameters.
+   *
+   *   5. Optionally, filter by `viewerId`, `errorCode`, `orderBy` a specific field, and sort in ascending or descending order.
+   *
+   *   6. Receive a response containing the list of video views matching the specified criteria.
+   *
+   * Each view in the response will include a unique `viewId`. You can use this `viewId` to call the <a href="https://docs.fastpix.io/reference/get_video_view_details">get details of video view</a> endpoint to retrieve more detailed information about that specific view.
+   *
+   * #### Example
+   *
+   * Suppose you're managing a video streaming service and need to analyze how the content performs across different devices and browsers. By calling the List Video Views endpoint with filters like `browser_name` and `device_type`, you can get insights into which platforms are most popular with the audience. This data will help you optimize content for the most-used platforms and troubleshoot any playback issues on less common devices.
+   *
+   *   Related guide: <a href="https://docs.fastpix.io/docs/audience-metrics">Audience metrics</a>, <a href="https://docs.fastpix.io/docs/understand-dashboard-ui#1-views-dashboard">Views dashboard</a>
+   */
+  async listVideoViews(
+    request: operations.ListVideoViewsRequest,
+    options?: RequestOptions,
+  ): Promise<operations.ListVideoViewsResponse> {
+    return unwrapAsync(viewsListVideoViews(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get details of video view
+   *
+   * @remarks
+   * Allows you to retrieve detailed information about a specific video view using its unique `viewId`. This is useful for getting insights into individual viewer interactions with your video content. This detailed information is valuable for enhancing user experience and improving engagement with your video assets.
+   *
+   * Make a `GET` request to this endpoint and you will receive a response containing detailed information about the specified video view, including metrics and attributes related to that view.
+   *
+   * #### Example
+   *
+   * Suppose a developer receives a report of a poor viewing experience for a specific user. By using this endpoint with the user's `viewId`, the developer can retrieve metrics like buffering duration, playback errors, and session length. This data allows the developer to pinpoint issues (such as poor connectivity or a browser-specific problem) and take steps to improve the user experience.
+   *
+   * Related guide: <a href="https://docs.fastpix.io/page/what-video-data-do-we-capture#/">What Video Data do we capture?</a>
+   */
+  async getVideoViewDetails(
+    request: operations.GetVideoViewDetailsRequest,
+    options?: RequestOptions,
+  ): Promise<operations.GetVideoViewDetailsResponse> {
+    return unwrapAsync(viewsGetVideoViewDetails(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * List by top content
+   *
+   * @remarks
+   * Retrieves a list of the top video views that fall within the specified filters and have been completed within a defined timespan. It allows you to identify the most popular content based on viewer interactions.
+   *
+   * #### How it works
+   *
+   *   1. Make a `GET` request to this endpoint with the desired query parameters.
+   *
+   *   2. Specify the timespan for which you want to retrieve the top content using the `timespan[]` parameter.
+   *
+   *   3. Filter the views based on dimensions such as browser, device, video title, etc., using the `filterby[]` parameter.
+   *
+   *   4. `Limit` the results to control the number of top views returned.
+   *
+   *   5. Receive a response containing the list of top video views matching the specified criteria.
+   *
+   *   Related guide: <a href="https://docs.fastpix.io/page/how-to-get-top-performing-content">Get top-performing content</a>
+   */
+  async listByTopContent(
+    request: operations.ListByTopContentRequest,
+    options?: RequestOptions,
+  ): Promise<operations.ListByTopContentResponse> {
+    return unwrapAsync(viewsListByTopContent(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get concurrent viewers timeseries
+   *
+   * @remarks
+   * Retrieves a time series of the number of concurrent viewers, providing a real-time snapshot of audience activity over the last 30 minutes. This endpoint is essential for monitoring live events, gauging audience reaction to new content releases, or understanding immediate engagement trends.
+   *
+   * #### How it works
+   *
+   *   1. Make a simple `GET` request to this endpoint. No query parameters are needed.
+   *
+   *   2. The API automatically gathers data for the **last 30 minutes**, calculating the number of concurrent viewers at regular intervals within that window.
+   *
+   *   3. Receive a response containing a `data` array, where each object represents a specific point in time.
+   *
+   *   4. Each object in the array includes the `intervalTime` (the timestamp of the measurement) and `numberOfViews` (the count of concurrent viewers at that instant), allowing you to easily plot viewer activity over time.
+   *
+   * #### Example
+   *
+   * Imagine you are streaming a major live event, such as a product launch, a sports game, or a webinar. You need to monitor audience engagement in real-time to see if viewership is increasing, decreasing, or holding steady.
+   *
+   * By calling this endpoint periodically (e.g., every minute), you can plot a live graph of your viewership. This allows you to identify peak moments of interest, see the immediate impact of social media promotions, or detect potential technical issues if there's a sudden, unexpected drop in viewers
+   */
+  async getDataViewlistCurrentViewsGetTimeseriesViews(
+    options?: RequestOptions,
+  ): Promise<operations.GetDataViewlistCurrentViewsGetTimeseriesViewsResponse> {
+    return unwrapAsync(viewsGetDataViewlistCurrentViewsGetTimeseriesViews(
+      this,
+      options,
+    ));
+  }
+
+  /**
+   * Get concurrent viewers breakdown by dimension
+   *
+   * @remarks
+   * Retrieves a real-time breakdown of present concurrent viewers, grouped by a chosen dimension. This endpoint allows you to see how your audience is distributed across different categories like geography, content, or technology, based on activity in the last 30 minutes.
+   *
+   * For example, you can see how many viewers are currently watching from the US vs. India, or which video titles are most popular right now.
+   *
+   * #### How it works
+   *
+   * 1. Make a `GET` request to this endpoint.
+   *
+   * 2. Specify the `dimension` you want to group by in the query parameters (e.g., `dimension=country` or `dimension=video_title`). This is the most important parameter as it defines how the data is categorized.
+   *
+   * 3. Optionally, use the `limit` parameter to control the number of results returned (e.g., `limit=5` to get the top 5 countries).
+   *
+   * 4. The API analyzes viewer data from the last 30 minutes and aggregates the viewer counts for each unique value within the chosen dimension.
+   *
+   * 5. Receive a response containing a `data` array, where each object represents a specific group (e.g., a country or a video title) and its corresponding number of `concurrent_viewers`.
+   *
+   * #### Example
+   *
+   * Imagine you are running a global streaming platform and have just launched a new original series. You want to see, in real-time, which regions are engaging most with the new content versus your older library content.
+   *
+   * By calling this endpoint with `dimension=video_title`, you can immediately see a list of your most-watched videos right now and their respective viewer counts. Then, by calling it again with `dimension=country`, you can get a live breakdown of your audience's geographic distribution. This helps you confirm if your marketing efforts in specific countries are paying off instantly and allows you to make data-driven decisions during live events.
+   */
+  async getDataViewlistCurrentViewsFilter(
+    request?: operations.GetDataViewlistCurrentViewsFilterRequest | undefined,
+    options?: RequestOptions,
+  ): Promise<operations.GetDataViewlistCurrentViewsFilterResponse> {
+    return unwrapAsync(viewsGetDataViewlistCurrentViewsFilter(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/types/async.ts

@@ -0,0 +1,64 @@
+export type APICall =
+  | {
+      status: "complete";
+      request: Request;
+      response: Response;
+    }
+  | {
+      status: "request-error";
+      request: Request;
+      response?: undefined;
+    }
+  | {
+      status: "invalid";
+      request?: undefined;
+      response?: undefined;
+    };
+
+export class APIPromise<T> implements Promise<T> {
+  readonly #promise: Promise<[T, APICall]>;
+  readonly #unwrapped: Promise<T>;
+
+  readonly [Symbol.toStringTag] = "APIPromise";
+
+  constructor(p: [T, APICall] | Promise<[T, APICall]>) {
+    this.#promise = p instanceof Promise ? p : Promise.resolve(p);
+    this.#unwrapped =
+      p instanceof Promise
+        ? this.#promise.then(([value]) => value)
+        : Promise.resolve(p[0]);
+  }
+
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?:
+      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+      | null
+      | undefined,
+    onrejected?:
+      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | null
+      | undefined,
+  ): Promise<TResult1 | TResult2> {
+    return this.#promise.then(
+      onfulfilled ? ([value]) => onfulfilled(value) : void 0,
+      onrejected,
+    );
+  }
+
+  catch<TResult = never>(
+    onrejected?:
+      | ((reason: any) => TResult | PromiseLike<TResult>)
+      | null
+      | undefined,
+  ): Promise<T | TResult> {
+    return this.#unwrapped.catch(onrejected);
+  }
+
+  finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+    return this.#unwrapped.finally(onfinally);
+  }
+
+  $inspect(): Promise<[T, APICall]> {
+    return this.#promise;
+  }
+}

package/src/types/blobs.ts

@@ -0,0 +1,27 @@
+import * as z from "zod";
+
+export const blobLikeSchema: z.ZodType<Blob, z.ZodTypeDef, Blob> =
+  z.custom<Blob>(isBlobLike, {
+    message: "expected a Blob, File or Blob-like object",
+    fatal: true,
+  });
+
+export function isBlobLike(val: unknown): val is Blob {
+  if (val instanceof Blob) {
+    return true;
+  }
+
+  if (typeof val !== "object" || val == null || !(Symbol.toStringTag in val)) {
+    return false;
+  }
+
+  const name = val[Symbol.toStringTag];
+  if (typeof name !== "string") {
+    return false;
+  }
+  if (name !== "Blob" && name !== "File") {
+    return false;
+  }
+
+  return "stream" in val && typeof val.stream === "function";
+}

package/src/types/constdatetime.ts

@@ -0,0 +1,11 @@
+import * as z from "zod";
+
+export function constDateTime(
+  val: string,
+): z.ZodType<string, z.ZodTypeDef, unknown> {
+  return z.custom<string>((v) => {
+    return (
+      typeof v === "string" && new Date(v).getTime() === new Date(val).getTime()
+    );
+  }, `Value must be equivalent to ${val}`);
+}

package/src/types/enums.ts

@@ -0,0 +1,12 @@
+declare const __brand: unique symbol;
+export type Unrecognized<T> = T & { [__brand]: "unrecognized" };
+
+export function catchUnrecognizedEnum<T>(value: T): Unrecognized<T> {
+  return value as Unrecognized<T>;
+}
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+export type ClosedEnum<T> = T[keyof T];
+export type OpenEnum<T> =
+  | Prettify<T[keyof T]>
+  | Unrecognized<T[keyof T] extends number ? number : string>;

package/src/types/fp.ts

@@ -0,0 +1,46 @@
+/**
+ * A monad that captures the result of a function call or an error if it was not
+ * successful. Railway programming, enabled by this type, can be a nicer
+ * alternative to traditional exception throwing because it allows functions to
+ * declare all _known_ errors with static types and then check for them
+ * exhaustively in application code. Thrown exception have a type of `unknown`
+ * and break out of regular control flow of programs making them harder to
+ * inspect and more verbose work with due to try-catch blocks.
+ */
+export type Result<T, E = unknown> =
+  | { ok: true; value: T; error?: never }
+  | { ok: false; value?: never; error: E };
+
+export function OK<V>(value: V): Result<V, never> {
+  return { ok: true, value };
+}
+
+export function ERR<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/**
+ * unwrap is a convenience function for extracting a value from a result or
+ * throwing if there was an error.
+ */
+export function unwrap<T>(r: Result<T, unknown>): T {
+  if (!r.ok) {
+    throw r.error;
+  }
+  return r.value;
+}
+
+/**
+ * unwrapAsync is a convenience function for resolving a value from a Promise
+ * of a result or rejecting if an error occurred.
+ */
+export async function unwrapAsync<T>(
+  pr: Promise<Result<T, unknown>>,
+): Promise<T> {
+  const r = await pr;
+  if (!r.ok) {
+    throw r.error;
+  }
+
+  return r.value;
+}

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export { blobLikeSchema, isBlobLike } from "./blobs.js";
+export { catchUnrecognizedEnum } from "./enums.js";
+export type { ClosedEnum, OpenEnum, Unrecognized } from "./enums.js";
+export type { Result } from "./fp.js";
+export type { PageIterator, Paginator } from "./operations.js";
+export { createPageIterator } from "./operations.js";
+export { RFCDate } from "./rfcdate.js";

package/src/types/operations.ts

@@ -0,0 +1,101 @@
+import { Result } from "./fp.js";
+
+export type Paginator<V> = () => Promise<V & { next: Paginator<V> }> | null;
+
+export type PageIterator<V, PageState = unknown> = V & {
+  next: Paginator<V>;
+  [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+  "~next"?: PageState | undefined;
+};
+
+export function createPageIterator<V>(
+  page: V & { next: Paginator<V> },
+  halt: (v: V) => boolean,
+): {
+  [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+} {
+  return {
+    [Symbol.asyncIterator]: async function* paginator() {
+      yield page;
+      if (halt(page)) {
+        return;
+      }
+
+      let p: typeof page | null = page;
+      for (p = await p.next(); p != null; p = await p.next()) {
+        yield p;
+        if (halt(p)) {
+          return;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * This utility create a special iterator that yields a single value and
+ * terminates. It is useful in paginated SDK functions that have early return
+ * paths when things go wrong.
+ */
+export function haltIterator<V extends object>(
+  v: V,
+): PageIterator<V, undefined> {
+  return {
+    ...v,
+    next: () => null,
+    [Symbol.asyncIterator]: async function* paginator() {
+      yield v;
+    },
+  };
+}
+
+/**
+ * Converts an async iterator of `Result<V, E>` into an async iterator of `V`.
+ * When error results occur, the underlying error value is thrown.
+ */
+export async function unwrapResultIterator<V, PageState>(
+  iteratorPromise: Promise<PageIterator<Result<V, unknown>, PageState>>,
+): Promise<PageIterator<V, PageState>> {
+  const resultIter = await iteratorPromise;
+
+  if (!resultIter.ok) {
+    throw resultIter.error;
+  }
+
+  return {
+    ...resultIter.value,
+    next: unwrapPaginator(resultIter.next),
+    "~next": resultIter["~next"],
+    [Symbol.asyncIterator]: async function* paginator() {
+      for await (const page of resultIter) {
+        if (!page.ok) {
+          throw page.error;
+        }
+        yield page.value;
+      }
+    },
+  };
+}
+
+function unwrapPaginator<V>(
+  paginator: Paginator<Result<V, unknown>>,
+): Paginator<V> {
+  return () => {
+    const nextResult = paginator();
+    if (nextResult == null) {
+      return null;
+    }
+    return nextResult.then((res) => {
+      if (!res.ok) {
+        throw res.error;
+      }
+      const out = {
+        ...res.value,
+        next: unwrapPaginator(res.next),
+      };
+      return out;
+    });
+  };
+}
+
+export const URL_OVERRIDE = Symbol("URL_OVERRIDE");

package/src/types/rfcdate.ts

@@ -0,0 +1,50 @@
+const dateRE = /^\d{4}-\d{2}-\d{2}$/;
+
+export class RFCDate {
+  private serialized: string;
+
+  /**
+   * Creates a new RFCDate instance using today's date.
+   */
+  static today(): RFCDate {
+    return new RFCDate(new Date());
+  }
+
+  /**
+   * Creates a new RFCDate instance using the provided input.
+   * If a string is used then in must be in the format YYYY-MM-DD.
+   *
+   * @param date A Date object or a date string in YYYY-MM-DD format
+   * @example
+   * new RFCDate("2022-01-01")
+   * @example
+   * new RFCDate(new Date())
+   */
+  constructor(date: Date | string) {
+    if (typeof date === "string" && !dateRE.test(date)) {
+      throw new RangeError(
+        "RFCDate: date strings must be in the format YYYY-MM-DD: " + date,
+      );
+    }
+
+    const value = new Date(date);
+    if (isNaN(+value)) {
+      throw new RangeError("RFCDate: invalid date provided: " + date);
+    }
+
+    this.serialized = value.toISOString().slice(0, "YYYY-MM-DD".length);
+    if (!dateRE.test(this.serialized)) {
+      throw new TypeError(
+        `RFCDate: failed to build valid date with given value: ${date} serialized to ${this.serialized}`,
+      );
+    }
+  }
+
+  toJSON(): string {
+    return this.toString();
+  }
+
+  toString(): string {
+    return this.serialized;
+  }
+}

package/src/types/streams.ts

@@ -0,0 +1,17 @@
+export function isReadableStream<T = Uint8Array>(
+  val: unknown,
+): val is ReadableStream<T> {
+  if (typeof val !== "object" || val === null) {
+    return false;
+  }
+
+  // Check for the presence of methods specific to ReadableStream
+  const stream = val as ReadableStream<Uint8Array>;
+
+  // ReadableStream has methods like getReader, cancel, and tee
+  return (
+    typeof stream.getReader === "function" &&
+    typeof stream.cancel === "function" &&
+    typeof stream.tee === "function"
+  );
+}

package/tests/integration/dimensions.integration.test.ts

@@ -0,0 +1,87 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Fastpix } from "../../src/sdk/sdk.js";
+
+const USERNAME = process.env["FASTPIX_USERNAME"];
+const PASSWORD = process.env["FASTPIX_PASSWORD"];
+
+function haveCreds() {
+  return Boolean(USERNAME && PASSWORD);
+}
+
+const TEST_TIMEOUT_MS = 120_000;
+
+test("Dimensions.listDimensions (integration)", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) {
+    console.warn("Skipping integration test: FASTPIX_USERNAME/PASSWORD not set");
+    return;
+  }
+
+  const sdk = new Fastpix({
+    security: { username: USERNAME!, password: PASSWORD! },
+    timeoutMs: TEST_TIMEOUT_MS,
+  });
+
+  try {
+    const res = await sdk.dimensions.listDimensions({ timeoutMs: TEST_TIMEOUT_MS });
+
+    const data = (res as any).data ?? (res as any);
+    assert.ok(Array.isArray(data), "expected array of dimensions");
+    console.log("Retrieved", data.length, "dimensions");
+  } catch (error) {
+    console.error("Error listing dimensions:", error);
+    throw error;
+  }
+});
+
+test("Dimensions.listFilterValuesForDimension (integration)", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) {
+    console.warn("Skipping integration test: FASTPIX_USERNAME/PASSWORD not set");
+    return;
+  }
+
+  const sdk = new Fastpix({
+    security: { username: USERNAME!, password: PASSWORD! },
+    timeoutMs: TEST_TIMEOUT_MS,
+  });
+
+  try {
+    const res = await sdk.dimensions.listFilterValuesForDimension({
+      dimensionsId: "browser_name",
+      timespan: "7:days",
+    }, { timeoutMs: TEST_TIMEOUT_MS });
+
+    const data = (res as any).data ?? (res as any);
+    assert.ok(Array.isArray(data), "expected array of filter values");
+    console.log("Retrieved", data.length, "filter values for browser_name dimension");
+  } catch (error) {
+    console.error("Error listing filter values for dimension:", error);
+    throw error;
+  }
+});
+
+test("Dimensions.listFilterValuesForDimension with device_type (integration)", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) {
+    console.warn("Skipping integration test: FASTPIX_USERNAME/PASSWORD not set");
+    return;
+  }
+
+  const sdk = new Fastpix({
+    security: { username: USERNAME!, password: PASSWORD! },
+    timeoutMs: TEST_TIMEOUT_MS,
+  });
+
+  try {
+    const res = await sdk.dimensions.listFilterValuesForDimension({
+      dimensionsId: "device_type",
+      timespan: "7:days",
+    }, { timeoutMs: TEST_TIMEOUT_MS });
+
+    const data = (res as any).data ?? (res as any);
+    assert.ok(Array.isArray(data), "expected array of filter values");
+    console.log("Retrieved", data.length, "filter values for device_type dimension");
+  } catch (error) {
+    console.error("Error listing filter values for device_type dimension:", error);
+    throw error;
+  }
+});

package/tests/integration/errors.integration.test.ts

@@ -0,0 +1,80 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Fastpix } from "../../src/sdk/sdk.js";
+
+const USERNAME = process.env["FASTPIX_USERNAME"];
+const PASSWORD = process.env["FASTPIX_PASSWORD"];
+const TEST_TIMEOUT_MS = 120_000;
+
+function haveCreds() {
+  return Boolean(USERNAME && PASSWORD);
+}
+
+// Test 1: Check main listErrors response structure
+test("Errors.listErrors returns structured response (integration)", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) return console.warn("Skipping integration test: FASTPIX_USERNAME/PASSWORD not set");
+
+  const sdk = new Fastpix({ security: { username: USERNAME!, password: PASSWORD! }, timeoutMs: TEST_TIMEOUT_MS });
+  const res = await sdk.errors.listErrors({ timespan: "7:days" }, { timeoutMs: TEST_TIMEOUT_MS });
+  const data = (res as any).data ?? (res as any);
+
+  assert.ok(Array.isArray(data.errors), "expected 'errors' to be an array");
+  assert.ok(Array.isArray(data.topErrors), "expected 'topErrors' to be an array");
+  assert.ok(Array.isArray(data.timespan) && data.timespan.length === 2, "expected timespan array of length 2");
+});
+
+// Test 2: Validate each error object fields
+test("Errors.listErrors errors objects have required fields", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) return;
+
+  const sdk = new Fastpix({ security: { username: USERNAME!, password: PASSWORD! }, timeoutMs: TEST_TIMEOUT_MS });
+  const res = await sdk.errors.listErrors({ timespan: "7:days" }, { timeoutMs: TEST_TIMEOUT_MS });
+  const errors = (res as any).data.errors;
+
+  errors.forEach((err: any, index: number) => {
+    assert.ok(err.id, `error[${index}].id should exist`);
+    assert.ok(err.message, `error[${index}].message should exist`);
+    assert.ok(err.code, `error[${index}].code should exist`);
+    assert.strictEqual(typeof err.count, "number", `error[${index}].count should be a number`);
+    assert.strictEqual(typeof err.percentage, "number", `error[${index}].percentage should be a number`);
+    assert.ok(err.description, `error[${index}].description should exist`);
+    assert.ok(err.lastSeen && !isNaN(Date.parse(err.lastSeen)), `error[${index}].lastSeen should be valid date`);
+  });
+});
+
+// Test 3: Validate topErrors objects
+test("Errors.listErrors topErrors objects have required fields", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) return;
+
+  const sdk = new Fastpix({ security: { username: USERNAME!, password: PASSWORD! }, timeoutMs: TEST_TIMEOUT_MS });
+  const res = await sdk.errors.listErrors({ timespan: "7:days" }, { timeoutMs: TEST_TIMEOUT_MS });
+  const topErrors = (res as any).data.topErrors;
+
+  topErrors.forEach((top: any, index: number) => {
+    assert.ok(top.code, `topErrors[${index}].code should exist`);
+    assert.strictEqual(typeof top.count, "number", `topErrors[${index}].count should be a number`);
+    assert.strictEqual(typeof top.uniqueViewersEffectedPercentage, "number", `topErrors[${index}].uniqueViewersEffectedPercentage should be a number`);
+    assert.ok(top.message, `topErrors[${index}].message should exist`);
+    assert.ok(top.lastSeen && !isNaN(Date.parse(top.lastSeen)), `topErrors[${index}].lastSeen should be valid date`);
+  });
+});
+
+// Test 4: Filter by browser_name
+test("Errors.listErrors supports browser filter", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) return;
+
+  const sdk = new Fastpix({ security: { username: USERNAME!, password: PASSWORD! }, timeoutMs: TEST_TIMEOUT_MS });
+  const res = await sdk.errors.listErrors({ timespan: "7:days", filterby: "browser_name:Chrome" }, { timeoutMs: TEST_TIMEOUT_MS });
+  const errors = (res as any).data.errors;
+  assert.ok(errors.length >= 0, "expected 0 or more errors for Chrome browser");
+});
+
+// Test 5: Filter by device_type
+test("Errors.listErrors supports device filter", { timeout: TEST_TIMEOUT_MS }, async () => {
+  if (!haveCreds()) return;
+
+  const sdk = new Fastpix({ security: { username: USERNAME!, password: PASSWORD! }, timeoutMs: TEST_TIMEOUT_MS });
+  const res = await sdk.errors.listErrors({ timespan: "7:days", filterby: "device_type:Mobile" }, { timeoutMs: TEST_TIMEOUT_MS });
+  const errors = (res as any).data.errors;
+  assert.ok(errors.length >= 0, "expected 0 or more errors for Mobile devices");
+});