perspectapi-ts-sdk 5.4.4 → 6.0.0

package/dist/index.js

@@ -399,11 +399,7 @@ var CacheManager = class {
   async getOrSet(key, resolveValue, policy) {
     if (!this.enabled || policy?.skipCache) {
       console.log("[Cache] Cache disabled or skipped", { key, enabled: this.enabled, skipCache: policy?.skipCache });
-      const value2 = await resolveValue();
-      if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
-        await this.set(key, value2, policy);
-      }
-      return value2;
+      return resolveValue();
     }
     const namespacedKey = this.namespacedKey(key);
     const cachedRaw = await this.adapter.get(namespacedKey);
@@ -426,7 +422,7 @@ var CacheManager = class {
     return value;
   }
   async set(key, value, options) {
-    if (!this.enabled || options?.ttlSeconds === 0) {
+    if (!this.enabled) {
       return;
     }
     const namespacedKey = this.namespacedKey(key);
@@ -3422,6 +3418,11 @@ var BaseV2Client = class {
     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);
@@ -3495,13 +3496,47 @@ var BaseV2Client = class {
 // src/v2/client/content-client.ts
 var ContentV2Client = class extends BaseV2Client {
   async list(siteName, params, cachePolicy) {
-    return this.getList(this.sitePath(siteName, "content"), 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) {
-    yield* this.listAutoPaginate(this.sitePath(siteName, "content"), params);
+  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) {
-    return this.getOne(this.sitePath(siteName, "content", idOrSlug), void 0, 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);
@@ -3518,6 +3553,56 @@ var ContentV2Client = class extends BaseV2Client {
   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
@@ -3614,18 +3699,31 @@ var OrdersV2Client = class extends BaseV2Client {
   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
+    );
+  }
 };
 
 // src/v2/client/site-users-client.ts
 var SiteUsersV2Client = class extends BaseV2Client {
-  // --- OTP Auth ---
+  // --- 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 ---
+  // --- Admin (API key) ---
   async list(siteName, params) {
     return this.getList(this.sitePath(siteName, "users"), params);
   }
@@ -3638,6 +3736,48 @@ var SiteUsersV2Client = class extends BaseV2Client {
   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) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me")
+    );
+  }
+  /** 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) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me/profile")
+    );
+  }
+  /**
+   * 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
@@ -3709,6 +3849,61 @@ var NewsletterV2Client = class extends BaseV2Client {
       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

package/dist/index.mjs

@@ -331,11 +331,7 @@ var CacheManager = class {
   async getOrSet(key, resolveValue, policy) {
     if (!this.enabled || policy?.skipCache) {
       console.log("[Cache] Cache disabled or skipped", { key, enabled: this.enabled, skipCache: policy?.skipCache });
-      const value2 = await resolveValue();
-      if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
-        await this.set(key, value2, policy);
-      }
-      return value2;
+      return resolveValue();
     }
     const namespacedKey = this.namespacedKey(key);
     const cachedRaw = await this.adapter.get(namespacedKey);
@@ -358,7 +354,7 @@ var CacheManager = class {
     return value;
   }
   async set(key, value, options) {
-    if (!this.enabled || options?.ttlSeconds === 0) {
+    if (!this.enabled) {
       return;
     }
     const namespacedKey = this.namespacedKey(key);
@@ -3354,6 +3350,11 @@ var BaseV2Client = class {
     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);
@@ -3427,13 +3428,47 @@ var BaseV2Client = class {
 // src/v2/client/content-client.ts
 var ContentV2Client = class extends BaseV2Client {
   async list(siteName, params, cachePolicy) {
-    return this.getList(this.sitePath(siteName, "content"), 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) {
-    yield* this.listAutoPaginate(this.sitePath(siteName, "content"), params);
+  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) {
-    return this.getOne(this.sitePath(siteName, "content", idOrSlug), void 0, 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);
@@ -3450,6 +3485,56 @@ var ContentV2Client = class extends BaseV2Client {
   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
@@ -3546,18 +3631,31 @@ var OrdersV2Client = class extends BaseV2Client {
   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
+    );
+  }
 };
 
 // src/v2/client/site-users-client.ts
 var SiteUsersV2Client = class extends BaseV2Client {
-  // --- OTP Auth ---
+  // --- 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 ---
+  // --- Admin (API key) ---
   async list(siteName, params) {
     return this.getList(this.sitePath(siteName, "users"), params);
   }
@@ -3570,6 +3668,48 @@ var SiteUsersV2Client = class extends BaseV2Client {
   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) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me")
+    );
+  }
+  /** 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) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me/profile")
+    );
+  }
+  /**
+   * 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
@@ -3641,6 +3781,61 @@ var NewsletterV2Client = class extends BaseV2Client {
       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

package/package.json

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

package/src/cache/cache-manager.ts

@@ -76,13 +76,7 @@ export class CacheManager {
   ): Promise<T> {
     if (!this.enabled || policy?.skipCache) {
       console.log('[Cache] Cache disabled or skipped', { key, enabled: this.enabled, skipCache: policy?.skipCache });
-      const value = await resolveValue();
-
-      if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
-        await this.set(key, value, policy);
-      }
-
-      return value;
+      return resolveValue();
     }
 
     const namespacedKey = this.namespacedKey(key);
@@ -113,7 +107,7 @@ export class CacheManager {
   }
 
   async set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void> {
-    if (!this.enabled || options?.ttlSeconds === 0) {
+    if (!this.enabled) {
       return;
     }
 

package/src/index.ts

@@ -10,6 +10,7 @@ export { default } from './perspect-api-client';
 // v2 client
 export { PerspectApiV2Client, createPerspectApiV2Client } from './v2';
 export { PerspectV2Error } from './v2/client/base-v2-client';
+export type * from './v2/types';
 
 // Individual clients (for advanced usage)
 export { AuthClient } from './client/auth-client';

package/src/v2/client/base-v2-client.ts

@@ -129,6 +129,12 @@ export abstract class BaseV2Client {
     return this.extractData<T>(response);
   }
 
+  /** PUT to upsert a resource. */
+  protected async putOne<T>(path: string, body?: unknown): Promise<T> {
+    const response = await this.http.put<T>(path, body);
+    return this.extractData<T>(response);
+  }
+
   /** DELETE a resource. */
   protected async deleteOne(path: string): Promise<V2Deleted> {
     const response = await this.http.delete<V2Deleted>(path);