perspectapi-ts-sdk 6.5.7 → 7.0.0

package/examples/README.md

@@ -0,0 +1,19 @@
+# PerspectAPI SDK Examples
+
+These examples use the current v2 SDK surface.
+
+Do not use `/api/v1`, `PerspectApiClient`, or `createPerspectApiClient` for new
+code. Historical v1 examples live under `docs/v1-deprecated/examples/`.
+
+## Basic v2 Usage
+
+```typescript
+import { createPerspectApiV2Client } from 'perspectapi-ts-sdk/v2';
+
+const client = createPerspectApiV2Client({
+  baseUrl: process.env.PERSPECTAPI_BASE_URL!,
+  apiKey: process.env.PERSPECTAPI_API_KEY!,
+});
+
+const products = await client.products.list('my-site', { limit: 20 });
+```

package/examples/basic-v2.ts

@@ -0,0 +1,37 @@
+/**
+ * Basic usage example for the current PerspectAPI v2 TypeScript SDK.
+ */
+
+import { createPerspectApiV2Client, PerspectV2Error } from '../src/v2';
+
+const client = createPerspectApiV2Client({
+  baseUrl: process.env.PERSPECTAPI_BASE_URL || 'https://api.perspect.com',
+  apiKey: process.env.PERSPECTAPI_API_KEY || 'your-api-key',
+});
+
+const siteName = process.env.PERSPECTAPI_SITE_NAME || 'my-site';
+
+async function main() {
+  try {
+    const site = await client.sites.get(siteName);
+    console.log('Site:', site.id, site.name);
+
+    const products = await client.products.list(siteName, { limit: 10 });
+    console.log(`Loaded ${products.data.length} products`);
+
+    const content = await client.content.list(siteName, {
+      type: 'post',
+      status: 'publish',
+      limit: 10,
+    });
+    console.log(`Loaded ${content.data.length} posts`);
+  } catch (error) {
+    if (error instanceof PerspectV2Error) {
+      console.error('Perspect API error:', error.type, error.code, error.message);
+      return;
+    }
+    console.error('Unexpected error:', error);
+  }
+}
+
+main();

package/llms.txt

@@ -0,0 +1,25 @@
+# PerspectAPI TypeScript SDK
+
+PerspectAPI's current SDK and REST API surface is v2.
+
+## Hard Rule For Code Generation
+
+Do not generate new code that uses `/api/v1`, `PerspectApiClient`,
+`createPerspectApiClient`, or `src/client/*`.
+
+v1 is deprecated and sunsets on 2026-06-01.
+
+## Use This Instead
+
+```typescript
+import { createPerspectApiV2Client } from 'perspectapi-ts-sdk/v2';
+
+const client = createPerspectApiV2Client({
+  baseUrl: 'https://api.perspect.com',
+  apiKey: process.env.PERSPECTAPI_API_KEY!,
+});
+
+const products = await client.products.list('my-site', { limit: 20 });
+```
+
+REST calls should use `/api/v2`.

package/package.json

