General

How to Login in to Third Party Services in Stripe Apps with OAuth PKCE

Jun 1, 2022

3 min read

One of the benefits of Stripe Apps is that they allow you to connect to third-party services directly from the Stripe Dashboard. There are many ways to implement the OAuth flows to authenticate with a third-party service, but the ideal one for Stripe Apps is PKCE. Unlike other OAuth flows, a Stripe app authenticating with a third-party using PKCE does not require any kind of backend. The entire process can take place in the user's browser.

What is OAuth PKCE

Proof Code for Key Exchange (PKCE, pronounced "pixie") is an extension of regular OAuth flows. It is designed for when you've got a client where it would be possible to access a secret key, such as a native app, or a single-page app. Because Stripe Apps are very restricted for security purposes, the OAuth PKCE flow is the only OAuth flow that works in Stripe Apps without requiring a separate backend.

Not all third-party services support the PKCE authorization flow. One that does is Dropbox, and we will use that for our code examples.

Using `createOAuthState` and `oauthContext` to Get an Auth Token

To use the OAuth PKCE flow, you'll use createOAuthState from the Stripe UI Extension SDK to generate a state and code challenge. We will use these to request a code and verifier from Dropbox. Dropbox will then respond to a specific endpoint for our Stripe App with the code and verifier, which we'll have access to in the oauthContext. With these, we can finally get our access token. If you wish to follow along, you'll need to both create a Stripe App and a Dropbox App.

We'll start by creating state to save our oauthState and challenge, and then get a code and verifier if we don't have one already. If we do have a code and verifier, we'll try to get the token, and put it in tokenData state.

// src/views/App.tsx
import { useEffect, useState } from 'react';
import { Box, Button, ContextView, Link } from '@stripe/ui-extension-sdk/ui';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { createOAuthState } from '@stripe/ui-extension-sdk/oauth';
import { getDropboxAuthURL, getDropboxToken } from '../util/getDropboxToken.ts';
import { TokenData } from '../util/types';
const App = ({ oauthContext }: ExtensionContextValue) => {
  const [oauthState, setOAuthState] = useState('');
  const [challenge, setChallenge] = useState('');
  const [tokenData, setTokenData] = useState<null | TokenData>(null);
  const code = oauthContext?.code;
  const verifier = oauthContext?.verifier;
  const showAuthLink = !code && !tokenData;
  useEffect(() => {
    // FIFTH, the app loads again after being redirected from
    // Dropbox. This time, code and verifier are available from
    // the oauthContext. We still don't have a token, so now
    // we will use the code and verifier to request one from
    // Dropbox, then set it to state.
    if (code && verifier && !tokenData) {
      getDropboxToken({ code, verifier }).then(token => {
        if (token) {
          setTokenData(token);
        }
      });
    }
    // FIRST time the app renders, there will be no oauth
    // state nor token data. So we'll run createOAuthState
    // and set those values to local state. These will be
    // used in the link the user clicks to login.
    else (!oauthState && !tokenData) {
      createOAuthState().then(({ state, challenge }) => {
        setOAuthState(state);
        setChallenge(challenge);
      });
    }
  }, [oauthState, code, verifier]);
  // SECOND, the user will see a login link if there is
  // no response code from Dropbox in oauthContext and
  // no tokenData present. Clicking this link will send
  // the oauthState and challenge to Dropbox, and they
  // will send back a code and verifier.
  return (
    <ContextView title="Dropbox OAuth PKCE Example">
      <Box>
        <Box>
          {showAuthLink && (
            <Link href={getDropboxAuthURL(oauthState, challenge)}>
              Begin authorization flow
            </Link>
          )}
          {tokenData && (
            <Box>
              Dropbox account is connected.
            </Box>
          )}
        </Box>
      </Box>
    </ContextView>
  );
}

