@quiltt/react 2.1.0 → 2.1.2

package/src/hooks/session/useIdentifySession.ts

@@ -0,0 +1,55 @@
+import { useCallback } from 'react'
+
+import type {
+  AuthAPI,
+  SessionResponse,
+  UnprocessableData,
+  UnprocessableResponse,
+  UsernamePayload,
+} from '@quiltt/core'
+
+import type { SetSession } from '../useSession'
+
+type IdentifySessionCallbacks = {
+  onSuccess?: () => unknown
+  onChallenged?: () => unknown
+  onError?: (errors: UnprocessableData) => unknown
+}
+type IdentifySession = (
+  payload: UsernamePayload,
+  callbacks: IdentifySessionCallbacks
+) => Promise<unknown>
+
+type UseIdentifySession = (auth: AuthAPI, setSession: SetSession) => IdentifySession
+
+export const useIdentifySession: UseIdentifySession = (auth, setSession) => {
+  const identifySession = useCallback<IdentifySession>(
+    async (payload, callbacks) => {
+      const response = await auth.identify(payload)
+      const unprocessableResponse = response as UnprocessableResponse
+
+      switch (response.status) {
+        case 201:
+          setSession((response as SessionResponse).data.token)
+          if (callbacks.onSuccess) return callbacks.onSuccess()
+          break
+
+        case 202:
+          if (callbacks.onChallenged) return callbacks.onChallenged()
+          break
+
+        case 422:
+          if (callbacks.onError) return callbacks.onError(unprocessableResponse.data)
+          break
+
+        default:
+          throw new Error(`Unexpected auth identify response status: ${response.status}`)
+      }
+    },
+    [auth, setSession]
+  )
+
+  return identifySession
+}
+
+export default useIdentifySession

package/src/hooks/session/useImportSession.ts

@@ -0,0 +1,43 @@
+import { useCallback } from 'react'
+
+import type { AuthAPI, Maybe, QuilttJWT } from '@quiltt/core'
+
+import type { SetSession } from '../useSession'
+
+type ImportSession = (token: string) => Promise<boolean>
+
+type UseImportSession = (
+  auth: AuthAPI,
+  session: Maybe<QuilttJWT> | undefined,
+  setSession: SetSession
+) => ImportSession
+
+export const useImportSession: UseImportSession = (auth, session, setSession) => {
+  const importSession = useCallback<ImportSession>(
+    async (token) => {
+      if (!token) return !!session
+      if (session && session.token == token) return true
+
+      const response = await auth.ping(token)
+
+      switch (response.status) {
+        case 200:
+          setSession(token)
+          return true
+          break
+
+        case 401:
+          return false
+          break
+
+        default:
+          throw new Error(`Unexpected auth ping response status: ${response.status}`)
+      }
+    },
+    [auth, session, setSession]
+  )
+
+  return importSession
+}
+
+export default useImportSession

package/src/hooks/session/useRevokeSession.ts

@@ -0,0 +1,27 @@
+import { useCallback } from 'react'
+
+import type { AuthAPI, Maybe, QuilttJWT } from '@quiltt/core'
+
+import type { SetSession } from '../useSession'
+
+type RevokeSession = () => Promise<void>
+
+type UseRevokeSession = (
+  auth: AuthAPI,
+  session: Maybe<QuilttJWT> | undefined,
+  setSession: SetSession
+) => RevokeSession
+
+export const useRevokeSession: UseRevokeSession = (auth, session, setSession) => {
+  const revokeSession = useCallback<RevokeSession>(async () => {
+    if (!session) return
+
+    await auth.revoke(session.token)
+
+    setSession(null)
+  }, [auth, session, setSession])
+
+  return revokeSession
+}
+
+export default useRevokeSession

package/src/hooks/useQuilttClient.ts

@@ -0,0 +1,5 @@
+import { useApolloClient } from '@apollo/client/index.js'
+
+export const useQuilttClient = useApolloClient
+
+export default useQuilttClient

package/src/hooks/useQuilttConnector.ts

