perspectapi-ts-sdk 1.1.1

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "perspectapi-ts-sdk",
+  "version": "1.1.1",
+  "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "node scripts/test-runner.js",
+    "test:all": "vitest run",
+    "test:watch": "node scripts/test-runner.js watch",
+    "test:coverage": "node scripts/test-runner.js coverage",
+    "test:unit": "node scripts/test-runner.js unit",
+    "test:integration": "node scripts/test-runner.js integration",
+    "test:types": "node scripts/test-runner.js types",
+    "test:ci": "node scripts/test-runner.js ci",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test:ci"
+  },
+  "keywords": [
+    "perspectapi",
+    "sdk",
+    "typescript",
+    "cloudflare-workers",
+    "headless-cms",
+    "api-client"
+  ],
+  "author": "PerspectAPI Team",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "@vitest/coverage-v8": "^1.6.1",
+    "eslint": "^8.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/perspectapi/perspectapi-ts-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/perspectapi/perspectapi-ts-sdk/issues"
+  },
+  "homepage": "https://github.com/perspectapi/perspectapi-ts-sdk#readme"
+}

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

@@ -0,0 +1,103 @@
+/**
+ * API Keys Management client for PerspectAPI SDK
+ */
+
+import { BaseClient } from './base-client';
+import type {
+  ApiKey,
+  CreateApiKeyRequest,
+  UpdateApiKeyRequest,
+  PaginatedResponse,
+  ApiResponse,
+} from '../types';
+
+export class ApiKeysClient extends BaseClient {
+  constructor(http: any) {
+    super(http, '/api/v1');
+  }
+
+  /**
+   * Get all API keys
+   */
+  async getApiKeys(params?: { page?: number; limit?: number }): Promise<PaginatedResponse<ApiKey>> {
+    return this.getPaginated<ApiKey>('/keys', params);
+  }
+
+  /**
+   * Get API key by ID
+   */
+  async getApiKeyById(id: string): Promise<ApiResponse<ApiKey>> {
+    return this.getSingle<ApiKey>(`/keys/${id}`);
+  }
+
+  /**
+   * Create new API key
+   */
+  async createApiKey(data: CreateApiKeyRequest): Promise<ApiResponse<ApiKey & { key: string }>> {
+    return this.create<CreateApiKeyRequest, ApiKey & { key: string }>('/keys', data);
+  }
+
+  /**
+   * Update API key
+   */
+  async updateApiKey(id: string, data: UpdateApiKeyRequest): Promise<ApiResponse<ApiKey>> {
+    return this.update<UpdateApiKeyRequest, ApiKey>(`/keys/${id}`, data);
+  }
+
+  /**
+   * Delete API key
+   */
+  async deleteApiKey(id: string): Promise<ApiResponse<{ message: string }>> {
+    return this.delete<{ message: string }>(`/keys/${id}`);
+  }
+
+  /**
+   * Regenerate API key
+   */
+  async regenerateApiKey(id: string): Promise<ApiResponse<ApiKey & { key: string }>> {
+    return this.create<Record<string, never>, ApiKey & { key: string }>(`/keys/${id}/regenerate`, {});
+  }
+
+  /**
+   * Activate API key
+   */
+  async activateApiKey(id: string): Promise<ApiResponse<ApiKey>> {
+    return this.patch<{ isActive: boolean }, ApiKey>(`/keys/${id}`, { isActive: true });
+  }
+
+  /**
+   * Deactivate API key
+   */
+  async deactivateApiKey(id: string): Promise<ApiResponse<ApiKey>> {
+    return this.patch<{ isActive: boolean }, ApiKey>(`/keys/${id}`, { isActive: false });
+  }
+
+  /**
+   * Get API key usage statistics
+   */
+  async getApiKeyStats(id: string): Promise<ApiResponse<{
+    totalRequests: number;
+    requestsToday: number;
+    requestsThisMonth: number;
+    lastUsedAt?: string;
+  }>> {
+    return this.getSingle(`/keys/${id}/stats`);
+  }
+
+  /**
+   * Test API key validity
+   */
+  async testApiKey(key: string): Promise<ApiResponse<{
+    valid: boolean;
+    keyId?: string;
+    permissions?: string[];
+    expiresAt?: string;
+  }>> {
+    return this.create<{ key: string }, {
+      valid: boolean;
+      keyId?: string;
+      permissions?: string[];
+      expiresAt?: string;
+    }>('/keys/test', { key });
+  }
+}

package/src/client/auth-client.ts

