@open-mercato/core 0.7.1-develop.7193.1.910a5b0a1e → 0.7.1-develop.7195.1.b5efd1d51a

package/src/modules/workflows/examples/templates/task-escalation.json

@@ -0,0 +1,110 @@
+{
+  "id": "task-escalation",
+  "nameKey": "workflows.templates.task-escalation.name",
+  "descriptionKey": "workflows.templates.task-escalation.description",
+  "category": "Operations",
+  "icon": "alarm-clock",
+  "definition": {
+    "steps": [
+      {
+        "stepId": "start",
+        "stepName": "Start",
+        "stepType": "START",
+        "description": "A task that must be handled within its SLA"
+      },
+      {
+        "stepId": "review_task",
+        "stepName": "Review Task",
+        "stepType": "USER_TASK",
+        "description": "Handle the task before the deadline",
+        "userTaskConfig": {
+          "assignedTo": ["support"],
+          "formSchema": {
+            "type": "object",
+            "required": ["resolution"],
+            "properties": {
+              "resolution": {
+                "enum": ["resolved", "escalate"],
+                "type": "string",
+                "title": "Resolution",
+                "description": "Resolve the task or escalate it"
+              },
+              "notes": {
+                "type": "string",
+                "title": "Notes",
+                "description": "Resolution or escalation notes"
+              }
+            }
+          },
+          "slaDuration": "PT8H",
+          "escalationRules": [
+            { "trigger": "sla_breach", "action": "escalate" }
+          ]
+        }
+      },
+      {
+        "stepId": "notify_escalation",
+        "stepName": "Notify Escalation",
+        "stepType": "AUTOMATED",
+        "description": "Alert the escalation channel"
+      },
+      {
+        "stepId": "end",
+        "stepName": "Done",
+        "stepType": "END",
+        "description": "Task closed"
+      }
+    ],
+    "transitions": [
+      {
+        "transitionId": "start_to_review",
+        "transitionName": "Assign Task",
+        "fromStepId": "start",
+        "toStepId": "review_task",
+        "trigger": "auto",
+        "priority": 100
+      },
+      {
+        "transitionId": "review_to_end",
+        "transitionName": "Resolved",
+        "fromStepId": "review_task",
+        "toStepId": "end",
+        "trigger": "auto",
+        "priority": 100
+      },
+      {
+        "transitionId": "review_to_escalation",
+        "transitionName": "Escalate",
+        "fromStepId": "review_task",
+        "toStepId": "notify_escalation",
+        "trigger": "auto",
+        "priority": 90,
+        "activities": [
+          {
+            "activityId": "emit_task_escalated",
+            "activityName": "Emit Task Escalated Event",
+            "activityType": "EMIT_EVENT",
+            "async": true,
+            "config": {
+              "eventName": "workflows.task.escalated",
+              "payload": {
+                "taskId": "{{context.taskId}}",
+                "workflowInstanceId": "{{workflow.instanceId}}",
+                "notes": "{{context.notes}}"
+              }
+            }
+          }
+        ]
+      },
+      {
+        "transitionId": "escalation_to_end",
+        "transitionName": "Close After Escalation",
+        "fromStepId": "notify_escalation",
+        "toStepId": "end",
+        "trigger": "auto",
+        "priority": 100
+      }
+    ],
+    "triggers": []
+  }
+}

package/src/modules/workflows/examples/templates/webhook-integration.json

