@quotivity/cpq-inventory-core 0.1.0

package/lib/extract/records.js

@@ -0,0 +1,327 @@
+/**
+ * Record shapes and field lists, one per object the tool reads. Field names follow the schema
+ * notes in the spec (verified against CPQ package v67). Do not "tidy" them: several look wrong
+ * and are not (TargetObject__c is the evaluation scope; Field__c means different things on
+ * PriceCondition and PriceAction; PriceCondition and ErrorCondition are not field-compatible).
+ */
+export const AUDIT = ['Id', 'LastModifiedDate', 'CreatedById', 'CreatedDate'];
+export const PRODUCT2_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'ProductCode',
+    'IsActive',
+    'SBQQ__PricingMethod__c',
+    'SBQQ__SubscriptionPricing__c',
+    'SBQQ__SubscriptionTerm__c',
+    'SBQQ__ChargeType__c',
+    'SBQQ__NonDiscountable__c',
+    'SBQQ__PriceEditable__c',
+    'SBQQ__OptionSelectionMethod__c',
+    'SBQQ__ConfigurationType__c',
+];
+export const PRICEBOOK2_FIELDS = [...AUDIT, 'Name', 'IsActive', 'IsStandard'];
+export const CURRENCY_FIELDS = ['Id', 'IsoCode', 'IsActive', 'IsCorporate'];
+export const DCR_FIELDS = ['Id', 'IsoCode', 'StartDate', 'NextStartDate', 'ConversionRate'];
+export const FEATURE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__ConfiguredSKU__c',
+    'SBQQ__MinOptionCount__c',
+    'SBQQ__MaxOptionCount__c',
+    'SBQQ__Number__c',
+];
+export const OPTION_FIELDS = [
+    ...AUDIT,
+    'SBQQ__ConfiguredSKU__c',
+    'SBQQ__OptionalSKU__c',
+    'SBQQ__Feature__c',
+    'SBQQ__Selected__c',
+    'SBQQ__Required__c',
+    'SBQQ__Type__c',
+    'SBQQ__Number__c',
+];
+export const CONSTRAINT_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Type__c',
+    'SBQQ__ConfiguredSKU__c',
+    'SBQQ__ConstrainedOption__c',
+    'SBQQ__ConstrainingOption__c',
+    'SBQQ__Active__c',
+];
+export const CONFIG_RULE_FIELDS = [
+    ...AUDIT,
+    'SBQQ__Product__c',
+    'SBQQ__ProductRule__c',
+    'SBQQ__ProductFeature__c',
+    'SBQQ__Active__c',
+];
+export const ATTRIBUTE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Product__c',
+    'SBQQ__TargetField__c',
+    'SBQQ__ApplyToProductOptions__c',
+    'SBQQ__Required__c',
+];
+export const QUOTE_PROCESS_FIELDS = [...AUDIT, 'Name', 'SBQQ__Default__c'];
+export const PROCESS_INPUT_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__QuoteProcess__c',
+    'SBQQ__Required__c',
+];
+export const PROCESS_INPUT_CONDITION_FIELDS = [
+    'Id',
+    'SBQQ__ProcessInput__c',
+    'SBQQ__Field__c',
+    'SBQQ__Operator__c',
+    'SBQQ__Value__c',
+];
+export const PRODUCT_RULE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Type__c',
+    'SBQQ__Scope__c',
+    'SBQQ__Active__c',
+    'SBQQ__ConditionsMet__c',
+    'SBQQ__AdvancedCondition__c',
+    'SBQQ__EvaluationEvent__c',
+    'SBQQ__ErrorMessage__c',
+    'SBQQ__LookupObject__c',
+];
+export const ERROR_CONDITION_FIELDS = [
+    'Id',
+    'SBQQ__Rule__c',
+    'SBQQ__Index__c',
+    'SBQQ__TestedObject__c',
+    'SBQQ__TestedField__c',
+    'SBQQ__Operator__c',
+    'SBQQ__FilterType__c',
+    'SBQQ__FilterValue__c',
+    'SBQQ__TestedVariable__c',
+    'SBQQ__FilterVariable__c',
+    'SBQQ__TestedConfigurationAttribute__c',
+];
+export const PRODUCT_ACTION_FIELDS = [
+    'Id',
+    'SBQQ__Rule__c',
+    'SBQQ__Type__c',
+    'SBQQ__Product__c',
+    'SBQQ__ValueField__c',
+    'SBQQ__ValueAttribute__c',
+    'SBQQ__Required__c',
+    'SBQQ__FilterField__c',
+    'SBQQ__FilterValue__c',
+];
+export const PRICE_RULE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Active__c',
+    'SBQQ__TargetObject__c',
+    'SBQQ__EvaluationEvent__c',
+    'SBQQ__ConfiguratorEvaluationEvent__c',
+    'SBQQ__ConditionsMet__c',
+    'SBQQ__AdvancedCondition__c',
+    'SBQQ__EvaluationOrder__c',
+    'SBQQ__LookupObject__c',
+];
+export const PRICE_CONDITION_FIELDS = [
+    'Id',
+    'SBQQ__Rule__c',
+    'SBQQ__Index__c',
+    'SBQQ__Object__c',
+    'SBQQ__Field__c',
+    'SBQQ__Operator__c',
+    'SBQQ__FilterType__c',
+    'SBQQ__Value__c',
+    'SBQQ__TestedVariable__c',
+    'SBQQ__FilterVariable__c',
+];
+export const PRICE_ACTION_FIELDS = [
+    'Id',
+    'SBQQ__Rule__c',
+    'SBQQ__TargetObject__c',
+    'SBQQ__Field__c',
+    'SBQQ__Formula__c',
+    'SBQQ__Value__c',
+    'SBQQ__ValueField__c',
+    'SBQQ__SourceVariable__c',
+    'SBQQ__SourceLookupField__c',
+    'SBQQ__Order__c',
+];
+export const SUMMARY_VARIABLE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__TargetObject__c',
+    'SBQQ__Scope__c',
+    'SBQQ__AggregateFunction__c',
+    'SBQQ__AggregateField__c',
+    'SBQQ__FilterField__c',
+    'SBQQ__Operator__c',
+    'SBQQ__FilterValue__c',
+    'SBQQ__ConstraintField__c',
+    'SBQQ__CombineWith__c',
+    'SBQQ__CompositeOperator__c',
+    'SBQQ__ValueElement__c',
+];
+export const LOOKUP_QUERY_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__ProductRule__c',
+    'SBQQ__PriceRule__c',
+    'SBQQ__LookupField__c',
+    'SBQQ__TestedObject__c',
+    'SBQQ__TestedField__c',
+    'SBQQ__Operator__c',
+];
+export const DISCOUNT_SCHEDULE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Type__c',
+    'SBQQ__AggregationScope__c',
+    'SBQQ__DiscountUnit__c',
+    'SBQQ__Product__c',
+];
+export const DISCOUNT_TIER_FIELDS = [
+    'Id',
+    'SBQQ__Schedule__c',
+    'SBQQ__LowerBound__c',
+    'SBQQ__UpperBound__c',
+    'SBQQ__Discount__c',
+    'SBQQ__DiscountAmount__c',
+    'SBQQ__Price__c',
+    'SBQQ__Number__c',
+];
+export const BLOCK_PRICE_FIELDS = [
+    ...AUDIT,
+    'SBQQ__Product__c',
+    'SBQQ__LowerBound__c',
+    'SBQQ__UpperBound__c',
+    'SBQQ__Price__c',
+];
+export const CONTRACTED_PRICE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Account__c',
+    'SBQQ__Product__c',
+    'SBQQ__Price__c',
+    'SBQQ__Discount__c',
+    'SBQQ__DiscountSchedule__c',
+    'SBQQ__EffectiveDate__c',
+    'SBQQ__ExpirationDate__c',
+];
+export const DIMENSION_FIELDS = [...AUDIT, 'Name', 'SBQQ__Product__c', 'SBQQ__Type__c'];
+export const SEGMENTED_LINE_FIELDS = [
+    'Id',
+    'SBQQ__Quote__c',
+    'SBQQ__Dimension__c',
+    'SBQQ__SegmentKey__c',
+    'SBQQ__SegmentIndex__c',
+    'SBQQ__Quantity__c',
+];
+export const APPROVAL_RULE_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'sbaa__Active__c',
+    'sbaa__ApprovalChain__c',
+    'sbaa__ApprovalStep__c',
+    'sbaa__Approver__c',
+    'sbaa__ApproverField__c',
+    'sbaa__TargetObject__c',
+    'sbaa__ConditionsMet__c',
+    'sbaa__AdvancedCondition__c',
+];
+export const APPROVAL_CONDITION_FIELDS = [
+    'Id',
+    'sbaa__ApprovalRule__c',
+    'sbaa__Index__c',
+    'sbaa__TestedField__c',
+    'sbaa__Operator__c',
+    'sbaa__FilterValue__c',
+    'sbaa__TestedVariable__c',
+];
+export const NAMED_FIELDS = [...AUDIT, 'Name'];
+export const APPROVER_FIELDS = [...AUDIT, 'Name', 'sbaa__User__c', 'sbaa__GroupId__c'];
+export const APPROVAL_HISTORY_FIELDS = [
+    'Id',
+    'sbaa__Status__c',
+    'sbaa__Rule__c',
+    'CreatedDate',
+    'LastModifiedDate',
+];
+export const PROCESS_INSTANCE_FIELDS = [
+    'Id',
+    'Status',
+    'CreatedDate',
+    'CompletedDate',
+    'ProcessDefinitionId',
+];
+export const PROCESS_DEFINITION_FIELDS = [
+    'Id',
+    'Name',
+    'DeveloperName',
+    'Type',
+    'TableEnumOrId',
+    'State',
+    'LastModifiedDate',
+];
+export const TEMPLATE_SECTION_FIELDS = ['Id', 'SBQQ__Template__c', 'SBQQ__Content__c'];
+export const TEMPLATE_CONTENT_FIELDS = [...AUDIT, 'Name', 'SBQQ__Type__c'];
+export const LINE_COLUMN_FIELDS = [...AUDIT, 'Name', 'SBQQ__Template__c', 'SBQQ__FieldName__c'];
+export const TERM_CONDITION_FIELDS = [
+    'Id',
+    'SBQQ__QuoteTerm__c',
+    'SBQQ__Field__c',
+    'SBQQ__Operator__c',
+    'SBQQ__Value__c',
+    'SBQQ__TestedVariable__c',
+    'SBQQ__Index__c',
+];
+export const CUSTOM_SCRIPT_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Code__c',
+    'SBQQ__QuoteFields__c',
+    'SBQQ__QuoteLineFields__c',
+    'SBQQ__GroupFields__c',
+];
+export const CUSTOM_ACTION_FIELDS = [
+    ...AUDIT,
+    'Name',
+    'SBQQ__Type__c',
+    'SBQQ__Location__c',
+    'SBQQ__Page__c',
+    'SBQQ__Active__c',
+];
+export const APEX_TRIGGER_FIELDS = [
+    'Id',
+    'Name',
+    'TableEnumOrId',
+    'NamespacePrefix',
+    'Status',
+    'Body',
+    'LastModifiedDate',
+];
+export const WEBLINK_FIELDS = ['Id', 'Name', 'PageOrSobjectType', 'NamespacePrefix'];
+export const LAYOUT_FIELDS = ['Id', 'Name', 'TableEnumOrId', 'NamespacePrefix'];
+export const FLEXIPAGE_FIELDS = [
+    'Id',
+    'DeveloperName',
+    'EntityDefinitionId',
+    'NamespacePrefix',
+    'Type',
+];
+export const VALIDATION_RULE_FIELDS = [
+    'Id',
+    'ValidationName',
+    'NamespacePrefix',
+    'Active',
+    'EntityDefinition.QualifiedApiName',
+];
+export const FIELD_DEFINITION_FIELDS = ['QualifiedApiName', 'Label', 'DataType', 'NamespacePrefix'];
+export const SBQQ_OBJECT_PREFIXES = ['SBQQ__', 'sbaa__'];
+export function isCpqObject(apiName) {
+    return !!apiName && SBQQ_OBJECT_PREFIXES.some((p) => apiName.startsWith(p));
+}
+//# sourceMappingURL=records.js.map