@@ -0,0 +1,87 @@
+/**
+ * Authentication client for PerspectAPI SDK
+ */
+
+import { BaseClient } from './base-client';
+import type {
+  SignUpRequest,
+  SignInRequest,
+  AuthResponse,
+  User,
+  ApiResponse,
+} from '../types';
+
+export class AuthClient extends BaseClient {
+  constructor(http: any) {
+    super(http, '/api/v1');
+  }
+
+  /**
+   * Get CSRF token
+   */
+  async getCsrfToken(): Promise<ApiResponse<{ token: string }>> {
+    return this.http.get<{ token: string }>(this.buildPath('/csrf'));
+  }
+
+  /**
+   * Sign up a new user
+   */
+  async signUp(data: SignUpRequest): Promise<ApiResponse<{ message: string; userId: string }>> {
+    return this.create<SignUpRequest, { message: string; userId: string }>('/signup', data);
+  }
+
+  /**
+   * Sign in user
+   */
+  async signIn(data: SignInRequest): Promise<ApiResponse<AuthResponse>> {
+    const response = await this.create<SignInRequest, AuthResponse>('/authenticate', data);
+    
+    // Update HTTP client with JWT if provided
+    if (response.data && 'token' in response.data && response.data.token) {
+      this.http.setAuth(response.data.token);
+    }
+    
+    return response;
+  }
+
+  /**
+   * Activate user account
+   */
+  async activateAccount(activationKey: string): Promise<ApiResponse<{ message: string }>> {
+    return this.getSingle<{ message: string }>(`/activate/${activationKey}`);
+  }
+
+  /**
+   * Request password reset
+   */
+  async forgotPassword(email: string): Promise<ApiResponse<{ message: string }>> {
+    return this.create<{ email: string }, { message: string }>('/forgotpassword', { email });
+  }
+
+  /**
+   * Reset password with token
+   */
+  async resetPassword(
+    resetToken: string,
+    password: string
+  ): Promise<ApiResponse<{ message: string }>> {
+    return this.create<{ password: string }, { message: string }>(
+      `/passwordreset/${resetToken}`,
+      { password }
+    );
+  }
+
+  /**
+   * Get current user profile
+   */
+  async getUserProfile(): Promise<ApiResponse<{ user: User }>> {
+    return this.getSingle<{ user: User }>('/userprofile');
+  }
+
+  /**
+   * Sign out (clear local auth)
+   */
+  signOut(): void {
+    this.http.clearAuth();
+  }
+}

package/src/client/base-client.ts

