@cccsaurora/howler-ui 2.18.0 → 2.19.0-cases.1040

package/components/routes/cases/search/CaseAssigneeFilter.test.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/// <reference types="vitest" />
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent, {} from '@testing-library/user-event';
+import { UserListContext } from '@cccsaurora/howler-ui/components/app/providers/UserListProvider';
+import i18n from '@cccsaurora/howler-ui/i18n';
+import { I18nextProvider } from 'react-i18next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import CaseAssigneeFilter from './CaseAssigneeFilter';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+// ---------------------------------------------------------------------------
+// Hoisted mocks
+// ---------------------------------------------------------------------------
+vi.mock('commons/components/app/hooks/useAppUser', () => ({
+    useAppUser: () => ({ user: { username: 'alice', name: 'Alice Smith' } })
+}));
+// Stub HowlerAvatar to avoid avatar API calls
+vi.mock('components/elements/display/HowlerAvatar', () => ({
+    default: ({ userId }) => _jsx("div", { id: `avatar-${userId}`, children: userId })
+}));
+// Stub UserList to a simple multi-select so we can test the onChange wire-up
+// without pulling in the full component and its popover.
+vi.mock('components/elements/UserList', () => ({
+    default: ({ userIds, onChange, multiple }) => (_jsxs("div", { id: "user-list", children: [_jsx("button", { id: "user-list-add", onClick: () => onChange([...userIds, 'bob']), children: "Add bob" }), multiple &&
+                userIds.map(id => (_jsxs("button", { id: `remove-${id}`, onClick: () => onChange(userIds.filter(u => u !== id)), children: ["Remove ", id] }, id)))] }))
+}));
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const mockSearchUsers = vi.fn();
+const USERS = {
+    alice: { username: 'alice', name: 'Alice Smith' },
+    bob: { username: 'bob', name: 'Bob Jones' }
+};
+const Wrapper = ({ children }) => (_jsx(I18nextProvider, { i18n: i18n, children: _jsx(UserListContext.Provider, { value: { users: USERS, searchUsers: mockSearchUsers, fetchUsers: vi.fn() }, children: children }) }));
+const renderFilter = (assigneeFilter, onChange = vi.fn()) => render(_jsx(CaseAssigneeFilter, { assigneeFilter: assigneeFilter, onChange: onChange }), { wrapper: Wrapper });
+const openPopper = async (user, labelText) => {
+    const chip = screen.getByText(labelText).closest('.MuiChip-root');
+    await user.click(chip);
+    await waitFor(() => {
+        expect(screen.getByTestId('user-list')).toBeInTheDocument();
+    });
+};
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('CaseAssigneeFilter', () => {
+    let user;
+    beforeEach(() => {
+        user = userEvent.setup();
+        vi.clearAllMocks();
+    });
+    describe('searchUsers on mount', () => {
+        it('calls searchUsers with "uname:*" on mount', () => {
+            renderFilter([]);
+            expect(mockSearchUsers).toHaveBeenCalledWith('uname:*');
+        });
+    });
+    describe('label', () => {
+        it('shows the default "Assignee" label when no assignees are selected', () => {
+            renderFilter([]);
+            expect(screen.getByText(i18n.t('route.cases.filter.assignee'))).toBeInTheDocument();
+        });
+        it('shows the user display name when one assignee is selected', () => {
+            renderFilter(['alice']);
+            expect(screen.getByText('Alice Smith')).toBeInTheDocument();
+        });
+        it('shows count + "Assignees" when multiple assignees are selected', () => {
+            renderFilter(['alice', 'bob']);
+            expect(screen.getByText(`2 ${i18n.t('route.cases.filter.assignees')}`)).toBeInTheDocument();
+        });
+        it('falls back to username when user is not in the user map', () => {
+            renderFilter(['unknown-user']);
+            const chipLabel = document.querySelector('.MuiChip-label');
+            expect(chipLabel?.textContent).toContain('unknown-user');
+        });
+    });
+    describe('chip color', () => {
+        it('uses default color when no assignees are selected', () => {
+            renderFilter([]);
+            const chip = screen.getByText(i18n.t('route.cases.filter.assignee')).closest('.MuiChip-root');
+            expect(chip).not.toHaveClass('MuiChip-colorPrimary');
+        });
+        it('uses primary color when assignees are selected', () => {
+            renderFilter(['alice']);
+            const chip = screen.getByText('Alice Smith').closest('.MuiChip-root');
+            expect(chip).toHaveClass('MuiChip-colorPrimary');
+        });
+    });
+    describe('"Myself" checkbox', () => {
+        it('is unchecked when the current user is not in the filter', async () => {
+            renderFilter([]);
+            await openPopper(user, i18n.t('route.cases.filter.assignee'));
+            const checkbox = screen.getByRole('checkbox', { name: i18n.t('route.cases.filter.myself') });
+            expect(checkbox).not.toBeChecked();
+        });
+        it('is checked when the current user is already in the filter', async () => {
+            renderFilter(['alice']);
+            await openPopper(user, 'Alice Smith');
+            const checkbox = screen.getByRole('checkbox', { name: i18n.t('route.cases.filter.myself') });
+            expect(checkbox).toBeChecked();
+        });
+        it('adds the current user to the filter when the checkbox is checked', async () => {
+            const onChange = vi.fn();
+            renderFilter([], onChange);
+            await openPopper(user, i18n.t('route.cases.filter.assignee'));
+            await user.click(screen.getByRole('checkbox', { name: i18n.t('route.cases.filter.myself') }));
+            expect(onChange).toHaveBeenCalledWith(['alice']);
+        });
+        it('removes the current user from the filter when the checkbox is unchecked', async () => {
+            const onChange = vi.fn();
+            renderFilter(['alice', 'bob'], onChange);
+            await openPopper(user, `2 ${i18n.t('route.cases.filter.assignees')}`);
+            await user.click(screen.getByRole('checkbox', { name: i18n.t('route.cases.filter.myself') }));
+            expect(onChange).toHaveBeenCalledWith(['bob']);
+        });
+    });
+    describe('UserList onChange passthrough', () => {
+        it('passes onChange directly to UserList', async () => {
+            const onChange = vi.fn();
+            renderFilter(['alice'], onChange);
+            await openPopper(user, 'Alice Smith');
+            await user.click(screen.getByTestId('user-list-add'));
+            expect(onChange).toHaveBeenCalledWith(['alice', 'bob']);
+        });
+    });
+});

package/components/routes/cases/search/CaseDateFilter.d.ts

