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

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:

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