@asteby/metacore-runtime-react 47.0.0 → 48.0.0

package/src/installed-addons-context.tsx

@@ -0,0 +1,58 @@
+// InstalledAddonsProvider / useAddonInstalled / useCapabilityProvided —
+// primitivo ÚNICO de "¿qué hay instalado?" para hosts y addons.
+//
+// Hoy cada addon lo resuelve a su manera: POS lee `installedAddons` del host
+// (lib/host.ts addonKnownMissing), sondea `/options/<Model>` (use-model-available:
+// 403/404 = ausente) o hardcodea claves (caja-policy useAnyFiscalAddonInstalled);
+// `useInstalledAddons` vive sólo en @asteby/metacore-marketplace. Esto lo sube a
+// runtime-react con dos niveles:
+//   - addon key  (useAddonInstalled('fiscal_mexico'))
+//   - capability (useCapabilityProvided('fiscal.invoice_issuer')) — contrato
+//     independiente del país/vertical: fiscal_mexico, fiscal_colombia… lo proveen
+//     vía manifest `provides_capabilities`; caja pregunta por la capacidad,
+//     no por la clave del addon.
+// Fuente: el host monta el provider con lo que ya trae su bootstrap
+// (installed addons + provides_capabilities del manifest). Sin provider:
+// `undefined` = desconocido (el consumidor decide; NUNCA asume ausente).
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+
+export interface InstalledAddonsValue {
+    addons: ReadonlySet<string>
+    capabilities: ReadonlySet<string>
+}
+
+const Ctx = createContext<InstalledAddonsValue | null>(null)
+
+export function InstalledAddonsProvider({
+    addons,
+    capabilities = [],
+    children,
+}: {
+    addons: readonly string[]
+    capabilities?: readonly string[]
+    children: ReactNode
+}) {
+    const aKey = [...addons].sort().join(',')
+    const cKey = [...capabilities].sort().join(',')
+    const value = useMemo<InstalledAddonsValue>(
+        () => ({ addons: new Set(addons), capabilities: new Set(capabilities) }),
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [aKey, cKey],
+    )
+    return <Ctx.Provider value={value}>{children}</Ctx.Provider>
+}
+
+/** true/false si el host lo sabe; undefined si no hay provider. */
+export function useAddonInstalled(key: string): boolean | undefined {
+    const v = useContext(Ctx)
+    return v ? v.addons.has(key) : undefined
+}
+
+export function useCapabilityProvided(capability: string): boolean | undefined {
+    const v = useContext(Ctx)
+    return v ? v.capabilities.has(capability) : undefined
+}
+
+export function useInstalledAddons(): InstalledAddonsValue | null {
+    return useContext(Ctx)
+}

package/src/option-filter.ts

