Groundwork for v2 (#206)

* chore: Fresh start Removed all files to prepare for a v2 rewrite. * feat: Base for implementing API operations Added core types, methods and interfaces for building API operations. The package provides a basic Backend that can communicate with the Clerk API. The Backend can handle APIRequest requests and APIResponse responses. Types are also provided for API resources and parameters, as well as expected errors. * feat: Add CI workflow Added a new CI workflow for Github Actions that will vet, and lint the code and run the test suite. Linting is done with golangci-lint. Tests are run against all Go versions from 1.19 onwards.
clerk · Jan 31, 2024 · 83c42d2 · 83c42d2
1 parent 9b83650
commit 83c42d2
Show file tree

Hide file tree

Showing 89 changed files with 779 additions and 9,561 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - $default-branch
+      - v2
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup go
+        uses: actions/setup-go@v4
+        with:
+          go-version: "1.21"
+      - name: Format
+        run: diff -u <(echo -n) <(gofmt -d -s .)
+      - name: Vet
+        run: go vet ./...
+      - name: Run linter
+        uses: golangci/golangci-lint-action@v3
+  test:
+    name: "Test: go v${{ matrix.go-version }}"
+    strategy:
+      matrix:
+        go-version:
+          - "1.19"
+          - "1.20"
+          - "1.21"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup go
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ matrix.go-version }}
+      - name: Run tests
+        run: go test -v -race ./...
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
diff --git a/README.md b/README.md
@@ -10,118 +10,24 @@
 
 # Clerk Go SDK
 
-Go client library for accessing the [Clerk Backend API](https://clerk.com/docs/reference/backend-api).
+**This is still a work in progress. The current stable release is v1. See the main branch for the stable release.**
 
-[![GoDoc](https://img.shields.io/static/v1?label=godoc&message=reference&color=blue)](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/clerk)
-[![Test Status](https://github.com/clerkinc/clerk-sdk-go/workflows/tests/badge.svg)](https://github.com/clerkinc/clerk-sdk-go/actions?query=workflow%3Atests)
+The official Go client library for accessing the [Clerk Backend API](https://clerk.com/docs/reference/backend-api).
+
+[![GoDoc](https://img.shields.io/static/v1?label=godoc&message=reference&color=blue)](https://pkg.go.dev/github.com/clerk/clerk-sdk-go/v2)
 
 [![chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://discord.com/invite/b5rXHjAg7A)
 [![documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs)
 [![twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev)
 
+## License
+
+This SDK is licensed under the MIT license found in the [LICENSE](./LICENSE) file.
+
 ---
 
 **Clerk is Hiring!**
 
 Would you like to work on Open Source software and help maintain this repository? [Apply today!](https://apply.workable.com/clerk-dev/)
 
 ---
-
-## Usage
-
-First, add the Clerk SDK as a dependency to your project.
-
-```
-$ go get github.com/clerkinc/clerk-sdk-go
-```
-
-Add the following import to your Go files.
-
-```go
-import "github.com/clerkinc/clerk-sdk-go/clerk"
-```
-
-Now, you can create a Clerk client by calling the `clerk.NewClient` function.
-This function requires your Clerk API key.
-You can get this from the dashboard of your Clerk application.
-
-Once you have a client, you can use the various services to access different parts of the API.
-
-```go
-apiKey := os.Getenv("CLERK_API_KEY")
-
-client, err := clerk.NewClient(apiKey)
-if err != nil {
-    // handle error
-}
-
-// List all users for current application
-users, err := client.Users().ListAll(clerk.ListAllUsersParams{})
-```
-
-The services exposed in the `clerk.Client` divide the API into logical chunks and
-follow the same structure that can be found in the [Backend API documentation](https://clerk.com/docs/reference/backend-api).
-
-For more examples on how to use the client, refer to the [examples](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/operations)
-
-### Options
-
-The SDK `Client` constructor can also accept additional options defined [here](https://github.com/clerk/clerk-sdk-go/blob/main/clerk/clerk_options.go).
-
-A common use case is injecting your own [`http.Client` object](https://pkg.go.dev/net/http#Client) for testing or automatically retrying requests.
-An example using [go-retryablehttp](https://github.com/hashicorp/go-retryablehttp/#getting-a-stdlib-httpclient-with-retries) is shown below:
-
-```go
-retryClient := retryablehttp.NewClient()
-retryClient.RetryMax = 5
-standardClient := retryClient.StandardClient() // *http.Client
-
-clerkSDKClient := clerk.NewClient(token, clerk.WithHTTPClient(standardClient))
-```
-
-## Middleware
-
-The SDK provides the [`WithSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#WithSessionV2) middleware that injects the active session into the request's context.
-
-The active session's claims can then be accessed using [`SessionFromContext`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#SessionFromContext).
-
-```go
-mux := http.NewServeMux()
-injectActiveSession := clerk.WithSessionV2(client)
-mux.Handle("/your-endpoint", injectActiveSession(yourEndpointHandler))
-```
-
-Additionally, there's [`RequireSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#RequireSessionV2) that will halt the request and respond with 403 if the user is not authenticated. This can be used to restrict access to certain routes unless the user is authenticated.
-
-For more info on how to use the middleware, refer to the
-[example](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/middleware).
-
-### Additional options
-
-The middleware supports the following options:
-
-- clerk.WithAuthorizedParty() to set the authorized parties to check against the azp claim of the token
-- clerk.WithLeeway() to set a custom leeway that gives some extra time to the token to accommodate for clock skew
-- clerk.WithJWTVerificationKey() to set the JWK to use for verifying tokens without the need to fetch or cache any JWKs at runtime
-- clerk.WithCustomClaims() to pass a type (e.g. struct), which will be populated with the token claims based on json tags.
-- clerk.WithSatelliteDomain() to skip the JWT token's "iss" claim verification.
-- clerk.WithProxyURL() to verify the JWT token's "iss" claim against the proxy url.
-
-For example
-
-```golang
-customClaims := myCustomClaimsStruct{}
-
-clerk.WithSessionV2(
-	clerkClient,
-	clerk.WithAuthorizedParty("my-authorized-party"),
-	clerk.WithLeeway(5 * time.Second),
-	clerk.WithCustomClaims(&customClaims),
-	clerk.WithSatelliteDomain(true),
-	clerk.WithProxyURL("https://example.com/__clerk"),
-	)
-```
-
-## License
-
-This SDK is licensed under the MIT license found in the [LICENSE](./LICENSE) file.