perspectapi-ts-sdk 5.4.5 → 6.0.0

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/newsletter-client.ts

@@ -6,7 +6,11 @@ import { BaseV2Client } from './base-v2-client';
 import type { CachePolicy } from '../../cache/types';
 import type {
   V2NewsletterSubscription, V2NewsletterList, V2NewsletterCampaign,
-  V2PaginationParams, V2List, V2NewsletterTrackingResponse,
+  V2PaginationParams, V2List, V2Deleted, V2NewsletterTrackingResponse,
+  V2NewsletterListCreateParams, V2NewsletterListUpdateParams,
+  V2NewsletterSyncInput, V2NewsletterSyncResult,
+  V2NewsletterSubscriptionListMembershipUpdate,
+  V2NewsletterImportRequest, V2NewsletterImportResult,
 } from '../types';
 
 export class NewsletterV2Client extends BaseV2Client {
@@ -122,4 +126,84 @@ export class NewsletterV2Client extends BaseV2Client {
       cachePolicy,
     );
   }
+
+  // --- Admin writes: Lists CRUD ---
+
+  async createList(
+    siteName: string,
+    data: V2NewsletterListCreateParams,
+  ): Promise<V2NewsletterList> {
+    return this.post<V2NewsletterList>(
+      this.sitePath(siteName, 'newsletter', 'lists'),
+      data,
+    );
+  }
+
+  async updateList(
+    siteName: string,
+    id: string,
+    data: V2NewsletterListUpdateParams,
+  ): Promise<V2NewsletterList> {
+    return this.patchOne<V2NewsletterList>(
+      this.sitePath(siteName, 'newsletter', `lists/${id}`),
+      data,
+    );
+  }
+
+  async deleteList(siteName: string, id: string): Promise<V2Deleted> {
+    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: string,
+    data: V2NewsletterSyncInput,
+  ): Promise<V2NewsletterSyncResult> {
+    return this.post<V2NewsletterSyncResult>(
+      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: string,
+    subscriptionId: string,
+    data: V2NewsletterSubscriptionListMembershipUpdate,
+  ): Promise<V2NewsletterSubscription> {
+    return this.post<V2NewsletterSubscription>(
+      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: string,
+    data: V2NewsletterImportRequest,
+  ): Promise<V2NewsletterImportResult> {
+    return this.post<V2NewsletterImportResult>(
+      this.sitePath(siteName, 'newsletter', 'subscriptions/import'),
+      data,
+    );
+  }
 }

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

@@ -1,10 +1,19 @@
 /**
  * v2 Orders Client (checkout sessions)
+ *
+ * `create()` initiates a Stripe checkout session and returns the checkout URL.
+ * No CSRF token is needed — v2 uses API-key auth only.
  */
 
 import { BaseV2Client } from './base-v2-client';
 import type { CachePolicy } from '../../cache/types';
-import type { V2Order, V2OrderListParams, V2List } from '../types';
+import type {
+  V2Order,
+  V2OrderListParams,
+  V2OrderCreateParams,
+  V2OrderCreateResult,
+  V2List,
+} from '../types';
 
 export class OrdersV2Client extends BaseV2Client {
 
@@ -19,4 +28,21 @@ export class OrdersV2Client extends BaseV2Client {
   async get(siteName: string, id: string, cachePolicy?: CachePolicy): Promise<V2Order> {
     return this.getOne<V2Order>(this.sitePath(siteName, 'orders', id), undefined, 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: string,
+    data: V2OrderCreateParams,
+  ): Promise<V2OrderCreateResult> {
+    return this.post<V2OrderCreateResult>(
+      this.sitePath(siteName, 'orders'),
+      data,
+    );
+  }
 }

package/src/v2/client/site-users-client.ts

@@ -1,9 +1,24 @@
 /**
  * v2 Site Users Client
+ *
+ * Two classes of endpoints:
+ *   - Admin paths (list/get/update/OTP flows) require an API key. Use the
+ *     usual `setApiKey(...)` on the main `PerspectApiV2Client` before calling.
+ *   - `/me*` paths require a site-user JWT (minted by `verifyOtp`). Call
+ *     `setAuth(jwt)` on the main client before calling these.
  */
 
 import { BaseV2Client } from './base-v2-client';
-import type { V2SiteUser, V2SiteUserUpdateParams, V2SiteUserListParams, V2List } from '../types';
+import type {
+  V2SiteUser,
+  V2SiteUserUpdateParams,
+  V2SiteUserMeUpdateParams,
+  V2SiteUserListParams,
+  V2SiteUserWithProfile,
+  V2SiteUserProfile,
+  V2List,
+  V2Deleted,
+} from '../types';
 
 export interface V2OtpRequestResponse {
   object: 'otp_request';
@@ -17,7 +32,7 @@ export interface V2OtpVerifyResponse extends V2SiteUser {
 
 export class SiteUsersV2Client extends BaseV2Client {
 
-  // --- OTP Auth ---
+  // --- OTP Auth (public, API-key-scoped) ---
 
   async requestOtp(
     siteName: string,
@@ -33,7 +48,7 @@ export class SiteUsersV2Client extends BaseV2Client {
     return this.post<V2OtpVerifyResponse>(this.sitePath(siteName, 'users', 'verify-otp'), data);
   }
 
-  // --- Admin ---
+  // --- Admin (API key) ---
 
   async list(siteName: string, params?: V2SiteUserListParams): Promise<V2List<V2SiteUser>> {
     return this.getList<V2SiteUser>(this.sitePath(siteName, 'users'), params);
@@ -50,4 +65,62 @@ export class SiteUsersV2Client extends BaseV2Client {
   async update(siteName: string, id: string, data: V2SiteUserUpdateParams): Promise<V2SiteUser> {
     return this.patchOne<V2SiteUser>(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: string): Promise<V2SiteUserWithProfile> {
+    return this.getOne<V2SiteUserWithProfile>(
+      this.sitePath(siteName, 'users', 'me'),
+    );
+  }
+
+  /** Update the authenticated user's own fields. */
+  async updateMe(
+    siteName: string,
+    data: V2SiteUserMeUpdateParams,
+  ): Promise<V2SiteUser> {
+    return this.patchOne<V2SiteUser>(
+      this.sitePath(siteName, 'users', 'me'),
+      data,
+    );
+  }
+
+  /** Fetch the profile KV map as a dedicated `site_user_profile` envelope. */
+  async getProfile(siteName: string): Promise<V2SiteUserProfile> {
+    return this.getOne<V2SiteUserProfile>(
+      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: string,
+    key: string,
+    value: string,
+  ): Promise<V2SiteUserProfile> {
+    const encoded = encodeURIComponent(key);
+    return this.putOne<V2SiteUserProfile>(
+      this.sitePath(siteName, 'users', `me/profile/${encoded}`),
+      { value },
+    );
+  }
+
+  /** Delete a single profile key. */
+  async deleteProfileValue(
+    siteName: string,
+    key: string,
+  ): Promise<V2Deleted> {
+    const encoded = encodeURIComponent(key);
+    return this.deleteOne(
+      this.sitePath(siteName, 'users', `me/profile/${encoded}`),
+    );
+  }
 }

package/src/v2/types.ts

@@ -250,6 +250,90 @@ export interface V2OrderListParams extends V2PaginationParams {
   date_to?: string;
 }
 
+// --- Order create (checkout session creation) ---
+
+export interface V2OrderLineItemPriceData {
+  currency: string;
+  product_data: {
+    name: string;
+    description?: string;
+    images?: string[];
+  };
+  unit_amount: number;
+}
+
+export interface V2OrderLineItem {
+  sku_id?: number;
+  product_id?: number;
+  price_data?: V2OrderLineItemPriceData;
+  price?: string;
+  quantity: number;
+}
+
+export interface V2OrderAddress {
+  line1?: string;
+  line2?: string;
+  city?: string;
+  state?: string;
+  postal_code?: string;
+  country?: string;
+}
+
+export interface V2OrderTaxRequest {
+  strategy?: string;
+  customer_identifier?: string;
+  customer_profile_id?: string;
+  customer_display_name?: string;
+  allow_exemption?: boolean;
+  save_profile?: boolean;
+  customer_exemption?: {
+    status?: "none" | "exempt" | "reverse_charge";
+    reason?: string;
+    tax_id?: string;
+    tax_id_type?: string;
+    certificate_url?: string;
+    metadata?: Record<string, unknown>;
+    expires_at?: string;
+  };
+}
+
+export interface V2OrderCreateParams {
+  line_items: V2OrderLineItem[];
+  success_url: string;
+  cancel_url: string;
+  customer_email?: string;
+  site_user_id?: string;
+  mode?: "payment" | "subscription";
+  metadata?: Record<string, string | number | boolean>;
+  tax?: V2OrderTaxRequest;
+  shipping_amount?: number;
+  shipping_address?: V2OrderAddress;
+  billing_address?: V2OrderAddress;
+  currency?: string;
+  referral_code?: string;
+  referrer_site_user_id?: string;
+}
+
+export interface V2OrderCreateResult extends V2Object {
+  object: "checkout_session";
+  checkout_url: string | null;
+  payment_status: string | null;
+  tax: {
+    amount: number;
+    currency: string;
+    strategy: string;
+    exemption_applied: boolean;
+    exemption_status: string;
+    breakdown: Array<{
+      jurisdiction?: string;
+      rate_percent: number;
+      tax_amount: number;
+      taxable_amount: number;
+      source: string;
+    }>;
+  };
+}
+
 // --- Site Users ---
 
 export interface V2SiteUser extends V2Object {
@@ -275,11 +359,41 @@ export interface V2SiteUserUpdateParams {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * Patch shape for the authenticated `/me` endpoint. Unlike the admin update,
+ * end users cannot change their own `status`.
+ */
+export interface V2SiteUserMeUpdateParams {
+  first_name?: string;
+  last_name?: string;
+  avatar_url?: string;
+  metadata?: Record<string, unknown>;
+}
+
 export interface V2SiteUserListParams extends V2PaginationParams {
   status?: "active" | "suspended" | "pending_verification";
   email?: string;
 }
 
+/**
+ * Response shape of `GET /sites/{siteName}/users/me`. Extends V2SiteUser with
+ * a `profile` side-channel populated from the `site_user_profiles` KV table.
+ */
+export interface V2SiteUserWithProfile extends V2SiteUser {
+  profile: Record<string, unknown>;
+}
+
+/**
+ * Standalone profile envelope returned by
+ * `GET|PUT /sites/{siteName}/users/me/profile[/:key]`. Each `data` entry is a
+ * parsed value (arbitrary JSON).
+ */
+export interface V2SiteUserProfile {
+  object: "site_user_profile";
+  site_user_id: string;
+  data: Record<string, unknown>;
+}
+
 // --- Newsletter ---
 
 export interface V2NewsletterSubscription extends V2Object {
@@ -332,6 +446,84 @@ export interface V2NewsletterTrackingResponse {
   success: boolean;
 }
 
+// --- Newsletter admin writes ---
+
+export interface V2NewsletterListCreateParams {
+  list_name: string;
+  slug: string;
+  description?: string | null;
+  is_public?: boolean;
+  is_default?: boolean;
+  welcome_email_enabled?: boolean;
+}
+
+export interface V2NewsletterListUpdateParams {
+  list_name?: string;
+  slug?: string;
+  description?: string | null;
+  is_public?: boolean;
+  is_default?: boolean;
+  welcome_email_enabled?: boolean;
+  status?: "active" | "archived";
+}
+
+export interface V2NewsletterSyncInput {
+  email: string;
+  name?: string | null;
+  status?: "pending" | "confirmed" | "unsubscribed" | "bounced" | "complained";
+  list_ids?: string[];
+  frequency?: "instant" | "daily" | "weekly" | "monthly";
+  topics?: string[];
+  language?: string | null;
+  source?: string | null;
+  source_url?: string | null;
+  notes?: string | null;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  resubscribe_override?: boolean;
+}
+
+export interface V2NewsletterSyncResult {
+  object: "newsletter_sync_result";
+  applied: boolean;
+  code: "CREATED" | "UPDATED" | "RESUBSCRIBED" | "ALREADY_UNSUBSCRIBED";
+  skipped_unsubscribed: boolean;
+  resubscribed: boolean;
+  created: boolean;
+  updated: boolean;
+  subscription: Record<string, unknown>;
+}
+
+export interface V2NewsletterSubscriptionListMembershipUpdate {
+  mode: "add" | "remove" | "replace";
+  list_ids: string[];
+}
+
+export interface V2NewsletterImportRequest {
+  rows: V2NewsletterSyncInput[];
+  resubscribe_override?: boolean;
+}
+
+export interface V2NewsletterImportResult {
+  object: "newsletter_import_result";
+  total: number;
+  processed: number;
+  applied: number;
+  created: number;
+  updated: number;
+  resubscribed: number;
+  skipped_unsubscribed: number;
+  rows: Array<{
+    index: number;
+    email: string;
+    applied: boolean;
+    code: V2NewsletterSyncResult["code"];
+    skipped_unsubscribed: boolean;
+    resubscribed: boolean;
+    subscription_id: string;
+  }>;
+}
+
 // --- Contact ---
 
 export interface V2ContactSubmission extends V2Object {