perspectapi-ts-sdk 4.1.0 → 5.0.0

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

@@ -0,0 +1,146 @@
+/**
+ * v2 Base Client — cursor pagination, expand support, typed errors.
+ */
+
+import { HttpClient } from '../../utils/http-client';
+import type { V2List, V2Error, V2Deleted } from '../types';
+
+export class PerspectV2Error extends Error {
+  readonly type: string;
+  readonly code: string;
+  readonly param?: string;
+  readonly status: number;
+
+  constructor(error: V2Error['error'], status: number) {
+    super(error.message);
+    this.name = 'PerspectV2Error';
+    this.type = error.type;
+    this.code = error.code;
+    this.param = error.param;
+    this.status = status;
+  }
+}
+
+export abstract class BaseV2Client {
+  protected http: HttpClient;
+  protected basePath: string;
+
+  constructor(http: HttpClient, basePath: string) {
+    this.http = http;
+    this.basePath = basePath;
+  }
+
+  protected buildPath(endpoint: string): string {
+    const clean = endpoint.replace(/^\//, '');
+    return clean ? `${this.basePath}/${clean}` : this.basePath;
+  }
+
+  protected sitePath(siteName: string, resource: string, suffix = ''): string {
+    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
+  private toParams(params?: any): Record<string, string> | undefined {
+    if (!params) return undefined;
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null) out[k] = String(v);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  }
+
+  /** GET a single resource. */
+  protected async getOne<T>(path: string, params?: object): Promise<T> {
+    const response = await this.http.get<T>(path, this.toParams(params));
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** GET a list of resources with cursor pagination. */
+  protected async getList<T>(
+    path: string,
+    params?: object,
+  ): Promise<V2List<T>> {
+    const response = await this.http.get<V2List<T>>(path, this.toParams(params));
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** POST to create a resource. */
+  protected async post<T>(path: string, body?: unknown): Promise<T> {
+    const response = await this.http.post<T>(path, body);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** PATCH to update a resource. */
+  protected async patchOne<T>(path: string, body?: unknown): Promise<T> {
+    const response = await this.http.patch<T>(path, body);
+    if (!response.success) {
+      throw this.toError(response);
+    }
+    return response.data!;
+  }
+
+  /** DELETE a resource. */
+  protected async deleteOne(path: string): Promise<V2Deleted> {
+    const response = await this.http.delete<V2Deleted>(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)) { ... }
+   */
+  protected async *listAutoPaginate<T extends { id: string }>(
+    path: string,
+    params?: object,
+  ): AsyncGenerator<T, void, unknown> {
+    let startingAfter: string | undefined;
+    let hasMore = true;
+
+    while (hasMore) {
+      const queryParams: Record<string, unknown> = { ...(params as Record<string, unknown>) };
+      if (startingAfter) queryParams.starting_after = startingAfter;
+
+      const page = await this.getList<T>(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;
+      }
+    }
+  }
+
+  private toError(response: { data?: unknown; error?: unknown; message?: string }): PerspectV2Error {
+    const data = response.data as Record<string, unknown> | undefined;
+    const errorObj = (data?.error ?? response.error) as V2Error['error'] | undefined;
+    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,
+    );
+  }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * v2 Categories Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2Category, V2CategoryCreateParams, V2CategoryUpdateParams,
+  V2PaginationParams, V2List, V2Deleted,
+} from '../types';
+
+export class CategoriesV2Client extends BaseV2Client {
+
+  async list(siteName: string, params?: V2PaginationParams & { type?: string }): Promise<V2List<V2Category>> {
+    return this.getList<V2Category>(this.sitePath(siteName, 'categories'), params);
+  }
+
+  async get(siteName: string, id: string): Promise<V2Category> {
+    return this.getOne<V2Category>(this.sitePath(siteName, 'categories', id));
+  }
+
+  async create(siteName: string, data: V2CategoryCreateParams): Promise<V2Category> {
+    return this.post<V2Category>(this.sitePath(siteName, 'categories'), data);
+  }
+
+  async update(siteName: string, id: string, data: V2CategoryUpdateParams): Promise<V2Category> {
+    return this.patchOne<V2Category>(this.sitePath(siteName, 'categories', id), data);
+  }
+
+  async del(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(this.sitePath(siteName, 'categories', id));
+  }
+}

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

@@ -0,0 +1,64 @@
+/**
+ * v2 Collections Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2Collection, V2CollectionItem, V2CollectionCreateParams,
+  V2CollectionUpdateParams, V2PaginationParams, V2List, V2Deleted,
+} from '../types';
+
+export class CollectionsV2Client extends BaseV2Client {
+
+  async list(siteName: string, params?: V2PaginationParams): Promise<V2List<V2Collection>> {
+    return this.getList<V2Collection>(this.sitePath(siteName, 'collections'), params);
+  }
+
+  async getCurrent(siteName: string): Promise<V2Collection | null> {
+    const result = await this.getOne<{ object: string; data: V2Collection | null }>(
+      this.sitePath(siteName, 'collections', 'current'),
+    );
+    return (result as unknown as V2Collection) ?? null;
+  }
+
+  async get(siteName: string, id: string): Promise<V2Collection> {
+    return this.getOne<V2Collection>(this.sitePath(siteName, 'collections', id));
+  }
+
+  async create(siteName: string, data: V2CollectionCreateParams): Promise<V2Collection> {
+    return this.post<V2Collection>(this.sitePath(siteName, 'collections'), data);
+  }
+
+  async update(siteName: string, id: string, data: V2CollectionUpdateParams): Promise<V2Collection> {
+    return this.patchOne<V2Collection>(this.sitePath(siteName, 'collections', id), data);
+  }
+
+  async del(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(this.sitePath(siteName, 'collections', id));
+  }
+
+  // --- Items ---
+
+  async listItems(siteName: string, collectionId: string): Promise<V2List<V2CollectionItem>> {
+    return this.getList<V2CollectionItem>(
+      this.sitePath(siteName, 'collections', `${collectionId}/items`),
+    );
+  }
+
+  async addItem(
+    siteName: string,
+    collectionId: string,
+    data: { product_id: string; max_quantity?: number | null; position?: number },
+  ): Promise<V2CollectionItem> {
+    return this.post<V2CollectionItem>(
+      this.sitePath(siteName, 'collections', `${collectionId}/items`),
+      data,
+    );
+  }
+
+  async removeItem(siteName: string, collectionId: string, itemId: string): Promise<V2Deleted> {
+    return this.deleteOne(
+      this.sitePath(siteName, 'collections', `${collectionId}/items/${itemId}`),
+    );
+  }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * v2 Contacts Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { V2ContactSubmission, V2PaginationParams, V2List } from '../types';
+
+export class ContactsV2Client extends BaseV2Client {
+
+  async submit(
+    siteName: string,
+    data: {
+      email: string;
+      message: string;
+      name?: string;
+      first_name?: string;
+      last_name?: string;
+      subject?: string;
+      phone?: string;
+      company?: string;
+      metadata?: Record<string, unknown>;
+    },
+  ): Promise<V2ContactSubmission> {
+    return this.post<V2ContactSubmission>(this.sitePath(siteName, 'contacts'), data);
+  }
+
+  async list(
+    siteName: string,
+    params?: V2PaginationParams & { status?: string },
+  ): Promise<V2List<V2ContactSubmission>> {
+    return this.getList<V2ContactSubmission>(this.sitePath(siteName, 'contacts'), params);
+  }
+
+  async get(siteName: string, id: string): Promise<V2ContactSubmission> {
+    return this.getOne<V2ContactSubmission>(this.sitePath(siteName, 'contacts', id));
+  }
+}

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

@@ -0,0 +1,44 @@
+/**
+ * v2 Content Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2Content, V2ContentCreateParams, V2ContentUpdateParams,
+  V2ContentListParams, V2List, V2Deleted,
+} from '../types';
+
+export class ContentV2Client extends BaseV2Client {
+
+  async list(siteName: string, params?: V2ContentListParams): Promise<V2List<V2Content>> {
+    return this.getList<V2Content>(this.sitePath(siteName, 'content'), params);
+  }
+
+  async *listAutoPaginated(siteName: string, params?: Omit<V2ContentListParams, 'starting_after' | 'ending_before'>) {
+    yield* this.listAutoPaginate<V2Content>(this.sitePath(siteName, 'content'), params);
+  }
+
+  async get(siteName: string, idOrSlug: string): Promise<V2Content> {
+    return this.getOne<V2Content>(this.sitePath(siteName, 'content', idOrSlug));
+  }
+
+  async create(siteName: string, data: V2ContentCreateParams): Promise<V2Content> {
+    return this.post<V2Content>(this.sitePath(siteName, 'content'), data);
+  }
+
+  async update(siteName: string, id: string, data: V2ContentUpdateParams): Promise<V2Content> {
+    return this.patchOne<V2Content>(this.sitePath(siteName, 'content', id), data);
+  }
+
+  async del(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(this.sitePath(siteName, 'content', id));
+  }
+
+  async publish(siteName: string, id: string): Promise<V2Content> {
+    return this.post<V2Content>(this.sitePath(siteName, 'content', `${id}/publish`));
+  }
+
+  async unpublish(siteName: string, id: string): Promise<V2Content> {
+    return this.post<V2Content>(this.sitePath(siteName, 'content', `${id}/unpublish`));
+  }
+}

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

@@ -0,0 +1,95 @@
+/**
+ * v2 Newsletter Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2NewsletterSubscription, V2NewsletterList, V2NewsletterCampaign,
+  V2PaginationParams, V2List,
+} from '../types';
+
+export class NewsletterV2Client extends BaseV2Client {
+
+  // --- Subscribe / Unsubscribe ---
+
+  async subscribe(
+    siteName: string,
+    data: {
+      email: string;
+      name?: string;
+      list_ids?: string[];
+      double_opt_in?: boolean;
+      source?: string;
+      source_url?: string;
+      frequency?: 'instant' | 'daily' | 'weekly' | 'monthly';
+      topics?: string[];
+      language?: string;
+      metadata?: Record<string, unknown>;
+    },
+  ): Promise<V2NewsletterSubscription> {
+    return this.post<V2NewsletterSubscription>(
+      this.sitePath(siteName, 'newsletter', 'subscribe'),
+      data,
+    );
+  }
+
+  async confirm(siteName: string, token: string): Promise<V2NewsletterSubscription> {
+    return this.getOne<V2NewsletterSubscription>(
+      this.sitePath(siteName, 'newsletter', `confirm/${token}`),
+    );
+  }
+
+  async unsubscribe(
+    siteName: string,
+    data: { token?: string; email?: string; reason?: string },
+  ): Promise<V2NewsletterSubscription> {
+    return this.post<V2NewsletterSubscription>(
+      this.sitePath(siteName, 'newsletter', 'unsubscribe'),
+      data,
+    );
+  }
+
+  // --- Subscriptions (admin) ---
+
+  async listSubscriptions(
+    siteName: string,
+    params?: V2PaginationParams & { status?: string },
+  ): Promise<V2List<V2NewsletterSubscription>> {
+    return this.getList<V2NewsletterSubscription>(
+      this.sitePath(siteName, 'newsletter', 'subscriptions'),
+      params,
+    );
+  }
+
+  async getSubscription(siteName: string, id: string): Promise<V2NewsletterSubscription> {
+    return this.getOne<V2NewsletterSubscription>(
+      this.sitePath(siteName, 'newsletter', `subscriptions/${id}`),
+    );
+  }
+
+  // --- Lists ---
+
+  async listLists(siteName: string): Promise<V2List<V2NewsletterList>> {
+    return this.getList<V2NewsletterList>(
+      this.sitePath(siteName, 'newsletter', 'lists'),
+    );
+  }
+
+  // --- Campaigns ---
+
+  async listCampaigns(
+    siteName: string,
+    params?: V2PaginationParams & { status?: string },
+  ): Promise<V2List<V2NewsletterCampaign>> {
+    return this.getList<V2NewsletterCampaign>(
+      this.sitePath(siteName, 'newsletter', 'campaigns'),
+      params,
+    );
+  }
+
+  async getCampaign(siteName: string, idOrSlug: string): Promise<V2NewsletterCampaign> {
+    return this.getOne<V2NewsletterCampaign>(
+      this.sitePath(siteName, 'newsletter', `campaigns/${idOrSlug}`),
+    );
+  }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * v2 Orders Client (checkout sessions)
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { V2Order, V2OrderListParams, V2List } from '../types';
+
+export class OrdersV2Client extends BaseV2Client {
+
+  async list(siteName: string, params?: V2OrderListParams): Promise<V2List<V2Order>> {
+    return this.getList<V2Order>(this.sitePath(siteName, 'orders'), params);
+  }
+
+  async *listAutoPaginated(siteName: string, params?: Omit<V2OrderListParams, 'starting_after' | 'ending_before'>) {
+    yield* this.listAutoPaginate<V2Order>(this.sitePath(siteName, 'orders'), params);
+  }
+
+  async get(siteName: string, id: string): Promise<V2Order> {
+    return this.getOne<V2Order>(this.sitePath(siteName, 'orders', id));
+  }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * v2 Organizations Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { V2Organization, V2List } from '../types';
+
+export class OrganizationsV2Client extends BaseV2Client {
+
+  async list(): Promise<V2List<V2Organization>> {
+    return this.getList<V2Organization>('/organizations');
+  }
+
+  async get(id: string): Promise<V2Organization> {
+    return this.getOne<V2Organization>(`/organizations/${id}`);
+  }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * v2 Products Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2Product, V2ProductCreateParams, V2ProductUpdateParams,
+  V2ProductListParams, V2List, V2Deleted,
+} from '../types';
+
+export class ProductsV2Client extends BaseV2Client {
+
+  async list(siteName: string, params?: V2ProductListParams): Promise<V2List<V2Product>> {
+    return this.getList<V2Product>(this.sitePath(siteName, 'products'), params);
+  }
+
+  async *listAutoPaginated(siteName: string, params?: Omit<V2ProductListParams, 'starting_after' | 'ending_before'>) {
+    yield* this.listAutoPaginate<V2Product>(this.sitePath(siteName, 'products'), params);
+  }
+
+  async get(siteName: string, idOrSlug: string): Promise<V2Product> {
+    return this.getOne<V2Product>(this.sitePath(siteName, 'products', idOrSlug));
+  }
+
+  async create(siteName: string, data: V2ProductCreateParams): Promise<V2Product> {
+    return this.post<V2Product>(this.sitePath(siteName, 'products'), data);
+  }
+
+  async update(siteName: string, id: string, data: V2ProductUpdateParams): Promise<V2Product> {
+    return this.patchOne<V2Product>(this.sitePath(siteName, 'products', id), data);
+  }
+
+  async del(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(this.sitePath(siteName, 'products', id));
+  }
+}

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

@@ -0,0 +1,53 @@
+/**
+ * v2 Site Users Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { V2SiteUser, V2SiteUserUpdateParams, V2SiteUserListParams, V2List } from '../types';
+
+export interface V2OtpRequestResponse {
+  object: 'otp_request';
+  email: string;
+  expires_in: number;
+}
+
+export interface V2OtpVerifyResponse extends V2SiteUser {
+  token: string;
+}
+
+export class SiteUsersV2Client extends BaseV2Client {
+
+  // --- OTP Auth ---
+
+  async requestOtp(
+    siteName: string,
+    data: { email: string; waitlist?: boolean; metadata?: Record<string, unknown> },
+  ): Promise<V2OtpRequestResponse> {
+    return this.post<V2OtpRequestResponse>(this.sitePath(siteName, 'users', 'request-otp'), data);
+  }
+
+  async verifyOtp(
+    siteName: string,
+    data: { email: string; code: string },
+  ): Promise<V2OtpVerifyResponse> {
+    return this.post<V2OtpVerifyResponse>(this.sitePath(siteName, 'users', 'verify-otp'), data);
+  }
+
+  // --- Admin ---
+
+  async list(siteName: string, params?: V2SiteUserListParams): Promise<V2List<V2SiteUser>> {
+    return this.getList<V2SiteUser>(this.sitePath(siteName, 'users'), params);
+  }
+
+  async *listAutoPaginated(siteName: string, params?: Omit<V2SiteUserListParams, 'starting_after' | 'ending_before'>) {
+    yield* this.listAutoPaginate<V2SiteUser>(this.sitePath(siteName, 'users'), params);
+  }
+
+  async get(siteName: string, id: string): Promise<V2SiteUser> {
+    return this.getOne<V2SiteUser>(this.sitePath(siteName, 'users', id));
+  }
+
+  async update(siteName: string, id: string, data: V2SiteUserUpdateParams): Promise<V2SiteUser> {
+    return this.patchOne<V2SiteUser>(this.sitePath(siteName, 'users', id), data);
+  }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * v2 Sites Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type { V2Site, V2PaginationParams, V2List } from '../types';
+
+export class SitesV2Client extends BaseV2Client {
+
+  async list(params?: V2PaginationParams): Promise<V2List<V2Site>> {
+    return this.getList<V2Site>('/sites', params);
+  }
+
+  async get(name: string): Promise<V2Site> {
+    return this.getOne<V2Site>(`/sites/${encodeURIComponent(name)}`);
+  }
+}

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

@@ -0,0 +1,32 @@
+/**
+ * v2 Webhooks Client
+ */
+
+import { BaseV2Client } from './base-v2-client';
+import type {
+  V2Webhook, V2WebhookCreateParams, V2WebhookUpdateParams,
+  V2PaginationParams, V2List, V2Deleted,
+} from '../types';
+
+export class WebhooksV2Client extends BaseV2Client {
+
+  async list(siteName: string, params?: V2PaginationParams): Promise<V2List<V2Webhook>> {
+    return this.getList<V2Webhook>(this.sitePath(siteName, 'webhooks'), params);
+  }
+
+  async get(siteName: string, id: string): Promise<V2Webhook> {
+    return this.getOne<V2Webhook>(this.sitePath(siteName, 'webhooks', id));
+  }
+
+  async create(siteName: string, data: V2WebhookCreateParams): Promise<V2Webhook> {
+    return this.post<V2Webhook>(this.sitePath(siteName, 'webhooks'), data);
+  }
+
+  async update(siteName: string, id: string, data: V2WebhookUpdateParams): Promise<V2Webhook> {
+    return this.patchOne<V2Webhook>(this.sitePath(siteName, 'webhooks', id), data);
+  }
+
+  async del(siteName: string, id: string): Promise<V2Deleted> {
+    return this.deleteOne(this.sitePath(siteName, 'webhooks', id));
+  }
+}