// src/util/getDropboxToken.ts
import { addSeconds } from 'date-fns';
import { TokenData } from './types';
const client_id = 'your_dropbox_client_id_goes_here';
const APP_NAME = 'com.example.dropbox-oauth-pkce';
const redirectURI = `https://dashboard.stripe.com/test/apps-oauth/${APP_NAME}`;
// FOURTH, the link to get the code and verifier also specifies
// the id of the Dropbox app we've created, and the redirect
// URI for Stripe. The redirect depends on the Stripe App's
// unique ID, which is seen in stripe-app.json.
export const getDropboxAuthURL = (state: string, challenge: string) =>
  `https://www.dropbox.com/oauth2/authorize?response_type=code&client_id=${client_id}&redirect_uri=${redirectURI}&state=${state}&code_challenge=${challenge}&code_challenge_method=S256`;
export const getDropboxToken = async ({
  code,
  verifier,
}: {
  code: string;
  verifier: string;
}): Promise<TokenData | void> => {
  try {
    const response = await fetch(
      `https://api.dropboxapi.com/oauth2/token?code=${code}&grant_type=authorization_code&code_verifier=${verifier}&client_id=${client_id}&redirect_uri=${redirectURI}`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      },
    );
    if (response.ok) {
      let token = await response.json();
      token = {
        ...token,
        expires_in: addSeconds(Date.now(), token.expires_in),
      };
      return token;
    }
    throw new Error(await response.text());
  } catch (e) {
    console.error('Unable to retrieve access token:', (e as Error).message);
  }
};

// src/util/types.ts
export interface TokenData {
  access_token: string;
  account_id: string;
  expires_in: number;
  scope: string;
  token_type: string;
  uid: string;
}

Fetch Dropbox User Data

To prove to ourselves that the token works, let's fetch Dropbox user data using the token. We'll create a new function to fetch this user data, and call it from within our Stripe App's view. We'll store this user data in state.

// src/util/getDropBoxAccount.ts
import { TokenData, AccountData } from "./types";
export const getDropboxAccount = async (
  tokenData: TokenData,
): Promise<AccountData | void> => {
  try {
    const response = await fetch(
      'https://api.dropboxapi.com/2/users/get_account',
      {
        method: 'POST',
        body: JSON.stringify({ account_id: tokenData.account_id }),
        headers: {
          Authorization: `Bearer ${tokenData.access_token}`,
          'Content-Type': 'application/json',
        },
      },
    );
    if (response.ok) {
      return await response.json();
    }
    throw new Error(await response.text());
  } catch (e) {
    console.error('Unable to get account data:', (e as Error).message);
  }
};

// src/views/App.tsx
// ...
import { useCallback, useEffect, useState } from 'react';
import { getDropboxAccount } from '../util/getDropboxAccount';
import { TokenData, AccountData } from '../util/types';
const App = ({ userContext, oauthContext }: ExtensionContextValue) => {
  // ...
  const [accountData, setAccountData] = useState<null | AccountData>(null);
  // ...
  const handleGetAccount = useCallback(() => {
    if (tokenData) {
      getDropboxAccount(tokenData).then(data => {
        if (data) {
          setAccountData(data);
        }
      });
    }
  }, [tokenData]);
  return (
    <ContextView title="Dropbox OAuth PKCE Example">
      <Box>
        <Box>
          { /* ... */ }
          {tokenData && (
            <>
              <Box>
                Dropbox account is connected.
              </Box>
              {!accountData && (
                <Box>
                  <Button onPress={handleGetAccount}>Load Account Data</Button>
                </Box>
              )}
            </>
          )}
          {accountData && (
            <Box>
              Your Dropbox identity: {accountData.name.display_name}
            </Box>
          )}
        </Box>
      </Box>
    </ContextView>
  );
}

// src/util/types
// ...
export interface AccountData {
  email: string;
  name: {
    display_name: string;
  };
}

Storing Tokens with the Secret Store

Currently, we're only persisting the retrieved token data in memory. As soon as we close the Stripe App, it will be forgotten and the user would have to fetch it all over again. For security reasons, we can't save it as a cookie or to local storage. But Stripe has a solution: the secret store.

The secret store allows us to persist key-value data with Stripe itself. We can use this to save our token data and load it whenever a user opens our Stripe App.

To make it easier to work with the secret store, we'll create a custom hook: useSecretStore.