@@ -0,0 +1,113 @@
+{
+  "id": "webhook-integration",
+  "nameKey": "workflows.templates.webhook-integration.name",
+  "descriptionKey": "workflows.templates.webhook-integration.description",
+  "category": "Integrations",
+  "icon": "webhook",
+  "definition": {
+    "steps": [
+      {
+        "stepId": "start",
+        "stepName": "Start",
+        "stepType": "START",
+        "description": "A domain event that should reach an external system"
+      },
+      {
+        "stepId": "notify_external",
+        "stepName": "Notify External System",
+        "stepType": "AUTOMATED",
+        "description": "Deliver the payload to the external endpoint"
+      },
+      {
+        "stepId": "record_delivery",
+        "stepName": "Record Delivery",
+        "stepType": "AUTOMATED",
+        "description": "Track that the delivery went out"
+      },
+      {
+        "stepId": "end",
+        "stepName": "Delivered",
+        "stepType": "END",
+        "description": "External system notified"
+      }
+    ],
+    "transitions": [
+      {
+        "transitionId": "start_to_notify",
+        "transitionName": "Call Webhook",
+        "fromStepId": "start",
+        "toStepId": "notify_external",
+        "trigger": "auto",
+        "priority": 100,
+        "activities": [
+          {
+            "activityId": "call_external_webhook",
+            "activityName": "Call External Webhook",
+            "activityType": "CALL_WEBHOOK",
+            "async": true,
+            "config": {
+              "url": "https://example.com/webhooks/orders",
+              "method": "POST",
+              "headers": { "Content-Type": "application/json" },
+              "body": {
+                "orderId": "{{context.id}}",
+                "workflowInstanceId": "{{workflow.instanceId}}",
+                "sentAt": "{{now}}"
+              }
+            },
+            "retryPolicy": {
+              "maxAttempts": 3,
+              "initialIntervalMs": 1000,
+              "backoffCoefficient": 2,
+              "maxIntervalMs": 10000
+            }
+          }
+        ]
+      },
+      {
+        "transitionId": "notify_to_record",
+        "transitionName": "Record Delivery",
+        "fromStepId": "notify_external",
+        "toStepId": "record_delivery",
+        "trigger": "auto",
+        "priority": 100,
+        "activities": [
+          {
+            "activityId": "record_delivery_state",
+            "activityName": "Record Delivery State",
+            "activityType": "SET_VARIABLE",
+            "config": {
+              "assignments": [
+                { "path": "webhookDelivered", "value": true },
+                { "path": "webhookDeliveredAt", "value": "{{now}}" }
+              ]
+            }
+          }
+        ]
+      },
+      {
+        "transitionId": "record_to_end",
+        "transitionName": "Finish",
+        "fromStepId": "record_delivery",
+        "toStepId": "end",
+        "trigger": "auto",
+        "priority": 100
+      }
+    ],
+    "triggers": [
+      {
+        "triggerId": "order_created_trigger",
+        "name": "Order Created Trigger",
+        "description": "Notifies the external system when a new sales order is created",
+        "eventPattern": "sales.order.created",
+        "config": {
+          "contextMapping": [
+            { "targetKey": "id", "sourceExpression": "payload.id" }
+          ]
+        },
+        "enabled": true,
+        "priority": 0
+      }
+    ]
+  }
+}

package/src/modules/workflows/extension-points.ts

@@ -5,7 +5,7 @@ export const extensionPoints = defineModuleExtensionPoints({
   hosts: {
     definitionsTable: dataTableExtensionHost({ tableId: 'workflows.definitions.list', source: 'backend/definitions/page.tsx' }),
     instancesTable: dataTableExtensionHost({ tableId: 'workflows.instances.list', source: 'backend/instances/page.tsx' }),
-    tasksTable: dataTableExtensionHost({ tableId: 'workflows.tasks.list', source: 'backend/tasks/page.tsx' }),
+    tasksTable: dataTableExtensionHost({ tableId: 'workflows.tasks.list', source: 'backend/work-inbox/page.tsx' }),
   },
 })
 

package/src/modules/workflows/frontend/[orgSlug]/portal/tasks/[id]/page.meta.ts

