@promakeai/cli 0.0.5 → 0.1.0

package/template/src/modules/api/USAGE.md

@@ -1,515 +0,0 @@
-# API Module Usage Guide
-
-## Overview
-
-Central API communication layer using `@promakeai/customer-backend-client`. Provides type-safe API calls and error handling utilities.
-
-**Important**: The API client configuration and error utilities are core infrastructure and should NOT be modified. UI components consuming the API are customizable.
-
-## Module Structure
-
-```
-src/modules/api/
-├── customer-client.ts      # [CORE] API client instance - DO NOT MODIFY
-└── get-error-message.ts    # [CORE] Error utility - DO NOT MODIFY
-```
-
-## Requirements & Dependencies
-
-### Required NPM Packages
-
-```json
-{
-  "@promakeai/customer-backend-client": "^1.0.7" // CORE - API client
-}
-```
-
-Note: `axios` is included as a dependency of the customer backend client.
-
-### Required Environment Variables
-
-```env
-# Option 1: Direct API URL
-VITE_API_CUSTOMER=https://your-api.example.com/
-
-# Option 2: Tenant-based URL (auto-generated)
-VITE_TENANT_UUID=your-tenant-uuid-here
-# Generates: https://{VITE_TENANT_UUID}.backend.promake.ai/
-```
-
-**At least ONE of these must be set** in your `.env` file.
-
-### Optional Project Dependencies
-
-**For Error Display** (Recommended):
-
-- `sonner` - For `toast.error()` in UI components
-
-**For Type Checking**:
-
-- `typescript` - For type safety
-
-**For React Query Integration** (Optional):
-
-- `@tanstack/react-query` - For query/mutation hooks
-
-### Project Integration Points
-
-**Required by**:
-
-- `@/modules/auth/use-auth` - Uses this client for authentication
-- Any page/component making API calls
-
-**Uses**:
-
-- Environment variables (Vite)
-
-## Customer Client Setup
-
-```tsx
-import { createClient } from "@promakeai/customer-backend-client";
-import enValidation from "./validation/en.json";
-import trValidation from "./validation/tr.json";
-
-const customerClient = createClient({
-  baseURL:
-    import.meta.env.VITE_API_CUSTOMER ||
-    `https://${import.meta.env.VITE_TENANT_UUID}.backend.promake.ai/`,
-  messages: {
-    en: enValidation,
-    tr: trValidation,
-  },
-  defaultLanguage: "tr",
-});
-```
-
-## Multi-language Validation
-
-The API client includes automatic multi-language validation error messages that sync with your app's language setting.
-
-### How It Works
-
-1. **Validation messages** are defined in `src/modules/api/validation/{language}.json`
-2. **All languages** are passed to the client at initialization
-3. **Language sync** happens automatically in `App.tsx` via `useEffect`
-4. **Runtime switching** updates validation errors immediately
-
-### Validation Message Files
-
-Validation messages are stored in the API module for better modularity:
-
-**English** (`src/modules/api/validation/en.json`):
-
-```json
-{
-  "username_required": "Username is required",
-  "password_required": "Password is required",
-  "email_invalid": "Invalid email address",
-  "password_min_length": "Password must be at least 8 characters"
-}
-```
-
-**Turkish** (`src/modules/api/validation/tr.json`):
-
-```json
-{
-  "username_required": "Kullanıcı adı zorunludur",
-  "password_required": "Şifre zorunludur",
-  "email_invalid": "Geçersiz e-posta adresi",
-  "password_min_length": "Şifre en az 8 karakter olmalıdır"
-}
-```
-
-**Why in `modules/api/validation/`?**
-
-- ✅ **Modular**: API module contains its own validation messages
-- ✅ **Portable**: When copying the API module, validation comes with it
-- ✅ **Clear separation**: UI texts in `lang/`, API validation in `modules/api/`
-
-### Available Validation Keys
-
-The following validation message keys are supported:
-
-**Auth Validation**:
-
-- `username_required`, `username_min_length`
-- `email_required`, `email_invalid`
-- `password_required`, `password_min_length`
-- `password_letter_required`, `password_number_required`
-- `code_required`, `reset_code_required`
-
-**Payment Validation**:
-
-- `session_id_required`
-- `quantity_positive`, `amount_positive`
-- `product_name_required`, `product_description_required`
-- `image_required`
-- `currency_required`, `tax_amount_non_negative`
-- `at_least_one_product`, `payment_type_invalid`
-
-**Contact/Shipping Validation**:
-
-- `firstname_required`, `lastname_required`
-- `phone_required`, `address_required`
-- `country_required`, `city_required`, `zip_required`
-
-### Language Synchronization
-
-The client automatically syncs with your app's language setting:
-
-```tsx
-// In App.tsx
-import { customerClient } from "@/modules/api/customer-client";
-import { useSiteConfig } from "@/hooks/useSiteConfig";
-
-const AppContent = () => {
-  const { getSetting } = useSiteConfig();
-  const currentLang = getSetting("site.defaultLanguage", "en");
-
-  useEffect(() => {
-    customerClient.setLanguage(currentLang);
-  }, [currentLang]);
-};
-```
-
-### Example Error Messages
-
-**Login with empty username (English)**:
-
-```tsx
-try {
-  await customerClient.auth.login({ username: "", password: "test" });
-} catch (error) {
-  // Error: "Username is required"
-}
-```
-
-**Login with empty username (Turkish)**:
-
-```tsx
-// After user switches language to Turkish
-try {
-  await customerClient.auth.login({ username: "", password: "test" });
-} catch (error) {
-  // Error: "Kullanıcı adı zorunludur"
-}
-```
-
-**Registration with invalid email (English)**:
-
-```tsx
-try {
-  await customerClient.auth.register({
-    username: "john",
-    email: "invalid-email",
-    password: "pass123",
-  });
-} catch (error) {
-  // Error: "Invalid email address"
-}
-```
-
-### Adding New Languages
-
-To add support for a new language:
-
-1. Create `src/modules/api/validation/{language-code}.json` with all validation keys
-2. Import it in `customer-client.ts`:
-   ```tsx
-   import deValidation from "./validation/de.json";
-   ```
-3. Add to messages object:
-   ```tsx
-   const customerClient = createClient({
-     messages: {
-       en: enValidation,
-       tr: trValidation,
-       de: deValidation, // New language
-     },
-   });
-   ```
-
-The language will automatically be available when users set `site.defaultLanguage` to `"de"` in settings.
-
-### Manual Language Override
-
-You can also manually change the validation language:
-
-```tsx
-customerClient.setLanguage("tr"); // Switch to Turkish
-customerClient.setLanguage("en"); // Switch to English
-```
-
-This is useful for testing or special use cases where you need to override the automatic sync.
-
-## Basic Usage
-
-### Direct Client Usage
-
-```tsx
-import { customerClient } from "@/modules/api/customer-client";
-
-const response = await customerClient.auth.login({ username, password });
-```
-
-### With Auth Hook (Recommended)
-
-```tsx
-import { useAuth } from "@/modules/auth/use-auth";
-
-function MyComponent() {
-  const { api, isAuthenticated } = useAuth();
-
-  if (isAuthenticated) {
-    const orders = await api.orders.getMyOrders(); // Token auto-added
-  }
-}
-```
-
-## Available API Methods
-
-### Auth Operations
-
-```tsx
-// Login
-await customerClient.auth.login({ username, password });
-
-// Register
-await customerClient.auth.register({ username, email, password });
-
-// Confirm email
-await customerClient.auth.confirm({ username, code });
-
-// Password reset flow
-await customerClient.auth.forgotPassword({ username });
-await customerClient.auth.resetPassword({ username, code, newPassword });
-
-// Token refresh (handled automatically by useAuth)
-await customerClient.axios.post("/auth/refresh", { refreshToken });
-```
-
-### Order Operations
-
-```tsx
-// Get user's orders (requires auth)
-const orders = await customerClient.orders.getMyOrders();
-
-// Get order by payment session
-const order = await customerClient.orders.getBySessionId({ sessionId });
-```
-
-### Payment Operations
-
-```tsx
-// Create checkout session
-const session = await customerClient.payment.createCheckout(checkoutData);
-
-// Verify payment
-const result = await customerClient.payment.verify({ sessionId });
-
-// Check payment status
-const status = await customerClient.payment.status({ sessionId });
-```
-
-### Token Management
-
-```tsx
-customerClient.setToken("access-token"); // Set token
-customerClient.setToken(null); // Clear token
-```
-
-### Direct Axios Access
-
-```tsx
-// For custom endpoints not in client API
-const response = await customerClient.axios.get("/custom-endpoint");
-const data = await customerClient.axios.post("/custom", { data });
-
-// Add interceptors
-customerClient.axios.interceptors.request.use((config) => {
-  console.log("Request:", config);
-  return config;
-});
-```
-
-## Error Handling
-
-### getErrorMessage Utility
-
-Extracts user-friendly messages from API errors:
-
-```tsx
-import { getErrorMessage } from "@/modules/api/get-error-message";
-
-try {
-  await customerClient.auth.login({ username, password });
-} catch (err) {
-  const message = getErrorMessage(err, "Login failed");
-  toast.error(message); // "Invalid credentials" or fallback
-}
-```
-
-**Priority Order**:
-
-1. `error.response.data.message` (backend message)
-2. `error.response.data.error` (backend error)
-3. `error.message` (axios error)
-4. Fallback message
-
-## React Query Integration
-
-```tsx
-import { useQuery, useMutation } from "@tanstack/react-query";
-import { customerClient } from "@/modules/api/customer-client";
-
-// Query
-function useMyOrders() {
-  return useQuery({
-    queryKey: ["orders"],
-    queryFn: () => customerClient.orders.getMyOrders(),
-  });
-}
-
-// Mutation
-function useCreateCheckout() {
-  return useMutation({
-    mutationFn: (data) => customerClient.payment.createCheckout(data),
-    onError: (err) => toast.error(getErrorMessage(err)),
-  });
-}
-```
-
-## Type Safety
-
-```tsx
-import type { ApiClient } from "@/modules/api/customer-client";
-
-// Use client type
-function service(client: ApiClient) {
-  return client.orders.getMyOrders();
-}
-
-// Extract response types
-type Order = Awaited<ReturnType<typeof customerClient.orders.getMyOrders>>;
-```
-
-## Best Practices
-
-### Error Handling Pattern
-
-```tsx
-import { getErrorMessage } from "@/modules/api/get-error-message";
-
-async function handleApiCall() {
-  try {
-    const result = await customerClient.auth.login(credentials);
-    toast.success("Success!");
-    return result;
-  } catch (err) {
-    const message = getErrorMessage(err, "Operation failed");
-    toast.error(message);
-    console.error("API Error:", err); // Debug
-    throw err; // Optional
-  }
-}
-```
-
-### With Loading State
-
-```tsx
-const [loading, setLoading] = useState(false);
-
-async function fetchData() {
-  setLoading(true);
-  try {
-    const data = await customerClient.orders.getMyOrders();
-    return data;
-  } catch (err) {
-    toast.error(getErrorMessage(err));
-  } finally {
-    setLoading(false);
-  }
-}
-```
-
-## Customization
-
-### Timeout Configuration
-
-```tsx
-// customer-client.ts
-const customerClient = createClient({
-  baseURL: import.meta.env.VITE_API_CUSTOMER,
-  timeout: 10000, // 10 seconds
-});
-```
-
-### Global Error Handler
-
-```tsx
-customerClient.axios.interceptors.response.use(
-  (response) => response,
-  (error) => {
-    if (error.response?.status === 500) {
-      toast.error("Server error");
-    }
-    return Promise.reject(error);
-  },
-);
-```
-
-## Debugging
-
-```tsx
-// Log all requests/responses
-customerClient.axios.interceptors.request.use((config) => {
-  console.log("📤", config.method?.toUpperCase(), config.url);
-  return config;
-});
-
-customerClient.axios.interceptors.response.use(
-  (response) => {
-    console.log("📥", response.status, response.config.url);
-    return response;
-  },
-  (error) => {
-    console.error("❌", error.config?.url, error.response?.status);
-    return Promise.reject(error);
-  },
-);
-```
-
-## Module Integration Checklist
-
-Before using this module, ensure:
-
-- ✅ `@promakeai/customer-backend-client` package installed
-- ✅ Environment variables configured (`.env` file)
-- ✅ At least ONE of: `VITE_API_CUSTOMER` or `VITE_TENANT_UUID` is set
-- ✅ `sonner` installed for toast notifications (optional but recommended)
-
-## Architecture Notes
-
-- **Singleton Instance**: Entire app uses one client instance
-- **Token Management**: Handled automatically by auth module
-- **Auto Retry**: 401 errors trigger token refresh and retry (via auth module)
-- **Type Safety**: Full TypeScript support with auto-completion
-- **JSON Parsing**: Responses automatically parsed
-
-## Dependencies Summary
-
-**Core** (Must not modify):
-
-- `@promakeai/customer-backend-client` - API client package
-- `customer-client.ts` - Client instance configuration
-- `get-error-message.ts` - Error extraction utility
-
-**Environment**:
-
-- `VITE_API_CUSTOMER` or `VITE_TENANT_UUID` - API URL configuration
-
-**Optional Integration**:
-
-- `sonner` - Toast notifications (UI layer)
-- `@tanstack/react-query` - Query management (UI layer)
-- `@/modules/auth/use-auth` - Token management (auth layer)

package/template/src/modules/api/customer-client.ts

@@ -1,20 +0,0 @@
-import {
-  createClient,
-  type ApiClient,
-} from "@promakeai/customer-backend-client";
-import enValidation from "./validation/en.json";
-import trValidation from "./validation/tr.json";
-
-const customerClient = createClient({
-  baseURL:
-    import.meta.env.VITE_API_CUSTOMER ||
-    `https://${import.meta.env.VITE_TENANT_UUID}.backend.promake.ai/`,
-  messages: {
-    en: enValidation,
-    tr: trValidation,
-  },
-  defaultLanguage: "en",
-});
-
-export { customerClient };
-export type { ApiClient };

