@yourself_id/siwys-react-js 0.0.27 → 0.0.28-sapp-118-documentation.0

package/README.md

@@ -1,19 +1,125 @@
-# SIWYS JS
+# Sign in with your SELF React SDK
 
-TODO: Update me.
+Sign in with your SELF (SIWYS) is a SELF product that allows users to authenticate with partner apps/dapps using their own private keys and credentials and the MDIP protocol.
 
-# Local Development
+This SDK is designed to offer reusable React components to help facilitate the user-facing authentication workflow.
 
-Uses [Vite](https://vite.dev/) for testing components locally.
+Please refer to the partner integration guide for more information regarding SIWYS.
 
-1. Render the component(s) you want to test inside `src/demo/demo.tsx`
-2. Run `yarn dev`
-3. Test at http://localhost:5173
+# Install
 
-# Importing Icons as SVGs
+```
+npm install @yourself_id/siwys-react-js
+```
+or
+```
+yarn add @yourself_id/siwys-react-js
+```
 
-Uses [SVGR](https://react-svgr.com/) to transform SVGs into React components.
+# Render SIWYS Button
 
-1. Save the SVG in the `icons/` folder
-2. Run `yarn generate-icons`
-3. The associated React components will be generated inside `src/icons`
+```js
+<SiwysButton
+  onClick={() => {
+    // navigate to dedicated SIWYS page
+  }}
+  colorTheme="dark"
+  glow
+/>
+```
+
+The following are the acceptable props for the `SiwysButton` component:
+
+|Parameter|Type|Description|Required|Default|
+|--|-|-|-|-|
+|onClick|func|Function to execute.<br/>This should redirect to a dedicated page that renders the `SignInWithYourSelf` Component (below) |Yes||
+|colorTheme|string|Color theme of button. <br/>Either "light" or "dark"|No|Auto-detect from system|
+|glow|boolean|Whether to show glow hover effect|No|false|
+
+# Render SIWYS Component
+
+The SIWYS component includes the QR code for scanning as well as additional information to inform users on how to take action. Consequently, this component should ideally be rendered on its own dedicated page to avoid any formatting/styling issues.
+
+```js
+<SignInWithYourSelf
+  createChallengeUrl="https://your-sever-url/challenges"
+  pollForChallengeComplete="https://your-server-url/auth"
+  pollingIntervalSec={5}
+  onChallengeComplete={(resp) => console.log("Auth Respone:", resp)}
+/>
+```
+
+The following are the acceptable props for the `SignInWithYourSelf` component:
+
+|Parameter|Type|Description|Required|Default|
+|--|-|-|-|-|
+|createChallengeUrl|func|URL for creating the Challenge.<br/>This should be the endpoint you created when setting up the SIWYS API SDK.|Yes||
+|pollForChallengeComplete|string|URL polling for challenge completion status.<br/>This should be the endpoint you created when setting up the SIWYS API SDK.|No|The component will not poll for challenge completion.|
+|pollingIntervalSec|boolean|How often to poll for Challenge completion.|No|5|
+|onChallengeComplete|boolean|Callback for handling a completed Challenge.<br/>Will pass back the result of the polling endpoint.<br/>Required when `pollForAuthUrl` is supplied.|No|N/A|
+
+> [!IMPORTANT]
+> If you do not provide the `pollForAuthUrl` you must implement your own logic of informing the Client when the challenge has been completed.
+> For more information see the setup guide for the SIWYS API SDK.
+
+# Complete Example
+
+The following is a complete, minimal example using Next.js and assuming that the `pollForChallengeCompleteUrl` sets the appropriate authentication mechansim, eg a JWT cookie.
+
+```js
+// index.tsx entrypoint
+import React, { render, useEffect, useState } from "react"
+
+import { useRouter } from 'next/router';
+
+import { SiwysButton } from "@yourself_id/react-js";
+
+const App: React.FC<{}> = () => {
+  const [user, setUser] = useState();
+  
+  const router = useRouter();
+
+  useEffect(() => {
+    // fetch user info if authenticated
+    fetch("/me").then(setUser)
+  }, [])
+
+  return (
+    <div>
+      {user && <Homepage />}
+      {!user && (
+        <SiwysButton
+          colorTheme="dark"
+          glow
+          onClick={() => router.push("/login")}
+        />
+      )}
+    </div>
+  );
+};
+
+export default App;
+
+render(<App />, document.getElementById('app')!)
+
+// pages/login/index.tsx
+import React, { render, useState } from "react"
+
+import { SignInWithYourSelf } from "@yourself_id/react-js";
+
+const Login: React.FC<{}> = () => {
+  const router = useRouter();
+
+  return (
+    <SignInWithYourSelf
+      createChallengeUrl="https://your-server-url/challenges"
+      pollForChallengeCompleteUrl="https://your-server-url/auth"
+      onChallengeComplete={() => router.push("/")} 
+    />
+  );
+};
+
+export default Login;
+```
+
+Note: `onChallengeComplete` may have a Coo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yourself_id/siwys-react-js",
-  "version": "0.0.27",
+  "version": "0.0.28-sapp-118-documentation.0+c67697f",
   "description": "A React component library",
   "repository": "https://github.com/selfidhq/siwys-js",
   "main": "dist/index.js",
@@ -50,5 +50,5 @@
   "resolutions": {
     "styled-components": "^6"
   },
-  "gitHead": "b68922569293a8eb9c7491c16be8788ad12e5de7"
+  "gitHead": "c67697fc65379095623304473e512803079cb7ee"
 }