fix(proxy_record): symmetric domain normalisation, util test helpers

Two follow-ups on top of @JulienJBO's #74:

* Domain normalisation was applied on the write side
  (BuildCreateRequest -> normalizeProxyRecordDomain) but not on plan, so a
  user config of `Example.COM.` would plan as `Example.COM.` while state
  ended up at the API's canonical form `example.com`. This trips the
  framework's "Provider produced inconsistent result after apply" check on
  first apply, and triggers a permanent RequiresReplace loop on every
  subsequent plan. Added a stringplanmodifier
  (normalizeProxyRecordDomainPlanModifier) that runs the existing
  normaliser on the planned value so plan and state stay symmetric.
  Covered with a table-driven unit test for the modifier itself, plus a
  bumped assertion in TestProxyRecordResourceNameAndSchema for the new
  modifier slot.

* Local stringPtr / int64Ptr test helpers in both proxy_record test files
  replaced with util.StringPtr / util.Int64Ptr now that #83 has landed
  the centralised helpers; resource also uses util.PtrToInt64 in place of
  the inline nil-check for resp.CreatedBy.

Also: drop the `2026-04-21` date from the design note observation about
the retry endpoint — date-stamped probes age badly, so generalise to
"at the time of writing".

Author: vdekrijger

docs/notes/proxy-record-design.md

@@ -56,7 +56,7 @@ Recommended lifecycle behavior:
 - `Delete`: delete the record and rely on `404` handling for any later refresh.
 
 `retry` should not be part of the declarative CRUD contract. It is an operational remediation endpoint to be used after the user fixes DNS, not a stable desired-state transition.
-The live API probe on `2026-04-21` also showed that `POST /retry/` returns `403 permission_denied` when called with a Personal API Key, so it cannot be a reliable part of provider CRUD with the current authentication model.
+At the time of writing, `POST /retry/` also returns `403 permission_denied` when called with a Personal API Key, which rules it out of provider CRUD with the current authentication model.
 
 ## Why Acceptance Is The Real Blocker
 

docs/resources/proxy_record.md

