v0.4.0¶

Release Date: 2026-06-08

Overview¶

This release adds GraphQL mutations for creating features and ideas, custom field support, and required field validation helpers. The handwritten GraphQL client has been moved to an example package for educational reference.

Highlights¶

Create Mutations - New mutations for creating features and ideas via GraphQL
Custom Field Support - Set custom field values on any record type
Required Field Validation - Helper functions to discover and validate required fields
Goauth Credentials - Support for goauth credentials file in integration tests

Installation¶

go get github.com/grokify/aha-go@v0.4.0

What's New¶

Create Mutations¶

Create features and ideas directly via GraphQL:

import (
    "github.com/grokify/aha-go/graphql"
    "github.com/grokify/aha-go/graphql/generated"
)

client := graphql.NewGenqlientClient("mycompany", "your-api-key")

// Create a feature in a release
resp, err := generated.CreateFeatureWithRelease(ctx, client,
    "My New Feature",           // name
    "RELEASE-ID",               // releaseId
    "<p>Description here</p>",  // description
    "tag1, tag2",               // tagList
    nil,                        // skipRequiredFieldsValidation
)
fmt.Printf("Created: %s\n", resp.CreateFeature.Feature.ReferenceNum)

// Create an idea
ideaResp, err := generated.CreateIdea(ctx, client,
    "New Idea",     // name
    "PROJECT-ID",   // projectId
    nil,            // skipRequiredFieldsValidation
)

Custom Field Support¶

Set custom fields on any record using the generic SetCustomFieldValues mutation:

// Set custom fields on a feature
resp, err := generated.SetCustomFieldValues(ctx, client,
    "FEATURE-ID",
    generated.CustomFieldableTypeEnumFeature,
    []generated.CustomFieldValueInput{
        {Key: "priority_score", Value: 85},
        {Key: "customer_segment", Value: "Enterprise"},
    },
)

Required Field Validation¶

Discover and validate required fields before creating records:

import "github.com/grokify/aha-go/graphql"

// Discover required fields for features in a project
reqs, err := graphql.GetFeatureRequirements(ctx, client, "EXISTING-FEATURE-ID")

// Get list of required field IDs
requiredIDs := reqs.RequiredFieldIDs()

// Get required custom field keys
customKeys := reqs.RequiredCustomFieldKeys()

// Check if a specific field is required
if reqs.IsRequired("description") {
    // Handle required field
}

// Validate that all required fields are provided
missing := graphql.ValidateRequiredFields(reqs, map[string]any{
    "name": "Feature Name",
    "description": "Description",
})
if len(missing) > 0 {
    fmt.Printf("Missing required fields: %v\n", missing)
}

Get Custom Field Definitions¶

Discover available custom fields for a project:

defs, err := graphql.GetProjectCustomFieldDefinitions(ctx, client, "PROJECT-ID")
for _, def := range defs {
    fmt.Printf("Field: %s (key: %s, type: %s)\n", def.Name, def.Key, def.Type)
    for _, opt := range def.Options {
        fmt.Printf("  Option: %s\n", opt.Name)
    }
}

New Queries¶

Query	Description
`GetFeatureScreenDefinition`	Get required fields configuration for features
`GetProjectCustomFields`	Get custom field definitions for a project
`GetFeatureWithCustomFields`	Get feature with its custom field values

New Mutations¶

Mutation	Description
`CreateFeatureWithRelease`	Create feature in a release
`CreateFeatureWithProject`	Create feature in a project
`CreateFeatureWithAssignments`	Create feature with full assignments
`CreateIdea`	Create an idea
`SetCustomFieldValues`	Set custom fields on any record

Package Restructuring¶

The handwritten GraphQL client has been moved to graphql/example as educational reference code:

// For production use (recommended)
import "github.com/grokify/aha-go/graphql/generated"

// For learning/reference only
import "github.com/grokify/aha-go/graphql/example"

Commits¶

Hash	Description
`31229b3`	chore(deps): update dependencies
`c30c035`	feat(graphql): add create mutations and SetCustomFieldValues
`504c1d5`	feat(graphql): add helper functions for required field validation
`b3a586a`	feat(graphql): add queries for required fields and custom fields
`c13bf26`	feat(test): add goauth credentials support for integration tests
`86232ae`	refactor(graphql): move handwritten client to example package
`28f8d7a`	docs: update GraphQL section with mutations and reference client note
`9223def`	feat(graphql): add mutation operations for features, ideas, and record links

Integration Test Credentials¶

Integration tests now support two credential patterns:

# Pattern 1: Direct environment variables
export AHA_SUBDOMAIN=mycompany
export AHA_API_KEY=your-api-key

# Pattern 2: Goauth credentials file
export GOAUTH_CREDENTIALS_FILE=/path/to/credentials.json
export GOAUTH_ACCOUNT=aha-production

Upgrade Notes¶

This is a backward-compatible release. The handwritten GraphQL client is now in graphql/example but the original import path will continue to work if you were using the manual client approach.

Contributors¶

@grokify