@atcute/client 3.0.0 → 3.1.0

package/README.md

@@ -7,24 +7,83 @@ lightweight and cute API client for AT Protocol.
   be trusted in returning valid responses.
 
 ```ts
-import { XRPC, CredentialManager } from '@atcute/client';
+import { Client, CredentialManager, ok, simpleFetchHandler } from '@atcute/client';
 
-const manager = new CredentialManager({ service: 'https://bsky.social' });
-const rpc = new XRPC({ handler: manager });
+// import additional lexicons
+import '@atcute/bluesky/lexicons';
 
-await manager.login({ identifier: 'example.com', password: 'ofki-yrwl-hmcc-cvau' });
+// basic usage
+{
+	const handler = simpleFetchHandler({ service: 'https://public.api.bsky.app' });
+	const rpc = new Client({ handler });
 
-console.log(manager.session);
-// -> { refreshJwt: 'eyJhb...', ... }
+	// explicit response handling
+	{
+		const { ok, data } = await rpc.get('app.bsky.actor.getProfile', {
+			params: {
+				actor: 'bsky.app',
+			},
+		});
 
-const { data } = await rpc.get('com.atproto.identity.resolveHandle', {
-	params: {
-		handle: 'pfrazee.com',
-	},
-});
+		if (!ok) {
+			switch (data.error) {
+				case 'InvalidRequest': {
+					// Account doesn't exist
+					break;
+				}
+				case 'AccountTakedown': {
+					// Account taken down
+					break;
+				}
+				case 'AccountDeactivated': {
+					// Account deactivated
+					break;
+				}
+			}
+		}
 
-console.log(data.did);
-// -> did:plc:ragtjsm2j2vknwkz3zp4oxrd
+		if (ok) {
+			console.log(data.displayName);
+			// -> "Bluesky"
+		}
+	}
+
+	// optimistic response handling
+	{
+		const data = await ok(
+			rpc.get('app.bsky.actor.getProfile', {
+				params: {
+					actor: 'bsky.app',
+				},
+			}),
+		);
+
+		console.log(data.displayName);
+		// -> "Bluesky"
+	}
+}
+
+// performing authenticated requests
+{
+	const manager = new CredentialManager({ service: 'https://bsky.social' });
+	const rpc = new Client({ handler: manager });
+
+	await manager.login({ identifier: 'example.com', password: 'ofki-yrwl-hmcc-cvau' });
+
+	console.log(manager.session);
+	// -> { refreshJwt: 'eyJhb...', ... }
+
+	const data = await ok(
+		rpc.get('com.atproto.identity.resolveHandle', {
+			params: {
+				handle: 'pfrazee.com',
+			},
+		}),
+	);
+
+	console.log(data.did);
+	// -> 'did:plc:ragtjsm2j2vknwkz3zp4oxrd'
+}
 ```
 
 by default, the API client only ships with the base AT Protocol (`com.atproto.*`) lexicons and

package/dist/client.d.ts

