@dainamite/cpq 0.2.2

package/src/modules/cpq/backend/cpq/wizards/[definitionCode]/page.tsx

@@ -0,0 +1,234 @@
+"use client"
+import * as React from 'react'
+import { useRouter, useSearchParams } from 'next/navigation'
+import { Alert } from '@open-mercato/ui/primitives/alert'
+import { WizardRunner } from '../../../../workflows/WizardRunner'
+import { registerBuiltInStepTypes } from '../../../../workflows/steps'
+import type { WizardDefinitionResult } from '../../../../workflows/types'
+
+// Register built-in step types once on module load
+registerBuiltInStepTypes()
+
+async function apiJson<T>(url: string): Promise<T> {
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`API error ${res.status}`)
+  return res.json() as Promise<T>
+}
+
+// ─── Params form shown before starting a wizard with required params ──
+
+type ParamsSchema = {
+  type?: string
+  required?: string[]
+  properties?: Record<string, { type?: string; format?: string; description?: string }>
+}
+
+function ParamsForm({
+  schema,
+  onStart,
+}: {
+  schema: ParamsSchema
+  onStart: (params: Record<string, string>) => void
+}) {
+  const properties = schema.properties ?? {}
+  const requiredFields = schema.required ?? []
+  const fieldNames = Object.keys(properties)
+
+  const [values, setValues] = React.useState<Record<string, string>>(() => {
+    const init: Record<string, string> = {}
+    for (const key of fieldNames) init[key] = ''
+    return init
+  })
+
+  const isValid = requiredFields.every((key) => values[key]?.trim())
+
+  return (
+    <div className="space-y-4">
+      <div className="rounded-lg border bg-muted/30 p-4 space-y-1">
+        <h4 className="text-sm font-medium">This wizard requires input parameters</h4>
+        <p className="text-xs text-muted-foreground">Fill in the required fields before starting.</p>
+      </div>
+
+      <div className="space-y-3">
+        {fieldNames.map((key) => {
+          const prop = properties[key]
+          const isRequired = requiredFields.includes(key)
+          return (
+            <div key={key}>
+              <label className="block text-sm font-medium mb-1">
+                {prop?.description || key}
+                {isRequired && <span className="text-destructive ml-0.5">*</span>}
+              </label>
+              <input
+                type="text"
+                value={values[key] ?? ''}
+                onChange={(e) => setValues((prev) => ({ ...prev, [key]: e.target.value }))}
+                placeholder={prop?.format === 'uuid' ? 'UUID' : key}
+                className="w-full rounded-md border px-3 py-2 text-sm font-mono"
+              />
+              {prop?.format && (
+                <p className="text-xs text-muted-foreground mt-0.5">Format: {prop.format}</p>
+              )}
+            </div>
+          )
+        })}
+      </div>
+
+      <button
+        type="button"
+        onClick={() => onStart(values)}
+        disabled={!isValid}
+        className="inline-flex items-center justify-center rounded-md bg-primary px-5 py-2 text-sm font-medium text-primary-foreground hover:bg-primary/90 disabled:opacity-50 disabled:cursor-not-allowed"
+      >
+        Preview Wizard
+      </button>
+    </div>
+  )
+}
+
+// ─── Main page ──────────────────────────────────────────────────
+
+export default function CpqWizardRunnerPage({ params }: { params: Record<string, string | string[]> }) {
+  const router = useRouter()
+  const searchParams = useSearchParams()
+  const definitionCode = params.definitionCode as string
+
+  const [definition, setDefinition] = React.useState<WizardDefinitionResult | null>(null)
+  const [loading, setLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+  const [started, setStarted] = React.useState(false)
+
+  // Parse launch params from query string
+  const queryParams = React.useMemo(() => {
+    const raw = searchParams.get('params')
+    if (!raw) return {}
+    try {
+      return JSON.parse(raw) as Record<string, unknown>
+    } catch {
+      return {}
+    }
+  }, [searchParams])
+
+  const [launchParams, setLaunchParams] = React.useState<Record<string, unknown>>(queryParams)
+
+  React.useEffect(() => {
+    async function load() {
+      if (!definitionCode || definitionCode === 'undefined') {
+        setError('Invalid wizard definition code')
+        setLoading(false)
+        return
+      }
+      setLoading(true)
+      setError(null)
+      try {
+        const def = await apiJson<WizardDefinitionResult>(
+          `/api/cpq/wizards?code=${encodeURIComponent(definitionCode)}`,
+        )
+        setDefinition(def)
+
+        // Auto-start if params were provided via query string or wizard has no required params
+        const schema = def.paramsSchema as ParamsSchema | null
+        const hasRequiredParams = schema?.required?.length
+        if (!hasRequiredParams || Object.keys(queryParams).length > 0) {
+          setStarted(true)
+        }
+      } catch (err) {
+        setError(err instanceof Error ? err.message : 'Failed to load wizard')
+      } finally {
+        setLoading(false)
+      }
+    }
+    load()
+  }, [definitionCode, queryParams])
+
+  const handleComplete = React.useCallback((stepData: Record<string, Record<string, unknown>>) => {
+    // Check for orderId first (e.g. purchasing wizard creates an order)
+    let orderId: string | undefined
+    let quoteId: string | undefined
+    for (const data of Object.values(stepData)) {
+      if (data.orderId && !orderId) orderId = data.orderId as string
+      if (data.quoteId && !quoteId) quoteId = data.quoteId as string
+    }
+    if (orderId) {
+      router.push(`/backend/cpq/orders/${orderId}`)
+    } else if (quoteId) {
+      router.push(`/backend/cpq/quotes/${quoteId}`)
+    } else {
+      router.push('/backend/cpq/wizards')
+    }
+  }, [router])
+
+  const handleParamsSubmit = React.useCallback((params: Record<string, string>) => {
+    setLaunchParams(params)
+    setStarted(true)
+  }, [])
+
+  if (loading) {
+    return <div className="text-sm text-muted-foreground">Loading wizard...</div>
+  }
+
+  if (error) {
+    return (
+      <div className="space-y-4">
+        <Alert variant="destructive">{error}</Alert>
+        <button
+          type="button"
+          onClick={() => router.push('/backend/cpq/wizards')}
+          className="inline-flex items-center justify-center rounded-md border px-4 py-2 text-sm font-medium hover:bg-muted"
+        >
+          Back to Wizards
+        </button>
+      </div>
+    )
+  }
+
+  if (!definition) {
+    return (
+      <div className="rounded-lg border bg-card p-6 text-center text-sm text-muted-foreground">
+        Wizard not found.
+      </div>
+    )
+  }
+
+  // Extract scope from auth context (will be provided by the framework at runtime)
+  // For now, use empty strings — the API routes resolve scope from the auth session
+  const scope = { organizationId: '', tenantId: '' }
+
+  return (
+    <div className="space-y-4 max-w-[900px] mx-auto">
+      <div className="flex items-center gap-3">
+        <button
+          type="button"
+          onClick={() => router.push('/backend/cpq/wizards')}
+          className="text-sm text-muted-foreground hover:text-foreground"
+        >
+          &larr; All Wizards
+        </button>
+      </div>
+
+      {!started ? (
+        <div className="space-y-4">
+          <div>
+            <h2 className="text-lg font-semibold">{definition.name}</h2>
+            {definition.description && (
+              <p className="text-sm text-muted-foreground mt-1">{definition.description}</p>
+            )}
+          </div>
+          <ParamsForm
+            schema={(definition.paramsSchema as ParamsSchema) ?? {}}
+            onStart={handleParamsSubmit}
+          />
+        </div>
+      ) : (
+        <WizardRunner
+          definition={definition}
+          params={launchParams}
+          initialQuoteId={launchParams.quoteId as string | undefined}
+          initialCustomerId={launchParams.customerId as string | undefined}
+          scope={scope}
+          onComplete={handleComplete}
+        />
+      )}
+    </div>
+  )
+}

package/src/modules/cpq/backend/cpq/wizards/page.meta.ts

@@ -0,0 +1,16 @@
+import React from 'react'
+import { Wand2 } from 'lucide-react'
+
+const wizardsIcon = React.createElement(Wand2, { size: 16 })
+
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['cpq.wizards.view'],
+  pageTitle: 'Wizards',
+  pageTitleKey: 'cpq.wizards.title',
+  pageGroup: 'CPQ',
+  pageGroupKey: 'customers~sales~cpq.nav.group',
+  pageOrder: 35,
+  icon: wizardsIcon,
+  breadcrumb: [{ label: 'Wizards', labelKey: 'cpq.wizards.title' }],
+} as const