@@ -0,0 +1,21 @@
+import type { PageMetadata } from '@open-mercato/shared/modules/registry'
+
+/**
+ * No `nav` block: a detail page is reached from the list, not from the sidebar.
+ * The guards are NOT optional for that reason — the catch-all is the only thing
+ * standing between a deep link and the page, and a missing `page.meta.ts` makes
+ * it public rather than merely unlisted.
+ *
+ * `portal.tasks.view`, not `.complete`: reading a task and finishing it are
+ * different grants, and the page renders read-only for a principal who holds
+ * only the first. The completion API enforces `.complete` independently — the
+ * page guard is defence in depth, never the authorization.
+ */
+export const metadata: PageMetadata = {
+  requireCustomerAuth: true,
+  requireCustomerFeatures: ['portal.tasks.view'],
+  titleKey: 'workflows.portal.tasks.detail.title',
+  title: 'Task',
+}
+
+export default metadata

package/src/modules/workflows/frontend/[orgSlug]/portal/tasks/[id]/page.tsx

@@ -0,0 +1,212 @@
+'use client'
+
+/**
+ * Portal task detail + completion.
+ *
+ * `canComplete` comes from the API, not from anything this page computes: a
+ * portal admin reading a company member's task gets `false` and sees the work
+ * read-only. The completion route enforces the same answer independently, so
+ * hiding the form is a courtesy and never the control.
+ */
+
+import * as React from 'react'
+import Link from 'next/link'
+import { useRouter } from 'next/navigation'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { Badge } from '@open-mercato/ui/primitives/badge'
+import { PortalPageHeader } from '@open-mercato/ui/portal/components/PortalPageHeader'
+import { PortalCard } from '@open-mercato/ui/portal/components/PortalCard'
+import { usePortalAppEvent } from '@open-mercato/ui/portal/hooks/usePortalAppEvent'
+import { PortalTaskForm, type PortalTaskFormValue } from '../../../../../components/portal/PortalTaskForm'
+import { flattenTaskText } from '../../../../../lib/task-resolution'
+
+type PortalTaskDetail = {
+  id: string
+  taskName: string
+  description: string | null
+  status: string
+  dueDate: string | null
+  formSchema: unknown
+  formData: unknown
+  entityBindings: unknown[] | null
+}
+
+type PortalTaskDetailResponse = {
+  ok: boolean
+  task?: PortalTaskDetail
+  decisions?: Array<{ id: string; label: unknown }>
+  formKey?: string | null
+  canComplete?: boolean
+  error?: string
+}
+
+const OPEN_STATUSES = ['PENDING', 'IN_PROGRESS']
+
+type Props = { params: { orgSlug: string; id: string } }
+
+export default function PortalTaskDetailPage({ params }: Props) {
+  const t = useT()
+  const router = useRouter()
+
+  const [detail, setDetail] = React.useState<PortalTaskDetailResponse | null>(null)
+  const [notFound, setNotFound] = React.useState(false)
+  const [values, setValues] = React.useState<Record<string, PortalTaskFormValue>>({})
+  const [comments, setComments] = React.useState('')
+  const [submitting, setSubmitting] = React.useState(false)
+  const [failure, setFailure] = React.useState<'load' | 'submit' | null>(null)
+
+  const listHref = `/${params.orgSlug}/portal/tasks`
+
+  // Depends on the id alone. The failure copy is translated at render rather
+  // than stored, so a `t` that changes identity cannot re-run this effect.
+  const load = React.useCallback(async () => {
+    const { ok, status, result } = await apiCall<PortalTaskDetailResponse>(
+      `/api/workflows/portal/tasks/${encodeURIComponent(params.id)}`,
+    )
+    if (status === 404) {
+      setNotFound(true)
+      return
+    }
+    if (!ok || !result?.ok) {
+      setFailure('load')
+      return
+    }
+    setDetail(result)
+  }, [params.id])
+
+  React.useEffect(() => {
+    void load()
+  }, [load])
+
+  usePortalAppEvent('workflows.task.portal_assigned', () => {
+    void load()
+  }, [load])
+
+  const task = detail?.task ?? null
+  const decisions = React.useMemo(
+    () =>
+      (detail?.decisions ?? []).map((decision) => ({
+        id: decision.id,
+        label: flattenTaskText(decision.label as never) ?? decision.id,
+      })),
+    [detail?.decisions],
+  )
+
+  const handleSubmit = React.useCallback(
+    async (decisionId?: string) => {
+      if (!task) return
+      setSubmitting(true)
+      setFailure(null)
+      const { ok, result } = await apiCall<{ ok: boolean; error?: string }>(
+        `/api/workflows/portal/tasks/${encodeURIComponent(task.id)}/complete`,
+        {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            formData: values,
+            ...(comments ? { comments } : {}),
+            ...(decisionId ? { decisionId } : {}),
+          }),
+        },
+      )
+      setSubmitting(false)
+      if (!ok || !result?.ok) {
+        setFailure('submit')
+        return
+      }
+      router.push(listHref)
+    },
+    [task, values, comments, router, listHref],
+  )
+
+  if (notFound) {
+    return (
+      <div className="flex flex-col gap-6">
+        <PortalPageHeader title={t('workflows.portal.tasks.detail.notFound', 'Task not available')} />
+        <PortalCard>
+          <p className="text-sm text-muted-foreground">
+            {t(
+              'workflows.portal.tasks.detail.notFoundBody',
+              'This task is not available to you. It may have been completed or reassigned.',
+            )}
+          </p>
+          <Link
+            href={listHref}
+            className="mt-4 inline-block text-sm font-medium underline underline-offset-4"
+          >
+            {t('workflows.portal.tasks.detail.back', 'Back to tasks')}
+          </Link>
+        </PortalCard>
+      </div>
+    )
+  }
+
+  if (!detail || !task) {
+    return (
+      <div className="flex items-center justify-center py-20">
+        <Spinner />
+      </div>
+    )
+  }
+
+  const isOpen = OPEN_STATUSES.includes(task.status)
+  const canComplete = detail.canComplete === true && isOpen
+
+  return (
+    <div className="flex flex-col gap-8">
+      <PortalPageHeader
+        label={t('workflows.portal.tasks.label', 'Your work')}
+        title={task.taskName}
+        description={task.description ?? undefined}
+        action={
+          <Badge variant="outline" className="text-overline">
+            {t(`workflows.portal.tasks.status.${task.status}`, task.status)}
+          </Badge>
+        }
+      />
+
+      <PortalCard>
+        {canComplete ? (
+          <PortalTaskForm
+            taskId={task.id}
+            taskName={task.taskName}
+            formSchema={task.formSchema}
+            formKey={detail.formKey ?? null}
+            entityBindings={task.entityBindings}
+            decisions={decisions}
+            values={values}
+            comments={comments}
+            submitting={submitting}
+            onFieldChange={(name, value) => setValues((current) => ({ ...current, [name]: value }))}
+            onValuesChange={setValues}
+            onCommentsChange={setComments}
+            onSubmit={handleSubmit}
+          />
+        ) : (
+          <p className="text-sm text-muted-foreground">
+            {isOpen
+              ? t(
+                  'workflows.portal.tasks.detail.readOnly',
+                  'You can see this task because it belongs to your company. Only the person it is assigned to can complete it.',
+                )
+              : t('workflows.portal.tasks.detail.closed', 'This task is already finished.')}
+          </p>
+        )}
+
+        {failure ? (
+          <p role="alert" className="mt-4 text-sm text-status-error-text">
+            {failure === 'submit'
+              ? t('workflows.portal.tasks.submitError', 'Could not submit this task.')
+              : t('workflows.portal.tasks.loadError', 'Could not load your tasks.')}
+          </p>
+        ) : null}
+      </PortalCard>
+
+      <Link href={listHref} className="text-sm font-medium underline underline-offset-4">
+        {t('workflows.portal.tasks.detail.back', 'Back to tasks')}
+      </Link>
+    </div>
+  )
+}