package/lib/index.d.ts

@@ -0,0 +1,30 @@
+import type { OrgConnection } from './connection.js';
+import { type ExtractOptions, type ProgressEvent } from './extract/index.js';
+import type { ReportData } from './report/types.js';
+export * from './banner.js';
+export * from './classify/advancedCondition.js';
+export * from './classify/formula.js';
+export { type Classification, type ClassifiedRecord, classifyAll, type Tally, } from './classify/index.js';
+export { MECHANISM_BUCKETS, type RowId, RULE_ROWS, type RuleRow, ruleRow, } from './classify/rules.js';
+export * from './config/outbound.js';
+export * from './connection.js';
+export { type Extraction, type ExtractOptions, extractAll, type ProgressEvent, type ProgressStep, } from './extract/index.js';
+export * as records from './extract/records.js';
+export * from './liveness.js';
+export { MAPPING_ROWS, type MappingDef, SHAPE_MEANINGS, VERDICT_MEANINGS } from './mapping.js';
+export { type AssembleOptions, assembleReport } from './report/assemble.js';
+export { ASSETS_DIR, assetsAvailable, buildPrintDocument } from './report/printDoc.js';
+export { buildShareSummary } from './report/shareSummary.js';
+export * from './report/types.js';
+export { type RunningServer, type RunStatus, type ServerOptions, startServer } from './server.js';
+export * from './soql.js';
+export * from './types.js';
+export interface RunOptions extends Omit<ExtractOptions, 'onProgress'> {
+    version: string;
+    runId?: string;
+    onProgress?: (e: ProgressEvent) => void;
+}
+export declare function newRunId(): string;
+/** The whole pipeline: extract → classify → assemble. Takes a connection, returns the data set. */
+export declare function runInventory(conn: OrgConnection, opts: RunOptions): Promise<ReportData>;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,51 @@
+import { randomBytes } from 'node:crypto';
+import { classifyAll } from './classify/index.js';
+import { extractAll } from './extract/index.js';
+import { assembleReport } from './report/assemble.js';
+export * from './banner.js';
+export * from './classify/advancedCondition.js';
+export * from './classify/formula.js';
+export { classifyAll, } from './classify/index.js';
+export { MECHANISM_BUCKETS, RULE_ROWS, ruleRow, } from './classify/rules.js';
+export * from './config/outbound.js';
+export * from './connection.js';
+export { extractAll, } from './extract/index.js';
+export * as records from './extract/records.js';
+export * from './liveness.js';
+export { MAPPING_ROWS, SHAPE_MEANINGS, VERDICT_MEANINGS } from './mapping.js';
+export { assembleReport } from './report/assemble.js';
+export { ASSETS_DIR, assetsAvailable, buildPrintDocument } from './report/printDoc.js';
+export { buildShareSummary } from './report/shareSummary.js';
+export * from './report/types.js';
+export { startServer } from './server.js';
+export * from './soql.js';
+export * from './types.js';
+export function newRunId() {
+    return randomBytes(2).toString('hex');
+}
+/** The whole pipeline: extract → classify → assemble. Takes a connection, returns the data set. */
+export async function runInventory(conn, opts) {
+    const runId = opts.runId ?? newRunId();
+    const progress = opts.onProgress ?? (() => { });
+    const ex = await extractAll(conn, {
+        windowMonths: opts.windowMonths,
+        now: opts.now,
+        onProgress: progress,
+    });
+    progress({ step: 'classify', status: 'start' });
+    const cl = classifyAll(ex);
+    const report = assembleReport(ex, cl, {
+        version: opts.version,
+        runId,
+        org: {
+            name: conn.orgName,
+            username: conn.username,
+            instanceUrl: conn.instanceUrl,
+            orgId: conn.orgId,
+        },
+        now: opts.now,
+    });
+    progress({ step: 'classify', status: 'done' });
+    return report;
+}
+//# sourceMappingURL=index.js.map

