ss-saleor-auth-sdk 1.0.0

package/.eslintignore

@@ -0,0 +1 @@
+.eslintrc.cjs

package/.eslintrc.cjs

@@ -0,0 +1,20 @@
+/* eslint-env node */
+module.exports = {
+  extends: [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended-type-checked",
+    "plugin:@typescript-eslint/stylistic-type-checked",
+  ],
+  plugins: ["@typescript-eslint"],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    project: true,
+    tsconfigRootDir: __dirname,
+  },
+  root: true,
+  rules: {
+    "@typescript-eslint/prefer-nullish-coalescing": "off",
+    "@typescript-eslint/require-await": "off",
+    "no-empty-pattern": "off",
+  },
+};

package/.github/workflows/main.yml

@@ -0,0 +1,32 @@
+name: Build, TypeScripts, tests
+on:
+  pull_request:
+  merge_group:
+    branches:
+      - main
+
+concurrency:
+  group: tests-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_and_test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install PNPM
+        uses: pnpm/action-setup@v2
+        with:
+          version: 8.10.0
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version-file: package.json
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm --version && pnpm install --frozen-lockfile
+
+      - name: Run tests
+        run: pnpm test

package/.nvmrc

@@ -0,0 +1 @@
+18

package/.prettierignore

@@ -0,0 +1,3 @@
+pnpm-lock.yaml
+coverage/**
+dist/

package/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": false,
+  "printWidth": 110,
+  "trailingComma": "all"
+}

package/README.md

@@ -0,0 +1,411 @@
+<div align="center">
+  <img width="150" alt="" src="https://github.com/saleor/auth-sdk/assets/1338731/c90a73d0-5ef1-4d09-9347-c5d02cd7244d">
+</div>
+
+<div align="center">
+  
+# Saleor Auth SDK
+
+Saleor Auth SDK integrates secure and customizable authentication and authorization into storefronts using Saleor.
+
+**Below 3kB bundle size (gzipped).**
+
+</div>
+
+<div align="center">
+  <a href="https://www.npmjs.com/package/@saleor/auth-sdk">npm</a>
+  <span> • </span>
+  <a href="https://docs.saleor.io/docs/3.x/api-usage/authentication">Docs</a>
+  <span> • </span>
+  <a href="https://twitter.com/getsaleor">Twitter</a>
+  <span> • </span>
+  <a href="https://discord.gg/H52JTZAtSH">Discord</a>
+</div>
+
+<br/>
+
+<div align="center">
+
+[![Discord Badge](https://dcbadge.vercel.app/api/server/H52JTZAtSH)](https://discord.gg/H52JTZAtSH)
+
+</div>
+
+## Usage
+
+### Next.js App Router
+
+Next.js 13+ App Router is the recommended way to use the Saleor Auth SDK. It is the easiest to set up and provides the best user experience.
+
+In order to use Saleor Auth SDK in React Server Components, the client needs to be created in the following way:
+
+```ts
+import { createSaleorAuthClient } from "@saleor/auth-sdk";
+import { getNextServerCookiesStorage } from "@saleor/auth-sdk/next/server";
+
+const nextServerCookiesStorage = getNextServerCookiesStorage();
+const saleorAuthClient = createSaleorAuthClient({
+  saleorApiUrl: "…",
+  refreshTokenStorage: nextServerCookiesStorage,
+  accessTokenStorage: nextServerCookiesStorage,
+});
+```
+
+Logging in can be implemented via Server Actions:
+
+```tsx
+<form
+  className="bg-white shadow-md rounded p-8"
+  action={async (formData) => {
+    "use server";
+
+    await saleorAuthClient.signIn(
+      {
+        email: formData.get("email").toString(),
+        password: formData.get("password").toString(),
+      },
+      { cache: "no-store" },
+    );
+  }}
+>
+  {/* … rest of the form … */}
+</form>
+```
+
+Then, you can use `saleorAuthClient.fetchWithAuth` directly for any queries and mutations.
+
+For a full working example see the [Saleor Auth SDK example](https://github.com/saleor/example-auth-sdk/blob/5babda35969c35f423680b47d1446466b18b2461/app/ssr/page.tsx).
+
+### Next.js Pages Router with [Apollo Client](https://www.apollographql.com/docs/react/)
+
+<details>
+  <summary>Step-by-step video tutorial</summary>
+
+Check the following [step-by-step video](https://www.youtube.com/watch?v=XY1t8JiPwk0) guide on how to set this up.
+[![Saleor Auth with Next.js](https://img.youtube.com/vi/t6nxBk7JHCw/0.jpg)](https://www.youtube.com/watch?v=XY1t8JiPwk0)
+
+</details>
+
+When using Next.js (Pages Router) along with [Apollo Client](https://www.apollographql.com/docs/react/), there are two essential steps to setting up your application. First, you have to surround your application's root with two providers: `<SaleorAuthProvider>` and `<ApolloProvider>`.
+
+`<SaleorAuthProvider>` comes from our React.js-auth package, located at `@saleor/auth-sdk/react`, and it needs to be set up with the Saleor auth client instance.
+
+The `<ApolloProvider>` comes from `@apollo/client` and it needs the live GraphQL client instance, which is enhanced with the authenticated `fetch` that comes from the Saleor auth client.
+
+Lastly, you must run the `useAuthChange` hook. This links the `onSignedOut` and `onSignedIn` events.
+
+Let's look at an example:
+
+```tsx
+import { AppProps } from "next/app";
+import { ApolloProvider, ApolloClient, InMemoryCache, createHttpLink } from "@apollo/client";
+import { createSaleorAuthClient } from "@saleor/auth-sdk";
+import { SaleorAuthProvider, useAuthChange } from "@saleor/auth-sdk/react";
+
+const saleorApiUrl = "<your Saleor API URL>";
+
+// Saleor Client
+const saleorAuthClient = createSaleorAuthClient({ saleorApiUrl });
+
+// Apollo Client
+const httpLink = createHttpLink({
+  uri: saleorApiUrl,
+  fetch: saleorAuthClient.fetchWithAuth,
+});
+
+export const apolloClient = new ApolloClient({
+  link: httpLink,
+  cache: new InMemoryCache(),
+});
+
+export default function App({ Component, pageProps }: AppProps) {
+  useAuthChange({
+    saleorApiUrl,
+    onSignedOut: () => apolloClient.resetStore(),
+    onSignedIn: () => {
+      apolloClient.refetchQueries({ include: "all" });
+    },
+  });
+
+  return (
+    <SaleorAuthProvider client={saleorAuthClient}>
+      <ApolloProvider client={apolloClient}>
+        <Component {...pageProps} />
+      </ApolloProvider>
+    </SaleorAuthProvider>
+  );
+}
+```
+
+Then, in your register, login and logout forms you can use the auth methods (`signIn`, `signOut`, `isAuthenticating`) provided by the `useSaleorAuthContext()`. For example, `signIn` is usually triggered when submitting the login form credentials.
+
+```tsx
+import React, { FormEvent } from "react";
+import { useSaleorAuthContext } from "@saleor/auth-sdk/react";
+import { gql, useQuery } from "@apollo/client";
+
+const CurrentUserDocument = gql`
+  query CurrentUser {
+    me {
+      id
+      email
+      firstName
+      lastName
+      avatar {
+        url
+        alt
+      }
+    }
+  }
+`;
+
+export default function LoginPage() {
+  const { signIn, signOut } = useSaleorAuthContext();
+
+  const { data: currentUser, loading } = useQuery(CurrentUserDocument);
+
+  const submitHandler = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+
+    const result = await signIn({
+      email: "admin@example.com",
+      password: "admin",
+    });
+
+    if (result.data.tokenCreate.errors) {
+      // handle errors
+    }
+  };
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <main>
+      {currentUser?.me ? (
+        <>
+          <div>Display user {JSON.stringify(currentUser)}</div>
+          <button className="button" onClick={() => signOut()}>
+            Log Out
+          </button>
+        </>
+      ) : (
+        <div>
+          <form onSubmit={submitHandler}>
+            {/* You must connect your inputs to state or use a form library such as react-hook-form */}
+            <input type="email" name="email" placeholder="Email" />
+            <input type="password" name="password" placeholder="Password" />
+            <button className="button" type="submit">
+              Log In
+            </button>
+          </form>
+        </div>
+      )}
+    </main>
+  );
+}
+```
+
+### Next.js (Pages Router) with [urql](https://formidable.com/open-source/urql/)
+
+When using Next.js (Pages Router) along with [urql](https://formidable.com/open-source/urql/) client, there are two essential steps to setting up your application. First, you have to surround your application's root with two providers: `<SaleorAuthProvider>` and `<Provider>`.
+
+`<SaleorAuthProvider>` comes from our React.js-auth package, located at `@saleor/auth-sdk/react`, and it needs to be set up with the Saleor auth client.
+
+The `<Provider>` comes from `urql` and it needs the GraphQL client instance, which is enhanced with the authenticated `fetch` that comes from the Saleor auth client.
+
+Lastly, you must run the `useAuthChange` hook. This links the `onSignedOut` and `onSignedIn` events and is meant to refresh the GraphQL store and in-flight active GraphQL queries.
+
+Let's look at an example:
+
+```tsx
+import { AppProps } from "next/app";
+import { Provider, cacheExchange, fetchExchange, ssrExchange } from "urql";
+import { SaleorAuthProvider, useAuthChange } from "@saleor/auth-sdk/react";
+
+const saleorApiUrl = "<your Saleor API URL>";
+
+const saleorAuthClient = createSaleorAuthClient({ saleorApiUrl });
+
+const makeUrqlClient = () =>
+  createClient({
+    url: saleorApiUrl,
+    fetch: saleorAuthClient.fetchWithAuth,
+    exchanges: [cacheExchange, fetchExchange],
+  });
+
+export default function App({ Component, pageProps }: AppProps) {
+  // https://github.com/urql-graphql/urql/issues/297#issuecomment-504782794
+  const [urqlClient, setUrqlClient] = useState<Client>(makeUrqlClient());
+
+  useAuthChange({
+    saleorApiUrl,
+    onSignedOut: () => setUrqlClient(makeUrqlClient()),
+    onSignedIn: () => setUrqlClient(makeUrqlClient()),
+  });
+
+  return (
+    <SaleorAuthProvider client={saleorAuthClient}>
+      <Provider value={urqlClient}>
+        <Component {...pageProps} />
+      </Provider>
+    </SaleorAuthProvider>
+  );
+}
+```
+
+Then, in your register, login and logout forms you can use the auth methods (`signIn`, `signOut`) provided by the `useSaleorAuthContext()`. For example, `signIn` is usually triggered when submitting the login form credentials.
+
+```tsx
+import React, { FormEvent } from "react";
+import { useSaleorAuthContext } from "@saleor/auth-sdk/react";
+import { gql, useQuery } from "urql";
+
+const CurrentUserDocument = gql`
+  query CurrentUser {
+    me {
+      id
+      email
+      firstName
+      lastName
+      avatar {
+        url
+        alt
+      }
+    }
+  }
+`;
+
+export default function LoginPage() {
+  const { signIn, signOut } = useSaleorAuthContext();
+
+  const [{ data: currentUser, fetching: loading }] = useQuery({
+    query: CurrentUserDocument,
+    pause: isAuthenticating,
+  });
+
+  const submitHandler = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+
+    const result = await signIn({
+      email: "admin@example.com",
+      password: "admin",
+    });
+
+    if (result.data.tokenCreate.errors) {
+      // handle errors
+    }
+  };
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <main>
+      {currentUser?.me ? (
+        <>
+          <div>Display user {JSON.stringify(currentUser)}</div>
+          <button className="button" onClick={() => signOut()}>
+            Log Out
+          </button>
+        </>
+      ) : (
+        <div>
+          <form onSubmit={submitHandler}>
+            {/* You must connect your inputs to state or use a form library such as react-hook-form */}
+            <input type="email" name="email" placeholder="Email" />
+            <input type="password" name="password" placeholder="Password" />
+            <button className="button" type="submit">
+              Log In
+            </button>
+          </form>
+        </div>
+      )}
+    </main>
+  );
+}
+```
+
+### Next.js (Pages Router) with OpenID Connect
+
+Setup `_app.tsx` as described above. In your login component trigger the external auth flow using the following code:
+
+```tsx
+import { useSaleorAuthContext, useSaleorExternalAuth } from "@saleor/auth-sdk/react";
+import { ExternalProvider } from "@saleor/auth-sdk";
+import Link from "next/link";
+import { gql, useQuery } from "@apollo/client";
+
+export default function Home() {
+  const {
+    loading: isLoadingCurrentUser,
+    error,
+    data,
+  } = useQuery(gql`
+    query CurrentUser {
+      me {
+        id
+        email
+        firstName
+        lastName
+      }
+    }
+  `);
+  const { authURL, loading: isLoadingExternalAuth } = useSaleorExternalAuth({
+    saleorApiUrl,
+    provider: ExternalProvider.OpenIDConnect,
+    redirectURL: "<your Next.js app>/api/auth/callback",
+  });
+
+  const { signOut } = useSaleorAuthContext();
+
+  if (isLoadingExternalAuth || isLoadingCurrentUser) {
+    return <div>Loading...</div>;
+  }
+
+  if (data?.me) {
+    return (
+      <div>
+        {JSON.stringify(data)}
+        <button onClick={() => signOut()}>Logout</button>
+      </div>
+    );
+  }
+  if (authURL) {
+    return (
+      <div>
+        <Link href={authURL}>Login</Link>
+      </div>
+    );
+  }
+  return <div>Something went wrong</div>;
+}
+```
+
+You also need to define the auth callback. In `pages/api/auth` create the `callback.ts` with the following content:
+
+```ts
+import { ExternalProvider, SaleorExternalAuth } from "@saleor/auth-sdk";
+import { createSaleorExternalAuthHandler } from "@saleor/auth-sdk/next";
+
+const externalAuth = new SaleorExternalAuth("<your Saleor instance URL>", ExternalProvider.OpenIDConnect);
+
+export default createSaleorExternalAuthHandler(externalAuth);
+```
+
+## FAQ
+
+## How do I reset password?
+
+The `SaleorAuthClient` class provides you with a reset password method. If the reset password mutation is successful, it will log you in automatically, just like after a regular sign-in. The [`onSignIn` method of `useAuthChange` hook](#how-do-i-tell-my-graphql-client-to-refresh-queries-on-signin--signout) will also be triggered.
+
+```javascript
+const { resetPassword } = useSaleorAuthContext();
+
+const response = await resetPassword({
+  email: "example@mail.com",
+  password: "newPassword",
+  token: "apiToken",
+});
+```

package/justfile

@@ -0,0 +1,9 @@
+alias p := publish
+
+publish version:
+  #!/usr/bin/env bash
+  set -euo pipefail
+  pnpm build
+  newversion=`pnpm version {{version}} -m "Release %s" --tag-version-prefix=`
+  echo Preparing $newversion
+  pnpm publish --access public --no-git-checks

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "ss-saleor-auth-sdk",
+  "version": "1.0.0",
+  "description": "Auth SDK for Saleor",
+  "sideEffects": false,
+  "types": "index.d.ts",
+  "main": "index.js",
+  "module": "index.mjs",
+  "scripts": {
+    "prepublishOnly": "pnpm build",
+    "prebuild": "pnpm clean",
+    "watch": "tsup-node src/* --format esm,cjs --dts --watch",
+    "build": "tsup-node src/* --format esm,cjs --dts && clear-package-json package.json -o dist/package.json --fields publishConfig && pnpm copy-files",
+    "clean": "rm -rf ./dist/*",
+    "test": "vitest",
+    "lint": "prettier --write . && eslint --fix src ",
+    "lint:ci": "prettier --check . && eslint src",
+    "release": "cd dist && ../node_modules/.bin/release-it",
+    "copy-files": "cp README.md dist/README.md"
+  },
+  "keywords": [],
+  "author": "Saleor Team",
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "cookie": "^0.6.0",
+    "graphql": "^16.8.1"
+  },
+  "peerDependencies": {
+    "next": "^13.4.4 || ^14.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "urql": "^4.0.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "urql": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "@types/cookie": "^0.5.4",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^20.9.0",
+    "@types/node-fetch": "^2.6.9",
+    "@types/react": "^18.2.37",
+    "@types/react-dom": "^18.2.15",
+    "@types/uuid": "^9.0.7",
+    "@typescript-eslint/eslint-plugin": "^6.11.0",
+    "@typescript-eslint/parser": "^6.11.0",
+    "@vitejs/plugin-react": "^4.1.1",
+    "clean-publish": "^4.2.0",
+    "eslint": "^8.53.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
+    "eslint-plugin-import": "^2.29.0",
+    "eslint-plugin-jsx-a11y": "^6.8.0",
+    "eslint-plugin-react": "^7.33.2",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "jsdom": "^22.1.0",
+    "prettier": "^3.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "release-it": "^17.0.0",
+    "tsup": "^7.2.0",
+    "typescript": "^5.2.2",
+    "urql": "^4.0.6",
+    "vite": "^4.5.0",
+    "vitest": "^0.34.6",
+    "vitest-fetch-mock": "^0.2.2"
+  },
+  "lint-staged": {
+    "*.{js,ts,tsx}": "eslint --cache --fix",
+    "*.{js,ts,tsx,css,md,json}": "prettier --write"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./react": {
+      "types": "./react/index.d.ts",
+      "import": "./react/index.mjs",
+      "require": "./react/index.js"
+    },
+    "./next": {
+      "types": "./next/index.d.ts",
+      "import": "./next/index.mjs",
+      "require": "./next/index.js"
+    },
+    "./next/server": {
+      "types": "./next/server.d.ts",
+      "import": "./next/server.mjs",
+      "require": "./next/server.js"
+    },
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saleor/auth-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/saleor/auth-sdk/issues"
+  },
+  "homepage": "https://github.com/saleor/auth-sdk#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/setup-tests.ts

@@ -0,0 +1,10 @@
+import createFetchMock from "vitest-fetch-mock";
+import { beforeEach, vi } from "vitest";
+
+const fetchMocker = createFetchMock(vi);
+fetchMocker.enableMocks();
+
+beforeEach(() => {
+  fetchMocker.resetMocks();
+  fetchMocker.doMock();
+});

package/src/SaleorAccessTokenStorageHandler.ts

@@ -0,0 +1,26 @@
+import type { StorageRepository } from "./types";
+
+export const getAccessTokenKey = (prefix?: string) =>
+  [prefix, "saleor_auth_access_token"].filter(Boolean).join("+");
+
+export class SaleorAccessTokenStorageHandler {
+  constructor(
+    private storage: StorageRepository,
+    private prefix?: string,
+  ) {}
+
+  getAccessToken = () => {
+    const key = getAccessTokenKey(this.prefix);
+    return this.storage.getItem(key);
+  };
+
+  setAccessToken = (token: string) => {
+    const key = getAccessTokenKey(this.prefix);
+    return this.storage.setItem(key, token);
+  };
+
+  clearAuthStorage = () => {
+    const key = getAccessTokenKey(this.prefix);
+    return this.storage.removeItem(key);
+  };
+}