@@ -0,0 +1,181 @@
+import type { At, Procedures, Queries } from './lexicons.js';
+import { type FetchHandler, type FetchHandlerObject } from './fetch-handler.js';
+type RequiredKeysOf<TType extends object> = TType extends any ? Exclude<{
+    [Key in keyof TType]: TType extends Record<Key, TType[Key]> ? Key : never;
+}[keyof TType], undefined> : never;
+type HasRequiredKeys<TType extends object> = RequiredKeysOf<TType> extends never ? false : true;
+type ResponseFormat = 'json' | 'blob' | 'bytes' | 'stream';
+type FormattedResponse<TDef> = {
+    json: TDef extends {
+        response: {
+            json: infer TData;
+        };
+    } ? TData : unknown;
+    blob: Blob;
+    bytes: Uint8Array;
+    stream: ReadableStream<Uint8Array>;
+};
+type BaseRequestOptions = {
+    signal?: AbortSignal;
+    headers?: HeadersInit;
+};
+export type QueryRequestOptions<TDef> = BaseRequestOptions & (TDef extends {
+    response: infer TResponse;
+} ? TResponse extends {
+    json: any;
+} ? {
+    as?: ResponseFormat | null;
+} : {
+    as: ResponseFormat | null;
+} : {
+    as: ResponseFormat | null;
+}) & (TDef extends {
+    params: infer TParams;
+} ? {
+    params: TParams;
+} : {
+    params?: Record<string, unknown>;
+});
+export type ProcedureRequestOptions<TDef> = BaseRequestOptions & (TDef extends {
+    response: infer TResponse;
+} ? TResponse extends {
+    json: any;
+} ? {
+    as?: ResponseFormat | null;
+} : {
+    as: ResponseFormat | null;
+} : {
+    as: ResponseFormat | null;
+}) & (TDef extends {
+    params: infer TParams;
+} ? {
+    params: TParams;
+} : {
+    params?: Record<string, unknown>;
+}) & (TDef extends {
+    input: infer TInput;
+} ? {
+    input: TInput;
+} : {
+    input?: Record<string, unknown>;
+});
+/** standard XRPC error payload structure */
+export type XRPCErrorPayload = {
+    /** error name */
+    error: string;
+    /** error description */
+    message?: string;
+};
+type BaseClientResponse = {
+    /** response status */
+    status: number;
+    /** response headers */
+    headers: Headers;
+};
+/** represents a successful response returned by the client */
+export type SuccessClientResponse<TDef, TInit> = BaseClientResponse & {
+    ok: true;
+    /** response data */
+    data: TInit extends {
+        as: infer TFormat;
+    } ? TFormat extends ResponseFormat ? FormattedResponse<TDef>[TFormat] : TFormat extends null ? null : never : TDef extends {
+        response: {
+            json: infer TData;
+        };
+    } ? TData : never;
+};
+/** represents a failed response returned by the client */
+export type FailedClientResponse = BaseClientResponse & {
+    ok: false;
+    /** response data */
+    data: XRPCErrorPayload;
+};
+/** represents a response returned by the client */
+export type ClientResponse<TDef, TInit> = SuccessClientResponse<TDef, TInit> | FailedClientResponse;
+/** options for configuring service proxying */
+export type ServiceProxyOptions = {
+    /** DID identifier that the upstream service should look up */
+    did: At.Did;
+    /**
+     * the specific service ID within the resolved DID document's `service` array
+     * that the upstream service should forward requests to.
+     *
+     * must start with `#`
+     *
+     * common values include:
+     * - `#atproto_pds` (personal data server)
+     * - `#atproto_labeler` (labeler service)
+     * - `#bsky_chat` (Bluesky chat service)
+     */
+    serviceId: `#${string}`;
+};
+/** options for configuring the client */
+export type ClientOptions = {
+    /** the underlying fetch handler it should make requests with */
+    handler: FetchHandler | FetchHandlerObject;
+    /** service proxy configuration */
+    proxy?: ServiceProxyOptions | null;
+};
+/** XRPC API client */
+export declare class Client<TQueries = Queries, TProcedures = Procedures> {
+    #private;
+    handler: FetchHandler;
+    proxy: ServiceProxyOptions | null;
+    constructor({ handler, proxy }: ClientOptions);
+    /**
+     * clones this XRPC client
+     * @param opts options to merge with
+     * @returns the cloned XRPC client
+     */
+    clone({ handler, proxy }?: Partial<ClientOptions>): Client<TQueries, TProcedures>;
+    /**
+     * performs an XRPC query request (HTTP GET)
+     * @param name NSID of the query
+     * @param options query options
+     */
+    get<TName extends keyof TQueries, TInit extends QueryRequestOptions<TQueries[TName]>>(name: TName, ...options: HasRequiredKeys<TInit> extends true ? [init: TInit] : [init?: TInit]): Promise<ClientResponse<TQueries[TName], TInit>>;
+    /**
+     * performs an XRPC procedure request (HTTP POST)
+     * @param name NSID of the procedure
+     * @param options procedure options
+     */
+    post<TName extends keyof TProcedures, TInit extends ProcedureRequestOptions<TProcedures[TName]>>(name: TName, ...options: HasRequiredKeys<TInit> extends true ? [init: TInit] : [init?: TInit]): Promise<ClientResponse<TProcedures[TName], TInit>>;
+}
+export declare const isXRPCErrorPayload: (input: any) => input is XRPCErrorPayload;
+type SuccessData<R> = R extends {
+    ok: true;
+    data: infer D;
+} ? D : never;
+/**
+ * takes in the response returned by the client, and either returns the data if
+ * it is a successful response, or throws if it's a failed response.
+ * @param input either a ClientResponse, or a promise that resolves to a ClientResponse
+ * @returns the data from a successful response
+ *
+ * @example
+ * const data = await ok(client.get('com.atproto.server.describeServer'));
+ * //    ^? ComAtprotoServerDescribeServer.Output
+ */
+export declare const ok: {
+    <T extends Promise<ClientResponse<any, any>>>(promise: T): Promise<SuccessData<Awaited<T>>>;
+    <T extends ClientResponse<any, any>>(response: T): SuccessData<T>;
+};
+/** options when constructing a ClientResponseError */
+export type ClientResponseErrorOptions = {
+    status: number;
+    headers?: Headers;
+    data: XRPCErrorPayload;
+};
+/** represents an error response returned by the client */
+export declare class ClientResponseError extends Error {
+    /** error name returned by service */
+    readonly error: string;
+    /** error message returned by service */
+    readonly description?: string;
+    /** response status */
+    readonly status: number;
+    /** response headers */
+    readonly headers: Headers;
+    constructor({ status, headers, data }: ClientResponseErrorOptions);
+}
+export {};