// src/hooks/useSecretStore.ts
import Stripe from 'stripe';
import {
  STRIPE_API_KEY,
  createHttpClient,
} from '@stripe/ui-extension-sdk/http_client';
import { useState, useEffect, useCallback } from 'react';
const stripe = new Stripe(STRIPE_API_KEY, {
  httpClient: createHttpClient(),
  apiVersion: '2020-08-27',
});
export function useSecretStore<T>(userId: string, secretName: string) {
  const [secret, setSecret] = useState<T | null>(null);
  const postSecret = useCallback(
    (newSecret: any) => {
      const postTokenPath = `apps/secrets?scope[type]=user&scope[user]=${userId}&name=${secretName}`;
      const createSecretResource = Stripe.StripeResource.extend({
        request: Stripe.StripeResource.method({
          method: 'POST',
          path: postTokenPath,
        }),
      });
      new createSecretResource(stripe).request(
        { payload: JSON.stringify(newSecret) },
        function (err: any) {
          if (err) {
            console.error(err);
          } else {
            setSecret(newSecret);
          }
        },
      );
    },
    [userId, secretName],
  );
  const getSecret = useCallback(() => {
    const getTokenPath = `apps/secrets/find?scope[type]=user&scope[user]=${userId}&name=${secretName}&expand[]=payload`;
    const getSecretResource = Stripe.StripeResource.extend({
      request: Stripe.StripeResource.method({
        method: 'GET',
        path: getTokenPath,
      }),
    });

    new getSecretResource(stripe).request(
      {},
      function (err: any, retrievedSecret: any) {
        if (!err) {
          const theSecret = JSON.parse(retrievedSecret.payload);
          setSecret(theSecret);
        }
      },
    );
  }, [userId, secretName]);
  useEffect(() => {
    getSecret();
  }, [getSecret]);
  return { secret, postSecret };
}

Once we've got our custom hook ready, we can integrate it into our App.tsx view. We will rewrite the useEffect to check for a saved token in the secret store, and use that if it's valid. Only if there is no token available do we create a new one, which will then be persisted to the secret store. We also add a Log Out button, which will reset the tokenData and secret store values to null.

The Log Out button creates an issue. If we have oauthContext from logging in, and then we log out, the Stripe App still has the same oauthContext. If we tried logging in again without closing the app, we would get an error because we're re-using old credentials. To fix this, we also add a React ref to keep track of whether or not we've used our current oauthContext values.

// src/views/App.tsx
import { useCallback, useEffect, useState, useRef } from 'react';
import { Box, Button, ContextView, Link } from '@stripe/ui-extension-sdk/ui';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { createOAuthState } from '@stripe/ui-extension-sdk/oauth';
import { TokenData, AccountData } from '../util/types';
import { useSecretStore } from '../hooks/useSecretStore';
import { getDropboxToken, getDropboxAuthURL } from '../util/getDropboxToken';
import { getDropboxAccount } from '../util/getDropboxAccount';
const App = ({ userContext, oauthContext }: ExtensionContextValue) => {
  const [oauthState, setOAuthState] = useState('');
  const [challenge, setChallenge] = useState('');
  const credentialsUsed = useRef(false);
  const [tokenData, setTokenData] = useState<null | TokenData>(null);
  const [accountData, setAccountData] = useState<null | AccountData>(null);
  const { secret, postSecret } = useSecretStore<TokenData>(
    userContext!.id,
    'dropbox_token',
  );
  const code = oauthContext?.code;
  const verifier = oauthContext?.verifier;
  const error = oauthContext?.error;
  const showAuthLink = (!code || credentialsUsed.current) && !tokenData;
  useEffect(() => {
    // First we check if the token is already in the secret store.
    // If it is, we set the tokenData state equal to it.
    if (secret) {
      setTokenData(secret as TokenData);
    }
    // Otherwise, let's see if we've got a code and verifier, but
    // not tokenData. If so, we are ready to fetch a token from
    // Dropbox. Then, we post the secret to the store.
    // We use the ref credentialsUsed to keep track of whether we
    // already used the code and verifier derived from props to
    // get a token. We should only fetch a token if we have not
    // used this code and verifier yet, or else we'll get an error.
    else if (code && verifier && !tokenData && !credentialsUsed.current) {
      getDropboxToken({ code, verifier }).then(token => {
        if (token) {
          credentialsUsed.current = true;
          postSecret(token);
        }
      });
    }
    // Finally, we probably don't have any OAuth stuff ready or in process.
    // Create the OAuthState in preparation for logging in and getting a token.
    else if (!oauthState && !tokenData) {
      createOAuthState().then(({ state, challenge }) => {
        setOAuthState(state);
        setChallenge(challenge);
      });
    }
  }, [secret, oauthState, code, verifier]);
  const handleGetAccount = useCallback(() => {
    if (tokenData) {
      getDropboxAccount(tokenData).then(data => {
        if (data) {
          setAccountData(data);
        }
      });
    }
  }, [tokenData]);
  const logOut = () => {
    if (tokenData) {
      postSecret(null);
      setTokenData(null);
    }
  };
  return (
    <ContextView title="Dropbox OAuth PKCE Example">
      <Box>
        <Box>
          {showAuthLink && (
            <Link href={getDropboxAuthURL(oauthState, challenge)}>
              Begin authorization flow
            </Link>
          )}
          {error && (
            <Box>
              OAuth error: {error}
            </Box>
          )}
          {tokenData && (
            <>
              <Box>
                Dropbox account is connected.
              </Box>
              {!accountData && (
                <Box>
                  <Button onPress={handleGetAccount}>Load Account Data</Button>
                </Box>
              )}
              <Box>
                <Button onPress={logOut}>Log Out</Button>
              </Box>
            </>
          )}
          {accountData && (
            <Box>
              Your Dropbox identity: {accountData.name.display_name}
            </Box>
          )}
        </Box>
        <Box>
      </Box>
    </ContextView>
  );
};
export default App;

