robobyte-front-builder 1.0.25 → 1.0.27

package/docs/fetchReportData.md

@@ -0,0 +1,379 @@
+# `fetchReportDataByPageId` — Standalone Reference (Host-App Usage)
+
+> **Scope.** This document is for calling `fetchReportDataByPageId` directly from host-app code — pages, hooks, action handlers, server-side logic, anywhere outside the UI Builder.
+>
+> If you're emitting builder Calculation code, use [`training/48-fetchReportData.md`](../training/48-fetchReportData.md) instead — that variant explains the auto-injected `fetchReportData` symbol, the Calculation scope, and the conventions of in-builder action code.
+
+A pure data fetcher by report `pageId`. No AG Grid. No React. Resolves the report's builder model (cached for the session), applies your filter on top of the report's own, optionally evaluates `customFilterCode`, calls `GenericGet`, and returns a normalized result.
+
+Use it whenever a host page needs **rows from a server-defined report** but you're not embedding a `<ReportViewer>` — e.g. seeding a form, computing a KPI counter, exporting to PDF, prefetching lookup tables, building a custom chart on top of report data.
+
+---
+
+## 1. Quick start
+
+```js
+import { fetchReportDataByPageId } from 'robobyte-front-builder'
+
+const result = await fetchReportDataByPageId({ pageId: 'OPEN_INVOICES' })
+if (result.success) {
+  console.log(`Got ${result.rows.length} of ${result.total} rows`)
+}
+```
+
+That's the minimum. `pageId` is the only required parameter.
+
+---
+
+## 2. Prerequisites
+
+### 2.1 Import paths — recommended vs legacy
+
+**Recommended** (since v1.0.23):
+
+```js
+import { fetchReportDataByPageId } from 'robobyte-front-builder'
+```
+
+**Legacy bare-alias path** (still supported):
+
+```js
+import fetchReportDataByPageId from 'services/reportData/fetchReportData'
+```
+
+The bare-alias path only works because the host's `next.config.js` includes a `NormalModuleReplacementPlugin` rule (`packageOwnedServices`) that routes `services/reportData/fetchReportData` to the package's source. Both paths resolve to **the same module instance**, so the in-memory `builderModelCache` is shared regardless of which one you use. Pick the package import for new code — it doesn't depend on the special webpack rule and is easier to read.
+
+### 2.2 The provider supplies API URL + auth
+
+`fetchReportDataByPageId` calls `Services.PostService` internally, which reads the API base URL and `accessToken` from `<RoboByteFrontBuilderProvider>` (set up at `_app.js` level). Without the provider, requests go nowhere useful and the call returns `{ success: false }`.
+
+---
+
+## 3. Signature
+
+```ts
+import { fetchReportDataByPageId } from 'robobyte-front-builder'
+
+await fetchReportDataByPageId({
+  pageId,                // string | number — REQUIRED
+  filter = {},           // see section 5
+  isDataOnly = false,    // true → return rows array directly, no wrapper
+  dataAsObject = false,  // true → expand underscore-paths into nested objects
+  isPagination = true,   // false → fetch all matching rows
+  isSingle = false,      // true → return first row only (row, not array)
+  globalParams = null,   // { 0: value, 1: value, ... } overrides selectionParams by index
+  page = 1,              // 1-based page number
+  pageSize = 50,         // rows per page
+  authContext = null,    // see section 5.3
+  context = null,        // see section 5.3
+})
+```
+
+Returns a `Promise`. **Always `await`** — see pitfalls.
+
+---
+
+## 4. Return shape
+
+```ts
+// Default — full wrapper
+{
+  success: true,
+  rows:    RowType[] | RowType,  // array OR single row (if isSingle)
+  total:   number,               // total rows on server (paginated mode)
+  rawResponse: any,              // exact backend response
+  finalRequest: {                // useful for debugging — what was actually sent
+    endpoint:    string,
+    getType:     'Pagination' | 'NoPagination' | 'SqlPagination' | 'SqlNoPagination',
+    filter:      object,
+    sourceModel: string,
+    params:      { page, pageSize },
+  }
+}
+
+// On error
+{ success: false, error: 'Report detailsOld not found' /* or Error object */ }
+
+// With isDataOnly: true
+RowType[] | RowType                // bare rows; no wrapper at all
+```
+
+Variants:
+
+| Options | Returns |
+|---|---|
+| Defaults | `{ success, rows: Row[], total, ... }` |
+| `isSingle: true` | `{ success, rows: Row, total, ... }` — `rows` is a single object |
+| `isDataOnly: true` | `Row[]` (or `Row` if `isSingle`) — no wrapper |
+| `isPagination: false` | All matching rows fetched in one request |
+| `dataAsObject: true` | `Foo_Bar` flat keys expanded into `Foo.Bar` nested objects |
+
+---
+
+## 5. The `filter` parameter
+
+Plain JS object. Three special slots; anything else at the top level is forwarded to the backend as-is.
+
+| Slot | Type | Purpose |
+|---|---|---|
+| `Tfilter` | `FilterItem[]` | Filters merged with the report's own. |
+| `TFilter` | `FilterItem[]` | Alias accepted for legacy callers. |
+| `customFilterCode` | `string` | JS source evaluated at fetch time. |
+
+### 5.1 `FilterItem` shape
+
+```ts
+{
+  path:          string,    // dotted field path, e.g. "Customer.RegionId"
+  friendlyName?: string,
+  value:         any,       // scalar | array (for In/NotIn/Between)
+  method:        'Equal' | 'NotEqual' | 'Greater' | 'GreaterOrEqual' |
+                 'Less'  | 'LessOrEqual'  | 'Contains' | 'StartsWith' |
+                 'EndsWith' | 'In' | 'NotIn' | 'IsNull' | 'IsNotNull' | 'Between',
+  orGroupName?:  string,    // group multiple items into an OR-block
+}
+```
+
+### 5.2 Null-value stripping
+
+Items where `value === null || value === undefined || value === ''` are dropped before the request is sent. So you can build a filter object from optional state without conditional guards:
+
+```js
+const filter = {
+  Tfilter: [
+    { path: 'Status',  value: status,    method: 'Equal' },  // dropped if status is null
+    { path: 'OwnerId', value: ownerId,   method: 'Equal' },  // dropped if ownerId is null
+    { path: 'Year',    value: 2026,      method: 'Equal' },  // kept
+  ]
+}
+```
+
+### 5.3 `customFilterCode` (advanced)
+
+A code string evaluated server-side at request time. Useful when the filter rule depends on the auth context and you want the rule to follow the report regardless of the caller. Available scope:
+
+| Var | Source |
+|---|---|
+| `authContext` | The `authContext` arg you pass to `fetchReportDataByPageId`. |
+| `context` | The `context` arg you pass. |
+| `filters` | The merged `Tfilter` array. Read-only. |
+| `customFilter` | Empty `[]` to push items into. |
+
+```js
+const result = await fetchReportDataByPageId({
+  pageId: 'MY_ORDERS',
+  filter: {
+    customFilterCode: `
+      if (authContext?.user?.shopId) {
+        customFilter.push({ path: 'ShopId', value: authContext.user.shopId, method: 'Equal' })
+      }
+    `,
+  },
+  authContext: { user },   // pass it explicitly
+})
+```
+
+> **In host-app code, you usually don't need `customFilterCode`.** Just build the filter object in plain JS from your React state and pass it. `customFilterCode` is for cases where the filter rule should travel with the report (e.g. server-side report definitions that include security constraints).
+
+---
+
+## 6. Recipes
+
+### 6.1 Fetch once on mount
+
+```jsx
+import { useEffect, useState } from 'react'
+import { fetchReportDataByPageId } from 'robobyte-front-builder'
+
+export function useTickets() {
+  const [data,    setData]    = useState(null)
+  const [loading, setLoading] = useState(true)
+  const [error,   setError]   = useState(null)
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    fetchReportDataByPageId({ pageId: 'OPEN_TICKETS', isPagination: false })
+      .then(r => {
+        if (cancelled) return
+        if (r.success) setData(r.rows)
+        else           setError(r.error)
+      })
+      .finally(() => { if (!cancelled) setLoading(false) })
+
+    return () => { cancelled = true }
+  }, [])
+
+  return { data, loading, error }
+}
+```
+
+### 6.2 KPI counter (just the total, no rows)
+
+```js
+async function loadOpenInvoiceCount() {
+  const r = await fetchReportDataByPageId({
+    pageId:       'OPEN_INVOICES',
+    isPagination: true,
+    pageSize:     1,                // we only need `total`, not the rows
+  })
+  return r.success ? r.total : 0
+}
+```
+
+### 6.3 Filter built from React state, memoized
+
+```jsx
+import { useMemo, useEffect, useState } from 'react'
+
+function FilteredReportData({ regionId, status }) {
+  const [rows, setRows] = useState([])
+
+  const filter = useMemo(() => ({
+    Tfilter: [
+      { path: 'Status',   value: status,    method: 'Equal' },
+      { path: 'RegionId', value: regionId,  method: 'Equal' },
+    ],
+  }), [regionId, status])
+
+  useEffect(() => {
+    let cancelled = false
+    fetchReportDataByPageId({ pageId: 'ORDERS', filter, isPagination: false })
+      .then(r => { if (!cancelled && r.success) setRows(r.rows) })
+    return () => { cancelled = true }
+  }, [filter])
+
+  return <Table rows={rows} />
+}
+```
+
+> `useMemo` matters — a fresh `filter` object on every parent render would refetch every render.
+
+### 6.4 Single record by id (for an Edit dialog)
+
+```js
+async function loadCustomer(id) {
+  const r = await fetchReportDataByPageId({
+    pageId:   'CUSTOMER_BY_ID',
+    isSingle: true,
+    filter:   { Tfilter: [{ path: 'Id', value: id, method: 'Equal' }] },
+  })
+  if (!r.success || !r.rows) throw new Error('not found')
+  return r.rows                          // single object, not an array
+}
+```
+
+### 6.5 Bulk export to CSV / Excel
+
+```js
+import * as XLSX from 'xlsx'
+
+async function exportAll() {
+  const r = await fetchReportDataByPageId({
+    pageId:       'ORDERS',
+    isPagination: false,                 // fetch every row
+    dataAsObject: true,                  // expand nested keys for readable headers
+    isDataOnly:   true,                  // skip the wrapper
+  })
+  const ws = XLSX.utils.json_to_sheet(r)
+  const wb = XLSX.utils.book_new()
+  XLSX.utils.book_append_sheet(wb, ws, 'Orders')
+  XLSX.writeFile(wb, 'orders.xlsx')
+}
+```
+
+### 6.6 Pagination cursor in a hook
+
+```jsx
+function usePaginatedReport(pageId, filter) {
+  const [page,    setPage]    = useState(1)
+  const [rows,    setRows]    = useState([])
+  const [total,   setTotal]   = useState(0)
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    fetchReportDataByPageId({ pageId, filter, page, pageSize: 50 })
+      .then(r => {
+        if (cancelled) return
+        if (r.success) { setRows(r.rows); setTotal(r.total) }
+      })
+      .finally(() => { if (!cancelled) setLoading(false) })
+    return () => { cancelled = true }
+  }, [pageId, filter, page])
+
+  return { rows, total, loading, page, setPage }
+}
+```
+
+### 6.7 Server-side selection-param override
+
+```js
+const r = await fetchReportDataByPageId({
+  pageId: 'SALES_BY_REGION',
+  globalParams: { 0: year, 1: regionId },     // 0-based positional, NOT keyed by name
+})
+```
+
+### 6.8 Forwarding auth context for `customFilterCode`
+
+```js
+import { useAuth } from 'your-auth-lib'
+
+function Component() {
+  const auth = useAuth()
+  // ...
+  const r = await fetchReportDataByPageId({
+    pageId: 'MY_SHOP_REPORT',
+    filter: {
+      customFilterCode: `
+        if (authContext?.user?.shopId) {
+          customFilter.push({ path: 'ShopId', value: authContext.user.shopId, method: 'Equal' })
+        }
+      `,
+    },
+    authContext: { user: auth.user },
+  })
+}
+```
+
+---
+
+## 7. Pitfalls
+
+- **Forgetting `await`.** Returns a `Promise`. Calling `r.success` on the unresolved Promise is always `undefined`.
+- **Importing from the wrong path.** Use `import { fetchReportDataByPageId } from 'robobyte-front-builder'`. The legacy bare-alias `'services/reportData/fetchReportData'` also works (the `NormalModuleReplacementPlugin` routes it to the same file), but anything else — relative paths, deep-import paths into `node_modules` — bypasses the dedupe rules and risks loading a second module instance with its own empty `builderModelCache`.
+- **`isSingle: true` returns the row, not an array.** `r.rows[0]` will crash; use `r.rows` directly.
+- **`isPagination: false` on a huge report.** All rows in one request. Use it for lookups (≤ a few thousand rows). For unbounded datasets, paginate.
+- **Filter `null`/`''`/`undefined` items are dropped.** This is usually convenient (you can pass partial state with no conditional guards). But if you literally want to filter for null, use `method: 'IsNull'` — don't pass `value: null`.
+- **`globalParams` is index-keyed.** Keys are 0-based positional indices into `selectionParams`, not names.
+- **The builder-model cache lives for the page session.** First call to a given `pageId` hits the metadata endpoint; subsequent calls reuse it. If you change the report definition mid-session, the cache stays stale until full reload. Hard-refresh the tab if you need fresh metadata.
+- **`filter` object identity in React.** When passing `filter` to a `useEffect`, memoize it with `useMemo`. A fresh literal each render triggers a refetch each render.
+- **`customFilterCode` cannot reference React state.** It's a code string evaluated server-side with `authContext`, `context`, `filters`, `customFilter` in scope — nothing else. If you need state-based filtering, build the filter array in JS before the call.
+- **Missing provider.** Without `<RoboByteFrontBuilderProvider>` wrapping your app, `Services.PostService` has no base URL or auth token; the request goes to the wrong host or 401s.
+
+---
+
+## 8. Cheat sheet
+
+1. `import { fetchReportDataByPageId } from 'robobyte-front-builder'` (recommended). The legacy bare-alias `'services/reportData/fetchReportData'` still works and resolves to the same module.
+2. `await fetchReportDataByPageId({ pageId: '...' })` — that's the minimum.
+3. Build the `filter` object in plain JS — `{ Tfilter: [{ path, value, method }] }`. Null values are auto-stripped.
+4. Memoize the `filter` with `useMemo` when passing into `useEffect`.
+5. `isDataOnly: true` returns the bare rows — skip the `r.success` ceremony when you trust the call.
+6. `isSingle: true` returns one row. `r.rows` is that row.
+7. `isPagination: false` for full datasets; combine with `isDataOnly` for clean export logic.
+8. `dataAsObject: true` to expand flat `Foo_Bar` keys into nested `Foo.Bar` objects.
+9. `globalParams: { 0: ..., 1: ... }` overrides selection params by index.
+10. Wrap the call with cancellation in `useEffect` (`let cancelled = false; … return () => { cancelled = true }`).
+
+---
+
+## Cross-references
+
+- **In-builder Calculation usage of the same function** (auto-injected as `fetchReportData`): [`training/48-fetchReportData.md`](../training/48-fetchReportData.md).
+- **`<ReportViewer>` host-app component** (when you want the data **rendered** rather than fetched): [`docs/ReportViewer.md`](./ReportViewer.md).
+- **Package installation, peer deps, `next.config.js`**: [`INTEGRATION.md`](../INTEGRATION.md).
+- **All `RoboByteFrontBuilderProvider` props**: [`README.md`](../README.md).
+- **AG Grid theme customization** (only matters if the fetched rows end up rendered in a grid downstream): README → *AG Grid theme*.