chore(docs): improve security documentation (#319)

Author: stainless-app[bot]

README.md

@@ -93,8 +93,8 @@ To send `null` instead of a struct, use `param.NullObj[T]()`, where `T` is a str
 To send a custom value instead of a struct, use `param.OverrideObj[T](value)`.
 
 To override request structs contain a `.WithExtraFields(map[string]any)` method which can be used to
-send non-conforming fields in the request body. Extra fields take higher precedence than normal
-fields.
+send non-conforming fields in the request body. Extra fields overwrite any struct fields with a matching
+key, so only use with trusted data.
 
 ```go
 params := FooParams{

option/requestoption.go

@@ -24,6 +24,8 @@ import (
 type RequestOption = requestconfig.RequestOption
 
 // WithBaseURL returns a RequestOption that sets the BaseURL for the client.
+//
+// For security reasons, ensure that the base URL is trusted.
 func WithBaseURL(base string) RequestOption {
 	u, err := url.Parse(base)
 	if err != nil {

packages/param/option.go

@@ -2,6 +2,7 @@ package param
 
 import (
 	"encoding/json"
+	"fmt"
 	"reflect"
 	"time"
 )
@@ -78,6 +79,16 @@ func (o Opt[T]) Or(v T) T {
 	return v
 }
 
+func (o Opt[T]) String() string {
+	if o.IsNull() {
+		return "null"
+	}
+	if s, ok := any(o.Value).(fmt.Stringer); ok {
+		return s.String()
+	}
+	return fmt.Sprintf("%v", o.Value)
+}
+
 // This is a sketchy way to implement time Formatting
 var timeType = reflect.TypeOf(time.Time{})
 var timeTimeValueLoc, _ = reflect.TypeOf(Opt[time.Time]{}).FieldByName("Value")

packages/param/param.go

@@ -94,8 +94,12 @@ func (m metadata) GetExtraFields() map[string]any {
 	return nil
 }
 
-func (m *metadata) WithExtraFields(fields map[string]any) {
-	m.any = metadataExtraFields(fields)
+// WithExtraFields adds extra fields to the JSON object.
+//
+// WithExtraFields will override any existing fields with the same key.
+// For security reasons, ensure this is only used with trusted input data.
+func (m *metadata) WithExtraFields(extraFields map[string]any) {
+	m.any = metadataExtraFields(extraFields)
 }
 
 func (m *metadata) setMetadata(override any) {