@atcute/client 2.0.3 → 2.0.4

package/lib/rpc.ts

@@ -0,0 +1,254 @@
+import type { At, Procedures, Queries } from './lexicons.js';
+
+import { buildFetchHandler, type FetchHandler, type FetchHandlerObject } from './fetch-handler.js';
+import { mergeHeaders } from './utils/http.js';
+
+export type HeadersObject = Record<string, string>;
+
+/** Response from XRPC service */
+export interface XRPCResponse<T = any> {
+	data: T;
+	headers: HeadersObject;
+}
+
+/** Options for constructing an XRPC error */
+export interface XRPCErrorOptions {
+	kind?: string;
+	description?: string;
+	headers?: HeadersObject;
+	cause?: unknown;
+}
+
+/** Error coming from the XRPC service */
+export class XRPCError extends Error {
+	override name = 'XRPCError';
+
+	/** Response status */
+	status: number;
+	/** Response headers */
+	headers: HeadersObject;
+	/** Error kind */
+	kind?: string;
+	/** Error description */
+	description?: string;
+
+	constructor(status: number, { kind, description, headers, cause }: XRPCErrorOptions = {}) {
+		super(`${kind || 'UnspecifiedKind'} > ${description || `Unspecified error description`}`, { cause });
+
+		this.status = status;
+		this.kind = kind;
+		this.description = description;
+		this.headers = headers || {};
+	}
+}
+
+/** Service proxy options */
+export interface XRPCProxyOptions {
+	type: 'atproto_pds' | 'atproto_labeler' | 'bsky_fg' | 'bsky_notif' | ({} & string);
+	service: At.DID;
+}
+
+/** Options for constructing an XRPC */
+export interface XRPCOptions {
+	handler: FetchHandler | FetchHandlerObject;
+	proxy?: XRPCProxyOptions;
+}
+
+/** XRPC request options */
+export interface XRPCRequestOptions {
+	type: 'get' | 'post';
+	nsid: string;
+	headers?: HeadersInit;
+	params?: Record<string, unknown>;
+	data?: FormData | Blob | ArrayBufferView | Record<string, unknown>;
+	signal?: AbortSignal;
+}
+
+/** XRPC response */
+export interface XRPCResponse<T = any> {
+	data: T;
+	headers: HeadersObject;
+}
+
+/** Base options for the query/procedure request */
+interface BaseRPCOptions {
+	/** Request headers to make */
+	headers?: HeadersInit;
+	/** Signal for aborting the request */
+	signal?: AbortSignal;
+}
+
+/** Options for the query/procedure request */
+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;
+
+export class XRPC {
+	handle: FetchHandler;
+	proxy: XRPCProxyOptions | undefined;
+
+	constructor({ handler, proxy }: XRPCOptions) {
+		this.handle = buildFetchHandler(handler);
+		this.proxy = proxy;
+	}
+
+	/**
+	 * Makes a query (GET) request
+	 * @param nsid Namespace ID of a query endpoint
+	 * @param options Options to include like parameters
+	 * @returns The response of the request
+	 */
+	get<K extends keyof Queries>(
+		nsid: K,
+		options: RPCOptions<Queries[K]>,
+	): Promise<XRPCResponse<OutputOf<Queries[K]>>> {
+		return this.request({ type: 'get', nsid: nsid, ...(options as any) });
+	}
+
+	/**
+	 * Makes a procedure (POST) request
+	 * @param nsid Namespace ID of a procedure endpoint
+	 * @param options Options to include like input body or parameters
+	 * @returns The response of the request
+	 */
+	call<K extends keyof Procedures>(
+		nsid: K,
+		options: RPCOptions<Procedures[K]>,
+	): Promise<XRPCResponse<OutputOf<Procedures[K]>>> {
+		return this.request({ type: 'post', nsid: nsid, ...(options as any) });
+	}
+
+	/** Makes a request to the XRPC service */
+	async request(options: XRPCRequestOptions): Promise<XRPCResponse> {
+		const data = options.data;
+
+		const url = `/xrpc/${options.nsid}` + constructSearchParams(options.params);
+		const isInputJson = isJsonValue(data);
+
+		const response = await this.handle(url, {
+			method: options.type,
+			signal: options.signal,
+			body: isInputJson ? JSON.stringify(data) : data,
+			headers: mergeHeaders(options.headers, {
+				'content-type': isInputJson ? 'application/json' : null,
+				'atproto-proxy': constructProxyHeader(this.proxy),
+			}),
+		});
+
+		const responseStatus = response.status;
+		const responseHeaders = Object.fromEntries(response.headers);
+		const responseType = responseHeaders['content-type'];
+
+		let promise: Promise<unknown> | undefined;
+		let ret: unknown;
+
+		if (responseType) {
+			if (responseType.startsWith('application/json')) {
+				promise = response.json();
+			} else if (responseType.startsWith('text/')) {
+				promise = response.text();
+			}
+		}
+
+		try {
+			ret = await (promise || response.arrayBuffer().then((buffer) => new Uint8Array(buffer)));
+		} catch (err) {
+			throw new XRPCError(2, {
+				cause: err,
+				kind: 'InvalidResponse',
+				description: `Failed to parse response body`,
+				headers: responseHeaders,
+			});
+		}
+
+		if (responseStatus === 200) {
+			return {
+				data: ret,
+				headers: responseHeaders,
+			};
+		}
+
+		if (isErrorResponse(ret)) {
+			throw new XRPCError(responseStatus, {
+				kind: ret.error,
+				description: ret.message,
+				headers: responseHeaders,
+			});
+		}
+
+		throw new XRPCError(responseStatus, { headers: responseHeaders });
+	}
+}
+
+const constructProxyHeader = (proxy: XRPCProxyOptions | undefined): string | null => {
+	if (proxy) {
+		return `${proxy.service}#${proxy.type}`;
+	}
+
+	return null;
+};
+
+const constructSearchParams = (params: Record<string, unknown> | undefined): string => {
+	let searchParams: URLSearchParams | undefined;
+
+	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 isJsonValue = (o: unknown): o is Record<string, unknown> => {
+	if (typeof o !== 'object' || o === null) {
+		return false;
+	}
+
+	if ('toJSON' in o) {
+		return true;
+	}
+
+	const proto = Object.getPrototypeOf(o);
+	return proto === null || proto === Object.prototype;
+};
+
+const isErrorResponse = (value: any): value is ErrorResponseBody => {
+	if (typeof value !== 'object' || value === null) {
+		return false;
+	}
+
+	const kindType = typeof value.error;
+	const messageType = typeof value.message;
+
+	return (
+		(kindType === 'undefined' || kindType === 'string') &&
+		(messageType === 'undefined' || messageType === 'string')
+	);
+};
+
+interface ErrorResponseBody {
+	error?: string;
+	message?: string;
+}
+
+export const clone = (rpc: XRPC): XRPC => {
+	return new XRPC({ handler: rpc.handle, proxy: rpc.proxy });
+};
+
+export const withProxy = (rpc: XRPC, options: XRPCProxyOptions) => {
+	return new XRPC({ handler: rpc.handle, proxy: options });
+};

package/lib/utils/did.ts

@@ -0,0 +1,73 @@
+/**
+ * @module
+ * DID document-related functionalities.
+ * This module is exported for convenience and is no way part of public API,
+ * it can be removed at any time.
+ */
+
+/**
+ * Retrieves AT Protocol PDS endpoint from the DID document, if available
+ * @param doc DID document
+ * @returns The PDS endpoint, if available
+ */
+export const getPdsEndpoint = (doc: DidDocument): string | undefined => {
+	return getServiceEndpoint(doc, '#atproto_pds', 'AtprotoPersonalDataServer');
+};
+
+/**
+ * Retrieve a service endpoint from the DID document, if available
+ * @param doc DID document
+ * @param serviceId Service ID
+ * @param serviceType Service type
+ * @returns The requested service endpoint, if available
+ */
+export const getServiceEndpoint = (
+	doc: DidDocument,
+	serviceId: string,
+	serviceType: string,
+): string | undefined => {
+	const did = doc.id;
+
+	const didServiceId = did + serviceId;
+	const found = doc.service?.find((service) => service.id === serviceId || service.id === didServiceId);
+
+	if (!found || found.type !== serviceType || typeof found.serviceEndpoint !== 'string') {
+		return undefined;
+	}
+
+	return validateUrl(found.serviceEndpoint);
+};
+
+const validateUrl = (urlStr: string): string | undefined => {
+	let url;
+	try {
+		url = new URL(urlStr);
+	} catch {
+		return undefined;
+	}
+
+	const proto = url.protocol;
+
+	if (url.hostname && (proto === 'http:' || proto === 'https:')) {
+		return urlStr;
+	}
+};
+
+/**
+ * DID document
+ */
+export interface DidDocument {
+	id: string;
+	alsoKnownAs?: string[];
+	verificationMethod?: Array<{
+		id: string;
+		type: string;
+		controller: string;
+		publicKeyMultibase?: string;
+	}>;
+	service?: Array<{
+		id: string;
+		type: string;
+		serviceEndpoint: string | Record<string, unknown>;
+	}>;
+}

package/lib/utils/http.ts

@@ -0,0 +1,27 @@
+/**
+ * @module
+ * Assortment of HTTP utilities
+ * This module is exported for convenience and is no way part of public API,
+ * it can be removed at any time.
+ */
+
+export const mergeHeaders = (
+	init: HeadersInit | undefined,
+	defaults: Record<string, string | null>,
+): HeadersInit | undefined => {
+	let headers: Headers | undefined;
+
+	for (const name in defaults) {
+		const value = defaults[name];
+
+		if (value !== null) {
+			headers ??= new Headers(init);
+
+			if (!headers.has(name)) {
+				headers.set(name, value);
+			}
+		}
+	}
+
+	return headers ?? init;
+};

package/lib/utils/jwt.ts

@@ -0,0 +1,76 @@
+/**
+ * @module
+ * JWT decoding utilities for session resumption checks.
+ * This module is exported for convenience and is no way part of public API,
+ * it can be removed at any time.
+ */
+
+/**
+ * Decodes a JWT token
+ * @param token The token string
+ * @returns JSON object from the token
+ */
+export const decodeJwt = (token: string): unknown => {
+	const pos = 1;
+	const part = token.split('.')[1];
+
+	let decoded: string;
+
+	if (typeof part !== 'string') {
+		throw new Error('invalid token: missing part ' + (pos + 1));
+	}
+
+	try {
+		decoded = base64UrlDecode(part);
+	} catch (e) {
+		throw new Error('invalid token: invalid b64 for part ' + (pos + 1) + ' (' + (e as Error).message + ')');
+	}
+
+	try {
+		return JSON.parse(decoded);
+	} catch (e) {
+		throw new Error('invalid token: invalid json for part ' + (pos + 1) + ' (' + (e as Error).message + ')');
+	}
+};
+
+/**
+ * Decodes a URL-safe Base64 string
+ * @param str URL-safe Base64 that needed to be decoded
+ * @returns The actual string
+ */
+export const base64UrlDecode = (str: string): string => {
+	let output = str.replace(/-/g, '+').replace(/_/g, '/');
+
+	switch (output.length % 4) {
+		case 0:
+			break;
+		case 2:
+			output += '==';
+			break;
+		case 3:
+			output += '=';
+			break;
+		default:
+			throw new Error('base64 string is not of the correct length');
+	}
+
+	try {
+		return b64DecodeUnicode(output);
+	} catch {
+		return atob(output);
+	}
+};
+
+const b64DecodeUnicode = (str: string): string => {
+	return decodeURIComponent(
+		atob(str).replace(/(.)/g, (_m, p) => {
+			let code = p.charCodeAt(0).toString(16).toUpperCase();
+
+			if (code.length < 2) {
+				code = '0' + code;
+			}
+
+			return '%' + code;
+		}),
+	);
+};

package/package.json

@@ -1,14 +1,18 @@
 {
   "type": "module",
   "name": "@atcute/client",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "lightweight and cute API client for AT Protocol",
   "license": "MIT",
   "repository": {
-    "url": "https://codeberg.org/mary-ext/atcute"
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/core/client"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
   ],
   "exports": {
     ".": "./dist/index.js",
@@ -18,10 +22,10 @@
     "./utils/jwt": "./dist/utils/jwt.js"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^2.1.1",
-    "vitest": "^2.1.1",
-    "@atcute/lex-cli": "^1.0.2",
-    "@atcute/internal-dev-env": "^1.0.0"
+    "@vitest/coverage-v8": "^2.1.3",
+    "vitest": "^2.1.3",
+    "@atcute/internal-dev-env": "^1.0.1",
+    "@atcute/lex-cli": "^1.0.3"
   },
   "scripts": {
     "build": "tsc --project tsconfig.build.json",