package/src/modules/cpq/backend/cpq/wizards/page.tsx

@@ -0,0 +1,141 @@
+"use client"
+import * as React from 'react'
+import { useRouter } from 'next/navigation'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import type { ColumnDef } from '@tanstack/react-table'
+import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { CpqListView, useCpqListData } from '../../../components/CpqListView'
+
+type WizardDefinition = {
+  id: string
+  code: string
+  name: string
+  description: string | null
+  version: number
+  surface: string
+  isActive: boolean
+  steps: Array<{ stepId: string; type: string; title: string }>
+  createdAt: string
+}
+
+const PAGE_SIZE = 50
+
+function buildFilterParams(values: FilterValues, params: URLSearchParams) {
+  if (typeof values.surface === 'string' && values.surface.trim()) {
+    params.set('surface', values.surface.trim())
+  }
+  if (values.isActive === true) params.set('isActive', 'true')
+  if (values.isActive === false) params.set('isActive', 'false')
+}
+
+export default function CpqWizardsPage() {
+  const router = useRouter()
+  const t = useT()
+
+  const data = useCpqListData<WizardDefinition>({
+    endpoint: '/api/cpq/wizards',
+    pageSize: PAGE_SIZE,
+    buildFilterParams,
+    loadErrorMessage: t('cpq.wizards.list.error.load', 'Failed to load wizards'),
+  })
+
+  const filters = React.useMemo<FilterDef[]>(
+    () => [
+      {
+        id: 'surface',
+        label: t('cpq.wizards.filters.surface', 'Surface'),
+        type: 'text',
+      },
+      {
+        id: 'isActive',
+        label: t('cpq.wizards.filters.isActive', 'Active'),
+        type: 'checkbox',
+      },
+    ],
+    [t],
+  )
+
+  const handlePreviewWizard = React.useCallback(
+    (definitionCode: string) => {
+      router.push(`/backend/cpq/wizards/${definitionCode}`)
+    },
+    [router],
+  )
+
+  const columns = React.useMemo<ColumnDef<WizardDefinition>[]>(
+    () => [
+      {
+        accessorKey: 'name',
+        header: t('cpq.wizards.table.name', 'Name'),
+        cell: ({ row }) => <span className="font-medium">{row.original.name}</span>,
+      },
+      {
+        accessorKey: 'code',
+        header: t('cpq.wizards.table.code', 'Code'),
+        cell: ({ row }) => <span className="font-mono text-xs">{row.original.code}</span>,
+      },
+      {
+        accessorKey: 'surface',
+        header: t('cpq.wizards.table.surface', 'Surface'),
+      },
+      {
+        id: 'steps',
+        header: t('cpq.wizards.table.steps', 'Steps'),
+        cell: ({ row }) => <span>{row.original.steps.length}</span>,
+      },
+      {
+        id: 'version',
+        header: t('cpq.wizards.table.version', 'Version'),
+        cell: ({ row }) => <span>v{row.original.version}</span>,
+      },
+      {
+        accessorKey: 'isActive',
+        header: t('cpq.wizards.table.active', 'Active'),
+        cell: ({ row }) => (
+          <Tag variant={row.original.isActive ? 'success' : 'neutral'} dot>
+            {row.original.isActive ? 'Yes' : 'No'}
+          </Tag>
+        ),
+      },
+    ],
+    [t],
+  )
+
+  return (
+    <CpqListView<WizardDefinition>
+      title={t('cpq.wizards.list.title', 'Wizards')}
+      tableId="cpq.wizards.list"
+      data={data}
+      columns={columns}
+      filters={filters}
+      pageSize={PAGE_SIZE}
+      searchPlaceholder={t('cpq.wizards.search.placeholder', 'Search wizards...')}
+      onRowClick={(row) => router.push(`/backend/cpq/wizards/${row.code}/detail`)}
+      // Wizards are read-only in the admin UI for now: no Edit / Delete
+      // entries — only `Preview` (run the wizard) and `View details`.
+      rowActions={(row) => (
+        <RowActions
+          items={[
+            {
+              id: 'preview',
+              label: t('cpq.wizards.actions.preview', 'Preview'),
+              onSelect: () => handlePreviewWizard(row.code),
+            },
+            {
+              id: 'details',
+              label: t('cpq.wizards.actions.details', 'View details'),
+              href: `/backend/cpq/wizards/${row.code}/detail`,
+            },
+          ]}
+        />
+      )}
+      emptyState={
+        <div className="rounded-lg border bg-card p-6 text-center text-sm text-muted-foreground">
+          {t('cpq.wizards.empty', 'No wizard definitions yet. Create one via the API.')}
+        </div>
+      }
+    />
+  )
+}

