Clients for API operations

[gkats]

Up until now, our SDK offered only one way to perform API operations. That is package level functions like actortoken.Create().

These package-level functions would use a global Backend to send requests to the Clerk API.

This design works well for most cases, but is a bit inflexible. The existence of a global Backend means that there's no way to configure individual API operations (override secret key, url, HTTP client).

We now provide an alternative API, which uses clients with a dedicated Backend for each individual API.

After this commit, there will be two ways to perform API operations using the SDK.

With globals

clerk.SetKey("sk_live_XXXX")
domain.Create(ctx, &domain.CreateParams{
  Name: clerk.String("clerk.com"),
})

With a client

config := domain.ClientConfig{}
config.Key = "sk_live_XXXX"
c := domain.NewClient(config)
c.Create(ctx, &domain.CreateParams{
  Name: clerk.String("clerk.com"),
})

Writing code to support both APIs can be cumbersome. This commit includes a generator that processes client files and creates functions for each exported Client method.

The generator is quick and dirty and relies heavily on conventions all over the place. It's a first version designed to help with getting v2 out quickly and certainly needs improvements.

In order to add a new API operation, we now have to

1. Add an exported method in <package>/client.go
2. Run go generate ./...

In order to add a whole new API, we have to

1. Create a new package with a <package>/client.go file.
2. Add the go:generate directive in the file.
3. Add boilerplate code for the Client type and its constructor.
4. Add methods on *Client for each API operation.
5. Run go generate ./...

In reality, the only additional steps is adding the generate directive and running the go generate command.

[gkats]

This would be better written as

//go:generate gen

but I couldn't figure out how to build the package and add it to the PATH. I should probably give it more time at some point.

[georgepsarakis]

❓ Could we perhaps avoid or simplify the code generation with something like the following?

var DefaultClient = &Client{Backend: clerk.GetBackend()}

func Create(ctx context.Context, params *CreateParams) (*clerk.ActorToken, error) {
  return DefaultClient.Create(ctx, params)
}

[gkats]

👍 Sure!