@codegenapps/frontend-sdk 1.0.1

package/README.md

@@ -0,0 +1,120 @@
+# Frontend SDK
+
+A dynamic, schema-driven frontend SDK for seamless API integration, featuring a fluent query builder.
+
+This SDK is designed to be highly flexible. It dynamically fetches an API specification (like `swagger.json` or `openapi.json`) at runtime and builds a powerful, chainable query interface based on it.
+
+## Features
+
+- **Dynamic Schema**: Initializes from a live API documentation URL. No need to rebuild the SDK when the API changes.
+- **Fluent Query Builder**: An intuitive, chainable interface (`from().select().eq()...`) for building complex API requests.
+- **Framework Agnostic**: Works with any frontend framework (React, Vue, Angular) or plain JavaScript/TypeScript.
+- **TypeScript Support**: Provides type definitions for core components, although API response types are dynamic.
+
+## Installation
+
+```bash
+npm install frontend-sdk # Replace 'frontend-sdk' with your actual package name on npm
+```
+
+## Quick Start
+
+Here's how to initialize the client and perform a query:
+
+```javascript
+import cga from 'frontend-sdk';
+
+// 1. Initialize the client
+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',
+
+    // (Optional) A function that provides the JWT for authenticated requests
+    tokenProvider: () => localStorage.getItem('jwt_token'),
+  });
+  console.log('SDK Initialized!');
+}
+
+// 2. Perform queries
+async function fetchDocuments() {
+  try {
+    const { data, error } = await cga
+      .from('documents')
+      .select('id, title')
+      .eq('owner_id', 1)
+      .order('created_at', { ascending: false })
+      .run();
+
+    if (error) {
+      console.error('Failed to fetch documents:', error);
+      return;
+    }
+
+    console.log('Fetched Documents:', data);
+  } catch (err) {
+    console.error('An unexpected error occurred:', err);
+  }
+}
+
+initialize().then(fetchDocuments);
+```
+
+## API
+
+### Initialization
+
+`cga.init(config)`
+
+Must be called once before any other methods.
+
+- `config.baseUrl` (string, required): The base URL for your API (e.g., `https://api.example.com/api`). The SDK will automatically try to fetch the schema from `{baseUrl_origin}/swagger/doc.json`.
+- `config.licenseKeyProvider` (Function, required): A function that returns your SDK license key.
+- `config.tokenProvider` (Function, optional): A function that returns the JWT for bearer authentication.
+- `config.headers` (Object, optional): An object of default headers to be sent with every request.
+
+### Querying
+
+#### `.from(tableName: string)`
+
+Starts a query chain for a specific resource/table.
+
+#### `.select(fields: string)`
+
+Selects which fields to return. If the backend doesn't support field selection, this will be handled client-side.
+
+#### Filter Methods
+
+- `.eq(column, value)`
+- `.neq(column, value)`
+- `.gt(column, value)`
+- `.gte(column, value)`
+- `.lt(column, value)`
+- `.lte(column, value)`
+- `.like(column, value)`
+- `.in(column, valuesArray)`
+
+#### `.byPk(primaryKeyObject)`
+
+Selects a single record by its primary key (or composite primary key).
+
+Example: `cga.from('daily_active_user').byPk({ activity_date: '...', user_id: 1, ... })`
+
+#### Data Modification
+
+- `.insert(dataObject | dataArray)`
+- `.update(dataObject)`
+- `.delete()`
+
+**Important**: `update` and `delete` must be chained with a filter method (like `.eq()` or `.byPk()`) to specify which record(s) to modify.
+
+#### `.run()`
+
+Executes the query and returns a `Promise` that resolves to `{ data, error }`. **All query chains must end with `.run()`.**
+
+## License
+
+MIT

package/dist/CgaClient.d.ts

@@ -0,0 +1,69 @@
+import { QueryBuilder } from './builder/QueryBuilder';
+/**
+ * Configuration for the CgaClient.
+ */
+export interface CgaClientConfig {
+    /**
+     * The base URL of the API.
+     * The SDK will attempt to fetch the API documentation from `{baseUrl_origin}/swagger/doc.json`.
+     * @example "https://api.example.com/api"
+     */
+    baseUrl: string;
+    /**
+     * A function that returns the license key.
+     * This function will be called during initialization to validate the SDK usage.
+     */
+    licenseKeyProvider: () => Promise<string> | string;
+    /**
+     * Optional headers to be sent with every request,
+     * e.g., for API keys.
+     * @example { 'X-API-KEY': 'YOUR_API_KEY' }
+     */
+    headers?: Record<string, string>;
+    /**
+     * An optional function that provides the JWT token for bearer authentication.
+     * This function will be called before each request that requires authentication.
+     */
+    tokenProvider?: () => Promise<string | null> | string | null;
+}
+/**
+ * The main client for interacting with the API.
+ */
+export declare class CgaClient {
+    private schema;
+    private httpClient;
+    /**
+     * Creates a new CgaClient instance.
+     * Note: The client is not ready to use until `init()` is called.
+     */
+    constructor();
+    /**
+     * Initializes the client with the provided configuration.
+     * This method must be called before any other methods are used.
+     * @param config The configuration for the client.
+     */
+    init(config: CgaClientConfig): Promise<void>;
+    /**
+     * Starts a query chain for a specific table.
+     * @param tableName The name of the table/resource to query.
+     */
+    from(tableName: string): QueryBuilder;
+    /**
+     * Provides access to authentication-related methods.
+     */
+    get auth(): {
+        /**
+         * Logs in a user.
+         * @param username 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<{
+            data: any;
+            error: null;
+        } | {
+            data: null;
+            error: any;
+        }>;
+    };
+}

package/dist/builder/QueryBuilder.d.ts

@@ -0,0 +1,38 @@
+import { AxiosInstance, AxiosRequestConfig } from 'axios';
+interface RequestOptions {
+    headers?: Record<string, string>;
+    axiosConfig?: AxiosRequestConfig;
+}
+export declare class QueryBuilder {
+    private state;
+    private schema;
+    private httpClient;
+    constructor(tableName: string, schema: any, httpClient: AxiosInstance);
+    private setRequestOptions;
+    select(fields: string, options?: RequestOptions): this;
+    eq(column: string, value: any): this;
+    neq(column: string, value: any): this;
+    gt(column: string, value: any): this;
+    gte(column: string, value: any): this;
+    lt(column: string, value: any): this;
+    lte(column: string, value: any): this;
+    like(column: string, value: string): this;
+    in(column: string, values: any[]): this;
+    byPk(keys: Record<string, any>): this;
+    range(page: number, pageSize: number): this;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): this;
+    meta(meta: string | string[]): this;
+    groupBy(groupBy: string | string[]): this;
+    insert(data: any | any[], options?: RequestOptions): this;
+    update(data: any, options?: RequestOptions): this;
+    delete(data?: any | any[], options?: RequestOptions): this;
+    run<TResponse>(): Promise<{
+        data: TResponse | TResponse[] | null;
+        error: any;
+    }>;
+    private buildRequestDetails;
+    private buildUrl;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { CgaClient } from './CgaClient';
+import type { CgaClientConfig } from './CgaClient';
+export type { CgaClientConfig };
+/**
+ * The main instance of the CgaClient.
+ * Use this to interact with the API.
+ *
+ * @example
+ * import cga from 'your-sdk-name';
+ *
+ * async function main() {
+ *   await cga.init({
+ *     baseUrl: '...',
+ *     licenseKeyProvider: () => '...',
+ *   });
+ *
+ *   const { data, error } = await cga.from('documents').select('*');
+ * }
+ */
+declare const cga: CgaClient;
+export default cga;