@stackonward/cli 1.6.0 → 1.8.0

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/codec.go

@@ -0,0 +1,33 @@
+package v1
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+
+	commonvalidator "{{module}}/internal/common/validator"
+)
+
+// DecodeStrict 拒绝重复字段、未知字段、空响应和多个 JSON 值。
+func DecodeStrict(body []byte, out any) error {
+	if len(bytes.TrimSpace(body)) == 0 || out == nil {
+		return fmt.Errorf("JSON body and decode target are required")
+	}
+	if err := commonvalidator.RejectDuplicateJSONFields(body); err != nil {
+		return err
+	}
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(out); err != nil {
+		return err
+	}
+	var trailing any
+	if err := decoder.Decode(&trailing); err != io.EOF {
+		if err == nil {
+			return fmt.Errorf("JSON body contains multiple values")
+		}
+		return err
+	}
+	return nil
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/error.go

@@ -0,0 +1,146 @@
+package v1
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"time"
+
+	"{{module}}/internal/core/httpclient"
+	"{{module}}/pkg/apierror"
+)
+
+// ErrorKind 是产品可安全分支处理的 OneX 边界错误闭集。
+type ErrorKind string
+
+const (
+	ErrorKindValidation      ErrorKind = "validation"
+	ErrorKindUnauthenticated ErrorKind = "unauthenticated"
+	ErrorKindForbidden       ErrorKind = "forbidden"
+	ErrorKindNotFound        ErrorKind = "not_found"
+	ErrorKindConflict        ErrorKind = "conflict"
+	ErrorKindRateLimited     ErrorKind = "rate_limited"
+	ErrorKindUnavailable     ErrorKind = "unavailable"
+	ErrorKindResultUnknown   ErrorKind = "result_unknown"
+	ErrorKindContract        ErrorKind = "contract"
+	ErrorKindCanceled        ErrorKind = "canceled"
+)
+
+// Error 保留稳定错误代码和重试语义，不向产品传播上游消息。
+type Error struct {
+	Kind       ErrorKind
+	ErrorType  string
+	Code       string
+	HTTPStatus int
+	Retryable  bool
+	RetryAfter string
+	// CurrentRegistrationRevision 仅保留安装能力已验证后的原生设备冲突恢复提示。
+	CurrentRegistrationRevision *int64
+	cause                       error
+}
+
+// Error 返回不含上游消息或秘密的稳定描述。
+func (e *Error) Error() string {
+	if e == nil {
+		return "onex request failed"
+	}
+	return fmt.Sprintf("onex request failed: kind=%s code=%s", e.Kind, e.Code)
+}
+
+// Unwrap 返回仅供错误链判断使用的底层原因。
+func (e *Error) Unwrap() error {
+	if e == nil {
+		return nil
+	}
+	return e.cause
+}
+
+// RetryAfterDelay 复用传输层对受控 Retry-After 的解析，供持久恢复安排下一次读取。
+func (e *Error) RetryAfterDelay(now time.Time) time.Duration {
+	if e == nil {
+		return 0
+	}
+	delay, _ := parseRetryAfter(e.RetryAfter, now)
+	return delay
+}
+
+// AffectsDependencyAvailability 区分业务拒绝与会降低依赖可用性的边界失败。
+func (e *Error) AffectsDependencyAvailability() bool {
+	if e == nil {
+		return false
+	}
+	switch e.Kind {
+	case ErrorKindRateLimited, ErrorKindUnavailable, ErrorKindResultUnknown, ErrorKindContract, ErrorKindUnauthenticated, ErrorKindForbidden:
+		return true
+	default:
+		return false
+	}
+}
+
+// NewValidationError 构造不会发起网络请求的边界校验错误。
+func NewValidationError(code string) *Error {
+	return &Error{Kind: ErrorKindValidation, Code: code}
+}
+
+// NewContractError 构造拒绝上游 schema 漂移的合同错误。
+func NewContractError(code string, cause error) *Error {
+	return &Error{Kind: ErrorKindContract, Code: code, cause: cause}
+}
+
+func decodeHTTPError(response *httpclient.Response) error {
+	kind, retryable := errorKindFromStatus(response.StatusCode)
+	result := &Error{
+		Kind:       kind,
+		ErrorType:  "",
+		Code:       "onex_request_failed",
+		HTTPStatus: response.StatusCode,
+		Retryable:  retryable,
+	}
+	fallbackCode := "onex_error_contract_invalid"
+	decoded := apierror.DecodeHTTPResponse(response.StatusCode, response.Headers, response.Body, apierror.New(http.StatusBadGateway, apierror.TypeAPI, fallbackCode, "Invalid OneX error contract"))
+	if decoded.Detail.Code == fallbackCode {
+		result.Kind = ErrorKindContract
+		result.Code = fallbackCode
+		return result
+	}
+	result.Code = decoded.Detail.Code
+	result.ErrorType = decoded.Detail.Type
+	result.RetryAfter = decoded.HTTPResponseMetadata().RetryAfter()
+	if result.Code == "native_device_revision_conflict" && response.StatusCode == http.StatusConflict {
+		for _, field := range decoded.Detail.Errors {
+			if field.Field != "current_registration_revision" {
+				continue
+			}
+			revision, err := strconv.ParseInt(field.Message, 10, 64)
+			if err != nil || revision < 1 || strconv.FormatInt(revision, 10) != field.Message || result.CurrentRegistrationRevision != nil {
+				result.Kind = ErrorKindContract
+				result.Code = "onex_error_contract_invalid"
+				result.CurrentRegistrationRevision = nil
+				return result
+			}
+			result.CurrentRegistrationRevision = &revision
+		}
+	}
+	return result
+}
+
+func errorKindFromStatus(status int) (ErrorKind, bool) {
+	switch status {
+	case http.StatusBadRequest, http.StatusUnprocessableEntity:
+		return ErrorKindValidation, false
+	case http.StatusUnauthorized:
+		return ErrorKindUnauthenticated, false
+	case http.StatusForbidden:
+		return ErrorKindForbidden, false
+	case http.StatusNotFound:
+		return ErrorKindNotFound, false
+	case http.StatusConflict:
+		return ErrorKindConflict, false
+	case http.StatusTooManyRequests:
+		return ErrorKindRateLimited, true
+	case http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
+		return ErrorKindUnavailable, true
+	default:
+		return ErrorKindContract, false
+	}
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/error_notification_test.go

@@ -0,0 +1,29 @@
+package v1
+
+import (
+	"fmt"
+	"net/http"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"{{module}}/internal/core/httpclient"
+)
+
+func TestNativeDeviceConflictOnlyAcceptsCanonicalPositiveRevision(t *testing.T) {
+	for _, value := range []string{"7", "0", "-1", "07", "token-secret"} {
+		t.Run(value, func(t *testing.T) {
+			err := decodeHTTPError(&httpclient.Response{StatusCode: http.StatusConflict, Headers: http.Header{"Content-Type": []string{"application/json"}}, Body: []byte(fmt.Sprintf(`{"error":{"type":"api_error","code":"native_device_revision_conflict","message":"private upstream text","errors":[{"field":"current_registration_revision","message":%q}]}}`, value))})
+			var result *Error
+			require.ErrorAs(t, err, &result)
+			if value == "7" {
+				require.NotNil(t, result.CurrentRegistrationRevision)
+				require.EqualValues(t, 7, *result.CurrentRegistrationRevision)
+			} else {
+				require.Nil(t, result.CurrentRegistrationRevision)
+				require.Equal(t, ErrorKindContract, result.Kind)
+			}
+			require.NotContains(t, result.Error(), "private upstream text")
+		})
+	}
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/notification/client.go

@@ -0,0 +1,132 @@
+package notification
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+	"time"
+
+	onexv1 "{{module}}/internal/integrations/onex/v1"
+)
+
+// Transport 借用已有 OneX 传输，不创建签名或连接生命周期。
+type Transport interface {
+	Do(context.Context, onexv1.Call, any) error
+}
+
+// Client 借用统一 transport 执行平台既有通知协议。
+type Client struct {
+	transport Transport
+	timeout   time.Duration
+}
+
+// NewClient 仅保存依赖，构造过程不会发送通知或访问网络。
+func NewClient(transport Transport, timeout time.Duration) (*Client, error) {
+	if transport == nil || timeout <= 0 {
+		return nil, fmt.Errorf("notification transport and timeout are required")
+	}
+	return &Client{transport: transport, timeout: timeout}, nil
+}
+
+// QueryInbox 查询原生收件箱，不裁剪过滤条件或展示字段。
+func (c *Client) QueryInbox(ctx context.Context, request InboxQuery) (InboxPage, error) {
+	var result InboxPage
+	err := c.call(ctx, http.MethodPost, "/native-notifications/inbox-queries", request.UserID, request, nil, http.StatusOK, "native_write", &result)
+	return result, err
+}
+
+// GetMessage 读取接收人的精确消息，不允许路径段穿越。
+func (c *Client) GetMessage(ctx context.Context, userID int64, messageNo string) (InboxMessage, error) {
+	var result InboxMessage
+	if len(messageNo) < 5 || len(messageNo) > 40 || messageNo != strings.TrimSpace(messageNo) || strings.ContainsAny(messageNo, "/\\%?#\x00\r\n") {
+		return result, onexv1.NewValidationError("onex_notification_message_invalid")
+	}
+	err := c.call(ctx, http.MethodGet, "/native-notifications/inbox-messages/"+url.PathEscape(messageNo), userID, nil, userQuery(userID), http.StatusOK, "native_read", &result)
+	return result, err
+}
+
+// CountUnread 返回原生未读汇总。
+func (c *Client) CountUnread(ctx context.Context, request InboxQuery) (Unread, error) {
+	var result Unread
+	err := c.call(ctx, http.MethodPost, "/native-notifications/unread-queries", request.UserID, request, nil, http.StatusOK, "native_write", &result)
+	return result, err
+}
+
+// AcknowledgeMessages 只确认请求中的消息版本。
+func (c *Client) AcknowledgeMessages(ctx context.Context, request AcknowledgeMessagesRequest) (Acknowledgement, error) {
+	var result Acknowledgement
+	err := c.call(ctx, http.MethodPost, "/native-notifications/message-acknowledgements", request.UserID, request, nil, http.StatusOK, "native_write", &result)
+	return result, err
+}
+
+// AcknowledgeScope 确认调用方显式指定的原生查询范围。
+func (c *Client) AcknowledgeScope(ctx context.Context, request InboxQuery) (Acknowledgement, error) {
+	var result Acknowledgement
+	err := c.call(ctx, http.MethodPost, "/native-notifications/acknowledgements", request.UserID, request, nil, http.StatusOK, "native_write", &result)
+	return result, err
+}
+
+// RegisterDevice 透传可信账号与会话，保留安装版本冲突。
+func (c *Client) RegisterDevice(ctx context.Context, request DeviceRegistration) (Device, error) {
+	var result Device
+	err := c.call(ctx, http.MethodPost, "/native-notifications/devices", request.UserID, request, nil, http.StatusCreated, "native_write", &result)
+	return result, err
+}
+
+// RevokeDevice 以安装能力注销，不携带账号会话。
+func (c *Client) RevokeDevice(ctx context.Context, request DeviceRevocation) error {
+	return c.call(ctx, http.MethodPost, "/native-notifications/device-revocations", 0, request, nil, http.StatusNoContent, "native_write", nil)
+}
+
+// ListDevices 查询接收人的有效设备列表。
+func (c *Client) ListDevices(ctx context.Context, userID int64) (DeviceList, error) {
+	var result DeviceList
+	err := c.call(ctx, http.MethodGet, "/native-notifications/devices", userID, nil, userQuery(userID), http.StatusOK, "native_read", &result)
+	return result, err
+}
+
+// GetPreferences 按调用方提供的分类和默认值读取偏好。
+func (c *Client) GetPreferences(ctx context.Context, request PreferenceQuery) (PushPreferences, error) {
+	var result PushPreferences
+	err := c.call(ctx, http.MethodPost, "/native-notifications/push-preference-queries", request.UserID, request, nil, http.StatusOK, "native_write", &result)
+	return result, err
+}
+
+// PutPreferences 返回平台接受的完整偏好。
+func (c *Client) PutPreferences(ctx context.Context, request PreferenceUpdate) (PushPreferences, error) {
+	var result PushPreferences
+	err := c.call(ctx, http.MethodPut, "/native-notifications/push-preferences", request.UserID, request, nil, http.StatusOK, "native_write", &result)
+	return result, err
+}
+
+// SendTestPush 只执行调用方显式请求，平台仍校验诊断权限与运行环境。
+func (c *Client) SendTestPush(ctx context.Context, request TestPushRequest) (TestPushResult, error) {
+	var result TestPushResult
+	err := c.call(ctx, http.MethodPost, "/native-notifications/test-push-sends", request.UserID, request, nil, http.StatusOK, "native_write", &result)
+	return result, err
+}
+
+// StartDispatch 提交冻结的产品事实，不选择模板或提供商。
+func (c *Client) StartDispatch(ctx context.Context, request DispatchStartRequest) (DispatchStartResult, error) {
+	var result DispatchStartResult
+	err := c.call(ctx, http.MethodPost, "/notifications/dispatch-command-starts", 0, request, nil, http.StatusCreated, "dispatch_command_start", &result)
+	return result, err
+}
+
+// AdvanceSource 推进产品事项版本，使旧通知失效。
+func (c *Client) AdvanceSource(ctx context.Context, request SourceAdvanceRequest) (SourceAdvanceResult, error) {
+	var result SourceAdvanceResult
+	err := c.call(ctx, http.MethodPost, "/notifications/source-state-advancements", 0, request, nil, http.StatusOK, "advance_source_state", &result)
+	return result, err
+}
+
+func (c *Client) call(ctx context.Context, method, path string, userID int64, body any, query url.Values, status int, operation string, out any) error {
+	return c.transport.Do(ctx, onexv1.Call{Method: method, Path: path, UserID: userID, Body: body, Query: query, ExpectedStatuses: []int{status}, Dependency: "notification", Operation: operation, Timeout: c.timeout}, out)
+}
+
+func userQuery(userID int64) url.Values {
+	return url.Values{"user_id": {strconv.FormatInt(userID, 10)}}
+}

package/dist/resources/templates/go-backend/internal/integrations/onex/v1/notification/client_test.go

@@ -0,0 +1,222 @@
+package notification
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/httpclient"
+	onexv1 "{{module}}/internal/integrations/onex/v1"
+)
+
+type wireSigner struct{}
+
+func (wireSigner) AuthHeaders(context.Context) (map[string]string, error) {
+	return map[string]string{"Authorization": "Bearer local-contract-test"}, nil
+}
+func (wireSigner) AuthorizeRequest(context.Context, *http.Request) error { return nil }
+
+const wireMessage = `{"delivery_id":10,"message_id":11,"message_no":"inm_sample","source_version":3,"title":"Status","subtitle":"Detail","content":"Ready","cover_url":"https://example.com/cover.png","action_url":"https://example.com/orders/one","category":"transactional","metadata":{"topic":"order"},"status":"unread","target_ref":"order:one","target_kind":"order","read_at":"2026-10-15T00:00:00Z","delivered_at":"2026-10-14T00:00:00Z","created_at":"2026-10-14T00:00:00Z","updated_at":"2026-10-15T00:00:00Z"}`
+const wireDevice = `{"id":7,"installation_id":"7b5dbd2e-c08c-4c09-b03a-e43ac0a70c60","application_code":"mobile","environment":"production","registration_revision":4,"provider":"fcm","platform":"android","app_version":"1.0","device_model":"phone","os_version":"16","status":"active","last_active_at":"2026-10-15T00:00:00Z","created_at":"2026-10-14T00:00:00Z"}`
+const wirePreferences = `{"enabled":false,"categories":{"orders":true,"offers":false},"quiet_hours":{"enabled":true,"start":"21:00","end":"07:00","timezone":"Asia/Tokyo"}}`
+const wireQuery = `{"user_id":42,"categories":["orders"],"target_ref":"order:one","target_scope":"any","read_status":"unread","delivery_ids":[10],"message_ids":[11],"page":2,"page_size":20}`
+const wireSource = `{"id":"d5812c28-9907-4a7c-8b9a-09317f1c9673","type":"orders.ready","subject_ref":"order:one","subject_version":3,"occurred_at":"2026-10-15T00:00:00Z"}`
+
+func TestClientCompleteNativeWireForTwoProducts(t *testing.T) {
+	query := InboxQuery{UserID: 42, Categories: []string{"orders"}, TargetRef: "order:one", TargetScope: "any", ReadStatus: "unread", DeliveryIDs: []int64{10}, MessageIDs: []int64{11}, Page: 2, PageSize: 20}
+	prefs := PushPreferences{Enabled: false, Categories: map[string]bool{"orders": true, "offers": false}, QuietHours: QuietHours{Enabled: true, Start: "21:00", End: "07:00", Timezone: "Asia/Tokyo"}}
+	source := SourceEvent{ID: "d5812c28-9907-4a7c-8b9a-09317f1c9673", Type: "orders.ready", SubjectRef: "order:one", SubjectVersion: 3, OccurredAt: time.Date(2026, 10, 15, 0, 0, 0, 0, time.UTC)}
+	registration := DeviceRegistration{UserID: 42, SessionID: 81, ApplicationCode: "mobile", Environment: "production", InstallationID: "7b5dbd2e-c08c-4c09-b03a-e43ac0a70c60", InstallationKey: "private-installation-key", RegistrationRevision: 4, DeviceToken: "private-device-token", Platform: "android", Provider: "fcm", AppVersion: "1.0", DeviceModel: "phone", OSVersion: "16"}
+	revocation := DeviceRevocation{ApplicationCode: "mobile", Environment: "production", InstallationID: registration.InstallationID, InstallationKey: registration.InstallationKey, RegistrationRevision: 5}
+	tests := []struct {
+		name, method, path, query, user, body, response string
+		status                                          int
+		call                                            func(context.Context, *Client) (any, error)
+	}{
+		{"inbox", http.MethodPost, "/native-notifications/inbox-queries", "", "42", wireQuery, `{"items":[` + wireMessage + `],"total":1,"unread_count":1,"unread_summary":{"orders":1}}`, 200,
+			func(ctx context.Context, c *Client) (any, error) { return c.QueryInbox(ctx, query) }},
+		{"message", http.MethodGet, "/native-notifications/inbox-messages/inm_sample", "user_id=42", "42", "", wireMessage, 200,
+			func(ctx context.Context, c *Client) (any, error) { return c.GetMessage(ctx, 42, "inm_sample") }},
+		{"unread", http.MethodPost, "/native-notifications/unread-queries", "", "42", wireQuery, `{"unread_count":1,"unread_summary":{"orders":1}}`, 200,
+			func(ctx context.Context, c *Client) (any, error) { return c.CountUnread(ctx, query) }},
+		{"message acknowledgement", http.MethodPost, "/native-notifications/message-acknowledgements", "", "42", `{"user_id":42,"messages":[{"message_no":"inm_sample","source_version":3}]}`, `{"updated":1,"unread_count":0,"unread_summary":{"orders":0}}`, 200,
+			func(ctx context.Context, c *Client) (any, error) {
+				return c.AcknowledgeMessages(ctx, AcknowledgeMessagesRequest{UserID: 42, Messages: []MessageVersion{{MessageNo: "inm_sample", SourceVersion: 3}}})
+			}},
+		{"scope acknowledgement", http.MethodPost, "/native-notifications/acknowledgements", "", "42", wireQuery, `{"updated":1,"unread_count":0,"unread_summary":{"orders":0}}`, 200,
+			func(ctx context.Context, c *Client) (any, error) { return c.AcknowledgeScope(ctx, query) }},
+		{"register", http.MethodPost, "/native-notifications/devices", "", "42", `{"user_id":42,"session_id":81,"application_code":"mobile","environment":"production","installation_id":"7b5dbd2e-c08c-4c09-b03a-e43ac0a70c60","installation_key":"private-installation-key","registration_revision":4,"device_token":"private-device-token","platform":"android","provider":"fcm","app_version":"1.0","device_model":"phone","os_version":"16"}`, wireDevice, 201,
+			func(ctx context.Context, c *Client) (any, error) { return c.RegisterDevice(ctx, registration) }},
+		{"revoke", http.MethodPost, "/native-notifications/device-revocations", "", "", `{"application_code":"mobile","environment":"production","installation_id":"7b5dbd2e-c08c-4c09-b03a-e43ac0a70c60","installation_key":"private-installation-key","registration_revision":5}`, "", 204,
+			func(ctx context.Context, c *Client) (any, error) { return nil, c.RevokeDevice(ctx, revocation) }},
+		{"devices", http.MethodGet, "/native-notifications/devices", "user_id=42", "42", "", `{"devices":[` + wireDevice + `]}`, 200,
+			func(ctx context.Context, c *Client) (any, error) { return c.ListDevices(ctx, 42) }},
+		{"preferences", http.MethodPost, "/native-notifications/push-preference-queries", "", "42", `{"user_id":42,"categories":["orders","offers"],"defaults":` + wirePreferences + `}`, wirePreferences, 200,
+			func(ctx context.Context, c *Client) (any, error) {
+				return c.GetPreferences(ctx, PreferenceQuery{UserID: 42, Categories: []string{"orders", "offers"}, Defaults: prefs})
+			}},
+		{"update preferences", http.MethodPut, "/native-notifications/push-preferences", "", "42", `{"user_id":42,"preferences":` + wirePreferences + `}`, wirePreferences, 200,
+			func(ctx context.Context, c *Client) (any, error) {
+				return c.PutPreferences(ctx, PreferenceUpdate{UserID: 42, Preferences: prefs})
+			}},
+		{"explicit diagnostic", http.MethodPost, "/native-notifications/test-push-sends", "", "42", `{"user_id":42,"title":"Diagnostic","body":"Explicit test","device_ids":[7]}`, `{"succeeded":1,"failed":0}`, 200,
+			func(ctx context.Context, c *Client) (any, error) {
+				return c.SendTestPush(ctx, TestPushRequest{UserID: 42, Title: "Diagnostic", Body: "Explicit test", DeviceIDs: []int64{7}})
+			}},
+		{"start", http.MethodPost, "/notifications/dispatch-command-starts", "", "", `{"source_event":` + wireSource + `,"command_key":"orders.ready","channel":"in_app","context":{"type":"product_event","reference":"order:one:revision:3"},"recipient":{"user_public_id":"usr_recipient"},"locale":"en","target":{"kind":"order","reference":"order:one"},"business_variables":{"order_no":"one","quantity":2}}`, `{"command_uid":"ndc_one","status":"pending","expires_at":"2026-10-16T00:00:00Z","replay":true}`, 201,
+			func(ctx context.Context, c *Client) (any, error) {
+				return c.StartDispatch(ctx, DispatchStartRequest{SourceEvent: source, CommandKey: "orders.ready", Channel: "in_app", Context: InputContext{Type: "product_event", Reference: "order:one:revision:3"}, Recipient: Recipient{UserPublicID: "usr_recipient"}, Locale: "en", Target: Target{Kind: "order", Reference: "order:one"}, BusinessVariables: map[string]any{"order_no": "one", "quantity": 2}})
+			}},
+		{"advance", http.MethodPost, "/notifications/source-state-advancements", "", "", `{"source_event":` + wireSource + `,"recipient":{"user_public_id":"usr_recipient"}}`, `{"status":"superseded","source_version":4}`, 200,
+			func(ctx context.Context, c *Client) (any, error) {
+				return c.AdvanceSource(ctx, SourceAdvanceRequest{SourceEvent: source, Recipient: Recipient{UserPublicID: "usr_recipient"}})
+			}},
+	}
+	require.Len(t, tests, 13)
+	for _, product := range []string{"sample_shop", "sample_media"} {
+		for _, test := range tests {
+			t.Run(product+"/"+test.name, func(t *testing.T) {
+				var requests atomic.Int32
+				server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					requests.Add(1)
+					require.Equal(t, test.method, r.Method)
+					require.Equal(t, "/internal/v1"+test.path, r.URL.Path)
+					require.Equal(t, test.query, r.URL.RawQuery)
+					require.Equal(t, product, r.Header.Get(types.HeaderOneXProductCode))
+					require.Equal(t, test.user, r.Header.Get(types.HeaderInternalUserID))
+					require.Equal(t, "Bearer local-contract-test", r.Header.Get("Authorization"))
+					require.Empty(t, r.Header.Get("X-Session-ID"))
+					require.Empty(t, r.Header.Get("Cookie"))
+					raw, err := io.ReadAll(r.Body)
+					require.NoError(t, err)
+					if test.body == "" {
+						require.Empty(t, raw)
+					} else {
+						require.JSONEq(t, test.body, string(raw))
+					}
+					w.Header().Set("Content-Type", "application/json")
+					w.WriteHeader(test.status)
+					_, err = w.Write([]byte(test.response))
+					require.NoError(t, err)
+				}))
+				t.Cleanup(server.Close)
+				transport, err := onexv1.NewClient(httpclient.New(zap.NewNop()), wireSigner{}, onexv1.Config{BaseURL: server.URL + "/internal/v1", ProductCode: product, Timeout: time.Second})
+				require.NoError(t, err)
+				client, err := NewClient(transport, time.Second)
+				require.NoError(t, err)
+				require.Zero(t, requests.Load())
+				result, err := test.call(t.Context(), client)
+				require.NoError(t, err)
+				require.EqualValues(t, 1, requests.Load())
+				if test.response != "" {
+					raw, err := json.Marshal(result)
+					require.NoError(t, err)
+					require.JSONEq(t, test.response, string(raw))
+				} else {
+					require.Nil(t, result)
+				}
+			})
+		}
+	}
+}
+
+func TestClientPreservesTypedErrorsAndDoesNotRetryWrites(t *testing.T) {
+	for _, test := range []struct {
+		name, body, code string
+		status           int
+		kind             onexv1.ErrorKind
+	}{
+		{"device revision", `{"error":{"type":"invalid_request_error","code":"native_device_revision_conflict","message":"private-device-token","errors":[{"field":"current_registration_revision","message":"9"}]}}`, "native_device_revision_conflict", 409, onexv1.ErrorKindConflict},
+		{"source superseded", `{"error":{"type":"invalid_request_error","code":"notification_source_superseded","message":"private-device-token"}}`, "notification_source_superseded", 409, onexv1.ErrorKindConflict},
+		{"unknown field", `{"id":7,"unexpected":true}`, "onex_response_contract_invalid", 201, onexv1.ErrorKindContract},
+		{"connection closed", "", "onex_result_unknown", 0, onexv1.ErrorKindResultUnknown},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			var requests atomic.Int32
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				requests.Add(1)
+				if test.status == 0 {
+					connection, _, err := w.(http.Hijacker).Hijack()
+					require.NoError(t, err)
+					require.NoError(t, connection.Close())
+					return
+				}
+				w.Header().Set("Content-Type", "application/json")
+				w.WriteHeader(test.status)
+				_, err := w.Write([]byte(test.body))
+				require.NoError(t, err)
+			}))
+			t.Cleanup(server.Close)
+			transport, err := onexv1.NewClient(httpclient.New(zap.NewNop()), wireSigner{}, onexv1.Config{BaseURL: server.URL + "/internal/v1", ProductCode: "sample_shop", Timeout: time.Second, SafeReadRetry: onexv1.SafeReadRetryConfig{MaxRetries: 2, InitialBackoff: time.Nanosecond, MaxBackoff: time.Nanosecond}})
+			require.NoError(t, err)
+			client, err := NewClient(transport, time.Second)
+			require.NoError(t, err)
+			_, err = client.RegisterDevice(t.Context(), DeviceRegistration{UserID: 42, DeviceToken: "private-device-token"})
+			var upstream *onexv1.Error
+			require.ErrorAs(t, err, &upstream)
+			require.Equal(t, test.kind, upstream.Kind)
+			require.Equal(t, test.code, upstream.Code)
+			require.NotContains(t, upstream.Error(), "private-device-token")
+			if test.name == "device revision" {
+				require.NotNil(t, upstream.CurrentRegistrationRevision)
+				require.EqualValues(t, 9, *upstream.CurrentRegistrationRevision)
+			}
+			require.EqualValues(t, 1, requests.Load())
+		})
+	}
+}
+
+type wireCapture struct {
+	calls []onexv1.Call
+	err   error
+}
+
+func (c *wireCapture) Do(_ context.Context, call onexv1.Call, _ any) error {
+	c.calls = append(c.calls, call)
+	return c.err
+}
+
+func TestClientConstructionPathAndOperationBoundaries(t *testing.T) {
+	_, err := NewClient(nil, time.Second)
+	require.Error(t, err)
+	_, err = NewClient(&wireCapture{}, 0)
+	require.Error(t, err)
+	upstream := &onexv1.Error{Kind: onexv1.ErrorKindUnavailable, Code: "onex_dependency_unavailable"}
+	transport := &wireCapture{err: upstream}
+	client, err := NewClient(transport, 3*time.Second)
+	require.NoError(t, err)
+	for _, number := range []string{"", "..", "../inm_sample", "inm_sample/other", "inm_%2f", "inm_a?b", "inm_a\nb"} {
+		_, err := client.GetMessage(t.Context(), 42, number)
+		var typed *onexv1.Error
+		require.ErrorAs(t, err, &typed)
+		require.Equal(t, onexv1.ErrorKindValidation, typed.Kind)
+	}
+	require.Empty(t, transport.calls)
+	_, err = client.QueryInbox(t.Context(), InboxQuery{UserID: 42, TargetScope: "any"})
+	require.True(t, errors.Is(err, upstream))
+	require.Equal(t, "native_write", transport.calls[0].Operation)
+	require.Equal(t, "notification", transport.calls[0].Dependency)
+	require.Equal(t, 3*time.Second, transport.calls[0].Timeout)
+	_, err = client.AcknowledgeMessages(t.Context(), AcknowledgeMessagesRequest{UserID: 42})
+	require.ErrorIs(t, err, upstream)
+	require.Equal(t, "native_write", transport.calls[1].Operation)
+	_, err = client.StartDispatch(t.Context(), DispatchStartRequest{})
+	require.ErrorIs(t, err, upstream)
+	require.Equal(t, "dispatch_command_start", transport.calls[2].Operation)
+	_, err = client.AdvanceSource(t.Context(), SourceAdvanceRequest{})
+	require.ErrorIs(t, err, upstream)
+	require.Equal(t, "advance_source_state", transport.calls[3].Operation)
+	_, err = client.GetMessage(t.Context(), 42, "inm_sample")
+	require.ErrorIs(t, err, upstream)
+	require.Equal(t, "native_read", transport.calls[4].Operation)
+}