@@ -0,0 +1,100 @@
+/**
+ * Base client class for PerspectAPI SDK
+ */
+
+import { HttpClient } from '../utils/http-client';
+import type { ApiResponse } from '../types';
+
+export abstract class BaseClient {
+  protected http: HttpClient;
+  protected basePath: string;
+
+  constructor(http: HttpClient, basePath: string) {
+    this.http = http;
+    this.basePath = basePath;
+  }
+
+  /**
+   * Build a site-scoped endpoint relative to the API base path
+   */
+  protected siteScopedEndpoint(
+    siteName: string,
+    endpoint = '',
+    options?: { includeSitesSegment?: boolean }
+  ): string {
+    if (!siteName || !siteName.trim()) {
+      throw new Error('siteName is required');
+    }
+
+    const encodedSiteName = encodeURIComponent(siteName.trim());
+    const cleanEndpoint = endpoint.replace(/^\//, '');
+    const includeSitesSegment = options?.includeSitesSegment ?? true;
+    const baseSegment = includeSitesSegment ? `sites/${encodedSiteName}` : encodedSiteName;
+    const suffix = cleanEndpoint ? `/${cleanEndpoint}` : '';
+
+    return `/${baseSegment}${suffix}`;
+  }
+
+  /**
+   * Build endpoint path
+   */
+  protected buildPath(endpoint: string): string {
+    const cleanBasePath = this.basePath.replace(/\/$/, '');
+    const cleanEndpoint = endpoint.replace(/^\//, '');
+    return `${cleanBasePath}/${cleanEndpoint}`;
+  }
+
+  /**
+   * Handle paginated responses
+   */
+  protected async getPaginated<T>(
+    endpoint: string,
+    params?: Record<string, any>
+  ): Promise<ApiResponse<T[]>> {
+    return this.http.get<T[]>(this.buildPath(endpoint), params);
+  }
+
+  /**
+   * Handle single resource responses
+   */
+  protected async getSingle<T>(endpoint: string): Promise<ApiResponse<T>> {
+    return this.http.get<T>(this.buildPath(endpoint));
+  }
+
+  /**
+   * Handle create operations
+   */
+  protected async create<T, R = T>(
+    endpoint: string,
+    data: T
+  ): Promise<ApiResponse<R>> {
+    return this.http.post<R>(this.buildPath(endpoint), data);
+  }
+
+  /**
+   * Handle update operations
+   */
+  protected async update<T, R = T>(
+    endpoint: string,
+    data: T
+  ): Promise<ApiResponse<R>> {
+    return this.http.put<R>(this.buildPath(endpoint), data);
+  }
+
+  /**
+   * Handle partial update operations
+   */
+  protected async patch<T, R = T>(
+    endpoint: string,
+    data: T
+  ): Promise<ApiResponse<R>> {
+    return this.http.patch<R>(this.buildPath(endpoint), data);
+  }
+
+  /**
+   * Handle delete operations
+   */
+  protected async delete<T = any>(endpoint: string): Promise<ApiResponse<T>> {
+    return this.http.delete<T>(this.buildPath(endpoint));
+  }
+}

package/src/client/categories-client.ts

@@ -0,0 +1,151 @@
+/**
+ * Categories Management client for PerspectAPI SDK
+ */
+
+import { BaseClient } from './base-client';
+import type {
+  Category,
+  CreateCategoryRequest,
+  PaginatedResponse,
+  ApiResponse,
+} from '../types';
+
+export class CategoriesClient extends BaseClient {
+  constructor(http: any) {
+    super(http, '/api/v1');
+  }
+
+  /**
+   * Get all categories
+   */
+  async getCategories(params?: { 
+    page?: number; 
+    limit?: number;
+    parentId?: number;
+    organizationId?: number;
+  }): Promise<PaginatedResponse<Category>> {
+    return this.getPaginated<Category>('/categories', params);
+  }
+
+  /**
+   * Get category by ID
+   */
+  async getCategoryById(id: number): Promise<ApiResponse<Category>> {
+    return this.getSingle<Category>(`/categories/${id}`);
+  }
+
+  /**
+   * Get category by slug
+   */
+  async getCategoryBySlug(slug: string): Promise<ApiResponse<Category>> {
+    return this.getSingle<Category>(`/categories/slug/${slug}`);
+  }
+
+  /**
+   * Get product category by slug (for products)
+   */
+  async getProductCategoryBySlug(siteName: string, slug: string): Promise<ApiResponse<Category>> {
+    return this.http.get(this.buildPath(
+      this.siteScopedEndpoint(siteName, `/product_category/slug/${encodeURIComponent(slug)}`)
+    ));
+  }
+
+  /**
+   * Create new category
+   */
+  async createCategory(data: CreateCategoryRequest): Promise<ApiResponse<Category>> {
+    return this.create<CreateCategoryRequest, Category>('/categories', data);
+  }
+
+  /**
+   * Update category
+   */
+  async updateCategory(id: number, data: Partial<CreateCategoryRequest>): Promise<ApiResponse<Category>> {
+    return this.update<Partial<CreateCategoryRequest>, Category>(`/categories/${id}`, data);
+  }
+
+  /**
+   * Delete category
+   */
+  async deleteCategory(id: number): Promise<ApiResponse<{ message: string }>> {
+    return this.delete<{ message: string }>(`/categories/${id}`);
+  }
+
+  /**
+   * Get category tree (hierarchical structure)
+   */
+  async getCategoryTree(rootId?: number): Promise<ApiResponse<Array<Category & {
+    children: Category[];
+  }>>> {
+    const endpoint = rootId ? `/categories/tree/${rootId}` : '/categories/tree';
+    return this.getSingle(endpoint);
+  }
+
+  /**
+   * Get category children
+   */
+  async getCategoryChildren(id: number): Promise<ApiResponse<Category[]>> {
+    return this.getSingle<Category[]>(`/categories/${id}/children`);
+  }
+
+  /**
+   * Get category parent
+   */
+  async getCategoryParent(id: number): Promise<ApiResponse<Category | null>> {
+    return this.getSingle<Category | null>(`/categories/${id}/parent`);
+  }
+
+  /**
+   * Move category to new parent
+   */
+  async moveCategoryToParent(id: number, parentId: number | null): Promise<ApiResponse<Category>> {
+    return this.patch<{ parentId: number | null }, Category>(`/categories/${id}`, { parentId });
+  }
+
+  /**
+   * Get category breadcrumb path
+   */
+  async getCategoryBreadcrumb(id: number): Promise<ApiResponse<Array<{
+    id: number;
+    name: string;
+    slug: string;
+  }>>> {
+    return this.getSingle(`/categories/${id}/breadcrumb`);
+  }
+
+  /**
+   * Get category content/products
+   */
+  async getCategoryContent(id: number, params?: {
+    page?: number;
+    limit?: number;
+    type?: 'content' | 'products' | 'all';
+  }): Promise<ApiResponse<{
+    content: any[];
+    products: any[];
+    total: number;
+  }>> {
+    return this.http.get(`/categories/${id}/content`, params);
+  }
+
+  /**
+   * Bulk update category order
+   */
+  async updateCategoryOrder(updates: Array<{
+    id: number;
+    order: number;
+    parentId?: number;
+  }>): Promise<ApiResponse<{ message: string }>> {
+    return this.create('/categories/reorder', { updates });
+  }
+
+  /**
+   * Search categories
+   */
+  async searchCategories(query: string, params?: {
+    limit?: number;
+    organizationId?: number;
+  }): Promise<ApiResponse<Category[]>> {
+    return this.http.get(`/categories/search`, { q: query, ...params });
+  }
+}