package/template/src/modules/api/get-error-message.ts

@@ -1,18 +0,0 @@
-export function getErrorMessage(
-  err: unknown,
-  fallback: string = "An error occurred",
-): string {
-  if (err && typeof err === "object") {
-    const e = err as {
-      response?: { data?: { error?: string; message?: string } };
-      message?: string;
-    };
-    return (
-      e.response?.data?.message ||
-      e.response?.data?.error ||
-      e.message ||
-      fallback
-    );
-  }
-  return fallback;
-}

package/template/src/modules/api/validation/en.json

@@ -1,29 +0,0 @@
-{
-  "username_required": "Username is required",
-  "username_min_length": "Username must be at least 3 characters",
-  "email_invalid": "Invalid email address",
-  "email_required": "Email is required",
-  "password_required": "Password is required",
-  "password_min_length": "Password must be at least 8 characters",
-  "password_letter_required": "Password must contain at least 1 letter",
-  "password_number_required": "Password must contain at least 1 number",
-  "code_required": "Verification code is required",
-  "reset_code_required": "Reset code is required",
-  "session_id_required": "Session ID is required",
-  "quantity_positive": "Quantity must be a positive integer",
-  "product_name_required": "Product name is required",
-  "product_description_required": "Product description is required",
-  "amount_positive": "Amount must be a positive integer",
-  "image_required": "Image URL is required",
-  "firstname_required": "First name is required",
-  "lastname_required": "Last name is required",
-  "phone_required": "Phone number is required",
-  "address_required": "Address is required",
-  "country_required": "Country is required",
-  "city_required": "City is required",
-  "zip_required": "Zip code is required",
-  "currency_required": "Currency is required",
-  "tax_amount_non_negative": "Tax amount must be non-negative",
-  "at_least_one_product": "At least one product is required",
-  "payment_type_invalid": "Payment type must be 'stripe', 'iyzico', 'bank_transfer', or 'cash_on_delivery'"
-}

