Introduce stripe.RawRequest as a canonical way to request APIs without definitions

README.md

@@ -529,6 +529,22 @@ To install a beta version of stripe-go use the commit notation of the `go get` c
 go get -u github.com/stripe/stripe-go/[email protected]
 ```
 
+### Custom SDKs
+If you would like to send a request to an undocumented API (for example you are in a private beta), or if you prefer to bypass the method definitions in the library and specify your request details directly, you can use the `RawRequest` method on the `stripe` backend.
+
+```go
+key := "sk_test_xyz" // set to "" to use stripe.Key
+content := `foo=myFoo&bar[]=true` // form-encoded POST body
+
+resp, err := stripe.RawRequest("POST", "/v1/beta_endpoint", content, nil)
+
+response, err := stripe.RawRequest(http.MethodPost, "/v1/beta_endpoint", key, content, params)
+
+// Optionally use json.Unmarshal to convert the response to a strongly-typed object.
+deserializedResponse := &MyResource{}
+err = json.Unmarshal(response.RawJSON, deserializedResponse)
+```
+
 > **Note**
 > There can be breaking changes between beta versions. 
 

api_version.go

@@ -7,5 +7,6 @@
 package stripe
 
 const (
-	apiVersion string = "2022-11-15"
+	apiVersion     string = "2022-11-15"
+	previewVersion string = "2023-05-16.preview-v2"
 )

params.go

@@ -170,6 +170,11 @@ type ListParamsContainer interface {
 	GetListParams() *ListParams
 }
 
+type APIMode string
+
+var PreviewAPIMode APIMode = "preview"
+var StandardAPIMode APIMode = "standard"
+
 // Params is the structure that contains the common properties
 // of any *Params structure.
 type Params struct {
@@ -246,6 +251,29 @@ type ParamsContainer interface {
 	GetParams() *Params
 }
 
+type RawParams struct {
+	Params        `form:"*"`
+	APIMode       APIMode `form:"-"`
+	StripeContext string  `form:"-"`
+}
+
+func (p *RawParams) GetAPIMode() APIMode {
+	if p.APIMode == "" {
+		return StandardAPIMode
+	}
+	return p.APIMode
+}
+
+func (p *RawParams) GetStripeContext() string {
+	return p.StripeContext
+}
+
+type RawParamsContainer interface {
+	ParamsContainer
+	GetAPIMode() APIMode
+	GetStripeContext() string
+}
+
 // RangeQueryParams are a set of generic request parameters that are used on
 // list endpoints to filter their results by some timestamp.
 type RangeQueryParams struct {

preview/client.go

@@ -0,0 +1,27 @@
+// Package preview provides preview / private beta APIs
+package preview
+
+import (
+	"net/http"
+
+	stripe "github.com/stripe/stripe-go/v74"
+)
+
+func GetDefaultRequestOptions(params stripe.RawParamsContainer) stripe.RawParamsContainer {
+	rawParams := stripe.RawParams{
+		Params:        *params.GetParams(),
+		APIMode:       stripe.PreviewAPIMode,
+		StripeContext: params.GetStripeContext(),
+	}
+	return &rawParams
+}
+
+func Get(path string, params stripe.RawParamsContainer) (*stripe.APIResponse, error) {
+	return stripe.RawRequest(http.MethodGet, path, "", GetDefaultRequestOptions(params))
+}
+func Post(path, content string, params stripe.RawParamsContainer) (*stripe.APIResponse, error) {
+	return stripe.RawRequest(http.MethodPost, path, content, params)
+}
+func Delete(path string, params stripe.RawParamsContainer) (*stripe.APIResponse, error) {
+	return stripe.RawRequest(http.MethodDelete, path, "", params)
+}

preview/client_test.go

@@ -0,0 +1,73 @@
+package preview
+
+import (
+	"io/ioutil"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	assert "github.com/stretchr/testify/require"
+	stripe "github.com/stripe/stripe-go/v74"
+	_ "github.com/stripe/stripe-go/v74/testing"
+)
+
+func stubAPIBackend(testServer *httptest.Server) {
+	backend := stripe.GetBackendWithConfig(
+		stripe.APIBackend,
+		&stripe.BackendConfig{
+			LeveledLogger: &stripe.LeveledLogger{
+				Level: stripe.LevelDebug,
+			},
+			MaxNetworkRetries: stripe.Int64(0),
+			URL:               stripe.String(testServer.URL),
+		},
+	).(*stripe.BackendImplementation)
+
+	stripe.SetBackend(stripe.APIBackend, backend)
+}
+
+func TestPreviewRequestWithAdditionalHeaders(t *testing.T) {
+	var body string
+	var path string
+	var method string
+	var contentType string
+	var stripeVersion string
+	var fooHeader string
+	var stripeContext string
+	testServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		req, _ := ioutil.ReadAll(r.Body)
+		r.Body.Close()
+		body = string(req)
+		path = r.URL.RequestURI()
+		method = r.Method
+		contentType = r.Header.Get("Content-Type")
+		stripeVersion = r.Header.Get("Stripe-Version")
+		fooHeader = r.Header.Get("foo")
+		stripeContext = r.Header.Get("Stripe-Context")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"object": "abc", "xyz": {"def": "jih"}}`))
+	}))
+
+	stubAPIBackend(testServer)
+
+	type myParams struct {
+		stripe.Params    `form:"-"`
+		stripe.RawParams `form:"-"`
+	}
+
+	params := myParams{stripe.Params{Headers: http.Header{"foo": []string{"bar"}}}, stripe.RawParams{StripeContext: "acct_123"}}
+
+	_, err := Get("/v1/abc", &params)
+	assert.NoError(t, err)
+
+	assert.Equal(t, stripe.APIMode(""), params.RawParams.APIMode)
+	assert.Equal(t, ``, body)
+	assert.Equal(t, `/v1/abc`, path)
+	assert.Equal(t, `GET`, method)
+	assert.Equal(t, `application/json`, contentType)
+	assert.NotEqual(t, stripe.APIVersion, stripeVersion)
+	assert.Equal(t, `bar`, fooHeader)
+	assert.Equal(t, `acct_123`, stripeContext)
+	assert.NoError(t, err)
+	defer testServer.Close()
+}