We've done a lot to create our authorization flow using PKCE. To see this entire example all together, check out this code sample on GitHub.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Tom VanAntwerp

@tvanantwerp @tvanantwerp

Creating Complex UIs Using the Stripe UI Extension SDK

Anyone who embarks on a journey to develop apps for the Stripe dashboard will need to grasp the concepts of frontend development using the Stripe UI Extension SDK. While a backend for your Stripe app may not always be necessary, a frontend is most certainly needed. In this blog, I will provide you with some tips & tricks that you might want to consider if you plan to develop more complex UIs. The Basics Stripe's UI Extension SDK is React-based. This means that you will need to have some React experience if you want to create Stripe apps. While Stripe apps are web apps, you will never touch HTML or CSS directly. In fact, you're forbidden to. This experience feels almost like developing in React Native. You use the provided UI primitives or components to scaffold your UI. When you open your app on the Stripe dashboard, you will see one of your app's *views*. Depending on where you are in the dashboard, you can open a view that is customer-related, payment-related, etc. Or, in the default case, you will open the default view if you are on the main dashboard page. A typical drawer view will have a ContextView component as its first child, and any other components from the UI toolkit as necessary. The main building block for your components is a Box. It's a plain block-level container, so you can think of it as a div. The Box, just like most other components, has a css property where you can apply styling. As mentioned before, you can't use real CSS though. Instead, you'll need to rely on the predefined CSS properties, most of which are very similar to real CSS properties in both naming and functionality. Just like we have a block-level container, we also have inline containers similar to span. In Stripe's case, this component is called Inline. All other components provide some additional functionality. Some of them are meant to be containers as well, while others are usually standalone. Navigating Within Views When you navigate through the Stripe dashboard, the dashboard will be opening different views in your app. On the Customers page, it will open a view for customers, for example (if such view is defined in stripe-app.json). However, what if you are on a view, but wish to navigate somewhere else within the view? Or maybe have functionality where you need to go back and forth between components? A typical scenario is having a widget, which, when clicked, opens more details, but within the same dashboard view. For this scenario, you can utilize React Router, specifically its MemoryRouter. Install it first: ` Since we don't have access to the DOM, and we cannot manipulate the browser location either, using MemoryRouter is good enough for our needs. It will store the current location as well as history in an internal memory array. You use it just like you would use the regular router. Let's assume that you need to authenticate your user before using the app. Let's also assume that, once logged in, you are shown an FAQ component with multiple questions. Once you click a FAQ question, you are directed to a FAQ answer within the view, as shown below: To model such transitions, you would use the React Router. The default view could have the following implementation: ` There are several things of note here. The ContextView is the root component in our DefaultView component. When we don't want to provide title and description of the ContextView, we use a space. You can't use an empty string, or leave out title and description all together. The first child of the ContextView is a Router. This is where our components will render, depending on our route. Remember that we use a MemoryRouter, and the route is an internal property of the router. It's not reflected in the window's location. When you open the view for the first time, you are presented with the AuthInit component. This component could check if you are authenticated, and if so, redirect you to /, and consequently the React Router will render the Faq component. Within the Faq component, we can use the useNavigate hook to navigate to a FaqEntry component to show the expanded question, and answer for a FAQ entry. For example: ` You can even try to extract the Router part into its own component, e.g. NavigationWrapper, and re-use it across views. In that case, you might consider including view IDs in the route to distinguish between different views. Following our example, this means our routes would become: ` The current view ID is always available in the environment?.viewportID property, should you ever need it. Using UserContext and Environment Everywhere The UserContext and Environment are so useful and so commonly used that it makes sense to store them in React context. Otherwise, you'd need to pass them down from your view component all the way to the components that need them. This is a technique known as "prop drilling" in the React world. First, define your context object: ` Now, simply wrap your view component in a context provider, and initialize it with the userContext and environment that are passed to your view: ` Now, you can use the useContext hook to retrieve properties from userContext and environment anywhere in your component tree. For example, this is how we would retrieve the payment object if we were on the payments page: ` Updating Title and Description Dynamically title and description are properties on the view level, but more often than not, you might want to update them dynamically as they are very context-dependant. In one of the above examples, we might want to display the FAQ answer in the title as we navigate to individual FAQ entries. In such cases, we can use React context again. Let's extend our GlobalContext with title and description properties, as well as setters for them. ` The DefaultView component now becomes: ` Now, any child component can update title and/or description, using the following snippet: ` Layout Options Before starting to model different type of layouts, it is highly recommended to learn the concept of "stacks". Stacks are Stripe's way of modelling flexbox-like layouts. It's not exactly the same as flexbox, but once you get the hang of it, you will find it to be very similar. You can stack up elements horizontally (on the "x" axis) or vertically (on the "y" axis). Furthermore, elements can be distributed in a different way along the axis, or aligned in a certain way, giving you the ability to make any kind of layout you can imagine. You can even stack up elements on top of each other. Whenever you want to align your content in any way, you need to use a stack. Key-Value Two-Column Layout Let's assume that you want to show key-value pairs in a two-column layout. This can be accomplished easily using stacks: ` The above code is for one row in the two-column layout. To add more, just add more blocks like these (or better, extract the above component in its own component). This is how it would be displayed in the app: The above code snippet has several things of note: - Whenever you use a width on a Box, make sure its parent has a gap defined. The reason is the way how the width is calculated - it takes gap into calculation, and if the gap is 0, the calculation will produce invalid width (which will just fit the content). - To align content of a Box (we used alignX: 'end'), the Box should be a stack. - In addition to using margin, you can also use marginTop, marginBottom, marginLeft, and marginRight to specify margin only on one (or more sides). - Vertically Aligning Elements Stacks are not only helpful for horizontal alignments. You can align vertically too, and this can come in handy if you want to nicely align an icon with a text label, or if you want to have form elements displayed in a straight line. For example: ` Wizards Whenever you need to have confirmation modals, or wizard-like flows, it's best to use the FocusView component. A focus view slides from the right and allows the user to have a dedicated space to perform a specific task, such as entering details to create a new entry in a database, or going through a wizard. A wizard can be implemented using two or more FocusView components. Here is an example of having a wizard with two components: ` Conclusion Stripe really did fantastic work to provide an amazing UI Extensions for developing custom Stripe apps. We hope this blog post provided you with some guidance on how to set solid foundations if you want to make more complex UIs using the Stripe UI Extension SDK. Stripe is continuously upgrading the UI Extension SDK, and you can definitely expect some new widgets to play with in the future!...