@@ -1,27 +1,38 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "6.5.7",
+  "version": "7.0.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
+    },
+    "./v2": {
+      "types": "./dist/v2/index.d.ts",
+      "import": "./dist/v2/index.mjs",
+      "require": "./dist/v2/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist/**/*",
     "src/**/*",
+    "docs/README.md",
+    "docs/v1-deprecated/**/*",
+    "examples/README.md",
+    "examples/basic-v2.ts",
     "tsconfig.json",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsup src/index.ts src/v2/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/v2/index.ts --format cjs,esm --dts --watch",
+    "lint:deprecated-v1": "node scripts/check-deprecated-v1.mjs",
     "test": "node scripts/test-runner.js",
     "test:all": "vitest run",
     "test:watch": "node scripts/test-runner.js watch",
@@ -29,7 +40,7 @@
     "test:unit": "node scripts/test-runner.js unit",
     "test:integration": "node scripts/test-runner.js integration",
     "test:types": "node scripts/test-runner.js types",
-    "test:ci": "node scripts/test-runner.js ci",
+    "test:ci": "npm run lint:deprecated-v1 && node scripts/test-runner.js ci",
     "lint": "eslint src --ext .ts",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build && npm run test:ci"

package/src/client/api-keys-client.ts

@@ -12,6 +12,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.apiKeys` from
+ * `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class ApiKeysClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/auth-client.ts

@@ -12,6 +12,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use
+ * `PerspectApiV2Client` / `createPerspectApiV2Client` for new integrations.
+ */
 export class AuthClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/base-client.ts

@@ -3,16 +3,23 @@
  */
 
 import { HttpClient } from '../utils/http-client';
+import { warnV1Deprecated } from '../deprecation';
 import type { ApiResponse } from '../types';
 import type { CacheManager } from '../cache/cache-manager';
 import type { CachePolicy, CacheInvalidateOptions } from '../cache/types';
 
+/**
+ * @deprecated v1 base client. v1 sunsets on 2026-06-01. Use
+ * `PerspectApiV2Client` / `createPerspectApiV2Client` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
+ */
 export abstract class BaseClient {
   protected http: HttpClient;
   protected basePath: string;
   protected cache?: CacheManager;
 
   constructor(http: HttpClient, basePath: string, cache?: CacheManager) {
+    warnV1Deprecated();
     this.http = http;
     this.basePath = basePath;
     this.cache = cache && cache.isEnabled() ? cache : undefined;

package/src/client/bundles-client.ts

@@ -16,6 +16,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use v2 collections and
+ * products clients from `PerspectApiV2Client`.
+ */
 export class BundlesClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/categories-client.ts

@@ -11,6 +11,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.categories`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class CategoriesClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/checkout-client.ts

@@ -10,6 +10,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use v2 checkout/orders
+ * surfaces from `PerspectApiV2Client`.
+ */
 export class CheckoutClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/contact-client.ts

@@ -13,6 +13,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.contacts`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class ContactClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/content-client.ts

@@ -16,6 +16,10 @@ import type {
 } from '../types';
 import { validateOptionalContentType, validateOptionalLimit } from '../utils/validators';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.content`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class ContentClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/newsletter-client.ts

@@ -20,6 +20,10 @@ import type {
 } from '../types';
 import { validateOptionalLimit } from '../utils/validators';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.newsletter`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class NewsletterClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/newsletter-management-client.ts

@@ -27,6 +27,10 @@ import type {
   NewsletterSubscriptionsImportResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.newsletter`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class NewsletterManagementClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/organizations-client.ts

@@ -11,6 +11,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use
+ * `client.organizations` from `PerspectApiV2Client`.
+ */
 export class OrganizationsClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/products-client.ts

@@ -16,6 +16,10 @@ import type {
 } from '../types';
 import { validateOptionalLimit } from '../utils/validators';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.products`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class ProductsClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

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

@@ -23,6 +23,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.siteUsers`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class SiteUsersClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);
@@ -511,7 +515,12 @@ export class SiteUsersClient extends BaseClient {
   async updateOrderFulfillment(
     siteName: string,
     sessionId: string,
-    data: { fulfillment_status: string; tracking_number?: string; notes?: string }
+    data: {
+      fulfillment_status: string;
+      tracking_number?: string;
+      notes?: string;
+      notify_customer?: boolean;
+    }
   ): Promise<ApiResponse<{ success: boolean }>> {
     return this.patch<typeof data, { success: boolean }>(
       this.siteUserEndpoint(siteName, `/users/orders/${encodeURIComponent(sessionId)}/fulfillment`),

package/src/client/sites-client.ts

@@ -11,6 +11,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.sites`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class SitesClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/client/webhooks-client.ts

@@ -11,6 +11,10 @@ import type {
   ApiResponse,
 } from '../types';
 
+/**
+ * @deprecated v1 client. v1 sunsets on 2026-06-01. Use `client.webhooks`
+ * from `PerspectApiV2Client` / `createPerspectApiV2Client`.
+ */
 export class WebhooksClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
     super(http, '/api/v1', cache);

package/src/deprecation.ts

@@ -8,7 +8,8 @@
 export const V1_SUNSET_DATE = "2026-06-01";
 export const V1_DEPRECATION_NOTICE =
   "perspectapi-ts-sdk v1 client is deprecated; sunsets 2026-06-01. " +
-  "New integrations must use createPerspectApiV2Client.";
+  "Do not use it for new code. Use createPerspectApiV2Client from " +
+  "perspectapi-ts-sdk/v2.";
 
 let warned = false;
 

package/src/index.ts

@@ -4,7 +4,8 @@
  *
  * ⚠️ v1 clients (everything exported from `./perspect-api-client` and
  * `./client/*`) are deprecated and sunset on 2026-06-01. New integrations
- * must use `PerspectApiV2Client` / `createPerspectApiV2Client`. See
+ * must use `PerspectApiV2Client` / `createPerspectApiV2Client`, preferably
+ * imported from `perspectapi-ts-sdk/v2` so the version is explicit. See
  * `src/deprecation.ts` for the shared sunset constants.
  */
 

package/src/loaders.ts

@@ -2,6 +2,11 @@
  * High-level data loading helpers that wrap the PerspectAPI SDK clients.
  * These helpers provide convenient product and content loading utilities with
  * graceful fallbacks that can be reused across applications.
+ *
+ * @deprecated These helpers are tied to the v1 `PerspectApiClient` and
+ * `/api/v1` route shapes. v1 sunsets on 2026-06-01. New integrations should
+ * use `PerspectApiV2Client` / `createPerspectApiV2Client` from
+ * `perspectapi-ts-sdk/v2` and call v2 resource clients directly.
  */
 
 import type { PerspectApiClient } from './perspect-api-client';
@@ -123,6 +128,9 @@ const normalizeQueryParamList = (
 
 /**
  * Transform a PerspectAPI product payload into a friendlier shape for UI layers.
+ *
+ * @deprecated Legacy v1 payload transformer. Prefer v2 product response types
+ * from `perspectapi-ts-sdk/v2`.
  */
 export const transformProduct = (
   perspectProduct: any,
@@ -180,6 +188,9 @@ export const transformProduct = (
 
 /**
  * Transform PerspectAPI content payload to a simplified BlogPost structure.
+ *
+ * @deprecated Legacy v1 payload transformer. Prefer v2 content response types
+ * from `perspectapi-ts-sdk/v2`.
  */
 export const transformContent = (
   perspectContent: Content | (Content & Record<string, unknown>),
@@ -305,6 +316,9 @@ const getDefaultFallbackPosts = (siteName: string): BlogPost[] => {
   ];
 };
 
+/**
+ * @deprecated v1 loader options. Use v2 resource clients directly.
+ */
 export interface LoaderOptions {
   /**
    * Pre-configured PerspectAPI client. Pass null/undefined to force fallback behaviour.
@@ -329,6 +343,9 @@ export interface LoaderOptions {
   limit?: number;
 }
 
+/**
+ * @deprecated v1 loader options. Use `client.products` from v2 directly.
+ */
 export interface LoadProductsOptions extends LoaderOptions {
   /**
    * Optional search term applied server-side.
@@ -368,6 +385,9 @@ const resolveFallbackPosts = (
 
 /**
  * Load products for a site with graceful fallbacks.
+ *
+ * @deprecated Uses the v1 client. Use `client.products.list(...)` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
  */
 export async function loadProducts(options: LoadProductsOptions): Promise<Product[]> {
   const {
@@ -426,12 +446,18 @@ export async function loadProducts(options: LoadProductsOptions): Promise<Produc
   }
 }
 
+/**
+ * @deprecated v1 loader options. Use `client.products` from v2 directly.
+ */
 export interface LoadProductBySlugOptions extends LoaderOptions {
   slug: string;
 }
 
 /**
  * Load single product by slug.
+ *
+ * @deprecated Uses the v1 client. Use `client.products.get(...)` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
  */
 export async function loadProductBySlug(
   options: LoadProductBySlugOptions
@@ -467,6 +493,9 @@ export async function loadProductBySlug(
   }
 }
 
+/**
+ * @deprecated v1 loader options. Use `client.content` from v2 directly.
+ */
 export interface LoadContentOptions extends LoaderOptions {
   /**
     * Additional query parameters for content filtering.
@@ -481,6 +510,9 @@ export interface LoadContentOptions extends LoaderOptions {
 
 /**
  * Load published pages for a site.
+ *
+ * @deprecated Uses the v1 client. Use `client.content.list(...)` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
  */
 export async function loadPages(
   options: LoadContentOptions
@@ -529,6 +561,9 @@ export async function loadPages(
 
 /**
  * Load published blog posts for a site.
+ *
+ * @deprecated Uses the v1 client. Use `client.content.list(...)` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
  */
 export async function loadPosts(
   options: LoadContentOptions
@@ -574,12 +609,18 @@ export async function loadPosts(
   }
 }
 
+/**
+ * @deprecated v1 loader options. Use `client.content` from v2 directly.
+ */
 export interface LoadContentBySlugOptions extends LoaderOptions {
   slug: string;
 }
 
 /**
  * Load a single content item (post or page) by slug.
+ *
+ * @deprecated Uses the v1 client. Use `client.content.get(...)` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
  */
 export async function loadContentBySlug(
   options: LoadContentBySlugOptions
@@ -615,12 +656,18 @@ export async function loadContentBySlug(
   }
 }
 
+/**
+ * @deprecated v1 loader options. Use `client.content` from v2 directly.
+ */
 export interface LoadBlockBySlugOptions extends LoaderOptions {
   slug: string;
 }
 
 /**
  * Load published blocks for a site.
+ *
+ * @deprecated Uses the v1 client. Use `client.content.list(...)` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
  */
 export async function loadBlocks(
   options: LoadContentOptions
@@ -664,6 +711,9 @@ export async function loadBlocks(
 
 /**
  * Load a single block by slug.
+ *
+ * @deprecated Uses the v1 client. Use `client.content.get(...)` from
+ * `perspectapi-ts-sdk/v2` for new integrations.
  */
 export async function loadBlockBySlug(
   options: LoadBlockBySlugOptions
@@ -694,6 +744,9 @@ export async function loadBlockBySlug(
 
 /**
  * Load all published content (pages + posts).
+ *
+ * @deprecated Uses the v1 client. Use v2 `client.content` reads directly for
+ * new integrations.
  */
 export async function loadAllContent(
   options: LoaderOptions
@@ -709,6 +762,9 @@ export async function loadAllContent(
   return [...pages, ...posts];
 }
 
+/**
+ * @deprecated v1 checkout helper options. Use v2 checkout/orders surfaces.
+ */
 export interface CheckoutSessionOptions {
   client?: PerspectApiClient | null;
   siteName: string;
@@ -749,6 +805,9 @@ export interface CheckoutSessionOptions {
 /**
  * Convenience helper that creates a checkout session by looking up Stripe price IDs
  * from product metadata. Falls back to gateway price IDs if Stripe IDs are missing.
+ *
+ * @deprecated Uses the v1 client. Use v2 checkout/orders surfaces for new
+ * integrations.
  */
 export async function createCheckoutSession(
   options: CheckoutSessionOptions

package/src/perspect-api-client.ts

@@ -26,7 +26,7 @@ import type { PerspectApiConfig, ApiResponse } from './types';
 /**
  * @deprecated v1 client is deprecated and sunsets 2026-06-01. New
  * integrations must use `PerspectApiV2Client` / `createPerspectApiV2Client`
- * from `perspectapi-ts-sdk` (see the `v2-client` reference page).
+ * from `perspectapi-ts-sdk/v2` (see the `v2-client` reference page).
  */
 export class PerspectApiClient {
   private http: HttpClient;
@@ -193,7 +193,7 @@ export class PerspectApiClient {
  * Create a new PerspectAPI client instance.
  *
  * @deprecated v1 factory is deprecated and sunsets 2026-06-01. Use
- * `createPerspectApiV2Client` for new integrations.
+ * `createPerspectApiV2Client` from `perspectapi-ts-sdk/v2` for new integrations.
  */
 export function createPerspectApiClient(config: PerspectApiConfig): PerspectApiClient {
   return new PerspectApiClient(config);

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

@@ -47,7 +47,12 @@ export class OrdersV2Client extends BaseV2Client {
     );
   }
 
-  /** Update fulfillment status, tracking number, and/or notes on an order. */
+  /**
+   * 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: string,
     id: string,

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

@@ -13,6 +13,8 @@ import type {
   V2SubscriptionPauseParams,
   V2SubscriptionCancelParams,
   V2SubscriptionChangePlanParams,
+  V2SubscriptionChargeParams,
+  V2SubscriptionChargeResult,
   V2CancelSubscriptionResult,
   V2List,
 } from '../types';
@@ -130,4 +132,17 @@ export class SubscriptionsV2Client extends BaseV2Client {
       params ?? {},
     );
   }
+
+  /** Charge a user's subscription once (admin). */
+  async chargeUserSubscription(
+    siteName: string,
+    userId: string,
+    subId: string,
+    params: V2SubscriptionChargeParams,
+  ): Promise<V2SubscriptionChargeResult> {
+    return this.post<V2SubscriptionChargeResult>(
+      this.sitePath(siteName, 'users', `${userId}/subscriptions/${subId}/charges`),
+      params,
+    );
+  }
 }

package/src/v2/types.ts

@@ -253,6 +253,7 @@ export interface V2Order extends V2Object {
 
 export interface V2OrderListParams extends V2PaginationParams {
   status?: string;
+  fulfillment_status?: string;
   customer_email?: string;
   date_from?: string;
   date_to?: string;
@@ -327,6 +328,8 @@ export interface V2OrderFulfillmentUpdate {
   fulfillment_status: string;
   tracking_number?: string;
   notes?: string;
+  /** When true, a terminal fulfillment status triggers a customer email. */
+  notify_customer?: boolean;
 }
 
 export interface V2OrderCreateResult extends V2Object {
@@ -689,6 +692,26 @@ export interface V2SubscriptionChangePlanParams {
   product_id: string;
 }
 
+export interface V2SubscriptionChargeParams {
+  amount_cents: number;
+  currency?: string;
+  description?: string;
+  idempotency_key: string;
+  metadata?: Record<string, string>;
+}
+
+export interface V2SubscriptionChargeResult {
+  object: "subscription_charge";
+  provider_invoice_id: string | null;
+  provider_invoice_item_id: string | null;
+  provider_payment_intent_id: string | null;
+  status: string | null;
+  paid: boolean;
+  amount_due: number | null;
+  amount_paid: number | null;
+  currency: string;
+}
+
 export interface V2CancelSubscriptionResult {
   object: "subscription_cancel_result";
   mode: string;