@@ -0,0 +1,13 @@
+import type { Dayjs } from 'dayjs';
+import type { FC } from 'react';
+import { DATE_RANGES } from '@cccsaurora/howler-ui/utils/constants';
+export type DateRangeOption = (typeof DATE_RANGES)[number];
+declare const CaseDateFilter: FC<{
+    dateRange: DateRangeOption;
+    onChange: (v: DateRangeOption) => void;
+    customStart: Dayjs;
+    customEnd: Dayjs;
+    onCustomStartChange: (v: Dayjs) => void;
+    onCustomEndChange: (v: Dayjs) => void;
+}>;
+export default CaseDateFilter;

package/components/routes/cases/search/CaseDateFilter.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { AvTimer } from '@mui/icons-material';
+import { Autocomplete, Stack, TextField, Typography } from '@mui/material';
+import { LocalizationProvider } from '@mui/x-date-pickers';
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs';
+import { DateTimePicker } from '@mui/x-date-pickers/DateTimePicker';
+import ChipPopper from '@cccsaurora/howler-ui/components/elements/display/ChipPopper';
+import { useTranslation } from 'react-i18next';
+import { DATE_RANGES } from '@cccsaurora/howler-ui/utils/constants';
+const CaseDateFilter = ({ dateRange, onChange, customStart, customEnd, onCustomStartChange, onCustomEndChange }) => {
+    const { t } = useTranslation();
+    return (_jsx(ChipPopper, { icon: _jsx(AvTimer, { fontSize: "small" }), label: _jsx(Typography, { variant: "body2", children: dateRange === 'date.range.all'
+                ? t('route.cases.filter.date')
+                : dateRange === 'date.range.custom'
+                    ? `${customStart.format('YYYY-MM-DD')} ${t('to')} ${customEnd.format('YYYY-MM-DD')}`
+                    : t(dateRange) }), minWidth: "225px", slotProps: { chip: { size: 'small', color: dateRange !== 'date.range.all' ? 'primary' : 'default' } }, children: _jsxs(Stack, { spacing: 1, children: [_jsx(Autocomplete, { size: "small", value: dateRange, options: [...DATE_RANGES], getOptionLabel: o => t(o), disableClearable: true, onChange: (_, nv) => onChange(nv), renderInput: params => _jsx(TextField, { ...params, label: t('route.cases.filter.date') }) }), dateRange === 'date.range.custom' && (_jsx(LocalizationProvider, { dateAdapter: AdapterDayjs, children: _jsxs(Stack, { direction: "row", spacing: 1, useFlexGap: true, flexWrap: "wrap", children: [_jsx(DateTimePicker, { sx: { minWidth: '175px', flexGrow: 1 }, slotProps: { textField: { size: 'small' } }, label: t('date.select.start'), value: customStart, maxDate: customEnd, onChange: nv => {
+                                    if (nv) {
+                                        onCustomStartChange(nv);
+                                    }
+                                }, ampm: false, disableFuture: true }), _jsx(DateTimePicker, { sx: { minWidth: '175px', flexGrow: 1 }, slotProps: { textField: { size: 'small' } }, label: t('date.select.end'), value: customEnd, minDate: customStart, onChange: nv => {
+                                    if (nv) {
+                                        onCustomEndChange(nv);
+                                    }
+                                }, ampm: false, disableFuture: true })] }) }))] }) }));
+};
+export default CaseDateFilter;

package/components/routes/cases/search/CaseDateFilter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/routes/cases/search/CaseDateFilter.test.js

@@ -0,0 +1,115 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/// <reference types="vitest" />
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent, {} from '@testing-library/user-event';
+import dayjs from 'dayjs';
+import i18n from '@cccsaurora/howler-ui/i18n';
+import { I18nextProvider } from 'react-i18next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import CaseDateFilter from './CaseDateFilter';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+// ---------------------------------------------------------------------------
+// Stub the date pickers so jsdom doesn't choke on them
+// ---------------------------------------------------------------------------
+vi.mock('@mui/x-date-pickers/DateTimePicker', () => ({
+    DateTimePicker: ({ label, onChange }) => (_jsx("button", { id: `picker-${label}`, onClick: () => onChange(dayjs('2025-06-01')), children: label }))
+}));
+// ---------------------------------------------------------------------------
+// Wrapper / render helper
+// ---------------------------------------------------------------------------
+const FIXED_START = dayjs('2025-01-01');
+const FIXED_END = dayjs('2025-03-01');
+const Wrapper = ({ children }) => _jsx(I18nextProvider, { i18n: i18n, children: children });
+const renderFilter = ({ dateRange = 'date.range.all', onChange = vi.fn(), onCustomStartChange = vi.fn(), onCustomEndChange = vi.fn() } = {}) => render(_jsx(CaseDateFilter, { dateRange: dateRange, onChange: onChange, customStart: FIXED_START, customEnd: FIXED_END, onCustomStartChange: onCustomStartChange, onCustomEndChange: onCustomEndChange }), { wrapper: Wrapper });
+const openPopper = async (user) => {
+    // The chip label varies; find the chip by the AvTimer icon's sibling
+    const chip = document.querySelector('.MuiChip-root');
+    await user.click(chip);
+    await waitFor(() => {
+        expect(screen.getByRole('combobox')).toBeInTheDocument();
+    });
+};
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('CaseDateFilter', () => {
+    let user;
+    beforeEach(() => {
+        user = userEvent.setup();
+        vi.clearAllMocks();
+    });
+    describe('label', () => {
+        it('shows "Date Range" label when date.range.all is selected', () => {
+            renderFilter({ dateRange: 'date.range.all' });
+            expect(screen.getByText(i18n.t('route.cases.filter.date'))).toBeInTheDocument();
+        });
+        it('shows the translated range label for a non-all preset', () => {
+            renderFilter({ dateRange: 'date.range.1.week' });
+            expect(screen.getByText(i18n.t('date.range.1.week'))).toBeInTheDocument();
+        });
+        it('shows formatted start/end dates for the custom range', () => {
+            renderFilter({ dateRange: 'date.range.custom' });
+            const expected = `${FIXED_START.format('YYYY-MM-DD')} ${i18n.t('to')} ${FIXED_END.format('YYYY-MM-DD')}`;
+            expect(screen.getByText(expected)).toBeInTheDocument();
+        });
+    });
+    describe('chip color', () => {
+        it('uses default color for date.range.all', () => {
+            renderFilter({ dateRange: 'date.range.all' });
+            const chip = document.querySelector('.MuiChip-root');
+            expect(chip).not.toHaveClass('MuiChip-colorPrimary');
+        });
+        it('uses primary color for any non-all range', () => {
+            renderFilter({ dateRange: 'date.range.1.day' });
+            const chip = document.querySelector('.MuiChip-root');
+            expect(chip).toHaveClass('MuiChip-colorPrimary');
+        });
+    });
+    describe('popper content', () => {
+        it('does not show the autocomplete before the chip is clicked', () => {
+            renderFilter();
+            expect(screen.queryByRole('combobox')).toBeNull();
+        });
+        it('shows the range autocomplete after the chip is clicked', async () => {
+            renderFilter();
+            await openPopper(user);
+            expect(screen.getByRole('combobox')).toBeInTheDocument();
+        });
+        it('does not show date pickers when a preset (non-custom) range is active', async () => {
+            renderFilter({ dateRange: 'date.range.1.day' });
+            await openPopper(user);
+            expect(screen.queryByTestId(`picker-${i18n.t('date.select.start')}`)).toBeNull();
+        });
+        it('shows start and end date pickers when custom range is active', async () => {
+            renderFilter({ dateRange: 'date.range.custom' });
+            await openPopper(user);
+            expect(screen.getByTestId(`picker-${i18n.t('date.select.start')}`)).toBeInTheDocument();
+            expect(screen.getByTestId(`picker-${i18n.t('date.select.end')}`)).toBeInTheDocument();
+        });
+    });
+    describe('interactions', () => {
+        it('calls onChange when a range option is selected from the autocomplete', async () => {
+            const onChange = vi.fn();
+            renderFilter({ dateRange: 'date.range.all', onChange });
+            await openPopper(user);
+            await user.click(screen.getByRole('combobox'));
+            const option = await screen.findByRole('option', { name: i18n.t('date.range.1.week') });
+            await user.click(option);
+            expect(onChange).toHaveBeenCalledWith('date.range.1.week');
+        });
+        it('calls onCustomStartChange when the start date picker fires', async () => {
+            const onCustomStartChange = vi.fn();
+            renderFilter({ dateRange: 'date.range.custom', onCustomStartChange });
+            await openPopper(user);
+            await user.click(screen.getByTestId(`picker-${i18n.t('date.select.start')}`));
+            expect(onCustomStartChange).toHaveBeenCalledWith(dayjs('2025-06-01'));
+        });
+        it('calls onCustomEndChange when the end date picker fires', async () => {
+            const onCustomEndChange = vi.fn();
+            renderFilter({ dateRange: 'date.range.custom', onCustomEndChange });
+            await openPopper(user);
+            await user.click(screen.getByTestId(`picker-${i18n.t('date.select.end')}`));
+            expect(onCustomEndChange).toHaveBeenCalledWith(dayjs('2025-06-01'));
+        });
+    });
+});