@@ -0,0 +1,88 @@
+// Option filter — lets a manifest HIDE options of a relation / dynamic picker
+// (e.g. keep cancelled invoices out of the "abonos" invoice selector, PIT-059).
+//
+// The filter runs client-side over the options the resolver already fetched, so
+// it needs no kernel change: it reads the extra scalar columns the options
+// endpoint returns (they land in `option.meta`) plus the standard `label`,
+// `name`, `description`, `color`, `icon` keys. Fully opt-in: a field without
+// `option_filter` / `optionFilter` behaves exactly as before.
+import type { ResolvedOption } from './use-options-resolver'
+
+export interface OptionFilterRule {
+    /** Option property to test: a `meta` key (e.g. `status`) or `id`/`value`/`label`/`name`/`description`/`color`/`icon`. */
+    field: string
+    /** Keep only options whose value equals this. */
+    equals?: string | number | boolean
+    /** snake_case alias of `notEquals`. */
+    not_equals?: string | number | boolean
+    /** Hide options whose value equals this. */
+    notEquals?: string | number | boolean
+    /** Keep only options whose value is one of these. */
+    in?: Array<string | number | boolean>
+    /** Hide options whose value is one of these. */
+    not_in?: Array<string | number | boolean>
+    /** camelCase alias of `not_in`. */
+    notIn?: Array<string | number | boolean>
+}
+
+/** One rule, or a list of rules that must ALL pass (AND). */
+export type OptionFilter = OptionFilterRule | OptionFilterRule[]
+
+type FilterCarrier = { optionFilter?: unknown; option_filter?: unknown }
+
+/** Reads the filter from a field (camelCase or the snake_case the kernel serves). */
+export function getOptionFilter(field: unknown): OptionFilterRule[] {
+    if (!field || typeof field !== 'object') return []
+    const f = field as FilterCarrier
+    const raw = f.optionFilter ?? f.option_filter
+    const list = Array.isArray(raw) ? raw : raw && typeof raw === 'object' ? [raw] : []
+    return list.filter(
+        (r): r is OptionFilterRule =>
+            !!r && typeof r === 'object' && typeof (r as OptionFilterRule).field === 'string' && (r as OptionFilterRule).field !== '',
+    )
+}
+
+function norm(v: unknown): string {
+    return String(v).trim().toLowerCase()
+}
+
+function readProp(opt: ResolvedOption, key: string): unknown {
+    if (key === 'id' || key === 'value' || key === 'label' || key === 'name' || key === 'description' || key === 'color' || key === 'icon' || key === 'image') {
+        return (opt as unknown as Record<string, unknown>)[key]
+    }
+    return opt.meta?.[key]
+}
+
+/** True when the option satisfies the rule. Comparison is trimmed + case-insensitive. */
+export function optionPassesRule(opt: ResolvedOption, rule: OptionFilterRule): boolean {
+    const raw = readProp(opt, rule.field)
+    const known = raw !== undefined && raw !== null
+    const v = known ? norm(raw) : ''
+    const notEquals = rule.notEquals ?? rule.not_equals
+    const notIn = rule.notIn ?? rule.not_in
+    // Positive rules need the property to exist; negative rules cannot exclude
+    // what they cannot see, so an option lacking the property is kept.
+    if (rule.equals !== undefined && !(known && v === norm(rule.equals))) return false
+    if (Array.isArray(rule.in) && !(known && rule.in.some((x) => norm(x) === v))) return false
+    if (notEquals !== undefined && known && v === norm(notEquals)) return false
+    if (Array.isArray(notIn) && known && notIn.some((x) => norm(x) === v)) return false
+    return true
+}
+
+/**
+ * Applies the field's filter to resolved options. Returns the SAME array when
+ * there is nothing to filter. `keepValue` (the current selection) is never
+ * hidden, so an existing record keeps showing its label after the option
+ * became ineligible.
+ */
+export function applyOptionFilter(
+    options: ResolvedOption[],
+    rules: OptionFilterRule[],
+    keepValue?: unknown,
+): ResolvedOption[] {
+    if (rules.length === 0) return options
+    const keep = keepValue === undefined || keepValue === null || keepValue === '' ? null : String(keepValue)
+    return options.filter(
+        (o) => (keep !== null && String(o.id) === keep) || rules.every((r) => optionPassesRule(o, r)),
+    )
+}

package/src/org-runtime-context.ts

@@ -26,3 +26,13 @@ export const CurrencyContext = createContext<string | undefined>(undefined)
 
 /** Reads the nearest org currency (undefined outside a provider). */
 export const useCurrency = () => useContext(CurrencyContext)
+
+/**
+ * Org default tax rate as a fraction (e.g. `0.16`), from the org's fiscal
+ * config. Document line editors use it when the picked product carries no rate
+ * of its own. `undefined` outside a provider → lines start at 0.
+ */
+export const TaxRateContext = createContext<number | undefined>(undefined)
+
+/** Reads the nearest org default tax rate (undefined outside a provider). */
+export const useOrgTaxRate = () => useContext(TaxRateContext)

package/src/org-runtime-provider.tsx

@@ -12,13 +12,15 @@ import {
   identityImageUrl,
   type GetImageUrl,
 } from './image-url-context'
