perspectapi-ts-sdk 4.1.0 → 5.0.0

package/dist/index.mjs

@@ -2720,15 +2720,16 @@ var SiteUsersClient = class extends BaseClient {
     );
   }
   /**
-   * Cancel a subscription (marks for cancellation at period end)
+   * Cancel a subscription.
    * @param siteName - The site name
    * @param id - Subscription ID
    * @param csrfToken - CSRF token (required)
+   * @param options - Cancellation mode/details
    */
-  async cancelSubscription(siteName, id, csrfToken) {
+  async cancelSubscription(siteName, id, csrfToken, options) {
     return this.create(
       this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(id)}/cancel`),
-      {},
+      options ?? {},
       csrfToken
     );
   }
@@ -2958,11 +2959,12 @@ var SiteUsersClient = class extends BaseClient {
    * @param siteName - The site name
    * @param userId - User ID
    * @param subscriptionId - Subscription ID
+   * @param options - Cancellation mode/details
    */
-  async cancelUserSubscription(siteName, userId, subscriptionId) {
+  async cancelUserSubscription(siteName, userId, subscriptionId, options) {
     return this.create(
       this.siteUserEndpoint(siteName, `/users/${encodeURIComponent(userId)}/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`),
-      {}
+      options ?? {}
     );
   }
   /**
@@ -3255,6 +3257,440 @@ function createPerspectApiClient(config) {
 }
 var perspect_api_client_default = PerspectApiClient;
 
+// src/v2/client/base-v2-client.ts
+var PerspectV2Error = class extends Error {
+  type;
+  code;
+  param;
+  status;
+  constructor(error, status) {
+    super(error.message);
+    this.name = "PerspectV2Error";
+    this.type = error.type;
+    this.code = error.code;
+    this.param = error.param;
+    this.status = status;
+  }
+};
+var BaseV2Client = class {
+  http;
+  basePath;
+  constructor(http, basePath) {
+    this.http = http;
+    this.basePath = basePath;
+  }
+  buildPath(endpoint) {
+    const clean = endpoint.replace(/^\//, "");
+    return clean ? `${this.basePath}/${clean}` : this.basePath;
+  }
+  sitePath(siteName, resource, suffix = "") {
+    const encoded = encodeURIComponent(siteName.trim());
+    const cleanSuffix = suffix.replace(/^\//, "");
+    const end = cleanSuffix ? `/${cleanSuffix}` : "";
+    return `/sites/${encoded}/${resource}${end}`;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  toParams(params) {
+    if (!params) return void 0;
+    const out = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== void 0 && v !== null) out[k] = String(v);
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  /** GET a single resource. */
+  async getOne(path, params) {
+    const response = await this.http.get(path, this.toParams(params));
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data;
+  }
+  /** GET a list of resources with cursor pagination. */
+  async getList(path, params) {
+    const response = await this.http.get(path, this.toParams(params));
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data;
+  }
+  /** POST to create a resource. */
+  async post(path, body) {
+    const response = await this.http.post(path, body);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data;
+  }
+  /** PATCH to update a resource. */
+  async patchOne(path, body) {
+    const response = await this.http.patch(path, body);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data;
+  }
+  /** DELETE a resource. */
+  async deleteOne(path) {
+    const response = await this.http.delete(path);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data;
+  }
+  /**
+   * Auto-paginating async generator.
+   * Yields every item across all pages.
+   *
+   * Usage:
+   *   for await (const item of client.listAutoPaginate(path, params)) { ... }
+   */
+  async *listAutoPaginate(path, params) {
+    let startingAfter;
+    let hasMore = true;
+    while (hasMore) {
+      const queryParams = { ...params };
+      if (startingAfter) queryParams.starting_after = startingAfter;
+      const page = await this.getList(path, queryParams);
+      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;
+      }
+    }
+  }
+  toError(response) {
+    const data = response.data;
+    const errorObj = data?.error ?? response.error;
+    if (errorObj && typeof errorObj === "object" && "type" in errorObj) {
+      return new PerspectV2Error(errorObj, 400);
+    }
+    return new PerspectV2Error(
+      { type: "api_error", code: "unknown", message: response.message ?? "Unknown error" },
+      500
+    );
+  }
+};
+
+// src/v2/client/content-client.ts
+var ContentV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "content"), params);
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "content"), params);
+  }
+  async get(siteName, idOrSlug) {
+    return this.getOne(this.sitePath(siteName, "content", idOrSlug));
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "content"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "content", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "content", id));
+  }
+  async publish(siteName, id) {
+    return this.post(this.sitePath(siteName, "content", `${id}/publish`));
+  }
+  async unpublish(siteName, id) {
+    return this.post(this.sitePath(siteName, "content", `${id}/unpublish`));
+  }
+};
+
+// src/v2/client/products-client.ts
+var ProductsV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "products"), params);
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "products"), params);
+  }
+  async get(siteName, idOrSlug) {
+    return this.getOne(this.sitePath(siteName, "products", idOrSlug));
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "products"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "products", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "products", id));
+  }
+};
+
+// src/v2/client/categories-client.ts
+var CategoriesV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "categories"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "categories", id));
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "categories"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "categories", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "categories", id));
+  }
+};
+
+// src/v2/client/collections-client.ts
+var CollectionsV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "collections"), params);
+  }
+  async getCurrent(siteName) {
+    const result = await this.getOne(
+      this.sitePath(siteName, "collections", "current")
+    );
+    return result ?? null;
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "collections", id));
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "collections"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "collections", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "collections", id));
+  }
+  // --- Items ---
+  async listItems(siteName, collectionId) {
+    return this.getList(
+      this.sitePath(siteName, "collections", `${collectionId}/items`)
+    );
+  }
+  async addItem(siteName, collectionId, data) {
+    return this.post(
+      this.sitePath(siteName, "collections", `${collectionId}/items`),
+      data
+    );
+  }
+  async removeItem(siteName, collectionId, itemId) {
+    return this.deleteOne(
+      this.sitePath(siteName, "collections", `${collectionId}/items/${itemId}`)
+    );
+  }
+};
+
+// src/v2/client/orders-client.ts
+var OrdersV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "orders"), params);
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "orders"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "orders", id));
+  }
+};
+
+// src/v2/client/site-users-client.ts
+var SiteUsersV2Client = class extends BaseV2Client {
+  // --- OTP Auth ---
+  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 ---
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "users"), params);
+  }
+  async *listAutoPaginated(siteName, params) {
+    yield* this.listAutoPaginate(this.sitePath(siteName, "users"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "users", id));
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "users", id), data);
+  }
+};
+
+// src/v2/client/newsletter-client.ts
+var NewsletterV2Client = class extends BaseV2Client {
+  // --- Subscribe / Unsubscribe ---
+  async subscribe(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", "subscribe"),
+      data
+    );
+  }
+  async confirm(siteName, token) {
+    return this.getOne(
+      this.sitePath(siteName, "newsletter", `confirm/${token}`)
+    );
+  }
+  async unsubscribe(siteName, data) {
+    return this.post(
+      this.sitePath(siteName, "newsletter", "unsubscribe"),
+      data
+    );
+  }
+  // --- Subscriptions (admin) ---
+  async listSubscriptions(siteName, params) {
+    return this.getList(
+      this.sitePath(siteName, "newsletter", "subscriptions"),
+      params
+    );
+  }
+  async getSubscription(siteName, id) {
+    return this.getOne(
+      this.sitePath(siteName, "newsletter", `subscriptions/${id}`)
+    );
+  }
+  // --- Lists ---
+  async listLists(siteName) {
+    return this.getList(
+      this.sitePath(siteName, "newsletter", "lists")
+    );
+  }
+  // --- Campaigns ---
+  async listCampaigns(siteName, params) {
+    return this.getList(
+      this.sitePath(siteName, "newsletter", "campaigns"),
+      params
+    );
+  }
+  async getCampaign(siteName, idOrSlug) {
+    return this.getOne(
+      this.sitePath(siteName, "newsletter", `campaigns/${idOrSlug}`)
+    );
+  }
+};
+
+// src/v2/client/contacts-client.ts
+var ContactsV2Client = class extends BaseV2Client {
+  async submit(siteName, data) {
+    return this.post(this.sitePath(siteName, "contacts"), data);
+  }
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "contacts"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "contacts", id));
+  }
+};
+
+// src/v2/client/organizations-client.ts
+var OrganizationsV2Client = class extends BaseV2Client {
+  async list() {
+    return this.getList("/organizations");
+  }
+  async get(id) {
+    return this.getOne(`/organizations/${id}`);
+  }
+};
+
+// src/v2/client/sites-client.ts
+var SitesV2Client = class extends BaseV2Client {
+  async list(params) {
+    return this.getList("/sites", params);
+  }
+  async get(name) {
+    return this.getOne(`/sites/${encodeURIComponent(name)}`);
+  }
+};
+
+// src/v2/client/api-keys-client.ts
+var ApiKeysV2Client = class extends BaseV2Client {
+  async list(params) {
+    return this.getList("/api-keys", params);
+  }
+  async get(id) {
+    return this.getOne(`/api-keys/${id}`);
+  }
+  async del(id) {
+    return this.deleteOne(`/api-keys/${id}`);
+  }
+};
+
+// src/v2/client/webhooks-client.ts
+var WebhooksV2Client = class extends BaseV2Client {
+  async list(siteName, params) {
+    return this.getList(this.sitePath(siteName, "webhooks"), params);
+  }
+  async get(siteName, id) {
+    return this.getOne(this.sitePath(siteName, "webhooks", id));
+  }
+  async create(siteName, data) {
+    return this.post(this.sitePath(siteName, "webhooks"), data);
+  }
+  async update(siteName, id, data) {
+    return this.patchOne(this.sitePath(siteName, "webhooks", id), data);
+  }
+  async del(siteName, id) {
+    return this.deleteOne(this.sitePath(siteName, "webhooks", id));
+  }
+};
+
+// src/v2/index.ts
+var PerspectApiV2Client = class {
+  http;
+  content;
+  products;
+  categories;
+  collections;
+  orders;
+  siteUsers;
+  newsletter;
+  contacts;
+  organizations;
+  sites;
+  apiKeys;
+  webhooks;
+  constructor(config) {
+    const baseUrl = config.baseUrl.replace(/\/+$/, "");
+    const v2BaseUrl = baseUrl.endsWith("/api/v2") ? baseUrl : `${baseUrl}/api/v2`;
+    this.http = new HttpClient({ ...config, baseUrl: v2BaseUrl });
+    const basePath = "";
+    this.content = new ContentV2Client(this.http, basePath);
+    this.products = new ProductsV2Client(this.http, basePath);
+    this.categories = new CategoriesV2Client(this.http, basePath);
+    this.collections = new CollectionsV2Client(this.http, basePath);
+    this.orders = new OrdersV2Client(this.http, basePath);
+    this.siteUsers = new SiteUsersV2Client(this.http, basePath);
+    this.newsletter = new NewsletterV2Client(this.http, basePath);
+    this.contacts = new ContactsV2Client(this.http, basePath);
+    this.organizations = new OrganizationsV2Client(this.http, basePath);
+    this.sites = new SitesV2Client(this.http, basePath);
+    this.apiKeys = new ApiKeysV2Client(this.http, basePath);
+    this.webhooks = new WebhooksV2Client(this.http, basePath);
+  }
+  /** Update the JWT token for authenticated requests. */
+  setAuth(jwt) {
+    this.http.setAuth(jwt);
+  }
+  /** Update the API key. */
+  setApiKey(apiKey) {
+    this.http.setApiKey(apiKey);
+  }
+  /** Clear authentication. */
+  clearAuth() {
+    this.http.clearAuth();
+  }
+};
+function createPerspectApiV2Client(config) {
+  return new PerspectApiV2Client(config);
+}
+
 // src/utils/image-transform.ts
 var DEFAULT_IMAGE_SIZES = {
   thumbnail: {
@@ -3879,6 +4315,8 @@ export {
   NoopCacheAdapter,
   OrganizationsClient,
   PerspectApiClient,
+  PerspectApiV2Client,
+  PerspectV2Error,
   ProductsClient,
   SiteUsersClient,
   SitesClient,
@@ -3887,6 +4325,7 @@ export {
   createApiError,
   createCheckoutSession,
   createPerspectApiClient,
+  createPerspectApiV2Client,
   perspect_api_client_default as default,
   generateResponsiveImageHtml,
   generateResponsiveUrls,

package/package.json

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

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

@@ -18,6 +18,8 @@ import type {
   VerifyOtpResponse,
   UpdateSiteUserRequest,
   SetProfileValueRequest,
+  CancelSubscriptionRequest,
+  CancelSubscriptionResponse,
   ApiResponse,
 } from '../types';
 
@@ -276,19 +278,21 @@ export class SiteUsersClient extends BaseClient {
   }
 
   /**
-   * Cancel a subscription (marks for cancellation at period end)
+   * Cancel a subscription.
    * @param siteName - The site name
    * @param id - Subscription ID
    * @param csrfToken - CSRF token (required)
+   * @param options - Cancellation mode/details
    */
   async cancelSubscription(
     siteName: string,
     id: string,
-    csrfToken?: string
-  ): Promise<ApiResponse<{ success: boolean; message: string }>> {
-    return this.create<Record<string, never>, { success: boolean; message: string }>(
+    csrfToken?: string,
+    options?: CancelSubscriptionRequest
+  ): Promise<ApiResponse<CancelSubscriptionResponse>> {
+    return this.create<CancelSubscriptionRequest, CancelSubscriptionResponse>(
       this.siteUserEndpoint(siteName, `/users/me/subscriptions/${encodeURIComponent(id)}/cancel`),
-      {},
+      options ?? {},
       csrfToken
     );
   }
@@ -596,15 +600,17 @@ export class SiteUsersClient extends BaseClient {
    * @param siteName - The site name
    * @param userId - User ID
    * @param subscriptionId - Subscription ID
+   * @param options - Cancellation mode/details
    */
   async cancelUserSubscription(
     siteName: string,
     userId: string,
-    subscriptionId: string
-  ): Promise<ApiResponse<{ success: boolean; message: string }>> {
-    return this.create<Record<string, never>, { success: boolean; message: string }>(
+    subscriptionId: string,
+    options?: CancelSubscriptionRequest
+  ): Promise<ApiResponse<CancelSubscriptionResponse>> {
+    return this.create<CancelSubscriptionRequest, CancelSubscriptionResponse>(
       this.siteUserEndpoint(siteName, `/users/${encodeURIComponent(userId)}/subscriptions/${encodeURIComponent(subscriptionId)}/cancel`),
-      {}
+      options ?? {}
     );
   }
 

package/src/index.ts

@@ -3,10 +3,14 @@
  * Cloudflare Workers compatible SDK for PerspectAPI
  */
 
-// Main client
+// Main client (v1)
 export { PerspectApiClient, createPerspectApiClient } from './perspect-api-client';
 export { default } from './perspect-api-client';
 
+// v2 client
+export { PerspectApiV2Client, createPerspectApiV2Client } from './v2';
+export { PerspectV2Error } from './v2/client/base-v2-client';
+
 // Individual clients (for advanced usage)
 export { AuthClient } from './client/auth-client';
 export { ContentClient } from './client/content-client';

package/src/types/index.ts

@@ -958,7 +958,7 @@ export interface SiteUserSubscription {
   provider_subscription_id?: string;
   plan_name?: string;
   plan_id?: string;
-  status: 'active' | 'past_due' | 'canceled' | 'paused' | 'trialing' | 'expired';
+  status: 'active' | 'past_due' | 'canceled' | 'paused' | 'trialing' | 'expired' | 'incomplete';
   amount?: number;
   currency?: string;
   billing_interval?: string;
@@ -981,11 +981,34 @@ export interface SiteUserOrder {
   currency: string;
   status: string;
   payment_status?: string;
+  fulfillment_status?: string;
   line_items: any[];
   created_at: string;
   completed_at?: string;
 }
 
+export type SubscriptionCancellationMode = 'immediate' | 'period_end' | 'scheduled';
+
+export interface CancelSubscriptionRequest {
+  mode?: SubscriptionCancellationMode;
+  cancel_at?: string;      // ISO timestamp
+  delay_days?: number;
+  delay_hours?: number;
+  delay_minutes?: number;
+}
+
+export interface CancelSubscriptionResponse {
+  success: boolean;
+  message: string;
+  cancellation?: {
+    mode: SubscriptionCancellationMode;
+    status: string;
+    cancel_at_period_end: boolean;
+    effective_at: string | null;
+    scheduled_cancel_at: string | null;
+  };
+}
+
 // Credits
 export interface CreditTransaction {
   id: number;

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

@@ -0,0 +1,21 @@
+/**
+ * v2 API Keys Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { V2ApiKey, V2PaginationParams, V2List, V2Deleted } from '../types';
+
+export class ApiKeysV2Client extends BaseV2Client {
+
+  async list(params?: V2PaginationParams): Promise<V2List<V2ApiKey>> {
+    return this.getList<V2ApiKey>('/api-keys', params);
+  }
+
+  async get(id: string): Promise<V2ApiKey> {
+    return this.getOne<V2ApiKey>(`/api-keys/${id}`);
+  }
+
+  async del(id: string): Promise<V2Deleted> {
+    return this.deleteOne(`/api-keys/${id}`);
+  }
+}