package/components/routes/cases/search/CaseStatusFilter.d.ts

@@ -0,0 +1,6 @@
+import type { FC } from 'react';
+declare const CaseStatusFilter: FC<{
+    statusFilter: string[];
+    onChange: (v: string[]) => void;
+}>;
+export default CaseStatusFilter;

package/components/routes/cases/search/CaseStatusFilter.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FilterList } from '@mui/icons-material';
+import { ToggleButton, ToggleButtonGroup, Typography } from '@mui/material';
+import ChipPopper from '@cccsaurora/howler-ui/components/elements/display/ChipPopper';
+import { useTranslation } from 'react-i18next';
+import { CASE_STATUSES } from '../constants';
+const CaseStatusFilter = ({ statusFilter, onChange }) => {
+    const { t } = useTranslation();
+    return (_jsx(ChipPopper, { icon: _jsx(FilterList, { fontSize: "small" }), label: _jsx(Typography, { variant: "body2", children: statusFilter.length === 0
+                ? t('route.cases.filter.status')
+                : statusFilter.map(s => t(`page.cases.status.${s}`)).join(', ') }), minWidth: "200px", slotProps: { chip: { size: 'small', color: statusFilter.length > 0 ? 'primary' : 'default' } }, children: _jsx(ToggleButtonGroup, { value: statusFilter, onChange: (_, nv) => onChange(nv), size: "small", orientation: "vertical", sx: { width: '100%' }, children: CASE_STATUSES.map(s => (_jsx(ToggleButton, { value: s, sx: { justifyContent: 'flex-start' }, children: t(`page.cases.status.${s}`) }, s))) }) }));
+};
+export default CaseStatusFilter;

package/components/routes/cases/search/CaseStatusFilter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/components/routes/cases/search/CaseStatusFilter.test.js

@@ -0,0 +1,86 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/// <reference types="vitest" />
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent, {} from '@testing-library/user-event';
+import i18n from '@cccsaurora/howler-ui/i18n';
+import { I18nextProvider } from 'react-i18next';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import CaseStatusFilter from './CaseStatusFilter';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const Wrapper = ({ children }) => _jsx(I18nextProvider, { i18n: i18n, children: children });
+const renderFilter = (statusFilter, onChange = vi.fn()) => render(_jsx(CaseStatusFilter, { statusFilter: statusFilter, onChange: onChange }), { wrapper: Wrapper });
+const openPopper = async (user) => {
+    const chip = screen.getByText(i18n.t('route.cases.filter.status')).closest('.MuiChip-root');
+    await user.click(chip);
+    await waitFor(() => {
+        expect(screen.getByRole('group')).toBeInTheDocument();
+    });
+};
+describe('CaseStatusFilter', () => {
+    let user;
+    beforeEach(() => {
+        user = userEvent.setup();
+        vi.clearAllMocks();
+    });
+    describe('label', () => {
+        it('shows the default "Status" label when no statuses are selected', () => {
+            renderFilter([]);
+            expect(screen.getByText(i18n.t('route.cases.filter.status'))).toBeInTheDocument();
+        });
+        it('shows a comma-separated list of status labels when statuses are selected', () => {
+            renderFilter(['open', 'on-hold']);
+            const expected = [i18n.t('page.cases.status.open'), i18n.t('page.cases.status.on-hold')].join(', ');
+            expect(screen.getByText(expected)).toBeInTheDocument();
+        });
+        it('shows a single status label when one status is selected', () => {
+            renderFilter(['resolved']);
+            expect(screen.getByText(i18n.t('page.cases.status.resolved'))).toBeInTheDocument();
+        });
+    });
+    describe('chip color', () => {
+        it('uses default color when no statuses are selected', () => {
+            renderFilter([]);
+            const chip = screen.getByText(i18n.t('route.cases.filter.status')).closest('.MuiChip-root');
+            expect(chip).not.toHaveClass('MuiChip-colorPrimary');
+        });
+        it('uses primary color when statuses are selected', () => {
+            renderFilter(['open']);
+            const chip = screen.getByText(i18n.t('page.cases.status.open')).closest('.MuiChip-root');
+            expect(chip).toHaveClass('MuiChip-colorPrimary');
+        });
+    });
+    describe('popper content', () => {
+        it('does not show toggle buttons before the chip is clicked', () => {
+            renderFilter([]);
+            expect(screen.queryByRole('group')).toBeNull();
+        });
+        it('shows all four status toggle buttons when the chip is clicked', async () => {
+            renderFilter([]);
+            await openPopper(user);
+            expect(screen.getByText(i18n.t('page.cases.status.open'))).toBeInTheDocument();
+            expect(screen.getByText(i18n.t('page.cases.status.in-progress'))).toBeInTheDocument();
+            expect(screen.getByText(i18n.t('page.cases.status.on-hold'))).toBeInTheDocument();
+            expect(screen.getByText(i18n.t('page.cases.status.resolved'))).toBeInTheDocument();
+        });
+    });
+    describe('interactions', () => {
+        it('calls onChange when a toggle button is clicked', async () => {
+            const onChange = vi.fn();
+            renderFilter([], onChange);
+            await openPopper(user);
+            await user.click(screen.getByText(i18n.t('page.cases.status.open')));
+            expect(onChange).toHaveBeenCalledWith(['open']);
+        });
+        it('calls onChange with empty array when the only selected status is deselected', async () => {
+            const onChange = vi.fn();
+            renderFilter(['open'], onChange);
+            const chip = screen.getByText(i18n.t('page.cases.status.open')).closest('.MuiChip-root');
+            await user.click(chip);
+            await waitFor(() => {
+                expect(screen.getByRole('group')).toBeInTheDocument();
+            });
+            await user.click(screen.getAllByText(i18n.t('page.cases.status.open'))[1]);
+            expect(onChange).toHaveBeenCalledWith([]);
+        });
+    });
+});

