@atproto/lex-password-session 0.0.4 → 0.0.5

package/src/password-session.ts

@@ -9,14 +9,35 @@ import { LexAuthFactorError } from './error.js'
 import { com } from './lexicons/index.js'
 import { extractPdsUrl, extractXrpcErrorCode } from './util.js'
 
+/**
+ * Represents a failure response when refreshing a session.
+ *
+ * This type captures the possible error responses from
+ * `com.atproto.server.refreshSession`, including both expected errors
+ * (e.g., invalid/expired refresh token) and unexpected errors (e.g., network issues).
+ */
 export type RefreshFailure = XrpcFailure<
   typeof com.atproto.server.refreshSession.main
 >
 
+/**
+ * Represents a failure response when deleting a session.
+ *
+ * This type captures the possible error responses from
+ * `com.atproto.server.deleteSession`, including both expected errors
+ * and unexpected errors (e.g., network issues, server unavailability).
+ */
 export type DeleteFailure = XrpcFailure<
   typeof com.atproto.server.deleteSession.main
 >
 
+/**
+ * Persisted session data containing authentication credentials and service information.
+ *
+ * This type extends the response from `com.atproto.server.createSession` with the
+ * service URL used for authentication. Store this data securely to resume sessions
+ * later without re-authenticating.
+ */
 export type SessionData = com.atproto.server.createSession.OutputBody & {
   service: string
 }
@@ -84,6 +105,44 @@ export type PasswordSessionOptions = {
   ) => void | Promise<void>
 }
 
