npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@speakeasy-api/react-embeds

v1.3.1

Published

![180100416-b66263e6-1607-4465-b45d-0e298a67c397](https://user-images.githubusercontent.com/68016351/181640742-31ab234a-3b39-432e-b899-21037596b360.png)

Downloads

54

Readme

Speakeasy React Components

180100416-b66263e6-1607-4465-b45d-0e298a67c397

Embed Speakeasy's React components in your API developer portal to augment your static API documentation with a magical developer experience. With our components, onboarding to and ongoing usage of your API becomes self-service for your users.

All the components we offer are composable, meaning you can use them in isolation, or any combination. Our available components are:

  • API Overview Cards - Give your users the key API metrics they want. API Cards provide your users with the most important API stats: number of requests, number of errors, error rate, and change over time. Each top-level API is represented with a card, which summarizes usage across all the API's individual endpoints filtered for a specific customer.
  • API Request Viewer - Enable your users to troubleshoot API integration issues without engineering support. The API Request Viewer gives user the ability to filter API traffic, make edits to headers & request objects, and replay specific requests. All without having to ever leave your dev portal.
  • API Usage Dashboard - Give your users advanced insight into their API traffic patterns filterable by api, api endpoint, and status. The Usage dashboard gives them rich visualizations to help them better understand how they use your API. Pair with the API Cards to provide both summarized and granular views of API traffic.

Installing Speakeasy Components

npm install @speakeasy-api/react-embeds
 #or
yarn add @speakeasy-api/react-embeds

Using Speakeasy Components

To embed Speakeasy components in your application, the first step is making sure they are properly authenticated and filtered for the logged in customer. After which you will be able to easily add the component into your react app

Authenticating and Filtering your Components

To get Speakeasy components working correctly, you will need to generate an accessToken filtered to the correct subset of data. There are two ways to generate an accessToken:

  1. [Recommended] Declare an embed filter in the instantiation of the Speakeasy SDK in your API handlers.
  2. Make an API request from your React app, passing in the filter as an API parameter. note: Access tokens retrieved through the /v1/workspace/embed-access-token endpoint are read-only.

Recommended Option: Create Filtered Access Token in SDK

Creating a filtered accessToken in the SDK is a language-specific activity. For the full range of supported languages, see our documentation. This instruction set will be in Go.

Step one: set up the Speakeasy SDK

​ Add the sdk to your api project according to the documentation. ​

// routes.go
​
func addPublicRoutes(r *mux.Router) {
	r := mux.NewRouter()
​
	speakeasySDK := speakeasy.New(speakeasy.Config {
		APIKey:		"YOUR API KEY HERE",
		ApiID:		"main_api",
		VersionID:	"1.0.0",
	}
    r.Use(speakeasySDK.Middleware)
​
    // Your paths
}

Step Two: add auth endpoint

Embed tokens can provide access to only a subset of your data, if desired. This is useful for allowing each of your customers to use your embedded component to view only their own data or for restricting which apis, versions, or endpoints you'd like to expose in your embedded component. ​

// controller.go
​
func EmbedAuthHandler(w http.ResponseWriter, r *http.Request) {
	ctrl := speakeasy.MiddlewareController(req)
​
    // Use your existing authentication provider or logic for the embed access token.
    customerID := auth.GetCustomerID(req)
​
    accessToken, err := ctrl.GetSDKInstance().GetEmbedAccessToken(ctx, &embedaccesstoken.EmbedAccessTokenRequest{
		Filters: []*embedaccesstoken.EmbedAccessTokenRequest_Filter{
			{
				Key:   "customer_id",
				Operator: "=",
				Value: customerID,
			},
		},
	})
​
    w.WriteHeader(http.StatusOK)
	if err := json.NewEncoder(w).Encode(EmbedResponse{AccessToken: accessToken}); err != nil {
		// handle error
	}
}
​
// models.go
​
type EmbedResponse struct {
	AccessToken string `json:"access_token"`
}
​
// routes.go
​
func addPublicRoutes(r *mux.Router) {
	r := mux.NewRouter()
​
	speakeasySDK := speakeasy.New(speakeasy.Config {
		APIKey:		"YOUR API KEY HERE",
		ApiID:		"main_api",
		VersionID:	"1.0.0",
	}
    r.Use(speakeasySDK.Middleware)
​
​
	r.Path("v1/auth/embed-token").Methods(http.MethodGet).HandlerFunc(EmbedAuthHandler)
​
    // Your other paths
}

Step Three: Add the embed to your react application

export const DataView = () => {
    const [embedToken, setEmbedToken] = useState(undefined);
​
    // This function will call the handler that you defined in step two.
    const getEmbedToken = useCallback(async () => {
        const accessTokenResponse = await axios.get("https://my-api.dev/v1/auth/embed-token);
        return accessTokenResponse.data.access_token;
    }, []);
​
    // Set the initial token
    useEffect(() => {
        getEmbedToken.then(token => setEmbedToken(token));
    }, [])
​
    return (
        <div>
            <h1>View your data</h1>
            <SpeakeasyRequestsComponent
                accessToken={embedToken}
                onRefetchAccessToken={getEmbedToken}
            />
        </div>
    )
}
​

Alternate Option: Create a Filtered Access Token in React

Step One: Create a filter object

Set the accessToken in your react code by configuring a SpeakeasyFilter object:

type SpeakeasyFilter = {
    // Currently supported filter keys.
    key: 'customer_id' | 'created_at';
    operator: '=' | '<' | '>';
    value: string;
}

customer_id should almost always be set in your filter to restrict data to a single customer, lest you unintentionally share another customer's data.

The filters you configure are then serialized as json into the filters query parameter in the API request you will make.

const filters = useMemo(() => {
      const customerId = "";  // your customer id.
      return {
        filters: [{
          key: "customer_id",
          operator: "=",
          value: customerId
        }]
      };
    }), [];

Step 2: Pass the filter as a parameter into the API request

return (await axios.get("https://app.speakeasyapi.dev/v1/workspace/embed-access-token", {
        headers: {
          "x-api-key": "" // your api key
        }, 
        params: { 
          filters 
        }
      })).data.access_token;
    }, []);

Step 3: Set up accessToken refresh

Nest the GET request from step 2 in onRefetchAccessToken a callback function that triggers when the 'accessToken' expires

const onRefetchAccessToken = useCallback(async () => {
      return (await axios.get("https://app.speakeasyapi.dev/v1/workspace/embed-access-token", {
        headers: {
          "x-api-key": "" // your api key
        }, 
        params: { 
          filters 
        }
      })).data.access_token;
    }, []);

    useEffect(() => {
        getAccessToken()
            .then(access_token => setAccessToken(access_token))
    }, []);

Put it all together for a full example of constructing a filters object and making an API request:

const App () => { 
    const [accessToken, setAccessToken] = useState("");

    const filters = useMemo(() => {
      const customerId = "";  // your customer id.
      return {
        filters: [{
          key: "customer_id",
          operator: "=",
          value: customerId
        }]
      };
    }), [];

    const onRefetchAccessToken = useCallback(async () => {
      return (await axios.get("https://app.speakeasyapi.dev/v1/workspace/embed-access-token", {
        headers: {
          "x-api-key": "" // your api key
        }, 
        params: { 
          filters 
        }
      })).data.access_token;
    }, []);

    useEffect(() => {
        getAccessToken()
            .then(access_token => setAccessToken(access_token))
    }, []);

    // return
}

Step 4: Add Components to Your App

After a filtered accessToken has been created, adding the react components to your app should be easy. Speakeasy components can be added directly into your react pages. The authentication props are passed directly into the embedded component. See the example below:

const SomeReactComponent = (props) => {

  // logic

  return (
    <>
      <YourComponent />
        <SpeakeasyRequestsComponent 
          accessToken={myApiToken}
          onRefetchAccessToken={myApiTokenRefreshFunc} 
        />
    </>
      <YourOtherComponent />
  )

If you have multiple components that are using the same access token, a SpeakeasyConfigure component can simplify the integration

const App = () => {

    // authentication

    return (
        <>
          <SpeakeasyConfigure
            accessToken={myApiToken}
            onRefetchAccessToken={amyApiTokenRefresh} 
          >
            <SpeakeasyApiComponent />
            <SpeakeasyRequestsComponent />
          </SpeakeasyConfigure>
        <>
    );
}