@lasterp/shared 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/node/index.d.ts

@@ -1,7 +1,7 @@
 interface Item {
 	itemCode: string;
 	area: string;
-	modelNumber: string;
+	model: string;
 	region: string;
 	grade: string;
 	gradeIssuer: string;
@@ -14,7 +14,7 @@ interface Item {
 interface ItemVariant extends Item {
 	itemVariant: string;
 }
-interface ModelNumber {
+interface Model {
 	modelNumber: string;
 	simCardType: string;
 	connectivity: string;
@@ -24,20 +24,492 @@ interface Colour {
 	hex: string;
 	colorSystem: string;
 }
+import { FrappeApp, FrappeAuth, FrappeCall } from "frappe-js-sdk";
+import { FrappeDB } from "frappe-js-sdk/lib/db";
+import { FrappeFileUpload } from "frappe-js-sdk/lib/file";
+import { Socket } from "socket.io-client";
+interface FrappeConfig {
+	/** The URL of your Frappe server */
+	url: string;
+	tokenParams?: TokenParams;
+	app: FrappeApp;
+	auth: FrappeAuth;
+	db: FrappeDB;
+	call: FrappeCall;
+	file: FrappeFileUpload;
+	socket?: Socket;
+	enableSocket?: boolean;
+	socketPort?: string;
+}
+interface TokenParams {
+	/** Whether to use token for API calls */
+	useToken: boolean;
+	/** Function that returns the token as a string - this could be fetched from LocalStorage or auth providers like Firebase, Auth0 etc. */
+	token?: () => string;
+	/** Type of token to be used for authentication */
+	type: "Bearer" | "token";
+}
+import { PropsWithChildren } from "react";
+type FrappeProviderProps = PropsWithChildren<{
+	/** URL of the Frappe server
+	*
+	* Only needed if the URL of the window is not the same as the Frappe server URL */
+	url?: string;
+	/** Token parameters to be used for authentication
+	*
+	* Only needed for token based authentication */
+	tokenParams?: TokenParams;
+	/** Flag to disable socket, if needed. This defaults to true. */
+	enableSocket?: boolean;
+	/** Port on which Socket is running. Only meant for local development. Set to undefined on production. */
+	socketPort?: string;
+	/** Get this from frappe.local.site on the server, or frappe.boot.sitename on the window.
+	* Required for Socket connection to work in Frappe v15+
+	*/
+	siteName?: string;
+	/** Custom Headers to be passed in each request */
+	customHeaders?: object;
+}>;
+declare const FrappeContext: React.Context<null | FrappeConfig>;
+declare const FrappeProvider: React.FC<FrappeProviderProps>;
+import { AuthCredentials, AuthResponse } from "frappe-js-sdk/lib/auth/types";
+/**
+* Hook to start listening to user state and provides functions to login/logout
+*
+* @param options - [Optional] SWRConfiguration options for fetching current logged in user
+* @returns Returns an object with the following properties: currentUser, loading, error, and functions to login, logout and updateCurrentUser
+*/
+declare const useFrappeAuth: () => {
+	/** The current logged in user. Will be null/undefined if user is not logged in */
+	currentUser: string | null | undefined;
+	/** Will be true when the hook is fetching user data  */
+	isLoading: boolean;
+	/** Will be true when the hook is fetching (or revalidating) the user state. (Refer to isValidating in useSWR)  */
+	isValidating: boolean;
+	/** Error object returned from API call */
+	error: Error | null | undefined;
+	/** Function to login the user with email and password */
+	login: (credentials: AuthCredentials) => Promise<AuthResponse>;
+	/** Function to log the user out */
+	logout: () => Promise<any>;
+	/** Function to fetch updated user state */
+	updateCurrentUser: () => void;
+	/** Function to get the user cookie and */
+	getUserCookie: () => void;
+};
+/**
+*  Hook to make a GET request to the server
+*
+* @param method - name of the method to call (will be dotted path e.g. "frappe.client.get_list")
+* @param params - parameters to pass to the method
+* @param options - optional query options
+* @param type - type of the request to make - defaults to GET
+*
+* @typeParam T - Type of the data returned by the method
+* @returns an object with the following properties: data, error, isLoading, isFetching, and refetch
+*
+* @example
+*
+* const { data, error, isLoading } = useFrappeGetCall("ping")
+*
+*/
+declare const useFrappeGetCall: <T = any>(method: string, params?: Record<string, any>, options?: {
+	enabled?: boolean;
+	staleTime?: number;
+	retry?: boolean | number;
+}, type?: "GET" | "POST") => {
+	data: T | undefined;
+	error: Error | null;
+	isLoading: boolean;
+	isFetching: boolean;
+	refetch: () => void;
+};
+/**
+*
+* @param method - name of the method to call (POST request) (will be dotted path e.g. "frappe.client.set_value")
+* @returns an object with the following properties: loading, error, isCompleted , result, and call and reset functions
+*
+* @example
+*
+* const { call, result, loading, error, isCompleted, reset } = useFrappePostCall("frappe.client.set_value")
+*
+* const onSubmit = async () => {
+*      const message = await call({ doctype: "User", docname: "test@example.com", fieldname: "full_name", value: "John Doe" })
+* }
+*
+*/
+declare const useFrappePostCall: unknown;
+/**
+*
+* @param method - name of the method to call (PUT request) (will be dotted path e.g. "frappe.client.set_value")
+* @returns an object with the following properties: loading, error, isCompleted , result, and call and reset functions
+*
+* @example
+*
+* const { call, result, loading, error, isCompleted, reset } = useFrappePutCall("frappe.client.set_value")
+*
+* const onSubmit = async () => {
+*      const message = await call({ doctype: "User", docname: "test@example.com", fieldname: "full_name", value: "John Doe" })
+* }
+*/
+declare const useFrappePutCall: unknown;
+/**
+*
+* @param method - name of the method to call (DELETE request) (will be dotted path e.g. "frappe.client.delete")
+* @returns an object with the following properties: loading, error, isCompleted , result, and call and reset functions
+*
+* @example
+*
+* const { call, result, loading, error, isCompleted, reset } = useFrappeDeleteCall("frappe.client.delete")
+*
+* const onSubmit = async () => {
+*      const message = await call({ doctype: "User", docname: "test@example.com" })
+* }
+*/
+declare const useFrappeDeleteCall: unknown;
+import { Filter } from "frappe-js-sdk/lib/db/types";
+/**
+* Hook to fetch number of documents from the database
+*
+*
+* @param doctype - The doctype to fetch
+* @param filters - filters to apply to the query
+* @param debug - Whether to log debug messages or not. Defaults to false
+* @param options [Optional] SWRConfiguration options for fetching data
+* @returns an object (SWRResponse) with the following properties: data (number), error, isValidating, and mutate
+*
+* @example
+*
+* const { data, error, isLoading, mutate } = useFrappeGetDocCount("User")
+*
+*/
+declare const useFrappeGetDocCount: <T = any>(doctype: string, filters?: Filter<T>[], debug?: boolean, options?: {
+	staleTime?: number;
+	retry?: boolean | number;
+}) => {
+	data: number | undefined;
+	error: Error | null;
+	isLoading: boolean;
+	isFetching: boolean;
+	refetch: () => void;
+};
+import { FrappeDoc } from "frappe-js-sdk/lib/db/types";
+/**
+* Hook to create a document in the database and maintain loading and error states
+* @returns Object with the following properties: loading, error, isCompleted and createDoc and reset functions
+*
+* @example
+*
+* const { createDoc, loading, error, isCompleted, reset } = useFrappeCreateDoc()
+*
+* const onSubmit = async () => {
+*      const doc = await createDoc("User", { name: "John Doe", email: "john.doe@example.com" })
+* }
+*/
+declare const useFrappeCreateDoc: <T = any>() => {
+	createDoc: (doctype: string, doc: T) => Promise<FrappeDoc<T>>;
+	loading: boolean;
+	error: Error | null | undefined;
+	isCompleted: boolean;
+	reset: () => void;
+};
+/**
+* Hook to delete a document in the database and maintain loading and error states
+* @returns Object with the following properties: loading, error, isCompleted and deleteDoc and reset functions
+*
+* @example
+*
+* const { deleteDoc, loading, error, isCompleted, reset } = useFrappeDeleteDoc()
+*
+* const onDelete = async () => {
+*      const message = await deleteDoc("User", "test@example.com")
+* }
+*/
+declare const useFrappeDeleteDoc: <T = any>() => {
+	deleteDoc: (doctype: string, docname?: string | null) => Promise<{
+		message: string;
+	}>;
+	loading: boolean;
+	error: Error | null | undefined;
+	isCompleted: boolean;
+	reset: () => void;
+};
+/** useFrappeEventListener hook for listening to events from the server
+* @param eventName - name of the event to listen to
+* @param callback - callback function to be called when the event is triggered. The callback function will receive the data sent from the server. It is recommended to memoize this function.
+*
+* @example
+* ```typescript
+* useFrappeEventListener('my_event', (data) => {
+*     // do something with the data
+*      if(data.status === 'success') {
+*          console.log('success')
+*      }
+* })
+* ```
+*/
+declare const useFrappeEventListener: <T = any>(eventName: string, callback: (eventData: T) => void) => void;
+interface ViewerEventData {
+	doctype: string;
+	docname: string;
+	users: string[];
+}
+interface DocumentUpdateEventData {
+	doctype: string;
+	name: string;
+	modified: string;
+}
+/**
+* Hook for listening to document events.
+* The hook will automatically subscribe to the document room, and unsubscribe when the component unmounts.
+* The hook listens to the following events:
+* - doc_update: This is triggered when the document is updated. The callback function will receive the updated document.
+* - doc_viewers: This is triggered when the list of viewers of the document changes. The hook will update the viewers state with the list of viewers.
+*
+* @param doctype Name of the doctype
+* @param docname Name of the document
+* @param emitOpenCloseEventsOnMount [Optional] If true, the hook will emit doc_open and doc_close events on mount and unmount respectively. Defaults to true.
+* @param onUpdateCallback Function to be called when the document is updated. It is recommended to memoize this function.
+* @returns viewers - array of userID's, emitDocOpen - function to emit doc_open event, emitDocClose - function to emit doc_close event
+*/
+declare const useFrappeDocumentEventListener: (doctype: string, docname: string, onUpdateCallback: (eventData: DocumentUpdateEventData) => void, emitOpenCloseEventsOnMount?: boolean) => {
+	viewers: string[];
+	emitDocOpen: () => void;
+	emitDocClose: () => void;
+};
+interface DocTypeListUpdateEventData {
+	doctype: string;
+	name: string;
+	user: string;
+}
+/**
+* Hook for listening to doctype events.
+* The hook will automatically subscribe to the doctype room, and unsubscribe when the component unmounts.
+* The hook listens to the following event:
+* - list_update: This is triggered when a document of the doctype is updated (created, modified or deleted). The callback function will receive the updated document.
+*
+* @param doctype Name of the doctype
+* @param onListUpdateCallback Function to be called when the document is updated. It is recommended to memoize this function.
+*/
+declare const useFrappeDocTypeEventListener: (doctype: string, onListUpdateCallback: (eventData: DocTypeListUpdateEventData) => void) => void;
+import { FileArgs } from "frappe-js-sdk/lib/file/types";
+interface FrappeFileUploadResponse {
+	/** Name of the file document in the database */
+	name: string;
+	owner: string;
+	creation: string;
+	modified: string;
+	modified_by: string;
+	docstatus: 0 | 1 | 2;
+	idx: number;
+	/** Name of the uploaded file */
+	file_name: string;
+	/** File is not accessible by guest users */
+	is_private: 1 | 0;
+	is_home_folder: 0 | 1;
+	is_attachments_folder: 0 | 1;
+	/** File size in bytes */
+	file_size: number;
+	/** Path of the file ex: /private/files/file_name.jpg  */
+	file_url: string;
+	folder: string;
+	is_folder: 0 | 1;
+	/** Doctype the file is linked to */
+	attached_to_doctype: string;
+	/** Document the file is linked to */
+	attached_to_name: string;
+	content_hash: string;
+	uploaded_to_dropbox: 0 | 1;
+	uploaded_to_google_drive: 0 | 1;
+	doctype: "File";
+}
+interface UseFrappeFileUploadReturnType<T = any> {
+	/** Function to upload the file */
+	upload: (file: File, args: FileArgs<T>, apiPath?: string) => Promise<FrappeFileUploadResponse>;
+	/** Upload Progress in % - rounded off */
+	progress: number;
+	/** Will be true when the file is being uploaded  */
+	loading: boolean;
+	/** Error object returned from API call */
+	error: Error | null;
+	/** Will be true if file upload is successful. Else false */
+	isCompleted: boolean;
+	/** Function to reset the state of the hook */
+	reset: () => void;
+}
+/**
+* Hook to upload files to the server
+*
+* @returns an object with the following properties: loading, error, isCompleted , result, and call and reset functions
+*
+* @example
+*
+* const { upload, progress, loading, error, isCompleted, reset } = useFrappeFileUpload()
+*
+* const onSubmit = async () => {
+*      const message = await upload(myFile, { doctype: "User", docname: "test@example.com", fieldname: "profile_pic", is_private: 1 })
+* }
+*/
+declare const useFrappeFileUpload: <T = any>() => UseFrappeFileUploadReturnType<T>;
+import { FrappeDoc as FrappeDoc2 } from "frappe-js-sdk/lib/db/types";
+/**
+* Hook to fetch a document from the database
+*
+*
+* @param doctype - The doctype to fetch
+* @param name - the name of the document to fetch
+* @param options [Optional] SWRConfiguration options for fetching data
+* @returns an object (SWRResponse) with the following properties: data, error, isValidating, and mutate
+*
+* @typeParam T - The type of the document
+*
+* @example
+*
+* const { data, error, isLoading, mutate } = useFrappeGetDoc("User", "test")
+*
+* if (isLoading) {
+*      return <div>Loading...</div>
+* }
+*
+* if (error) {
+*      return <div>Error: {error.message}</div>
+* }
+*
+* return <div>{data?.name} - {data?.email}</div>
+*/
+declare const useFrappeGetDoc: <T = any>(doctype: string, name?: string, options?: {
+	staleTime?: number;
+	retry?: boolean | number;
+}) => {
+	data: FrappeDoc2<T> | undefined;
+	error: Error | null;
+	isLoading: boolean;
+	isFetching: boolean;
+	refetch: () => void;
+};
+import { FrappeDoc as FrappeDoc3, GetDocListArgs } from "frappe-js-sdk/lib/db/types";
+/**
+* Hook to fetch a list of documents from the database
+*
+* @param doctype Name of the doctype to fetch
+* @param args Arguments to pass (filters, pagination, etc)
+* @param options [Optional] SWRConfiguration options for fetching data
+* @returns an object (SWRResponse) with the following properties: data, error, isValidating, and mutate
+*
+* @typeParam T - The type definition of the document object
+*
+* @example
+*
+* const { data, error, isLoading, mutate } = useFrappeGetDocList("User")
+*
+* if (isLoading) {
+*      return <div>Loading...</div>
+* }
+*
+* if (error) {
+*      return <div>Error: {error.message}</div>
+* }
+*
+* return <ul>{data?.map((user) => <li key={user.name}>{user.name}</li>)}</ul>
+*
+*/
+declare const useFrappeGetDocList: <
+	T = any,
+	K = FrappeDoc3<T>
+>(doctype: string, args?: GetDocListArgs<K>, options?: {
+	staleTime?: number;
+	retry?: boolean | number;
+}) => {
+	data: T[] | undefined;
+	error: Error | null;
+	isLoading: boolean;
+	isFetching: boolean;
+	refetch: () => void;
+};
+/**
+* Hook to prefetch a document from the database
+* @param doctype - The doctype to fetch
+* @param name - The name of the document to fetch
+* @param swrKey - The SWRKey to use for caching the result - optional
+* @param options - The SWRConfiguration options for fetching data
+* @returns A function to prefetch the document
+*
+* @example
+*
+* const preloadDoc = useFrappePrefetchDoc("User", "test@example.com")
+*
+* // Call the function when you want to prefetch the document
+* const onHover = () => {
+*      preloadDoc()
+* }
+*/
+declare const useFrappePrefetchDoc: <T = any>(doctype: string, name?: string, options?: {
+	staleTime?: number;
+}) => (() => void);
+import { Filter as Filter2 } from "frappe-js-sdk/lib/db/types";
+interface SearchResult {
+	value: string;
+	label: string;
+	description: string;
+}
+/**
+* Hook to search for documents - only works with Frappe v15+
+*
+* @param doctype - name of the doctype (table) where we are performing our search
+* @param text - search text
+* @param filters - (optional) the results will be filtered based on these
+* @param limit - (optional) the number of results to return. Defaults to 20
+* @param debounce - (optional) the number of milliseconds to wait before making the API call. Defaults to 250ms.
+* @returns result - array of type SearchResult with a list of suggestions based on search text
+*
+* @example
+*
+* const [searchText, setSearchText] = useState("")
+* const { data, error, isLoading, mutate } = useSearch("User", searchText)
+*/
+declare const useSearch: (doctype: string, text: string, filters?: Filter2[], limit?: number, debounce?: number) => {
+	data: {
+		message: SearchResult[];
+	} | undefined;
+	error: Error | null;
+	isLoading: boolean;
+	isFetching: boolean;
+	refetch: () => void;
+};
+import { FrappeDoc as FrappeDoc4 } from "frappe-js-sdk/lib/db/types";
+/**
+* Hook to update a document in the database and maintain loading and error states
+* @returns Object with the following properties: loading, error, isCompleted and updateDoc and reset functions
+*
+* @example
+*
+* const { updateDoc, loading, error, isCompleted, reset } = useFrappeUpdateDoc()
+*
+* const onSubmit = async () => {
+*      const doc = await updateDoc("User", "test@example.com", { name: "John Doe", email: "john.doe@example.com" })
+* }
+*/
+declare const useFrappeUpdateDoc: <T = any>() => {
+	updateDoc: (doctype: string, docname: string | null, doc: Partial<T>) => Promise<FrappeDoc4<T>>;
+	loading: boolean;
+	error: Error | null | undefined;
+	isCompleted: boolean;
+	reset: () => void;
+};
 interface Globals {
 	header: Header;
 	footer: Footer;
 }
 interface Brand {
-	brandImage: string;
+	brandImage?: string;
 }
 interface NavbarItem {
 	label: string;
 	enableDropdown: boolean;
 	enableLink: boolean;
-	link: string;
-	dropdownDescription: string;
-	groups: NavbarSubItemGroup[];
+	link?: string;
+	dropdownDescription?: string;
+	groups?: NavbarSubItemGroup[];
 }
 interface NavbarSubItemGroup {
 	title: string;
@@ -45,22 +517,22 @@ interface NavbarSubItemGroup {
 }
 interface NavbarSubItem {
 	label: string;
-	description: string;
-	image: string;
-	link: string;
+	description?: string;
+	image?: string;
+	link?: string;
 }
 interface Topbar {
 	topbarEnabled: boolean;
 	items: TopbarItem[];
 }
 interface TopbarItem {
-	icon: string;
+	icon?: string;
 	label: string;
-	link: string;
+	link?: string;
 }
 interface Header {
 	brand: Brand;
-	headerType: string;
+	headerType?: string;
 	tabs: NavbarItem[];
 	topbar: Topbar;
 }
@@ -70,16 +542,16 @@ interface FooterItemGroup {
 }
 interface FooterItem {
 	label: string;
-	link: string;
+	link?: string;
 }
 interface Footer {
-	footerType: string;
+	footerType?: string;
 	groups: FooterItemGroup[];
-	copyright: string;
-	address: string;
-	country: string;
-	phone: string;
-	email: string;
+	copyright?: string;
+	address?: string;
+	country?: string;
+	phone?: string;
+	email?: string;
 }
 interface Hero {
 	type: string;
@@ -91,8 +563,9 @@ interface Block {
 }
 interface Page {
 	slug: string;
-	hero: Hero;
+	hero?: Hero;
 	blocks: Block[];
 }
+import { camelize, decamelize, camelizeKeys, decamelizeKeys } from "humps";
 declare function equalsIgnoreCase(str1: string, str2: string): boolean;
-export { equalsIgnoreCase, TopbarItem, Topbar, Page, NavbarSubItemGroup, NavbarSubItem, NavbarItem, ModelNumber, ItemVariant, Item, Hero, Header, Globals, FooterItemGroup, FooterItem, Footer, Colour, Brand, Block };
+export { useSearch, useFrappeUpdateDoc, useFrappePutCall, useFrappePrefetchDoc, useFrappePostCall, useFrappeGetDocList, useFrappeGetDocCount, useFrappeGetDoc, useFrappeGetCall, useFrappeFileUpload, useFrappeEventListener, useFrappeDocumentEventListener, useFrappeDocTypeEventListener, useFrappeDeleteDoc, useFrappeDeleteCall, useFrappeCreateDoc, useFrappeAuth, equalsIgnoreCase, decamelizeKeys, decamelize, camelizeKeys, camelize, ViewerEventData, UseFrappeFileUploadReturnType, TopbarItem, Topbar, TokenParams, SearchResult, Page, NavbarSubItemGroup, NavbarSubItem, NavbarItem, Model, ItemVariant, Item, Hero, Header, Globals, FrappeProviderProps, FrappeProvider, FrappeFileUploadResponse, FrappeContext, FrappeConfig, FooterItemGroup, FooterItem, Footer, DocumentUpdateEventData, DocTypeListUpdateEventData, Colour, Brand, Block };