@codegenapps/frontend-sdk 1.0.1 → 1.0.3

package/README.md

@@ -14,24 +14,24 @@ This SDK is designed to be highly flexible. It dynamically fetches an API specif
 ## Installation
 
 ```bash
-npm install frontend-sdk # Replace 'frontend-sdk' with your actual package name on npm
+npm install @codegenapps/frontend-sdk
 ```
 
 ## Quick Start
 
-Here's how to initialize the client and perform a query:
+The following example demonstrates how to initialize the client and perform a query in a standard JavaScript environment.
 
 ```javascript
-import cga from 'frontend-sdk';
+import cga from '@codegenapps/frontend-sdk';
 
-// 1. Initialize the client
+// 1. Initialize the client (ideally once when your application starts)
 async function initialize() {
   await cga.init({
     // The base URL of your API
     baseUrl: 'http://localhost:8080/api',
 
     // A function that provides your SDK license key
-    licenseKeyProvider: () => 'YOUR_SDK_LICENSE_KEY',
+    licenseKeyProvider: () => 'YOUR_API_KEY',
 
     // (Optional) A function that provides the JWT for authenticated requests
     tokenProvider: () => localStorage.getItem('jwt_token'),
@@ -60,7 +60,133 @@ async function fetchDocuments() {
   }
 }
 
-initialize().then(fetchDocuments);
+initialize().then(async () => {
+  await fetchDocuments();
+  await loginUser(); // 示範登入功能
+});
+
+// 3. Perform login
+async function loginUser() {
+  const API_KEY = 'YOUR_API_KEY'; 
+  const account = 'test@example.com';  
+  const password = 'testpassword';      
+
+  try {
+    console.log(`嘗試使用帳號: ${account}, API Key: ${API_KEY} 登入...`);
+    const { data, error } = await cga.auth.login(account, password, API_KEY);
+
+    if (error) {
+      console.error('登入失敗:', error);
+      return;
+    }
+
+    console.log('登入成功! 取得的資料:', data);
+    // 您可以在這裡處理登入成功後的邏輯，例如儲存 JWT token
+    if (data && data.token) {
+      localStorage.setItem('jwt_token', data.token);
+      console.log('JWT Token 已儲存到 localStorage。');
+    }
+
+  } catch (err) {
+    console.error('執行登入時發生意外錯誤:', err);
+  }
+}
+
+```
+
+## Usage with Frameworks
+
+This SDK is framework-agnostic. The Quick Start example uses standard JavaScript (`async/await`) that works in any modern environment. Here’s how you might integrate it into popular frameworks.
+
+### React Example
+
+In a React component, you can use the `useEffect` hook to fetch data when the component mounts.
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import cga from '@codegenapps/frontend-sdk';
+
+// Initialize the SDK once in your app's entry point (e.g., index.js)
+// await cga.init({ ... });
+
+function DocumentsList() {
+  const [documents, setDocuments] = useState([]);
+  const [error, setError] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    async function getDocuments() {
+      const { data, error } = await cga
+        .from('documents')
+        .select('id, title')
+        .eq('owner_id', 1)
+        .run();
+
+      if (error) {
+        setError(error);
+      } else {
+        setDocuments(data);
+      }
+      setIsLoading(false);
+    }
+
+    getDocuments();
+  }, []); // The empty dependency array ensures this runs once on mount
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {documents.map(doc => (
+        <li key={doc.id}>{doc.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### Vue.js Example
+
+In a Vue component (using Composition API), you can use the `onMounted` hook.
+
+```vue
+<script setup>
+import { ref, onMounted } from 'vue';
+import cga from '@codegenapps/frontend-sdk';
+
+// Initialize the SDK once in your app's entry point (e.g., main.js)
+// await cga.init({ ... });
+
+const documents = ref([]);
+const error = ref(null);
+const isLoading = ref(true);
+
+onMounted(async () => {
+  const { data, error: fetchError } = await cga
+    .from('documents')
+    .select('id, title')
+    .eq('owner_id', 1)
+    .run();
+
+  if (fetchError) {
+    error.value = fetchError;
+  } else {
+    documents.value = data;
+  }
+  isLoading.value = false;
+});
+</script>
+
+<template>
+  <div v-if="isLoading">Loading...</div>
+  <div v-else-if="error">Error: {{ error.message }}</div>
+  <ul v-else>
+    <li v-for="doc in documents" :key="doc.id">
+      {{ doc.title }}
+    </li>
+  </ul>
+</template>
 ```
 
 ## API
@@ -115,6 +241,47 @@ Example: `cga.from('daily_active_user').byPk({ activity_date: '...', user_id: 1,
 
 Executes the query and returns a `Promise` that resolves to `{ data, error }`. **All query chains must end with `.run()`.**
 
+### Customizing Requests
+
+While the query builder provides methods for common operations, you can further customize requests by passing an `options` object to the action methods (`select`, `insert`, `update`, `delete`).
+
+#### Adding Custom Headers
+
+You can add or override headers for a specific request.
+
+```javascript
+const { data, error } = await cga
+  .from('documents')
+  .select('id, title', { // <-- Pass options here
+    headers: {
+      'X-Request-ID': 'custom-request-12345'
+    }
+  })
+  .run();
+```
+
+#### Adding Custom Query Parameters
+
+For special query parameters not covered by the built-in filter methods, you can use `axiosConfig.params`. These will be merged with the parameters generated by the builder.
+
+```javascript
+const { data, error } = await cga
+  .from('documents')
+  .select('id, title', { // <-- Pass options here
+    axiosConfig: {
+      params: {
+        '_cache': false,
+        'apiVersion': '2.1'
+      }
+    }
+  })
+  .eq('owner_id', 1) // Builder params are still used
+  .run();
+
+// The above request will be sent to a URL like:
+// /api/documents?_cache=false&apiVersion=2.1&filter=owner_id,eq,1
+```
+
 ## License
 
-MIT
+MIT

package/dist/CgaClient.d.ts

@@ -54,11 +54,11 @@ export declare class CgaClient {
     get auth(): {
         /**
          * Logs in a user.
-         * @param username The user's username.
+         * @param account The user's username.
          * @param password The user's password.
          * @param apiKey The API key required for login.
          */
-        login(username: string, password: string, apiKey: string): Promise<{
+        login(account: string, password: string, apiKey: string): Promise<{
             data: any;
             error: null;
         } | {

package/dist/index.esm.js

@@ -6366,15 +6366,15 @@ class CgaClient {
         return {
             /**
              * Logs in a user.
-             * @param username The user's username.
+             * @param account The user's username.
              * @param password The user's password.
              * @param apiKey The API key required for login.
              */
-            login(username, password, apiKey) {
+            login(account, password, apiKey) {
                 return __awaiter(this, void 0, void 0, function* () {
                     var _a;
                     try {
-                        const response = yield httpClient.post('/auth/login', { username, password }, { headers: { 'X-API-KEY': apiKey } });
+                        const response = yield httpClient.post('/auth/login', { account, password }, { headers: { 'X-API-KEY': apiKey } });
                         return { data: response.data.data, error: null };
                     }
                     catch (error) {