package/components/routes/dossiers/DossierEditor.js

@@ -13,7 +13,7 @@ import { useTranslation } from 'react-i18next';
 import { useNavigate, useParams, useSearchParams } from 'react-router-dom';
 import { useContextSelector } from 'use-context-selector';
 import QueryResultText from '../../elements/display/QueryResultText';
-import HitQuery from '../hits/search/HitQuery';
+import RecordQuery from '../hits/search/RecordQuery';
 import LeadForm from './LeadForm';
 import PivotForm from './PivotForm';
 const DossierEditor = () => {
@@ -188,6 +188,6 @@ const DossierEditor = () => {
                                             fontSize: '0.9em',
                                             fontStyle: 'italic',
                                             mb: 0.5
-                                        }), variant: "body2", children: t('hit.search.prompt') }), _jsx(HitQuery, { disabled: !dossier || loading, onChange: (_val, isDirty) => setSearchDirty(isDirty), triggerSearch: query => setDossier(_dossier => ({ ..._dossier, query })) }), searchTotal >= 0 && _jsx(QueryResultText, { count: searchTotal, query: dossier.query })] }) }), _jsxs(Tabs, { value: tab, onChange: (_ev, value) => setTab(value), children: [_jsx(Tab, { label: t('route.dossiers.manager.tabs.leads'), value: "leads" }), _jsx(Tab, { label: t('route.dossiers.manager.tabs.pivots'), value: "pivots" })] }), tab === 'leads' && _jsx(LeadForm, { dossier: dossier, setDossier: setDossier, loading: loading }), tab === 'pivots' && _jsx(PivotForm, { dossier: dossier, setDossier: setDossier, loading: loading })] })] }) }));
+                                        }), variant: "body2", children: t('hit.search.prompt') }), _jsx(RecordQuery, { disabled: !dossier || loading, onChange: (_val, isDirty) => setSearchDirty(isDirty), triggerSearch: query => setDossier(_dossier => ({ ..._dossier, query })) }), searchTotal >= 0 && _jsx(QueryResultText, { count: searchTotal, query: dossier.query })] }) }), _jsxs(Tabs, { value: tab, onChange: (_ev, value) => setTab(value), children: [_jsx(Tab, { label: t('route.dossiers.manager.tabs.leads'), value: "leads" }), _jsx(Tab, { label: t('route.dossiers.manager.tabs.pivots'), value: "pivots" })] }), tab === 'leads' && _jsx(LeadForm, { dossier: dossier, setDossier: setDossier, loading: loading }), tab === 'pivots' && _jsx(PivotForm, { dossier: dossier, setDossier: setDossier, loading: loading })] })] }) }));
 };
 export default memo(DossierEditor);

package/components/routes/dossiers/DossierEditor.test.js

