Grexx Platform API TypeScript Client

Common errors

• TypeError: Cannot read properties of undefined (reading 'caseInfo')

  cause The `CaseService` or other service client was not correctly imported or `grexx-api` itself failed to load.
  fix Ensure `import { CaseService } from 'grexx-api';` is at the top of your file and that `grexx-api` is correctly installed via `npm install grexx-api`.

• Error: Request failed with status code 401 (Unauthorized)

  cause The provided `OpenAPI.TOKEN` is either missing, invalid, or has expired, preventing authentication with the Grexx Platform API.
  fix Verify that `OpenAPI.TOKEN` is set correctly with a valid, unexpired API key for your Grexx instance. Check the API key's permissions on the Grexx platform.

• Error: Request failed with status code 404 (Not Found)

  cause The `OpenAPI.BASE` URL is incorrect, the specific API endpoint does not exist at the provided path, or the resource (e.g., `casePath`) does not exist on the Grexx platform.
  fix Double-check `OpenAPI.BASE` against your Grexx platform's API documentation. Confirm that the `casePath` or other resource identifiers are correct and exist on your Grexx instance.

Warnings

• breaking Major version updates (e.g., v12 to v13) typically introduce breaking changes, which directly correspond to significant updates or refactorings in the underlying Grexx Platform API's OpenAPI specification. These changes may include altered endpoint paths, renamed parameters, different response body structures, or changes in required authentication schemes.
  Fix: Always review the release notes or changelog for specific breaking changes when upgrading major versions. Regenerate or update client code if you are using a custom OpenAPI generator, and adapt your application code to the new API contract.
• gotcha The `OpenAPI.TOKEN` and `OpenAPI.BASE` configurations are global. If you are developing a server-side application that needs to interact with multiple Grexx instances or different user contexts, direct modification of these global properties can lead to race conditions or incorrect API calls. Ensure these are set appropriately for the current request context.
  Fix: For multi-tenant or multi-user applications, consider wrapping API calls within a function or class that accepts configuration parameters specific to each request or user, or ensure that global settings are managed carefully with proper isolation mechanisms (e.g., using a fresh instance of the client configuration for each request if the library supports it, or dynamically setting it with care).
• gotcha API keys (OpenAPI.TOKEN) and base URLs (OpenAPI.BASE) should never be hardcoded directly into production application code or committed to version control. This is a significant security risk.
  Fix: Store API keys and sensitive configurations in environment variables, a secure vault service (e.g., AWS Secrets Manager, HashiCorp Vault), or a `.env` file for local development. Access them at runtime using `process.env.YOUR_API_KEY`.

Install

• npm install grexx-api npm
• yarn add grexx-api yarn
• pnpm add grexx-api pnpm

Imports

• OpenAPI
  wrong:

  const OpenAPI = require('grexx-api').OpenAPI;

  correct:

  import { OpenAPI } from 'grexx-api';

  Used for global client configuration like base URL and authentication tokens. Primarily designed for ESM imports.
• CaseService
  wrong:

  const CaseService = require('grexx-api').CaseService;

  correct:

  import { CaseService } from 'grexx-api';

  Imports the service client for Case-related API endpoints. Each major API entity typically has its own service export.
• CaseInfo
  wrong:

  import { CaseInfo } from 'grexx-api';

  correct:

  import type { CaseInfo } from 'grexx-api';

  For importing TypeScript types/interfaces like `CaseInfo` which represent API response structures. Use `import type` for clarity and bundler optimization.

Quickstart

Demonstrates initializing the Grexx API client and retrieving information for a specific case using the `CaseService`.

import { OpenAPI, CaseService } from 'grexx-api';

// Configure the API client with your base URL and API key
OpenAPI.BASE = process.env.GREXX_API_BASE_URL ?? 'https://name.grexx.today/api/v1';
OpenAPI.TOKEN = process.env.GREXX_API_KEY ?? 'your-api-key'; // Replace with a secure way to load your API key

const casePath = 'example-case-id'; // Replace with a valid case ID from your Grexx platform

CaseService.caseInfo(casePath, { css: true, rootline: false })
  .then(response => {
    console.log('Successfully fetched Case Info:');
    console.log(`Case ID: ${response.id}`);
    console.log(`Case Title: ${response.title}`);
  })
  .catch(error => {
    console.error('Error fetching case info:', error.message || error);
    if (error.status) {
      console.error(`Status: ${error.status}, Body: ${JSON.stringify(error.body)}`);
    }
  });