+/**
+ * Password-based authentication session for AT Protocol services.
+ *
+ * This class provides session management for CLI tools, scripts, and bots that
+ * need to authenticate with AT Protocol services using password credentials.
+ * It implements the {@link Agent} interface, allowing it to be used directly
+ * with AT Protocol clients.
+ *
+ * **Security Warning:** It is strongly recommended to use app passwords instead
+ * of main account credentials. App passwords provide limited access and can be
+ * revoked independently without compromising your main account. For browser-based
+ * applications, use OAuth-based authentication instead.
+ *
+ * @example Basic usage with app password
+ * ```ts
+ * const session = await PasswordSession.login({
+ *   service: 'https://bsky.social',
+ *   identifier: 'alice.bsky.social',
+ *   password: 'xxxx-xxxx-xxxx-xxxx', // App password
+ *   onUpdated: (data) => saveToStorage(data),
+ *   onDeleted: (data) => clearStorage(data.did),
+ * })
+ *
+ * const client = new Client(session)
+ * // Use client to make authenticated requests
+ * ```
+ *
+ * @example Resuming a persisted session
+ * ```ts
+ * const savedData = JSON.parse(fs.readFileSync('session.json', 'utf8'))
+ * const session = await PasswordSession.resume(savedData, {
+ *   onUpdated: (data) => saveToStorage(data),
+ *   onDeleted: (data) => clearStorage(data.did),
+ * })
+ * ```
+ *
+ * @implements {Agent}
+ */
 export class PasswordSession implements Agent {
   /**
    * Internal {@link Agent} used for session management towards the
@@ -107,23 +166,59 @@ export class PasswordSession implements Agent {
     this.#sessionPromise = Promise.resolve(this.#sessionData)
   }
 
+  /**
+   * The DID (Decentralized Identifier) of the authenticated account.
+   *
+   * @throws {Error} If the session has been destroyed (logged out).
+   */
   get did() {
     return this.session.did
   }
 
+  /**
+   * The handle (username) of the authenticated account.
+   *
+   * @throws {Error} If the session has been destroyed (logged out).
+   */
   get handle() {
     return this.session.handle
   }
 
+  /**
+   * The current session data containing authentication credentials.
+   *
+   * @throws {Error} If the session has been destroyed (logged out).
+   */
   get session() {
     if (this.#sessionData) return this.#sessionData
     throw new Error('Logged out')
   }
 
+  /**
+   * Whether this session has been destroyed (logged out).
+   *
+   * Once destroyed, this session instance can no longer be used for
+   * authenticated requests. Create a new session via {@link PasswordSession.login}
+   * or {@link PasswordSession.resume}.
+   */
   get destroyed(): boolean {
     return this.#sessionData === null
   }
 
+  /**
+   * Handles authenticated fetch requests to the user's PDS.
+   *
+   * This method implements the {@link Agent} interface and is called by
+   * AT Protocol clients to make authenticated requests. It automatically:
+   * - Adds the access token to request headers
+   * - Detects expired tokens and triggers refresh
+   * - Retries requests after successful token refresh
+   *
+   * @param path - The request path (will be resolved against the PDS URL)
+   * @param init - Standard fetch RequestInit options (headers, body, etc.)
+   * @returns The fetch Response from the PDS
+   * @throws {TypeError} If an 'authorization' header is already set in init
+   */
   async fetchHandler(path: string, init: RequestInit): Promise<Response> {
     const headers = new Headers(init.headers)
     if (headers.has('authorization')) {
@@ -190,6 +285,21 @@ export class PasswordSession implements Agent {
     return fetch(fetchUrl(newSessionData, path), { ...init, headers })
   }
 
+  /**
+   * Refreshes the session by obtaining new access and refresh tokens.
+   *
+   * This method is automatically called by {@link fetchHandler} when the access
+   * token expires. You can also call it manually to proactively refresh tokens.
+   *
+   * On success, the {@link PasswordSessionOptions.onUpdated} callback is invoked
+   * with the new session data. On expected failures (invalid session), the
+   * {@link PasswordSessionOptions.onDeleted} callback is invoked. On unexpected
+   * failures (network issues), the {@link PasswordSessionOptions.onUpdateFailure}
+   * callback is invoked and the existing session data is preserved.
+   *
+   * @returns The refreshed session data
+   * @throws {RefreshFailure} If the session is no longer valid (triggers onDeleted)
+   */
   async refresh(): Promise<SessionData> {
     this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
       const response = await xrpcSafe(
@@ -250,6 +360,21 @@ export class PasswordSession implements Agent {
     return this.#sessionPromise
   }
 
+  /**
+   * Logs out by deleting the session on the server.
+   *
+   * This method invalidates both the access and refresh tokens on the server,
+   * preventing any further use of this session. After successful logout, the
+   * session is marked as destroyed and the {@link PasswordSessionOptions.onDeleted}
+   * callback is invoked.
+   *
+   * If the logout request fails due to network issues or server unavailability,
+   * the {@link PasswordSessionOptions.onDeleteFailure} callback is invoked and
+   * the session remains active locally. In this case, you should retry the
+   * logout later to ensure the session is properly invalidated on the server.
+   *
+   * @throws {DeleteFailure} If the logout request fails due to unexpected errors
+   */
   async logout(): Promise<void> {
     let reason: DeleteFailure | null = null
 
@@ -290,6 +415,32 @@ export class PasswordSession implements Agent {
     )
   }
 
+  /**
+   * Creates a new account and returns an authenticated session.
+   *
+   * This static method registers a new account on the specified service and
+   * automatically creates an authenticated session for it.
+   *
+   * @param body - Account creation parameters (handle, email, password, etc.)
+   * @param options - Session options including the service URL
+   * @returns A new PasswordSession for the created account
+   * @throws If account creation fails (e.g., handle taken, invalid invite code)
+   *
+   * @example
+   * ```ts
+   * const session = await PasswordSession.createAccount(
+   *   {
+   *     handle: 'alice.bsky.social',
+   *     email: 'alice@example.com',
+   *     password: 'secure-password',
+   *   },
+   *   {
+   *     service: 'https://bsky.social',
+   *     onUpdated: (data) => saveToStorage(data),
+   *   }
+   * )
+   * ```
+   */
   static async createAccount(
     body: com.atproto.server.createAccount.InputBody,
     {
@@ -318,29 +469,53 @@ export class PasswordSession implements Agent {
   }
 
   /**
-   * @note It is **not** recommended to use {@link PasswordSession} with main
-   * account credentials. Instead, it is strongly advised to use OAuth based
-   * authentication for main username/password credentials and use
-   * {@link PasswordSession} with an app-password, for bots, scripts, or similar
-   * use-cases.
+   * Creates a new authenticated session using password credentials.
+   *
+   * This static method authenticates with the specified service and returns
+   * a new PasswordSession instance that can be used for authenticated requests.
    *
-   * @throws If unable to create a session. In particular, if the server
-   * requires a 2FA token, a {@link XrpcResponseError} with the
-   * `AuthFactorTokenRequired` error code will be thrown.
+   * **Security Warning:** It is strongly recommended to use app passwords instead
+   * of main account credentials. App passwords can be created in your account
+   * settings and provide limited access that can be revoked independently. For
+   * browser-based applications, use OAuth-based authentication instead.
    *
+   * @param options - Login options including service URL, identifier, and password
+   * @param options.service - The AT Protocol service URL (e.g., 'https://bsky.social')
+   * @param options.identifier - The user's handle or DID
+   * @param options.password - The user's password or app password
+   * @param options.allowTakendown - If true, allow login to takendown accounts
+   * @param options.authFactorToken - 2FA token if required by the server
+   * @returns A new authenticated PasswordSession
+   * @throws {LexAuthFactorError} If the server requires a 2FA token
+   * @throws If authentication fails (invalid credentials, etc.)
    *
-   * @example Handling 2FA errors
+   * @example Basic login with app password
+   * ```ts
+   * const session = await PasswordSession.login({
+   *   service: 'https://bsky.social',
+   *   identifier: 'alice.bsky.social',
+   *   password: 'xxxx-xxxx-xxxx-xxxx', // App password
+   *   onUpdated: (data) => saveToStorage(data),
+   * })
+   * ```
    *
+   * @example Handling 2FA requirement
    * ```ts
    * try {
    *   const session = await PasswordSession.login({
-   *     service: 'https://example.com',
-   *     identifier: 'alice',
-   *     password: 'correct horse battery staple',
+   *     service: 'https://bsky.social',
+   *     identifier: 'alice.bsky.social',
+   *     password: 'xxxx-xxxx-xxxx-xxxx',
    *   })
    * } catch (err) {
-   *   if (err instanceof XrpcResponseError && err.error === 'AuthFactorTokenRequired') {
-   *     // Prompt user for 2FA token and re-attempt session creation
+   *   if (err instanceof LexAuthFactorError) {
+   *     const token = await promptUser('Enter 2FA code:')
+   *     const session = await PasswordSession.login({
+   *       service: 'https://bsky.social',
+   *       identifier: 'alice.bsky.social',
+   *       password: 'xxxx-xxxx-xxxx-xxxx',
+   *       authFactorToken: token,
+   *     })
    *   }
    * }
    * ```