package/src/modules/workflows/frontend/[orgSlug]/portal/tasks/page.meta.ts

@@ -0,0 +1,25 @@
+import type { PageMetadata } from '@open-mercato/shared/modules/registry'
+
+/**
+ * The ONLY enforcement point for this page.
+ *
+ * The `(frontend)` catch-all reads this file to guard the route; a portal page
+ * without a sibling `page.meta.ts` is not "unguarded by default", it is
+ * SILENTLY PUBLIC. The `nav` block is what lists the page in the portal sidebar,
+ * RBAC-filtered by the same feature — so granting `portal.tasks.view` is all it
+ * takes for the entry to appear, with no menu-injection widget.
+ */
+export const metadata: PageMetadata = {
+  requireCustomerAuth: true,
+  requireCustomerFeatures: ['portal.tasks.view'],
+  titleKey: 'workflows.portal.tasks.title',
+  title: 'Tasks',
+  nav: {
+    label: 'Tasks',
+    labelKey: 'workflows.portal.tasks.nav',
+    group: 'main',
+    order: 40,
+  },
+}
+
+export default metadata

package/src/modules/workflows/frontend/[orgSlug]/portal/tasks/page.tsx

@@ -0,0 +1,185 @@
+'use client'
+
+/**
+ * Portal task list.
+ *
+ * Reads `/api/workflows/portal/tasks`, which is the authorization — this page
+ * renders whatever that route returns and decides nothing itself. A row that
+ * should not be here is a route bug, never a rendering bug, and keeping the
+ * decision out of the browser is what makes that true.
+ *
+ * `usePortalAppEvent('workflows.task.portal_assigned', …)` refetches when a task
+ * is addressed to this principal, so it appears without a reload. The event
+ * carries an id and nothing else; the answer always comes back through the
+ * authorized API.
+ */
+
+import * as React from 'react'
+import Link from 'next/link'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { Badge } from '@open-mercato/ui/primitives/badge'
+import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
+import { PortalPageHeader } from '@open-mercato/ui/portal/components/PortalPageHeader'
+import { PortalCard } from '@open-mercato/ui/portal/components/PortalCard'
+import { usePortalAppEvent } from '@open-mercato/ui/portal/hooks/usePortalAppEvent'
+
+type PortalTaskRow = {
+  id: string
+  taskName: string
+  description: string | null
+  status: string
+  dueDate: string | null
+  createdAt: string
+}
+
+type PortalTaskListResponse = {
+  ok: boolean
+  tasks?: PortalTaskRow[]
+  error?: string
+}
+
+const OPEN_STATUSES = ['PENDING', 'IN_PROGRESS']
+
+type Props = { params: { orgSlug: string } }
+
+export default function PortalTasksPage({ params }: Props) {
+  const t = useT()
+  const [tasks, setTasks] = React.useState<PortalTaskRow[] | null>(null)
+  const [failed, setFailed] = React.useState(false)
+
+  // Deliberately depends on NOTHING. `t` is not a dependency because the error
+  // copy is translated at render, not stored — a `t` that changes identity
+  // between renders would otherwise re-run the effect and refetch in a loop.
+  const load = React.useCallback(async () => {
+    setFailed(false)
+    const { ok, result } = await apiCall<PortalTaskListResponse>('/api/workflows/portal/tasks')
+    if (!ok || !result?.ok) {
+      setFailed(true)
+      setTasks([])
+      return
+    }
+    setTasks(result.tasks ?? [])
+  }, [])
+
+  React.useEffect(() => {
+    void load()
+  }, [load])
+
+  usePortalAppEvent('workflows.task.portal_assigned', () => {
+    void load()
+  }, [load])
+
+  const openTasks = React.useMemo(
+    () => (tasks ?? []).filter((task) => OPEN_STATUSES.includes(task.status)),
+    [tasks],
+  )
+  const doneTasks = React.useMemo(
+    () => (tasks ?? []).filter((task) => !OPEN_STATUSES.includes(task.status)),
+    [tasks],
+  )
+
+  const formatDate = (value: string | null) => {
+    if (!value) return null
+    return new Date(value).toLocaleDateString(undefined, {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+    })
+  }
+
+  const renderRow = (task: PortalTaskRow) => {
+    const due = formatDate(task.dueDate)
+    const isOverdue =
+      task.dueDate != null &&
+      OPEN_STATUSES.includes(task.status) &&
+      new Date(task.dueDate).getTime() < Date.now()
+
+    return (
+      <Link
+        key={task.id}
+        href={`/${params.orgSlug}/portal/tasks/${task.id}`}
+        className="block rounded-lg border p-4 transition-colors hover:bg-muted/50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <div className="flex flex-col gap-2 sm:flex-row sm:items-start sm:justify-between">
+          <div className="min-w-0">
+            <p className="truncate font-medium">{task.taskName}</p>
+            {task.description ? (
+              <p className="mt-0.5 line-clamp-2 text-sm text-muted-foreground">{task.description}</p>
+            ) : null}
+          </div>
+          <div className="flex shrink-0 flex-wrap items-center gap-2">
+            {due ? (
+              // Status is never colour-only: the overdue row carries its own
+              // word alongside the token.
+              <Badge variant={isOverdue ? 'destructive' : 'outline'} className="text-overline">
+                {isOverdue
+                  ? t('workflows.portal.tasks.overdue', 'Overdue {date}', { date: due })
+                  : t('workflows.portal.tasks.due', 'Due {date}', { date: due })}
+              </Badge>
+            ) : null}
+            <Badge variant="outline" className="text-overline">
+              {t(`workflows.portal.tasks.status.${task.status}`, task.status)}
+            </Badge>
+          </div>
+        </div>
+      </Link>
+    )
+  }
+
+  return (
+    <div className="flex flex-col gap-8">
+      <PortalPageHeader
+        label={t('workflows.portal.tasks.label', 'Your work')}
+        title={t('workflows.portal.tasks.title', 'Tasks')}
+        description={t(
+          'workflows.portal.tasks.description',
+          'Things we need from you to move your orders along.',
+        )}
+      />
+
+      {tasks === null ? (
+        <div className="flex items-center justify-center py-20">
+          <Spinner />
+        </div>
+      ) : failed ? (
+        <PortalCard>
+          <p role="alert" className="text-sm text-status-error-text">
+            {t('workflows.portal.tasks.loadError', 'Could not load your tasks.')}
+          </p>
+        </PortalCard>
+      ) : openTasks.length === 0 && doneTasks.length === 0 ? (
+        <EmptyState
+          variant="subtle"
+          size="lg"
+          title={t('workflows.portal.tasks.empty.title', 'Nothing needs you right now')}
+          description={t(
+            'workflows.portal.tasks.empty.description',
+            'When we need something from you, it will show up here.',
+          )}
+        />
+      ) : (
+        <div className="flex flex-col gap-6">
+          {openTasks.length > 0 ? (
+            <PortalCard>
+              <h2 className="mb-4 text-base font-semibold tracking-tight">
+                {t('workflows.portal.tasks.open', 'Waiting on you')}
+              </h2>
+              <div className="flex flex-col gap-3">{openTasks.map(renderRow)}</div>
+            </PortalCard>
+          ) : null}
+
+          {doneTasks.length > 0 ? (
+            <PortalCard>
+              <h2 className="mb-4 text-base font-semibold tracking-tight">
+                {t('workflows.portal.tasks.done', 'Completed')}
+              </h2>
+              <div className="flex flex-col gap-3">{doneTasks.map(renderRow)}</div>
+            </PortalCard>
+          ) : null}
+        </div>
+      )}
+    </div>
+  )
+}