@@ -61,7 +61,7 @@ vi.mock('commons/components/pages/PageCenter', () => ({
 vi.mock('../../elements/display/QueryResultText', () => ({
     default: ({ count, query }) => (_jsxs("div", { id: "query-result-text", children: [count, " ", ' results for ', " ", query] }))
 }));
-vi.mock('../hits/search/HitQuery', () => ({
+vi.mock('../hits/search/RecordQuery', () => ({
     default: ({ onChange, triggerSearch, disabled }) => {
         return (_jsxs("div", { id: "hit-query", children: [_jsx("input", { id: "query-input", disabled: disabled, onChange: e => {
                         onChange?.(e.target.value, false);

package/components/routes/dossiers/Dossiers.js

@@ -2,6 +2,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { Topic } from '@mui/icons-material';
 import { Typography } from '@mui/material';
 import api from '@cccsaurora/howler-ui/api';
+import { ModalContext } from '@cccsaurora/howler-ui/components/app/providers/ModalProvider';
+import SearchResponseProvider, { SearchResponseContext } from '@cccsaurora/howler-ui/components/app/providers/SearchResponseProvider';
 import { TuiListProvider } from '@cccsaurora/howler-ui/components/elements/addons/lists';
 import { TuiListMethodContext } from '@cccsaurora/howler-ui/components/elements/addons/lists/TuiListProvider';
 import ItemManager from '@cccsaurora/howler-ui/components/elements/display/ItemManager';
@@ -18,12 +20,13 @@ const DossiersBase = () => {
     const navigate = useNavigate();
     const { dispatchApi } = useMyApi();
     const { showSuccessMessage } = useMySnackbar();
+    const { withConfirmDeleteModal } = useContext(ModalContext);
     const [searchParams, setSearchParams] = useSearchParams();
     const { load } = useContext(TuiListMethodContext);
     const pageCount = useMyLocalStorageItem(StorageKey.PAGE_COUNT, 25)[0];
+    const { response, request, remove, getSearchRequestData } = useContext(SearchResponseContext);
     const [phrase, setPhrase] = useState('');
     const [offset, setOffset] = useState(parseInt(searchParams.get('offset')) || 0);
-    const [response, setResponse] = useState(null);
     const [hasError, setHasError] = useState(false);
     const [loading, setLoading] = useState(false);
     const onSearch = useCallback(async () => {
@@ -40,11 +43,11 @@ const DossiersBase = () => {
             // Check for the actual search query
             const query = phrase ? `*:*${phrase}*` : '*:*';
             // Ensure the overview should be visible and/or matches the type we are filtering for
-            setResponse(await dispatchApi(api.search.dossier.post({
+            await request(api.search.dossier.post, {
                 query,
                 rows: pageCount,
                 offset
-            })));
+            });
         }
         catch (e) {
             setHasError(true);
@@ -52,7 +55,7 @@ const DossiersBase = () => {
         finally {
             setLoading(false);
         }
-    }, [phrase, setSearchParams, searchParams, dispatchApi, pageCount, offset]);
+    }, [phrase, setSearchParams, searchParams, request, pageCount, offset]);
     // Load the items into list when response changes.
     // This hook should only trigger when the 'response' changes.
     useEffect(() => {
@@ -68,24 +71,27 @@ const DossiersBase = () => {
     }, [response, load]);
     const onPageChange = useCallback((_offset) => {
         if (_offset !== offset) {
-            searchParams.set('offset', _offset.toString());
+            const modifiedRequest = getSearchRequestData({ offset: _offset });
+            searchParams.set('offset', modifiedRequest.offset.toString());
             setSearchParams(searchParams, { replace: true });
-            setOffset(_offset);
+            setOffset(modifiedRequest.offset);
         }
-    }, [offset, searchParams, setSearchParams]);
-    const onDelete = useCallback(async (e, id) => {
+    }, [offset, searchParams, setSearchParams, getSearchRequestData]);
+    const onDelete = useCallback((e, id) => {
         e.preventDefault();
         e.stopPropagation();
-        try {
-            await dispatchApi(api.dossier.del(id), { throwError: false, showError: true });
-            await onSearch();
-            showSuccessMessage(t('route.dossiers.manager.delete.success'));
-        }
-        catch (_err) {
-            // eslint-disable-next-line no-console
-            console.warn(_err);
-        }
-    }, [dispatchApi, onSearch, showSuccessMessage, t]);
+        withConfirmDeleteModal(async () => {
+            try {
+                await dispatchApi(api.dossier.del(id), { throwError: true, showError: true });
+                remove(id);
+                showSuccessMessage(t('route.dossiers.manager.delete.success'));
+            }
+            catch (_err) {
+                // eslint-disable-next-line no-console
+                console.warn(_err);
+            }
+        });
+    }, [dispatchApi, remove, withConfirmDeleteModal, showSuccessMessage, t]);
     useEffect(() => {
         onSearch();
         if (!searchParams.has('offset')) {
@@ -111,6 +117,6 @@ const DossiersBase = () => {
     return (_jsx(ItemManager, { onSearch: onSearch, onPageChange: onPageChange, phrase: phrase, setPhrase: setPhrase, hasError: hasError, searching: loading, aboveSearch: _jsx(Typography, { sx: theme => ({ fontStyle: 'italic', color: theme.palette.text.disabled, mb: 0.5 }), variant: "body2", children: t('route.dossiers.search.prompt') }), renderer: ({ item }, classRenderer) => renderer(item.item, classRenderer()), response: response, onSelect: (item) => navigate(`/dossiers/${item.id}/edit`), onCreate: () => navigate('/dossiers/create'), createPrompt: "route.dossiers.create", searchPrompt: "route.dossiers.manager.search", createIcon: _jsx(Topic, { sx: { mr: 1 } }) }));
 };
 const Dossiers = () => {
-    return (_jsx(TuiListProvider, { children: _jsx(DossiersBase, {}) }));
+    return (_jsx(TuiListProvider, { children: _jsx(SearchResponseProvider, { idField: "dossier_id", children: _jsx(DossiersBase, {}) }) }));
 };
 export default Dossiers;

package/components/routes/help/ActionIntroductionDocumentation.js

@@ -25,7 +25,7 @@ const ActionIntroductionDocumentation = () => {
     useEffect(() => {
         api.action.operations
             .get()
-            .then(_operations => _operations.filter(a => difference(a.roles, user.roles).length < 1))
+            .then(_operations => _operations.filter(a => difference(a.roles, user.roles).length < a.roles.length))
             .then(setOperations)
             // eslint-disable-next-line no-console
             .catch(console.debug);

package/components/routes/help/ApiDocumentation.js

@@ -49,7 +49,7 @@ const ApiDocumentation = () => {
                                             .replace(/(\S+)\s+=>\s+(.+)/g, '\n`$1`: $2\n')
                                             .replace(/(Data Block:\n)([\s\S]+)(Result Example:)/, (__, p1, p2, p3) => `${p1}\`\`\`\n${p2.trim()}\n\`\`\`\n${p3}`)
                                             .replace(/(Result Example:\n)([\s\S]+)$/, (__, p1, p2) => `${p1}\`\`\`\n${p2.trim()}\n\`\`\``) }));
-                                    return (_jsxs(Fragment, { children: [_jsxs(TableRow, { style: { marginBottom: '1rem' }, sx: [isLg && { '& > td': { borderBottom: 0 } }], children: [_jsx(TableCell, { children: _jsxs(Stack, { direction: "column", spacing: 1, alignItems: "start", children: [_jsx(Typography, { children: endpoint.name }), _jsx("code", { children: endpoint.path }), _jsxs(Stack, { direction: "row", spacing: 1, children: [endpoint.complete ? (_jsx(Chip, { size: "small", label: "Stable", color: "success" })) : (_jsx(Chip, { size: "small", label: "Unstable", color: "error" })), endpoint.protected ? (_jsx(Chip, { size: "small", label: "Protected", color: "warning" })) : (_jsx(Chip, { size: "small", label: "Unprotected" }))] }), _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.methods.map(m => (_jsx(Chip, { size: "small", label: m }, m))) }), endpoint.ui_only && _jsx(Chip, { size: "small", label: "UI Only" })] }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_type.map(type => (_jsx(Chip, { size: "small", label: type, color: user.roles?.includes(type) ? 'success' : 'default' }, type))) }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_priv.map((p) => (_jsx(Chip, { size: "small", label: t(APIKEY_LABELS[p]) }, p))) }) }), !isLg && _jsx(TableCell, { children: documentationCell })] }), isLg && (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: 3, sx: { '& pre': { whiteSpace: 'pre-wrap' } }, children: documentationCell }) }))] }, endpoint.id));
+                                    return (_jsxs(Fragment, { children: [_jsxs(TableRow, { style: { marginBottom: '1rem' }, sx: [isLg && { '& > td': { borderBottom: 0 } }], children: [_jsx(TableCell, { children: _jsxs(Stack, { direction: "column", spacing: 1, alignItems: "start", children: [_jsx(Typography, { children: endpoint.name }), _jsx("code", { children: endpoint.path }), _jsxs(Stack, { direction: "row", spacing: 1, children: [endpoint.complete ? (_jsx(Chip, { label: "Stable", color: "success" })) : (_jsx(Chip, { label: "Unstable", color: "error" })), endpoint.protected ? (_jsx(Chip, { label: "Protected", color: "warning" })) : (_jsx(Chip, { label: "Unprotected" }))] }), _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.methods.map(m => (_jsx(Chip, { size: "small", label: m }, m))) }), endpoint.ui_only && _jsx(Chip, { label: "UI Only" })] }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_type.map(type => (_jsx(Chip, { size: "small", label: type, color: user.roles?.includes(type) ? 'success' : 'default' }, type))) }) }), _jsx(TableCell, { children: _jsx(Stack, { spacing: 1, direction: "row", children: endpoint.required_priv.map((p) => (_jsx(Chip, { size: "small", label: t(APIKEY_LABELS[p]) }, p))) }) }), !isLg && _jsx(TableCell, { children: documentationCell })] }), isLg && (_jsx(TableRow, { children: _jsx(TableCell, { colSpan: 3, sx: { '& pre': { whiteSpace: 'pre-wrap' } }, children: documentationCell }) }))] }, endpoint.id));
                                 }) })] }) })] }) }));
 };
 export default ApiDocumentation;

