@nylas/react 2.2.4 → 3.0.1

package/LICENSE.md

@@ -20,3 +20,4 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+

package/README.md

@@ -9,8 +9,6 @@ React components for Nylas Scheduler
 - [Node.js](https://nodejs.org/en/) v20 or higher
 - [React.js](https://react.dev/) v18 or higher
 
-## Compatibility Notice
-
 ## Installation
 
 Install Nylas React Components via npm:
@@ -25,6 +23,16 @@ or yarn
   yarn add @nylas/react@latest
 ```
 
+## Exports overview
+
+- **Elements**
+  - `NylasSchedulerEditor`, `NylasScheduling`, `NylasSchedulingMethod`
+  - Import from `@nylas/react` or `@nylas/react/elements`
+
+- **Connect**
+  - `useNylasConnect`, `NylasConnectButton`
+  - Import from `@nylas/react` or `@nylas/react/connect`
+
 ## Getting Started
 
 The following example adds the Nylas Scheduler Editor and Scheduling components to your React app.
@@ -64,7 +72,7 @@ function App() {
           element={
             <div>
               <NylasSchedulerEditor
-                schedulerPreviewLink={`${window.location.origin}/?config_id={config.id}`}
+                schedulerPreviewLink={`${window.location.origin}/?config_id=${config.id}`}
                 nylasSessionsConfig={{
                   clientId: "NYLAS_CLIENT_ID", // Replace with your Nylas client ID from the previous
                   redirectUri: `${window.location.origin}/scheduler-editor`,
@@ -105,9 +113,205 @@ npm run dev -- --port <PORT>
 
 After you run the command, open your browser to `http://localhost:<PORT>/scheduler-editor` to see your Scheduler Editor and create your first Scheduling Page.
 
+
+## Nylas Connect Hook
+
+The `useNylasConnect` hook provides a simple way to add OAuth authentication to your React app using Nylas Connect.
+
+### Basic Usage
+
+```jsx
+import { useNylasConnect } from '@nylas/react';
+
+function LoginButton() {
+  const { isConnected, connect, logout, grant, isLoading } = useNylasConnect({
+    clientId: 'your-nylas-client-id',
+    redirectUri: 'http://localhost:3000/callback'
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  if (isConnected) {
+    return (
+      <div>
+        <p>Connected as: {grant?.email}</p>
+        <button onClick={() => logout()}>Logout</button>
+      </div>
+    );
+  }
+
+  return (
+    <button onClick={() => connect({ method: 'popup' })}>
+      Connect Account
+    </button>
+  );
+}
+```
+
+
+### Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `clientId` | `string` | - | Your Nylas Client ID |
+| `redirectUri` | `string` | - | OAuth callback URL |
+| `autoHandleCallback` | `boolean` | `true` | Automatically handle OAuth callback |
+| `autoRefreshInterval` | `number` | - | Auto-refresh session interval (ms) |
+| `retryAttempts` | `number` | `0` | Number of retry attempts for failed operations |
+| `enableAutoRecovery` | `boolean` | `false` | Enable automatic error recovery |
+
+### Hook Return Values
+
+The hook returns an object with the following properties:
+
+**State:**
+- `isConnected` - Whether user is authenticated
+- `grant` - Current user's grant information
+- `isLoading` - Loading state for operations
+- `error` - Current error, if any
+
+**Actions:**
+- `connect(options)` - Start OAuth flow
+- `logout(grantId?)` - Sign out user
+- `refreshSession()` - Refresh current session
+- `subscribe(callback)` - Listen to connection events
+
+### Environment Setup
+
+For security, use environment variables for your configuration:
+
+```bash
+# .env.local
+VITE_NYLAS_CLIENT_ID=your-nylas-client-id
+VITE_NYLAS_REDIRECT_URI=http://localhost:3000/callback
+```
+
+```jsx
+const { isConnected, connect } = useNylasConnect({
+  clientId: import.meta.env.VITE_NYLAS_CLIENT_ID,
+  redirectUri: import.meta.env.VITE_NYLAS_REDIRECT_URI
+});
+```
+
+
+
+
+
+## Nylas Connect Button
+
+The `NylasConnectButton` component provides a simple way to add email provider authentication to your React application.
+
+### Basic Usage
+
+```jsx
+import { NylasConnectButton } from "@nylas/react";
+
+function App() {
+  return (
+    <NylasConnectButton
+      clientId="your-nylas-client-id"
+      redirectUri="http://localhost:3000/callback"
+      onSuccess={(result) => {
+        console.log("Connected successfully:", result);
+      }}
+      onError={(error) => {
+        console.error("Connection failed:", error);
+      }}
+    />
+  );
+}
+```
+
+### External Identity Provider Integration
+
+For applications that use external identity providers (via JWKS), you can pass identity provider tokens during authentication:
+
+```jsx
+import { NylasConnectButton } from "@nylas/react";
+
+function App() {
+  // Function to retrieve JWT token from your external identity provider
+  const getIdpToken = async () => {
+    // Get the JWT token from your authentication system
+    const token = await yourAuthSystem.getJWT();
+    return token; // or return null if not available
+  };
+
+  return (
+    <NylasConnectButton
+      clientId="your-nylas-client-id"
+      redirectUri="http://localhost:3000/callback"
+      identityProviderToken={getIdpToken}
+      onSuccess={(result) => {
+        console.log("Connected with IDP claims:", result);
+      }}
+      onError={(error) => {
+        console.error("Connection failed:", error);
+      }}
+    />
+  );
+}
+```
+
+### Custom Backend Code Exchange
+
+For enhanced security, you can handle the OAuth code exchange on your backend:
+
+```jsx
+import { NylasConnectButton } from "@nylas/react";
+
+function App() {
+  const handleCodeExchange = async (params) => {
+    // Send the authorization code to your backend
+    const response = await fetch("/api/auth/exchange", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        code: params.code,
+        state: params.state,
+        clientId: params.clientId,
+        redirectUri: params.redirectUri,
+        scopes: params.scopes,
+        provider: params.provider,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Token exchange failed: ${response.statusText}`);
+    }
+
+    const tokenData = await response.json();
+
+    // Return the expected ConnectResult format
+    return {
+      accessToken: tokenData.access_token,
+      idToken: tokenData.id_token,
+      grantId: tokenData.grant_id,
+      expiresAt: Date.now() + tokenData.expires_in * 1000,
+      scope: tokenData.scope,
+      grantInfo: tokenData.grant_info,
+    };
+  };
+
+  return (
+    <NylasConnectButton
+      clientId="your-nylas-client-id"
+      redirectUri="http://localhost:3000/callback"
+      codeExchange={handleCodeExchange}
+      onSuccess={(result) => {
+        console.log("Connected successfully:", result);
+      }}
+      onError={(error) => {
+        console.error("Connection failed:", error);
+      }}
+    />
+  );
+}
+```
+
 ## Links
 
-For a complete walkthrough on setting up Scheduler can be found at [https://developer.nylas.com/docs/v3/getting-started/scheduler/](https://developer.nylas.com/docs/v3/getting-started/scheduler/), with the complete code available on [GitHub](https://github.com/nylas-samples/quickstart-scheduler-react).
+A complete walkthrough for setting up Scheduler can be found at [https://developer.nylas.com/docs/v3/getting-started/scheduler/](https://developer.nylas.com/docs/v3/getting-started/scheduler/), with the complete code available on [GitHub](https://github.com/nylas-samples/quickstart-scheduler-react).
 
 ### Further reading: