perspectapi-ts-sdk 6.5.9 → 7.0.0

package/dist/v2/index.js

@@ -0,0 +1,1419 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/v2/index.ts
+var v2_exports = {};
+__export(v2_exports, {
+  ApiKeysV2Client: () => ApiKeysV2Client,
+  BaseV2Client: () => BaseV2Client,
+  CategoriesV2Client: () => CategoriesV2Client,
+  CollectionsV2Client: () => CollectionsV2Client,
+  ContactsV2Client: () => ContactsV2Client,
+  ContentV2Client: () => ContentV2Client,
+  CreditsV2Client: () => CreditsV2Client,
+  NewsletterV2Client: () => NewsletterV2Client,
+  OrdersV2Client: () => OrdersV2Client,
+  OrganizationsV2Client: () => OrganizationsV2Client,
+  PerspectApiV2Client: () => PerspectApiV2Client,
+  PerspectV2Error: () => PerspectV2Error,
+  ProductsV2Client: () => ProductsV2Client,
+  SiteUsersV2Client: () => SiteUsersV2Client,
+  SitesV2Client: () => SitesV2Client,
+  SubscriptionsV2Client: () => SubscriptionsV2Client,
+  WebhooksV2Client: () => WebhooksV2Client,
+  createPerspectApiV2Client: () => createPerspectApiV2Client
+});
+module.exports = __toCommonJS(v2_exports);
+
+// 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;
+  defaultHeaders;
+  timeout;
+  retries;
+  constructor(config) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.timeout = config.timeout || 3e4;
+    this.retries = config.retries || 3;
+    this.defaultHeaders = {
+      "Content-Type": "application/json",
+      "User-Agent": "perspectapi-ts-sdk/1.0.0",
+      ...config.headers
+    };
+    if (config.apiKey) {
+      this.defaultHeaders["X-API-Key"] = config.apiKey;
+    }
+    if (config.jwt) {
+      this.defaultHeaders["Authorization"] = `Bearer ${config.jwt}`;
+    }
+  }
+  /**
+   * Update authentication token
+   */
+  setAuth(jwt) {
+    this.defaultHeaders["Authorization"] = `Bearer ${jwt}`;
+  }
+  /**
+   * Update API key
+   */
+  setApiKey(apiKey) {
+    this.defaultHeaders["X-API-Key"] = apiKey;
+  }
+  /**
+   * Whether this client currently has a site-user/admin bearer token attached.
+   * Bearer-scoped GETs must not share cache entries across callers.
+   */
+  hasBearerAuth() {
+    return Boolean(this.defaultHeaders["Authorization"]);
+  }
+  /**
+   * Remove authentication
+   */
+  clearAuth() {
+    delete this.defaultHeaders["Authorization"];
+    delete this.defaultHeaders["X-API-Key"];
+  }
+  /**
+   * Make HTTP request with retry logic
+   */
+  async request(endpoint, options = {}) {
+    const url = this.buildUrl(endpoint, options.params);
+    const requestOptions = this.buildRequestOptions(options);
+    console.log(`[HTTP Client] ====== Request Details ======`);
+    console.log(`[HTTP Client] Method: ${options.method || "GET"}`);
+    console.log(`[HTTP Client] Base URL: ${this.baseUrl}`);
+    console.log(`[HTTP Client] Endpoint: ${endpoint}`);
+    console.log(`[HTTP Client] Full URL: ${url}`);
+    if (options.params) {
+      console.log(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
+      if (options.params.slug_prefix) {
+        console.log(`[HTTP Client] \u26A0\uFE0F slug_prefix detected: "${options.params.slug_prefix}"`);
+      }
+    }
+    const safeHeaders = { ...requestOptions.headers };
+    if (safeHeaders["Authorization"]) {
+      safeHeaders["Authorization"] = "Bearer [REDACTED]";
+    }
+    if (safeHeaders["X-API-Key"]) {
+      safeHeaders["X-API-Key"] = "[REDACTED]";
+    }
+    console.log(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
+    let lastError;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const response = await this.fetchWithTimeout(url, requestOptions);
+        return await this.handleResponse(response);
+      } catch (error) {
+        lastError = error;
+        if (error && typeof error === "object" && "status" in error && typeof error.status === "number" && error.status < 500) {
+          throw error;
+        }
+        if (attempt === this.retries) {
+          break;
+        }
+        await this.delay(Math.pow(2, attempt) * 1e3);
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * GET request
+   */
+  async get(endpoint, params) {
+    return this.request(endpoint, { method: "GET", params });
+  }
+  /**
+   * POST request
+   */
+  async post(endpoint, body, options) {
+    return this.request(endpoint, { method: "POST", body, ...options });
+  }
+  /**
+   * PUT request
+   */
+  async put(endpoint, body, options) {
+    return this.request(endpoint, { method: "PUT", body, ...options });
+  }
+  /**
+   * DELETE request
+   */
+  async delete(endpoint, options) {
+    return this.request(endpoint, { method: "DELETE", ...options });
+  }
+  /**
+   * PATCH request
+   */
+  async patch(endpoint, body, options) {
+    return this.request(endpoint, { method: "PATCH", body, ...options });
+  }
+  /**
+   * Build full URL with query parameters
+   */
+  buildUrl(endpoint, params) {
+    const url = `${this.baseUrl}${endpoint.startsWith("/") ? "" : "/"}${endpoint}`;
+    console.log(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
+    console.log(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
+    console.log(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
+    if (!params || Object.keys(params).length === 0) {
+      console.log(`[HTTP Client - URL Builder] No params, returning: ${url}`);
+      return url;
+    }
+    console.log(`[HTTP Client - URL Builder] Processing params:`, params);
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== void 0 && value !== null) {
+        console.log(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
+        searchParams.append(key, String(value));
+      } else {
+        console.log(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
+      }
+    });
+    const finalUrl = `${url}?${searchParams.toString()}`;
+    console.log(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
+    return finalUrl;
+  }
+  /**
+   * Build request options
+   */
+  buildRequestOptions(options) {
+    const headers = {
+      ...this.defaultHeaders,
+      ...options.headers
+    };
+    if (options.csrfToken) {
+      headers["X-CSRF-Token"] = options.csrfToken;
+    }
+    const requestOptions = {
+      method: options.method || "GET",
+      headers
+    };
+    if (options.body && options.method !== "GET") {
+      if (typeof options.body === "string") {
+        requestOptions.body = options.body;
+      } else {
+        requestOptions.body = JSON.stringify(options.body);
+      }
+    }
+    return requestOptions;
+  }
+  /**
+   * Fetch with timeout support
+   */
+  async fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+      return response;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Handle response and errors
+   */
+  async handleResponse(response) {
+    const contentType = response.headers.get("content-type");
+    const isJson = contentType?.includes("application/json");
+    console.log(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
+    console.log(`[HTTP Client - Response] Content-Type: ${contentType}`);
+    let data;
+    try {
+      data = isJson ? await response.json() : await response.text();
+    } catch (error) {
+      console.error(`[HTTP Client - Response] Failed to parse response:`, error);
+      data = null;
+    }
+    const dataStr = JSON.stringify(data);
+    if (dataStr && dataStr.length > 1e3) {
+      console.log(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1e3) + "...");
+    } else {
+      console.log(`[HTTP Client - Response] Data:`, data);
+    }
+    if (!response.ok) {
+      console.error(`[HTTP Client - Response] Error response received`);
+      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;
+    }
+    if (isJson && typeof data === "object") {
+      if ("data" in data || "message" in data || "error" in data) {
+        const apiResponse = data;
+        console.log(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : "N/A"}`);
+        return apiResponse;
+      }
+      console.log(`[HTTP Client - Response] Wrapping response in data property`);
+      return { data, success: true };
+    }
+    console.log(`[HTTP Client - Response] Returning text response`);
+    return { data, success: true };
+  }
+  /**
+   * Delay utility for retries
+   */
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/cache/noop-adapter.ts
+var NoopCacheAdapter = class {
+  async get() {
+    return void 0;
+  }
+  async set() {
+  }
+  async delete() {
+  }
+  async deleteMany() {
+  }
+  async clear() {
+  }
+};
+
+// src/cache/cache-manager.ts
+var TAG_PREFIX = "__tag__";
+var CacheManager = class {
+  adapter;
+  defaultTtlSeconds;
+  keyPrefix;
+  enabled;
+  constructor(config) {
+    const defaultOptions = {
+      defaultTtlSeconds: 300,
+      keyPrefix: "perspectapi"
+    };
+    const mergedConfig = {
+      ...defaultOptions,
+      ...config
+    };
+    if (config && config.enabled !== false && config.adapter) {
+      this.enabled = true;
+      this.adapter = config.adapter;
+    } else {
+      this.enabled = false;
+      this.adapter = new NoopCacheAdapter();
+    }
+    this.defaultTtlSeconds = mergedConfig.defaultTtlSeconds ?? 300;
+    this.keyPrefix = mergedConfig.keyPrefix ?? "perspectapi";
+  }
+  isEnabled() {
+    return this.enabled;
+  }
+  getKeyPrefix() {
+    return this.keyPrefix;
+  }
+  buildKey(parts) {
+    const normalized = parts.flatMap((part) => this.normalizeKeyPart(part)).filter((part) => part !== void 0 && part !== null && part !== "");
+    return normalized.join(":");
+  }
+  async getOrSet(key, resolveValue, policy) {
+    if (!this.enabled || policy?.skipCache) {
+      console.log("[Cache] Cache disabled or skipped", { key, enabled: this.enabled, skipCache: policy?.skipCache });
+      return resolveValue();
+    }
+    const namespacedKey = this.namespacedKey(key);
+    const cachedRaw = await this.adapter.get(namespacedKey);
+    if (cachedRaw) {
+      const entry = this.deserialize(cachedRaw);
+      if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        console.log("[Cache] \u2713 HIT", { key, tags: entry.tags });
+        return entry.value;
+      }
+      console.log("[Cache] \u2717 EXPIRED", { key, expiresAt: new Date(entry.expiresAt) });
+      await this.adapter.delete(namespacedKey);
+      if (entry.tags?.length) {
+        await this.removeKeyFromTags(namespacedKey, entry.tags);
+      }
+    } else {
+      console.log("[Cache] \u2717 MISS", { key });
+    }
+    const value = await resolveValue();
+    await this.set(key, value, policy);
+    return value;
+  }
+  async set(key, value, options) {
+    if (!this.enabled) {
+      return;
+    }
+    const namespacedKey = this.namespacedKey(key);
+    const ttlSeconds = options?.ttlSeconds ?? this.defaultTtlSeconds;
+    const entry = {
+      value,
+      expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1e3 : void 0,
+      tags: options?.tags,
+      metadata: options?.metadata
+    };
+    console.log("[Cache] SET", { key, ttlSeconds, tags: options?.tags });
+    await this.adapter.set(namespacedKey, this.serialize(entry), {
+      ttlSeconds: ttlSeconds > 0 ? ttlSeconds : void 0
+    });
+    if (options?.tags?.length) {
+      await this.registerKeyTags(namespacedKey, options.tags);
+    }
+  }
+  async delete(key) {
+    if (!this.enabled) {
+      return;
+    }
+    const namespacedKey = this.namespacedKey(key);
+    await this.adapter.delete(namespacedKey);
+  }
+  async invalidate(options) {
+    if (!this.enabled) {
+      return;
+    }
+    let totalInvalidated = 0;
+    if (options.keys?.length) {
+      const namespacedKeys = options.keys.map((key) => this.namespacedKey(key));
+      console.log("[Cache] INVALIDATE by keys", { count: options.keys.length, keys: options.keys });
+      if (this.adapter.deleteMany) {
+        await this.adapter.deleteMany(namespacedKeys);
+      } else {
+        await Promise.all(namespacedKeys.map((key) => this.adapter.delete(key)));
+      }
+      totalInvalidated += options.keys.length;
+    }
+    if (options.tags?.length) {
+      console.log("[Cache] INVALIDATE by tags", { tags: options.tags });
+      await Promise.all(
+        options.tags.map(async (tag) => {
+          const tagKey = this.tagKey(tag);
+          const payload = await this.adapter.get(tagKey);
+          if (!payload) {
+            console.log("[Cache] No entries for tag", { tag });
+            return;
+          }
+          const keys = this.deserializeTagSet(payload);
+          if (keys.length) {
+            console.log("[Cache] Invalidating entries for tag", { tag, count: keys.length });
+            if (this.adapter.deleteMany) {
+              await this.adapter.deleteMany(keys);
+            } else {
+              await Promise.all(keys.map((key) => this.adapter.delete(key)));
+            }
+            totalInvalidated += keys.length;
+          }
+          await this.adapter.delete(tagKey);
+        })
+      );
+    }
+    console.log("[Cache] \u2713 INVALIDATED", { totalEntries: totalInvalidated, keys: options.keys?.length || 0, tags: options.tags?.length || 0 });
+  }
+  namespacedKey(key) {
+    return `${this.keyPrefix}:${key}`;
+  }
+  tagKey(tag) {
+    return this.namespacedKey(`${TAG_PREFIX}:${tag}`);
+  }
+  serialize(entry) {
+    return JSON.stringify(entry);
+  }
+  deserialize(payload) {
+    try {
+      return JSON.parse(payload);
+    } catch {
+      return { value: payload };
+    }
+  }
+  deserializeTagSet(payload) {
+    try {
+      const parsed = JSON.parse(payload);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      return [];
+    }
+  }
+  async registerKeyTags(namespacedKey, tags) {
+    await Promise.all(
+      tags.map(async (tag) => {
+        const tagKey = this.tagKey(tag);
+        const existingPayload = await this.adapter.get(tagKey);
+        const keys = existingPayload ? this.deserializeTagSet(existingPayload) : [];
+        if (!keys.includes(namespacedKey)) {
+          keys.push(namespacedKey);
+          await this.adapter.set(tagKey, JSON.stringify(keys));
+        }
+      })
+    );
+  }
+  async removeKeyFromTags(namespacedKey, tags) {
+    await Promise.all(
+      tags.map(async (tag) => {
+        const tagKey = this.tagKey(tag);
+        const existingPayload = await this.adapter.get(tagKey);
+        if (!existingPayload) {
+          return;
+        }
+        const keys = this.deserializeTagSet(existingPayload);
+        const updated = keys.filter((key) => key !== namespacedKey);
+        if (updated.length === 0) {
+          await this.adapter.delete(tagKey);
+        } else if (updated.length !== keys.length) {
+          await this.adapter.set(tagKey, JSON.stringify(updated));
+        }
+      })
+    );
+  }
+  normalizeKeyPart(part) {
+    if (part === void 0 || part === null || part === "") {
+      return [];
+    }
+    if (Array.isArray(part)) {
+      return part.flatMap((item) => this.normalizeKeyPart(item));
+    }
+    if (typeof part === "object") {
+      return [this.normalizeObject(part)];
+    }
+    return [String(part)];
+  }
+  normalizeObject(input) {
+    const sortedKeys = Object.keys(input).sort();
+    const normalized = {};
+    for (const key of sortedKeys) {
+      const value = input[key];
+      if (value === void 0) {
+        continue;
+      }
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        normalized[key] = JSON.parse(this.normalizeObject(value));
+      } else if (Array.isArray(value)) {
+        normalized[key] = value.map(
+          (item) => typeof item === "object" && item !== null ? JSON.parse(this.normalizeObject(item)) : item
+        );
+      } else {
+        normalized[key] = value;
+      }
+    }
+    return JSON.stringify(normalized);
+  }
+};
+
+// src/v2/client/base-v2-client.ts
+var PerspectV2Error = class extends Error {
+  type;
+  code;
+  param;
+  status;
+  constructor(error, status) {
+    super(error.message);
+    this.name = "PerspectV2Error";
+    this.type = error.type;
+    this.code = error.code;
+    this.param = error.param;
+    this.status = status;
+  }
+};
+var BaseV2Client = class {
+  http;
+  basePath;
+  cache;
+  constructor(http, basePath, cache) {
+    this.http = http;
+    this.basePath = basePath;
+    this.cache = cache && cache.isEnabled() ? cache : void 0;
+  }
+  buildPath(endpoint) {
+    const clean = endpoint.replace(/^\//, "");
+    return clean ? `${this.basePath}/${clean}` : this.basePath;
+  }
+  sitePath(siteName, resource, suffix = "") {
+    const encoded = encodeURIComponent(siteName.trim());
+    const cleanSuffix = suffix.replace(/^\//, "");
+    const end = cleanSuffix ? `/${cleanSuffix}` : "";
+    return `/sites/${encoded}/${resource}${end}`;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  toParams(params) {
+    if (!params) return void 0;
+    const out = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0 && v !== null) out[k] = String(v);
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  /**
+   * Extract v2 payload from HttpClient response.
+   *
+   * The shared HttpClient wraps responses in a v1-style { success, data } envelope.
+   * v2 API responses don't have a `success` field — the HttpClient already throws
+   * on HTTP errors, so if we reach this point the request succeeded.
+   *
+   * The HttpClient may return the v2 payload nested under `data` (when the response
+   * JSON contains a `data` key, which v2 list responses do) or as a direct wrap.
+   * We unwrap accordingly.
+   */
+  extractData(response) {
+    if ("object" in response && typeof response.object === "string") {
+      const payload2 = response;
+      if (payload2.error && typeof payload2.error === "object" && "type" in payload2.error) {
+        throw this.toError(response);
+      }
+      return response;
+    }
+    const payload = response.data;
+    if (payload && typeof payload === "object" && "error" in payload) {
+      const errObj = payload.error;
+      if (errObj && typeof errObj === "object" && "type" in errObj) {
+        throw this.toError(response);
+      }
+    }
+    return payload;
+  }
+  /** GET a single resource, with optional caching. */
+  async getOne(path, params, cachePolicy) {
+    const fetcher = async () => {
+      const response = await this.http.get(path, this.toParams(params));
+      return this.extractData(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
+  }
+  /** GET a list of resources with cursor pagination, with optional caching. */
+  async getList(path, params, cachePolicy) {
+    const fetcher = async () => {
+      const response = await this.http.get(path, this.toParams(params));
+      return this.extractData(response);
+    };
+    return this.fetchWithCache(path, params, cachePolicy, fetcher);
+  }
+  /** POST to create a resource. */
+  async post(path, body) {
+    const response = await this.http.post(path, body);
+    return this.extractData(response);
+  }
+  /** PATCH to update a resource. */
+  async patchOne(path, body) {
+    const response = await this.http.patch(path, body);
+    return this.extractData(response);
+  }
+  /** PUT to upsert a resource. */
+  async putOne(path, body) {
+    const response = await this.http.put(path, body);
+    return this.extractData(response);
+  }
+  /** DELETE a resource. */
+  async deleteOne(path) {
+    const response = await this.http.delete(path);
+    return this.extractData(response);
+  }
+  /** Fetch with optional cache. Bypasses cache for writes or when no cache is configured. */
+  async fetchWithCache(path, params, policy, fetcher) {
+    const hasBearerAuth = typeof this.http.hasBearerAuth === "function" && this.http.hasBearerAuth();
+    if (!this.cache || policy?.skipCache || hasBearerAuth) {
+      return fetcher();
+    }
+    const key = this.buildCacheKey(path, params);
+    return this.cache.getOrSet(key, fetcher, policy);
+  }
+  /** Invalidate cache entries by keys or tags. */
+  async invalidateCache(options) {
+    if (!this.cache) return;
+    await this.cache.invalidate(options);
+  }
+  buildCacheKey(path, params) {
+    const parts = [path];
+    if (params && Object.keys(params).length > 0) {
+      const sorted = {};
+      for (const key of Object.keys(params).sort()) {
+        sorted[key] = params[key];
+      }
+      parts.push(sorted);
+    }
+    if (this.cache) {
+      return this.cache.buildKey(parts);
+    }
+    return parts.map((p) => typeof p === "string" ? p : JSON.stringify(p)).join(":");
+  }
+  /**
+   * Auto-paginating async generator.
+   * Yields every item across all pages.
+   *
+   * Usage:
+   *   for await (const item of client.listAutoPaginate(path, params)) { ... }
+   */
+  async *listAutoPaginate(path, params) {
+    let startingAfter;
+    let hasMore = true;
+    while (hasMore) {
+      const queryParams = { ...params };
+      if (startingAfter) queryParams.starting_after = startingAfter;
+      const page = await this.getList(path, queryParams);
+      for (const item of page.data) {
+        yield item;
+      }
+      hasMore = page.has_more;
+      if (page.data.length > 0) {
+        startingAfter = page.data[page.data.length - 1].id;
+      } else {
+        hasMore = false;
+      }
+    }
+  }
+  toError(response) {
+    const data = response.data;
+    const errorObj = data?.error ?? response.error;
+    if (errorObj && typeof errorObj === "object" && "type" in errorObj) {
+      return new PerspectV2Error(errorObj, 400);
+    }
+    return new PerspectV2Error(
+      { type: "api_error", code: "unknown", message: response.message ?? "Unknown error" },
+      500
+    );
+  }
+};
+
+// src/v2/client/content-client.ts
+var ContentV2Client = class extends BaseV2Client {
+  async list(siteName, params, cachePolicy) {
+    return this.getList(
+      this.sitePath(siteName, "content"),
+      params,
+      this.withContentTags(siteName, cachePolicy, {
+        category: params?.category,
+        slugPrefix: params?.slug_prefix,
+        type: params?.type
+      })
+    );
+  }
+  async *listAutoPaginated(siteName, params, cachePolicy) {
+    let startingAfter;
+    let hasMore = true;
+    while (hasMore) {
+      const queryParams = { ...params ?? {} };
+      if (startingAfter) {
+        queryParams.starting_after = startingAfter;
+      }
+      const page = await this.list(siteName, queryParams, cachePolicy);
+      for (const item of page.data) {
+        yield item;
+      }
+      hasMore = page.has_more;
+      if (page.data.length > 0) {
+        startingAfter = page.data[page.data.length - 1].id;
+      } else {
+        hasMore = false;
+      }
+    }
+  }
+  async get(siteName, idOrSlug, cachePolicy) {
+    const isContentId = this.isContentId(idOrSlug);
+    return this.getOne(
+      this.sitePath(siteName, "content", idOrSlug),
+      void 0,
+      this.withContentTags(siteName, cachePolicy, {
+        id: isContentId ? idOrSlug : void 0,
+        slug: isContentId ? void 0 : idOrSlug,
+        slugPrefix: isContentId ? void 0 : this.extractSlugPrefix(idOrSlug)
+      })
+    );
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "content"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "content", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "content", id));
+  }
+  async publish(siteName, id) {
+    return this.post(this.sitePath(siteName, "content", `${id}/publish`));
+  }
+  async unpublish(siteName, id) {
+    return this.post(this.sitePath(siteName, "content", `${id}/unpublish`));
+  }
+  withContentTags(siteName, cachePolicy, options) {
+    const tags = new Set(cachePolicy?.tags ?? []);
+    for (const tag of this.buildContentTags(siteName, options)) {
+      tags.add(tag);
+    }
+    return {
+      ...cachePolicy,
+      tags: Array.from(tags)
+    };
+  }
+  buildContentTags(siteName, options) {
+    const tags = /* @__PURE__ */ new Set(["content", `content:site:${siteName}`]);
+    const normalizedPrefix = this.normalizeTagPart(options.slugPrefix);
+    const normalizedCategory = this.normalizeTagPart(options.category);
+    const normalizedType = this.normalizeTagPart(options.type);
+    if (options.slug) {
+      tags.add(`content:slug:${siteName}:${options.slug}`);
+    }
+    if (options.id) {
+      tags.add(`content:id:${options.id}`);
+    }
+    if (normalizedPrefix) {
+      tags.add(`content:prefix:${normalizedPrefix}`);
+    }
+    if (normalizedType) {
+      tags.add(`content:${normalizedType}`);
+    }
+    if (normalizedCategory) {
+      tags.add("content:category");
+      tags.add(`content:category:${siteName}:${normalizedCategory}`);
+    }
+    return Array.from(tags);
+  }
+  normalizeTagPart(value) {
+    if (typeof value !== "string") {
+      return void 0;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === "" ? void 0 : normalized;
+  }
+  extractSlugPrefix(slug) {
+    const slashIndex = slug.indexOf("/");
+    if (slashIndex > 0) {
+      return slug.slice(0, slashIndex);
+    }
+    return void 0;
+  }
+  isContentId(idOrSlug) {
+    return /^cnt_/i.test(idOrSlug);
+  }
+};
+
+// src/v2/client/products-client.ts
+var ProductsV2Client = class extends BaseV2Client {
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "products"), params, cachePolicy);
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "products"), params);
+  }
+  async get(siteName, idOrSlug, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "products", idOrSlug), void 0, cachePolicy);
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "products"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "products", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "products", id));
+  }
+};
+
+// src/v2/client/categories-client.ts
+var CategoriesV2Client = class extends BaseV2Client {
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "categories"), params, cachePolicy);
+  }
+  async get(siteName, id, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "categories", id), void 0, cachePolicy);
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "categories"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "categories", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "categories", id));
+  }
+};
+
+// src/v2/client/collections-client.ts
+var CollectionsV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "collections"), params, {
+      tags: [`collections:${siteName}`]
+    });
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "collections"), params);
+  }
+  async getCurrent(siteName) {
+    const result = await this.getOne(
+      this.sitePath(siteName, "collections", "current")
+    );
+    return result ?? null;
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "collections", id));
+  }
+  async create(siteName, data) {
+    const result = await this.post(this.sitePath(siteName, "collections"), data);
+    await this.invalidateCache({ tags: [`collections:${siteName}`] });
+    return result;
+  }
+  async update(siteName, id, data) {
+    const result = await this.patchOne(this.sitePath(siteName, "collections", id), data);
+    await this.invalidateCache({
+      tags: [`collections:${siteName}`],
+      keys: [this.sitePath(siteName, "collections", id)]
+    });
+    return result;
+  }
+  async del(siteName, id) {
+    const result = await this.deleteOne(this.sitePath(siteName, "collections", id));
+    await this.invalidateCache({
+      tags: [`collections:${siteName}`],
+      keys: [this.sitePath(siteName, "collections", id)]
+    });
+    return result;
+  }
+  // --- Items ---
+  async listItems(siteName, collectionId) {
+    return this.getList(
+      this.sitePath(siteName, "collections", `${collectionId}/items`)
+    );
+  }
+  async addItem(siteName, collectionId, data) {
+    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) {
+    const result = await this.deleteOne(
+      this.sitePath(siteName, "collections", `${collectionId}/items/${itemId}`)
+    );
+    await this.invalidateCache({
+      keys: [this.sitePath(siteName, "collections", `${collectionId}/items`)]
+    });
+    return result;
+  }
+};
+
+// src/v2/client/orders-client.ts
+var OrdersV2Client = class extends BaseV2Client {
+  async list(siteName, params, cachePolicy) {
+    return this.getList(this.sitePath(siteName, "orders"), params, cachePolicy);
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "orders"), params);
+  }
+  async get(siteName, id, cachePolicy) {
+    return this.getOne(this.sitePath(siteName, "orders", id), void 0, cachePolicy);
+  }
+  /**
+   * Create a checkout session via Stripe. Returns the session ID and a
+   * `checkout_url` that the client should redirect to (or open in a new tab).
+   *
+   * This replaces the v1 `checkout.createCheckoutSession()` + `getCsrfToken()`
+   * dance — v2 is API-key-only and requires no CSRF token.
+   */
+  async create(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "orders"),
+      data
+    );
+  }
+  /**
+   * Update fulfillment status, tracking number, and/or notes on an order.
+   *
+   * Set `notify_customer: true` when moving the order into a terminal
+   * fulfillment state to send the customer fulfillment email.
+   */
+  async updateFulfillment(siteName, id, data) {
+    return this.patchOne(
+      this.sitePath(siteName, "orders", `${id}/fulfillment`),
+      data
+    );
+  }
+};
+
+// src/v2/client/site-users-client.ts
+function bypassAuthenticatedCache(policy) {
+  return { ...policy, skipCache: true };
+}
+var SiteUsersV2Client = class extends BaseV2Client {
+  // --- OTP Auth (public, API-key-scoped) ---
+  async requestOtp(siteName, data) {
+    return this.post(this.sitePath(siteName, "users", "request-otp"), data);
+  }
+  async verifyOtp(siteName, data) {
+    return this.post(this.sitePath(siteName, "users", "verify-otp"), data);
+  }
+  // --- Admin (API key) ---
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "users"), params);
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "users"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "users", id));
+  }
+  async getProfileForUser(siteName, id, cachePolicy) {
+    return this.getOne(
+      this.sitePath(siteName, "users", `${id}/profile`),
+      void 0,
+      cachePolicy
+    );
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "users", id), data);
+  }
+  // --- Authenticated "me" endpoints (site-user JWT) ---
+  /**
+   * Load the currently-authenticated site user's canonical record plus their
+   * profile KV map. Requires `client.setAuth(jwt)` to have been called with
+   * the token returned from `verifyOtp`.
+   */
+  async getMe(siteName, cachePolicy) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me"),
+      void 0,
+      bypassAuthenticatedCache(cachePolicy)
+    );
+  }
+  /** Update the authenticated user's own fields. */
+  async updateMe(siteName, data) {
+    return this.patchOne(
+      this.sitePath(siteName, "users", "me"),
+      data
+    );
+  }
+  /** Fetch the profile KV map as a dedicated `site_user_profile` envelope. */
+  async getProfile(siteName, cachePolicy) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me/profile"),
+      void 0,
+      bypassAuthenticatedCache(cachePolicy)
+    );
+  }
+  /**
+   * Set a single profile key. The value is persisted verbatim — callers wanting
+   * structured data should JSON-stringify their value first.
+   */
+  async setProfileValue(siteName, key, value) {
+    const encoded = encodeURIComponent(key);
+    return this.putOne(
+      this.sitePath(siteName, "users", `me/profile/${encoded}`),
+      { value }
+    );
+  }
+  /** Delete a single profile key. */
+  async deleteProfileValue(siteName, key) {
+    const encoded = encodeURIComponent(key);
+    return this.deleteOne(
+      this.sitePath(siteName, "users", `me/profile/${encoded}`)
+    );
+  }
+};
+
+// src/v2/client/newsletter-client.ts
+var NewsletterV2Client = class extends BaseV2Client {
+  // --- Subscribe / Unsubscribe ---
+  async subscribe(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", "subscribe"),
+      data
+    );
+  }
+  async confirm(siteName, token) {
+    return this.getOne(
+      this.sitePath(siteName, "newsletter", `confirm/${token}`)
+    );
+  }
+  async unsubscribe(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", "unsubscribe"),
+      data
+    );
+  }
+  async trackOpen(siteName, token) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", `track/open/${encodeURIComponent(token)}`)
+    );
+  }
+  async trackClick(siteName, token, url) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", `track/click/${encodeURIComponent(token)}`),
+      { url }
+    );
+  }
+  // --- Subscriptions (admin) ---
+  async listSubscriptions(siteName, params, cachePolicy) {
+    return this.getList(
+      this.sitePath(siteName, "newsletter", "subscriptions"),
+      params,
+      cachePolicy
+    );
+  }
+  async getSubscription(siteName, id, cachePolicy) {
+    return this.getOne(
+      this.sitePath(siteName, "newsletter", `subscriptions/${id}`),
+      void 0,
+      cachePolicy
+    );
+  }
+  // --- Lists ---
+  async listLists(siteName, cachePolicy) {
+    return this.getList(
+      this.sitePath(siteName, "newsletter", "lists"),
+      void 0,
+      cachePolicy
+    );
+  }
+  // --- Campaigns ---
+  async listCampaigns(siteName, params, cachePolicy) {
+    return this.getList(
+      this.sitePath(siteName, "newsletter", "campaigns"),
+      params,
+      cachePolicy
+    );
+  }
+  async getCampaign(siteName, idOrSlug, cachePolicy) {
+    return this.getOne(
+      this.sitePath(siteName, "newsletter", `campaigns/${idOrSlug}`),
+      void 0,
+      cachePolicy
+    );
+  }
+  // --- Admin writes: Lists CRUD ---
+  async createList(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", "lists"),
+      data
+    );
+  }
+  async updateList(siteName, id, data) {
+    return this.patchOne(
+      this.sitePath(siteName, "newsletter", `lists/${id}`),
+      data
+    );
+  }
+  async deleteList(siteName, id) {
+    return this.deleteOne(
+      this.sitePath(siteName, "newsletter", `lists/${id}`)
+    );
+  }
+  // --- Admin writes: Subscription sync / membership / import ---
+  /**
+   * Upsert a subscription by email and (optionally) replace its list
+   * memberships. Returns a `newsletter_sync_result` envelope with the
+   * outcome (created / updated / resubscribed / already-unsubscribed).
+   */
+  async syncSubscription(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", "subscriptions/sync"),
+      data
+    );
+  }
+  /**
+   * Add/remove/replace the list memberships for an existing subscription.
+   * Returns the refreshed subscription record.
+   */
+  async updateSubscriptionListMembership(siteName, subscriptionId, data) {
+    return this.post(
+      this.sitePath(
+        siteName,
+        "newsletter",
+        `subscriptions/${subscriptionId}/list-membership`
+      ),
+      data
+    );
+  }
+  /**
+   * Bulk import subscriptions. Each row is upserted via the same sync
+   * path; `refreshListCounts` is deferred until after all rows are
+   * processed on the server.
+   */
+  async importSubscriptions(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", "subscriptions/import"),
+      data
+    );
+  }
+};
+
+// src/v2/client/contacts-client.ts
+var ContactsV2Client = class extends BaseV2Client {
+  async submit(siteName, data) {
+    return this.post(this.sitePath(siteName, "contacts"), data);
+  }
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "contacts"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "contacts", id));
+  }
+};
+
+// src/v2/client/organizations-client.ts
+var OrganizationsV2Client = class extends BaseV2Client {
+  async list() {
+    return this.getList("/organizations");
+  }
+  async get(id) {
+    return this.getOne(`/organizations/${id}`);
+  }
+};
+
+// src/v2/client/sites-client.ts
+var SitesV2Client = class extends BaseV2Client {
+  async list(params) {
+    return this.getList("/sites", params);
+  }
+  async get(name) {
+    return this.getOne(`/sites/${encodeURIComponent(name)}`);
+  }
+};
+
+// src/v2/client/api-keys-client.ts
+var ApiKeysV2Client = class extends BaseV2Client {
+  async list(params) {
+    return this.getList("/api-keys", params);
+  }
+  async get(id) {
+    return this.getOne(`/api-keys/${id}`);
+  }
+  async del(id) {
+    return this.deleteOne(`/api-keys/${id}`);
+  }
+};
+
+// src/v2/client/webhooks-client.ts
+var WebhooksV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "webhooks"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "webhooks", id));
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "webhooks"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "webhooks", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "webhooks", id));
+  }
+};
+
+// src/v2/client/subscriptions-client.ts
+var SubscriptionsV2Client = class extends BaseV2Client {
+  // --- Authenticated "me" endpoints (site-user JWT) ---
+  /** List all subscriptions for the authenticated user. */
+  async listMySubscriptions(siteName, cachePolicy) {
+    return this.getList(
+      this.sitePath(siteName, "users", "me/subscriptions"),
+      void 0,
+      { ...cachePolicy, skipCache: true }
+    );
+  }
+  /** Pause a subscription. */
+  async pauseSubscription(siteName, subId, params) {
+    return this.post(
+      this.sitePath(siteName, "users", `me/subscriptions/${subId}/pause`),
+      params ?? {}
+    );
+  }
+  /** Resume a paused subscription. */
+  async resumeSubscription(siteName, subId) {
+    return this.post(
+      this.sitePath(siteName, "users", `me/subscriptions/${subId}/resume`)
+    );
+  }
+  /** Cancel a subscription. */
+  async cancelSubscription(siteName, subId, params) {
+    return this.post(
+      this.sitePath(siteName, "users", `me/subscriptions/${subId}/cancel`),
+      params ?? {}
+    );
+  }
+  /** Change the plan (price) of a subscription. */
+  async changeSubscriptionPlan(siteName, subId, params) {
+    return this.post(
+      this.sitePath(siteName, "users", `me/subscriptions/${subId}/change-plan`),
+      params
+    );
+  }
+  // --- Admin endpoints (API key) ---
+  /** List subscriptions for a specific user (admin). */
+  async listUserSubscriptions(siteName, userId, cachePolicy) {
+    return this.getList(
+      this.sitePath(siteName, "users", `${userId}/subscriptions`),
+      void 0,
+      cachePolicy
+    );
+  }
+  /** Pause a user's subscription (admin). */
+  async pauseUserSubscription(siteName, userId, subId, params) {
+    return this.post(
+      this.sitePath(siteName, "users", `${userId}/subscriptions/${subId}/pause`),
+      params ?? {}
+    );
+  }
+  /** Resume a user's paused subscription (admin). */
+  async resumeUserSubscription(siteName, userId, subId) {
+    return this.post(
+      this.sitePath(siteName, "users", `${userId}/subscriptions/${subId}/resume`)
+    );
+  }
+  /** Cancel a user's subscription (admin). */
+  async cancelUserSubscription(siteName, userId, subId, params) {
+    return this.post(
+      this.sitePath(siteName, "users", `${userId}/subscriptions/${subId}/cancel`),
+      params ?? {}
+    );
+  }
+  /** Charge a user's subscription once (admin). */
+  async chargeUserSubscription(siteName, userId, subId, params) {
+    return this.post(
+      this.sitePath(siteName, "users", `${userId}/subscriptions/${subId}/charges`),
+      params
+    );
+  }
+};
+
+// src/v2/client/credits-client.ts
+var CreditsV2Client = class extends BaseV2Client {
+  // --- Authenticated "me" endpoints (site-user JWT) ---
+  /** Get the current credit balance for the authenticated user. */
+  async getMyBalance(siteName, cachePolicy) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me/credits/balance"),
+      void 0,
+      { ...cachePolicy, skipCache: true }
+    );
+  }
+  /** Get credit balance and transaction history for the authenticated user. */
+  async getMyCredits(siteName, cachePolicy) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me/credits"),
+      void 0,
+      { ...cachePolicy, skipCache: true }
+    );
+  }
+  // --- Admin endpoints (API key) ---
+  /** Get the credit balance for a specific user (admin). */
+  async getUserBalance(siteName, userId) {
+    return this.getOne(
+      this.sitePath(siteName, "users", `${userId}/credits/balance`)
+    );
+  }
+  /** Grant credit to a specific user (admin). */
+  async grantCredit(siteName, userId, data) {
+    return this.post(
+      this.sitePath(siteName, "users", `${userId}/credits/grant`),
+      data
+    );
+  }
+};
+
+// src/v2/index.ts
+var PerspectApiV2Client = class {
+  http;
+  cache;
+  content;
+  products;
+  categories;
+  collections;
+  orders;
+  siteUsers;
+  newsletter;
+  contacts;
+  organizations;
+  sites;
+  apiKeys;
+  webhooks;
+  subscriptions;
+  credits;
+  constructor(config) {
+    const baseUrl = config.baseUrl.replace(/\/+$/, "");
+    const v2BaseUrl = baseUrl.endsWith("/api/v2") ? baseUrl : `${baseUrl}/api/v2`;
+    this.http = new HttpClient({ ...config, baseUrl: v2BaseUrl });
+    this.cache = new CacheManager(config.cache);
+    const basePath = "";
+    const cache = this.cache;
+    this.content = new ContentV2Client(this.http, basePath, cache);
+    this.products = new ProductsV2Client(this.http, basePath, cache);
+    this.categories = new CategoriesV2Client(this.http, basePath, cache);
+    this.collections = new CollectionsV2Client(this.http, basePath, cache);
+    this.orders = new OrdersV2Client(this.http, basePath, cache);
+    this.siteUsers = new SiteUsersV2Client(this.http, basePath, cache);
+    this.newsletter = new NewsletterV2Client(this.http, basePath, cache);
+    this.contacts = new ContactsV2Client(this.http, basePath, cache);
+    this.organizations = new OrganizationsV2Client(this.http, basePath, cache);
+    this.sites = new SitesV2Client(this.http, basePath, cache);
+    this.apiKeys = new ApiKeysV2Client(this.http, basePath, cache);
+    this.webhooks = new WebhooksV2Client(this.http, basePath, cache);
+    this.subscriptions = new SubscriptionsV2Client(this.http, basePath, cache);
+    this.credits = new CreditsV2Client(this.http, basePath, cache);
+  }
+  /** Update the JWT token for authenticated requests. */
+  setAuth(jwt) {
+    this.http.setAuth(jwt);
+  }
+  /** Update the API key. */
+  setApiKey(apiKey) {
+    this.http.setApiKey(apiKey);
+  }
+  /** Clear authentication. */
+  clearAuth() {
+    this.http.clearAuth();
+  }
+};
+function createPerspectApiV2Client(config) {
+  return new PerspectApiV2Client(config);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiKeysV2Client,
+  BaseV2Client,
+  CategoriesV2Client,
+  CollectionsV2Client,
+  ContactsV2Client,
+  ContentV2Client,
+  CreditsV2Client,
+  NewsletterV2Client,
+  OrdersV2Client,
+  OrganizationsV2Client,
+  PerspectApiV2Client,
+  PerspectV2Error,
+  ProductsV2Client,
+  SiteUsersV2Client,
+  SitesV2Client,
+  SubscriptionsV2Client,
+  WebhooksV2Client,
+  createPerspectApiV2Client
+});