@janiscommerce/app-tracking-shift

A React Native library for managing work shifts and work logs in Janis Commerce applications. This package provides comprehensive shift tracking functionality with offline support and seamless integration with the Staff MS (Microservice).

Features

• 🕒 Shift Management: Open, close, and manage work shifts
• 📝 Work Log Tracking: Track work activities with start/end times
• 📱 Offline Support: Continue working even without internet connection
• 🔄 Automatic Sync: Sync pending work logs when connection is restored
• 🎯 React Context Integration: Easy state management with React Context
• 🛡️ Authorization Control: Built-in staff authorization validation
• ⚡ Performance Optimized: Uses MMKV for fast local storage
• 🔧 Error Handling: Comprehensive error reporting with Crashlytics integration

Installation

npm install @janiscommerce/app-tracking-shift

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install @janiscommerce/app-crashlytics@>=2.1.0
npm install @janiscommerce/app-request@>=2.0.0
npm install react@>=17.0.2
npm install react-native@>=0.67.5

Quick Start

1. Provider Setup

Wrap your app with the ShiftTrackingProvider:

import React from 'react';
import {ShiftTrackingProvider} from '@janiscommerce/app-tracking-shift';

const App = () => {
	return (
		<ShiftTrackingProvider onError={(error) => console.error(error)}>
			{/* Your app components */}
		</ShiftTrackingProvider>
	);
};

export default App;

2. Using the Hook

Access shift data and methods using the useShiftTracking hook:

import React from 'react';
import {useShiftTracking} from '@janiscommerce/app-tracking-shift';

const MyComponent = () => {
	const {
		shiftId,
		shiftStatus,
		shiftData,
		workLogTypes,
		currentWorkLogData,
		hasStaffAuthorization,
		isShiftLoading,
		error,
	} = useShiftTracking();

	return (
		<div>
			<p>Shift Status: {shiftStatus}</p>
			<p>Shift ID: {shiftId}</p>
			{/* Your component logic */}
		</div>
	);
};

3. Managing Shifts

Use the Shift class for shift operations:

import {Shift} from '@janiscommerce/app-tracking-shift';

// Open a shift
const handleOpenShift = async () => {
	try {
		const shiftId = await Shift.open();
		console.log('Shift opened:', shiftId);
	} catch (error) {
		console.error('Error opening shift:', error);
	}
};

// Close a shift
const handleCloseShift = async () => {
	try {
		const shiftId = await Shift.finish();
		console.log('Shift closed:', shiftId);
	} catch (error) {
		console.error('Error closing shift:', error);
	}
};

4. Work Log Management

// Open a work log
const handleOpenWorkLog = async () => {
	const workLog = {
		referenceId: 'task-123',
		name: 'Customer Service',
		type: 'work',
		suggestedTime: 30, // minutes
	};

	try {
		const workLogId = await Shift.openWorkLog(workLog);
		console.log('Work log opened:', workLogId);
	} catch (error) {
		console.error('Error opening work log:', error);
	}
};

// Finish a work log
const handleFinishWorkLog = async () => {
	const workLog = {
		referenceId: 'task-123',
	};

	try {
		const workLogId = await Shift.finishWorkLog(workLog);
		console.log('Work log finished:', workLogId);
	} catch (error) {
		console.error('Error finishing work log:', error);
	}
};

API Reference

ShiftTrackingProvider

The main provider component that manages shift state and initialization.

Props:

• children (ReactNode): Child components
• onError (function, optional): Error callback function

useShiftTracking Hook

Returns the current shift tracking state and data.

Returns:

• shiftId (string): Current shift ID
• shiftStatus (string): Current shift status ('opened', 'closed', 'paused')
• shiftData (object): Complete shift data
• workLogTypes (array): Available work log types
• currentWorkLogData (object): Current active work log data
• currentWorkLogId (string): Current work log ID
• hasStaffAuthorization (boolean): Staff authorization status
• isShiftLoading (boolean): Loading state
• error (object): Current error state

Shift Class

Main class for shift and work log operations.

Methods

open()

• Opens a new work shift
• Returns: Promise<string> - Shift ID

finish(params?)

• Closes the current shift
• Parameters: { date?: string } - Optional closing date
• Returns: Promise<string> - Shift ID

openWorkLog(workLog)

• Opens a new work log
• Parameters: { referenceId, name, type, suggestedTime? }
• Returns: Promise<string> - Work log ID

finishWorkLog(workLog)

• Finishes the current work log
• Parameters: { referenceId }
• Returns: Promise<string> - Work log ID

getWorkLogs(shiftId?)

• Gets work logs for a shift
• Parameters: shiftId (optional) - Shift ID
• Returns: Promise<Array> - Array of work logs

fetchWorklogTypes()

• Fetches available work log types
• Returns: Promise<Array> - Array of work log types

sendPendingWorkLogs()

• Sends pending offline work logs
• Returns: Promise<null>

deleteShiftRegisters()

• Deletes all shift-related data
• Returns: Promise<boolean>

Properties

hasStaffAuthorization (getter)

• Returns: boolean - Staff authorization status

hasPendingData (getter)

• Returns: boolean - Pending offline data status

WithShiftTracking HOC

Higher-order component that provides shift tracking data to wrapped components.

import {WithShiftTracking} from '@janiscommerce/app-tracking-shift';

const MyComponent = ({shiftData}) => {
	// Component logic
};

export default WithShiftTracking(MyComponent, {
	pausedShiftComponent: <PausedShiftNotification />,
});

Internal Work Logs

The package provides predefined internal work logs:

import {INTERNAL_WORKLOGS} from '@janiscommerce/app-tracking-shift';

// Available internal work logs:
// INTERNAL_WORKLOGS.PICKING_WORK
// INTERNAL_WORKLOGS.DELIVERY_WORK

Offline Support

The library automatically handles offline scenarios:

1. Offline Storage: Work logs are stored locally when offline
2. Automatic Sync: Pending work logs are automatically synced when connection is restored
3. Data Persistence: Uses MMKV for fast and reliable local storage
4. Error Recovery: Graceful error handling for network issues

Error Handling

All errors are standardized and include:

• Descriptive error messages
• Error types for categorization
• Automatic Crashlytics reporting
• Promise rejection for proper error handling

Storage Keys

The library uses the following storage keys (managed automatically):

• shift.id - Current shift ID
• shift.status - Current shift status
• shift.data - Complete shift data
• worklog.id - Current work log ID
• worklog.data - Current work log data
• worklogTypes.data - Work log types cache
• staff.authorization - Staff authorization data
• offline.data - Offline work logs

Contributing

This package is maintained by Janis Commerce. For issues and feature requests, please use the GitHub Issues.