package/dist/client.js

@@ -0,0 +1,180 @@
+import { buildFetchHandler } from './fetch-handler.js';
+import { mergeHeaders } from './utils/http.js';
+const JSON_CONTENT_TYPE_RE = /\bapplication\/json\b/;
+/** XRPC API client */
+export class Client {
+    constructor({ handler, proxy = null }) {
+        this.handler = buildFetchHandler(handler);
+        this.proxy = proxy;
+    }
+    /**
+     * clones this XRPC client
+     * @param opts options to merge with
+     * @returns the cloned XRPC client
+     */
+    clone({ handler = this.handler, proxy = this.proxy } = {}) {
+        return new Client({ handler, proxy });
+    }
+    get(name, options = {}) {
+        return this.#perform('get', name, options);
+    }
+    post(name, options = {}) {
+        return this.#perform('post', name, options);
+    }
+    async #perform(method, name, { signal, as: format = 'json', headers, input, params }) {
+        const isWebInput = input &&
+            (input instanceof Blob ||
+                ArrayBuffer.isView(input) ||
+                input instanceof ArrayBuffer ||
+                input instanceof ReadableStream);
+        const url = `/xrpc/${name}` + _constructSearchParams(params);
+        const response = await this.handler(url, {
+            method,
+            signal,
+            body: input && !isWebInput ? JSON.stringify(input) : input,
+            headers: mergeHeaders(headers, {
+                'content-type': input && !isWebInput ? 'application/json' : null,
+                'atproto-proxy': _constructProxyHeader(this.proxy),
+            }),
+        });
+        {
+            const status = response.status;
+            const headers = response.headers;
+            const type = headers.get('content-type');
+            if (status !== 200) {
+                let json;
+                if (type != null && JSON_CONTENT_TYPE_RE.test(type)) {
+                    // it should be okay to swallow the parsing error here
+                    try {
+                        const parsed = await response.json();
+                        if (isXRPCErrorPayload(parsed)) {
+                            json = parsed;
+                        }
+                    }
+                    catch { }
+                }
+                else {
+                    await response.body?.cancel();
+                }
+                return {
+                    ok: false,
+                    status: status,
+                    headers: headers,
+                    data: json ?? {
+                        error: `UnknownXRPCError`,
+                        message: `Request failed with status code ${status}`,
+                    },
+                };
+            }
+            {
+                let data;
+                switch (format) {
+                    case 'json': {
+                        if (type != null && JSON_CONTENT_TYPE_RE.test(type)) {
+                            // we shouldn't be handling parsing errors
+                            data = await response.json();
+                        }
+                        else {
+                            await response.body?.cancel();
+                            throw new TypeError(`Invalid response content-type (got ${type})`);
+                        }
+                        break;
+                    }
+                    case null: {
+                        data = null;
+                        await response.body?.cancel();
+                        if (type != null) {
+                            throw new TypeError(`Invalid response content-type (got ${type})`);
+                        }
+                        break;
+                    }
+                    case 'blob': {
+                        data = await response.blob();
+                        break;
+                    }
+                    case 'bytes': {
+                        data = new Uint8Array(await response.arrayBuffer());
+                        break;
+                    }
+                    case 'stream': {
+                        data = response.body;
+                        break;
+                    }
+                }
+                return {
+                    ok: true,
+                    status: status,
+                    headers: headers,
+                    data: data,
+                };
+            }
+        }
+    }
+}
+// #endregion
+// #region Utility functions
+const _constructSearchParams = (params) => {
+    let searchParams;
+    for (const key in params) {
+        const value = params[key];
+        if (value !== undefined) {
+            searchParams ??= new URLSearchParams();
+            if (Array.isArray(value)) {
+                for (let idx = 0, len = value.length; idx < len; idx++) {
+                    const val = value[idx];
+                    searchParams.append(key, '' + val);
+                }
+            }
+            else {
+                searchParams.set(key, '' + value);
+            }
+        }
+    }
+    return searchParams ? `?` + searchParams.toString() : '';
+};
+const _constructProxyHeader = (proxy) => {
+    if (proxy != null) {
+        return `${proxy.did}${proxy.serviceId}`;
+    }
+    return null;
+};
+export const isXRPCErrorPayload = (input) => {
+    if (typeof input !== 'object' || input == null) {
+        return false;
+    }
+    const kindType = typeof input.error;
+    const messageType = typeof input.message;
+    return kindType === 'string' && (messageType === 'undefined' || messageType === 'string');
+};
+/**
+ * takes in the response returned by the client, and either returns the data if
+ * it is a successful response, or throws if it's a failed response.
+ * @param input either a ClientResponse, or a promise that resolves to a ClientResponse
+ * @returns the data from a successful response
+ *
+ * @example
+ * const data = await ok(client.get('com.atproto.server.describeServer'));
+ * //    ^? ComAtprotoServerDescribeServer.Output
+ */
+export const ok = (input) => {
+    if (input instanceof Promise) {
+        return input.then(ok);
+    }
+    if (input.ok) {
+        return input.data;
+    }
+    throw new ClientResponseError(input);
+};
+/** represents an error response returned by the client */
+export class ClientResponseError extends Error {
+    constructor({ status, headers = new Headers(), data }) {
+        super(`${data.error} > ${data.message ?? '(unspecified description)'}`);
+        this.name = 'ClientResponseError';
+        this.error = data.error;
+        this.description = data.message;
+        this.status = status;
+        this.headers = headers;
+    }
+}
+// #endregion
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../lib/client.ts"],"names":[],"mappings":"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"}

