@atcute/client 3.0.0 → 3.1.0

package/lib/credential-manager.ts

@@ -1,65 +1,71 @@
 import type { At, ComAtprotoServerCreateSession } from './lexicons.js';
 
+import { Client, ClientResponseError, isXRPCErrorPayload, ok } from './client.js';
 import { simpleFetchHandler, type FetchHandlerObject } from './fetch-handler.js';
-import { XRPC, XRPCError } from './rpc.js';
 
 import { getPdsEndpoint, type DidDocument } from './utils/did.js';
 import { decodeJwt } from './utils/jwt.js';
 
-/** Interface for the decoded access token, for convenience */
+/**
+ * represents the decoded access token, for convenience
+ * @deprecated
+ */
 export interface AtpAccessJwt {
-	/** Access token scope, app password returns a different scope. */
+	/** access token scope */
 	scope:
 		| 'com.atproto.access'
 		| 'com.atproto.appPass'
 		| 'com.atproto.appPassPrivileged'
 		| 'com.atproto.signupQueued'
 		| 'com.atproto.takendown';
-	/** Account DID */
+	/** account DID */
 	sub: At.Did;
-	/** Expiration time */
+	/** expiration time in Unix seconds */
 	exp: number;
-	/** Creation/issued time */
+	/** token issued time in Unix seconds */
 	iat: number;
 }
 
-/** Interface for the decoded refresh token, for convenience */
+/**
+ * represents the the decoded refresh token, for convenience
+ * @deprecated
+ */
 export interface AtpRefreshJwt {
-	/** Refresh token scope */
+	/** refresh token scope */
 	scope: 'com.atproto.refresh';
-	/** ID of this refresh token */
+	/** unique identifier for this session */
 	jti: string;
-	/** Account DID */
+	/** account DID */
 	sub: At.Did;
-	/** Intended audience of this refresh token, in DID */
+	/** intended audience of this refresh token, in DID */
 	aud: At.Did;
-	/** Expiration time */
+	/** token expiration time in seconds */
 	exp: number;
-	/** Creation/issued time */
+	/** token issued time in seconds */
 	iat: number;
 }
 
-/** Saved session data, this can be reused again for next time. */
+/** session data, can be persisted and reused */
 export interface AtpSessionData {
-	/** Refresh token */
+	/** refresh token */
 	refreshJwt: string;
-	/** Access token */
+	/** access token */
 	accessJwt: string;
-	/** Account handle */
+	/** account handle */
 	handle: string;
-	/** Account DID */
+	/** account DID */
 	did: At.Did;
 	/** PDS endpoint found in the DID document, this will be used as the service URI if provided */
 	pdsUri?: string;
-	/** Email address of the account, might not be available if on app password */
+	/** email address of the account, might not be available if on app password */
 	email?: string;
-	/** If the email address has been confirmed or not */
+	/** whether the email address has been confirmed or not */
 	emailConfirmed?: boolean;
-	/** If the account has email-based two-factor authentication enabled */
+	/** whether the account has email-based two-factor authentication enabled */
 	emailAuthFactor?: boolean;
-	/** Whether the account is active (not deactivated, taken down, or suspended) */
+	/** whether the account is active (not deactivated, taken down, or suspended) */
 	active: boolean;
-	/** Possible reason for why the account is inactive */
+	/** possible reason for why the account is inactive */
 	inactiveStatus?: string;
 }
 
