@casperid/react 1.1.0 → 2.0.0

package/README.md

@@ -2,6 +2,25 @@
 
 The official React SDK for integrating CasperID — the privacy-first, decentralized identity layer for the open web.
 
+## Hosted Authorization
+
+Passkeys registered for `casperid.com` must be used from the CasperID account domain. SDK v2 starts the hosted flow and does not embed identity or KYC screens in the partner application.
+
+```tsx
+import { authorizeWithCasperID } from '@casperid/react';
+
+const result = await authorizeWithCasperID({
+  clientId: 'app_your_client_id',
+  redirectUri: `${window.location.origin}/auth/callback`,
+  accountUrl: 'https://account.casperid.com',
+  mode: 'auto',
+  // Optional. Popup flows default to 30 minutes; set 0 to disable.
+  timeoutMs: 30 * 60 * 1000,
+});
+```
+
+`auto` opens a popup on desktop and redirects the full page on mobile. On the callback route, call `consumeHostedAuthorizationCallback()`. Send its `code`, `codeVerifier`, and `redirectUri` to your backend, which exchanges them at `POST /api/oauth/token` using the app secret. Never expose the app secret in frontend code.
+
 ## Why CasperID?
 
 CasperID provides a "Sign in with Google" style experience but with the security and ownership of Web3.
@@ -20,51 +39,43 @@ npm install @casperid/react
 ## Quick Start
 
 ```tsx
-import { CasperIDProvider, CasperIDModal } from '@casperid/react';
-import '@casperid/react/style.css';
+import { CasperIDButton, useHostedAuthorizationCallback } from '@casperid/react';
 
 function App() {
-  const [isOpen, setIsOpen] = useState(false);
-
-  const handleSuccess = (sessionToken, data) => {
-    console.log('Verified!', sessionToken, data?.businessToken);
-    setIsOpen(false);
+  const handleSuccess = (result) => {
+    // Send result.code, result.codeVerifier, and result.redirectUri to your backend.
   };
+  useHostedAuthorizationCallback(handleSuccess, console.error);
 
   return (
-    <div>
-      <button onClick={() => setIsOpen(true)}>Verify with CasperID</button>
-      
-      <CasperIDModal 
-        isOpen={isOpen}
-        onClose={() => setIsOpen(false)}
-        onSuccess={handleSuccess}
-        apiKey="your_api_key_here"
-        requiredTier="layer_2" // Liveness verification
-      />
-    </div>
+    <CasperIDButton
+      clientId="app_your_client_id"
+      redirectUri={`${window.location.origin}/auth/callback`}
+      mode="auto"
+      timeoutMs={30 * 60 * 1000}
+      onSuccess={handleSuccess}
+      onError={console.error}
+    >
+      Continue with CasperID
+    </CasperIDButton>
   );
 }
 ```
 
-## Handling Success
-
-The `onSuccess` callback provides the `sessionToken` as the first argument and an optional `data` object containing the `businessToken` as the second argument.
+## Backend Exchange
 
-```tsx
-const handleSuccess = (sessionToken, { businessToken } = {}) => {
-  // 1. Send businessToken to your server for verification
-  // 2. Decode it to get user identity
-};
-```
+Exchange the authorization code server-side at `POST /api/oauth/token` using your app secret and PKCE verifier. Never expose the app secret in browser code.
 
 ### Understanding User Identity
 
-When you decode the `businessToken` or call the `/verify-token` endpoint, you will receive:
+The returned business token includes:
 
 - **`humanId`**: This is the unique, user-friendly handle (e.g., `alice.casper`). **This should be prioritized for your UI.**
 - **`name`**: The user's verified full name (or `null` if not shared).
-- **`wallet`**: The Casper wallet address. In early registration stages, this may be `pending_wallet` until the user finishes minting. The SDK automatically refreshes the token once minting is complete.
+- **`wallet`**: The Casper wallet address.
+- **`authorization_status`**: `complete` or `provisional`.
+- **`required_tier` / `tier`**: The app's required tier and the user's actual tier.
+- **`scopes`**: The permissions approved by the user.
 
 ## Documentation