# CommonGrants TypeScript SDK: Complete Guide to Installation and Usage

> Discover the CommonGrants TypeScript SDK for seamless integration. Learn installation and usage for fully typed, authentication-aware clients. Get started today.

- Repository: [U.S. Department of Health & Human Services/simpler-grants-protocol](https://github.com/hhs/simpler-grants-protocol)
- Tags: tutorial
- Published: 2026-03-03

---

**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:

```bash
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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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

```typescript
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

```typescript
// 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

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

```

### Search with Filters

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

```

### Working with Custom Fields

```typescript
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`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/types.ts) and Zod schemas in [`lib/ts-sdk/src/schemas/zod/models.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/auth.ts)
- **Resource-oriented client** with automatic pagination handling in [`lib/ts-sdk/src/client/client.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/lib/ts-sdk/src/client/client.ts)
- **Extensible schemas** allowing typed custom fields through [`lib/ts-sdk/src/extensions/with-custom-fields.ts`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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`](https://github.com/hhs/simpler-grants-protocol/blob/main/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.