The library provides built-in type support. You can pass a generic type to methods like updateDoc<T> to enforce schema.

Additionally, all document responses are returned as an intersection of the specified type and the FrappeDoc<T> type, which includes standard Frappe fields:

• name: Primary key
• owner: Creator
• creation: ISO timestamp
• modified: ISO timestamp
• modified_by: Last modifier
• docstatus: 0 (Saved), 1 (Submitted), 2 (Cancelled)
• idx: Index

interface TestDoc {
  test_field: string;
}

// Enforcing types on database calls
db.updateDoc<TestDoc>('My Custom DocType', 'Test', {
  test_field: 'This is an updated test field.',
});

Install the library using npm or yarn to use it in your TypeScript/JavaScript project.

npm install frappe-js-sdk

or

yarn add frappe-js-sdk

The SDK is organized into several functional modules that are all exported from the main entry point. You can access these directly via the FrappeApp instance or by importing the specific modules if they are exported separately:

• Authentication: Manage user sessions and login/logout.
• Database: Perform CRUD operations on DocTypes.
• File: Handle file uploads and management.
• Call: Execute RPC calls to server-side functions.

To use the library, create an instance of FrappeApp with your Frappe backend URL.

For standard cookie-based authentication, pass only the URL. For token-based authentication (OAuth bearer tokens or API key/secret pairs), provide an options object with useToken: true, a token function that returns the token string, and the type (either "Bearer" or "token").

import { FrappeApp } from 'frappe-js-sdk';

// Standard initialization
const frappe = new FrappeApp('https://test.frappe.cloud');

// Token-based initialization
const frappe = new FrappeApp("https://test.frappe.cloud", {
    useToken: true,
    token: getTokenFromLocalStorage(),
    type: "Bearer"
});

Use frappe.call() to interact with whitelisted (@frappe.whitelist()) backend methods. Supported HTTP methods include:

• get(method, params)
• post(method, params)
• put(method, params)
• delete(method, params)

const call = frappe.call();

// GET request
call.get('frappe.desk.search_link', { doctype: 'Currency', txt: 'IN' });

// POST request
call.post('frappe.client.set_value', { doctype: 'User', name: 'Administrator', fieldname: 'interest', value: 'Frappe' });

// PUT request
call.put('frappe.client.set_value', { doctype: 'User', name: 'Administrator', fieldname: 'interest', value: 'Frappe' });

// DELETE request
call.delete('frappe.client.delete', { doctype: 'Tag', name: 'Random Tag' });

Access authentication methods via frappe.auth(). Supported operations include:

• loginWithUsernamePassword({ username, password }): Logs in a user via /api/method/login.
• getLoggedInUser(): Retrieves the currently logged-in user via /api/method/frappe.auth.get_logged_user.
• logout(): Logs out the user via /api/method/logout.
• forgetPassword(email): Sends a password reset link to the specified email.

const auth = frappe.auth();

// Login
auth.loginWithUsernamePassword({ username: 'admin', password: 'my-password' })
  .then(() => console.log('Logged in'));

// Get User
auth.getLoggedInUser()
  .then((user) => console.log(`User ${user} is logged in.`));

// Logout
auth.logout()
  .then(() => console.log('Logged out.'));

// Forget Password
auth.forgetPassword('example@example.com')
  .then(() => console.log('Password Reset Email Sent!'));

The setValue method allows you to update a specific field on a document without sending the entire document object.

setValue<T>(doctype: string, name: string, fieldname: string | object, value?: any): Promise<FrappeDoc<T>>

• If fieldname is a string, value is the new value.
• If fieldname is an object (mapping fields to values), the value parameter is ignored.

// Set a single field
await db.setValue('Task', 'TASK-001', 'status', 'Completed');

// Set multiple fields via an object
await db.setValue('Task', 'TASK-001', { status: 'Completed', priority: 'High' });

After initializing FrappeApp, use its methods to obtain instances of the core functional modules. Each module shares the same underlying configuration (URL, Axios instance, and authentication settings) provided during initialization.

• app.auth(): Returns a FrappeAuth instance for managing authentication.
• app.db(): Returns a FrappeDB instance for database operations.
• app.file(): Returns a FrappeFileUpload instance for handling file uploads.
• app.call(): Returns a FrappeCall instance for executing Frappe method calls.

const app = new FrappeApp('https://your-frappe-site.com');

const auth = app.auth();
const db = app.db();
const file = app.file();
const call = app.call();