@@ -0,0 +1,39 @@
+'use client'
+
+import { useEffect } from 'react'
+import { useQuilttSession } from './useQuilttSession'
+
+const QUILTT_CDN_BASE = process.env.QUILTT_CDN_BASE || 'https://cdn.quiltt.io'
+
+// Script Element Singleton
+let scriptElement: HTMLScriptElement
+
+export const useQuilttConnector = () => {
+  const { session } = useQuilttSession()
+
+  // Create Script Element
+  useEffect(() => {
+    if (scriptElement) return
+
+    scriptElement = document.createElement('script')
+    scriptElement.src = `${QUILTT_CDN_BASE}/v1/connector.js`
+
+    if (session?.token) {
+      scriptElement.setAttribute('quiltt-token', session.token)
+    }
+
+    document.head.appendChild(scriptElement)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  // Update Script Element
+  useEffect(() => {
+    if (!scriptElement) return
+
+    if (session?.token && session.token !== scriptElement.getAttribute('quiltt-token')) {
+      scriptElement.setAttribute('quiltt-token', session.token)
+    } else if (!session?.token && scriptElement.getAttribute('quiltt-token')) {
+      scriptElement.removeAttribute('quiltt-token')
+    }
+  }, [session?.token])
+}

package/src/hooks/useQuilttSession.ts

@@ -0,0 +1,45 @@
+import { useCallback } from 'react'
+
+import { useSession } from './useSession'
+
+import { AuthAPI } from '@quiltt/core'
+
+import {
+  useAuthenticateSession,
+  useIdentifySession,
+  useImportSession,
+  useRevokeSession,
+} from './session'
+import { useQuilttSettings } from './useQuilttSettings'
+
+export const useQuilttSession = () => {
+  const { clientId } = useQuilttSettings()
+  const [session, setSession] = useSession()
+
+  const auth = new AuthAPI(clientId)
+  const importSession = useImportSession(auth, session, setSession)
+  const identifySession = useIdentifySession(auth, setSession)
+  const authenticateSession = useAuthenticateSession(auth, setSession)
+  const revokeSession = useRevokeSession(auth, session, setSession)
+
+  // Optionally takes a token, to help guard against async processes clearing the wrong session
+  const forgetSession = useCallback(
+    async (token?: string) => {
+      if (!token || (session && token && token == session.token)) {
+        setSession(null)
+      }
+    },
+    [session, setSession]
+  )
+
+  return {
+    session,
+    importSession,
+    identifySession,
+    authenticateSession,
+    revokeSession,
+    forgetSession,
+  }
+}
+
+export default useQuilttSession

package/src/hooks/useQuilttSettings.ts

@@ -0,0 +1,17 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+
+type QuilttSettingsContext = {
+  clientId?: string | undefined
+}
+
+export const QuilttSettings = createContext<QuilttSettingsContext>({})
+
+export const useQuilttSettings = () => {
+  const settings = useContext(QuilttSettings)
+
+  return { ...settings }
+}
+
+export default useQuilttSettings

package/src/hooks/useSession.ts

@@ -0,0 +1,69 @@
+'use client'
+
+import { Dispatch, SetStateAction, useMemo } from 'react'
+import { useEffect, useCallback } from 'react'
+
+import type { Maybe, PrivateClaims, QuilttJWT } from '@quiltt/core'
+import { JsonWebTokenParse, Timeoutable } from '@quiltt/core'
+
+import { useStorage } from './useStorage'
+
+export type SetSession = Dispatch<SetStateAction<Maybe<string> | undefined>>
+
+const parse = JsonWebTokenParse<PrivateClaims>
+
+/**
+ * Singleton timeout, allows hooks to come and go, while ensuring that there is
+ * one notification being sent, preventing race conditions.
+ */
+const sessionTimer = new Timeoutable()
+
+/**
+ * useSession uses useStorage to support a global singleton style of access. When
+ * updated, all components, and windows should also invalidate.
+ *
+ * TODO: Support Rotation before Expiry
+ *
+ * Dataflow can come from two directions:
+ *  1. Login - Bottom Up
+ *    This happens on login, when a token is passed up through the setSession
+ *    callback. From here it needs to be stored, and shared for usage.
+ *  2. Refresh - Top Down
+ *    This happens when a page is reloaded or a person returns, and everything is
+ *    reinitialized.
+ */
+export const useSession = (storageKey = 'session'): [Maybe<QuilttJWT> | undefined, SetSession] => {
+  const [token, setToken] = useStorage<string>(storageKey)
+  const session = useMemo(() => parse(token), [token])
+
+  // Clear session if/when it expires
+  useEffect(() => {
+    if (!session) return
+
+    const expirationMS = session.claims.exp * 1000
+    const expire = () => setToken(null)
+
+    if (Date.now() >= expirationMS) {
+      expire()
+    } else {
+      sessionTimer.set(expire, expirationMS - Date.now())
+      return () => sessionTimer.clear(expire)
+    }
+  }, [session, setToken])
+
+  // Bubbles up from Login
+  const setSession = useCallback(
+    (nextState: Maybe<string> | SetStateAction<Maybe<string> | undefined> | undefined) => {
+      const newState = nextState instanceof Function ? nextState(token) : nextState
+
+      if (token !== newState && (!newState || parse(newState))) {
+        setToken(newState)
+      }
+    },
+    [token, setToken]
+  )
+
+  return [session, setSession]
+}
+
+export default useSession

package/src/hooks/useStorage.ts

@@ -0,0 +1,73 @@
+'use client'
+
+import type { Dispatch, SetStateAction } from 'react'
+import { useCallback, useEffect, useState } from 'react'
+
+import type { Maybe } from '@quiltt/core'
+import { GlobalStorage } from '@quiltt/core'
+
+/**
+ * Attempt to persist state with local storage, so it remains after refresh and
+ * across open documents. Falls back to in memory storage when localStorage is
+ * unavailable.
+ *
+ * This hook is used in the same way as useState except that you must pass the
+ * storage key in the 1st parameter. If the window object is not present (as in SSR),
+ * useStorage() will return the default nextState.
+ *
+ * Expect values to remain in sync
+ *   Across Hooks
+ *   Across Reloads
+ *   Across Windows (Documents)
+ *
+ * @param key
+ * @param initialState
+ * @returns {Array} [storage, setStorage]
+ */
+export const useStorage = <T>(
+  key: string,
+  initialState?: Maybe<T>
+): [Maybe<T> | undefined, Dispatch<SetStateAction<Maybe<T> | undefined>>] => {
+  const getStorage = useCallback(() => {
+    let state
+
+    if ((state = GlobalStorage.get(key)) !== undefined) {
+      return state
+    }
+
+    return initialState
+  }, [key, initialState])
+
+  const [hookState, setHookState] = useState<Maybe<T> | undefined>(getStorage())
+
+  const setStorage = useCallback(
+    (nextState: Maybe<T> | SetStateAction<Maybe<T> | undefined>) => {
+      const newState = nextState instanceof Function ? nextState(hookState) : nextState
+
+      if (hookState !== newState) {
+        GlobalStorage.set(key, newState)
+      }
+    },
+    [key, hookState]
+  )
+
+  /**
+   * The empty dependency array ensures that the effect runs only once when the component mounts
+   * and doesn't re-run unnecessarily on subsequent renders because it doesn't depend on any
+   * props or state variables that could change during the component's lifetime.
+   *
+   * Use an empty dependency array to avoid unnecessary re-renders.
+   */
+  useEffect(() => {
+    GlobalStorage.subscribe(key, setHookState)
+
+    setHookState(getStorage())
+
+    return () => GlobalStorage.unsubscribe(key, setHookState)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return [hookState, setStorage]
+}
+
+export default useStorage

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from '@quiltt/core'
+export * from './hooks'
+export * from './providers'
+export * from './components'

package/src/providers/QuilttAuthProvider.tsx

@@ -0,0 +1,43 @@
+'use client'
+
+import type { FC, PropsWithChildren } from 'react'
+import { useEffect } from 'react'
+
+import { ApolloProvider } from '@apollo/client'
+import { InMemoryCache, QuilttClient } from '@quiltt/core'
+import { useQuilttSession } from '../hooks'
+
+type QuilttAuthProviderProps = PropsWithChildren & {
+  token?: string
+}
+
+const Client = new QuilttClient({
+  cache: new InMemoryCache(),
+})
+
+/**
+ * If a token is provided, will validate the token against the api and then import
+ * it into trusted storage. While this process is happening, the component is put
+ * into a loading state and the children are not rendered to prevent race conditions
+ * from triggering within the transitionary state.
+ *
+ */
+export const QuilttAuthProvider: FC<QuilttAuthProviderProps> = ({ token, children }) => {
+  const { session, importSession } = useQuilttSession()
+
+  // Import Passed in Tokens
+  useEffect(() => {
+    if (token) importSession(token)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [token])
+
+  // Reset Client Store when logging in or out
+  useEffect(() => {
+    Client.resetStore()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [session])
+
+  return <ApolloProvider client={Client}>{children}</ApolloProvider>
+}
+
+export default QuilttAuthProvider

package/src/providers/QuilttProvider.tsx

@@ -0,0 +1,19 @@
+import type { FC, PropsWithChildren } from 'react'
+
+import { QuilttAuthProvider } from './QuilttAuthProvider'
+import { QuilttSettingsProvider } from './QuilttSettingsProvider'
+
+type QuilttProviderProps = PropsWithChildren & {
+  clientId?: string
+  token?: string
+}
+
+export const QuilttProvider: FC<QuilttProviderProps> = ({ clientId, token, children }) => {
+  return (
+    <QuilttSettingsProvider clientId={clientId}>
+      <QuilttAuthProvider token={token}>{children}</QuilttAuthProvider>
+    </QuilttSettingsProvider>
+  )
+}
+
+export default QuilttProvider

package/src/providers/QuilttSettingsProvider.tsx

@@ -0,0 +1,20 @@
+'use client'
+
+import type { FC, PropsWithChildren } from 'react'
+import { useState } from 'react'
+
+import { QuilttSettings } from '../hooks'
+
+type QuilttSettingsProviderProps = PropsWithChildren & {
+  clientId?: string
+}
+
+export const QuilttSettingsProvider: FC<QuilttSettingsProviderProps> = ({ clientId, children }) => {
+  const [_clientId] = useState(clientId)
+
+  return (
+    <QuilttSettings.Provider value={{ clientId: _clientId }}>{children}</QuilttSettings.Provider>
+  )
+}
+
+export default QuilttSettingsProvider

package/src/providers/index.ts

@@ -0,0 +1,3 @@
+export * from './QuilttAuthProvider'
+export * from './QuilttProvider'
+export * from './QuilttSettingsProvider'

package/src/types.ts

@@ -0,0 +1,9 @@
+import { Component, ComponentType, FC } from 'react'
+
+export type AnyTag = string | FC<any> | (new (props: any) => Component)
+
+export type PropsOf<Tag> = Tag extends keyof JSX.IntrinsicElements
+  ? JSX.IntrinsicElements[Tag]
+  : Tag extends ComponentType<infer Props>
+  ? Props & JSX.IntrinsicAttributes
+  : never