@conga-cloud/graphql

🚀 @conga-cloud/graphql is a TypeScript/JavaScript SDK designed to connect front-end clients to a multi-tenant GraphQL back-end. Each tenant has its own GraphQL schema based on the authentication token. This SDK simplifies GraphQL queries, mutations, subscriptions, and type generation for strongly-typed interactions.

📦 Installation

Install the package using npm:

npm install @conga-cloud/graphql

Or using Yarn:

yarn add @conga-cloud/graphql

⚡ CLI Command: TypeScript Type Generation

This package provides a CLI command to generate TypeScript types dynamically based on your GraphQL schema.

Generate Types

Run the following command:

npx @conga-cloud/graphql generate

This will:

1. Prompt the user to select an environment (QA, Staging, Production, Development).
2. Open a browser for login.
3. Capture the authentication token.
4. Generate the types for the corresponding environment and tenant

The generated types will be saved in src/types/graphql.ts.

🔧 Usage

Initialize the Client

import { GraphQLClient } from "@conga-cloud/graphql";

const client = new GraphQLClient(); // Available arguments are 'Development', 'QA', 'Staging' and 'Production'...default is 'Production'
await client.initialize();          // Will authenticate and generate an access token for graphql calls

Execute Queries

import { Query } from './types/graphql';

const query = `
        Data{
          Account{
            edges{
              node{
                Id
                Name
                AccountNumber
                Type
                Industry
              }
            }
          }
        }
      `;

client.query<Query>(query).then((data) => console.log(data));

📡 Subscriptions & Queries

The SDK allows both querying data and subscribing to real-time updates.

Create a GraphQL Query

import { Query } from "./types/graphql";
import { connection } from "@conga-cloud/graphql";

const conn = connection("Account").nodes(["Id", "Name", "AccountNumber", "Type", "Status", "Industry"]);
const data = await client.query<Query>(conn);

Subscribe to Real-Time Data

client.subscription<Query>(
    conn,
    (response: Query) => {
        const edges = result.Data?.Account?.edges;
        console.log(edges);
    },
    (error) => {
        console.error(error);
    }
);

🔧 Query Builder Methods

The Connection class provides a method-based approach to constructing GraphQL queries:

Methods Overview

• .nodes(fields: string[]) – Select fields for a connection.
• .edge(id: string) – Fetch a single record by ID.
• .connection(connection: Connection) – Add child connections.
• .where(condition: string) – Filter results with conditions.
• .pageInfo() – Include pagination info.
• .first(count: number) / .last(count: number) – Limit the number of results.
• .before(cursor: string) / .after(cursor: string) – Handle pagination cursors.
• .orderBy(field: string, direction: "Ascending" | "Descending") – Sort results.

Example:

import { connection } from "@conga-cloud/graphql";

const accountQuery = connection("Account")
    .nodes(["Id", "Name", "AccountNumber"])
    .where("Status = 'Active'")
    .orderBy("Name", "Ascending")
    .first(10);

const query: string = accountQuery.toQuery();

This will generate a GraphQL query string dynamically.

🎯 Features

✅ Multi-Tenant Schema Support – Fetches schemas dynamically based on auth token. ✅ GraphQL Query & Mutation Execution – Simplifies GraphQL API interactions. ✅ TypeScript Type Generation – Ensures type safety for GraphQL operations. ✅ Seamless Authentication – Integrated OAuth OIDC flow with browser login. ✅ CLI Commands – Provides a CLI tool for authentication and type generation. ✅ Subscriptions – Real-time updates via GraphQL subscriptions. ✅ Query Builder – Method-based approach to building GraphQL queries.