-import { CurrencyContext, TimeZoneContext } from './org-runtime-context'
+import { CurrencyContext, TaxRateContext, TimeZoneContext } from './org-runtime-context'
 
 export interface OrgRuntimeProviderProps {
   /** Org IANA timezone (e.g. `America/Mexico_City`). */
   timeZone?: string
   /** Org ISO-4217 currency (e.g. `MXN`). */
   currency?: string
+  /** Org default tax rate as a fraction (e.g. `0.16`) for document lines. */
+  taxRate?: number
   /** Resolver turning a stored path into a fetchable URL. Defaults to identity. */
   getImageUrl?: GetImageUrl
   children: ReactNode
@@ -27,6 +29,7 @@ export interface OrgRuntimeProviderProps {
 export function OrgRuntimeProvider({
   timeZone,
   currency,
+  taxRate,
   getImageUrl = identityImageUrl,
   children,
 }: OrgRuntimeProviderProps) {
@@ -34,7 +37,9 @@ export function OrgRuntimeProvider({
     <ImageUrlContext.Provider value={getImageUrl}>
       <TimeZoneContext.Provider value={timeZone}>
         <CurrencyContext.Provider value={currency}>
-          {children}
+          <TaxRateContext.Provider value={taxRate}>
+            {children}
+          </TaxRateContext.Provider>
         </CurrencyContext.Provider>
       </TimeZoneContext.Provider>
     </ImageUrlContext.Provider>

package/src/primitives/aging.ts

@@ -0,0 +1,76 @@
+// AgingTable — antigüedad de saldos (CxC y CxP) como función pura.
+//
+// customers ya guarda aging_1_30 … aging_90_plus por cliente (refresh_credit_file).
+// Esta función es la MISMA regla para la UI (drill-down por documento, CxP que
+// hoy no la tiene) y para reportes: un solo lugar decide qué es «corriente».
+import { roundMoney } from '../business/format'
+
+export interface AgingBucket {
+    key: string
+    label: string
+    /** Días vencidos desde (inclusive). `current` usa -Infinity..0. */
+    from: number
+    /** Días vencidos hasta (inclusive). `null` = sin tope. */
+    to: number | null
+}
+
+export const DEFAULT_AGING_BUCKETS: AgingBucket[] = [
+    { key: 'current', label: 'Corriente', from: Number.NEGATIVE_INFINITY, to: 0 },
+    { key: 'd1_30', label: '1–30', from: 1, to: 30 },
+    { key: 'd31_60', label: '31–60', from: 31, to: 60 },
+    { key: 'd61_90', label: '61–90', from: 61, to: 90 },
+    { key: 'd90_plus', label: '90+', from: 91, to: null },
+]
+
+export interface AgingDoc {
+    party_id: string
+    party_name?: string
+    due_at: string | null // ISO date; null = vence al emitir
+    issued_at: string
+    balance: number
+}
+
+export interface AgingRow {
+    party_id: string
+    party_name?: string
+    buckets: Record<string, number>
+    total: number
+    overdue: number
+    oldest_overdue_days: number
+}
+
+const DAY = 86_400_000
+
+/** Días vencidos al corte (negativo = falta para vencer). Fechas en ISO (día). */
+export function daysOverdue(dueISO: string, asOfISO: string): number {
+    const due = Date.parse(dueISO.slice(0, 10) + 'T00:00:00Z')
+    const asOf = Date.parse(asOfISO.slice(0, 10) + 'T00:00:00Z')
+    return Math.round((asOf - due) / DAY)
+}
+
+export function bucketFor(days: number, buckets: readonly AgingBucket[] = DEFAULT_AGING_BUCKETS): string {
+    for (const b of buckets) if (days >= b.from && (b.to === null || days <= b.to)) return b.key
+    return buckets[buckets.length - 1].key
+}
+
+/** Agrupa por contraparte y tramo. Saldos ≤ 0 se ignoran (anticipos van aparte). */
+export function computeAging(docs: readonly AgingDoc[], asOfISO: string, buckets: readonly AgingBucket[] = DEFAULT_AGING_BUCKETS): { rows: AgingRow[]; totals: Record<string, number>; total: number } {
+    const rows = new Map<string, AgingRow>()
+    const totals: Record<string, number> = Object.fromEntries(buckets.map(b => [b.key, 0]))
+    for (const d of docs) {
+        if (d.balance <= 0) continue
+        const days = daysOverdue(d.due_at ?? d.issued_at, asOfISO)
+        const key = bucketFor(days, buckets)
+        const row = rows.get(d.party_id) ?? { party_id: d.party_id, party_name: d.party_name, buckets: Object.fromEntries(buckets.map(b => [b.key, 0])), total: 0, overdue: 0, oldest_overdue_days: 0 }
+        row.buckets[key] = roundMoney(row.buckets[key] + d.balance)
+        row.total = roundMoney(row.total + d.balance)
+        if (days > 0) {
+            row.overdue = roundMoney(row.overdue + d.balance)
+            row.oldest_overdue_days = Math.max(row.oldest_overdue_days, days)
+        }
+        totals[key] = roundMoney(totals[key] + d.balance)
+        rows.set(d.party_id, row)
+    }
+    const list = [...rows.values()].sort((a, b) => b.overdue - a.overdue || b.total - a.total)
+    return { rows: list, totals, total: roundMoney(list.reduce((s, r) => s + r.total, 0)) }
+}

package/src/primitives/allocation.ts

@@ -0,0 +1,104 @@
+// PaymentAllocator — reglas puras para aplicar un pago a varios documentos
+// abiertos (CxC: facturas del cliente; CxP: facturas del proveedor).
+//
+// Lo usan: cobro multi-factura + REP (customers / fiscal_mexico), CxC
+// «Registrar abono», CxP «Aplicar pago», abonos de apartado. Sin React y sin
+// host: la UI (PaymentAllocator) y el backend (wasm) pueden validar con lo mismo.
+import { roundMoney } from '../business/format'
+
+/** Documento abierto con saldo. `installments_paid` = parcialidades previas vigentes. */
+export interface OpenDocument {
+    id: string
+    number: string
+    issued_at: string // ISO date
+    due_at?: string | null
+    total: number
+    balance: number
+    currency: string
+    /** `PPD` / `PUE` u otro: el núcleo no lo interpreta; fiscal_mexico sí. */
+    payment_method?: string | null
+    installments_paid?: number
+    /** Extensiones de país (UUID, serie…). Pasan intactas a la línea. */
+    extra?: Record<string, unknown>
+}
+
+export interface Allocation {
+    document_id: string
+    amount: number
+    /** Saldo anterior / pagado / insoluto: lo que pide el DoctoRelacionado del REP y el estado de cuenta. */
+    balance_before: number
+    balance_after: number
+    /** Número de parcialidad de ESTE pago para el documento (1-based). */
+    installment: number
+}
+
+export type AllocationStrategy = 'oldest_due_first' | 'oldest_issued_first' | 'manual'
+
+export interface AllocationResult {
+    allocations: Allocation[]
+    applied: number
+    unapplied: number
+}
+
+function sortKey(d: OpenDocument, s: AllocationStrategy): string {
+    return s === 'oldest_issued_first' ? d.issued_at : (d.due_at ?? d.issued_at)
+}
+
+/** Reparte `amount` sobre `docs` según la estrategia. `manual` respeta `manual[id]`. */
+export function allocatePayment(
+    amount: number,
+    docs: readonly OpenDocument[],
+    strategy: AllocationStrategy = 'oldest_due_first',
+    manual: Readonly<Record<string, number>> = {},
+): AllocationResult {
+    let left = roundMoney(Math.max(0, amount))
+    const ordered = strategy === 'manual' ? [...docs] : [...docs].sort((a, b) => sortKey(a, strategy).localeCompare(sortKey(b, strategy)))
+    const allocations: Allocation[] = []
+    for (const d of ordered) {
+        if (left <= 0) break
+        const balance = roundMoney(d.balance)
+        if (balance <= 0) continue
+        const want = strategy === 'manual' ? roundMoney(manual[d.id] ?? 0) : balance
+        const pay = roundMoney(Math.min(want, balance, left))
+        if (pay <= 0) continue
+        allocations.push({
+            document_id: d.id,
+            amount: pay,
+            balance_before: balance,
+            balance_after: roundMoney(balance - pay),
+            installment: (d.installments_paid ?? 0) + 1,
+        })
+        left = roundMoney(left - pay)
+    }
+    const applied = roundMoney(allocations.reduce((s, a) => s + a.amount, 0))
+    return { allocations, applied, unapplied: roundMoney(Math.max(0, amount) - applied) }
+}
+
+export interface AllocationIssue {
+    code: 'over_balance' | 'over_amount' | 'currency_mismatch' | 'unapplied' | 'non_positive'
+    document_id?: string
+    severity: 'error' | 'warning'
+}
+
+/** Revisión previa a guardar (la UI la pinta en ValidationChecklist; el backend la repite). */
+export function validateAllocation(
+    amount: number,
+    currency: string,
+    docs: readonly OpenDocument[],
+    allocations: readonly Allocation[],
+    opts: { allowUnapplied?: boolean } = {},
+): AllocationIssue[] {
+    const byId = new Map(docs.map(d => [d.id, d]))
+    const issues: AllocationIssue[] = []
+    if (amount <= 0) issues.push({ code: 'non_positive', severity: 'error' })
+    for (const a of allocations) {
+        const d = byId.get(a.document_id)
+        if (!d) continue
+        if (a.amount > roundMoney(d.balance) + 0.005) issues.push({ code: 'over_balance', document_id: d.id, severity: 'error' })
+        if (d.currency !== currency) issues.push({ code: 'currency_mismatch', document_id: d.id, severity: 'error' })
+    }
+    const applied = roundMoney(allocations.reduce((s, a) => s + a.amount, 0))
+    if (applied > roundMoney(amount) + 0.005) issues.push({ code: 'over_amount', severity: 'error' })
+    else if (applied < roundMoney(amount) - 0.005) issues.push({ code: 'unapplied', severity: opts.allowUnapplied ? 'warning' : 'error' })
+    return issues
+}

package/src/primitives/approvals.ts

@@ -0,0 +1,103 @@
+// ApprovalInbox — tipos y cliente de la bandeja de aprobaciones del kernel
+// (dynamic/approvals.go, rutas /approvals*). Una sola bandeja para TODO lo que
+// declare `supervisor_policy`, `approval` o un guard `on_violation:
+// request_approval`, sin importar el addon (descuentos, crédito, OC por monto,
+// cancelación CFDI, ajustes negativos…).
+import type { ApiClient } from '../api-context'
+
+/** Espejo de dynamic.ApprovalRequest (JSON). jsonb llega como string. */
+export interface ApprovalRequestDTO {
+    id: string
+    addon_key: string
+    model_key: string
+    record_id: string
+    action_key: string
+    constraint_key: string
+    kind: 'constraint' | 'action' | 'explicit' | 'pin'
+    label: string
+    status: 'pending' | 'approved' | 'applied' | 'failed' | 'rejected' | 'expired'
+    requested_by: string
+    requested_by_role: string
+    requested_at: string
+    expires_at: string | null
+    roles: string | string[]
+    reason_required: boolean
+    payload: string | Record<string, unknown>
+    snapshot: string | Record<string, unknown>
+    violation: string | Record<string, unknown>
+    decided_by: string | null
+    decided_at: string | null
+    reason: string
+    error: string
+}
+
+export interface ApprovalListQuery {
+    status?: ApprovalRequestDTO['status']
+    kind?: ApprovalRequestDTO['kind']
+    model?: string
+    /** Solo las que yo pedí. */
+    mine?: boolean
+    /** Solo las que mis roles pueden decidir (default de la bandeja). */
+    for_me?: boolean
+    page?: number
+    per_page?: number
+}
+
+/** Categoría visible en la bandeja. El mapeo policy → categoría es extensible por addons. */
+export interface ApprovalCategory {
+    key: string
+    label: string
+    icon?: string
+    /** Coincide si devuelve true (p. ej. por action_key, constraint_key o model_key). */
+    match: (r: ApprovalRequestDTO) => boolean
+}
+
+const categories: ApprovalCategory[] = []
+
+/** Los addons registran su categoría al cargar (purchases: «Compras», fiscal_mexico: «Cancelación CFDI»…). */
+export function registerApprovalCategory(c: ApprovalCategory): () => void {
+    categories.push(c)
+    return () => {
+        const i = categories.indexOf(c)
+        if (i >= 0) categories.splice(i, 1)
+    }
+}
+
+export function categorize(r: ApprovalRequestDTO): string {
+    return categories.find(c => c.match(r))?.key ?? 'other'
+}
+
+export function groupApprovals(items: readonly ApprovalRequestDTO[]): Record<string, ApprovalRequestDTO[]> {
+    const out: Record<string, ApprovalRequestDTO[]> = {}
+    for (const r of items) (out[categorize(r)] ??= []).push(r)
+    return out
+}
+
+export function parseJSONField<T = Record<string, unknown>>(v: string | T | null | undefined): T | null {
+    if (v == null || v === '') return null
+    if (typeof v !== 'string') return v
+    try {
+        return JSON.parse(v) as T
+    } catch {
+        return null
+    }
+}
+
+/** Cliente fino sobre las rutas del kernel; la UI lo usa vía useApi(). */
+export function approvalsClient(api: ApiClient) {
+    const qs = (q: ApprovalListQuery) =>
+        Object.entries(q)
+            .filter(([, v]) => v !== undefined && v !== '')
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+            .join('&')
+    return {
+        list: async (q: ApprovalListQuery = { status: 'pending', for_me: true }) => {
+            const res = await api.get(`/approvals?${qs(q)}`)
+            return { items: (res.data?.data ?? []) as ApprovalRequestDTO[], total: Number(res.data?.meta?.total ?? 0) }
+        },
+        count: async () => Number((await api.get('/approvals/count')).data?.data?.count ?? 0),
+        approve: (id: string, reason?: string) => api.post(`/approvals/${id}/approve`, { reason }),
+        reject: (id: string, reason: string) => api.post(`/approvals/${id}/reject`, { reason }),
+        approveWithPin: (id: string, pin: string, reason: string) => api.post(`/approvals/${id}/approve-pin`, { pin, reason }),
+    }
+}