@@ -67,29 +73,36 @@ export interface CredentialManagerOptions {
 	/** PDS server URL */
 	service: string;
 
-	/** Custom fetch function */
-	fetch?: typeof globalThis.fetch;
+	/** custom fetch function */
+	fetch?: typeof fetch;
 
-	/** Function that gets called if the session turned out to have expired during an XRPC request */
+	/** function called when the session expires and can't be refreshed */
 	onExpired?: (session: AtpSessionData) => void;
-	/** Function that gets called if the session has been refreshed during an XRPC request */
+	/** function called after a successful session refresh */
 	onRefresh?: (session: AtpSessionData) => void;
-	/** Function that gets called if the session object has been refreshed */
+	/** function called whenever the session object is updated (login, resume, refresh) */
 	onSessionUpdate?: (session: AtpSessionData) => void;
 }
 
 export class CredentialManager implements FetchHandlerObject {
+	/** service URL to make authentication requests with */
 	readonly serviceUrl: string;
+	/** fetch implementation */
 	fetch: typeof fetch;
 
-	#server: XRPC;
+	/** internal client instance for making authentication requests */
+	#server: Client;
+	/** holds a promise for the current refresh operation, used for debouncing */
 	#refreshSessionPromise: Promise<void> | undefined;
 
+	/** callback for session expiration */
 	#onExpired: CredentialManagerOptions['onExpired'];
+	/** callback for successful session refresh */
 	#onRefresh: CredentialManagerOptions['onRefresh'];
+	/** callback for session updates */
 	#onSessionUpdate: CredentialManagerOptions['onSessionUpdate'];
 
-	/** Current session state */
+	/** current active session, undefined if not authenticated */
 	session?: AtpSessionData;
 
 	constructor({
@@ -102,13 +115,14 @@ export class CredentialManager implements FetchHandlerObject {
 		this.serviceUrl = service;
 		this.fetch = _fetch;
 
-		this.#server = new XRPC({ handler: simpleFetchHandler({ service: service, fetch: _fetch }) });
+		this.#server = new Client({ handler: simpleFetchHandler({ service, fetch: _fetch }) });
 
 		this.#onRefresh = onRefresh;
 		this.#onExpired = onExpired;
 		this.#onSessionUpdate = onSessionUpdate;
 	}
 
+	/** service URL to make actual API requests with */
 	get dispatchUrl() {
 		return this.session?.pdsUri ?? this.serviceUrl;
 	}
@@ -138,13 +152,14 @@ export class CredentialManager implements FetchHandlerObject {
 			return initialResponse;
 		}
 
-		// Return initial response if:
-		// - refreshSession returns expired
-		// - Body stream has been consumed
+		// return initial response if:
+		// - the above refreshSession failed and cleared the session
+		// - provided request body was a stream, which can't be resent once consumed
 		if (!this.session || init.body instanceof ReadableStream) {
 			return initialResponse;
 		}
 
+		// set the new token and retry the request
 		headers.set('authorization', `Bearer ${this.session.accessJwt}`);
 
 		return await (0, this.fetch)(url, { ...init, headers });
@@ -158,30 +173,29 @@ export class CredentialManager implements FetchHandlerObject {
 
 	async #refreshSessionInner(): Promise<void> {
 		const currentSession = this.session;
-
 		if (!currentSession) {
 			return;
 		}
 
-		try {
-			const { data } = await this.#server.call('com.atproto.server.refreshSession', {
-				headers: {
-					authorization: `Bearer ${currentSession.refreshJwt}`,
-				},
-			});
-
-			this.#updateSession({ ...currentSession, ...data });
-			this.#onRefresh?.(this.session!);
-		} catch (err) {
-			if (err instanceof XRPCError) {
-				const kind = err.kind;
-
-				if (kind === 'ExpiredToken' || kind === 'InvalidToken') {
-					this.session = undefined;
-					this.#onExpired?.(currentSession);
-				}
+		const response = await this.#server.post('com.atproto.server.refreshSession', {
+			headers: {
+				authorization: `Bearer ${currentSession.refreshJwt}`,
+			},
+		});
+
+		if (!response.ok) {
+			const error = response.data.error;
+
+			if (error === 'ExpiredToken' || error === 'InvalidToken') {
+				this.session = undefined;
+				this.#onExpired?.(currentSession);
 			}
+
+			throw new ClientResponseError(response);
 		}
+
+		this.#updateSession({ ...currentSession, ...response.data });
+		this.#onRefresh?.(this.session!);
 	}
 
 	#updateSession(raw: ComAtprotoServerCreateSession.Output): AtpSessionData {
@@ -192,7 +206,7 @@ export class CredentialManager implements FetchHandlerObject {
 			pdsUri = getPdsEndpoint(didDoc);
 		}
 
-		const newSession = {
+		const newSession: AtpSessionData = {
 			accessJwt: raw.accessJwt,
 			refreshJwt: raw.refreshJwt,
 			handle: raw.handle,
@@ -200,7 +214,7 @@ export class CredentialManager implements FetchHandlerObject {
 			pdsUri: pdsUri,
 			email: raw.email,
 			emailConfirmed: raw.emailConfirmed,
-			emailAuthFactor: raw.emailConfirmed,
+			emailAuthFactor: raw.emailAuthFactor,
 			active: raw.active ?? true,
 			inactiveStatus: raw.status,
 		};
@@ -212,16 +226,16 @@ export class CredentialManager implements FetchHandlerObject {
 	}
 
 	/**
-	 * Resume a saved session
-	 * @param session Session information, taken from `AtpAuth#session` after login
+	 * resume from a persisted session
+	 * @param session session data, taken from `AtpAuth#session` after login
 	 */
 	async resume(session: AtpSessionData): Promise<AtpSessionData> {
-		const now = Date.now() / 1000 + 60 * 5;
+		const now = Date.now() / 1_000 + 60 * 5;
 
 		const refreshToken = decodeJwt(session.refreshJwt) as AtpRefreshJwt;
 
 		if (now >= refreshToken.exp) {
-			throw new XRPCError(401, { kind: 'InvalidToken' });
+			throw new ClientResponseError({ status: 401, data: { error: 'InvalidToken' } });
 		}
 
 		const accessToken = decodeJwt(session.accessJwt) as AtpAccessJwt;
@@ -230,62 +244,69 @@ export class CredentialManager implements FetchHandlerObject {
 		if (now >= accessToken.exp) {
 			await this.#refreshSession();
 		} else {
-			const promise = this.#server.get('com.atproto.server.getSession', {
-				headers: {
-					authorization: `Bearer ${session.accessJwt}`,
+			const promise = ok(
+				this.#server.get('com.atproto.server.getSession', {
+					headers: {
+						authorization: `Bearer ${session.accessJwt}`,
+					},
+				}),
+			);
+
+			promise.then(
+				(next) => {
+					const existing = this.session;
+					if (!existing || existing.did !== next.did) {
+						return;
+					}
+
+					this.#updateSession({ ...existing, ...next });
 				},
-			});
-
-			promise.then((response) => {
-				const existing = this.session;
-				const next = response.data;
-
-				if (!existing) {
-					return;
-				}
-
-				this.#updateSession({ ...existing, ...next });
-			});
+				(_err) => {
+					// ignore error
+				},
+			);
 		}
 
 		if (!this.session) {
-			throw new XRPCError(401, { kind: 'InvalidToken' });
+			throw new ClientResponseError({ status: 401, data: { error: 'InvalidToken' } });
 		}
 
 		return this.session;
 	}
 
 	/**
-	 * Perform a login operation
-	 * @param options Login options
-	 * @returns Session data that can be saved for later
+	 * sign in to an account
+	 * @param options credential options
+	 * @returns session data
 	 */
 	async login(options: AuthLoginOptions): Promise<AtpSessionData> {
 		// Reset the session
 		this.session = undefined;
 
-		const res = await this.#server.call('com.atproto.server.createSession', {
-			data: {
-				identifier: options.identifier,
-				password: options.password,
-				authFactorToken: options.code,
-				allowTakendown: options.allowTakendown,
-			},
-		});
+		const session = await ok(
+			this.#server.post('com.atproto.server.createSession', {
+				input: {
+					identifier: options.identifier,
+					password: options.password,
+					authFactorToken: options.code,
+					allowTakendown: options.allowTakendown,
+				},
+			}),
+		);
 
