From 824469a07d011eeb25d37669aee97dce91c2531f Mon Sep 17 00:00:00 2001 From: Ewan Harris Date: Fri, 10 Nov 2023 14:27:58 +0000 Subject: [PATCH] Split godoc into separate packages (#311) --- authentication/doc.go | 54 +++++++++++ doc.go | 202 ++++++++++++++++-------------------------- management/doc.go | 153 ++++++++++++++++++++++++++++++++ 3 files changed, 281 insertions(+), 128 deletions(-) create mode 100644 authentication/doc.go create mode 100644 management/doc.go diff --git a/authentication/doc.go b/authentication/doc.go new file mode 100644 index 00000000..12bcb8b2 --- /dev/null +++ b/authentication/doc.go @@ -0,0 +1,54 @@ +// Package authentication provides a client for using the Auth0 Authentication API. +// +// # Usage +// +// import ( +// "github.com/auth0/go-auth0" +// "github.com/auth0/go-auth0/authentication" +// "github.com/auth0/go-auth0/authentication/database" +// "github.com/auth0/go-auth0/authentication/oauth" +// ) +// a, err := authentication.New( +// context.TODO(), +// domain, +// authentication.WithClientID(id), +// authentication.WithClientSecret(secret), // Optional depending on the grants used +// ) +// if err != nil { +// // handle err +// } +// // Now we have an authentication client, we can interact with the Auth0 Authentication API. +// // Sign up a user +// userData := database.SignupRequest{ +// Connection: "Username-Password-Authentication", +// Username: "mytestaccount", +// Password: "mypassword", +// Email: "mytestaccount@example.com", +// } +// createdUser, err := a.Database.Signup(context.TODO(), userData) +// if err != nil { +// // handle err +// } +// // Login using OAuth grants +// tokenSet, err := a.OAuth.LoginWithAuthCodeWithPKCE(context.TODO(), oauth.LoginWithAuthCodeWithPKCERequest{ +// Code: "test-code", +// CodeVerifier: "test-code-verifier", +// }, oauth.IDTokenValidationOptionalVerification{}) +// +// if err != nil { +// // handle err +// } +// +// # Configuration +// +// There are several options that can be specified during the creation of a client. +// For a complete list see [Option]. +// +// a, err := authentication.New( +// context.TODO(), +// domain, +// authentication.WithClientID(id), +// authentication.WithClientSecret(secret), // Optional depending on the grants used +// authentication.WithClockTolerance(10 * time.Second), +// ) +package authentication diff --git a/doc.go b/doc.go index 9764b86c..c9024584 100644 --- a/doc.go +++ b/doc.go @@ -1,129 +1,75 @@ -/* -Package auth0 provides a client for using the Auth0 Authentication and Management APIs. - -# Authentication - -# Usage - - import ( - "github.com/auth0/go-auth0" - "github.com/auth0/go-auth0/authentication" - "github.com/auth0/go-auth0/authentication/database" - "github.com/auth0/go-auth0/authentication/oauth" - ) - -Initialize a new client using a context, domain, client ID, and client secret if required. - - authAPI, err := authentication.New( - context.Background(), - domain, - authentication.WithClientID(id), - authentication.WithClientSecret(secret), // Optional depending on the grants used - ) - if err != nil { - // handle err - } - -Now we have an authentication client, we can interact with the Auth0 Authentication API. - - // Sign up a user - userData := database.SignupRequest{ - Connection: "Username-Password-Authentication", - Username: "mytestaccount", - Password: "mypassword", - Email: "mytestaccount@example.com", - } - - createdUser, err := authAPI.Database.Signup(context.Background(), userData) - if err != nil { - // handle err - } - - // Login using OAuth grants - tokenSet, err := authAPI.OAuth.LoginWithAuthCodeWithPKCE(context.Background(), oauth.LoginWithAuthCodeWithPKCERequest{ - Code: "test-code", - CodeVerifier: "test-code-verifier", - }, oauth.IDTokenValidationOptionalVerification{}) - if err != nil { - // handle err - } - -# Management - -Usage - - import ( - "github.com/auth0/go-auth0" - "github.com/auth0/go-auth0/management" - ) - -Initialize a new client using a domain, client ID and secret. - - m, err := management.New( - domain, - management.WithClientCredentials(context.Background(), id, secret), - ) - if err != nil { - // handle err - } - -Or using a static token. - - m, err := management.New(domain, management.WithStaticToken(token)) - if err != nil { - // handle err - } - -With a management client we can then interact with the Auth0 Management API. - - c := &management.Client{ - Name: auth0.String("Client Name"), - Description: auth0.String("Long description of client"), - } - - err = m.Client.Create(context.Background(), c) - if err != nil { - // handle err - } - -## Authentication - -The auth0 management package handles authentication by exchanging the client ID and secret -supplied when creating a new management client. - -This is handled internally using the https://godoc.org/golang.org/x/oauth2 -package. - -## Rate Limiting - -The auth0 package also handles rate limiting by respecting the `X-Rate-Limit-*` -headers sent by the server. - -The amount of time the client waits for the rate limit to be reset is taken from -the `X-Rate-Limit-Reset` header as the amount of seconds to wait. - -# Configuration - -There are several other options that can be specified during the creation of a -new client. - - m, err := management.New( - domain, - management.WithClientCredentials(context.Background(), id, secret), - management.WithDebug(true), - ) - -## Request Options - -As with the global client configuration, fine-grained configuration can be done -on a request basis. - - c, err := m.Connection.List( - context.Background(), - management.Page(2), - management.PerPage(10), - management.IncludeFields("id", "name", "options"), - management.Parameter("strategy", "auth0"), - ) -*/ +// Package auth0 is the Auth0 SDK for Go. +// +// The SDK provides clients that interact with the Auth0 Authentication and Management APIs +// and is split into separate packages as such. +// +// - auth0 - Provides helpers for providing values as pointers. +// - authentication - Provides an Authentication Client for use when interacting with the +// [Authentication API]. +// - management - Provides a Management Client for use when interacting with the Auth0 +// [Management API]. +// +// # Getting Started +// +// Install the SDK using `go get` +// +// go get github.com/auth0/go-auth0 +// +// # Authentication +// +// Below is an example of using the Authentication client, for full documentation visit the +// [authentication client docs]. +// +// authAPI, err := authentication.New( +// context.TODO(), +// domain, +// authentication.WithClientID(id), +// authentication.WithClientSecret(secret), // Optional depending on the grants used +// ) +// if err != nil { +// // handle err +// } +// // Now we have an authentication client, we can interact with the Auth0 Authentication API. +// // Sign up a user +// userData := database.SignupRequest{ +// Connection: "Username-Password-Authentication", +// Username: "mytestaccount", +// Password: "mypassword", +// Email: "mytestaccount@example.com", +// } +// createdUser, err := authAPI.Database.Signup(context.TODO(), userData) +// if err != nil { +// // handle err +// } +// +// # Management +// +// Below is an example of using the Management client, for full documentation visit the +// [management client docs]. +// +// import ( +// "github.com/auth0/go-auth0" +// "github.com/auth0/go-auth0/management" +// ) +// // Initialize a new client using a domain, client ID and secret. +// m, err := management.New( +// domain, +// management.WithClientCredentials(context.TODO(), id, secret), +// ) +// if err != nil { +// // handle err +// } +// c := &management.Client{ +// Name: auth0.String("Client Name"), +// Description: auth0.String("Long description of client"), +// } +// err = m.Client.Create(context.TODO(), c) +// if err != nil { +// // handle err +// } +// +// [management client docs]: https://pkg.go.dev/github.com/auth0/go-auth0/management +// [Authentication API]: https://auth0.com/docs/api/authentication +// [Management API]: https://auth0.com/docs/api/management/v2 +// [authentication client docs]: https://pkg.go.dev/github.com/auth0/go-auth0/authentication package auth0 diff --git a/management/doc.go b/management/doc.go new file mode 100644 index 00000000..c26b539e --- /dev/null +++ b/management/doc.go @@ -0,0 +1,153 @@ +// Package management provides a client for using the Auth0 Management API. +// +// # Usage +// +// A management client can be instantiated a domain, client ID and secret. +// +// import ( +// "github.com/auth0/go-auth0" +// "github.com/auth0/go-auth0/management" +// ) +// // Initialize a new client using a domain, client ID and secret. +// m, err := management.New( +// domain, +// management.WithClientCredentials(context.TODO(), id, secret), +// ) +// if err != nil { +// // handle err +// } +// +// Or a domain, and a static token. +// +// import ( +// "github.com/auth0/go-auth0" +// "github.com/auth0/go-auth0/management" +// ) +// // Initialize a new client using a domain and static token. +// m, err := management.New(domain, management.WithStaticToken(token)) +// if err != nil { +// // handle err +// } +// +// With a management client we can then interact with the Auth0 Management API. +// +// c := &management.Client{ +// Name: auth0.String("Client Name"), +// Description: auth0.String("Long description of client"), +// } +// err = m.Client.Create(context.TODO(), c) +// if err != nil { +// // handle err +// } +// +// # Authentication +// +// The auth0 management package handles authentication by exchanging the client ID and secret +// supplied when creating a new management client. +// +// This is handled internally using the https://godoc.org/golang.org/x/oauth2 +// package. +// +// # Rate Limiting. +// +// The auth0 package also handles rate limiting by respecting the `X-Rate-Limit-*` +// headers sent by the server. +// +// The amount of time the client waits for the rate limit to be reset is taken from +// the `X-Rate-Limit-Reset` header as the amount of seconds to wait. +// +// The rate limit configuration cane be configured using the [WithRetries] helper that allows +// configuring the maximum number of retries and the HTTP status codes to retry on. +// If you wish to disable retries the [WithNoRetries] helper can be used. +// +// # Configuration +// +// There are several options that can be specified during the creation of a +// new client. For a complete list see [Option]. +// +// m, err := management.New( +// domain, +// management.WithClientCredentials(context.TODO(), id, secret), +// management.WithDebug(true), +// ) +// +// # Request Options +// +// As with the global client configuration, fine-grained configuration can be done +// on a request basis. For a complete list see [RequestOption]. +// +// c, err := m.Connection.List( +// context.TODO(), +// management.Page(2), +// management.PerPage(10), +// management.IncludeFields("id", "name", "options"), +// management.Parameter("strategy", "auth0"), +// ) +// +// # Page Based Pagination +// +// To use page based pagination use the [Page] and [PerPage] RequestOptions, then the +// HasNext method of the return value can be used to check if there is remaining data. +// +// for { +// clients, err := m.Client.List( +// context.TODO(), +// management.Page(page), +// management.PerPage(100), +// ) +// if err != nil { +// return err +// } +// // Accumulate here the results or check for a specific client. +// +// // The `HasNext` helper func checks whether +// // the API has informed us that there is +// // more data to retrieve or not. +// if !clients.HasNext() { +// break +// } +// page++ +// } +// +// # Checkpoint Pagination +// +// Checkpoint pagination should be used when you wish to retrieve more than 1000 results. The APIs +// that support it are: +// - `Log.List` (`/api/v2/logs`) +// - `Organization.List` (`/api/v2/organizations`) +// - `Organization.Members` (`/api/v2/organizations/{id}/members`) +// - `Role.Users` (`/api/v2/roles/{id}/users`) +// +// To use checkpoint pagination, for the first call, only pass the [Take] query parameter, +// the API will then return a `Next` value that can be used for future requests with the [From] +// RequestOption.// +// +// orgList, err := m.Organization.List(context.TODO(), management.Take(100)) +// if err != nil { +// log.Fatalf("err: %+v", err) +// } +// if !orgList.HasNext() { +// // No need to continue we can stop here. +// return +// } +// for { +// // Pass the `next` and `take` query parameters now so +// // that we can correctly paginate the organizations. +// orgList, err = m.Organization.List( +// context.TODO(), +// management.From(orgList.Next), +// management.Take(100), +// ) +// if err != nil { +// log.Fatalf("err :%+v", err) +// } +// // Accumulate here the results or check for a specific client. +// +// // The `HasNext` helper func checks whether +// // the API has informed us that there is +// // more data to retrieve or not. +// if !orgList.HasNext() { +// break +// } +// } +package management