Update GraphQL Schema

Updates the SDK's GraphQL schema and related types from an API server instance.

Usage

/schema-update local    # Download from local server
/schema-update staging  # Download from staging server
/schema-update          # Will prompt for server choice

Checklist

You MUST use TodoWrite to create a todo for EACH step below. Mark each complete only after verification.

Download Schema

• • Determine server source (from argument or ask user): local or staging
• • Run schema download from packages/graphql:
  • •Local: pnpm gql:download:local
  • •Staging: pnpm gql:download:staging
• • Run pnpm gql:generate:introspection to generate GraphQL documents

Update Documents

• • Cross-reference packages/graphql/schema.graphql with existing GQL documents
• • Add missing fields to existing fragments
• • Introduce new fragments if necessary
• • If new queries or mutations exist in schema, ask user if they should be added

Check for New Enums

• • Search for new enum definitions in packages/graphql/schema.graphql
• • For each new enum:
  • •Add enum definition to packages/graphql/src/enums.ts with JSDoc comments
  • •Import the enum type in packages/graphql/src/graphql.ts
  • •Add scalar binding in graphql config (alphabetically ordered)
• • Note: Do NOT create separate type exports for enums - the enum definition serves as both value and type

Export Input Types

• • Check for new input types in schema
• • Common types (used across multiple queries): export from packages/graphql/src/inputs.ts
• • Query-specific types: colocate with corresponding query files (permits.ts, transactions.ts, swaps.ts, user.ts, reserve.ts, hub.ts, misc.ts)
• • Use pattern: export type InputName = ReturnType<typeof graphql.scalar<'InputName'>>;
• • Exclude fork-related input types unless explicitly needed
• • Ensure scalar bindings exist in graphql.ts for all input types

Update URQL Cache Configuration

Update packages/client/src/cache.ts to handle new/removed types:

Keys Section

• • Add new types with id field: These should be normalized (cached by id)
  typescript

  NewTypeName: (data: NewTypeName) => data.id,
  

• • Add ephemeral types (value objects without stable identity): Return null to disable normalization
  typescript

  NewValueObject: () => null,
  

• • Remove deleted types: Remove any types that no longer exist in the schema
• • When unsure: If you're uncertain whether it needs normalization, ask the user

Resolvers Section

Add field transformers for enhanced client-side types:

• • DateTime fields: Transform to JavaScript Date objects
  typescript

  TypeName: {
    dateField: transformToDate,           // for non-nullable DateTime
    nullableDateField: transformToNullableDate,  // for nullable DateTime
  },
  

• • BigDecimal fields: Transform to BigDecimal class instances
  typescript

  TypeName: {
    decimalField: transformToBigDecimal,           // for non-nullable BigDecimal
    nullableDecimalField: transformToNullableBigDecimal,  // for nullable BigDecimal
  },
  

• • BigInt fields: Transform to native BigInt
  typescript

  TypeName: {
    bigIntField: transformToBigInt,
  },
  

Common Patterns

• •Activity types (*Activity) typically have timestamp: DateTime! → use transformToDate
• •Types with createdAt: DateTime (nullable) → use transformToNullableDate
• •Types with createdAt: DateTime! (non-nullable) → use transformToDate
• •Health factor types have nullable BigDecimal fields → use transformToNullableBigDecimal

Validate

• • Run pnpm check from packages/graphql to verify document integrity
• • Run pnpm build to ensure TypeScript compilation succeeds
• • Run pnpm test --run to verify tests pass
• • Run pnpm lint:fix to format code

Code Patterns

Enum Definition (enums.ts)

/**
 * Description of what this enum represents.
 */
export enum EnumName {
  /**
   * Description of this value
   */
  VALUE_ONE = 'VALUE_ONE',
  /**
   * Description of this value
   */
  VALUE_TWO = 'VALUE_TWO',
}

Scalar Binding (graphql.ts)

// Add to imports
import type { ..., EnumName } from './enums';

// Add to scalars config (alphabetically)
scalars: {
  ...
  EnumName: EnumName,
  ...
}

Input Type Export

export type InputName = ReturnType<typeof graphql.scalar<'InputName'>>;

Stop Conditions

Common Mistakes

1. •Creating type exports for enums - Enums are both values and types; don't use ReturnType<typeof graphql.scalar<'EnumName'>>
2. •Adding new queries/mutations without being asked - Only update existing documents unless explicitly requested
3. •Forgetting scalar bindings - Every input type needs a corresponding entry in graphql.ts
4. •Non-alphabetical ordering - Scalar bindings should be alphabetically ordered
5. •Missing JSDoc comments - All enums should have documentation
6. •Forgetting cache.ts updates - New types need keys configuration; types with DateTime/BigDecimal/BigInt need resolvers
7. •Wrong nullable transformer - Use transformToNullableDate/transformToNullableBigDecimal for nullable fields, non-nullable variants for required fields
8. •Missing type imports in cache.ts - Add imports for any new types used in the keys section