Go: export Ptr and Deref so consumers stop hand-rolling them

[jeremy]

v0.13.0 pointerized the optional fields across the Go surface (#560, #615, #632)
and shipped no way to build a pointer. ptr[T any] has been sitting unexported
at go/pkg/basecamp/helpers.go:313 the whole time, there is no exported
Ptr/String/Bool, and go/README.md said nothing about pointer fields. So
the release hands every Go consumer a pointer-shaped API and makes them write
their own generic helper before they can call it.

This SDK's own test suite is the proof. Four hand-rolled helpers, in a package
where the unexported ptr was already in scope:

helper	defined at	uses
strPtr	go/pkg/basecamp/schedules_test.go:756	21
boolPtr	go/pkg/basecamp/schedules_test.go:757	5
idsPtr	go/pkg/basecamp/schedules_test.go:758	3
intPtr	go/pkg/basecamp/test_helpers_test.go:84	5

If the people who wrote the pointer contract reached for a hand-rolled helper,
an external consumer has no chance.

Shape: one generic Ptr, not typed constructors

go.mod declares go 1.26, so generics are not in question — the choice is
purely about what reads best.

I counted the pointer-typed exported fields on the hand-written wrapper surface
(go/pkg/basecamp/*.go minus tests): 300 fields, spread over

• 6 distinct scalar types — *string 81, *bool 23, *time.Time 16,
  *int32 12, *int 10, *int64 9
• 14 pointer-to-slice fields — *[]RichTextAttachment 8, *[]int64 6
• 143 struct pointers — *Person 45, *Bucket 39, *Parent 29, and 30 others

An AWS-style typed set (String, Bool, Time, …) needs six names to cover
the scalar column alone — including three separate integer widths, which is
exactly the kind of near-miss API that gets picked wrong — and covers none
of the other 157 fields. UpdateScheduleEntryRequest.ParticipantIDs is
*[]int64 where a pointer to an empty slice is what removes every participant;
no typed constructor set reaches it. One generic Ptr covers all 300 with one
name to learn, and the next pointerized field for free.

The cost is that Ptr(5) infers *int and will not assign to an *int32
field. That is a compile error, not a silent bug, and the godoc says to write
Ptr(int32(5)). I took that over six names.

Worth noting from the cross-SDK survey: no other SDK needs an equivalent,
because each has a native mechanism for optional arguments — TS optional props,
Ruby/Python keyword defaults + compact, Kotlin T? = null ctor params, Swift
T? = nil init args. Go is the only one of the six where "send an explicit
false" costs the caller a named variable, which is why this gap exists here
and nowhere else.

Deref too — the read direction is the dangerous half

The migration guide's finding is that hc.UpdatedAt.IsZero() still compiles
against *time.Time, because Go auto-dereferences a value-receiver method call,
and panics at run time. That is a silent break with no compiler help at all, so
it belongs in the same PR as the fix for the loud half.

Deref[T any](p *T) T returns the zero value on nil. Its godoc is explicit that
collapsing absence to the zero value is only correct where the caller cannot
tell the two apart, and to compare against nil where the difference carries
meaning.

Before / after, real call sites

Write — SchedulesService.UpdateEntry, whose request struct is pointers end
to end (go/pkg/basecamp/schedules.go:195):

// Before — a named variable per field, or your own helper first.
summary := "Kickoff, moved"
allDay := false
participants := []int64{}

entry, err := account.Schedules().UpdateEntry(ctx, entryID, &basecamp.UpdateScheduleEntryRequest{
    Summary:        &summary,
    AllDay:         &allDay,       // an explicit false, not "unset"
    ParticipantIDs: &participants, // an explicit empty list: remove everyone
})

// After
entry, err := account.Schedules().UpdateEntry(ctx, entryID, &basecamp.UpdateScheduleEntryRequest{
    Summary:        basecamp.Ptr("Kickoff, moved"),
    AllDay:         basecamp.Ptr(false),
    ParticipantIDs: basecamp.Ptr([]int64{}),
})

Read — HillChart.UpdatedAt (go/pkg/basecamp/hill_charts.go:21), nil on a
chart that has never moved:

// Before — compiles, panics at run time.
if !hc.UpdatedAt.IsZero() { ... }

// Before, done correctly — every read site pays for it.
if hc.UpdatedAt != nil && !hc.UpdatedAt.IsZero() { ... }

// After
if updated := basecamp.Deref(hc.UpdatedAt); !updated.IsZero() { ... }

Additive

No existing exported signature changes, and nothing is removed or renamed.
Two new exported functions, plus doc/README/test additions. The only edits to
existing declarations are the two unexported helper bodies described below. This
adds nothing to v0.13.0's breaking surface.

The unexported ptr/deref stay, but forward

ptr and deref are the vocabulary at hundreds of internal conversion sites,
and rewriting those would be pure churn against actively-moving files. They keep
their names and now forward to the exported pair, so there is one definition of
each contract and the version consumers get cannot drift from the version this
package relies on. TestUnexportedSpellingsForwardToTheExportedOnes pins that.

The four hand-rolled test helpers are deliberately left alone here — they sit in
schedules_test.go, which #632/#636 have just been through, and this PR is not
worth a conflict with the spec train. They are cited above as evidence, and
retiring them is a clean follow-up.

Placement

New file go/pkg/basecamp/pointers.go rather than appending to helpers.go.
helpers.go is internal plumbing (error truncation, pageParam, ListMeta,
hasNextPage) that no consumer opens; a file named for the thing is where
someone looks. Discoverability is the actual failure mode here, so the guidance
lands in three places a Go consumer might start from:

• godoc on each symbol, with the real call sites above
• an # Optional Fields section in the package doc (doc.go) — the pkg.go.dev
  landing page
• an ## Optional Fields section in go/README.md — the gap the migration
  guide flagged by name

Runnable ExamplePtr and ExampleDeref in example_test.go, both with
// Output: so they actually execute rather than only compile.

Tests

Table-driven, go/pkg/basecamp/pointers_test.go:

• Ptr addresses the value including the zero value, across all six scalar
  types; addresses nil/empty/populated slices; returns a distinct pointer per
  call (a shared address would alias every request built in a loop)
• Deref returns the zero value for nil across *string, *bool, *int,
  *int64, *time.Time, *[]int64, and returns the pointed-at value
  otherwise — including an explicit false and an explicit ""
• the forwarding pin

The nil case is not vacuous. Replacing Deref's body with the naive
return *p and re-running:

=== RUN   TestDeref_ReturnsTheZeroValueForNilRatherThanPanicking
=== RUN   TestDeref_ReturnsTheZeroValueForNilRatherThanPanicking/*string
--- FAIL: TestDeref_ReturnsTheZeroValueForNilRatherThanPanicking (0.00s)
    --- FAIL: TestDeref_ReturnsTheZeroValueForNilRatherThanPanicking/*string (0.00s)
panic: runtime error: invalid memory address or nil pointer dereference [recovered, repanicked]
[signal SIGSEGV: segmentation violation code=0x2 addr=0x0 pc=0x1015e58bc]
...
github.com/basecamp/basecamp-sdk/go/pkg/basecamp.Deref[...](...)
	go/pkg/basecamp/pointers.go:51
FAIL	github.com/basecamp/basecamp-sdk/go/pkg/basecamp	0.344s
FAIL
REAL_EXIT=1

Verification

• make check (root, all gates) — green, REAL_EXIT grepped from the captured
  log, not echo $?
• make -C go check (fmt-check, vet, lint, test) — REAL_EXIT=0
• go test -race ./... — REAL_EXIT=0, all six packages ok
• go doc output for both symbols inspected; both examples execute and match
• PRE_SHA == POST_SHA across the full run, working tree clean throughout

---

Summary by cubic

Exported generic Ptr[T] and Deref[T] for Go to make optional pointer fields easy to set and read without hand-rolled helpers. Adds docs, examples, and tests, with internal helpers forwarding to the exported versions; no breaking changes.

• New Features
  • basecamp.Ptr[T](v) builds a pointer for any type, including zero values and slices.
  • basecamp.Deref[T](p) returns the zero value on nil to avoid panics when reading optional fields (e.g., HillChart.UpdatedAt).
  • Added “Optional Fields” guidance to go/README.md and package docs, plus runnable examples (ExamplePtr, ExampleDeref).
  • Kept unexported ptr/deref and made them forward to the exported functions; added tests to pin behavior across scalars, slices, nil, and distinct pointer allocation.

^{Written for commit a2cde1c. Summary will update on new commits.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.