May 31, 2022

7 mins

Stripe Apps

Integrating In-house Data and Workflows with Stripe Using Private Stripe Apps

Stripe Apps is a recently-announced platform that allows developers to embed content within Stripe's web UI, extending its functionality to allow interaction with non-Stripe services. Your immediate thought upon hearing of such a platform might be that it is useful for public services, such as customer support, to develop Stripe integrations. This is a core use-case and high-profile public integrations like those for Intercom and DocuSign have featured prominently in demonstrations of the platform's capabilities. However, you shouldn't overlook the value of private apps, developed specifically for your organization and visible only to your employees. Private apps may prove to be even more valuable, because they can specifically address your business' problems, automating domain-specific workflows, and integrate with in-house data and services. What is a private Stripe App? Stripe Apps published to the marketplace act like apps you might be familiar with from iOS or Android. They are developed for use by the public, each version of them goes through a strict review by Stripe, and they are published to the Stripe Marketplace where anyone can install them. Private Stripe Apps, in contrast, are published directly to the Stripe account that owns them. Since they are not going to be visible to users outside of the organization they are developed for, they don't have to go through the app review process, simplifying the development and maintenance process. Accessing internal services Since Stripe Apps are browser apps which execute on a user's own machine — as opposed to on Stripe's servers — private Stripe Apps can make use of resources that are only accessible from company-controlled devices. Intranet services and any internal authentication are accessible from your private Stripe App just as they are from any other browser-based internal tooling. There are only two caveats to accessing HTTP services from Stripe Apps. Both of them are driven by the security model of apps. The first is that services must be served over HTTPS, which is standard for internet-facing services, but might not be the case for private services on an intranet. The second one is that services must allow all cross-origin requests, since requests from Stripe Apps are made with a null origin, and therefore CORS allowlisting cannot be used to secure services against cross-site request forgery. If this is a major concern, endpoints specific to your Stripe App can be constructed that are secured through Stripe's request signing mechanism, and which proxy requests to the internal services only for requests signed with the App's secret. Enriching views with context-based data and workflows Stripe Apps are displayed on the same screen as Stripe objects like customers or invoices, and can access information about those objects and interact with them. This enables smoother workflows by operators by showing important context all in the same view. For example: - Displaying product shipping and returns information on the Invoice Details screen in order to make processing refunds more efficient. - Allowing operators to see — and maybe edit — the features that a given subscription plan includes directly in the Product Details screen. - Displaying account activity from multiple sources like access and change logs in the Customer Details screen in order to make it easier to resolve support queries. If anyone in your organization is currently working with multiple open browser tabs to manually collate information or execute workflows that cross service boundaries, a private Stripe App could help automate that process. This will free them up to do more valuable tasks, and reduce the likelihood of errors by making contextual information more reliably available, and eliminating manual steps....