package/dist/credential-manager.d.ts

@@ -1,95 +1,104 @@
 import type { At } from './lexicons.js';
 import { type FetchHandlerObject } from './fetch-handler.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;
 }
 export interface CredentialManagerOptions {
     /** PDS server URL */
     service: string;
-    /** Custom fetch function */
-    fetch?: typeof globalThis.fetch;
-    /** Function that gets called if the session turned out to have expired during an XRPC request */
+    /** custom fetch function */
+    fetch?: typeof fetch;
+    /** 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 declare class CredentialManager implements FetchHandlerObject {
     #private;
+    /** service URL to make authentication requests with */
     readonly serviceUrl: string;
+    /** fetch implementation */
     fetch: typeof fetch;
-    /** Current session state */
+    /** current active session, undefined if not authenticated */
     session?: AtpSessionData;
     constructor({ service, onExpired, onRefresh, onSessionUpdate, fetch: _fetch, }: CredentialManagerOptions);
+    /** service URL to make actual API requests with */
     get dispatchUrl(): string;
     handle(pathname: string, init: RequestInit): Promise<Response>;
     /**
-     * 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
      */
     resume(session: AtpSessionData): Promise<AtpSessionData>;
     /**
-     * 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
      */
     login(options: AuthLoginOptions): Promise<AtpSessionData>;
 }
-/** 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;
 }