perspectapi-ts-sdk 4.1.0 → 5.0.0

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';

package/src/v2/types.ts

@@ -0,0 +1,395 @@
+/**
+ * v2 SDK Types — matches the API wire format exactly (snake_case).
+ *
+ * These types reflect the actual JSON returned by /api/v2/ endpoints.
+ * No transformation layer is needed in the SDK.
+ */
+
+// --- Base types ---
+
+export interface V2Object {
+  object: string;
+  id: string;
+}
+
+export interface V2List<T> {
+  object: "list";
+  data: T[];
+  has_more: boolean;
+  url: string;
+}
+
+export interface V2Deleted {
+  object: string;
+  id: string;
+  deleted: true;
+}
+
+export interface V2Error {
+  error: {
+    type: V2ErrorType;
+    code: string;
+    message: string;
+    param?: string;
+  };
+}
+
+export type V2ErrorType =
+  | "invalid_request_error"
+  | "authentication_error"
+  | "permission_error"
+  | "not_found_error"
+  | "rate_limit_error"
+  | "api_error";
+
+// --- Pagination ---
+
+export interface V2PaginationParams {
+  limit?: number;
+  starting_after?: string;
+  ending_before?: string;
+}
+
+// --- Content ---
+
+export interface V2Content extends V2Object {
+  object: "content";
+  title: string;
+  content: string;
+  markdown: string | null;
+  slug: string;
+  slug_prefix: string | null;
+  type: "post" | "page" | "block";
+  status: "draft" | "publish" | "private" | "trash" | "scheduled";
+  author: string | null;
+  custom: Record<string, unknown> | null;
+  featured_image?: string | null;
+  scheduled_at: string | null;
+  published_at: string;
+  updated_at: string;
+}
+
+export interface V2ContentCreateParams {
+  title: string;
+  content: string;
+  markdown?: string;
+  custom?: Record<string, unknown>;
+  slug?: string;
+  slug_prefix?: string;
+  published_at?: string;
+  scheduled_at?: string | null;
+  status?: "draft" | "publish" | "private" | "trash" | "scheduled";
+  type?: "post" | "page" | "block";
+}
+
+export interface V2ContentUpdateParams extends Partial<V2ContentCreateParams> {}
+
+export interface V2ContentListParams extends V2PaginationParams {
+  status?: "draft" | "publish" | "private" | "trash" | "scheduled";
+  type?: "post" | "page" | "block";
+  search?: string;
+  slug_prefix?: string;
+}
+
+// --- Products ---
+
+export interface V2Product extends V2Object {
+  object: "product";
+  name: string;
+  description: string | null;
+  excerpt: string | null;
+  meta_description: string | null;
+  price: number;
+  unit_amount: number;
+  currency: string;
+  sku: string | null;
+  slug: string | null;
+  slug_prefix: string | null;
+  published: boolean;
+  stock_quantity: number | null;
+  custom: Record<string, unknown> | null;
+  recurring: { interval: string; interval_count?: number } | null;
+  tax_behavior: "inclusive" | "exclusive" | "unspecified" | null;
+  category_id: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2ProductCreateParams {
+  name: string;
+  description?: string;
+  excerpt?: string;
+  meta_description?: string;
+  category_id?: string;
+  price: number;
+  unit_amount: number;
+  currency?: string;
+  sku?: string;
+  custom?: Record<string, unknown>;
+  slug?: string;
+  slug_prefix?: string;
+  published?: boolean;
+  stock_quantity?: number | null;
+  recurring?: { interval: "day" | "week" | "month" | "year"; interval_count?: number };
+  tax_behavior?: "inclusive" | "exclusive" | "unspecified";
+  attachment_ids?: number[];
+}
+
+export interface V2ProductUpdateParams extends Partial<V2ProductCreateParams> {}
+
+export interface V2ProductListParams extends V2PaginationParams {
+  published?: boolean;
+  category_id?: string;
+  search?: string;
+  slug_prefix?: string;
+}
+
+// --- Categories ---
+
+export interface V2Category extends V2Object {
+  object: "category";
+  name: string;
+  description: string | null;
+  slug: string | null;
+  slug_prefix: string | null;
+  parent_id: string | null;
+  type: "post" | "product" | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2CategoryCreateParams {
+  name: string;
+  description?: string;
+  slug?: string;
+  slug_prefix?: string;
+  parent_id?: string;
+  type?: "post" | "product";
+}
+
+export interface V2CategoryUpdateParams extends Partial<V2CategoryCreateParams> {}
+
+// --- Collections ---
+
+export interface V2Collection extends V2Object {
+  object: "collection";
+  name: string;
+  description: string | null;
+  available_from: string | null;
+  available_until: string | null;
+  published: boolean;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2CollectionItem extends V2Object {
+  object: "collection_item";
+  collection_id: string;
+  product_id: string;
+  max_quantity: number | null;
+  position: number;
+}
+
+export interface V2CollectionCreateParams {
+  name: string;
+  description?: string | null;
+  available_from?: string | null;
+  available_until?: string | null;
+  published?: boolean;
+}
+
+export interface V2CollectionUpdateParams extends Partial<V2CollectionCreateParams> {}
+
+// --- Orders (Checkout Sessions) ---
+
+export interface V2Order extends V2Object {
+  object: "checkout_session";
+  customer_email: string;
+  customer_name: string | null;
+  customer_phone: string | null;
+  customer_details: Record<string, unknown> | null;
+  shipping_details: Record<string, unknown> | null;
+  order_id: string | null;
+  line_items: unknown[] | null;
+  amount_total: number;
+  currency: string;
+  tax_summary: Record<string, unknown> | null;
+  status: string;
+  payment_status: string | null;
+  fulfillment_status: string | null;
+  tracking_number: string | null;
+  notes: string | null;
+  live_mode: boolean;
+  metadata: Record<string, unknown> | null;
+  created_at: string;
+  completed_at: string | null;
+  expires_at: string | null;
+}
+
+export interface V2OrderListParams extends V2PaginationParams {
+  status?: string;
+  customer_email?: string;
+  date_from?: string;
+  date_to?: string;
+}
+
+// --- Site Users ---
+
+export interface V2SiteUser extends V2Object {
+  object: "site_user";
+  email: string;
+  email_verified: boolean;
+  first_name: string | null;
+  last_name: string | null;
+  avatar_url: string | null;
+  status: string;
+  waitlist: boolean;
+  metadata: Record<string, unknown> | null;
+  created_at: string | null;
+  updated_at: string | null;
+  last_login_at: string | null;
+}
+
+export interface V2SiteUserUpdateParams {
+  first_name?: string;
+  last_name?: string;
+  avatar_url?: string;
+  status?: "active" | "suspended" | "pending_verification";
+  metadata?: Record<string, unknown>;
+}
+
+export interface V2SiteUserListParams extends V2PaginationParams {
+  status?: "active" | "suspended" | "pending_verification";
+  email?: string;
+}
+
+// --- Newsletter ---
+
+export interface V2NewsletterSubscription extends V2Object {
+  object: "newsletter_subscription";
+  email: string;
+  name: string | null;
+  status: string;
+  double_opt_in: boolean;
+  confirmed_at: string | null;
+  source: string | null;
+  frequency: string | null;
+  topics: string[] | null;
+  language: string | null;
+  tags: string[] | null;
+  custom_fields: Record<string, unknown> | null;
+  unsubscribed_at: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2NewsletterList extends V2Object {
+  object: "newsletter_list";
+  name: string;
+  slug: string;
+  description: string | null;
+  is_default: boolean;
+  subscriber_count: number;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2NewsletterCampaign extends V2Object {
+  object: "newsletter_campaign";
+  name: string;
+  slug: string | null;
+  subject: string;
+  preview_text: string | null;
+  status: string;
+  sent_at: string | null;
+  completed_at: string | null;
+  total_recipients: number;
+  sent_count: number;
+  opened_count: number;
+  clicked_count: number;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- Contact ---
+
+export interface V2ContactSubmission extends V2Object {
+  object: "contact_submission";
+  name: string | null;
+  first_name: string | null;
+  last_name: string | null;
+  email: string;
+  subject: string | null;
+  message: string;
+  phone: string | null;
+  company: string | null;
+  status: string;
+  metadata: Record<string, unknown> | null;
+  created_at: string | null;
+  processed_at: string | null;
+}
+
+// --- Organizations ---
+
+export interface V2Organization extends V2Object {
+  object: "organization";
+  name: string;
+  slug: string | null;
+  endpoint_status: string | null;
+  endpoint_url: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- Sites ---
+
+export interface V2Site extends V2Object {
+  object: "site";
+  name: string;
+  title: string | null;
+  description: string | null;
+  domain: string | null;
+  custom_domain: string | null;
+  organization_id: string | null;
+  tax_enabled: boolean;
+  lifecycle_status: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- API Keys ---
+
+export interface V2ApiKey extends V2Object {
+  object: "api_key";
+  name: string;
+  description: string | null;
+  organization_id: string | null;
+  site_name: string | null;
+  permissions: string[] | null;
+  is_active: boolean;
+  expires_at: string | null;
+  last_used_at: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+// --- Webhooks ---
+
+export interface V2Webhook extends V2Object {
+  object: "webhook";
+  url: string;
+  description: string | null;
+  events: string[] | null;
+  is_active: boolean;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+export interface V2WebhookCreateParams {
+  url: string;
+  description?: string;
+  events?: string[];
+  is_active?: boolean;
+}
+
+export interface V2WebhookUpdateParams extends Partial<V2WebhookCreateParams> {}