perspectapi-ts-sdk 5.4.5 → 6.0.1

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,20 @@
 /**
  * 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,
+  V2OrderFulfillmentUpdate,
+  V2List,
+} from '../types';
 
 export class OrdersV2Client extends BaseV2Client {
 
@@ -19,4 +29,33 @@ 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,
+    );
+  }
+
+  /** Update fulfillment status, tracking number, and/or notes on an order. */
+  async updateFulfillment(
+    siteName: string,
+    id: string,
+    data: V2OrderFulfillmentUpdate,
+  ): Promise<V2Order> {
+    return this.patchOne<V2Order>(
+      this.sitePath(siteName, 'orders', `${id}/fulfillment`),
+      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/client/subscriptions-client.ts

@@ -0,0 +1,126 @@
+/**
+ * v2 Subscriptions Client — lifecycle operations for site user subscriptions.
+ *
+ * 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 {
+  V2SiteUserSubscription,
+  V2SubscriptionPauseParams,
+  V2SubscriptionCancelParams,
+  V2SubscriptionChangePlanParams,
+  V2CancelSubscriptionResult,
+  V2List,
+} from '../types';
+
+export class SubscriptionsV2Client extends BaseV2Client {
+
+  // --- Authenticated "me" endpoints (site-user JWT) ---
+
+  /** List all subscriptions for the authenticated user. */
+  async listMySubscriptions(
+    siteName: string,
+  ): Promise<V2List<V2SiteUserSubscription>> {
+    return this.getList<V2SiteUserSubscription>(
+      this.sitePath(siteName, 'users', 'me/subscriptions'),
+    );
+  }
+
+  /** Pause a subscription. */
+  async pauseSubscription(
+    siteName: string,
+    subId: string,
+    params?: V2SubscriptionPauseParams,
+  ): Promise<V2SiteUserSubscription> {
+    return this.post<V2SiteUserSubscription>(
+      this.sitePath(siteName, 'users', `me/subscriptions/${subId}/pause`),
+      params ?? {},
+    );
+  }
+
+  /** Resume a paused subscription. */
+  async resumeSubscription(
+    siteName: string,
+    subId: string,
+  ): Promise<V2SiteUserSubscription> {
+    return this.post<V2SiteUserSubscription>(
+      this.sitePath(siteName, 'users', `me/subscriptions/${subId}/resume`),
+    );
+  }
+
+  /** Cancel a subscription. */
+  async cancelSubscription(
+    siteName: string,
+    subId: string,
+    params?: V2SubscriptionCancelParams,
+  ): Promise<V2CancelSubscriptionResult> {
+    return this.post<V2CancelSubscriptionResult>(
+      this.sitePath(siteName, 'users', `me/subscriptions/${subId}/cancel`),
+      params ?? {},
+    );
+  }
+
+  /** Change the plan (price) of a subscription. */
+  async changeSubscriptionPlan(
+    siteName: string,
+    subId: string,
+    params: V2SubscriptionChangePlanParams,
+  ): Promise<V2SiteUserSubscription> {
+    return this.post<V2SiteUserSubscription>(
+      this.sitePath(siteName, 'users', `me/subscriptions/${subId}/change-plan`),
+      params,
+    );
+  }
+
+  // --- Admin endpoints (API key) ---
+
+  /** List subscriptions for a specific user (admin). */
+  async listUserSubscriptions(
+    siteName: string,
+    userId: string,
+  ): Promise<V2List<V2SiteUserSubscription>> {
+    return this.getList<V2SiteUserSubscription>(
+      this.sitePath(siteName, 'users', `${userId}/subscriptions`),
+    );
+  }
+
+  /** Pause a user's subscription (admin). */
+  async pauseUserSubscription(
+    siteName: string,
+    userId: string,
+    subId: string,
+    params?: V2SubscriptionPauseParams,
+  ): Promise<V2SiteUserSubscription> {
+    return this.post<V2SiteUserSubscription>(
+      this.sitePath(siteName, 'users', `${userId}/subscriptions/${subId}/pause`),
+      params ?? {},
+    );
+  }
+
+  /** Resume a user's paused subscription (admin). */
+  async resumeUserSubscription(
+    siteName: string,
+    userId: string,
+    subId: string,
+  ): Promise<V2SiteUserSubscription> {
+    return this.post<V2SiteUserSubscription>(
+      this.sitePath(siteName, 'users', `${userId}/subscriptions/${subId}/resume`),
+    );
+  }
+
+  /** Cancel a user's subscription (admin). */
+  async cancelUserSubscription(
+    siteName: string,
+    userId: string,
+    subId: string,
+    params?: V2SubscriptionCancelParams,
+  ): Promise<V2CancelSubscriptionResult> {
+    return this.post<V2CancelSubscriptionResult>(
+      this.sitePath(siteName, 'users', `${userId}/subscriptions/${subId}/cancel`),
+      params ?? {},
+    );
+  }
+}

package/src/v2/index.ts

@@ -27,6 +27,8 @@ import { OrganizationsV2Client } from './client/organizations-client';
 import { SitesV2Client } from './client/sites-client';
 import { ApiKeysV2Client } from './client/api-keys-client';
 import { WebhooksV2Client } from './client/webhooks-client';
+import { SubscriptionsV2Client } from './client/subscriptions-client';
+import { CreditsV2Client } from './client/credits-client';
 
 export interface PerspectApiV2Config extends PerspectApiConfig {
   cache?: CacheConfig;
@@ -48,6 +50,8 @@ export class PerspectApiV2Client {
   readonly sites: SitesV2Client;
   readonly apiKeys: ApiKeysV2Client;
   readonly webhooks: WebhooksV2Client;
+  readonly subscriptions: SubscriptionsV2Client;
+  readonly credits: CreditsV2Client;
 
   constructor(config: PerspectApiV2Config) {
     // Ensure base URL points to /api/v2
@@ -73,6 +77,8 @@ export class PerspectApiV2Client {
     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. */
@@ -112,3 +118,5 @@ export { OrganizationsV2Client } from './client/organizations-client';
 export { SitesV2Client } from './client/sites-client';
 export { ApiKeysV2Client } from './client/api-keys-client';
 export { WebhooksV2Client } from './client/webhooks-client';
+export { SubscriptionsV2Client } from './client/subscriptions-client';
+export { CreditsV2Client } from './client/credits-client';