CommonGrants TypeScript SDK: Complete Guide to Installation and Usage

Yes, CommonGrants provides a first-class TypeScript SDK published as @common-grants/sdk that wraps the REST API with fully typed, authentication-aware clients.

The CommonGrants TypeScript SDK lives in the hhs/simpler-grants-protocol repository under the lib/ts-sdk directory. It offers developers a type-safe way to interact with the Common Grants API, complete with runtime validation via Zod schemas, automatic pagination handling, and flexible authentication strategies.

Installation and Setup

Install the SDK from npm to get started with CommonGrants TypeScript development:

npm install @common-grants/sdk

The package exports modular entry points for tree-shaking, allowing you to import only the components you need, such as the core client, authentication helpers, or type definitions.

Core Architecture and Components

The SDK follows a resource-oriented design pattern centered in lib/ts-sdk/src/client/client.ts. Understanding these core components helps you leverage the full power of the CommonGrants TypeScript SDK.

HTTP Client

The Client class in lib/ts-sdk/src/client/client.ts serves as the core HTTP client, handling base URL configuration, low-level fetch operations, and auto-pagination via the fetchMany method. It manages request headers, query parameters, and response parsing while providing a consistent interface for all API interactions.

Authentication Layer

Located in lib/ts-sdk/src/client/auth.ts, the authentication module provides constructors for three authentication strategies:

• Bearer token: Auth.bearer("your-jwt-token")
• API key: Auth.apiKey("your-api-key")
• No authentication: Auth.none()

The buildAuthHeaders helper automatically transforms these configurations into proper HTTP headers for each request.

Opportunities Namespace

The opportunities namespace in lib/ts-sdk/src/client/opportunities.ts provides high-level methods for interacting with the /common-grants/opportunities endpoint:

• get(id): Retrieve a single opportunity by UUID
• list(options): List opportunities with automatic pagination
• search(params): Search opportunities with query strings and filters

This namespace handles schema validation, pagination logic, and query building automatically.

Type Definitions and Schemas

Central TypeScript definitions reside in lib/ts-sdk/src/types.ts, providing interfaces for OpportunityBase, OppFilters, and pagination types. Runtime validation uses Zod schemas defined in lib/ts-sdk/src/schemas/zod/models.ts, ensuring type safety from API response to application code.

Extensions System

The SDK supports schema extension via lib/ts-sdk/src/extensions/with-custom-fields.ts. The withCustomFields utility allows you to augment base schemas with typed custom fields, enabling strong typing for legacy system identifiers or domain-specific metadata.

Practical Usage Examples

These examples demonstrate real-world usage patterns for the CommonGrants TypeScript SDK.

Basic Client Initialization with Bearer Token

import { Client, Auth } from "@common-grants/sdk/client";

const client = new Client({
  baseUrl: "https://api.common-grants.org",
  auth: Auth.bearer("your-jwt-token"),
});

// Fetch a single opportunity
const opp = await client.opportunities.get("123e4567-e89b-12d3-a456-426614174000");
console.log(opp.title);

Auto-Pagination for Complete Dataset Retrieval

// Auto-paginate to retrieve every opportunity (default pageSize = 100, maxItems = 1000)
const allOpps = await client.opportunities.list();
console.log(`Found ${allOpps.items.length} opportunities`);

Specific Page Retrieval

const page2 = await client.opportunities.list({ page: 2, pageSize: 10 });
console.log(page2.items.map(o => o.title));

Search with Filters

const results = await client.opportunities.search({
  query: "education",
  statuses: ["open"],
});
console.log(`Search returned ${results.items.length} open opportunities`);

Working with Custom Fields

import { z } from "zod";
import { withCustomFields, CustomFieldType } from "@common-grants/sdk/extensions";
import { OpportunityBaseSchema } from "@common-grants/sdk/schemas";

// Extend the base schema with a typed custom field
const OpportunityWithLegacyId = withCustomFields(OpportunityBaseSchema, {
  legacyId: {
    fieldType: CustomFieldType.integer,
    valueSchema: z.number().int(),
    description: "Legacy system identifier",
  },
});

const opp = await client.opportunities.get("some-id", {
  schema: OpportunityWithLegacyId,
});
console.log(opp.customFields?.legacyId?.value); // typed as number

Summary

The CommonGrants TypeScript SDK provides a robust, type-safe interface to the Common Grants API:

• First-class TypeScript support with full type definitions in lib/ts-sdk/src/types.ts and Zod schemas in lib/ts-sdk/src/schemas/zod/models.ts
• Flexible authentication via Bearer tokens, API keys, or unauthenticated access using lib/ts-sdk/src/client/auth.ts
• Resource-oriented client with automatic pagination handling in lib/ts-sdk/src/client/client.ts
• Extensible schemas allowing typed custom fields through lib/ts-sdk/src/extensions/with-custom-fields.ts
• Published as @common-grants/sdk on npm for easy installation

Frequently Asked Questions

How do I install the CommonGrants TypeScript SDK?

Install the SDK using npm with the command npm install @common-grants/sdk. The package provides modular exports, allowing you to import specific components like the client, authentication helpers, or type definitions without bundling unused code.

What authentication methods does the SDK support?

The SDK supports three authentication strategies implemented in lib/ts-sdk/src/client/auth.ts: Bearer token authentication via Auth.bearer(), API key authentication via Auth.apiKey(), and unauthenticated access via Auth.none(). The buildAuthHeaders helper automatically converts these configurations into the appropriate HTTP headers for each request.

Can I extend the SDK to handle custom fields?

Yes, the SDK includes an extension system in lib/ts-sdk/src/extensions/with-custom-fields.ts that allows you to augment base schemas with typed custom fields. Using the withCustomFields utility, you can define Zod schemas for custom properties (such as legacy system identifiers) and pass them to methods like client.opportunities.get() for fully typed responses that include your custom data.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}