May 25, 2022

3 mins

Stripe Apps

JavaScript Errors: An Introductory Primer

JavaScript Errors are an integral part of the language, and its runtime environment. They provide valuable feedback when something goes wrong during the execution of your script. And once you understand how to use and handle Errors, you'll find them a much better debugging tool than always reaching for console.log. Why Use Errors? When JavaScript throws errors, it's usually because there's a mistake in the code. For example, trying to access properties of null or undefined would throw a TypeError. Or trying to use a variable before it has been declared would throw a ReferenceError. But these can often be caught before execution by properly linting your code. More often, you'll want to create your own errors in your programs to catch problems unique to what you're trying to build. Throwing your own errors can make it easier for you to interrupt the control flow of your code when necessary conditions aren't met. Why would you want to use Error instead of just console.logging all sorts of things? Because an Error will force you to address it. JavaScript is optimistic. It will do its best to execute despite all sorts of issues in the code. Just logging some problem might not be enough to notice it. You could end up with subtle bugs in your program and not know! Using console.log won't stop your program from continuing to execute. An Error, however, interrupts your program. It tells JavaScript, "we can't proceed until we've fixed this problem". And then JavaScript happily passes the message on to you! Using Errors in JavaScript Here's an example of throwing an error: ` When an Error is thrown, nothing after that throw in your scope will be executed. JavaScript will instead pass the Error to the nearest error handler higher up in the call stack. If no handler is found, the program terminates. Since you probably don't want your programs to crash, it's important to set up Error handling. This is where something like try / catch comes in. Any code you write inside the try will attempt to execute. If an Error is thrown by anything inside the try, then the following catch block is where you can decide how to handle that Error. ` In the catch block, you receive an error object (by convention, this is usually named error or err, but you could give it any name) which you can then handle as needed. Asynchronous Code and Errors There are two ways to write asynchronous JavaScript, and they each have their own way of writing Error handling. If you're using async / await, you can use the try / catch block as in the previous example. However, if you're using Promises, you'll want to chain a catch to the Promise like so: ` Understanding the Error Object The Error object is a built-in object that JavaScript provides to handle runtime errors. All types of errors inherit from it. Error has several useful properties. - message: Probably the most useful of Error's properties, message is a human-readable description of the error. When creating a new Error, the string you pass will become the message. - name: A string representing the error type. By default, this is Error. If you're using a built-in sub-class of Error like TypeError, it will be that instead. Otherwise, if you're creating a custom type of Error, you'll need to set this in the constructor. - stack: While technically non-standard, stack is a widely supported property that gives a full stack trace of where the error was created. - cause: This property allows you to give more specific data when throwing an error. For example, if you want to add a more detailed message to a caught error, you could throw a new Error with your message and pass the original Error as the cause. Or you could add structured data for easier error analysis. Creating an Error object is quite straightforward: ` In addition to the generic Error, JavaScript provides several built-in sub-classes of Error: - EvalError: Thrown when a problem occurs with the eval() function. This only exists for backwards compatibility, and will not be thrown by JavaScript. You shouldn't use eval() anyway. - InternalError: Non-standard error thrown when something goes wrong in the internals of the JavaScript engine. Really only used in Firefox. - RangeError: Thrown when a value is not within the expected range. - ReferenceError: Thrown when a value doesn't exist yet / hasn't been initialized. - SyntaxError: Thrown when a parsing error occurs. - TypeError: Thrown when a variable is not of the expected type. - URIError: Thrown when using a global URI handling function incorrectly. Each of these error types inherits from the Error object and generally adds no additional properties or methods, but they do change the name property to reflect the error type. Making Your Own Custom Errors It's sometimes useful to extend the Error object yourself! This lets you add properties to particular Errors you throw, as well as easily check in catch blocks if an Error is of a particular type. To extend Error, use a class. ` In this example, CustomError extends the Error class. It changes the name to CustomError and gives it the new property foo: 'bar'. You can then throw your CustomError, check if the error in your catch block is an instance of the CustomError, and access the properties associated with your CustomError. This gives you a lot more control over how Errors are structured and validated, which could greatly aid with debugging because your errors won't all just be Errors. Common Confusions There are many ways that using Errors can go subtly wrong. Here are some of the common issues to keep in mind when working with Error. Failure to Catch When an Error is thrown, the program will cease executing anything else in its scope and start working its way back up the call stack until it finds a catch block to deal with the Error. If it never finds a catch, the program will crash. So it's important to make sure you actually catch your errors, or else you might terminate your program unintentionally for small and recoverable issues. It's especially helpful to think about catching errors when you're executing code from external libraries which you don't control. You may import a function to handle something for you, and it unexpectedly throws an Error. You should anticipate this possibility and ask yourself: "Should this code go inside of a try / catch block?" to prevent an error like this from crashing your code. Network Requests Don't Throw on 400 and 500 Statuses You might want to make a request to an API, and then handle an error if the request fails. ` Maybe you made a bad request and got back a 400. Maybe you're not properly authenticated and got a 401 or 403. Maybe the endpoint is invalid and you get a 404. Or maybe the server is having a bad day and you get a 500. In none of those cases will you get an Error! From JavaScript's point of view, your request worked. You sent some data to a place, and the place sent you something back. Mission accomplished! Except it's not. You need to deal with these HTTP error statuses. So if you want to handle responses that aren't OK, you need to do it explicitly. To fix the previous example: ` You Can Throw Anything You should throw new Errors. But you could throw 'literally anything'. There's nothing forcing you to only throw an Error. However, it's a lot harder to handle your errors if there's no consistency in what to expect in your catch blocks. It's a best practice to only throw an Error and not any other kind of JavaScript object. This problem becomes especially clear in TypeScript, when the default type of an error in a catch block is not Error, but unknown. TypeScript has no way to know if an error passed into the catch is going to actually be an Error or not, which can make it more frustrating to write error handling code. For this reason, it's often a good idea to check what exactly you've received before trying to handle it. ` (Alas, you cannot throw 🥳. That's a SyntaxError. But throw new Error('🥳') is still perfectly valid!) Conclusion Wielding JavaScript Errors is a big upgrade from console.logging all the things and hoping for the best. And it's not very hard to do it well! By using Error, your apps will be much more explicit in how you expect things to work, and how you expect things might not work. And when something does go wrong, you'll be more likely to notice and better equipped to figure out the problem....

