[Issue #497] Support custom fields in TS SDK client by widal001 · Pull Request #522 · HHS/simpler-grants-protocol

widal001 · 2026-02-19T17:48:48Z

Summary

Enables TypeScript SDK users to leverage the API client to parse API responses that include custom fields.

Fixes [TS SDK] Client Support Custom fields #497
Time to review: 10 minutes

Changes proposed

What was added, updated, or removed in this PR.

Updates each of the methods in Client.opportunities to accept an optional schema parameter that can be used to parse custom fields included in API responses. This schema param should be a Zod schema whose inferred type is an extension of OpportunityBase
Fixes two "code smells" in the API client that David flagged:
- Extra round trip in Client.opportunities.search()
- Hard coding statusCode and message in the response for Client.fetchMany() instead of using the metadata from the first response
Changes the expected input for withCustomFields() from CustomFieldSpec[] to Record<string, CustomFieldSpec> to more closely match the actual customFields object that is being added to a given opportunity.
Adds a few additional examples to lib/ts-sdk/examples/ including a mock server that can be used instead of having to spin up the California grants example or the actual Simpler.Grants.gov API

Context for reviewers

Testing instructions, background context, more in-depth details of the implementation, and anything else you'd like to call out or ask reviewers. Explain how the changes were verified.

Instructions for review

Checkout the PR locally: git checkout issue-497-ts-sdk-client-support-custom-fields
Change directory into the SDK: cd lib/ts-sdk/
Run pnpm example:server to spin up the local mock server
In a new terminal window run pnpm example:get-custom-fields 573525f2-8e15-4405-83fb-e6523511d893

Notes

We'll want to make a corresponding change to the CustomFieldSpec attributes and the with_custom_fields() input in the Python SDK, to align with these changes in the TypeScript SDK.
Once we merge this in and check for alignment with Python SDK, we'll open up a separate PR for [TS SDK] Publish v0.5.0 #516

Additional information

Screenshots, GIF demos, code examples or output to help show the changes working as expected.

Allows API client users to pass a custom zod schema to resource methods like `Client.opportunities.get()` this allows users to parse API responses that include custom fields by passing in a schema generated from `withCustomFields()`

- fetchMany() preserves metadata from first response - search() avoids an extra round trip to get response metadata

Previously accepted CustomFieldSpec[] and used `CustomFieldSpec.key` to build the resulting customFields object. Now we expect Record<string,CustomFieldSpec> which more closely matches the final customFields object added to a schema

- Fixes `withCustomFields()` examples in TS SDK README - Adds TS SDK to root-level README

widal001 · 2026-02-19T19:03:57Z

lib/ts-sdk/src/extensions/types.ts

+ * const Schema = withCustomFields(OpportunityBaseSchema, {
+ *   legacyId: { fieldType: "object", valueSchema: ... }
+ * } as const);


This provides an example of the DX change from the old withCustomFields() to the new pattern which accepts:

Record<string,CustomFieldSpec> instead of:

CustomFieldSpec[]

widal001 · 2026-02-19T19:09:26Z

lib/ts-sdk/src/extensions/types.ts

+  /** Optional display name; used as the default for CustomField.name when provided, otherwise the record key is used */
+  name?: string;


Also adds the CustomFieldSpec.name which was missing from the previous iteration. This is used to populate the default value of customFields.legacyId.name

For example:

{ "id": "1cdb6dcd-18f8-4e21-9e20-f8f77cd11269", "title": "Example opportunity", ... "customFields": { "legacyId": { "name": "Legacy ID", "fieldType": "number", "value": 12345, "description": "An integer ID for the opportunity, needed for compatibility with legacy systems" } } }

jcrichlake

A couple of questions/comments.

lib/ts-sdk/__tests__/client/client.spec.ts

jcrichlake · 2026-02-19T19:58:32Z

lib/ts-sdk/__tests__/client/opportunities.spec.ts

      await expect(client.opportunities.search({ query: "test" })).rejects.toThrow("500");
    });