package/template/src/modules/api/validation/tr.json

@@ -1,29 +0,0 @@
-{
-  "username_required": "Kullanıcı adı zorunludur",
-  "username_min_length": "Kullanıcı adı en az 3 karakter olmalıdır",
-  "email_invalid": "Geçersiz e-posta adresi",
-  "email_required": "E-posta zorunludur",
-  "password_required": "Şifre zorunludur",
-  "password_min_length": "Şifre en az 8 karakter olmalıdır",
-  "password_letter_required": "Şifre en az 1 harf içermelidir",
-  "password_number_required": "Şifre en az 1 rakam içermelidir",
-  "code_required": "Doğrulama kodu zorunludur",
-  "reset_code_required": "Sıfırlama kodu zorunludur",
-  "session_id_required": "Oturum ID zorunludur",
-  "quantity_positive": "Miktar pozitif bir tam sayı olmalıdır",
-  "product_name_required": "Ürün adı zorunludur",
-  "product_description_required": "Ürün açıklaması zorunludur",
-  "amount_positive": "Tutar pozitif bir tam sayı olmalıdır",
-  "image_required": "Görsel URL zorunludur",
-  "firstname_required": "Ad zorunludur",
-  "lastname_required": "Soyad zorunludur",
-  "phone_required": "Telefon numarası zorunludur",
-  "address_required": "Adres zorunludur",
-  "country_required": "Ülke zorunludur",
-  "city_required": "Şehir zorunludur",
-  "zip_required": "Posta kodu zorunludur",
-  "currency_required": "Para birimi zorunludur",
-  "tax_amount_non_negative": "Vergi tutarı negatif olamaz",
-  "at_least_one_product": "En az bir ürün gereklidir",
-  "payment_type_invalid": "Ödeme tipi 'stripe', 'iyzico', 'bank_transfer' veya 'cash_on_delivery' olmalıdır"
-}