frappe-js-client
Version:
Next-generation TS/JS client for Frappe REST APIs, built on axios for robust, type-safe integration.
268 lines (267 loc) • 10.3 kB
TypeScript
import { AxiosInstance } from 'axios';
import { GetCountArgs, GetDocArgs, GetListArgs, GetValueArgs } from './types';
import { FrappeDoc } from '../db/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 = object, K = FrappeDoc<T>>(doctype: string, args?: GetListArgs<K>): 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(doctype: string, args?: GetCountArgs): Promise<number>;
/**
* 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 = 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 = object>(doctype: string, fieldname: string, args?: GetValueArgs<T>): 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 = 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 = 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 = object>(doc: object): 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 = object>(docs: object[]): Promise<T[]>;
/**
* 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 = object>(doc: object): 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 renamed document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.renameDoc('DocType', 'test', 'test2')
* ```
*/
renameDoc<T = object>(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 = object>(doc: object): 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 = 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 the deleted document
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.deleteDoc('DocType', 'test')
* ```
*/
deleteDoc<T = object>(doctype: string, name: string): Promise<T>;
/**
* Updates multiple documents in the Frappe database.
*
* @param docs - The documents to update
* @returns A promise that resolves to the updated documents
*
* @example
* ```typescript
* const client = new FrappeClient('https://instance.example.com', axiosInstance)
* await client.bulkUpdate([{doctype:'DocType', name:'test', fieldname:'test', value:'test'}])
* ```
*/
bulkUpdate<T = object>(docs: object[]): 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 response data
*/
get<T = any>(path: string, params?: object): 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 = any>(path: string, data?: object, params?: object): Promise<Record<string, 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 = any>(path: string, data?: object, params?: object): Promise<Record<string, 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 = any>(path: string, params?: object): Promise<Record<string, T>>;
}