-		return this.#updateSession(res.data);
+		return this.#updateSession(session);
 	}
 }
 
-/** Login options */
+/** credentials */
 export interface AuthLoginOptions {
-	/** What account to login as, this could be domain handle, DID, or email address */
+	/** what account to login as, this could be domain handle, DID, or email address */
 	identifier: string;
-	/** Account password */
+	/** account password */
 	password: string;
-	/** Two-factor authentication code */
+	/** two-factor authentication code, if email TOTP is enabled */
 	code?: string;
-	/** Allow signing in even if the account has been taken down,  */
+	/** allow signing in even if the account has been taken down */
 	allowTakendown?: boolean;
 }
 
@@ -298,6 +319,9 @@ const isExpiredTokenResponse = async (response: Response): Promise<boolean> => {
 		return false;
 	}
 
+	// this is nasty as it relies heavily on what the PDS returns, but avoiding
+	// cloning and reading the request as much as possible is better.
+
 	// {"error":"ExpiredToken","message":"Token has expired"}
 	// {"error":"ExpiredToken","message":"Token is expired"}
 	if (extractContentLength(response.headers) > 54 * 1.5) {
@@ -305,8 +329,10 @@ const isExpiredTokenResponse = async (response: Response): Promise<boolean> => {
 	}
 
 	try {
-		const { error, message } = await response.clone().json();
-		return error === 'ExpiredToken' && (typeof message === 'string' || message === undefined);
+		const data = await response.clone().json();
+		if (isXRPCErrorPayload(data)) {
+			return data.error === 'ExpiredToken';
+		}
 	} catch {}
 
 	return false;

package/lib/fetch-handler.ts

@@ -1,7 +1,7 @@
-/** Fetch handler function */
+/** fetch handler function */
 export type FetchHandler = (pathname: string, init: RequestInit) => Promise<Response>;
 
-/** Fetch handler in an object */
+/** fetch handler in an object */
 export interface FetchHandlerObject {
 	handle(this: FetchHandlerObject, pathname: string, init: RequestInit): Promise<Response>;
 }
@@ -25,6 +25,6 @@ export const simpleFetchHandler = ({
 }: SimpleFetchHandlerOptions): FetchHandler => {
 	return async (pathname, init) => {
 		const url = new URL(pathname, service);
-		return _fetch(url, init);
+		return await _fetch(url, init);
 	};
 };

package/lib/index.ts

@@ -1,3 +1,4 @@
-export * from './rpc.js';
-export * from './fetch-handler.js';
+export * from './client.js';
 export * from './credential-manager.js';
+export * from './fetch-handler.js';
+export * from './rpc.js';

package/lib/lexicons.ts

@@ -316,6 +316,17 @@ export declare namespace ComAtprotoAdminUpdateAccountPassword {
 	type Output = undefined;
 }
 
+/** Administrative action to update an account's signing key in their Did document. */
+export declare namespace ComAtprotoAdminUpdateAccountSigningKey {
+	interface Params {}
+	interface Input {
+		did: At.Did;
+		/** Did-key formatted public key */
+		signingKey: At.Did;
+	}
+	type Output = undefined;
+}
+
 /** Update the service-specific admin status of a subject (account, record, or blob). */
 export declare namespace ComAtprotoAdminUpdateSubjectStatus {
 	interface Params {}
@@ -1336,6 +1347,10 @@ export declare namespace ComAtprotoServerUpdateEmail {
 	}
 }
 
+export declare namespace ComAtprotoSyncDefs {
+	type HostStatus = 'active' | 'banned' | 'idle' | 'offline' | 'throttled' | (string & {});
+}
+
 /** Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS. */
 export declare namespace ComAtprotoSyncGetBlob {
 	interface Params {
@@ -1404,6 +1419,26 @@ export declare namespace ComAtprotoSyncGetHead {
 	}
 }
 
+/** Returns information about a specified upstream host, as consumed by the server. Implemented by relays. */
+export declare namespace ComAtprotoSyncGetHostStatus {
+	interface Params {
+		/** Hostname of the host (eg, PDS or relay) being queried. */
+		hostname: string;
+	}
+	type Input = undefined;
+	interface Output {
+		hostname: string;
+		/** Number of accounts on the server which are associated with the upstream host. Note that the upstream may actually have more accounts. */
+		accountCount?: number;
+		/** Recent repo stream event sequence number. May be delayed from actual stream processing (eg, persisted cursor not in-memory cursor). */
+		seq?: number;
+		status?: ComAtprotoSyncDefs.HostStatus;
+	}
+	interface Errors {
+		HostNotFound: {};
+	}
+}
+
 /** Get the current commit CID & revision of the specified repo. Does not require auth. */
 export declare namespace ComAtprotoSyncGetLatestCommit {
 	interface Params {
@@ -1516,6 +1551,34 @@ export declare namespace ComAtprotoSyncListBlobs {
 	}
 }
 
+/** Enumerates upstream hosts (eg, PDS or relay instances) that this service consumes from. Implemented by relays. */
+export declare namespace ComAtprotoSyncListHosts {
+	interface Params {
+		cursor?: string;
+		/**
+		 * Minimum: 1 \
+		 * Maximum: 1000
+		 * @default 200
+		 */
+		limit?: number;
+	}
+	type Input = undefined;
+	interface Output {
+		/** Sort order is not formally specified. Recommended order is by time host was first seen by the server, with oldest first. */
+		hosts: Host[];
+		cursor?: string;
+	}
+	interface Host {
+		[Brand.Type]?: 'com.atproto.sync.listHosts#host';
+		/** hostname of server; not a URL (no scheme) */
+		hostname: string;
+		accountCount?: number;
+		/** Recent repo stream event sequence number. May be delayed from actual stream processing (eg, persisted cursor not in-memory cursor). */
+		seq?: number;
+		status?: ComAtprotoSyncDefs.HostStatus;
+	}
+}
+
 /** Enumerates all the DID, rev, and commit CID for all repos hosted by this service. Does not require auth; implemented by PDS and Relay. */
 export declare namespace ComAtprotoSyncListRepos {
 	interface Params {
@@ -1593,6 +1656,9 @@ export declare namespace ComAtprotoSyncRequestCrawl {
 		hostname: string;
 	}
 	type Output = undefined;
+	interface Errors {
+		HostBanned: {};
+	}
 }
 
 export declare namespace ComAtprotoSyncSubscribeRepos {
@@ -1887,6 +1953,12 @@ export declare interface Queries {
 		output: ComAtprotoSyncGetHead.Output;
 		response: { json: ComAtprotoSyncGetHead.Output };
 	};
+	'com.atproto.sync.getHostStatus': {
+		params: ComAtprotoSyncGetHostStatus.Params;
+		/** @deprecated */
+		output: ComAtprotoSyncGetHostStatus.Output;
+		response: { json: ComAtprotoSyncGetHostStatus.Output };
+	};
 	'com.atproto.sync.getLatestCommit': {
 		params: ComAtprotoSyncGetLatestCommit.Params;
 		/** @deprecated */
@@ -1917,6 +1989,12 @@ export declare interface Queries {
 		output: ComAtprotoSyncListBlobs.Output;
 		response: { json: ComAtprotoSyncListBlobs.Output };
 	};
+	'com.atproto.sync.listHosts': {
+		params: ComAtprotoSyncListHosts.Params;
+		/** @deprecated */
+		output: ComAtprotoSyncListHosts.Output;
+		response: { json: ComAtprotoSyncListHosts.Output };
+	};
 	'com.atproto.sync.listRepos': {
 		params: ComAtprotoSyncListRepos.Params;
 		/** @deprecated */
@@ -1970,6 +2048,9 @@ export declare interface Procedures {
 	'com.atproto.admin.updateAccountPassword': {
 		input: ComAtprotoAdminUpdateAccountPassword.Input;
 	};
+	'com.atproto.admin.updateAccountSigningKey': {
+		input: ComAtprotoAdminUpdateAccountSigningKey.Input;
+	};
 	'com.atproto.admin.updateSubjectStatus': {
 		input: ComAtprotoAdminUpdateSubjectStatus.Input;
 		/** @deprecated */

package/lib/rpc.ts

@@ -3,15 +3,24 @@ import type { At, Procedures, Queries } from './lexicons.js';
 import { buildFetchHandler, type FetchHandler, type FetchHandlerObject } from './fetch-handler.js';
 import { mergeHeaders } from './utils/http.js';
 
+/**
+ * @deprecated
+ */
 export type HeadersObject = Record<string, string>;
 
-/** Response from XRPC service */
+/**
+ * Response from XRPC service
+ * @deprecated
+ */
 export interface XRPCResponse<T = any> {
 	data: T;
 	headers: HeadersObject;
 }
 
-/** Options for constructing an XRPC error */
+/**
+ * Options for constructing an XRPC error
+ * @deprecated
+ */
 export interface XRPCErrorOptions {
 	kind?: string;
 	description?: string;
@@ -19,7 +28,10 @@ export interface XRPCErrorOptions {
 	cause?: unknown;
 }
 
-/** Error coming from the XRPC service */
+/**
+ * Error coming from the XRPC service
+ * @deprecated
+ */
 export class XRPCError extends Error {
 	override name = 'XRPCError';
 
@@ -50,19 +62,28 @@ export class XRPCError extends Error {
 	}
 }
 
-/** Service proxy options */
+/**
+ * Service proxy options
+ * @deprecated
+ */
 export interface XRPCProxyOptions {
 	type: 'atproto_pds' | 'atproto_labeler' | 'bsky_fg' | 'bsky_notif' | ({} & string);
 	service: At.Did;
 }
 
-/** Options for constructing an XRPC */
+/**
+ * Options for constructing an XRPC
+ * @deprecated
+ */
 export interface XRPCOptions {
 	handler: FetchHandler | FetchHandlerObject;
 	proxy?: XRPCProxyOptions;
 }
 
-/** XRPC request options */
+/**
+ * XRPC request options
+ * @deprecated
+ */
 export interface XRPCRequestOptions {
 	type: 'get' | 'post';
 	nsid: string;
@@ -72,7 +93,10 @@ export interface XRPCRequestOptions {
 	signal?: AbortSignal;
 }
 
-/** XRPC response */
+/**
+ * XRPC response
+ * @deprecated
+ */
 export interface XRPCResponse<T = any> {
 	data: T;
 	headers: HeadersObject;
@@ -86,13 +110,19 @@ interface BaseRPCOptions {
 	signal?: AbortSignal;
 }
 
-/** Options for the query/procedure request */
+/**
+ * Options for the query/procedure request
+ * @deprecated
+ */
 export type RPCOptions<T> = BaseRPCOptions &
 	(T extends { params: any } ? { params: T['params'] } : {}) &
 	(T extends { input: any } ? { data: T['input'] } : {});
 
 type OutputOf<T> = T extends { output: any } ? T['output'] : never;
 
+/**
+ * @deprecated
+ */
 export class XRPC {
 	handle: FetchHandler;
 	proxy: XRPCProxyOptions | undefined;
@@ -253,10 +283,16 @@ interface ErrorResponseBody {
 	message?: string;
 }
 
+/**
+ * @deprecated
+ */
 export const clone = (rpc: XRPC): XRPC => {
 	return new XRPC({ handler: rpc.handle, proxy: rpc.proxy });
 };
 
+/**
+ * @deprecated
+ */
 export const withProxy = (rpc: XRPC, options: XRPCProxyOptions) => {
 	return new XRPC({ handler: rpc.handle, proxy: options });
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@atcute/client",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "lightweight and cute API client for AT Protocol",
   "license": "MIT",
   "repository": {
@@ -25,7 +25,7 @@
     "@vitest/coverage-v8": "^3.0.4",
     "vitest": "^3.0.4",
     "@atcute/internal-dev-env": "^1.0.1",
-    "@atcute/lex-cli": "^1.1.0"
+    "@atcute/lex-cli": "^1.1.2"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",