@mussnad/frappe-js-client
Version:
Next-generation TS/JS client for Frappe REST APIs, built on axios for robust, type-safe integration.
301 lines (300 loc) • 12.1 kB
TypeScript
import { AxiosInstance } from 'axios';
import { BulkUpdateResponse, GetCountArgs, GetCountResponse, GetDocArgs, GetListArgs, GetValueArgs, RenameDocResponse } from './types';
import { FrappeDoc } from '../frappe/types';
import { ApiData, ApiParams, TypedResponse } from '../call/types';
/**
* FrappeClient is a class that provides a client for the Frappe API.
* It is used to fetch documents from the Frappe database.
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
*/
export declare class FrappeClient {
/** URL of the Frappe App instance */
private readonly appURL;
/** Axios instance for making HTTP requests */
readonly axios: AxiosInstance;
/** Whether to use token based authentication */
readonly useToken: boolean;
/** Function that returns the authentication token */
readonly token?: () => string;
/** Type of token to be used for authentication */
readonly tokenType?: 'Bearer' | 'token';
/**
* Creates a new FrappeClient instance.
*
* @param appURL - The URL of the Frappe App instance
* @param axios - The Axios instance for making HTTP requests
* @param useToken - Whether to use token based authentication
* @param token - Function that returns the authentication token
* @param tokenType - Type of token to use ('Bearer' or 'token')
*/
constructor(appURL: string, axios: AxiosInstance, useToken?: boolean, token?: () => string, tokenType?: 'Bearer' | 'token');
/**
* Fetches a list of documents from the Frappe database.
*
* @param doctype - The name of the document type to fetch
* @param args - The arguments for the fetch operation
* @returns A promise that resolves to the list of documents
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* const docs = await client.getList('DocType', {
* fields: ['name', 'title'],
* })
* ```
*/
getList<T extends FrappeDoc<object>>(doctype: string, args?: GetListArgs<T>): Promise<T[]>;
/**
* Fetches the count of documents from the Frappe database.
*
* @param doctype - The name of the document type to fetch
* @param args - The arguments for the fetch operation
* @returns A promise that resolves to the count of documents
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* const count = await client.getCount('DocType', {
* filters: ['name', '=', 'test'],
* })
* ```
*/
getCount<T extends GetCountResponse, K extends FrappeDoc<T>>(doctype: string, args?: GetCountArgs<K>): Promise<T>;
/**
* Fetches a document from the Frappe database.
*
* @param doctype - The name of the document type to fetch
* @param name - The name of the document to fetch
* @param args - The arguments for the fetch operation
* @returns A promise that resolves to the document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* const doc = await client.getDoc('DocType', 'test')
* ```
*/
getDoc<T extends FrappeDoc<object>>(doctype: string, name: string, args?: GetDocArgs<T>): Promise<T>;
/**
* Fetches a value from the Frappe database.
*
* @param doctype - The name of the document type to fetch
* @param fieldname - The name of the field to fetch
* @param args - The arguments for the fetch operation
* @returns A promise that resolves to the value
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* const value = await client.getValue('DocType', 'test')
* ```
*/
getValue<T extends FrappeDoc<object>>(doctype: string, fieldname: string, args?: GetValueArgs): Promise<T>;
/**
* Fetches a single value from the Frappe database.
*
* @param doctype - The name of the document type to fetch
* @param field - The name of the field to fetch
* @returns A promise that resolves to the value
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* const value = await client.getSingleValue('DocType', 'test')
* ```
*/
getSingleValue<T extends FrappeDoc<object>>(doctype: string, field: string): Promise<T>;
/**
* Sets a value in the Frappe database.
*
* @param doctype - The name of the document type to fetch
* @param name - The name of the document to fetch
* @param fieldname - The name of the field to fetch
* @param value - The value to set
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.setValue('DocType', 'test', 'test', 'test')
* ```
*/
setValue<T extends FrappeDoc<object>>(doctype: string, name: string, fieldname: string, value: string): Promise<T>;
/**
* Inserts a document in the Frappe database.
*
* @param doc - The document to insert
* @returns A promise that resolves to the inserted document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.insertDoc({doctype:'DocType', name:'test', fieldname:'test', value:'test'})
* ```
*/
insertDoc<T extends FrappeDoc<object>>(doc: T): Promise<T>;
/**
* Inserts multiple documents in the Frappe database.
*
* @param docs - The documents to insert
* @returns A promise that resolves to the inserted documents
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.insertMany([{doctype:'DocType', name:'test', fieldname:'test', value:'test'}])
* ```
*/
insertMany<T extends FrappeDoc<object>>(docs: T[]): Promise<string[]>;
/**
* Saves a document in the Frappe database.
*
* @param doc - The document to save
* @returns A promise that resolves to the saved document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.saveDoc({doctype:'DocType', name:'test', fieldname:'test', value:'test'})
* ```
*/
saveDoc<T extends FrappeDoc<object>>(doc: T): Promise<T>;
/**
* Renames a document in the Frappe database.
*
* @param doctype - The name of the document type to rename
* @param old_name - The old name of the document
* @param new_name - The new name of the document
* @param merge - Whether to merge the document
* @returns A promise that resolves to the new document name
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* const newName = await client.renameDoc('DocType', 'test', 'test2')
* ```
*/
renameDoc<T extends RenameDocResponse>(doctype: string, old_name: string, new_name: string, merge?: boolean): Promise<T>;
/**
* Submits a document in the Frappe database.
*
* @param doc - The document to submit
* @returns A promise that resolves to the submitted document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.submitDoc({doctype:'DocType', name:'test', fieldname:'test', value:'test'})
* ```
*/
submitDoc<T extends FrappeDoc<object>>(doc: T): Promise<T>;
/**
* Cancels a document in the Frappe database.
*
* @param doctype - The name of the document type to cancel
* @param name - The name of the document to cancel
* @returns A promise that resolves to the canceled document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.cancelDoc('DocType', 'test')
* ```
*/
cancelDoc<T extends FrappeDoc<object>>(doctype: string, name: string): Promise<T>;
/**
* Deletes a document in the Frappe database.
*
* @param doctype - The name of the document type to delete
* @param name - The name of the document to delete
* @returns A promise that resolves to void on successful deletion
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.deleteDoc('DocType', 'test')
* ```
*/
deleteDoc(doctype: string, name: string): Promise<void>;
/**
* Updates multiple documents in the Frappe database.
*
* @param docs - The documents to update
* @returns A promise that resolves to the bulk update result containing any failed documents
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* const result = await client.bulkUpdate([
* {doctype:'DocType', name:'test', fieldname:'test', value:'test'}
* ]);
* if (result.failed_docs.length > 0) {
* console.log('Some documents failed to update:', result.failed_docs);
* }
* ```
*/
bulkUpdate<T extends FrappeDoc<object>>(docs: T[]): Promise<BulkUpdateResponse>;
/**
* Validates a link in the Frappe database.
*
* @param doctype - The name of the document type to validate
* @param docname - The name of the document to validate
* @param fields - The fields to validate
* @returns A promise that resolves to the validated document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.validateLink('DocType', 'test', ['field1', 'field2'])
* ```
*/
validateLink<T extends FrappeDoc<object>>(doctype: string, docname: string, fields?: string[]): Promise<T>;
/**
* Makes a GET request to the Frappe API.
*
* @param path - The path to the API endpoint
* @param params - Optional query parameters
* @returns A promise that resolves to the complete response data
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* // For endpoints returning {message: ...}
* const messageResponse = await client.get('/api/method/some.path');
* console.log(messageResponse.message);
*
* // For endpoints returning {data: ...}
* const dataResponse = await client.get('/api/resource/some.path');
* console.log(dataResponse.data);
* ```
*/
get<T extends TypedResponse<any>>(path: string, params?: ApiParams): Promise<T>;
/**
* Makes a POST request to the Frappe API.
*
* @param path - The path to the API endpoint
* @param data - Optional request body
* @param params - Optional query parameters
* @returns A promise that resolves to the response data
*/
post<T extends TypedResponse<any>>(path: string, data?: ApiData, params?: ApiParams): Promise<T>;
/**
* Makes a PUT request to the Frappe API.
*
* @param path - The path to the API endpoint
* @param data - Optional request body
* @param params - Optional query parameters
* @returns A promise that resolves to the response data
*/
put<T extends TypedResponse<any>>(path: string, data?: ApiData, params?: ApiParams): Promise<T>;
/**
* Makes a DELETE request to the Frappe API.
*
* @param path - The path to the API endpoint
* @param params - Optional query parameters
* @returns A promise that resolves to the response data
*/
delete<T extends TypedResponse<any>>(path: string, params?: ApiParams): Promise<T>;
}