package/src/modules/cpq/ce.ts

@@ -0,0 +1,150 @@
+import type { CustomEntitySpec } from '@open-mercato/shared/modules/entities'
+
+const entities: CustomEntitySpec[] = [
+  {
+    id: 'cpq:cpq_product_specification',
+    label: 'Product Specification',
+    description: 'CPQ product blueprint — defines attributes, dependencies, and relationships.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_product_offering',
+    label: 'Product Offering',
+    description: 'Sellable instance of a product specification with design-time values and charges.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_product_relationship',
+    label: 'Product Relationship',
+    description: 'Structural relationship between product specifications (parent_child, requires, excludes).',
+    labelField: 'id',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_product_attribute',
+    label: 'Product Attribute',
+    description: 'Configurable attribute definition for a CPQ product.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_product_charge',
+    label: 'Product Charge',
+    description: 'Charge definition (NRC/MRC/usage) for a CPQ product.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_pricing_table',
+    label: 'Pricing Table',
+    description: 'Multi-dimensional pricing table with named price columns.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_pricing_table_entry',
+    label: 'Pricing Table Entry',
+    description: 'Individual row in a pricing table with dimension values and prices.',
+    labelField: 'id',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_price_rule',
+    label: 'Price Rule',
+    description: 'Post-calculation price adjustment rule (discount, surcharge, override).',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_bundle_slot',
+    label: 'Bundle Slot',
+    description: 'Structural slot within a bundle specification — defines what component specs can fill it.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_offering_component',
+    label: 'Offering Component',
+    description: 'Links a bundle offering to a specific component offering within a slot.',
+    labelField: 'id',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_quote_configuration',
+    label: 'Quote Configuration',
+    description: 'CPQ-specific configuration data for a sales quote.',
+    labelField: 'id',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_quote_line_configuration',
+    label: 'Quote Line Configuration',
+    description: 'CPQ-specific configuration for a sales quote line (one per offering).',
+    labelField: 'id',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_wizard_definition',
+    label: 'Wizard Definition',
+    description: 'CPQ wizard definition — multi-step guided quoting flow.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_inventory_subscription',
+    label: 'Inventory Subscription',
+    description: 'Commercial wrapper grouping subscription items under shared contractual terms.',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_inventory_subscription_item',
+    label: 'Inventory Subscription Item',
+    description: 'Concrete product/service record within an inventory subscription.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_inventory_asset',
+    label: 'Inventory Asset',
+    description: 'Tangible or intangible thing the customer owns — hardware, licenses, fees.',
+    labelField: 'name',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_order_configuration',
+    label: 'Order Configuration',
+    description: 'CPQ-specific configuration data for a sales order.',
+    labelField: 'id',
+    showInSidebar: false,
+    fields: [],
+  },
+  {
+    id: 'cpq:cpq_order_line_configuration',
+    label: 'Order Line Configuration',
+    description: 'CPQ-specific configuration for a sales order line (one per offering).',
+    labelField: 'id',
+    showInSidebar: false,
+    fields: [],
+  },
+]
+
+export { entities }
+export default entities

package/src/modules/cpq/cli.ts

@@ -0,0 +1,10 @@
+import type { ModuleCli } from '@open-mercato/shared/modules/registry'
+
+const seedCommand: ModuleCli = {
+  command: 'seed',
+  async run() {
+    console.log('CPQ seed: no default seed data. Configure specifications, offerings, and pricing via the admin UI.')
+  },
+}
+
+export default [seedCommand]