@spottoai/types-package 1.0.2-dev1138.1 → 1.0.2-dev1138.12

package/dist/esm/azure/financialChargeCompositionKernel.js

@@ -0,0 +1,48 @@
+import { formatExactDecimalValue, sumCanonicalDecimals } from '../common/exactDecimal.js';
+import { FINANCIAL_CHARGE_COMPOSITION_CONTRACT_VERSION_V1, FINANCIAL_CHARGE_COMPOSITION_SCHEMA_VERSION_V1, } from './financialChargeComposition.js';
+import { createFinancialChargeCompositionIdV1 } from './financialChargeCompositionValidation.js';
+const bucketKey = (component) => `${component.chargeSource}\u0000${component.chargeRecurrence}\u0000${component.chargeClassification}`;
+export const createFinancialChargeCompositionV1 = (request) => {
+    if (!Array.isArray(request.components) || request.components.length === 0 || request.components.length > 20000) {
+        throw new TypeError('Financial charge composition requires a bounded non-empty component collection.');
+    }
+    if (new Set(request.components.map(component => component.componentId)).size !== request.components.length) {
+        throw new TypeError('Financial charge composition cannot classify one component more than once.');
+    }
+    const groups = new Map();
+    for (const component of request.components) {
+        const key = bucketKey(component);
+        const group = groups.get(key);
+        if (group)
+            group.push(component);
+        else
+            groups.set(key, [component]);
+    }
+    const buckets = [...groups.values()]
+        .map(group => ({
+        chargeSource: group[0].chargeSource,
+        chargeRecurrence: group[0].chargeRecurrence,
+        chargeClassification: group[0].chargeClassification,
+        amount: formatExactDecimalValue(sumCanonicalDecimals(group.map(component => component.amount))),
+        componentIds: [...new Set(group.map(component => component.componentId))].sort(),
+        evidenceRefIds: [...new Set(group.flatMap(component => component.evidenceRefIds))].sort(),
+    }))
+        .sort((left, right) => `${left.chargeSource}\u0000${left.chargeRecurrence}\u0000${left.chargeClassification}`.localeCompare(`${right.chargeSource}\u0000${right.chargeRecurrence}\u0000${right.chargeClassification}`));
+    const bucketTotal = formatExactDecimalValue(sumCanonicalDecimals(buckets.map(bucket => bucket.amount)));
+    if (bucketTotal !== request.sourceTotal)
+        throw new TypeError('Financial charge composition does not reconcile to its source total.');
+    const identity = {
+        schemaVersion: FINANCIAL_CHARGE_COMPOSITION_SCHEMA_VERSION_V1,
+        contractVersion: FINANCIAL_CHARGE_COMPOSITION_CONTRACT_VERSION_V1,
+        baselineId: request.baselineId,
+        ownerScopeId: request.ownerScopeId,
+        period: request.period,
+        costBasis: request.costBasis,
+        estimateLens: request.estimateLens,
+        accountingCurrencyCode: request.accountingCurrencyCode,
+        buckets,
+        reconciliation: { status: 'reconciled', bucketTotal, sourceTotal: request.sourceTotal, difference: '0' },
+        algorithmVersion: request.algorithmVersion,
+    };
+    return { ...identity, chargeCompositionId: createFinancialChargeCompositionIdV1(identity) };
+};

package/dist/esm/azure/financialChargeCompositionValidation.js