package/lib/liveness.d.ts

@@ -0,0 +1,19 @@
+import type { Audited } from './extract/records.js';
+/** Share of an object's records sharing one LastModifiedDate above which Alive is unreliable. */
+export declare const BULK_TOUCH_SHARE = 0.6;
+/** Below this many records a shared date is not evidence of a bulk touch. */
+export declare const BULK_TOUCH_MIN_RECORDS = 10;
+export interface BulkTouch {
+    object: string;
+    date: string;
+    share: number;
+}
+/** Configuration liveness reads LastModifiedDate. Never CreatedDate. */
+export declare function isAlive(rec: Pick<Audited, 'LastModifiedDate'>, since: string): boolean;
+/**
+ * Package upgrades and mass updates rewrite LastModifiedDate across whole objects. When more than
+ * 60% of an object's records share one LastModifiedDate, its Alive value is unreliable and the report
+ * prints the date rather than the count.
+ */
+export declare function detectBulkTouch(object: string, records: readonly Pick<Audited, 'LastModifiedDate'>[]): BulkTouch | null;
+//# sourceMappingURL=liveness.d.ts.map

package/lib/liveness.js

@@ -0,0 +1,34 @@
+/** Share of an object's records sharing one LastModifiedDate above which Alive is unreliable. */
+export const BULK_TOUCH_SHARE = 0.6;
+/** Below this many records a shared date is not evidence of a bulk touch. */
+export const BULK_TOUCH_MIN_RECORDS = 10;
+/** Configuration liveness reads LastModifiedDate. Never CreatedDate. */
+export function isAlive(rec, since) {
+    const d = rec.LastModifiedDate;
+    return !!d && d >= since;
+}
+/**
+ * Package upgrades and mass updates rewrite LastModifiedDate across whole objects. When more than
+ * 60% of an object's records share one LastModifiedDate, its Alive value is unreliable and the report
+ * prints the date rather than the count.
+ */
+export function detectBulkTouch(object, records) {
+    if (records.length < BULK_TOUCH_MIN_RECORDS)
+        return null;
+    const tally = new Map();
+    for (const r of records) {
+        if (!r.LastModifiedDate)
+            continue;
+        const key = r.LastModifiedDate;
+        tally.set(key, (tally.get(key) ?? 0) + 1);
+    }
+    let best = null;
+    for (const entry of tally)
+        if (!best || entry[1] > best[1])
+            best = entry;
+    if (!best)
+        return null;
+    const share = best[1] / records.length;
+    return share > BULK_TOUCH_SHARE ? { object, date: best[0].slice(0, 10), share } : null;
+}
+//# sourceMappingURL=liveness.js.map

package/lib/mapping.d.ts

@@ -0,0 +1,14 @@
+import type { BucketId, Shape, Verdict } from './types.js';
+/** Stage 2: the same ten buckets with a verdict per construct. From the spec's mapping table. */
+export interface MappingDef {
+    id: string;
+    bucket: BucketId;
+    from: string;
+    to: string;
+    verdict: Verdict;
+    shape?: Shape;
+}
+export declare const MAPPING_ROWS: readonly MappingDef[];
+export declare const VERDICT_MEANINGS: Record<Exclude<Verdict, 'Further review'>, string>;
+export declare const SHAPE_MEANINGS: Record<Shape, string>;
+//# sourceMappingURL=mapping.d.ts.map