@atproto/lex-password-session 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @atproto/lex-password-session
 
+## 0.0.5
+
+### Patch Changes
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix `exports` field in package.json
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add JSDoc
+
+- Updated dependencies [[`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`7b9a98a`](https://github.com/bluesky-social/atproto/commit/7b9a98a763636c5f66a06da11fe6013f29dd9157), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015)]:
+  - @atproto/lex-schema@0.0.12
+  - @atproto/lex-client@0.0.12
+
 ## 0.0.4
 
 ### Patch Changes

package/README.md

@@ -1,9 +1,9 @@
-# @atproto/lex-password-agent
+# @atproto/lex-password-session
 
-Password-based client authentication for AT Protocol Lexicons. See the [Changelog](./CHANGELOG.md) for version history.
+Password-based session authentication for AT Protocol Lexicons. See the [Changelog](./CHANGELOG.md) for version history.
 
 ```bash
-npm install @atproto/lex-password-agent
+npm install @atproto/lex-password-session
 ```
 
 - Session management with automatic token refresh
@@ -17,7 +17,7 @@ npm install @atproto/lex-password-agent
 
 **What is this?**
 
-`@atproto/lex-password-agent` provides a `PasswordAgent` class that implements the `Agent` interface from `@atproto/lex-client`. It handles password-based authentication with AT Protocol services, including:
+`@atproto/lex-password-session` provides a `PasswordSession` class that implements the `Agent` interface from `@atproto/lex-client`. It handles password-based authentication with AT Protocol services, including:
 
 1. Creating sessions with username/password credentials
 2. Automatic token refresh when access tokens expire
@@ -26,28 +26,23 @@ npm install @atproto/lex-password-agent
 
 ```typescript
 import { Client } from '@atproto/lex-client'
-import { PasswordAgent } from '@atproto/lex-password-agent'
+import { PasswordSession } from '@atproto/lex-password-session'
 import * as app from './lexicons/app.js'
 
 // Login with credentials
-const result = await PasswordAgent.login({
+const session = await PasswordSession.login({
   service: 'https://bsky.social',
   identifier: 'alice.bsky.social',
   password: 'app-password',
-  hooks: {
-    onRefreshed: (session) => saveToStorage(session),
-    onDeleted: (session) => clearStorage(session),
-  },
+  onUpdated: (data) => saveToStorage(data),
+  onDeleted: (data) => clearStorage(data.did),
 })
 
-if (!result.success) throw result.error
-
-const agent = result.value
-const client = new Client(agent)
+const client = new Client(session)
 
 // Make authenticated requests
 const profile = await client.call(app.bsky.actor.getProfile, {
-  actor: agent.did,
+  actor: session.did,
 })
 ```
 
@@ -55,18 +50,19 @@ const profile = await client.call(app.bsky.actor.getProfile, {
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 - [Quick Start](#quick-start)
-- [PasswordAgent](#passwordagent)
+- [PasswordSession](#passwordsession)
   - [Login](#login)
   - [Two-Factor Authentication](#two-factor-authentication)
   - [Resume Session](#resume-session)
   - [Logout](#logout)
   - [Static Delete](#static-delete)
+  - [Create Account](#create-account)
 - [Session Hooks](#session-hooks)
-  - [onRefreshed](#onrefreshed)
-  - [onRefreshFailure](#onrefreshfailure)
+  - [onUpdated](#onupdated)
+  - [onUpdateFailure](#onupdatefailure)
   - [onDeleted](#ondeleted)
   - [onDeleteFailure](#ondeletefailure)
-- [Session Object](#session-object)
+- [Session Data](#session-data)
 - [Error Handling](#error-handling)
 - [Using with Client](#using-with-client)
 - [License](#license)
@@ -78,91 +74,92 @@ const profile = await client.call(app.bsky.actor.getProfile, {
 **1. Install the package**
 
 ```bash
-npm install @atproto/lex-password-agent @atproto/lex-client
+npm install @atproto/lex-password-session @atproto/lex-client
 ```
 
 **2. Login and make requests**
 
 ```typescript
 import { Client } from '@atproto/lex-client'
-import { PasswordAgent } from '@atproto/lex-password-agent'
+import { PasswordSession } from '@atproto/lex-password-session'
 
-const result = await PasswordAgent.login({
+const session = await PasswordSession.login({
   service: 'https://bsky.social',
   identifier: 'your-handle.bsky.social',
   password: 'your-app-password',
 })
 
-if (result.success) {
-  const agent = result.value
-  const client = new Client(agent)
+const client = new Client(session)
 
-  // Make authenticated API calls
-  console.log('Logged in as:', agent.did)
-}
+// Make authenticated API calls
+console.log('Logged in as:', session.did)
 ```
 
-## PasswordAgent
+## PasswordSession
 
-The `PasswordAgent` class manages password-based authentication sessions.
+The `PasswordSession` class manages password-based authentication sessions.
 
 ### Login
 
 Create a new session with username and password:
 
 ```typescript
-import { PasswordAgent } from '@atproto/lex-password-agent'
+import { PasswordSession } from '@atproto/lex-password-session'
 
-const result = await PasswordAgent.login({
+const session = await PasswordSession.login({
   service: 'https://bsky.social',
   identifier: 'alice.bsky.social', // handle or email
   password: 'app-password',
-  hooks: {
-    onRefreshed: (session) => {
-      // Persist session for later restoration
-      localStorage.setItem('session', JSON.stringify(session))
-    },
-    onDeleted: () => {
-      localStorage.removeItem('session')
-    },
+  onUpdated: (data) => {
+    // Persist session for later restoration
+    localStorage.setItem('session', JSON.stringify(data))
+  },
+  onDeleted: () => {
+    localStorage.removeItem('session')
   },
 })
 
-if (result.success) {
-  const agent = result.value
-  console.log('Logged in as:', agent.did)
-} else {
-  console.error('Login failed:', result.error, result.message)
-}
+console.log('Logged in as:', session.did)
 ```
 
-The `login()` method returns a discriminated union:
-
-- On success: `{ success: true, value: PasswordAgent }`
-- On expected errors: `XrpcResponseError` with `success: false`
-- On unexpected errors: throws the error
+The `login()` method throws on failure. For expected errors like invalid credentials, an `XrpcResponseError` is thrown. For 2FA requirements, a `LexAuthFactorError` is thrown.
 
 ### Two-Factor Authentication
 
-If the account has 2FA enabled, login will return an `AuthFactorTokenRequired` error:
-
-```typescript
-const result = await PasswordAgent.login({
-  service: 'https://bsky.social',
-  identifier: 'alice.bsky.social',
-  password: 'app-password',
-})
+> [!CAUTION]
+>
+> Two-factor authentication only applies when using **main account credentials**, which is **strongly discouraged**. Password authentication should be used with [app passwords](https://bsky.app/settings/app-passwords) only because they are designed for programmatic access (bots, scripts, CLI tools). For user-facing applications, use OAuth via [@atproto/oauth-client](../../../oauth/oauth-client) which provides better security and user control.
 
-if (!result.success && result.error === 'AuthFactorTokenRequired') {
-  // Prompt user for 2FA code, then retry
-  const code = await prompt2FACode()
+If the account has 2FA enabled, login will throw a `LexAuthFactorError`:
 
-  const retryResult = await PasswordAgent.login({
-    service: 'https://bsky.social',
-    identifier: 'alice.bsky.social',
-    password: 'app-password',
-    authFactorToken: code,
-  })
+```typescript
+import {
+  PasswordSession,
+  LexAuthFactorError,
+} from '@atproto/lex-password-session'
+
+async function loginWith2FA(
+  identifier: string,
+  password: string,
+  authFactorToken?: string,
+): Promise<PasswordSession> {
+  try {
+    return await PasswordSession.login({
+      service: 'https://bsky.social',
+      identifier,
+      password,
+      authFactorToken,
+      onUpdated: (data) => saveToStorage(data),
+      onDeleted: (data) => removeFromStorage(data.did),
+    })
+  } catch (err) {
+    if (err instanceof LexAuthFactorError && !authFactorToken) {
+      // 2FA required - prompt user for code
+      const token = await promptUserFor2FACode(err.message)
+      return loginWith2FA(identifier, password, token)
+    }
+    throw err
+  }
 }
 ```
 
@@ -171,24 +168,27 @@ if (!result.success && result.error === 'AuthFactorTokenRequired') {
 Restore a previously saved session:
 
 ```typescript
-import { PasswordAgent, Session } from '@atproto/lex-password-agent'
+import { PasswordSession, SessionData } from '@atproto/lex-password-session'
 
 // Load session from storage
-const savedSession: Session = JSON.parse(localStorage.getItem('session')!)
+const savedSession: SessionData = JSON.parse(localStorage.getItem('session')!)
 
 // Resume the session (automatically refreshes tokens)
-const agent = await PasswordAgent.resume(savedSession, {
-  hooks: {
-    onRefreshed: (session) => {
-      localStorage.setItem('session', JSON.stringify(session))
-    },
-    onDeleted: () => {
-      localStorage.removeItem('session')
-    },
+const session = await PasswordSession.resume(savedSession, {
+  onUpdated: (data) => {
+    localStorage.setItem('session', JSON.stringify(data))
+  },
+  onDeleted: () => {
+    localStorage.removeItem('session')
   },
 })
 
-console.log('Session resumed for:', agent.did)
+console.log('Session resumed for:', session.did)
+
+// Access session properties
+console.log(session.did) // User's DID
+console.log(session.handle) // User's handle
+console.log(session.destroyed) // false (session is active)
 ```
 
 > [!NOTE]
@@ -200,66 +200,87 @@ console.log('Session resumed for:', agent.did)
 End the session and notify the server:
 
 ```typescript
-await agent.logout()
+await session.logout()
 ```
 
 After logout:
 
 - The `onDeleted` hook is called
-- The agent is marked as destroyed (`agent.destroyed === true`)
+- The session is marked as destroyed (`session.destroyed === true`)
 - Further requests will throw `'Logged out'`
 
 ### Static Delete
 
-Delete a session without creating an agent instance:
+Delete a session without creating a session instance:
 
 ```typescript
-import { PasswordAgent, Session } from '@atproto/lex-password-agent'
+import { PasswordSession, SessionData } from '@atproto/lex-password-session'
 
-const session: Session = JSON.parse(localStorage.getItem('session')!)
+const data: SessionData = JSON.parse(localStorage.getItem('session')!)
 
 // Delete the session on the server
-await PasswordAgent.delete(session)
+await PasswordSession.delete(data)
 ```
 
 This is useful for cleanup scenarios where you don't need to make additional requests.
 
+### Create Account
+
+Create a new account and get an authenticated session:
+
+```typescript
+import { PasswordSession } from '@atproto/lex-password-session'
+
+const session = await PasswordSession.createAccount(
+  {
+    handle: 'alice.bsky.social',
+    email: 'alice@example.com',
+    password: 'secure-password',
+  },
+  {
+    service: 'https://bsky.social',
+    onUpdated: (data) => saveToStorage(data),
+    onDeleted: (data) => removeFromStorage(data.did),
+  },
+)
+
+console.log('Account created:', session.did)
+```
+
 ## Session Hooks
 
-Hooks provide callbacks for session lifecycle events. All hooks receive the agent as `this` context.
+Hooks provide callbacks for session lifecycle events. All hooks receive the session instance as `this` context.
 
-### onRefreshed
+### onUpdated
 
-Called when tokens are successfully refreshed:
+Called when the session is successfully created or refreshed:
 
 ```typescript
-const result = await PasswordAgent.login({
+const session = await PasswordSession.login({
   service: 'https://bsky.social',
   identifier: 'alice.bsky.social',
   password: 'app-password',
-  hooks: {
-    onRefreshed(session) {
-      // `this` is the PasswordAgent instance
-      console.log('Session refreshed for:', this.did)
-
-      // Persist the updated session
-      saveSession(session)
-    },
+  onUpdated(data) {
+    // `this` is the PasswordSession instance
+    console.log('Session updated for:', this.did)
+
+    // Persist the updated session
+    saveSession(data)
   },
 })
 ```
 
 > [!IMPORTANT]
 >
-> Requests are blocked while `onRefreshed` is running. Keep this callback fast to avoid delays.
+> Requests are blocked while `onUpdated` is running. Keep this callback fast to avoid delays.
 
-### onRefreshFailure
+### onUpdateFailure
 
 Called when token refresh fails due to transient errors (network issues, server unavailability):
 
 ```typescript
-hooks: {
-  onRefreshFailure(session, error) {
+{
+  onUpdateFailure(data, error) {
     console.warn('Token refresh failed:', error.message)
     // Session may still be valid - consider retry logic
   }
@@ -271,10 +292,10 @@ hooks: {
 Called when the session is terminated (logout or server-side invalidation):
 
 ```typescript
-hooks: {
-  onDeleted(session) {
-    console.log('Session ended for:', session.data.did)
-    clearPersistedSession(session.data.did)
+{
+  onDeleted(data) {
+    console.log('Session ended for:', data.did)
+    clearPersistedSession(data.did)
     redirectToLogin()
   }
 }
@@ -285,11 +306,11 @@ hooks: {
 Called when logout fails due to transient errors:
 
 ```typescript
-hooks: {
-  onDeleteFailure(session, error) {
+{
+  onDeleteFailure(data, error) {
     console.error('Logout failed:', error.message)
     // Consider queuing for retry to avoid orphaned sessions
-    queueLogoutRetry(session)
+    queueLogoutRetry(data)
   }
 }
 ```
@@ -298,29 +319,21 @@ hooks: {
 >
 > Ignoring delete failures can leave sessions active on the server. Implement retry logic for security-sensitive applications.
 
-## Session Object
+## Session Data
 
-The `Session` type contains all data needed to authenticate and restore sessions:
+The `SessionData` type contains all data needed to authenticate and restore sessions:
 
 ```typescript
-type Session = {
+type SessionData = {
   // Session credentials and user info from createSession response
-  data: {
-    accessJwt: string
-    refreshJwt: string
-    did: string
-    handle: string
-    email?: string
-    emailConfirmed?: boolean
-    didDoc?: object
-    // ... other fields from createSession
-  }
-
-  // When tokens were last refreshed
-  refreshedAt: string // ISO 8601 datetime
-
-  // PDS URL extracted from DID document (for routing requests)
-  pdsUrl: string | null
+  accessJwt: string
+  refreshJwt: string
+  did: string
+  handle: string
+  email?: string
+  emailConfirmed?: boolean
+  didDoc?: object
+  // ... other fields from createSession
 
   // Original service URL used for login
   service: string
@@ -329,28 +342,37 @@ type Session = {
 
 ## Error Handling
 
-Login errors are returned as `XrpcResponseError` objects:
+The `PasswordSession` class uses exception-based error handling:
 
 ```typescript
-const result = await PasswordAgent.login({
-  service: 'https://bsky.social',
-  identifier: 'alice.bsky.social',
-  password: 'wrong-password',
-})
-
-if (!result.success) {
-  switch (result.error) {
-    case 'AuthenticationRequired':
-      console.error('Invalid credentials')
-      break
-    case 'AuthFactorTokenRequired':
-      console.error('2FA required')
-      break
-    case 'AccountTakedown':
-      console.error('Account has been suspended')
-      break
-    default:
-      console.error('Login failed:', result.message)
+import {
+  PasswordSession,
+  LexAuthFactorError,
+} from '@atproto/lex-password-session'
+import { XrpcResponseError } from '@atproto/lex-client'
+
+try {
+  const session = await PasswordSession.login({
+    service: 'https://bsky.social',
+    identifier: 'alice.bsky.social',
+    password: 'wrong-password',
+  })
+} catch (err) {
+  if (err instanceof LexAuthFactorError) {
+    console.error('2FA required')
+  } else if (err instanceof XrpcResponseError) {
+    switch (err.error) {
+      case 'AuthenticationRequired':
+        console.error('Invalid credentials')
+        break
+      case 'AccountTakedown':
+        console.error('Account has been suspended')
+        break
+      default:
+        console.error('Login failed:', err.message)
+    }
+  } else {
+    throw err
   }
 }
 ```
@@ -367,41 +389,39 @@ Common error codes:
 
 ## Using with Client
 
-The `PasswordAgent` implements the `Agent` interface and can be used directly with `Client`:
+The `PasswordSession` implements the `Agent` interface and can be used directly with `Client`:
 
 ```typescript
 import { Client } from '@atproto/lex-client'
-import { PasswordAgent } from '@atproto/lex-password-agent'
+import { PasswordSession } from '@atproto/lex-password-session'
 import * as app from './lexicons/app.js'
 
-const result = await PasswordAgent.login({
+const session = await PasswordSession.login({
   service: 'https://bsky.social',
   identifier: 'alice.bsky.social',
   password: 'app-password',
 })
 
-if (result.success) {
-  const client = new Client(result.value)
+const client = new Client(session)
 
-  // The client automatically uses the agent for authentication
-  const profile = await client.call(app.bsky.actor.getProfile, {
-    actor: client.assertDid,
-  })
+// The client automatically uses the session for authentication
+const profile = await client.call(app.bsky.actor.getProfile, {
+  actor: client.assertDid,
+})
 
-  // Tokens are automatically refreshed when expired
-  const timeline = await client.call(app.bsky.feed.getTimeline, {
-    limit: 50,
-  })
+// Tokens are automatically refreshed when expired
+const timeline = await client.call(app.bsky.feed.getTimeline, {
+  limit: 50,
+})
 
-  // Create records
-  await client.create(app.bsky.feed.post, {
-    text: 'Hello from lex-password-agent!',
-    createdAt: new Date().toISOString(),
-  })
-}
+// Create records
+await client.create(app.bsky.feed.post, {
+  text: 'Hello from lex-password-session!',
+  createdAt: new Date().toISOString(),
+})
 ```
 
-The agent handles:
+The session handles:
 
 - Adding `Authorization` headers to requests
 - Detecting expired tokens (401 responses or `ExpiredToken` errors)

package/dist/error.d.ts

@@ -1,8 +1,55 @@
 import { LexError, XrpcFailure } from '@atproto/lex-client';
+/**
+ * Error thrown when two-factor authentication (2FA) is required.
+ *
+ * This error is thrown by {@link PasswordSession.login} when the server
+ * requires an additional authentication factor (e.g., email code). Catch this
+ * error to prompt the user for their 2FA code and retry the login with the
+ * `authFactorToken` parameter.
+ *
+ * @example Handling 2FA requirement
+ * ```ts
+ * import { PasswordSession, LexAuthFactorError } from '@atproto/lex-password-session'
+ *
+ * try {
+ *   const session = await PasswordSession.login({
+ *     service: 'https://bsky.social',
+ *     identifier: 'alice.bsky.social',
+ *     password: 'xxxx-xxxx-xxxx-xxxx',
+ *   })
+ * } catch (err) {
+ *   if (err instanceof LexAuthFactorError) {
+ *     // Prompt user for 2FA code
+ *     const token = await promptUser('Enter 2FA code from email:')
+ *
+ *     // Retry with the 2FA token
+ *     const session = await PasswordSession.login({
+ *       service: 'https://bsky.social',
+ *       identifier: 'alice.bsky.social',
+ *       password: 'xxxx-xxxx-xxxx-xxxx',
+ *       authFactorToken: token,
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @extends LexError
+ */
 export declare class LexAuthFactorError extends LexError {
     readonly cause: XrpcFailure;
     name: string;
+    /**
+     * Creates a new LexAuthFactorError.
+     *
+     * @param cause - The underlying XRPC failure response from the server
+     */
     constructor(cause: XrpcFailure);
+    /**
+     * Converts this error to an HTTP Response.
+     *
+     * @returns A 500 Internal Server Error response (2FA errors should not be
+     * exposed to end users in server contexts)
+     */
     toResponse(): Response;
 }
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAE3D,qBAAa,kBAAmB,SAAQ,QAAQ;IAGlC,QAAQ,CAAC,KAAK,EAAE,WAAW;IAFvC,IAAI,SAAuB;gBAEN,KAAK,EAAE,WAAW;IAI9B,UAAU,IAAI,QAAQ;CAGhC"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAQlC,QAAQ,CAAC,KAAK,EAAE,WAAW;IAPvC,IAAI,SAAuB;IAE3B;;;;OAIG;gBACkB,KAAK,EAAE,WAAW;IAIvC;;;;;OAKG;IACM,UAAU,IAAI,QAAQ;CAGhC"}