perspectapi-ts-sdk 1.1.1

package/src/perspect-api-client.ts

@@ -0,0 +1,179 @@
+/**
+ * Main PerspectAPI SDK Client
+ * Cloudflare Workers compatible TypeScript SDK
+ */
+
+import { HttpClient } from './utils/http-client';
+import { AuthClient } from './client/auth-client';
+import { ContentClient } from './client/content-client';
+import { ApiKeysClient } from './client/api-keys-client';
+import { OrganizationsClient } from './client/organizations-client';
+import { SitesClient } from './client/sites-client';
+import { ProductsClient } from './client/products-client';
+import { CategoriesClient } from './client/categories-client';
+import { WebhooksClient } from './client/webhooks-client';
+import { CheckoutClient } from './client/checkout-client';
+import { ContactClient } from './client/contact-client';
+
+import type { PerspectApiConfig, ApiResponse } from './types';
+
+export class PerspectApiClient {
+  private http: HttpClient;
+  
+  // Service clients
+  public readonly auth: AuthClient;
+  public readonly content: ContentClient;
+  public readonly apiKeys: ApiKeysClient;
+  public readonly organizations: OrganizationsClient;
+  public readonly sites: SitesClient;
+  public readonly products: ProductsClient;
+  public readonly categories: CategoriesClient;
+  public readonly webhooks: WebhooksClient;
+  public readonly checkout: CheckoutClient;
+  public readonly contact: ContactClient;
+
+  constructor(config: PerspectApiConfig) {
+    // Validate required configuration
+    if (!config.baseUrl) {
+      throw new Error('baseUrl is required in PerspectApiConfig');
+    }
+
+    // Initialize HTTP client
+    this.http = new HttpClient(config);
+
+    // Initialize service clients
+    this.auth = new AuthClient(this.http);
+    this.content = new ContentClient(this.http);
+    this.apiKeys = new ApiKeysClient(this.http);
+    this.organizations = new OrganizationsClient(this.http);
+    this.sites = new SitesClient(this.http);
+    this.products = new ProductsClient(this.http);
+    this.categories = new CategoriesClient(this.http);
+    this.webhooks = new WebhooksClient(this.http);
+    this.checkout = new CheckoutClient(this.http);
+    this.contact = new ContactClient(this.http);
+  }
+
+  /**
+   * Update authentication token
+   */
+  setAuth(jwt: string): void {
+    this.http.setAuth(jwt);
+  }
+
+  /**
+   * Update API key
+   */
+  setApiKey(apiKey: string): void {
+    this.http.setApiKey(apiKey);
+  }
+
+  /**
+   * Clear authentication
+   */
+  clearAuth(): void {
+    this.http.clearAuth();
+  }
+
+  /**
+   * Health check endpoint
+   */
+  async health(): Promise<ApiResponse<{
+    status: string;
+    timestamp: string;
+    version?: string;
+    uptime?: number;
+  }>> {
+    return this.http.get('/health');
+  }
+
+  /**
+   * Get API version info
+   */
+  async getVersion(): Promise<ApiResponse<{
+    version: string;
+    buildDate: string;
+    gitCommit?: string;
+  }>> {
+    return this.http.get('/api/v1/version');
+  }
+
+  /**
+   * Get API status and statistics
+   */
+  async getStatus(): Promise<ApiResponse<{
+    status: string;
+    database: {
+      connected: boolean;
+      latency?: number;
+    };
+    cache: {
+      connected: boolean;
+      hitRate?: number;
+    };
+    queues: {
+      connected: boolean;
+      pendingJobs?: number;
+    };
+    uptime: number;
+    requestsPerMinute: number;
+  }>> {
+    return this.http.get('/api/v1/status');
+  }
+
+  /**
+   * Test API connectivity and authentication
+   */
+  async test(): Promise<ApiResponse<{
+    success: boolean;
+    authenticated: boolean;
+    user?: {
+      id: string;
+      email: string;
+    };
+    permissions?: string[];
+    timestamp: string;
+  }>> {
+    return this.http.get('/api/v1/test');
+  }
+
+  /**
+   * Get CSRF token (for form submissions)
+   * @param siteName - Optional site name for site-specific token (recommended for development)
+   */
+  async getCsrfToken(siteName?: string): Promise<ApiResponse<{ 
+    token?: string;
+    csrf_token?: string;
+    site_id?: string;
+    site_name?: string;
+  }>> {
+    if (siteName) {
+      // Use site-specific endpoint (works from localhost/development)
+      return this.http.get(`/api/v1/csrf/token/${siteName}`);
+    }
+    // Use host-based endpoint (requires correct Host header)
+    return this.http.get('/api/v1/csrf/token');
+  }
+
+  /**
+   * Validate CSRF token
+   */
+  async validateCsrfToken(token: string): Promise<ApiResponse<{
+    valid: boolean;
+    message?: string;
+  }>> {
+    return this.http.post('/api/v1/csrf/validate', { token });
+  }
+}
+
+/**
+ * Create a new PerspectAPI client instance
+ */
+export function createPerspectApiClient(config: PerspectApiConfig): PerspectApiClient {
+  return new PerspectApiClient(config);
+}
+
+/**
+ * Default export for convenience
+ */
+export default PerspectApiClient;

package/src/types/index.ts

@@ -0,0 +1,399 @@
+/**
+ * Core types and interfaces for PerspectAPI SDK
+ */
+
+// Base API Response
+export interface ApiResponse<T = any> {
+  data?: T;
+  message?: string;
+  error?: string;
+  success?: boolean;
+}
+
+// Pagination
+export interface PaginationParams {
+  page?: number;
+  limit?: number;
+  offset?: number;
+}
+
+export interface PaginatedResponse<T> extends ApiResponse<T[]> {
+  pagination?: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+  };
+}
+
+// Authentication
+export interface SignUpRequest {
+  email: string;
+  password: string;
+  firstName?: string;
+  lastName?: string;
+}
+
+export interface SignInRequest {
+  email: string;
+  password: string;
+}
+
+export interface AuthResponse {
+  message: string;
+  user?: User;
+  token?: string;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  createdAt?: string;
+  isActive?: boolean;
+}
+
+// API Keys
+export interface ApiKey {
+  id: string;
+  name: string;
+  description?: string;
+  permissions: string[];
+  organizationId?: number;
+  siteName?: string;
+  isActive: boolean;
+  createdAt: string;
+  expiresAt?: string;
+  lastUsedAt?: string;
+}
+
+export interface CreateApiKeyRequest {
+  name: string;
+  description?: string;
+  permissions: string[];
+  organizationId?: number;
+  siteName?: string;
+  expiresAt?: string;
+}
+
+export interface UpdateApiKeyRequest {
+  name?: string;
+  description?: string;
+  permissions?: string[];
+  isActive?: boolean;
+}
+
+// Organizations
+export interface Organization {
+  id: number;
+  name: string;
+  description?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateOrganizationRequest {
+  name: string;
+  description?: string;
+}
+
+// Sites
+export interface Site {
+  id: number;
+  name: string;
+  domain?: string;
+  managementDomain?: string;
+  description?: string;
+  organizationId: number;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateSiteRequest {
+  name: string;
+  domain?: string;
+  managementDomain?: string;
+  description?: string;
+  organizationId: number;
+}
+
+// Content Management
+export type ContentStatus = 'draft' | 'publish' | 'private' | 'trash';
+export type ContentType = 'post' | 'page';
+
+export interface Content {
+  id: number;
+  pageTitle: string;
+  pageContent: string;
+  contentMarkdown?: string;
+  custom?: Record<string, any>;
+  slug?: string;
+  pageStatus: ContentStatus;
+  pageType: ContentType;
+  userId?: number;
+  organizationId?: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateContentRequest {
+  page_title: string;
+  page_content: string;
+  content_markdown?: string;
+  custom?: Record<string, any>;
+  slug?: string;
+  page_status?: ContentStatus;
+  page_type?: ContentType;
+}
+
+export interface UpdateContentRequest extends Partial<CreateContentRequest> {}
+
+export interface ContentQueryParams extends PaginationParams {
+  page_status?: ContentStatus;
+  page_type?: ContentType;
+  search?: string;
+  user_id?: number;
+}
+
+// Categories
+export interface Category {
+  id: number;
+  name: string;
+  slug: string;
+  description?: string;
+  parentId?: number;
+  organizationId?: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateCategoryRequest {
+  name: string;
+  slug?: string;
+  description?: string;
+  parentId?: number;
+}
+
+// Products
+export interface MediaItem {
+  media_id: string;
+  attachment_id: number;
+  file_name: string;
+  link: string;
+  content_type: string;
+  width: number;
+  height: number;
+  filesize: number;
+  r2_key: string;
+  site_name: string;
+}
+
+export interface Product {
+  id: number | string;
+  name?: string;
+  product?: string;
+  description?: string;
+  description_markdown?: string;
+  price?: number;
+  currency?: string;
+  sku?: string;
+  slug?: string;
+  slug_prefix?: string;
+  image?: string;
+  media?: MediaItem[] | MediaItem[][];
+  isActive?: boolean;
+  organizationId?: number;
+  createdAt?: string;
+  updatedAt?: string;
+  gateway_product_id_live?: string;
+  gateway_product_id_test?: string;
+  stripe_product_id_live?: string;
+  stripe_product_id_test?: string;
+  [key: string]: any;
+}
+
+export interface CreateProductRequest {
+  name: string;
+  description?: string;
+  price: number;
+  currency?: string;
+  sku?: string;
+  isActive?: boolean;
+}
+
+export interface ProductQueryParams extends PaginationParams {
+  organizationId?: number;
+  isActive?: boolean;
+  search?: string;
+  category?: string | string[];
+  category_id?: number | string | Array<number | string>;
+}
+
+export interface BlogPost {
+  id: string | number;
+  slug: string;
+  slug_prefix?: string;
+  page_type?: string;
+  title: string;
+  content?: string;
+  excerpt?: string;
+  image?: string;
+  published?: boolean;
+  created_at?: string;
+  updated_at?: string;
+  description?: string;
+  published_date?: string;
+  author?: string;
+  tags?: string[];
+  [key: string]: any;
+}
+
+// Payment Gateways
+export interface PaymentGateway {
+  id: number;
+  name: string;
+  provider: string;
+  isActive: boolean;
+  configuration: Record<string, any>;
+  organizationId?: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreatePaymentGatewayRequest {
+  name: string;
+  provider: string;
+  configuration: Record<string, any>;
+  isActive?: boolean;
+}
+
+// Webhooks
+export interface Webhook {
+  id: string;
+  name: string;
+  url: string;
+  provider: string;
+  events: string[];
+  isActive: boolean;
+  secret?: string;
+  organizationId?: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateWebhookRequest {
+  name: string;
+  url: string;
+  provider: string;
+  events: string[];
+  isActive?: boolean;
+  secret?: string;
+}
+
+// Checkout/Stripe
+export type CheckoutMetadataValue =
+  | string
+  | number
+  | boolean
+  | null
+  | CheckoutMetadataValue[]
+  | { [key: string]: CheckoutMetadataValue };
+
+export type CheckoutMetadata = Record<string, CheckoutMetadataValue>;
+
+export interface CreateCheckoutSessionRequest {
+  // Single item checkout (legacy/simple)
+  priceId?: string;
+  quantity?: number;
+  
+  // Multiple items checkout (recommended)
+  line_items?: Array<{
+    // Either use existing Stripe price ID
+    price?: string;
+    quantity: number;
+    // Or define price data inline
+    price_data?: {
+      currency: string;
+      product_data: {
+        name: string;
+        description?: string;
+        images?: string[];
+      };
+      unit_amount: number;  // Amount in cents
+    };
+  }>;
+  
+  // Common fields
+  success_url: string;  // Required
+  cancel_url: string;   // Required
+  successUrl?: string;  // Alternative naming
+  cancelUrl?: string;   // Alternative naming
+  customer_email?: string;
+  customerEmail?: string;  // Alternative naming
+  metadata?: CheckoutMetadata;
+  mode?: 'payment' | 'subscription' | 'setup';
+  automatic_tax?: {
+    enabled: boolean;
+  };
+  shipping_address_collection?: {
+    allowed_countries: string[];
+  };
+  billing_address_collection?: 'auto' | 'required';
+}
+
+export interface CheckoutSession {
+  id: string;
+  url: string;
+  status: string;
+}
+
+// Contact Forms
+export interface ContactSubmission {
+  id: string;
+  name: string;
+  email: string;
+  subject?: string;
+  message: string;
+  status: string;
+  createdAt: string;
+}
+
+export interface CreateContactRequest {
+  name: string;
+  email: string;
+  subject?: string;
+  message: string;
+  turnstileToken?: string;
+}
+
+// Error Types
+export interface ApiError {
+  message: string;
+  code?: string;
+  status?: number;
+  details?: any;
+}
+
+// SDK Configuration
+export interface PerspectApiConfig {
+  baseUrl: string;
+  apiKey?: string;
+  jwt?: string;
+  timeout?: number;
+  retries?: number;
+  headers?: Record<string, string>;
+}
+
+// HTTP Methods
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+// Request Options
+export interface RequestOptions {
+  method?: HttpMethod;
+  headers?: Record<string, string>;
+  body?: any;
+  params?: Record<string, string | number | boolean>;
+  timeout?: number;
+}