npm - @atproto/lex-password-session - Versions diffs - 0.0.4 → 0.0.6 - Mend

@atproto/lex-password-session 0.0.4 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (38) hide show

package/dist/lexicons/com/atproto/server/refreshSession.defs.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"refreshSession.defs.js","sourceRoot":"","sources":["../../../../../src/lexicons/com/atproto/server/refreshSession.defs.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,oDAAuC;AAEvC,MAAM,KAAK,GAAG,mCAAmC,CAAA;AAExC,sBAAK;AAEd,qGAAqG;AACrG,MAAM,IAAI;AACR,aAAa;AACb,cAAC,CAAC,SAAS,CACT,KAAK;AACL,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE;AACxB,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE;AACzB,aAAa,CAAC,cAAC,CAAC,WAAW,CAAC;IAC1B,SAAS,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE;IACnC,UAAU,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACpD,GAAG,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC9C,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,~~aAAa~~,EAAE,CAAC;~~IACjE~~,KAAK,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE,CAAC;IACzD,cAAc,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE,CAAC;IACnE,eAAe,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE,CAAC;IACpE,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE,CAAC;IAC3D,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,~~CAAC,~~aAAa,CAAC,cAAC,CAAC,MAAM,~~EAAE~~,~~CAAC~~;~~CAC3D~~,CAAC,EACF,CAAC,iBAAiB,EAAE,cAAc,EAAE,cAAc,CAAC,CACpD,CAAA;AACM,oBAAI;~~AAQA~~,QAAA,IAAI,GAAiB,IAAI,CAAC,IAAI,EACzC,QAAA,OAAO,GAAiB,IAAI,CAAC,UAAU,EACvC,QAAA,MAAM,GAAiB,IAAI,CAAC,KAAK,EACjC,QAAA,OAAO,GAAiB,IAAI,CAAC,MAAM,CAAA","sourcesContent":["/\n THIS FILE WAS GENERATED BY \"@atproto/lex\". DO NOT EDIT.\n /\n\nimport { l } from '@atproto/lex-schema'\n\nconst $nsid = 'com.atproto.server.refreshSession'\n\nexport { $nsid }\n\n/* Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt'). /\nconst main =\n /#__PURE__/\n l.procedure(\n $nsid,\n /#__PURE__/ l.params(),\n /#__PURE__/ l.payload(),\n /#__PURE__/ l.jsonPayload({\n accessJwt: /#__PURE__/ l.string(),\n refreshJwt: /#__PURE__/ l.string(),\n handle: /#__PURE__/ l.string({ format: 'handle' }),\n did: /#__PURE__/ l.string({ format: 'did' }),\n didDoc: /#__PURE__/ l.optional(/#__PURE__/ l.~~unknownObject~~()),\n email: /#__PURE__/ l.optional(/#__PURE__/ l.string()),\n emailConfirmed: /#__PURE__/ l.optional(/#__PURE__/ l.boolean()),\n emailAuthFactor: /#__PURE__/ l.optional(/#__PURE__/ l.boolean()),\n active: /#__PURE__/ l.optional(/#__PURE__/ l.boolean()),\n status: /#__PURE__/ l.optional(/#__PURE__/ l.string()),\n }),\n ['AccountTakedown', 'InvalidToken', 'ExpiredToken'],\n )\nexport { main }\n\nexport type Params = l.InferMethodParams<typeof main>\nexport type Input = l.InferMethodInput<typeof main>\nexport type InputBody = l.InferMethodInputBody<typeof main>\nexport type Output = l.InferMethodOutput<typeof main>\nexport type OutputBody = l.InferMethodOutputBody<typeof main>\n\nexport const $lxm = /#__PURE__/ main.nsid,\n $params = /#__PURE__/ main.parameters,\n $input = /#__PURE__/ main.input,\n $output = /#__PURE__*/ main.output\n"]}
1	+ {"version":3,"file":"refreshSession.defs.js","sourceRoot":"","sources":["../../../../../src/lexicons/com/atproto/server/refreshSession.defs.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,oDAAuC;AAEvC,MAAM,KAAK,GAAG,mCAAmC,CAAA;AAExC,sBAAK;AAEd,qGAAqG;AACrG,MAAM,IAAI;AACR,aAAa;AACb,cAAC,CAAC,SAAS,CACT,KAAK;AACL,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE;AACxB,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE;AACzB,aAAa,CAAC,cAAC,CAAC,WAAW,CAAC;IAC1B,SAAS,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE;IACnC,UAAU,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE;IACpC,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACpD,GAAG,EAAE,aAAa,CAAC,cAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC9C,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE,CAAC;IAC1D,KAAK,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,MAAM,EAAE,CAAC;IACzD,cAAc,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE,CAAC;IACnE,eAAe,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE,CAAC;IACpE,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,cAAC,CAAC,OAAO,EAAE,CAAC;IAC3D,MAAM,EAAE,aAAa,CAAC,cAAC,CAAC,QAAQ;IAC9B,aAAa,CAAC,cAAC,CAAC,MAAM,EAElB,CACL;CACF,CAAC,EACF,CAAC,iBAAiB,EAAE,cAAc,EAAE,cAAc,CAAC,CACpD,CAAA;AACM,oBAAI;AAcA,QAAA,IAAI,GAAiB,IAAI,CAAC,IAAI,EACzC,QAAA,OAAO,GAAiB,IAAI,CAAC,UAAU,EACvC,QAAA,MAAM,GAAiB,IAAI,CAAC,KAAK,EACjC,QAAA,OAAO,GAAiB,IAAI,CAAC,MAAM,CAAA","sourcesContent":["/\n THIS FILE WAS GENERATED BY \"@atproto/lex\". DO NOT EDIT.\n /\n\nimport { l } from '@atproto/lex-schema'\n\nconst $nsid = 'com.atproto.server.refreshSession'\n\nexport { $nsid }\n\n/* Refresh an authentication session. Requires auth using the 'refreshJwt' (not the 'accessJwt'). /\nconst main =\n /#__PURE__/\n l.procedure(\n $nsid,\n /#__PURE__/ l.params(),\n /#__PURE__/ l.payload(),\n /#__PURE__/ l.jsonPayload({\n accessJwt: /#__PURE__/ l.string(),\n refreshJwt: /#__PURE__/ l.string(),\n handle: /#__PURE__/ l.string({ format: 'handle' }),\n did: /#__PURE__/ l.string({ format: 'did' }),\n didDoc: /#__PURE__/ l.optional(/#__PURE__/ l.lexMap()),\n email: /#__PURE__/ l.optional(/#__PURE__/ l.string()),\n emailConfirmed: /#__PURE__/ l.optional(/#__PURE__/ l.boolean()),\n emailAuthFactor: /#__PURE__/ l.optional(/#__PURE__/ l.boolean()),\n active: /#__PURE__/ l.optional(/#__PURE__/ l.boolean()),\n status: /#__PURE__/ l.optional(\n /#__PURE__/ l.string<{\n knownValues: ['takendown', 'suspended', 'deactivated']\n }>(),\n ),\n }),\n ['AccountTakedown', 'InvalidToken', 'ExpiredToken'],\n )\nexport { main }\n\nexport type $Params = l.InferMethodParams<typeof main>\nexport type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>\nexport type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<\n typeof main,\n B\n>\nexport type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>\nexport type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<\n typeof main,\n B\n>\n\nexport const $lxm = /#__PURE__/ main.nsid,\n $params = /#__PURE__/ main.parameters,\n $input = /#__PURE__/ main.input,\n $output = /#__PURE__*/ main.output\n"]}

package/dist/password-session.d.ts CHANGED Viewed

@@ -1,8 +1,29 @@
 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>;
-export type SessionData = com.atproto.server.createSession.OutputBody & {
+/**
+ * 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;
 };
 export type PasswordSessionOptions = {
@@ -55,45 +76,199 @@ 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);
+    /**
+     * 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>;
-    static createAccount(body: com.atproto.server.createAccount.InputBody, { service, headers, ...options }: PasswordSessionOptions & {
+    /**
+     * 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 createAccount(body: com.atproto.server.createAccount.$InputBody, { service, headers, ...options }: PasswordSessionOptions & {
         headers?: HeadersInit;
         service: string | URL;
     }): Promise<PasswordSession>;
     /**
-     * @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,
+     *     })
      *   }
      * }
      * ```

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

	@@ -1 +1 @@
1	- {"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,WAAW,EAIZ,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,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9E;;;;;;;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,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9E;;;;;;;;;;;;;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,GAAE,sBAA2B;IAWzD,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;~~IA4D/B~~,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;~~WAwChB~~,aAAa,CACxB,IAAI,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,~~SAAS~~,~~EAChD~~,EACE,OAAO,EACP,OAAO,EACP,GAAG,OAAO,EACX,EAAE,sBAAsB,GAAG;QAC1B,OAAO,CAAC,EAAE,WAAW,CAAA;QACrB,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;KACtB,GACA,OAAO,CAAC,eAAe,CAAC;IAiB3B~~;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG~~;WACU,KAAK,CAAC,EACjB,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,sBAAsB,GAC/B,OAAO,CAAC,IAAI,CAAC;CAIjB"}
1	+ {"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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"}

package/dist/password-session.js CHANGED Viewed

@@ -5,6 +5,44 @@ const lex_client_1 = require("@atproto/lex-client");
 const error_js_1 = require("./error.js");
 const index_js_1 = require("./lexicons/index.js");
 const util_js_1 = require("./util.js");
+/**
+ * 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}
+ */
 class PasswordSession {
     options;
     /**
@@ -23,20 +61,56 @@ class PasswordSession {
         this.#sessionData = sessionData;
         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() {
         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, init) {
         const headers = new Headers(init.headers);
         if (headers.has('authorization')) {
@@ -88,6 +162,21 @@ class PasswordSession {
         headers.set('authorization', `Bearer ${newSessionData.accessJwt}`);
         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() {
         this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
             const response = await (0, lex_client_1.xrpcSafe)(this.#serviceAgent, index_js_1.com.atproto.server.refreshSession.main, { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } });
@@ -129,6 +218,21 @@ class PasswordSession {
         });
         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() {
         let reason = null;
         this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
@@ -156,6 +260,32 @@ class PasswordSession {
             // Successful logout
         });
     }
+    /**
+     * 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, { service, headers, ...options }) {
         const response = await (0, lex_client_1.xrpc)((0, lex_client_1.buildAgent)({ service, headers, fetch: options.fetch }), index_js_1.com.atproto.server.createAccount.main, { body });
         const data = {
@@ -167,29 +297,53 @@ class PasswordSession {
         return 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,
+     *     })
      *   }
      * }
      * ```

package/dist/password-session.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"password-session.js","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n Agent,\n XrpcFailure,\n buildAgent,\n xrpc,\n xrpcSafe,\n} from '@atproto/lex-client'\nimport { LexAuthFactorError } from './error.js'\nimport { com } from './lexicons/index.js'\nimport { extractPdsUrl, extractXrpcErrorCode } from './util.js'\n\nexport type RefreshFailure = XrpcFailure<\n typeof com.atproto.server.refreshSession.main\n>\n\nexport type DeleteFailure = XrpcFailure<\n typeof com.atproto.server.deleteSession.main\n>\n\nexport type SessionData = com.atproto.server.createSession.OutputBody & {\n service: string\n}\n\nexport type PasswordSessionOptions = {\n /*\n Custom fetch implementation to use for network requests\n /\n fetch?: typeof globalThis.fetch\n\n /\n Called whenever the session is successfully created/refreshed, and new\n * credentials have been obtained. Use this hook to persist the updated\n * session information.\n \n If this callback returns a promise, this function will never be called\n * again (on the same process) until the promise resolves.\n \n @note this function must not throw\n /\n onUpdated?: (this: PasswordSession, data: SessionData) => void \| Promise<void>\n\n /\n Called whenever the session update fails due to an expected error, such as\n * a network issue or server unavailability. This function can be used to log\n * the error or notify the user, but should not assume that the session is\n * invalid.\n \n @note this function must not throw\n /\n onUpdateFailure?: (\n this: PasswordSession,\n data: SessionData,\n err: RefreshFailure,\n ) => void \| Promise<void>\n\n /\n Called whenever the session is deleted, either due to an explicit logout or\n * because the refresh operation indicated that the session is no longer\n * valid. Use this hook to clean up any persisted session information and\n * update the application state accordingly.\n \n @note this function must not throw\n /\n onDeleted?: (this: PasswordSession, data: SessionData) => void \| Promise<void>\n\n /\n Called whenever a session deletion fails due to an unexpected error, such\n * as a network issue or server unavailability. This function can be used to\n * log the error or notify the user. When this function is called, the session\n * might still be valid on the server. It is up to the implementation to\n * decide whether to retry the deletion or keep the session active. Ignoring\n * these errors is not recommended as it can lead to orphaned sessions on the\n * server, or security issues if the user believes they have logged out when a\n * bad actor is still using the session. The implementation should consider\n * keeping track of failed deletions and retrying them later, until they\n * succeed.\n \n @note this function must not throw\n /\n onDeleteFailure?: (\n this: PasswordSession,\n data: SessionData,\n err: DeleteFailure,\n ) => void \| Promise<void>\n}\n\nexport class PasswordSession implements Agent {\n /\n Internal {@link Agent} used for session management towards the\n * authentication service only.\n /\n #serviceAgent: Agent\n\n #sessionData: null \| SessionData\n #sessionPromise: Promise<SessionData>\n\n constructor(\n sessionData: SessionData,\n protected readonly options: PasswordSessionOptions = {},\n ) {\n this.#serviceAgent = buildAgent({\n service: sessionData.service,\n fetch: options.fetch,\n })\n\n this.#sessionData = sessionData\n this.#sessionPromise = Promise.resolve(this.#sessionData)\n }\n\n get did() {\n return this.session.did\n }\n\n get handle() {\n return this.session.handle\n }\n\n get session() {\n if (this.#sessionData) return this.#sessionData\n throw new Error('Logged out')\n }\n\n get destroyed(): boolean {\n return this.#sessionData === null\n }\n\n async fetchHandler(path: string, init: RequestInit): Promise<Response> {\n const headers = new Headers(init.headers)\n if (headers.has('authorization')) {\n throw new TypeError(\"Unexpected 'authorization' header set\")\n }\n\n const sessionPromise = this.#sessionPromise\n const sessionData = await sessionPromise\n\n const fetch = this.options.fetch ?? globalThis.fetch\n\n headers.set('authorization', `Bearer ${sessionData.accessJwt}`)\n const initialRes = await fetch(fetchUrl(sessionData, path), {\n ...init,\n headers,\n })\n\n const refreshNeeded =\n initialRes.status === 401 \|\|\n (initialRes.status === 400 &&\n (await extractXrpcErrorCode(initialRes)) === 'ExpiredToken')\n\n if (!refreshNeeded) {\n return initialRes\n }\n\n // Refresh session (unless it was already refreshed in the meantime)\n const newSessionPromise =\n this.#sessionPromise === sessionPromise\n ? this.refresh()\n : this.#sessionPromise\n\n // Error should have been propagated through hooks\n const newSessionData = await newSessionPromise.catch((_err) => null)\n if (!newSessionData) {\n return initialRes\n }\n\n // refresh silently failed, no point in retrying.\n if (newSessionData.accessJwt === sessionData.accessJwt) {\n return initialRes\n }\n\n if (init?.signal?.aborted) {\n return initialRes\n }\n\n // The stream was already consumed. We cannot retry the request. A solution\n // would be to tee() the input stream but that would bufferize the entire\n // stream in memory which can lead to memory starvation. Instead, we will\n // return the original response and let the calling code handle retries.\n if (ReadableStream && init?.body instanceof ReadableStream) {\n return initialRes\n }\n\n // Make sure the initial request is cancelled to avoid leaking resources\n // (NodeJS 👀): https://undici.nodejs.org/#/?id=garbage-collection\n if (!initialRes.bodyUsed) {\n await initialRes.body?.cancel()\n }\n\n // Finally, retry the request with the new access token\n headers.set('authorization', `Bearer ${newSessionData.accessJwt}`)\n return fetch(fetchUrl(newSessionData, path), { ...init, headers })\n }\n\n async refresh(): Promise<SessionData> {\n this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n const response = await xrpcSafe(\n this.#serviceAgent,\n com.atproto.server.refreshSession.main,\n { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n )\n\n if (!response.success && response.matchesSchema()) {\n // Expected errors that indicate the session is no longer valid\n await this.options.onDeleted?.call(this, sessionData)\n\n // Update the session promise to a rejected state\n this.#sessionData = null\n throw response\n }\n\n if (!response.success) {\n response.error\n if (response.matchesSchema()) {\n response.error\n }\n // We failed to refresh the token, assume the session might still be\n // valid by returning the existing session.\n await this.options.onUpdateFailure?.call(this, sessionData, response)\n\n return sessionData\n }\n\n const data = response.body\n\n // Historically, refreshSession did not return all the fields from\n // getSession. In particular, emailConfirmed and didDoc were missing.\n // Similarly, some servers might not return the didDoc in refreshSession.\n // We fetch them via getSession if missing, allowing to ensure that we are\n // always talking with the right PDS.\n if (data.emailConfirmed == null \|\| data.didDoc == null) {\n const extraData = await xrpcSafe(\n this.#serviceAgent,\n com.atproto.server.getSession.main,\n { headers: { Authorization: `Bearer ${data.accessJwt}` } },\n )\n if (extraData.success && extraData.body.did === data.did) {\n Object.assign(data, extraData.body)\n }\n }\n\n const newSession: SessionData = {\n ...data,\n service: sessionData.service,\n }\n\n await this.options.onUpdated?.call(this, newSession)\n\n return (this.#sessionData = newSession)\n })\n\n return this.#sessionPromise\n }\n\n async logout(): Promise<void> {\n let reason: DeleteFailure \| null = null\n\n this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n const result = await xrpcSafe(\n this.#serviceAgent,\n com.atproto.server.deleteSession.main,\n { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n )\n\n if (result.success \|\| result.matchesSchema()) {\n await this.options.onDeleted?.call(this, sessionData)\n\n // Update the session promise to a rejected state\n this.#sessionData = null\n throw new Error('Logged out')\n } else {\n // Capture the reason for the failure to re-throw in the outer promise\n reason = result\n\n // An unknown/unexpected error occurred (network, server down, etc)\n await this.options.onDeleteFailure?.call(this, sessionData, result)\n\n // Keep the session in an active state\n return sessionData\n }\n })\n\n return this.#sessionPromise.then(\n (_session) => {\n // If the promise above resolved, then logout failed. Re-throw the\n // reason captured earlier.\n throw reason!\n },\n (_err) => {\n // Successful logout\n },\n )\n }\n\n static async createAccount(\n body: com.atproto.server.createAccount.InputBody,\n {\n service,\n headers,\n ...options\n }: PasswordSessionOptions & {\n headers?: HeadersInit\n service: string \| URL\n },\n ): Promise<PasswordSession> {\n const response = await xrpc(\n buildAgent({ service, headers, fetch: options.fetch }),\n com.atproto.server.createAccount.main,\n { body },\n )\n\n const data: SessionData = {\n ...response.body,\n service: String(service),\n }\n\n const agent = new PasswordSession(data, options)\n await options.onUpdated?.call(agent, data)\n return agent\n }\n\n /\n @note It is not recommended to use {@link PasswordSession} with main\n * account credentials. Instead, it is strongly advised to use OAuth based\n * authentication for main username/password credentials and use\n * {@link PasswordSession} with an app-password, for bots, scripts, or similar\n * use-cases.\n \n @throws If unable to create a session. In particular, if the server\n * requires a 2FA token, a {@link XrpcResponseError} with the\n * `AuthFactorTokenRequired` error code will be thrown.\n \n \n * @example Handling 2FA errors\n \n ```ts\n * try {\n * const session = await PasswordSession.login({\n * service: 'https://example.com',\n * identifier: 'alice',\n * password: 'correct horse battery staple',\n * })\n * } catch (err) {\n * if (err instanceof XrpcResponseError && err.error === 'AuthFactorTokenRequired') {\n * // Prompt user for 2FA token and re-attempt session creation\n * }\n * }\n * ```\n /\n static async login({\n service,\n identifier,\n password,\n allowTakendown,\n authFactorToken,\n ...options\n }: PasswordSessionOptions & {\n service: string \| URL\n identifier: string\n password: string\n allowTakendown?: boolean\n authFactorToken?: string\n }): Promise<PasswordSession> {\n const xrpcAgent = buildAgent({\n service,\n fetch: options.fetch,\n })\n\n const response = await xrpcSafe(\n xrpcAgent,\n com.atproto.server.createSession.main,\n { body: { identifier, password, allowTakendown, authFactorToken } },\n )\n\n if (!response.success) {\n if (response.error === 'AuthFactorTokenRequired') {\n throw new LexAuthFactorError(response)\n }\n throw response.reason\n }\n\n const data: SessionData = {\n ...response.body,\n service: String(service),\n }\n\n const agent = new PasswordSession(data, options)\n await options.onUpdated?.call(agent, data)\n return agent\n }\n\n /\n Resume an existing session, ensuring it is still valid by refreshing it.\n * Any error thrown here indicates that the session is definitely no longer\n * valid. Network errors will be propagated through the\n * {@link PasswordSessionOptions.onUpdateFailure} hook, and not re-thrown\n * here. This means that a resolved promise does not necessarily indicate a\n * valid session, only that it's refresh did not definitively fail.\n \n This is the same as calling {@link PasswordSession.refresh} after\n * constructing the {@link PasswordSession} manually.\n \n @throws If, and only if, the session is definitely no longer valid.\n /\n static async resume(\n data: SessionData,\n options: PasswordSessionOptions,\n ): Promise<PasswordSession> {\n const agent = new PasswordSession(data, options)\n await agent.refresh()\n return agent\n }\n\n /\n Delete a session without having to {@link resume resume()} it first, or\n * provide hooks.\n \n @throws In case of unexpected error (network issue, server down, etc)\n * meaning that the session may still be valid.\n */\n static async delete(\n data: SessionData,\n options?: PasswordSessionOptions,\n ): Promise<void> {\n const agent = new PasswordSession(data, options)\n await agent.logout()\n }\n}\n\nfunction fetchUrl(sessionData: SessionData, path: string): URL {\n const pdsUrl = extractPdsUrl(sessionData.didDoc)\n return new URL(path, pdsUrl ?? sessionData.service)\n}\n"]}
1	+ {"version":3,"file":"password-session.js","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n Agent,\n XrpcFailure,\n buildAgent,\n xrpc,\n xrpcSafe,\n} from '@atproto/lex-client'\nimport { LexAuthFactorError } from './error.js'\nimport { com } from './lexicons/index.js'\nimport { extractPdsUrl, extractXrpcErrorCode } from './util.js'\n\n/*\n Represents a failure response when refreshing a session.\n \n This type captures the possible error responses from\n * `com.atproto.server.refreshSession`, including both expected errors\n * (e.g., invalid/expired refresh token) and unexpected errors (e.g., network issues).\n /\nexport type RefreshFailure = XrpcFailure<\n typeof com.atproto.server.refreshSession.main\n>\n\n/\n Represents a failure response when deleting a session.\n \n This type captures the possible error responses from\n * `com.atproto.server.deleteSession`, including both expected errors\n * and unexpected errors (e.g., network issues, server unavailability).\n /\nexport type DeleteFailure = XrpcFailure<\n typeof com.atproto.server.deleteSession.main\n>\n\n/\n Persisted session data containing authentication credentials and service information.\n \n This type extends the response from `com.atproto.server.createSession` with the\n * service URL used for authentication. Store this data securely to resume sessions\n * later without re-authenticating.\n /\nexport type SessionData = com.atproto.server.createSession.$OutputBody & {\n service: string\n}\n\nexport type PasswordSessionOptions = {\n /\n Custom fetch implementation to use for network requests\n /\n fetch?: typeof globalThis.fetch\n\n /\n Called whenever the session is successfully created/refreshed, and new\n * credentials have been obtained. Use this hook to persist the updated\n * session information.\n \n If this callback returns a promise, this function will never be called\n * again (on the same process) until the promise resolves.\n \n @note this function must not throw\n /\n onUpdated?: (this: PasswordSession, data: SessionData) => void \| Promise<void>\n\n /\n Called whenever the session update fails due to an expected error, such as\n * a network issue or server unavailability. This function can be used to log\n * the error or notify the user, but should not assume that the session is\n * invalid.\n \n @note this function must not throw\n /\n onUpdateFailure?: (\n this: PasswordSession,\n data: SessionData,\n err: RefreshFailure,\n ) => void \| Promise<void>\n\n /\n Called whenever the session is deleted, either due to an explicit logout or\n * because the refresh operation indicated that the session is no longer\n * valid. Use this hook to clean up any persisted session information and\n * update the application state accordingly.\n \n @note this function must not throw\n /\n onDeleted?: (this: PasswordSession, data: SessionData) => void \| Promise<void>\n\n /\n Called whenever a session deletion fails due to an unexpected error, such\n * as a network issue or server unavailability. This function can be used to\n * log the error or notify the user. When this function is called, the session\n * might still be valid on the server. It is up to the implementation to\n * decide whether to retry the deletion or keep the session active. Ignoring\n * these errors is not recommended as it can lead to orphaned sessions on the\n * server, or security issues if the user believes they have logged out when a\n * bad actor is still using the session. The implementation should consider\n * keeping track of failed deletions and retrying them later, until they\n * succeed.\n \n @note this function must not throw\n /\n onDeleteFailure?: (\n this: PasswordSession,\n data: SessionData,\n err: DeleteFailure,\n ) => void \| Promise<void>\n}\n\n/\n Password-based authentication session for AT Protocol services.\n \n This class provides session management for CLI tools, scripts, and bots that\n * need to authenticate with AT Protocol services using password credentials.\n * It implements the {@link Agent} interface, allowing it to be used directly\n * with AT Protocol clients.\n \n Security Warning: It is strongly recommended to use app passwords instead\n * of main account credentials. App passwords provide limited access and can be\n * revoked independently without compromising your main account. For browser-based\n * applications, use OAuth-based authentication instead.\n \n @example Basic usage with app password\n * ```ts\n * const session = await PasswordSession.login({\n * service: 'https://bsky.social',\n * identifier: 'alice.bsky.social',\n * password: 'xxxx-xxxx-xxxx-xxxx', // App password\n * onUpdated: (data) => saveToStorage(data),\n * onDeleted: (data) => clearStorage(data.did),\n * })\n \n const client = new Client(session)\n * // Use client to make authenticated requests\n * ```\n \n @example Resuming a persisted session\n * ```ts\n * const savedData = JSON.parse(fs.readFileSync('session.json', 'utf8'))\n * const session = await PasswordSession.resume(savedData, {\n * onUpdated: (data) => saveToStorage(data),\n * onDeleted: (data) => clearStorage(data.did),\n * })\n * ```\n \n @implements {Agent}\n /\nexport class PasswordSession implements Agent {\n /\n Internal {@link Agent} used for session management towards the\n * authentication service only.\n /\n #serviceAgent: Agent\n\n #sessionData: null \| SessionData\n #sessionPromise: Promise<SessionData>\n\n constructor(\n sessionData: SessionData,\n protected readonly options: PasswordSessionOptions = {},\n ) {\n this.#serviceAgent = buildAgent({\n service: sessionData.service,\n fetch: options.fetch,\n })\n\n this.#sessionData = sessionData\n this.#sessionPromise = Promise.resolve(this.#sessionData)\n }\n\n /\n The DID (Decentralized Identifier) of the authenticated account.\n \n @throws {Error} If the session has been destroyed (logged out).\n /\n get did() {\n return this.session.did\n }\n\n /\n The handle (username) of the authenticated account.\n \n @throws {Error} If the session has been destroyed (logged out).\n /\n get handle() {\n return this.session.handle\n }\n\n /\n The current session data containing authentication credentials.\n \n @throws {Error} If the session has been destroyed (logged out).\n /\n get session() {\n if (this.#sessionData) return this.#sessionData\n throw new Error('Logged out')\n }\n\n /\n Whether this session has been destroyed (logged out).\n \n Once destroyed, this session instance can no longer be used for\n * authenticated requests. Create a new session via {@link PasswordSession.login}\n * or {@link PasswordSession.resume}.\n /\n get destroyed(): boolean {\n return this.#sessionData === null\n }\n\n /\n Handles authenticated fetch requests to the user's PDS.\n \n This method implements the {@link Agent} interface and is called by\n * AT Protocol clients to make authenticated requests. It automatically:\n * - Adds the access token to request headers\n * - Detects expired tokens and triggers refresh\n * - Retries requests after successful token refresh\n \n @param path - The request path (will be resolved against the PDS URL)\n * @param init - Standard fetch RequestInit options (headers, body, etc.)\n * @returns The fetch Response from the PDS\n * @throws {TypeError} If an 'authorization' header is already set in init\n /\n async fetchHandler(path: string, init: RequestInit): Promise<Response> {\n const headers = new Headers(init.headers)\n if (headers.has('authorization')) {\n throw new TypeError(\"Unexpected 'authorization' header set\")\n }\n\n const sessionPromise = this.#sessionPromise\n const sessionData = await sessionPromise\n\n const fetch = this.options.fetch ?? globalThis.fetch\n\n headers.set('authorization', `Bearer ${sessionData.accessJwt}`)\n const initialRes = await fetch(fetchUrl(sessionData, path), {\n ...init,\n headers,\n })\n\n const refreshNeeded =\n initialRes.status === 401 \|\|\n (initialRes.status === 400 &&\n (await extractXrpcErrorCode(initialRes)) === 'ExpiredToken')\n\n if (!refreshNeeded) {\n return initialRes\n }\n\n // Refresh session (unless it was already refreshed in the meantime)\n const newSessionPromise =\n this.#sessionPromise === sessionPromise\n ? this.refresh()\n : this.#sessionPromise\n\n // Error should have been propagated through hooks\n const newSessionData = await newSessionPromise.catch((_err) => null)\n if (!newSessionData) {\n return initialRes\n }\n\n // refresh silently failed, no point in retrying.\n if (newSessionData.accessJwt === sessionData.accessJwt) {\n return initialRes\n }\n\n if (init?.signal?.aborted) {\n return initialRes\n }\n\n // The stream was already consumed. We cannot retry the request. A solution\n // would be to tee() the input stream but that would bufferize the entire\n // stream in memory which can lead to memory starvation. Instead, we will\n // return the original response and let the calling code handle retries.\n if (ReadableStream && init?.body instanceof ReadableStream) {\n return initialRes\n }\n\n // Make sure the initial request is cancelled to avoid leaking resources\n // (NodeJS 👀): https://undici.nodejs.org/#/?id=garbage-collection\n if (!initialRes.bodyUsed) {\n await initialRes.body?.cancel()\n }\n\n // Finally, retry the request with the new access token\n headers.set('authorization', `Bearer ${newSessionData.accessJwt}`)\n return fetch(fetchUrl(newSessionData, path), { ...init, headers })\n }\n\n /\n Refreshes the session by obtaining new access and refresh tokens.\n \n This method is automatically called by {@link fetchHandler} when the access\n * token expires. You can also call it manually to proactively refresh tokens.\n \n On success, the {@link PasswordSessionOptions.onUpdated} callback is invoked\n * with the new session data. On expected failures (invalid session), the\n * {@link PasswordSessionOptions.onDeleted} callback is invoked. On unexpected\n * failures (network issues), the {@link PasswordSessionOptions.onUpdateFailure}\n * callback is invoked and the existing session data is preserved.\n \n @returns The refreshed session data\n * @throws {RefreshFailure} If the session is no longer valid (triggers onDeleted)\n /\n async refresh(): Promise<SessionData> {\n this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n const response = await xrpcSafe(\n this.#serviceAgent,\n com.atproto.server.refreshSession.main,\n { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n )\n\n if (!response.success && response.matchesSchema()) {\n // Expected errors that indicate the session is no longer valid\n await this.options.onDeleted?.call(this, sessionData)\n\n // Update the session promise to a rejected state\n this.#sessionData = null\n throw response\n }\n\n if (!response.success) {\n response.error\n if (response.matchesSchema()) {\n response.error\n }\n // We failed to refresh the token, assume the session might still be\n // valid by returning the existing session.\n await this.options.onUpdateFailure?.call(this, sessionData, response)\n\n return sessionData\n }\n\n const data = response.body\n\n // Historically, refreshSession did not return all the fields from\n // getSession. In particular, emailConfirmed and didDoc were missing.\n // Similarly, some servers might not return the didDoc in refreshSession.\n // We fetch them via getSession if missing, allowing to ensure that we are\n // always talking with the right PDS.\n if (data.emailConfirmed == null \|\| data.didDoc == null) {\n const extraData = await xrpcSafe(\n this.#serviceAgent,\n com.atproto.server.getSession.main,\n { headers: { Authorization: `Bearer ${data.accessJwt}` } },\n )\n if (extraData.success && extraData.body.did === data.did) {\n Object.assign(data, extraData.body)\n }\n }\n\n const newSession: SessionData = {\n ...data,\n service: sessionData.service,\n }\n\n await this.options.onUpdated?.call(this, newSession)\n\n return (this.#sessionData = newSession)\n })\n\n return this.#sessionPromise\n }\n\n /\n Logs out by deleting the session on the server.\n \n This method invalidates both the access and refresh tokens on the server,\n * preventing any further use of this session. After successful logout, the\n * session is marked as destroyed and the {@link PasswordSessionOptions.onDeleted}\n * callback is invoked.\n \n If the logout request fails due to network issues or server unavailability,\n * the {@link PasswordSessionOptions.onDeleteFailure} callback is invoked and\n * the session remains active locally. In this case, you should retry the\n * logout later to ensure the session is properly invalidated on the server.\n \n @throws {DeleteFailure} If the logout request fails due to unexpected errors\n /\n async logout(): Promise<void> {\n let reason: DeleteFailure \| null = null\n\n this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n const result = await xrpcSafe(\n this.#serviceAgent,\n com.atproto.server.deleteSession.main,\n { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n )\n\n if (result.success \|\| result.matchesSchema()) {\n await this.options.onDeleted?.call(this, sessionData)\n\n // Update the session promise to a rejected state\n this.#sessionData = null\n throw new Error('Logged out')\n } else {\n // Capture the reason for the failure to re-throw in the outer promise\n reason = result\n\n // An unknown/unexpected error occurred (network, server down, etc)\n await this.options.onDeleteFailure?.call(this, sessionData, result)\n\n // Keep the session in an active state\n return sessionData\n }\n })\n\n return this.#sessionPromise.then(\n (_session) => {\n // If the promise above resolved, then logout failed. Re-throw the\n // reason captured earlier.\n throw reason!\n },\n (_err) => {\n // Successful logout\n },\n )\n }\n\n /\n Creates a new account and returns an authenticated session.\n \n This static method registers a new account on the specified service and\n * automatically creates an authenticated session for it.\n \n @param body - Account creation parameters (handle, email, password, etc.)\n * @param options - Session options including the service URL\n * @returns A new PasswordSession for the created account\n * @throws If account creation fails (e.g., handle taken, invalid invite code)\n \n @example\n * ```ts\n * const session = await PasswordSession.createAccount(\n * {\n * handle: 'alice.bsky.social',\n * email: 'alice@example.com',\n * password: 'secure-password',\n * },\n * {\n * service: 'https://bsky.social',\n * onUpdated: (data) => saveToStorage(data),\n * }\n * )\n * ```\n /\n static async createAccount(\n body: com.atproto.server.createAccount.$InputBody,\n {\n service,\n headers,\n ...options\n }: PasswordSessionOptions & {\n headers?: HeadersInit\n service: string \| URL\n },\n ): Promise<PasswordSession> {\n const response = await xrpc(\n buildAgent({ service, headers, fetch: options.fetch }),\n com.atproto.server.createAccount.main,\n { body },\n )\n\n const data: SessionData = {\n ...response.body,\n service: String(service),\n }\n\n const agent = new PasswordSession(data, options)\n await options.onUpdated?.call(agent, data)\n return agent\n }\n\n /\n Creates a new authenticated session using password credentials.\n \n This static method authenticates with the specified service and returns\n * a new PasswordSession instance that can be used for authenticated requests.\n \n Security Warning: It is strongly recommended to use app passwords instead\n * of main account credentials. App passwords can be created in your account\n * settings and provide limited access that can be revoked independently. For\n * browser-based applications, use OAuth-based authentication instead.\n \n @param options - Login options including service URL, identifier, and password\n * @param options.service - The AT Protocol service URL (e.g., 'https://bsky.social')\n * @param options.identifier - The user's handle or DID\n * @param options.password - The user's password or app password\n * @param options.allowTakendown - If true, allow login to takendown accounts\n * @param options.authFactorToken - 2FA token if required by the server\n * @returns A new authenticated PasswordSession\n * @throws {LexAuthFactorError} If the server requires a 2FA token\n * @throws If authentication fails (invalid credentials, etc.)\n \n @example Basic login with app password\n * ```ts\n * const session = await PasswordSession.login({\n * service: 'https://bsky.social',\n * identifier: 'alice.bsky.social',\n * password: 'xxxx-xxxx-xxxx-xxxx', // App password\n * onUpdated: (data) => saveToStorage(data),\n * })\n * ```\n \n @example Handling 2FA requirement\n * ```ts\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 * const token = await promptUser('Enter 2FA code:')\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 static async login({\n service,\n identifier,\n password,\n allowTakendown,\n authFactorToken,\n ...options\n }: PasswordSessionOptions & {\n service: string \| URL\n identifier: string\n password: string\n allowTakendown?: boolean\n authFactorToken?: string\n }): Promise<PasswordSession> {\n const xrpcAgent = buildAgent({\n service,\n fetch: options.fetch,\n })\n\n const response = await xrpcSafe(\n xrpcAgent,\n com.atproto.server.createSession.main,\n { body: { identifier, password, allowTakendown, authFactorToken } },\n )\n\n if (!response.success) {\n if (response.error === 'AuthFactorTokenRequired') {\n throw new LexAuthFactorError(response)\n }\n throw response.reason\n }\n\n const data: SessionData = {\n ...response.body,\n service: String(service),\n }\n\n const agent = new PasswordSession(data, options)\n await options.onUpdated?.call(agent, data)\n return agent\n }\n\n /\n Resume an existing session, ensuring it is still valid by refreshing it.\n * Any error thrown here indicates that the session is definitely no longer\n * valid. Network errors will be propagated through the\n * {@link PasswordSessionOptions.onUpdateFailure} hook, and not re-thrown\n * here. This means that a resolved promise does not necessarily indicate a\n * valid session, only that it's refresh did not definitively fail.\n \n This is the same as calling {@link PasswordSession.refresh} after\n * constructing the {@link PasswordSession} manually.\n \n @throws If, and only if, the session is definitely no longer valid.\n /\n static async resume(\n data: SessionData,\n options: PasswordSessionOptions,\n ): Promise<PasswordSession> {\n const agent = new PasswordSession(data, options)\n await agent.refresh()\n return agent\n }\n\n /\n Delete a session without having to {@link resume resume()} it first, or\n * provide hooks.\n \n @throws In case of unexpected error (network issue, server down, etc)\n * meaning that the session may still be valid.\n */\n static async delete(\n data: SessionData,\n options?: PasswordSessionOptions,\n ): Promise<void> {\n const agent = new PasswordSession(data, options)\n await agent.logout()\n }\n}\n\nfunction fetchUrl(sessionData: SessionData, path: string): URL {\n const pdsUrl = extractPdsUrl(sessionData.didDoc)\n return new URL(path, pdsUrl ?? sessionData.service)\n}\n"]}