package/components/routes/help/HitBannerDocumentation.js

@@ -9,6 +9,7 @@ import { useTranslation } from 'react-i18next';
 const HitBannerDocumentation = () => {
     const { t } = useTranslation();
     const dummyHit = useMemo(() => ({
+        __index: 'hit',
         timestamp: '2023-02-11T15:10:31.585826Z',
         howler: {
             id: 'howler.id',

package/components/routes/help/HitDocumentation.js

@@ -5,7 +5,6 @@ import { useScrollRestoration } from '@cccsaurora/howler-ui/components/hooks/use
 import { useCallback, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { useSearchParams } from 'react-router-dom';
-import BundleDocumentation from './BundleDocumentation';
 import HelpTabs from './components/HelpTabs';
 import HitBannerDocumentation from './HitBannerDocumentation';
 import HitLabelsDocumentation from './HitLabelsDocumentation';
@@ -23,8 +22,7 @@ const HitDocumentation = () => {
         searchParams.set('tab', _tab);
         setSearchParams(new URLSearchParams(searchParams));
     }, [searchParams, setSearchParams]);
-    return (_jsx(PageCenter, { margin: 4, width: "100%", maxWidth: "1750px", textAlign: "left", children: _jsxs(Stack, { sx: { flexDirection: useHorizontal ? 'column' : 'row', '& h1': { mt: 0 } }, children: [_jsxs(HelpTabs, { value: tab, children: [_jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.schema.title') }), value: "schema", onClick: () => onChange('schema') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.banner.title') }), value: "header", onClick: () => onChange('header') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.bundle.title') }), value: "bundle", onClick: () => onChange('bundle') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.links.title') }), value: "links", onClick: () => onChange('links') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.labels.title') }), value: "labels", onClick: () => onChange('labels') })] }), _jsx(Box, { children: {
-                        bundle: () => _jsx(BundleDocumentation, {}),
+    return (_jsx(PageCenter, { margin: 4, width: "100%", maxWidth: "1750px", textAlign: "left", children: _jsxs(Stack, { sx: { flexDirection: useHorizontal ? 'column' : 'row', '& h1': { mt: 0 } }, children: [_jsxs(HelpTabs, { value: tab, children: [_jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.schema.title') }), value: "schema", onClick: () => onChange('schema') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.banner.title') }), value: "header", onClick: () => onChange('header') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.links.title') }), value: "links", onClick: () => onChange('links') }), _jsx(Tab, { label: _jsx(Typography, { variant: "caption", children: t('help.hit.labels.title') }), value: "labels", onClick: () => onChange('labels') })] }), _jsx(Box, { children: {
                         header: () => _jsx(HitBannerDocumentation, {}),
                         links: () => _jsx(HitLinksDocumentation, {}),
                         labels: () => _jsx(HitLabelsDocumentation, {}),

package/components/routes/help/markdown/en/client.md.js

@@ -1 +1 @@
-export default "# Howler Client Documentation\n\nThis documentation will outline how to interact with the howler API using the howler client in both Java and python development environments. We will outline the basic process of creating a new hit in each environment as well as searching howler for hits matching your query.\n\n## Getting started\n\n### Installation\n\nIn order to use the howler client, you need to list it as a dependency in your project.\n\n#### **Python**\n\nSimply install through pip:\n\n```bash\npip install howler-client\n```\n\nYou can also add it to your requirements.txt, or whatever dependency management system you use.\n\n### Authentication\n\nAs outlined in the [Authentication Documentation](/help/auth), there's a number of ways users can choose to authenticate. In order to interface with the howler client, however, the suggested flow is to use an API key. So before we start, let's generate a key.\n\n1. Open the Howler UI you'd like to interface with.\n2. Log in, then click your profile in the top right.\n3. Under user menu, click Settings.\n4. Under User Security, press the (+) icon on the API Keys row.\n5. Name your key, and give it the requisite permissions.\n6. Press Create, and copy the supplied string somewhere safe. **You will not see this string again.**\n\nThis API Key will be supplied to your code later on.\n\n## Python Client\n\nIn order to connect with howler using the python client, there is a fairly simple process to follow:\n\n```python\nfrom howler_client import get_client\n\nUSERNAME = 'user' # Obtain this from the user settings page of the Howler UI\nAPIKEY = 'apikey_name:apikey_data'\n\napikey = (USERNAME, APIKEY)\n\nhowler = get_client(\"$CURRENT_URL\", apikey=apikey)\n```\n\n```alert\nYou can skip generating an API Key and providing it if you're executing this code within HOGWARTS (i.e., on jupyterhub or airflow). OBO will handle authentication for you!\n```\n\nThat's it! You can now use the `howler` object to interact with the server. So what does that actually look like?\n\n### Creating hits in Python\n\nFor the python client, you can create hits using either the `howler.hit.create` or `howler.hit.create_from_map` functions.\n\n#### `create`\n\nThis function takes in a single argument - either a single hit, or a list of them, conforming to the [Howler Schema](/help/hit?tab=schema). Here is a simple example:\n\n```python\n# Some bogus data in the Howler Schema format\nexample_hit = {\n  \"howler\": {\n    \"analytic\": \"example\",\n    \"score\": 10.0\n  },\n  \"event\": {\n    \"reason\": \"Example hit\"\n  }\n}\n\nhowler.hit.create(example_hit)\n```\n\nYou can also ingest data in a flat format:\n\n```python\nexample_hit = {\n  \"howler.analytic\": \"example\",\n  \"howler.score\": 10.0,\n  \"event.reason\": \"Example hit\"\n}\n\nhowler.hit.create(example_hit)\n```\n\n#### `create_from_map`\n\nThis function takes in three arguments:\n\n- `tool name`: The name of the analytic creating the hit\n- `map`: A mapping between the raw data you have and the howler schema\n  - The format is a dictionary where the keys are the flattened path of the raw data, and the values are a list of flattened paths for Howler's fields where the data will be copied into.\n- `documents`: The raw data you want to add to howler\n\nHere is a simple example:\n\n```python\n# The mapping from our data to howler's schema\nhwl_map = {\n  \"file.sha256\": [\"file.hash.sha256\", \"howler.hash\"],\n  \"file.name\": [\"file.name\"],\n  \"src_ip\": [\"source.ip\", \"related.ip\"],\n  \"dest_ip\": [\"destination.ip\", \"related.ip\"],\n  \"time.created\": [\"event.start\"],\n}\n\n# Some bogus data in a custom format we want to add to howler\nexample_hit = {\n  \"src_ip\": \"0.0.0.0\",\n  \"dest_ip\": \"8.8.8.8\",\n  \"file\": {\n    \"name\": \"hello.exe\",\n    \"sha256\": sha256(str(\"hello.exe\").encode()).hexdigest()\n  },\n  \"time\": {\n    \"created\": datetime.now().isoformat()\n  },\n}\n\n# Note that the third argument is of type list!\nhowler.hit.create_from_map(\"example_ingestor\", hwl_map, [example_hit])\n```\n\n### Querying Hits\n\nQuerying hits using the howler python client is done using the `howler.search.hit` function. It has a number of required and optional arguments:\n\n- Required:\n  - `query`: lucene query (string)\n- Optional:\n  - `filters`: Additional lucene queries used to filter the data (list of strings)\n  - `fl`: List of fields to return (comma separated string of fields)\n  - `offset`: Offset at which the query items should start (integer)\n  - `rows`: Number of records to return (integer)\n  - `sort`: Field used for sorting with direction (string: ex. 'id desc')\n  - `timeout`: Max amount of milliseconds the query will run (integer)\n  - `use_archive`: Also query the archive\n  - `track_total_hits`: Number of hits to track (default: 10k)\n\nHere are some example queries:\n\n```python\n# Search for all hits created by assemblyline, show the first 50, and return only their ids\nhowler.search.hit(\"howler.analytic:assemblyline\", fl=\"howler.id\", rows=50)\n\n# Search for all resolved hits created in the last five days, returning their id and the analytic that created them. Show only ten, offset by 40\nhowler.search.hit(\"howler.status:resolved\", filters=['event.created:[now-5d TO now]'] fl=\"howler.id,howler.analytic\", rows=10, offset=40)\n\n# Search for all hits, timeout if the query takes more than 100ms\nhowler.search.hit(\"howler.id:*\", track_total_hits=100000000, timeout=100, use_archive=True)\n```\n\n### Updating Hits\n\nIn order to update hits, there are a number of supported functions:\n\n- `howler.hit.update(...)`\n- `howler.hit.update_by_query(...)`\n- `howler.hit.overwrite(...)`\n\n#### `update()`\n\nIf you want to update a hit in a transactional way, you can use the following code:\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.update(hit_to_update[\"howler\"][\"id\"], [(UPDATE_SET, \"howler.score\", hit_to_update[\"howler\"][\"score\"] + 100)])\n```\n\nThe following operations can be run to update a hit.\n\n**List Operations:**\n\n- `UPDATE_APPEND`: Used to append a value to a given list\n- `UPDATE_APPEND_IF_MISSING`: Used to append a value to a given list if the value isn't already in the list\n- `UPDATE_REMOVE`: Will remove a given value from a list\n\n**Numeric Operations:**\n\n- `UPDATE_DEC`: Decrement a numeric value by the specified amount\n- `UPDATE_INC`: Increment a numeric value by the specified amount\n- `UPDATE_MAX`: Will set a numeric value to the maximum of the existing value and the specified value\n- `UPDATE_MIN`: Will set a numeric value to the minimum of the existing value and the specified value\n\n**Multipurpose Operations:**\n\n- `UPDATE_SET`: Set a field's value to the given value\n- `UPDATE_DELETE`: Will delete a given field's value\n\n#### `update_by_query()`\n\nThis function allows you to update a large number of hits by a query:\n\n```python\nclient.hit.update_by_query(f'howler.analytic:\"Example Alert\"', [(UPDATE_INC, \"howler.score\", 100)])\n```\n\nThe same operations as in `update()` can be used.\n\n### `overwrite()`\n\nThis function allows you to directly overwrite a hit with a partial hit object. This is the most easy to use, but loses some of the validation and additional processing of the update functions.\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.overwrite(hit_to_update[\"howler\"][\"id\"], {\"source.ip\": \"127.0.0.1\", \"destination.ip\": \"8.8.8.8\"})\n```\n"
+export default "# Howler Client Documentation\n\nThis documentation will outline how to interact with the howler API using the howler client in both Java and python development environments. We will outline the basic process of creating a new hit in each environment as well as searching howler for hits matching your query.\n\n## Getting started\n\n### Installation\n\nIn order to use the howler client, you need to list it as a dependency in your project.\n\n#### **Python**\n\nSimply install through pip:\n\n```bash\npip install howler-client\n```\n\nYou can also add it to your requirements.txt, or whatever dependency management system you use.\n\n### Authentication\n\nAs outlined in the [Authentication Documentation](/help/auth), there's a number of ways users can choose to authenticate. In order to interface with the howler client, however, the suggested flow is to use an API key. So before we start, let's generate a key.\n\n1. Open the Howler UI you'd like to interface with.\n2. Log in, then click your profile in the top right.\n3. Under user menu, click Settings.\n4. Under User Security, press the (+) icon on the API Keys row.\n5. Name your key, and give it the requisite permissions.\n6. Press Create, and copy the supplied string somewhere safe. **You will not see this string again.**\n\nThis API Key will be supplied to your code later on.\n\n## Python Client\n\nIn order to connect with howler using the python client, there is a fairly simple process to follow:\n\n```python\nfrom howler_client import get_client\n\nUSERNAME = 'user' # Obtain this from the user settings page of the Howler UI\nAPIKEY = 'apikey_name:apikey_data'\n\napikey = (USERNAME, APIKEY)\n\nhowler = get_client(\"$CURRENT_URL\", apikey=apikey)\n```\n\n```alert\nYou can skip generating an API Key and providing it if you're executing this code within HOGWARTS (i.e., on jupyterhub or airflow). OBO will handle authentication for you!\n```\n\nThat's it! You can now use the `howler` object to interact with the server. So what does that actually look like?\n\n### Creating hits in Python\n\nFor the python client, you can create hits using either the `howler.hit.create` or `howler.hit.create_from_map` functions.\n\n#### `create`\n\nThis function takes in a single argument - either a single hit, or a list of them, conforming to the [Howler Schema](/help/hit?tab=schema). Here is a simple example:\n\n```python\n# Some bogus data in the Howler Schema format\nexample_hit = {\n  \"howler\": {\n    \"analytic\": \"example\",\n    \"score\": 10.0\n  },\n  \"event\": {\n    \"reason\": \"Example hit\"\n  }\n}\n\nhowler.hit.create(example_hit)\n```\n\nYou can also ingest data in a flat format:\n\n```python\nexample_hit = {\n  \"howler.analytic\": \"example\",\n  \"howler.score\": 10.0,\n  \"event.reason\": \"Example hit\"\n}\n\nhowler.hit.create(example_hit)\n```\n\n#### `create_from_map`\n\nThis function takes in three arguments:\n\n- `tool name`: The name of the analytic creating the hit\n- `map`: A mapping between the raw data you have and the howler schema\n  - The format is a dictionary where the keys are the flattened path of the raw data, and the values are a list of flattened paths for Howler's fields where the data will be copied into.\n- `documents`: The raw data you want to add to howler\n\nHere is a simple example:\n\n```python\n# The mapping from our data to howler's schema\nhwl_map = {\n  \"file.sha256\": [\"file.hash.sha256\", \"howler.hash\"],\n  \"file.name\": [\"file.name\"],\n  \"src_ip\": [\"source.ip\", \"related.ip\"],\n  \"dest_ip\": [\"destination.ip\", \"related.ip\"],\n  \"time.created\": [\"event.start\"],\n}\n\n# Some bogus data in a custom format we want to add to howler\nexample_hit = {\n  \"src_ip\": \"0.0.0.0\",\n  \"dest_ip\": \"8.8.8.8\",\n  \"file\": {\n    \"name\": \"hello.exe\",\n    \"sha256\": sha256(str(\"hello.exe\").encode()).hexdigest()\n  },\n  \"time\": {\n    \"created\": datetime.now().isoformat()\n  },\n}\n\n# Note that the third argument is of type list!\nhowler.hit.create_from_map(\"example_ingestor\", hwl_map, [example_hit])\n```\n\n### Querying Hits\n\nQuerying hits using the howler python client is done using the `howler.search.hit` function. It has a number of required and optional arguments:\n\n- Required:\n  - `query`: lucene query (string)\n- Optional:\n  - `filters`: Additional lucene queries used to filter the data (list of strings)\n  - `fl`: List of fields to return (comma separated string of fields)\n  - `offset`: Offset at which the query items should start (integer)\n  - `rows`: Number of records to return (integer)\n  - `sort`: Field used for sorting with direction (string: ex. 'id desc')\n  - `timeout`: Max amount of milliseconds the query will run (integer)\n  - `track_total_hits`: Number of hits to track (default: 10k)\n\nHere are some example queries:\n\n```python\n# Search for all hits created by assemblyline, show the first 50, and return only their ids\nhowler.search.hit(\"howler.analytic:assemblyline\", fl=\"howler.id\", rows=50)\n\n# Search for all resolved hits created in the last five days, returning their id and the analytic that created them. Show only ten, offset by 40\nhowler.search.hit(\"howler.status:resolved\", filters=['event.created:[now-5d TO now]'] fl=\"howler.id,howler.analytic\", rows=10, offset=40)\n\n# Search for all hits, timeout if the query takes more than 100ms\nhowler.search.hit(\"howler.id:*\", track_total_hits=100000000, timeout=100)\n```\n\n### Updating Hits\n\nIn order to update hits, there are a number of supported functions:\n\n- `howler.hit.update(...)`\n- `howler.hit.update_by_query(...)`\n- `howler.hit.overwrite(...)`\n\n#### `update()`\n\nIf you want to update a hit in a transactional way, you can use the following code:\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.update(hit_to_update[\"howler\"][\"id\"], [(UPDATE_SET, \"howler.score\", hit_to_update[\"howler\"][\"score\"] + 100)])\n```\n\nThe following operations can be run to update a hit.\n\n**List Operations:**\n\n- `UPDATE_APPEND`: Used to append a value to a given list\n- `UPDATE_APPEND_IF_MISSING`: Used to append a value to a given list if the value isn't already in the list\n- `UPDATE_REMOVE`: Will remove a given value from a list\n\n**Numeric Operations:**\n\n- `UPDATE_DEC`: Decrement a numeric value by the specified amount\n- `UPDATE_INC`: Increment a numeric value by the specified amount\n- `UPDATE_MAX`: Will set a numeric value to the maximum of the existing value and the specified value\n- `UPDATE_MIN`: Will set a numeric value to the minimum of the existing value and the specified value\n\n**Multipurpose Operations:**\n\n- `UPDATE_SET`: Set a field's value to the given value\n- `UPDATE_DELETE`: Will delete a given field's value\n\n#### `update_by_query()`\n\nThis function allows you to update a large number of hits by a query:\n\n```python\nclient.hit.update_by_query(f'howler.analytic:\"Example Alert\"', [(UPDATE_INC, \"howler.score\", 100)])\n```\n\nThe same operations as in `update()` can be used.\n\n### `overwrite()`\n\nThis function allows you to directly overwrite a hit with a partial hit object. This is the most easy to use, but loses some of the validation and additional processing of the update functions.\n\n```python\nhit_to_update = client.search.hit(\"howler.id:*\", rows=1, sort=\"event.created desc\")[\"items\"][0]\n\nresult = client.hit.overwrite(hit_to_update[\"howler\"][\"id\"], {\"source.ip\": \"127.0.0.1\", \"destination.ip\": \"8.8.8.8\"})\n```\n"