@@ -30,7 +30,7 @@ output "analytics_proxy_target_cname" {
 
 ### Required
 
-- `domain` (String) The custom domain to provision in PostHog.
+- `domain` (String) The custom domain to provision in PostHog. Configured values are normalised to lowercase with no trailing dot, so `Example.COM.` and `example.com` plan as the same value.
 
 ### Optional
 

internal/httpclient/proxy_record_test.go

@@ -7,6 +7,7 @@ import (
 	"net/http/httptest"
 	"testing"
 
+	"github.com/posthog/terraform-provider/internal/util"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -29,7 +30,7 @@ func TestListProxyRecords(t *testing.T) {
 		assert.Equal(t, testProxyRecordsCollectionPath(), r.URL.Path)
 
 		resp := ProxyRecordListResponse{
-			MaxProxyRecords: int64Ptr(10),
+			MaxProxyRecords: util.Int64Ptr(10),
 			Results: []ProxyRecord{
 				{ID: testProxyRecordID, Domain: "a.example.com", TargetCNAME: "cname-1.proxyhog.com.", Status: "waiting"},
 				{ID: "proxy-2", Domain: "b.example.com", TargetCNAME: "cname-2.proxyhog.com.", Status: "valid"},
@@ -124,10 +125,6 @@ func writeJSONResponse(t *testing.T, w http.ResponseWriter, body any) {
 	require.NoError(t, json.NewEncoder(w).Encode(body))
 }
 
-func int64Ptr(v int64) *int64 {
-	return &v
-}
-
 func testProxyRecordsCollectionPath() string {
 	return apiOrganizationsPrefix + testOrganizationID + proxyRecordsPathSuffix
 }

internal/resource/proxy_record.go

@@ -14,6 +14,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/types"
 	"github.com/posthog/terraform-provider/internal/httpclient"
 	"github.com/posthog/terraform-provider/internal/resource/core"
+	"github.com/posthog/terraform-provider/internal/util"
 )
 
 func NewProxyRecord() resource.Resource {
@@ -49,9 +50,10 @@ func (o ProxyRecordOps) Schema() schema.Schema {
 			"organization_id": core.OrganizationIDSchemaAttribute(),
 			"domain": schema.StringAttribute{
 				Required:            true,
-				MarkdownDescription: "The custom domain to provision in PostHog.",
+				MarkdownDescription: "The custom domain to provision in PostHog. Configured values are normalised to lowercase with no trailing dot, so `Example.COM.` and `example.com` plan as the same value.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
+					normalizeProxyRecordDomainPlanModifier{},
 				},
 			},
 			"target_cname": proxyRecordComputedStringAttribute("The PostHog-managed CNAME target that your DNS record must point to."),
@@ -90,11 +92,7 @@ func (o ProxyRecordOps) MapResponseToModel(_ context.Context, resp httpclient.Pr
 	model.Message = core.PtrToStringNullIfEmptyTrimmed(resp.Message)
 	model.CreatedAt = core.PtrToStringNullIfEmptyTrimmed(resp.CreatedAt)
 	model.UpdatedAt = core.PtrToStringNullIfEmptyTrimmed(resp.UpdatedAt)
-	if resp.CreatedBy == nil {
-		model.CreatedBy = types.Int64Null()
-	} else {
-		model.CreatedBy = types.Int64Value(*resp.CreatedBy)
-	}
+	model.CreatedBy = util.PtrToInt64(resp.CreatedBy)
 
 	return diags
 }
@@ -119,6 +117,33 @@ func normalizeProxyRecordDomain(raw string) string {
 	return strings.ToLower(strings.TrimSuffix(strings.TrimSpace(raw), "."))
 }
 
+// normalizeProxyRecordDomainPlanModifier rewrites the planned `domain` value
+// through normalizeProxyRecordDomain before plan finalises. Without it, a config
+// of `Example.COM.` would plan as `Example.COM.` while state holds the API's
+// canonical form (`example.com`), which trips Terraform's "Provider produced
+// inconsistent result after apply" check on first apply and triggers a
+// permanent RequiresReplace loop on every subsequent plan.
+type normalizeProxyRecordDomainPlanModifier struct{}
+
+func (normalizeProxyRecordDomainPlanModifier) Description(_ context.Context) string {
+	return "Normalises the domain to lowercase with no trailing dot."
+}
+
+func (m normalizeProxyRecordDomainPlanModifier) MarkdownDescription(ctx context.Context) string {
+	return m.Description(ctx)
+}
+
+func (normalizeProxyRecordDomainPlanModifier) PlanModifyString(_ context.Context, req planmodifier.StringRequest, resp *planmodifier.StringResponse) {
+	if req.ConfigValue.IsNull() || req.ConfigValue.IsUnknown() {
+		return
+	}
+	normalized := normalizeProxyRecordDomain(req.ConfigValue.ValueString())
+	if normalized == req.PlanValue.ValueString() {
+		return
+	}
+	resp.PlanValue = types.StringValue(normalized)
+}
+
 func proxyRecordComputedStringAttribute(description string) schema.StringAttribute {
 	return schema.StringAttribute{
 		Computed:            true,

internal/resource/proxy_record_test.go

@@ -8,9 +8,11 @@ import (
 	"testing"
 
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/types"
 	"github.com/posthog/terraform-provider/internal/httpclient"
 	"github.com/posthog/terraform-provider/internal/resource/core"
+	"github.com/posthog/terraform-provider/internal/util"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -56,6 +58,55 @@ func TestNormalizeProxyRecordDomain(t *testing.T) {
 	}
 }
 
+func TestProxyRecordDomainPlanModifier(t *testing.T) {
+	tests := map[string]struct {
+		config           types.String
+		planBefore       types.String
+		expectedAfter    types.String
+		expectModified   bool
+		modifierExpected string
+	}{
+		"normalises mixed-case config": {
+			config:         types.StringValue("Proxy.Example.COM"),
+			planBefore:     types.StringValue("Proxy.Example.COM"),
+			expectedAfter:  types.StringValue(testNormalizedProxyRecordDomain),
+			expectModified: true,
+		},
+		"strips trailing dot": {
+			config:         types.StringValue(testNormalizedProxyRecordDomain + "."),
+			planBefore:     types.StringValue(testNormalizedProxyRecordDomain + "."),
+			expectedAfter:  types.StringValue(testNormalizedProxyRecordDomain),
+			expectModified: true,
+		},
+		"already canonical config is left alone": {
+			config:         types.StringValue(testNormalizedProxyRecordDomain),
+			planBefore:     types.StringValue(testNormalizedProxyRecordDomain),
+			expectedAfter:  types.StringValue(testNormalizedProxyRecordDomain),
+			expectModified: false,
+		},
+		"null config is a no-op": {
+			config:         types.StringNull(),
+			planBefore:     types.StringNull(),
+			expectedAfter:  types.StringNull(),
+			expectModified: false,
+		},
+	}
+
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			req := planmodifier.StringRequest{
+				ConfigValue: tc.config,
+				PlanValue:   tc.planBefore,
+			}
+			resp := planmodifier.StringResponse{PlanValue: tc.planBefore}
+
+			normalizeProxyRecordDomainPlanModifier{}.PlanModifyString(context.Background(), req, &resp)
+
+			assert.Equal(t, tc.expectedAfter, resp.PlanValue)
+		})
+	}
+}
+
 func TestProxyRecordBuildCreateRequest(t *testing.T) {
 	ops := ProxyRecordOps{}
 	req, diags := ops.BuildCreateRequest(context.Background(), ProxyRecordTFModel{
@@ -84,7 +135,7 @@ func TestProxyRecordResourceNameAndSchema(t *testing.T) {
 	domainAttr, ok := s.Attributes["domain"].(schema.StringAttribute)
 	require.True(t, ok, "domain must be a string attribute")
 	assert.True(t, domainAttr.Required)
-	require.Len(t, domainAttr.PlanModifiers, 1)
+	require.Len(t, domainAttr.PlanModifiers, 2, "domain should carry RequiresReplace and the normalize plan modifier")
 
 	targetAttr, ok := s.Attributes["target_cname"].(schema.StringAttribute)
 	require.True(t, ok, "target_cname must be a string attribute")
@@ -102,9 +153,9 @@ func TestProxyRecordMapResponseToModel(t *testing.T) {
 		Domain:      testNormalizedProxyRecordDomain,
 		TargetCNAME: testProxyRecordTargetCNAME,
 		Status:      testProxyRecordStatus,
-		CreatedAt:   stringPtr(testProxyRecordCreatedAt),
-		UpdatedAt:   stringPtr(testProxyRecordUpdatedAt),
-		CreatedBy:   int64Ptr(testProxyRecordCreatorID),
+		CreatedAt:   util.StringPtr(testProxyRecordCreatedAt),
+		UpdatedAt:   util.StringPtr(testProxyRecordUpdatedAt),
+		CreatedBy:   util.Int64Ptr(testProxyRecordCreatorID),
 	}
 
 	var model ProxyRecordTFModel
@@ -204,14 +255,6 @@ func TestProxyRecordUpdateReturnsError(t *testing.T) {
 	assert.Contains(t, err.Error(), "do not support updates")
 }
 
-func stringPtr(v string) *string {
-	return &v
-}
-
-func int64Ptr(v int64) *int64 {
-	return &v
-}
-
 func testProxyRecordCollectionPath() string {
 	return testProxyRecordAPIPathPrefix + testProxyRecordOrganizationID + testProxyRecordAPIPathSuffix
 }