Jul 14, 2023

6 mins

JavaScript

6 Steps to AI Adoption: Benefits of LLMs & SLMs with Jerome Hardaway and Rob Ocel

Rob Ocel and Jerome Hardaway continue their series on AI adoption by exploring the world of AI, focusing on small language models (SLMs) and large language models (LLMs). They compare the unique capabilities of SLMs against the vast knowledge encompassed by LLMs, and highlight the transformative potential of AI in driving creativity, problem-solving, and user-centric design in technology. SLMs are designed to excel at specific tasks, offering faster processing and cost-effectiveness due to their open-source nature. These models have proven to be invaluable in sectors like finance, where data security is of utmost importance. By leveraging SLMs, organizations can enhance their security measures and protect sensitive information. Moreover, SLMs provide a stepping stone for engineers to adapt to new technologies and incorporate AI into their work, ultimately improving user experiences. On the other hand, LLMs encompass a wide range of knowledge, making them incredibly versatile. These models have the potential to transform industries by providing insights, predictions, and solutions to complex problems. With advancements in AI chip technology by tech giants like Apple, Nvidia, Google, and Meta, LLMs are becoming even more powerful and efficient. Evaluating AI models based on factors like stability and industry support is crucial to harnessing the full potential of LLMs. The conversation also addresses some ethical questions related to AI implementation. While AI brings numerous benefits, concerns about job displacement cannot be ignored. As AI continues to evolve, it is essential to strike a balance between automation and human involvement. Engineers must focus on improving AI sophistication and seamless integration into user interactions, ensuring that AI enhances human capabilities rather than replacing them. Additionally, ethical guidelines and regulations must be established to address potential biases and ensure responsible AI implementation. Download this episode here....