@@ -0,0 +1,155 @@
+import { formatExactDecimalValue, sumCanonicalDecimals } from '../common/exactDecimal.js';
+import { sha256Utf8 } from '../common/sha256.js';
+import { FINANCIAL_CHARGE_COMPOSITION_CONTRACT_VERSION_V1, FINANCIAL_CHARGE_COMPOSITION_SCHEMA_VERSION_V1, resolveFinancialChargeInclusionPolicyV1, } from './financialChargeComposition.js';
+import { canonicalizeFinancialDataflowJsonV1, hasFinancialDataflowExactFieldsV1, isFinancialDataflowCurrencyV1, isFinancialDataflowHashV1, isFinancialDataflowIdentityV1, isFinancialDataflowRecordV1, isFinancialDataflowValueWithinLimitsV1, } from './financialDataflowValidation.js';
+import { isFinancialBaselinePeriodV2 } from './financialScopeBaselineValidation.js';
+import { isCanonicalExactMoney } from './financialValidationPrimitives.js';
+const SOURCES = new Set(['azure-native', 'marketplace', 'unknown']);
+const RECURRENCES = new Set(['one-time', 'recurring', 'usage-based', 'unknown']);
+const CLASSIFICATIONS = new Set(['usage', 'purchase', 'adjustment', 'tax', 'credit', 'refund', 'residual']);
+const COST_BASES = new Set(['billed', 'amortized']);
+const ESTIMATE_LENSES = new Set(['actual-only', 'actual-plus-estimated', 'estimates-only']);
+const isSortedUniqueHashes = (value) => Array.isArray(value) && value.length > 0 && value.length <= 20000 && value.every(isFinancialDataflowHashV1) &&
+    value.every((entry, index) => index === 0 || value[index - 1] < entry);
+const isBucket = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, [
+        'chargeSource',
+        'chargeRecurrence',
+        'chargeClassification',
+        'amount',
+        'componentIds',
+        'evidenceRefIds',
+    ]) &&
+    SOURCES.has(value.chargeSource) &&
+    RECURRENCES.has(value.chargeRecurrence) &&
+    CLASSIFICATIONS.has(value.chargeClassification) &&
+    isCanonicalExactMoney({ amount: value.amount, currencyCode: 'AUD' }) &&
+    isSortedUniqueHashes(value.componentIds) &&
+    isSortedUniqueHashes(value.evidenceRefIds);
+const isIdentity = (value) => {
+    if (!isFinancialDataflowRecordV1(value) ||
+        !hasFinancialDataflowExactFieldsV1(value, [
+            'schemaVersion',
+            'contractVersion',
+            'baselineId',
+            'ownerScopeId',
+            'period',
+            'costBasis',
+            'estimateLens',
+            'accountingCurrencyCode',
+            'buckets',
+            'reconciliation',
+            'algorithmVersion',
+        ]) ||
+        value.schemaVersion !== FINANCIAL_CHARGE_COMPOSITION_SCHEMA_VERSION_V1 ||
+        value.contractVersion !== FINANCIAL_CHARGE_COMPOSITION_CONTRACT_VERSION_V1 ||
+        !isFinancialDataflowHashV1(value.baselineId) ||
+        !isFinancialDataflowIdentityV1(value.ownerScopeId) ||
+        !isFinancialBaselinePeriodV2(value.period) ||
+        !COST_BASES.has(value.costBasis) ||
+        !ESTIMATE_LENSES.has(value.estimateLens) ||
+        !isFinancialDataflowCurrencyV1(value.accountingCurrencyCode) ||
+        !Array.isArray(value.buckets) ||
+        value.buckets.length === 0 ||
+        value.buckets.length > 20000 ||
+        !value.buckets.every(isBucket) ||
+        !isFinancialDataflowIdentityV1(value.algorithmVersion) ||
+        !isFinancialDataflowRecordV1(value.reconciliation) ||
+        !hasFinancialDataflowExactFieldsV1(value.reconciliation, ['status', 'bucketTotal', 'sourceTotal', 'difference']) ||
+        value.reconciliation.status !== 'reconciled' ||
+        value.reconciliation.difference !== '0' ||
+        !isCanonicalExactMoney({ amount: value.reconciliation.bucketTotal, currencyCode: value.accountingCurrencyCode }) ||
+        !isCanonicalExactMoney({ amount: value.reconciliation.sourceTotal, currencyCode: value.accountingCurrencyCode }))
+        return false;
+    const componentIds = value.buckets.flatMap(bucket => bucket.componentIds);
+    if (new Set(componentIds).size !== componentIds.length)
+        return false;
+    const keys = value.buckets.map(bucket => `${bucket.chargeSource}\u0000${bucket.chargeRecurrence}\u0000${bucket.chargeClassification}`);
+    if (!keys.every((key, index) => index === 0 || keys[index - 1] < key))
+        return false;
+    try {
+        const bucketTotal = formatExactDecimalValue(sumCanonicalDecimals(value.buckets.map(bucket => bucket.amount)));
+        return bucketTotal === value.reconciliation.bucketTotal && bucketTotal === value.reconciliation.sourceTotal;
+    }
+    catch {
+        return false;
+    }
+};
+export const canonicalizeFinancialChargeCompositionIdentityV1 = (value) => {
+    if (!isFinancialDataflowValueWithinLimitsV1(value) || !isIdentity(value)) {
+        throw new TypeError('Invalid FinancialChargeCompositionIdentityPreimageV1.');
+    }
+    return canonicalizeFinancialDataflowJsonV1(value);
+};
+export const createFinancialChargeCompositionIdV1 = (value) => `sha256:${sha256Utf8(canonicalizeFinancialChargeCompositionIdentityV1(value))}`;
+export const isFinancialChargeCompositionV1 = (value) => {
+    if (!isFinancialDataflowValueWithinLimitsV1(value) ||
+        !isFinancialDataflowRecordV1(value) ||
+        !hasFinancialDataflowExactFieldsV1(value, [
+            'chargeCompositionId',
+            'schemaVersion',
+            'contractVersion',
+            'baselineId',
+            'ownerScopeId',
+            'period',
+            'costBasis',
+            'estimateLens',
+            'accountingCurrencyCode',
+            'buckets',
+            'reconciliation',
+            'algorithmVersion',
+        ]))
+        return false;
+    const { chargeCompositionId, ...identity } = value;
+    return isFinancialDataflowHashV1(chargeCompositionId) && isIdentity(identity) &&
+        chargeCompositionId === createFinancialChargeCompositionIdV1(identity);
+};
+export const isFinancialChargeInclusionPolicyRefV1 = (value) => isFinancialDataflowRecordV1(value) &&
+    hasFinancialDataflowExactFieldsV1(value, ['policyId', 'policyDigest']) &&
+    isFinancialDataflowIdentityV1(value.policyId) &&
+    isFinancialDataflowHashV1(value.policyDigest) &&
+    resolveFinancialChargeInclusionPolicyV1(value) !== undefined;
+const sumBuckets = (buckets) => formatExactDecimalValue(sumCanonicalDecimals(buckets.map(bucket => bucket.amount)));
+const sourcesFor = (policy, role) => role === 'include' ? policy.includeSources : role === 'exclude' ? policy.excludeSources : policy.withholdSources;
+export const selectFinancialChargesV1 = (composition, policyRef) => {
+    if (!isFinancialChargeCompositionV1(composition))
+        throw new TypeError('Invalid financial charge composition.');
+    const policy = resolveFinancialChargeInclusionPolicyV1(policyRef);
+    if (!policy)
+        throw new TypeError('Unregistered financial charge-inclusion policy.');
+    const partition = (role) => composition.buckets.filter(bucket => sourcesFor(policy, role).includes(bucket.chargeSource));
+    const included = partition('include');
+    const excluded = partition('exclude');
+    const withheld = partition('withhold');
+    if (included.length + excluded.length + withheld.length !== composition.buckets.length) {
+        throw new TypeError('Financial charge-inclusion policy does not partition every charge source.');
+    }
+    const includedAmount = sumBuckets(included);
+    const excludedAmount = sumBuckets(excluded);
+    const withheldAmount = sumBuckets(withheld);
+    const forecastEligibleAmount = sumBuckets(included.filter(bucket => bucket.chargeRecurrence === 'recurring' || bucket.chargeRecurrence === 'usage-based'));
+    const oneTimeAmount = sumBuckets(included.filter(bucket => bucket.chargeRecurrence === 'one-time'));
+    const unknownRecurrenceAmount = sumBuckets(included.filter(bucket => bucket.chargeRecurrence === 'unknown'));
+    const reasonCodes = [];
+    if (withheldAmount !== '0')
+        reasonCodes.push('charge-source-unknown');
+    const forecastReasonCodes = [...reasonCodes];
+    if (unknownRecurrenceAmount !== '0')
+        forecastReasonCodes.push('charge-recurrence-unknown');
+    const result = {
+        status: withheldAmount === '0' ? 'available' : 'partial',
+        includedAmount,
+        excludedAmount,
+        withheldAmount,
+        forecastEligibleAmount,
+        oneTimeAmount,
+        unknownRecurrenceAmount,
+        forecastStatus: withheldAmount === '0' && unknownRecurrenceAmount === '0' ? 'available' : 'partial',
+        currencyCode: composition.accountingCurrencyCode,
+        ...(reasonCodes.length === 0 ? {} : { reasonCodes: reasonCodes }),
+        ...(forecastReasonCodes.length === 0
+            ? {}
+            : { forecastReasonCodes: forecastReasonCodes }),
+    };
+    return result;
+};