perspectapi-ts-sdk 6.1.2 → 6.3.0

package/dist/index.mjs

@@ -8,6 +8,20 @@ function warnV1Deprecated() {
   console.warn(`[perspectapi-ts-sdk] ${V1_DEPRECATION_NOTICE}`);
 }
 
+// src/types/index.ts
+var PerspectApiError = class extends Error {
+  code;
+  status;
+  details;
+  constructor({ message, code, status, details }) {
+    super(message);
+    this.name = "PerspectApiError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+
 // src/utils/http-client.ts
 var HttpClient = class {
   baseUrl;
@@ -211,12 +225,12 @@ var HttpClient = class {
     }
     if (!response.ok) {
       console.error(`[HTTP Client - Response] Error response received`);
-      const error = {
+      const error = new PerspectApiError({
         message: data?.error || data?.message || `HTTP ${response.status}: ${response.statusText}`,
         status: response.status,
         code: data?.code,
         details: data
-      };
+      });
       console.error(`[HTTP Client - Response] Throwing error:`, error);
       throw error;
     }
@@ -825,13 +839,29 @@ var CollectionsV2Client = class extends BaseV2Client {
     return this.getOne(this.sitePath(siteName, "collections", id));
   }
   async create(siteName, data) {
-    return this.post(this.sitePath(siteName, "collections"), data);
+    const result = await this.post(this.sitePath(siteName, "collections"), data);
+    await this.invalidateCache({ keys: [this.sitePath(siteName, "collections")] });
+    return result;
   }
   async update(siteName, id, data) {
-    return this.patchOne(this.sitePath(siteName, "collections", id), data);
+    const result = await this.patchOne(this.sitePath(siteName, "collections", id), data);
+    await this.invalidateCache({
+      keys: [
+        this.sitePath(siteName, "collections"),
+        this.sitePath(siteName, "collections", id)
+      ]
+    });
+    return result;
   }
   async del(siteName, id) {
-    return this.deleteOne(this.sitePath(siteName, "collections", id));
+    const result = await this.deleteOne(this.sitePath(siteName, "collections", id));
+    await this.invalidateCache({
+      keys: [
+        this.sitePath(siteName, "collections"),
+        this.sitePath(siteName, "collections", id)
+      ]
+    });
+    return result;
   }
   // --- Items ---
   async listItems(siteName, collectionId) {
@@ -840,15 +870,23 @@ var CollectionsV2Client = class extends BaseV2Client {
     );
   }
   async addItem(siteName, collectionId, data) {
-    return this.post(
+    const result = await this.post(
       this.sitePath(siteName, "collections", `${collectionId}/items`),
       data
     );
+    await this.invalidateCache({
+      keys: [this.sitePath(siteName, "collections", `${collectionId}/items`)]
+    });
+    return result;
   }
   async removeItem(siteName, collectionId, itemId) {
-    return this.deleteOne(
+    const result = await this.deleteOne(
       this.sitePath(siteName, "collections", `${collectionId}/items/${itemId}`)
     );
+    await this.invalidateCache({
+      keys: [this.sitePath(siteName, "collections", `${collectionId}/items`)]
+    });
+    return result;
   }
 };
 
@@ -4068,6 +4106,180 @@ var CloudflareKVCacheAdapter = class {
   }
 };
 
+// src/cache/in-memory-adapter.ts
+var InMemoryCacheAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  async get(key) {
+    const entry = this.store.get(key);
+    if (!entry) {
+      return void 0;
+    }
+    if (entry.expiresAt && entry.expiresAt <= Date.now()) {
+      this.store.delete(key);
+      return void 0;
+    }
+    return entry.value;
+  }
+  async set(key, value, options) {
+    const expiresAt = options?.ttlSeconds && options.ttlSeconds > 0 ? Date.now() + options.ttlSeconds * 1e3 : void 0;
+    this.store.set(key, { value, expiresAt });
+  }
+  async delete(key) {
+    this.store.delete(key);
+  }
+  async deleteMany(keys) {
+    keys.forEach((key) => this.store.delete(key));
+  }
+  async clear() {
+    this.store.clear();
+  }
+};
+
+// src/ab/bucketing.ts
+var BUCKET_SPACE = 1e4;
+function bucketFor(visitorId, flagKey, version) {
+  const input = `${visitorId}|${flagKey}|${version}`;
+  const bytes = new TextEncoder().encode(input);
+  let hash = 2166136261;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) % BUCKET_SPACE;
+}
+function variantForBucket(bucket, variants, trafficAllocationBp) {
+  if (bucket >= trafficAllocationBp) return null;
+  const sorted = [...variants].sort((a, b) => a.key < b.key ? -1 : 1);
+  const totalWeight = sorted.reduce((acc, v) => acc + v.weightBp, 0);
+  if (totalWeight <= 0) return null;
+  const scaled = Math.floor(bucket * totalWeight / trafficAllocationBp);
+  let cursor = 0;
+  for (const v of sorted) {
+    cursor += v.weightBp;
+    if (scaled < cursor) return v.key;
+  }
+  return sorted[sorted.length - 1].key;
+}
+
+// src/ab/ab-client.ts
+var CONFIG_TTL_SECONDS = 3600;
+var VID_COOKIE = "perspect_vid";
+var VID_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2;
+var BASE_URL_DEFAULT = "https://api.perspect.com";
+function createPerspectAb(options) {
+  const { apiKey, siteName, ctx } = options;
+  const baseUrl = (options.baseUrl ?? BASE_URL_DEFAULT).replace(/\/$/, "");
+  return {
+    async forRequest(request) {
+      const { visitorId, mintedNew } = readOrMintVid(request);
+      const responseHeaders = new Headers();
+      if (mintedNew) {
+        responseHeaders.append(
+          "Set-Cookie",
+          `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`
+        );
+      }
+      const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+    },
+    async refreshConfig() {
+      await fetchAndStoreConfig(options.cache, apiKey, siteName, baseUrl);
+    }
+  };
+}
+function buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId) {
+  return {
+    async getVariant(flagKey) {
+      const flag = config.flags[flagKey];
+      if (!flag || flag.status !== "running") {
+        return { variant: flag?.defaultVariant ?? null, enrolled: false, config: null };
+      }
+      const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+      const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+      if (assigned === null) {
+        return { variant: flag.defaultVariant, enrolled: false, config: null };
+      }
+      const variantCfg = flag.variants.find((v) => v.key === assigned)?.config ?? null;
+      emit(apiKey, baseUrl, ctx, {
+        site: siteName,
+        kind: "exposure",
+        flag: flagKey,
+        version: flag.currentVersion,
+        variant: assigned,
+        visitorId,
+        dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, "exposure"),
+        ts: Math.floor(Date.now() / 1e3)
+      });
+      return { variant: assigned, enrolled: true, config: variantCfg };
+    },
+    async track(event, properties) {
+      for (const [flagKey, flag] of Object.entries(config.flags)) {
+        if (flag.status !== "running") continue;
+        const goals = flag.goalsByVersion[String(flag.currentVersion)] ?? [];
+        if (!goals.includes(event)) continue;
+        const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+        const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+        if (assigned === null) continue;
+        emit(apiKey, baseUrl, ctx, {
+          site: siteName,
+          kind: "conversion",
+          flag: flagKey,
+          version: flag.currentVersion,
+          variant: assigned,
+          visitorId,
+          event,
+          dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
+          ts: Math.floor(Date.now() / 1e3),
+          properties
+        });
+      }
+    }
+  };
+}
+function configCacheKey(siteName) {
+  return `ab:config:${siteName}`;
+}
+async function getConfig(cache, apiKey, siteName, baseUrl) {
+  if (cache) {
+    const raw = await cache.get(configCacheKey(siteName));
+    if (raw) return JSON.parse(raw);
+  }
+  return fetchAndStoreConfig(cache, apiKey, siteName, baseUrl);
+}
+async function fetchAndStoreConfig(cache, apiKey, siteName, baseUrl) {
+  const res = await fetch(`${baseUrl}/_ab/config?site=${encodeURIComponent(siteName)}`, {
+    headers: { "x-api-key": apiKey }
+  });
+  if (!res.ok) return { schemaVersion: 1, flags: {} };
+  const config = await res.json();
+  if (cache) {
+    await cache.set(configCacheKey(siteName), JSON.stringify(config), { ttlSeconds: CONFIG_TTL_SECONDS });
+  }
+  return config;
+}
+function emit(apiKey, baseUrl, ctx, body) {
+  const task = fetch(`${baseUrl}/_ab/event`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-api-key": apiKey },
+    body: JSON.stringify(body)
+  }).then(() => void 0).catch(() => void 0);
+  if (ctx) ctx.waitUntil(task);
+}
+function readOrMintVid(request) {
+  const cookie = request.headers.get("cookie") ?? "";
+  const match = cookie.match(/(?:^|; )perspect_vid=([^;]+)/);
+  if (match) return { visitorId: decodeURIComponent(match[1]), mintedNew: false };
+  return { visitorId: crypto.randomUUID().replace(/-/g, ""), mintedNew: true };
+}
+async function dedupFor(visitorId, flagKey, version, variant, event) {
+  const input = `${visitorId}|${flagKey}|${version}|${variant}|${event}`;
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  const bytes = new Uint8Array(digest);
+  let hex = "";
+  for (let i = 0; i < 16; i++) hex += bytes[i].toString(16).padStart(2, "0");
+  return hex;
+}
+
 // src/utils/image-transform.ts
 var DEFAULT_IMAGE_SIZES = {
   thumbnail: {
@@ -4738,11 +4950,13 @@ export {
   ContentClient,
   DEFAULT_IMAGE_SIZES,
   HttpClient,
+  InMemoryCacheAdapter,
   NewsletterClient,
   NewsletterManagementClient,
   NoopCacheAdapter,
   OrganizationsClient,
   PerspectApiClient,
+  PerspectApiError,
   PerspectApiV2Client,
   PerspectV2Error,
   ProductsClient,
@@ -4751,9 +4965,11 @@ export {
   V1_DEPRECATION_NOTICE,
   V1_SUNSET_DATE,
   WebhooksClient,
+  bucketFor,
   buildImageUrl,
   createApiError,
   createCheckoutSession,
+  createPerspectAb,
   createPerspectApiClient,
   createPerspectApiV2Client,
   perspect_api_client_default as default,
@@ -4771,5 +4987,6 @@ export {
   loadProducts,
   transformContent,
   transformMediaItem,
-  transformProduct
+  transformProduct,
+  variantForBucket
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "6.1.2",
+  "version": "6.3.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/ab/ab-client.ts

@@ -0,0 +1,262 @@
+import { bucketFor, variantForBucket } from './bucketing';
+import type { CacheAdapter } from '../cache/types';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface CreatePerspectAbOptions {
+  apiKey: string;
+  siteName: string;
+  baseUrl?: string;
+  /** Pluggable cache adapter — CloudflareKVCacheAdapter, InMemoryCacheAdapter, or NoopCacheAdapter. */
+  cache?: CacheAdapter;
+  /** ExecutionContext (CF Workers) or any object with waitUntil — enables background tasks. */
+  ctx?: { waitUntil(p: Promise<unknown>): void };
+}
+
+export interface AbForRequestResult {
+  ab: AbClient;
+  /** Merge into the outgoing response — may carry a freshly minted perspect_vid cookie. */
+  responseHeaders: Headers;
+}
+
+export interface AbVariantResult {
+  variant: string | null;
+  enrolled: boolean;
+  config: Record<string, unknown> | null;
+}
+
+export interface AbClient {
+  getVariant(flagKey: string): Promise<AbVariantResult>;
+  track(event: string, properties?: Record<string, unknown>): Promise<void>;
+}
+
+export interface PerspectAb {
+  forRequest(request: Request): Promise<AbForRequestResult>;
+  refreshConfig(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal config types
+// ---------------------------------------------------------------------------
+
+interface AbVariantCfg {
+  key: string;
+  weightBp: number;
+  config: Record<string, unknown> | null;
+}
+
+interface AbFlagCfg {
+  currentVersion: number;
+  status: 'draft' | 'running' | 'paused' | 'stopped';
+  variants: AbVariantCfg[];
+  trafficAllocationBp: number;
+  defaultVariant: string;
+  goalsByVersion: Record<string, string[]>;
+}
+
+interface AbConfigBlob {
+  schemaVersion: 1;
+  flags: Record<string, AbFlagCfg>;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CONFIG_TTL_SECONDS = 3_600;
+const VID_COOKIE = 'perspect_vid';
+const VID_COOKIE_MAX_AGE = 60 * 60 * 24 * 365 * 2;
+const BASE_URL_DEFAULT = 'https://api.perspect.com';
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export function createPerspectAb(options: CreatePerspectAbOptions): PerspectAb {
+  const { apiKey, siteName, ctx } = options;
+  const baseUrl = (options.baseUrl ?? BASE_URL_DEFAULT).replace(/\/$/, '');
+
+  return {
+    async forRequest(request: Request): Promise<AbForRequestResult> {
+      const { visitorId, mintedNew } = readOrMintVid(request);
+      const responseHeaders = new Headers();
+      if (mintedNew) {
+        responseHeaders.append(
+          'Set-Cookie',
+          `${VID_COOKIE}=${visitorId}; Path=/; Max-Age=${VID_COOKIE_MAX_AGE}; SameSite=Lax; Secure; HttpOnly`,
+        );
+      }
+      const config = await getConfig(options.cache, apiKey, siteName, baseUrl);
+      return { ab: buildAbClient(apiKey, siteName, baseUrl, ctx, config, visitorId), responseHeaders };
+    },
+
+    async refreshConfig(): Promise<void> {
+      await fetchAndStoreConfig(options.cache, apiKey, siteName, baseUrl);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// AB client
+// ---------------------------------------------------------------------------
+
+function buildAbClient(
+  apiKey: string,
+  siteName: string,
+  baseUrl: string,
+  ctx: { waitUntil(p: Promise<unknown>): void } | undefined,
+  config: AbConfigBlob,
+  visitorId: string,
+): AbClient {
+  return {
+    async getVariant(flagKey: string): Promise<AbVariantResult> {
+      const flag = config.flags[flagKey];
+      if (!flag || flag.status !== 'running') {
+        return { variant: flag?.defaultVariant ?? null, enrolled: false, config: null };
+      }
+      const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+      const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+      if (assigned === null) {
+        return { variant: flag.defaultVariant, enrolled: false, config: null };
+      }
+      const variantCfg = flag.variants.find((v) => v.key === assigned)?.config ?? null;
+      emit(apiKey, baseUrl, ctx, {
+        site: siteName,
+        kind: 'exposure',
+        flag: flagKey,
+        version: flag.currentVersion,
+        variant: assigned,
+        visitorId,
+        dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, 'exposure'),
+        ts: Math.floor(Date.now() / 1000),
+      });
+      return { variant: assigned, enrolled: true, config: variantCfg };
+    },
+
+    async track(event: string, properties?: Record<string, unknown>): Promise<void> {
+      for (const [flagKey, flag] of Object.entries(config.flags)) {
+        if (flag.status !== 'running') continue;
+        const goals = flag.goalsByVersion[String(flag.currentVersion)] ?? [];
+        if (!goals.includes(event)) continue;
+        const bucket = bucketFor(visitorId, flagKey, flag.currentVersion);
+        const assigned = variantForBucket(bucket, flag.variants, flag.trafficAllocationBp);
+        if (assigned === null) continue;
+        emit(apiKey, baseUrl, ctx, {
+          site: siteName,
+          kind: 'conversion',
+          flag: flagKey,
+          version: flag.currentVersion,
+          variant: assigned,
+          visitorId,
+          event,
+          dedup: await dedupFor(visitorId, flagKey, flag.currentVersion, assigned, event),
+          ts: Math.floor(Date.now() / 1000),
+          properties,
+        });
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Config cache (SWR via CacheAdapter)
+// ---------------------------------------------------------------------------
+
+function configCacheKey(siteName: string): string {
+  return `ab:config:${siteName}`;
+}
+
+async function getConfig(
+  cache: CacheAdapter | undefined,
+  apiKey: string,
+  siteName: string,
+  baseUrl: string,
+): Promise<AbConfigBlob> {
+  if (cache) {
+    const raw = await cache.get(configCacheKey(siteName));
+    if (raw) return JSON.parse(raw) as AbConfigBlob;
+  }
+  return fetchAndStoreConfig(cache, apiKey, siteName, baseUrl);
+}
+
+async function fetchAndStoreConfig(
+  cache: CacheAdapter | undefined,
+  apiKey: string,
+  siteName: string,
+  baseUrl: string,
+): Promise<AbConfigBlob> {
+  const res = await fetch(`${baseUrl}/_ab/config?site=${encodeURIComponent(siteName)}`, {
+    headers: { 'x-api-key': apiKey },
+  });
+  if (!res.ok) return { schemaVersion: 1, flags: {} };
+  const config = (await res.json()) as AbConfigBlob;
+  if (cache) {
+    await cache.set(configCacheKey(siteName), JSON.stringify(config), { ttlSeconds: CONFIG_TTL_SECONDS });
+  }
+  return config;
+}
+
+// ---------------------------------------------------------------------------
+// Event emission
+// ---------------------------------------------------------------------------
+
+interface EventBody {
+  site: string;
+  kind: 'exposure' | 'conversion' | 'handoff';
+  flag: string;
+  version: number;
+  variant: string;
+  visitorId: string;
+  dedup: string;
+  ts: number;
+  event?: string;
+  properties?: Record<string, unknown>;
+}
+
+function emit(
+  apiKey: string,
+  baseUrl: string,
+  ctx: { waitUntil(p: Promise<unknown>): void } | undefined,
+  body: EventBody,
+): void {
+  const task = fetch(`${baseUrl}/_ab/event`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'x-api-key': apiKey },
+    body: JSON.stringify(body),
+  })
+    .then(() => undefined)
+    .catch(() => undefined);
+  if (ctx) ctx.waitUntil(task);
+}
+
+// ---------------------------------------------------------------------------
+// Visitor ID
+// ---------------------------------------------------------------------------
+
+function readOrMintVid(request: Request): { visitorId: string; mintedNew: boolean } {
+  const cookie = request.headers.get('cookie') ?? '';
+  const match = cookie.match(/(?:^|; )perspect_vid=([^;]+)/);
+  if (match) return { visitorId: decodeURIComponent(match[1]), mintedNew: false };
+  return { visitorId: crypto.randomUUID().replace(/-/g, ''), mintedNew: true };
+}
+
+// ---------------------------------------------------------------------------
+// Dedup hash
+// ---------------------------------------------------------------------------
+
+async function dedupFor(
+  visitorId: string,
+  flagKey: string,
+  version: number,
+  variant: string,
+  event: string,
+): Promise<string> {
+  const input = `${visitorId}|${flagKey}|${version}|${variant}|${event}`;
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+  const bytes = new Uint8Array(digest);
+  let hex = '';
+  for (let i = 0; i < 16; i++) hex += bytes[i].toString(16).padStart(2, '0');
+  return hex;
+}

package/src/ab/bucketing.ts

@@ -0,0 +1,56 @@
+/**
+ * Deterministic bucketing for A/B assignments.
+ *
+ * Both the site SDK (local assignment) and the platform event endpoint
+ * (server-side validation) compute the same hash → variant mapping.
+ * Any change here must ship to both simultaneously, or assignments and
+ * validation will diverge.
+ */
+
+const BUCKET_SPACE = 10000;
+
+/**
+ * FNV-1a 32-bit over UTF-8 bytes, reduced mod 10000.
+ * Pure function, no crypto — determinism and portability beat pre-image
+ * resistance here. The attack surface on the mapping is the same for
+ * both sides; what matters is that site and platform agree bit-for-bit.
+ */
+export function bucketFor(
+  visitorId: string,
+  flagKey: string,
+  version: number,
+): number {
+  const input = `${visitorId}|${flagKey}|${version}`;
+  const bytes = new TextEncoder().encode(input);
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i];
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0) % BUCKET_SPACE;
+}
+
+/**
+ * Resolve a bucket to a variant using cumulative weightBp ranges.
+ * Variants are consumed in the order given — callers must sort variants
+ * consistently on both sides (we sort by key).
+ *
+ * Returns null iff bucket >= trafficAllocationBp (visitor not enrolled).
+ */
+export function variantForBucket(
+  bucket: number,
+  variants: { key: string; weightBp: number }[],
+  trafficAllocationBp: number,
+): string | null {
+  if (bucket >= trafficAllocationBp) return null;
+  const sorted = [...variants].sort((a, b) => (a.key < b.key ? -1 : 1));
+  const totalWeight = sorted.reduce((acc, v) => acc + v.weightBp, 0);
+  if (totalWeight <= 0) return null;
+  const scaled = Math.floor((bucket * totalWeight) / trafficAllocationBp);
+  let cursor = 0;
+  for (const v of sorted) {
+    cursor += v.weightBp;
+    if (scaled < cursor) return v.key;
+  }
+  return sorted[sorted.length - 1].key;
+}

package/src/index.ts

@@ -58,12 +58,25 @@ export { BaseClient } from './client/base-client';
 
 // Utilities
 export { HttpClient, createApiError } from './utils/http-client';
+export { PerspectApiError } from './types';
 
 // Cache utilities
 export { CacheManager } from './cache/cache-manager';
 export { CloudflareKVCacheAdapter } from './cache/cloudflare-kv-adapter';
-// InMemoryCacheAdapter removed — useless in Cloudflare Workers (per-request memory, no persistence)
+export { InMemoryCacheAdapter } from './cache/in-memory-adapter';
 export { NoopCacheAdapter } from './cache/noop-adapter';
+export type { CacheAdapter, CacheConfig } from './cache/types';
+
+// A/B testing
+export { createPerspectAb } from './ab/ab-client';
+export { bucketFor, variantForBucket } from './ab/bucketing';
+export type {
+  CreatePerspectAbOptions,
+  PerspectAb,
+  AbClient,
+  AbVariantResult,
+  AbForRequestResult,
+} from './ab/ab-client';
 
 // Image transformation utilities
 export {

package/src/types/index.ts

@@ -1138,6 +1138,20 @@ export interface ApiError {
   details?: any;
 }
 
+export class PerspectApiError extends Error implements ApiError {
+  code?: string;
+  status?: number;
+  details?: any;
+
+  constructor({ message, code, status, details }: ApiError) {
+    super(message);
+    this.name = 'PerspectApiError';
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+}
+
 // SDK Configuration
 export interface PerspectApiConfig {
   baseUrl: string;