+    it("parses items with a custom schema", async () => {


This shares the same name as the previous test you added. Can you update this to make it slightly more descriptive so that if it breaks in the future it's less confusing?

FWIW this was intentional -- I added roughly the same test parses items with custom schema to each of the Client.opportunity methods and the tests are already grouped by method:

And it groups them when they error as well:

But maybe I can restate the response method in that description to make it clearer? ("parses list response item with custom schema")

Updated the test names here: test(ts-sdk): Make test names more descriptive

lib/ts-sdk/examples/mock-api-server.ts

lib/ts-sdk/src/client/client.ts

lib/ts-sdk/README.md

lib/ts-sdk/__tests__/client/opportunities.spec.ts

Makes the function easier to reason about by moving some logic to a private fetchOnePage() method and moving the first page request out of the while loop

Accidentally dropped an `as const` in the withCustomFields() example

Previously it would error if `Client.opportunity.search()` returned no matching results because pageSize was expected to be > 0

widal001 added 5 commits February 19, 2026 11:29

refactor(ts-sdk): Fixes code smells in API client

d63d93c

- fetchMany() preserves metadata from first response - search() avoids an extra round trip to get response metadata

refactor(ts-sdk): Input for withCustomFields()

1f6a89a

Previously accepted CustomFieldSpec[] and used `CustomFieldSpec.key` to build the resulting customFields object. Now we expect Record<string,CustomFieldSpec> which more closely matches the final customFields object added to a schema

refactor(ts-sdk): Update and expand examples

436a061

docs(ts-sdk): Update READMEs

ac60203

- Fixes `withCustomFields()` examples in TS SDK README - Adds TS SDK to root-level README

github-actions bot added sdk Issue or PR related to our SDKs typescript Issue or PR related to TypeScript tooling ts-sdk Related to TypeScript SDK labels Feb 19, 2026

widal001 commented Feb 19, 2026

View reviewed changes

widal001 marked this pull request as ready for review February 19, 2026 19:14

widal001 requested a review from jcrichlake February 19, 2026 19:14

jcrichlake reviewed Feb 19, 2026

View reviewed changes

widal001 commented Feb 19, 2026

View reviewed changes

lib/ts-sdk/__tests__/client/opportunities.spec.ts Show resolved Hide resolved

widal001 added 4 commits February 19, 2026 17:02

test(ts-sdk): Make test names more descriptive

7989c7b

refactor(ts-sdk): Client.fetchMany()

9e12251

Makes the function easier to reason about by moving some logic to a private fetchOnePage() method and moving the first page request out of the while loop

doc(ts-sdk): Restores dropped as const in example

c8a77cf

Accidentally dropped an `as const` in the withCustomFields() example

fix(ts-sdk): Error thrown if search has no results

9a02a22

Previously it would error if `Client.opportunity.search()` returned no matching results because pageSize was expected to be > 0

jcrichlake approved these changes Feb 20, 2026

View reviewed changes

fix: Dependabot warnings in root workspace

b150f05

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

[Issue #497] Support custom fields in TS SDK client#522

[Issue #497] Support custom fields in TS SDK client#522
widal001 wants to merge 10 commits intomainfrom
issue-497-ts-sdk-client-support-custom-fields

widal001 commented Feb 19, 2026 •

edited

Loading

Uh oh!

widal001 Feb 19, 2026 •

edited

Loading

Uh oh!

widal001 Feb 19, 2026

Uh oh!

jcrichlake left a comment

Uh oh!

Uh oh!

jcrichlake Feb 19, 2026

Uh oh!

widal001 Feb 19, 2026 •

edited

Loading

Uh oh!

widal001 Feb 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		/** Optional display name; used as the default for CustomField.name when provided, otherwise the record key is used */
		name?: string;

Comments

Conversation

widal001 commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes proposed

Context for reviewers

Instructions for review

Notes

Additional information

Uh oh!

widal001 Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

widal001 Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

jcrichlake left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jcrichlake Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

widal001 Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

widal001 Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

widal001 commented Feb 19, 2026 •

edited

Loading

widal001 Feb 19, 2026 •

edited

Loading

widal001 Feb 19, 2026 •

edited

Loading