perspectapi-ts-sdk 5.4.5 → 6.0.1

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,38 @@ 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
+    );
+  }
+  /** Update fulfillment status, tracking number, and/or notes on an order. */
+  async updateFulfillment(siteName, id, data) {
+    return this.patchOne(
+      this.sitePath(siteName, "orders", `${id}/fulfillment`),
+      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 +3675,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 +3788,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
@@ -3708,6 +3910,102 @@ var WebhooksV2Client = class extends BaseV2Client {
   }
 };
 
+// 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) {
+    return this.getList(
+      this.sitePath(siteName, "users", "me/subscriptions")
+    );
+  }
+  /** 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) {
+    return this.getList(
+      this.sitePath(siteName, "users", `${userId}/subscriptions`)
+    );
+  }
+  /** 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 ?? {}
+    );
+  }
+};
+
+// 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) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me/credits/balance")
+    );
+  }
+  /** Get credit balance and transaction history for the authenticated user. */
+  async getMyCredits(siteName) {
+    return this.getOne(
+      this.sitePath(siteName, "users", "me/credits")
+    );
+  }
+  // --- 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;
@@ -3724,6 +4022,8 @@ var PerspectApiV2Client = class {
   sites;
   apiKeys;
   webhooks;
+  subscriptions;
+  credits;
   constructor(config) {
     const baseUrl = config.baseUrl.replace(/\/+$/, "");
     const v2BaseUrl = baseUrl.endsWith("/api/v2") ? baseUrl : `${baseUrl}/api/v2`;
@@ -3743,6 +4043,8 @@ var PerspectApiV2Client = class {
     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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "5.4.5",
+  "version": "6.0.1",
   "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);

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

@@ -12,15 +12,57 @@ import type {
 export class ContentV2Client extends BaseV2Client {
 
   async list(siteName: string, params?: V2ContentListParams, cachePolicy?: CachePolicy): Promise<V2List<V2Content>> {
-    return this.getList<V2Content>(this.sitePath(siteName, 'content'), params, cachePolicy);
+    return this.getList<V2Content>(
+      this.sitePath(siteName, 'content'),
+      params,
+      this.withContentTags(siteName, cachePolicy, {
+        category: params?.category,
+        slugPrefix: params?.slug_prefix,
+        type: params?.type,
+      }),
+    );
   }
 
-  async *listAutoPaginated(siteName: string, params?: Omit<V2ContentListParams, 'starting_after' | 'ending_before'>) {
-    yield* this.listAutoPaginate<V2Content>(this.sitePath(siteName, 'content'), params);
+  async *listAutoPaginated(
+    siteName: string,
+    params?: Omit<V2ContentListParams, 'starting_after' | 'ending_before'>,
+    cachePolicy?: CachePolicy,
+  ) {
+    let startingAfter: string | undefined;
+    let hasMore = true;
+
+    while (hasMore) {
+      const queryParams: V2ContentListParams = { ...(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: string, idOrSlug: string, cachePolicy?: CachePolicy): Promise<V2Content> {
-    return this.getOne<V2Content>(this.sitePath(siteName, 'content', idOrSlug), undefined, cachePolicy);
+    const isContentId = this.isContentId(idOrSlug);
+
+    return this.getOne<V2Content>(
+      this.sitePath(siteName, 'content', idOrSlug),
+      undefined,
+      this.withContentTags(siteName, cachePolicy, {
+        id: isContentId ? idOrSlug : undefined,
+        slug: isContentId ? undefined : idOrSlug,
+        slugPrefix: isContentId ? undefined : this.extractSlugPrefix(idOrSlug),
+      }),
+    );
   }
 
   async create(siteName: string, data: V2ContentCreateParams): Promise<V2Content> {
@@ -42,4 +84,83 @@ export class ContentV2Client extends BaseV2Client {
   async unpublish(siteName: string, id: string): Promise<V2Content> {
     return this.post<V2Content>(this.sitePath(siteName, 'content', `${id}/unpublish`));
   }
+
+  private withContentTags(
+    siteName: string,
+    cachePolicy: CachePolicy | undefined,
+    options: {
+      category?: string | null;
+      id?: string;
+      slug?: string;
+      slugPrefix?: string | null;
+      type?: string | null;
+    },
+  ): CachePolicy {
+    const tags = new Set<string>(cachePolicy?.tags ?? []);
+
+    for (const tag of this.buildContentTags(siteName, options)) {
+      tags.add(tag);
+    }
+
+    return {
+      ...cachePolicy,
+      tags: Array.from(tags),
+    };
+  }
+
+  private buildContentTags(
+    siteName: string,
+    options: {
+      category?: string | null;
+      id?: string;
+      slug?: string;
+      slugPrefix?: string | null;
+      type?: string | null;
+    },
+  ): string[] {
+    const tags = new Set<string>(['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);
+  }
+
+  private normalizeTagPart(value?: string | null): string | undefined {
+    if (typeof value !== 'string') {
+      return undefined;
+    }
+
+    const normalized = value.trim().toLowerCase();
+    return normalized === '' ? undefined : normalized;
+  }
+
+  private extractSlugPrefix(slug: string): string | undefined {
+    const slashIndex = slug.indexOf('/');
+    if (slashIndex > 0) {
+      return slug.slice(0, slashIndex);
+    }
+    return undefined;
+  }
+
+  private isContentId(idOrSlug: string): boolean {
+    return /^cnt_/i.test(idOrSlug);
+  }
 }

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

@@ -0,0 +1,57 @@
+/**
+ * v2 Credits Client — balance queries and admin grant operations.
+ *
+ * Two classes of endpoints:
+ *   - /me paths require a site-user JWT (call `setAuth(jwt)` first)
+ *   - Admin paths require an API key (call `setApiKey(key)` first)
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2CreditBalance,
+  V2GrantCreditParams,
+  V2GrantCreditResult,
+} from '../types';
+
+export class CreditsV2Client extends BaseV2Client {
+
+  // --- Authenticated "me" endpoints (site-user JWT) ---
+
+  /** Get the current credit balance for the authenticated user. */
+  async getMyBalance(siteName: string): Promise<V2CreditBalance> {
+    return this.getOne<V2CreditBalance>(
+      this.sitePath(siteName, 'users', 'me/credits/balance'),
+    );
+  }
+
+  /** Get credit balance and transaction history for the authenticated user. */
+  async getMyCredits(siteName: string): Promise<V2CreditBalance> {
+    return this.getOne<V2CreditBalance>(
+      this.sitePath(siteName, 'users', 'me/credits'),
+    );
+  }
+
+  // --- Admin endpoints (API key) ---
+
+  /** Get the credit balance for a specific user (admin). */
+  async getUserBalance(
+    siteName: string,
+    userId: string,
+  ): Promise<V2CreditBalance> {
+    return this.getOne<V2CreditBalance>(
+      this.sitePath(siteName, 'users', `${userId}/credits/balance`),
+    );
+  }
+
+  /** Grant credit to a specific user (admin). */
+  async grantCredit(
+    siteName: string,
+    userId: string,
+    data: V2GrantCreditParams,
+  ): Promise<V2GrantCreditResult> {
+    return this.post<V2GrantCreditResult>(
+      this.sitePath(siteName, 'users', `${userId}/credits/grant`),
+      data,
+    );
+  }
+}