@atproto/lex-password-session 0.0.3 → 0.0.5

package/dist/error.js

@@ -2,12 +2,62 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LexAuthFactorError = void 0;
 const lex_client_1 = require("@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
+ */
 class LexAuthFactorError extends lex_client_1.LexError {
-    response;
+    cause;
     name = 'LexAuthFactorError';
-    constructor(response) {
-        super(response.error, response.message, { cause: response.reason });
-        this.response = response;
+    /**
+     * Creates a new LexAuthFactorError.
+     *
+     * @param cause - The underlying XRPC failure response from the server
+     */
+    constructor(cause) {
+        super(cause.error, cause.message ?? 'Auth factor token required', { cause });
+        this.cause = cause;
+    }
+    /**
+     * 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() {
+        return Response.json({ error: 'InternalServerError' }, { status: 500 });
     }
 }
 exports.LexAuthFactorError = LexAuthFactorError;

package/dist/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,oDAAiE;AAGjE,MAAa,kBAAmB,SAAQ,qBAAQ;IAInC;IAHX,IAAI,GAAG,oBAAoB,CAAA;IAE3B,YACW,QAER;QAED,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;QAJ1D,aAAQ,GAAR,QAAQ,CAEhB;IAGH,CAAC;CACF;AAVD,gDAUC","sourcesContent":["import { LexError, XrpcResponseError } from '@atproto/lex-client'\nimport { com } from './lexicons'\n\nexport class LexAuthFactorError extends LexError {\n  name = 'LexAuthFactorError'\n\n  constructor(\n    readonly response: XrpcResponseError<\n      typeof com.atproto.server.createSession.main\n    >,\n  ) {\n    super(response.error, response.message, { cause: response.reason })\n  }\n}\n"]}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,oDAA2D;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAa,kBAAmB,SAAQ,qBAAQ;IAQzB;IAPrB,IAAI,GAAG,oBAAoB,CAAA;IAE3B;;;;OAIG;IACH,YAAqB,KAAkB;QACrC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,IAAI,4BAA4B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QADzD,UAAK,GAAL,KAAK,CAAa;IAEvC,CAAC;IAED;;;;;OAKG;IACM,UAAU;QACjB,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IACzE,CAAC;CACF;AArBD,gDAqBC","sourcesContent":["import { LexError, XrpcFailure } from '@atproto/lex-client'\n\n/**\n * Error thrown when two-factor authentication (2FA) is required.\n *\n * This error is thrown by {@link PasswordSession.login} when the server\n * requires an additional authentication factor (e.g., email code). Catch this\n * error to prompt the user for their 2FA code and retry the login with the\n * `authFactorToken` parameter.\n *\n * @example Handling 2FA requirement\n * ```ts\n * import { PasswordSession, LexAuthFactorError } from '@atproto/lex-password-session'\n *\n * try {\n *   const session = await PasswordSession.login({\n *     service: 'https://bsky.social',\n *     identifier: 'alice.bsky.social',\n *     password: 'xxxx-xxxx-xxxx-xxxx',\n *   })\n * } catch (err) {\n *   if (err instanceof LexAuthFactorError) {\n *     // Prompt user for 2FA code\n *     const token = await promptUser('Enter 2FA code from email:')\n *\n *     // Retry with the 2FA token\n *     const session = await PasswordSession.login({\n *       service: 'https://bsky.social',\n *       identifier: 'alice.bsky.social',\n *       password: 'xxxx-xxxx-xxxx-xxxx',\n *       authFactorToken: token,\n *     })\n *   }\n * }\n * ```\n *\n * @extends LexError\n */\nexport class LexAuthFactorError extends LexError {\n  name = 'LexAuthFactorError'\n\n  /**\n   * Creates a new LexAuthFactorError.\n   *\n   * @param cause - The underlying XRPC failure response from the server\n   */\n  constructor(readonly cause: XrpcFailure) {\n    super(cause.error, cause.message ?? 'Auth factor token required', { cause })\n  }\n\n  /**\n   * Converts this error to an HTTP Response.\n   *\n   * @returns A 500 Internal Server Error response (2FA errors should not be\n   * exposed to end users in server contexts)\n   */\n  override toResponse(): Response {\n    return Response.json({ error: 'InternalServerError' }, { status: 500 })\n  }\n}\n"]}

package/dist/lexicons/com/atproto/server/createAccount.defs.d.ts

@@ -3,29 +3,29 @@ declare const $nsid = "com.atproto.server.createAccount";
 export { $nsid };
 /** Create an account. Implemented by PDS. */
 declare const main: l.Procedure<"com.atproto.server.createAccount", l.ParamsSchema<{}>, l.Payload<"application/json", l.ObjectSchema<{
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly handle: l.StringSchema<{
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.OptionalSchema<l.StringSchema<{
+    did: l.OptionalSchema<l.StringSchema<{
         readonly format: "did";
     }>>;
-    readonly inviteCode: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly verificationCode: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly verificationPhone: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly password: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly recoveryKey: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly plcOp: l.OptionalSchema<l.UnknownObjectSchema>;
+    inviteCode: l.OptionalSchema<l.StringSchema<{}>>;
+    verificationCode: l.OptionalSchema<l.StringSchema<{}>>;
+    verificationPhone: l.OptionalSchema<l.StringSchema<{}>>;
+    password: l.OptionalSchema<l.StringSchema<{}>>;
+    recoveryKey: l.OptionalSchema<l.StringSchema<{}>>;
+    plcOp: l.OptionalSchema<l.UnknownObjectSchema>;
 }>>, l.Payload<"application/json", l.ObjectSchema<{
-    readonly accessJwt: l.StringSchema<{}>;
-    readonly refreshJwt: l.StringSchema<{}>;
-    readonly handle: l.StringSchema<{
+    accessJwt: l.StringSchema<{}>;
+    refreshJwt: l.StringSchema<{}>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
 }>>, readonly ["InvalidHandle", "InvalidPassword", "InvalidInviteCode", "HandleNotAvailable", "UnsupportedDomain", "UnresolvableDid", "IncompatibleDidDoc"]>;
 export { main };
 export type Params = l.InferMethodParams<typeof main>;
@@ -34,28 +34,28 @@ export type InputBody = l.InferMethodInputBody<typeof main>;
 export type Output = l.InferMethodOutput<typeof main>;
 export type OutputBody = l.InferMethodOutputBody<typeof main>;
 export declare const $lxm: "com.atproto.server.createAccount", $params: l.ParamsSchema<{}>, $input: l.Payload<"application/json", l.ObjectSchema<{
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly handle: l.StringSchema<{
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.OptionalSchema<l.StringSchema<{
+    did: l.OptionalSchema<l.StringSchema<{
         readonly format: "did";
     }>>;
-    readonly inviteCode: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly verificationCode: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly verificationPhone: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly password: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly recoveryKey: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly plcOp: l.OptionalSchema<l.UnknownObjectSchema>;
+    inviteCode: l.OptionalSchema<l.StringSchema<{}>>;
+    verificationCode: l.OptionalSchema<l.StringSchema<{}>>;
+    verificationPhone: l.OptionalSchema<l.StringSchema<{}>>;
+    password: l.OptionalSchema<l.StringSchema<{}>>;
+    recoveryKey: l.OptionalSchema<l.StringSchema<{}>>;
+    plcOp: l.OptionalSchema<l.UnknownObjectSchema>;
 }>>, $output: l.Payload<"application/json", l.ObjectSchema<{
-    readonly accessJwt: l.StringSchema<{}>;
-    readonly refreshJwt: l.StringSchema<{}>;
-    readonly handle: l.StringSchema<{
+    accessJwt: l.StringSchema<{}>;
+    refreshJwt: l.StringSchema<{}>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
 }>>;
 //# sourceMappingURL=createAccount.defs.d.ts.map

package/dist/lexicons/com/atproto/server/createSession.defs.d.ts

@@ -3,25 +3,25 @@ declare const $nsid = "com.atproto.server.createSession";
 export { $nsid };
 /** Create an authentication session. */
 declare const main: l.Procedure<"com.atproto.server.createSession", l.ParamsSchema<{}>, l.Payload<"application/json", l.ObjectSchema<{
-    readonly identifier: l.StringSchema<{}>;
-    readonly password: l.StringSchema<{}>;
-    readonly authFactorToken: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly allowTakendown: l.OptionalSchema<l.BooleanSchema>;
+    identifier: l.StringSchema<{}>;
+    password: l.StringSchema<{}>;
+    authFactorToken: l.OptionalSchema<l.StringSchema<{}>>;
+    allowTakendown: l.OptionalSchema<l.BooleanSchema>;
 }>>, l.Payload<"application/json", l.ObjectSchema<{
-    readonly accessJwt: l.StringSchema<{}>;
-    readonly refreshJwt: l.StringSchema<{}>;
-    readonly handle: l.StringSchema<{
+    accessJwt: l.StringSchema<{}>;
+    refreshJwt: l.StringSchema<{}>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
-    readonly emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
-    readonly active: l.OptionalSchema<l.BooleanSchema>;
-    readonly status: l.OptionalSchema<l.StringSchema<{}>>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
+    emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
+    active: l.OptionalSchema<l.BooleanSchema>;
+    status: l.OptionalSchema<l.StringSchema<{}>>;
 }>>, readonly ["AccountTakedown", "AuthFactorTokenRequired"]>;
 export { main };
 export type Params = l.InferMethodParams<typeof main>;
@@ -30,24 +30,24 @@ export type InputBody = l.InferMethodInputBody<typeof main>;
 export type Output = l.InferMethodOutput<typeof main>;
 export type OutputBody = l.InferMethodOutputBody<typeof main>;
 export declare const $lxm: "com.atproto.server.createSession", $params: l.ParamsSchema<{}>, $input: l.Payload<"application/json", l.ObjectSchema<{
-    readonly identifier: l.StringSchema<{}>;
-    readonly password: l.StringSchema<{}>;
-    readonly authFactorToken: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly allowTakendown: l.OptionalSchema<l.BooleanSchema>;
+    identifier: l.StringSchema<{}>;
+    password: l.StringSchema<{}>;
+    authFactorToken: l.OptionalSchema<l.StringSchema<{}>>;
+    allowTakendown: l.OptionalSchema<l.BooleanSchema>;
 }>>, $output: l.Payload<"application/json", l.ObjectSchema<{
-    readonly accessJwt: l.StringSchema<{}>;
-    readonly refreshJwt: l.StringSchema<{}>;
-    readonly handle: l.StringSchema<{
+    accessJwt: l.StringSchema<{}>;
+    refreshJwt: l.StringSchema<{}>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
-    readonly emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
-    readonly active: l.OptionalSchema<l.BooleanSchema>;
-    readonly status: l.OptionalSchema<l.StringSchema<{}>>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
+    emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
+    active: l.OptionalSchema<l.BooleanSchema>;
+    status: l.OptionalSchema<l.StringSchema<{}>>;
 }>>;
 //# sourceMappingURL=createSession.defs.d.ts.map

package/dist/lexicons/com/atproto/server/getSession.defs.d.ts

@@ -3,35 +3,35 @@ declare const $nsid = "com.atproto.server.getSession";
 export { $nsid };
 /** Get information about the current auth session. Requires auth. */
 declare const main: l.Query<"com.atproto.server.getSession", l.ParamsSchema<{}>, l.Payload<"application/json", l.ObjectSchema<{
-    readonly handle: l.StringSchema<{
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
-    readonly emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
-    readonly active: l.OptionalSchema<l.BooleanSchema>;
-    readonly status: l.OptionalSchema<l.StringSchema<{}>>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
+    emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
+    active: l.OptionalSchema<l.BooleanSchema>;
+    status: l.OptionalSchema<l.StringSchema<{}>>;
 }>>, undefined>;
 export { main };
 export type Params = l.InferMethodParams<typeof main>;
 export type Output = l.InferMethodOutput<typeof main>;
 export type OutputBody = l.InferMethodOutputBody<typeof main>;
 export declare const $lxm: "com.atproto.server.getSession", $params: l.ParamsSchema<{}>, $output: l.Payload<"application/json", l.ObjectSchema<{
-    readonly handle: l.StringSchema<{
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
-    readonly emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
-    readonly active: l.OptionalSchema<l.BooleanSchema>;
-    readonly status: l.OptionalSchema<l.StringSchema<{}>>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
+    emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
+    active: l.OptionalSchema<l.BooleanSchema>;
+    status: l.OptionalSchema<l.StringSchema<{}>>;
 }>>;
 //# sourceMappingURL=getSession.defs.d.ts.map

package/dist/lexicons/com/atproto/server/refreshSession.defs.d.ts

@@ -3,20 +3,20 @@ declare const $nsid = "com.atproto.server.refreshSession";
 export { $nsid };
 /** Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt'). */
 declare const main: l.Procedure<"com.atproto.server.refreshSession", l.ParamsSchema<{}>, l.Payload<undefined, undefined>, l.Payload<"application/json", l.ObjectSchema<{
-    readonly accessJwt: l.StringSchema<{}>;
-    readonly refreshJwt: l.StringSchema<{}>;
-    readonly handle: l.StringSchema<{
+    accessJwt: l.StringSchema<{}>;
+    refreshJwt: l.StringSchema<{}>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
-    readonly emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
-    readonly active: l.OptionalSchema<l.BooleanSchema>;
-    readonly status: l.OptionalSchema<l.StringSchema<{}>>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
+    emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
+    active: l.OptionalSchema<l.BooleanSchema>;
+    status: l.OptionalSchema<l.StringSchema<{}>>;
 }>>, readonly ["AccountTakedown", "InvalidToken", "ExpiredToken"]>;
 export { main };
 export type Params = l.InferMethodParams<typeof main>;
@@ -25,19 +25,19 @@ export type InputBody = l.InferMethodInputBody<typeof main>;
 export type Output = l.InferMethodOutput<typeof main>;
 export type OutputBody = l.InferMethodOutputBody<typeof main>;
 export declare const $lxm: "com.atproto.server.refreshSession", $params: l.ParamsSchema<{}>, $input: l.Payload<undefined, undefined>, $output: l.Payload<"application/json", l.ObjectSchema<{
-    readonly accessJwt: l.StringSchema<{}>;
-    readonly refreshJwt: l.StringSchema<{}>;
-    readonly handle: l.StringSchema<{
+    accessJwt: l.StringSchema<{}>;
+    refreshJwt: l.StringSchema<{}>;
+    handle: l.StringSchema<{
         readonly format: "handle";
     }>;
-    readonly did: l.StringSchema<{
+    did: l.StringSchema<{
         readonly format: "did";
     }>;
-    readonly didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
-    readonly email: l.OptionalSchema<l.StringSchema<{}>>;
-    readonly emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
-    readonly emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
-    readonly active: l.OptionalSchema<l.BooleanSchema>;
-    readonly status: l.OptionalSchema<l.StringSchema<{}>>;
+    didDoc: l.OptionalSchema<l.UnknownObjectSchema>;
+    email: l.OptionalSchema<l.StringSchema<{}>>;
+    emailConfirmed: l.OptionalSchema<l.BooleanSchema>;
+    emailAuthFactor: l.OptionalSchema<l.BooleanSchema>;
+    active: l.OptionalSchema<l.BooleanSchema>;
+    status: l.OptionalSchema<l.StringSchema<{}>>;
 }>>;
 //# sourceMappingURL=refreshSession.defs.d.ts.map

package/dist/password-session.d.ts

@@ -1,7 +1,28 @@
 import { Agent, XrpcFailure } from '@atproto/lex-client';
 import { com } from './lexicons/index.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;
 };
@@ -20,7 +41,7 @@ export type PasswordSessionOptions = {
      *
      * @note this function **must** not throw
      */
-    onUpdated: (this: PasswordSession, data: SessionData) => void | Promise<void>;
+    onUpdated?: (this: PasswordSession, data: SessionData) => void | Promise<void>;
     /**
      * Called whenever the session update fails due to an expected error, such as
      * a network issue or server unavailability. This function can be used to log
@@ -38,7 +59,7 @@ export type PasswordSessionOptions = {
      *
      * @note this function **must** not throw
      */
-    onDeleted: (this: PasswordSession, data: SessionData) => void | Promise<void>;
+    onDeleted?: (this: PasswordSession, data: SessionData) => void | Promise<void>;
     /**
      * Called whenever a session deletion fails due to an unexpected error, such
      * as a network issue or server unavailability. This function can be used to
@@ -55,46 +76,204 @@ export type PasswordSessionOptions = {
      */
     onDeleteFailure?: (this: PasswordSession, data: SessionData, err: DeleteFailure) => 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 declare class PasswordSession implements Agent {
     #private;
     protected readonly options: PasswordSessionOptions;
-    constructor(sessionData: SessionData, options: PasswordSessionOptions);
+    constructor(sessionData: SessionData, options?: PasswordSessionOptions);
+    /**
+     * The DID (Decentralized Identifier) of the authenticated account.
+     *
+     * @throws {Error} If the session has been destroyed (logged out).
+     */
     get did(): `did:${string}:${string}`;
+    /**
+     * The handle (username) of the authenticated account.
+     *
+     * @throws {Error} If the session has been destroyed (logged out).
+     */
     get handle(): `${string}.${string}`;
+    /**
+     * The current session data containing authentication credentials.
+     *
+     * @throws {Error} If the session has been destroyed (logged out).
+     */
     get session(): SessionData;
+    /**
+     * 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;
+    /**
+     * 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
+     */
     fetchHandler(path: string, init: RequestInit): Promise<Response>;
+    /**
+     * 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)
+     */
     refresh(): Promise<SessionData>;
+    /**
+     * 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
+     */
     logout(): Promise<void>;
     /**
-     * @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 account and returns an authenticated session.
      *
-     * @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.
+     * 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 Handling 2FA errors
+     * @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 createAccount(body: com.atproto.server.createAccount.InputBody, { service, headers, ...options }: PasswordSessionOptions & {
+        headers?: HeadersInit;
+        service: string | URL;
+    }): Promise<PasswordSession>;
+    /**
+     * 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.
+     *
+     * **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 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.create({
-     *     service: 'https://example.com',
-     *     identifier: 'alice',
-     *     password: 'correct horse battery staple',
+     *   const session = await PasswordSession.login({
+     *     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,
+     *     })
      *   }
      * }
      * ```
      */
-    static create({ service, identifier, password, allowTakendown, authFactorToken, ...options }: PasswordSessionOptions & {
+    static login({ service, identifier, password, allowTakendown, authFactorToken, ...options }: PasswordSessionOptions & {
         service: string | URL;
         identifier: string;
         password: string;
@@ -122,6 +301,6 @@ export declare class PasswordSession implements Agent {
      * @throws In case of unexpected error (network issue, server down, etc)
      * meaning that the session may still be valid.
      */
-    static delete(data: SessionData, options?: Partial<PasswordSessionOptions>): Promise<void>;
+    static delete(data: SessionData, options?: PasswordSessionOptions): Promise<void>;
 }
 //# sourceMappingURL=password-session.d.ts.map

package/dist/password-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EAEL,WAAW,EAGZ,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA;AAGzC,MAAM,MAAM,cAAc,GAAG,WAAW,CACtC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAC9C,CAAA;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,CACrC,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAC7C,CAAA;AAED,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,GAAG;IACtE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAE/B;;;;;;;;;OASG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7E;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,CAChB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,cAAc,KAChB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEzB;;;;;;;OAOG;IACH,SAAS,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE7E;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,CAChB,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,WAAW,EACjB,GAAG,EAAE,aAAa,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B,CAAA;AAED,qBAAa,eAAgB,YAAW,KAAK;;IAYzC,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,sBAAsB;gBADlD,WAAW,EAAE,WAAW,EACL,OAAO,EAAE,sBAAsB;IAWpD,IAAI,GAAG,8BAEN;IAED,IAAI,MAAM,0BAET;IAED,IAAI,OAAO,gBAGV;IAED,IAAI,SAAS,IAAI,OAAO,CAEvB;IAEK,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAkEhE,OAAO,IAAI,OAAO,CAAC,WAAW,CAAC;IAwD/B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAwC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;WACU,MAAM,CAAC,EAClB,OAAO,EACP,UAAU,EACV,QAAQ,EACR,cAAc,EACd,eAAe,EACf,GAAG,OAAO,EACX,EAAE,sBAAsB,GAAG;QAC1B,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;QACrB,UAAU,EAAE,MAAM,CAAA;QAClB,QAAQ,EAAE,MAAM,CAAA;QAChB,cAAc,CAAC,EAAE,OAAO,CAAA;QACxB,eAAe,CAAC,EAAE,MAAM,CAAA;KACzB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B5B;;;;;;;;;;;;OAYG;WACU,MAAM,CACjB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,eAAe,CAAC;IAM3B;;;;;;OAMG;WACU,MAAM,CACjB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,GACxC,OAAO,CAAC,IAAI,CAAC;CAQjB"}
+{"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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"}