Apr 23, 2024

2 mins

Engineering Leadership

How to Login in to Third Party Services in Stripe Apps with OAuth PKCE

What is OAuth PKCE

Using `createOAuthState` and `oauthContext` to Get an Auth Token

Fetch Dropbox User Data

Storing Tokens with the Secret Store

Tom VanAntwerp

You might also like

Creating Complex UIs Using the Stripe UI Extension SDK

Integrating In-house Data and Workflows with Stripe Using Private Stripe Apps

JavaScript Errors: An Introductory Primer

6 Steps to AI Adoption: Benefits of LLMs & SLMs with Jerome Hardaway and Rob Ocel

You might also like

Creating Complex UIs Using the Stripe UI Extension SDK

Integrating In-house Data and Workflows with Stripe Using Private Stripe Apps

JavaScript Errors: An Introductory Primer

6 Steps to AI Adoption: Benefits of LLMs & SLMs with Jerome Hardaway and Rob Ocel

What is OAuth PKCE

Using createOAuthState and oauthContext to Get an Auth Token

Fetch Dropbox User Data

Storing Tokens with the Secret Store

Tom VanAntwerp

Creating Complex UIs Using the Stripe UI Extension SDK

Integrating In-house Data and Workflows with Stripe Using Private Stripe Apps

JavaScript Errors: An Introductory Primer

6 Steps to AI Adoption: Benefits of LLMs & SLMs with Jerome Hardaway and Rob Ocel

Creating Complex UIs Using the Stripe UI Extension SDK

Integrating In-house Data and Workflows with Stripe Using Private Stripe Apps

JavaScript Errors: An Introductory Primer

6 Steps to AI Adoption: Benefits of LLMs & SLMs with Jerome Hardaway and Rob Ocel

Using `createOAuthState` and `oauthContext` to Get an Auth Token