perspectapi-ts-sdk 3.7.0 → 5.0.0

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));
+  }
+}

package/src/v2/index.ts

@@ -0,0 +1,105 @@
+/**
+ * PerspectAPI v2 SDK Client
+ *
+ * Stripe-style API with consistent envelopes, prefixed IDs,
+ * cursor pagination, and snake_case responses.
+ *
+ * Usage:
+ *   import { PerspectApiV2Client } from 'perspectapi-ts-sdk/v2';
+ *   const client = new PerspectApiV2Client({ baseUrl: '...', apiKey: '...' });
+ *   const posts = await client.content.list('mysite', { type: 'post', limit: 10 });
+ */
+
+import { HttpClient } from '../utils/http-client';
+import type { PerspectApiConfig } from '../types';
+
+import { ContentV2Client } from './client/content-client';
+import { ProductsV2Client } from './client/products-client';
+import { CategoriesV2Client } from './client/categories-client';
+import { CollectionsV2Client } from './client/collections-client';
+import { OrdersV2Client } from './client/orders-client';
+import { SiteUsersV2Client } from './client/site-users-client';
+import { NewsletterV2Client } from './client/newsletter-client';
+import { ContactsV2Client } from './client/contacts-client';
+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';
+
+export class PerspectApiV2Client {
+  private http: HttpClient;
+
+  readonly content: ContentV2Client;
+  readonly products: ProductsV2Client;
+  readonly categories: CategoriesV2Client;
+  readonly collections: CollectionsV2Client;
+  readonly orders: OrdersV2Client;
+  readonly siteUsers: SiteUsersV2Client;
+  readonly newsletter: NewsletterV2Client;
+  readonly contacts: ContactsV2Client;
+  readonly organizations: OrganizationsV2Client;
+  readonly sites: SitesV2Client;
+  readonly apiKeys: ApiKeysV2Client;
+  readonly webhooks: WebhooksV2Client;
+
+  constructor(config: PerspectApiConfig) {
+    // Ensure base URL points to /api/v2
+    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: string): void {
+    this.http.setAuth(jwt);
+  }
+
+  /** Update the API key. */
+  setApiKey(apiKey: string): void {
+    this.http.setApiKey(apiKey);
+  }
+
+  /** Clear authentication. */
+  clearAuth(): void {
+    this.http.clearAuth();
+  }
+}
+
+export function createPerspectApiV2Client(config: PerspectApiConfig): PerspectApiV2Client {
+  return new PerspectApiV2Client(config);
+}
+
+// Re-export all types
+export type * from './types';
+
+// Re-export client classes
+export { BaseV2Client, PerspectV2Error } from './client/base-v2-client';
+export { ContentV2Client } from './client/content-client';
+export { ProductsV2Client } from './client/products-client';
+export { CategoriesV2Client } from './client/categories-client';
+export { CollectionsV2Client } from './client/collections-client';
+export { OrdersV2Client } from './client/orders-client';
+export { SiteUsersV2Client } from './client/site-users-client';
+export { NewsletterV2Client } from './client/newsletter-client';
+export { ContactsV2Client } from './client/contacts-client';
+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';