@spottoai/types-package 1.0.2-dev1138.13 → 1.0.2-dev1138.14

package/dist/esm/reporting/jobs/reportJobSpec.js

@@ -0,0 +1,295 @@
+/**
+ * The background report request (`ReportJobSpecV1`), stored as `requestJson` on the `reportjobs` row
+ * (core/specs/reporting/reporting-scheduler.md, "Request spec"; types-package/specs/reporting/reporting-scheduler-types.md).
+ *
+ * Parsing is strict (unknown fields fail) and normalising: subscription IDs are lower-cased, de-duplicated and
+ * sorted, so equal requests serialise to the same canonical JSON.
+ */
+import { hasExactlyKeys, isBoundedPlainText, isCalendarDate, isPlainRecord, isReportEntityId, isReportGuid, utf8ByteLength, } from '../shared/reportingIds.js';
+export const REPORT_JOB_SPEC_SCHEMA_VERSION = 1;
+export const REPORT_JOB_REPORT_TYPES = ['sdm', 'architecture-assessment'];
+export const REPORT_JOB_MAX_SUBSCRIPTIONS = 200;
+export const REPORT_JOB_MAX_CLOUD_ACCOUNTS = 20;
+export const REPORT_JOB_MAX_SERVICE_IDS = 20;
+export const REPORT_JOB_MAX_EXPLICIT_PERIOD_DAYS = 366;
+/** Maximum UTF-8 size of the canonical `requestJson`. */
+export const REPORT_JOB_SPEC_MAX_BYTES = 32 * 1024;
+export const SDM_BACKGROUND_LAYOUTS = ['spotto-layout', 'monthly-insights'];
+export const SDM_BACKGROUND_DETAIL_ROW_LIMITS = [10, 25, 50, 'all'];
+export const CURRENT_STATE_AUDIENCES = ['customer', 'internal'];
+export const CURRENT_STATE_SECTION_KEYS = ['costOpportunities', 'securityPosture', 'reliabilityAvailability', 'quickWins', 'roadmap'];
+const SERVICE_ID_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+const CURRENCY_PATTERN = /^[A-Z]{3}$/;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const isReportJobReportType = (value) => typeof value === 'string' && REPORT_JOB_REPORT_TYPES.includes(value);
+/**
+ * Lower-cases, de-duplicates and sorts subscription IDs. Lower case is Spotto's canonical subscription ID form: the
+ * request and the scope hash use it, and so do the storage keys and paths reportworker builds from it.
+ */
+export const normalizeReportSubscriptionIds = (subscriptionIds) => Array.from(new Set(subscriptionIds.map(id => id.trim().toLowerCase()))).sort();
+const parseScope = (value, errors) => {
+    if (!isPlainRecord(value) || !hasExactlyKeys(value, ['cloudAccountIds', 'subscriptionIds'])) {
+        errors.push('scope: must contain exactly cloudAccountIds and subscriptionIds');
+        return undefined;
+    }
+    const { cloudAccountIds, subscriptionIds } = value;
+    let valid = true;
+    if (!Array.isArray(cloudAccountIds) || cloudAccountIds.length === 0) {
+        errors.push('scope.cloudAccountIds: at least one cloud account is required');
+        valid = false;
+    }
+    else {
+        cloudAccountIds.forEach((id, index) => {
+            if (!isReportEntityId(id)) {
+                errors.push(`scope.cloudAccountIds[${index}]: invalid cloud account ID`);
+                valid = false;
+            }
+        });
+    }
+    if (!Array.isArray(subscriptionIds) || subscriptionIds.length === 0) {
+        errors.push('scope.subscriptionIds: at least one subscription is required');
+        valid = false;
+    }
+    else {
+        subscriptionIds.forEach((id, index) => {
+            if (typeof id !== 'string' || !isReportGuid(id.trim())) {
+                errors.push(`scope.subscriptionIds[${index}]: invalid subscription ID`);
+                valid = false;
+            }
+        });
+    }
+    if (!valid)
+        return undefined;
+    const normalizedAccounts = Array.from(new Set(cloudAccountIds)).sort();
+    const normalizedSubscriptions = normalizeReportSubscriptionIds(subscriptionIds);
+    if (normalizedAccounts.length > REPORT_JOB_MAX_CLOUD_ACCOUNTS) {
+        errors.push(`scope.cloudAccountIds: at most ${REPORT_JOB_MAX_CLOUD_ACCOUNTS} cloud accounts`);
+        return undefined;
+    }
+    if (normalizedSubscriptions.length > REPORT_JOB_MAX_SUBSCRIPTIONS) {
+        errors.push(`scope.subscriptionIds: at most ${REPORT_JOB_MAX_SUBSCRIPTIONS} subscriptions`);
+        return undefined;
+    }
+    return { cloudAccountIds: normalizedAccounts, subscriptionIds: normalizedSubscriptions };
+};
+const parsePeriod = (value, errors) => {
+    if (!isPlainRecord(value)) {
+        errors.push('period: must be an object');
+        return undefined;
+    }
+    if (value.kind === 'previous-calendar-month' || value.kind === 'previous-calendar-quarter') {
+        if (!hasExactlyKeys(value, ['kind'])) {
+            errors.push('period: a period rule has no other fields');
+            return undefined;
+        }
+        return { kind: value.kind };
+    }
+    if (value.kind === 'explicit') {
+        if (!hasExactlyKeys(value, ['kind', 'startDate', 'endDate']) || !isCalendarDate(value.startDate) || !isCalendarDate(value.endDate)) {
+            errors.push('period: explicit periods need startDate and endDate as YYYY-MM-DD');
+            return undefined;
+        }
+        const days = (Date.parse(`${value.endDate}T00:00:00.000Z`) - Date.parse(`${value.startDate}T00:00:00.000Z`)) / DAY_MS + 1;
+        if (days < 1 || days > REPORT_JOB_MAX_EXPLICIT_PERIOD_DAYS) {
+            errors.push(`period: startDate must not be after endDate and the period must be at most ${REPORT_JOB_MAX_EXPLICIT_PERIOD_DAYS} days`);
+            return undefined;
+        }
+        return { kind: 'explicit', startDate: value.startDate, endDate: value.endDate };
+    }
+    errors.push('period.kind: must be previous-calendar-month, previous-calendar-quarter or explicit');
+    return undefined;
+};
+const parseSdmConfiguration = (value, errors) => {
+    if (!isPlainRecord(value) || !hasExactlyKeys(value, ['layout', 'cloudIqServiceProfile'])) {
+        errors.push('configuration: SDM needs exactly layout and cloudIqServiceProfile');
+        return undefined;
+    }
+    const { layout, cloudIqServiceProfile: profile } = value;
+    let valid = true;
+    if (typeof layout !== 'string' || !SDM_BACKGROUND_LAYOUTS.includes(layout)) {
+        errors.push('configuration.layout: must be spotto-layout or monthly-insights');
+        valid = false;
+    }
+    if (!isPlainRecord(profile) || !hasExactlyKeys(profile, ['selectedServiceIds'], ['detailRowLimit'])) {
+        errors.push('configuration.cloudIqServiceProfile: needs selectedServiceIds and optionally detailRowLimit');
+        return undefined;
+    }
+    const { selectedServiceIds, detailRowLimit } = profile;
+    if (!Array.isArray(selectedServiceIds) ||
+        selectedServiceIds.length > REPORT_JOB_MAX_SERVICE_IDS ||
+        !selectedServiceIds.every(id => typeof id === 'string' && SERVICE_ID_PATTERN.test(id)) ||
+        new Set(selectedServiceIds).size !== selectedServiceIds.length) {
+        errors.push(`configuration.cloudIqServiceProfile.selectedServiceIds: up to ${REPORT_JOB_MAX_SERVICE_IDS} unique service IDs`);
+        valid = false;
+    }
+    if (detailRowLimit !== undefined && !SDM_BACKGROUND_DETAIL_ROW_LIMITS.includes(detailRowLimit)) {
+        errors.push('configuration.cloudIqServiceProfile.detailRowLimit: must be 10, 25, 50 or all');
+        valid = false;
+    }
+    if (!valid)
+        return undefined;
+    return {
+        layout: layout,
+        cloudIqServiceProfile: {
+            selectedServiceIds: [...selectedServiceIds],
+            ...(detailRowLimit === undefined ? {} : { detailRowLimit: detailRowLimit }),
+        },
+    };
+};
+const parseCurrentStateConfiguration = (value, errors) => {
+    if (!isPlainRecord(value) || !hasExactlyKeys(value, ['audience', 'sections', 'scopeCurrencyCode'], ['preparedBy'])) {
+        errors.push('configuration: Current State needs audience, sections, scopeCurrencyCode and optionally preparedBy');
+        return undefined;
+    }
+    const { audience, sections, scopeCurrencyCode, preparedBy } = value;
+    let valid = true;
+    if (typeof audience !== 'string' || !CURRENT_STATE_AUDIENCES.includes(audience)) {
+        errors.push('configuration.audience: must be customer or internal');
+        valid = false;
+    }
+    if (!isPlainRecord(sections) ||
+        !hasExactlyKeys(sections, CURRENT_STATE_SECTION_KEYS) ||
+        !CURRENT_STATE_SECTION_KEYS.every(key => typeof sections[key] === 'boolean')) {
+        errors.push(`configuration.sections: needs exactly ${CURRENT_STATE_SECTION_KEYS.join(', ')} as booleans`);
+        valid = false;
+    }
+    const currency = typeof scopeCurrencyCode === 'string' ? scopeCurrencyCode.trim().toUpperCase() : '';
+    if (!CURRENCY_PATTERN.test(currency)) {
+        errors.push('configuration.scopeCurrencyCode: must be a three-letter ISO 4217 code');
+        valid = false;
+    }
+    const preparedByText = typeof preparedBy === 'string' ? preparedBy.trim() : preparedBy;
+    if (preparedByText !== undefined && (!isBoundedPlainText(preparedByText, 120) || preparedByText.includes('://'))) {
+        errors.push('configuration.preparedBy: 1..120 characters of plain text, no URLs');
+        valid = false;
+    }
+    if (!valid)
+        return undefined;
+    const sectionRecord = sections;
+    return {
+        audience: audience,
+        sections: {
+            costOpportunities: sectionRecord.costOpportunities,
+            securityPosture: sectionRecord.securityPosture,
+            reliabilityAvailability: sectionRecord.reliabilityAvailability,
+            quickWins: sectionRecord.quickWins,
+            roadmap: sectionRecord.roadmap,
+        },
+        scopeCurrencyCode: currency,
+        ...(preparedByText === undefined ? {} : { preparedBy: preparedByText }),
+    };
+};
+const parseSpecUnsafe = (input) => {
+    const errors = [];
+    if (!isPlainRecord(input))
+        return { ok: false, errors: ['spec: must be an object'] };
+    if (input.schemaVersion !== REPORT_JOB_SPEC_SCHEMA_VERSION)
+        return { ok: false, errors: ['schemaVersion: must be 1'] };
+    if (input.reportType === 'sdm') {
+        if (!hasExactlyKeys(input, ['schemaVersion', 'reportType', 'scope', 'period', 'configuration'])) {
+            return { ok: false, errors: ['spec: SDM needs exactly schemaVersion, reportType, scope, period and configuration'] };
+        }
+        const scope = parseScope(input.scope, errors);
+        const period = parsePeriod(input.period, errors);
+        const configuration = parseSdmConfiguration(input.configuration, errors);
+        if (!scope || !period || !configuration || errors.length > 0)
+            return { ok: false, errors };
+        return { ok: true, value: { schemaVersion: 1, reportType: 'sdm', scope, period, configuration } };
+    }
+    if (input.reportType === 'architecture-assessment') {
+        if (!hasExactlyKeys(input, ['schemaVersion', 'reportType', 'scope', 'configuration'])) {
+            return { ok: false, errors: ['spec: Current State needs exactly schemaVersion, reportType, scope and configuration (no period)'] };
+        }
+        const scope = parseScope(input.scope, errors);
+        const configuration = parseCurrentStateConfiguration(input.configuration, errors);
+        if (!scope || !configuration || errors.length > 0)
+            return { ok: false, errors };
+        return { ok: true, value: { schemaVersion: 1, reportType: 'architecture-assessment', scope, configuration } };
+    }
+    return { ok: false, errors: ['reportType: must be sdm or architecture-assessment'] };
+};
+/** Strict, normalising parser. Never throws (hostile getters are reported as an invalid spec). */
+export const parseReportJobSpecV1 = (input) => {
+    try {
+        return parseSpecUnsafe(input);
+    }
+    catch {
+        return { ok: false, errors: ['spec: unreadable'] };
+    }
+};
+const canonicalSpecObject = (spec) => {
+    const scope = { cloudAccountIds: spec.scope.cloudAccountIds, subscriptionIds: spec.scope.subscriptionIds };
+    if (spec.reportType === 'sdm') {
+        const period = spec.period.kind === 'explicit'
+            ? { kind: 'explicit', startDate: spec.period.startDate, endDate: spec.period.endDate }
+            : { kind: spec.period.kind };
+        const profile = spec.configuration.cloudIqServiceProfile;
+        return {
+            schemaVersion: 1,
+            reportType: 'sdm',
+            scope,
+            period,
+            configuration: {
+                layout: spec.configuration.layout,
+                cloudIqServiceProfile: {
+                    selectedServiceIds: profile.selectedServiceIds,
+                    ...(profile.detailRowLimit === undefined ? {} : { detailRowLimit: profile.detailRowLimit }),
+                },
+            },
+        };
+    }
+    const configuration = spec.configuration;
+    return {
+        schemaVersion: 1,
+        reportType: 'architecture-assessment',
+        scope,
+        configuration: {
+            audience: configuration.audience,
+            sections: {
+                costOpportunities: configuration.sections.costOpportunities,
+                securityPosture: configuration.sections.securityPosture,
+                reliabilityAvailability: configuration.sections.reliabilityAvailability,
+                quickWins: configuration.sections.quickWins,
+                roadmap: configuration.sections.roadmap,
+            },
+            scopeCurrencyCode: configuration.scopeCurrencyCode,
+            ...(configuration.preparedBy === undefined ? {} : { preparedBy: configuration.preparedBy }),
+        },
+    };
+};
+/**
+ * The canonical `requestJson`: validated, normalised, fixed key order. Producers store exactly this string, and
+ * `requestSha256` is the SHA-256 of its UTF-8 bytes. Throws on an invalid spec or one above 32 KiB.
+ */
+export const serializeReportJobSpecV1 = (spec) => {
+    const parsed = parseReportJobSpecV1(spec);
+    if (!parsed.ok)
+        throw new Error(`Invalid report job spec: ${parsed.errors.join('; ')}`);
+    const json = JSON.stringify(canonicalSpecObject(parsed.value));
+    if (utf8ByteLength(json) > REPORT_JOB_SPEC_MAX_BYTES)
+        throw new RangeError(`Report job spec exceeds ${REPORT_JOB_SPEC_MAX_BYTES} bytes.`);
+    return json;
+};
+/**
+ * Parses stored `requestJson`. It must be valid JSON, a valid spec and already canonical (byte-equal to
+ * `serializeReportJobSpecV1` of itself), so a hash over the stored string identifies the request exactly.
+ */
+export const parseReportJobRequestJson = (requestJson) => {
+    if (typeof requestJson !== 'string' || requestJson.length === 0)
+        return { ok: false, errors: ['requestJson: must be a non-empty string'] };
+    if (utf8ByteLength(requestJson) > REPORT_JOB_SPEC_MAX_BYTES)
+        return { ok: false, errors: ['requestJson: exceeds 32 KiB'] };
+    let raw;
+    try {
+        raw = JSON.parse(requestJson);
+    }
+    catch {
+        return { ok: false, errors: ['requestJson: not valid JSON'] };
+    }
+    const parsed = parseReportJobSpecV1(raw);
+    if (!parsed.ok)
+        return parsed;
+    if (JSON.stringify(canonicalSpecObject(parsed.value)) !== requestJson)
+        return { ok: false, errors: ['requestJson: not in canonical form'] };
+    return parsed;
+};

package/dist/esm/reporting/jobs/reportJobStatus.js

@@ -0,0 +1,87 @@
+/**
+ * Background report job status, failure stage and failure code vocabularies
+ * (core/specs/reporting/reporting-scheduler.md, "Report job table").
+ *
+ * Status is a monotonic milestone: retries change `attemptCount` and the lease, never move status backwards.
+ */
+export const REPORT_JOB_STATUSES = [
+    'accepted',
+    'running',
+    'source-ready',
+    'generated',
+    'completed',
+    'completed-with-notification-errors',
+    'failed',
+];
+export const REPORT_JOB_TERMINAL_STATUSES = ['completed', 'completed-with-notification-errors', 'failed'];
+/** Allowed status changes. Every non-terminal status may also move to `failed`. */
+export const REPORT_JOB_STATUS_TRANSITIONS = {
+    accepted: ['running', 'failed'],
+    running: ['source-ready', 'failed'],
+    'source-ready': ['generated', 'failed'],
+    generated: ['completed', 'completed-with-notification-errors', 'failed'],
+    completed: [],
+    'completed-with-notification-errors': [],
+    failed: [],
+};
+export const isReportJobStatus = (value) => typeof value === 'string' && REPORT_JOB_STATUSES.includes(value);
+export const isTerminalReportJobStatus = (status) => REPORT_JOB_TERMINAL_STATUSES.includes(status);
+export const canTransitionReportJobStatus = (from, to) => REPORT_JOB_STATUS_TRANSITIONS[from].includes(to);
+export const REPORT_JOB_NOTIFICATION_STATUSES = ['none', 'pending', 'delivered', 'partially-delivered', 'attachment-too-large', 'failed'];
+export const isReportJobNotificationStatus = (value) => typeof value === 'string' && REPORT_JOB_NOTIFICATION_STATUSES.includes(value);
+export const REPORT_JOB_FAILURE_STAGES = [
+    'request',
+    'authorization-or-entitlement',
+    'scope-resolution',
+    'source-load',
+    'report-model',
+    'document-render',
+    'artifact-persist',
+    'notification',
+];
+export const isReportJobFailureStage = (value) => typeof value === 'string' && REPORT_JOB_FAILURE_STAGES.includes(value);
+/**
+ * Each failure code and the stage it belongs to. `retries-exhausted` has no fixed stage: the writer records the
+ * stage the last attempt was in.
+ */
+export const REPORT_JOB_FAILURE_STAGE_BY_CODE = {
+    'request-invalid': 'request',
+    'request-hash-mismatch': 'request',
+    'message-row-mismatch': 'request',
+    'region-mismatch': 'request',
+    'unsupported-schema-version': 'request',
+    'notifications-not-enabled': 'request',
+    'report-type-disabled': 'request',
+    'company-not-found': 'authorization-or-entitlement',
+    'entitlement-missing': 'authorization-or-entitlement',
+    'scope-not-owned': 'scope-resolution',
+    'scope-load-failed': 'scope-resolution',
+    'no-ready-subscriptions': 'scope-resolution',
+    'source-not-ready': 'source-load',
+    'source-invalid': 'source-load',
+    'snapshot-too-large': 'source-load',
+    'snapshot-invalid': 'source-load',
+    'invalid-rate': 'report-model',
+    'invalid-currency': 'report-model',
+    'no-prepared-by': 'report-model',
+    'model-error': 'report-model',
+    'render-error': 'document-render',
+    'docx-invalid': 'document-render',
+    'artifact-too-large': 'document-render',
+    'artifact-conflict': 'artifact-persist',
+    'artifact-integrity': 'artifact-persist',
+    'retries-exhausted': null,
+};
+export const REPORT_JOB_FAILURE_CODES = Object.keys(REPORT_JOB_FAILURE_STAGE_BY_CODE);
+export const isReportJobFailureCode = (value) => typeof value === 'string' && Object.prototype.hasOwnProperty.call(REPORT_JOB_FAILURE_STAGE_BY_CODE, value);
+/**
+ * The stage to record for a failure code. `retries-exhausted` requires the caller's current stage.
+ */
+export const resolveReportJobFailureStage = (code, currentStage) => {
+    const stage = REPORT_JOB_FAILURE_STAGE_BY_CODE[code];
+    if (stage)
+        return stage;
+    if (!currentStage)
+        throw new Error(`Failure code ${code} needs the stage the attempt was in.`);
+    return currentStage;
+};

package/dist/esm/reporting/shared/reportTableEntities.js

@@ -0,0 +1,41 @@
+/**
+ * Azure Table entities arrive in two key casings: the REST API with `odata=nometadata` (the API's TableStore)
+ * returns `PartitionKey`/`RowKey`/`Timestamp`, while `@azure/data-tables` (reportworker, cloud-engine's
+ * `schedules` table) returns `partitionKey`/`rowKey`/`timestamp`/`etag`. The contracts use the REST casing;
+ * these helpers convert either shape and drop system properties.
+ */
+/** System and metadata properties a Table read may add; never part of a contract row. */
+export const REPORT_TABLE_SYSTEM_FIELDS = [
+    'Timestamp',
+    'timestamp',
+    'etag',
+    'odata.etag',
+    'odata.metadata',
+    'odata.type',
+    'odata.id',
+    'odata.editLink',
+];
+/**
+ * Returns a copy with `PartitionKey`/`RowKey` (from either casing), without system properties and without
+ * `null`/`undefined` values (some SDKs return absent properties as `null`). Conflicting casings are kept as-is so
+ * the caller's validation rejects them.
+ */
+export const normalizeReportTableEntity = (entity) => {
+    const result = {};
+    for (const [key, value] of Object.entries(entity)) {
+        if (value === null || value === undefined || REPORT_TABLE_SYSTEM_FIELDS.includes(key))
+            continue;
+        if (key === 'partitionKey' && !('PartitionKey' in entity))
+            result.PartitionKey = value;
+        else if (key === 'rowKey' && !('RowKey' in entity))
+            result.RowKey = value;
+        else
+            result[key] = value;
+    }
+    return result;
+};
+/** The `@azure/data-tables` shape of a contract row: `partitionKey`/`rowKey` instead of `PartitionKey`/`RowKey`. */
+export const toReportTableSdkEntity = (row) => {
+    const { PartitionKey, RowKey, ...rest } = row;
+    return { partitionKey: PartitionKey, rowKey: RowKey, ...rest };
+};

package/dist/esm/reporting/shared/reportingDigest.js

@@ -0,0 +1,57 @@
+/**
+ * SHA-256 through Web Crypto, which the API (Cloudflare Workers), cloud-engine and reportworker (Node 24) all
+ * provide as `globalThis.crypto.subtle`. The package has no Node or DOM typings, so the shapes are declared here.
+ */
+import { utf8ByteLength } from './reportingIds.js';
+const getSubtle = () => {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle || typeof subtle.digest !== 'function') {
+        throw new Error('Web Crypto (globalThis.crypto.subtle) is required for report job hashing.');
+    }
+    return subtle;
+};
+/** UTF-8 encodes a string without relying on `TextEncoder` typings. */
+export const encodeUtf8 = (value) => {
+    const bytes = new Uint8Array(utf8ByteLength(value));
+    let offset = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        let code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length) {
+            const next = value.charCodeAt(index + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+                index += 1;
+            }
+        }
+        if (code >= 0xd800 && code <= 0xdfff)
+            code = 0xfffd; // lone surrogate, as TextEncoder does
+        if (code < 0x80)
+            bytes[offset++] = code;
+        else if (code < 0x800) {
+            bytes[offset++] = 0xc0 | (code >> 6);
+            bytes[offset++] = 0x80 | (code & 0x3f);
+        }
+        else if (code < 0x10000) {
+            bytes[offset++] = 0xe0 | (code >> 12);
+            bytes[offset++] = 0x80 | ((code >> 6) & 0x3f);
+            bytes[offset++] = 0x80 | (code & 0x3f);
+        }
+        else {
+            bytes[offset++] = 0xf0 | (code >> 18);
+            bytes[offset++] = 0x80 | ((code >> 12) & 0x3f);
+            bytes[offset++] = 0x80 | ((code >> 6) & 0x3f);
+            bytes[offset++] = 0x80 | (code & 0x3f);
+        }
+    }
+    return bytes;
+};
+/** Lower-case hex SHA-256 of a UTF-8 string or of raw bytes. */
+export const sha256Hex = async (input) => {
+    const data = typeof input === 'string' ? encodeUtf8(input) : input;
+    const digest = new Uint8Array(await getSubtle().digest('SHA-256', data));
+    let hex = '';
+    for (const byte of digest)
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+};
+export const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;

package/dist/esm/reporting/shared/reportingIds.js

@@ -0,0 +1,88 @@
+/**
+ * Identifier rules shared by the background report job contracts and the report storage contracts.
+ *
+ * Every identifier that ends up in a Table key, a Blob path, a Service Bus MessageId (`:` separated) or a
+ * file name is validated here first. The rules are deliberately narrower than what storage accepts, so an
+ * accepted value is always safe in every one of those places.
+ */
+/** Company, cloud-account, schedule and action-group IDs: alphanumeric ends, `._-` inside, at most 80 characters. */
+export const REPORT_ENTITY_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,78}[A-Za-z0-9])?$/;
+/** Azure subscription and tenant IDs (GUIDs, any case). */
+export const REPORT_GUID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** Calendar dates as `YYYY-MM-DD`. */
+export const REPORT_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const hasControlCharacter = (value) => {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+};
+export const isReportEntityId = (value) => typeof value === 'string' && REPORT_ENTITY_ID_PATTERN.test(value);
+/**
+ * Company IDs on jobs, rows and messages: an entity ID of at most 56 characters, so the Service Bus MessageId
+ * `report-job:{companyId}:{jobId}` stays within its 128-character limit. Real IDs are `comp-` plus 15 characters.
+ */
+export const REPORT_JOB_COMPANY_ID_MAX_LENGTH = 56;
+export const isReportJobCompanyId = (value) => isReportEntityId(value) && value.length <= REPORT_JOB_COMPANY_ID_MAX_LENGTH;
+export const isReportGuid = (value) => typeof value === 'string' && REPORT_GUID_PATTERN.test(value);
+/** A plain-text value with no control characters, trimmed, within the length bounds. */
+export const isBoundedPlainText = (value, maxLength) => typeof value === 'string' && value.length > 0 && value.length <= maxLength && value === value.trim() && !hasControlCharacter(value);
+/** An exact ISO-8601 UTC timestamp as produced by `Date.prototype.toISOString`. */
+export const isIsoUtcTimestamp = (value) => {
+    if (typeof value !== 'string' || value.length !== 24)
+        return false;
+    const time = Date.parse(value);
+    return Number.isFinite(time) && new Date(time).toISOString() === value;
+};
+/** A real calendar date in `YYYY-MM-DD` form. */
+export const isCalendarDate = (value) => {
+    if (typeof value !== 'string' || !REPORT_DATE_PATTERN.test(value))
+        return false;
+    const time = Date.parse(`${value}T00:00:00.000Z`);
+    return Number.isFinite(time) && new Date(time).toISOString().slice(0, 10) === value;
+};
+/** An IANA time zone name the runtime's `Intl` recognises. */
+export const isIanaTimeZone = (value) => {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 64)
+        return false;
+    if (!/^(?:UTC|[A-Za-z][A-Za-z0-9_+-]*(?:\/[A-Za-z0-9_+-]+){1,2})$/.test(value))
+        return false;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Number of bytes `value` occupies as UTF-8 (no dependency on `TextEncoder`). */
+export const utf8ByteLength = (value) => {
+    let bytes = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code < 0x80)
+            bytes += 1;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && index + 1 < value.length) {
+            const next = value.charCodeAt(index + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                bytes += 4;
+                index += 1;
+            }
+            else
+                bytes += 3;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+};
+export const hasExactlyKeys = (value, required, optional = []) => {
+    const keys = Object.keys(value);
+    const allowed = new Set([...required, ...optional]);
+    return required.every(key => Object.prototype.hasOwnProperty.call(value, key)) && keys.every(key => allowed.has(key));
+};
+export const isPlainRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/esm/reporting/shared/reportingPaths.js

@@ -0,0 +1,23 @@
+/**
+ * The API's reporting path-segment rule (`sanitizePathSegment` in api/services/ReportingTemplates/ReportingTemplateService.ts
+ * and api/services/ReportingSettings/ReportingSettingsService.ts): trim, replace runs of characters outside
+ * `[A-Za-z0-9._-]` with `-`, trim leading and trailing `-`, and use the fallback when nothing is left.
+ */
+export const sanitizeReportingPathSegment = (value, fallback) => {
+    const normalized = value
+        .trim()
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return normalized || fallback;
+};
+export const REPORTING_DOCX_EXTENSION = '.docx';
+export const REPORT_FILE_NAME_MAX_LENGTH = 120;
+/**
+ * A generated-report file name as the API accepts it: unchanged by the sanitiser, ends with `.docx`,
+ * at most 120 characters, and not just the extension.
+ */
+export const isReportFileName = (value) => typeof value === 'string' &&
+    value.length > REPORTING_DOCX_EXTENSION.length &&
+    value.length <= REPORT_FILE_NAME_MAX_LENGTH &&
+    value.endsWith(REPORTING_DOCX_EXTENSION) &&
+    sanitizeReportingPathSegment(value, '') === value;

package/dist/esm/scheduler/index.js

@@ -1 +1,4 @@
-export * from './scheduler.js';
+export * from './schedulerContracts.js';
+export * from './schedulerValidation.js';
+export * from './resourceStrategy.js';
+export * from './weeklyAvailabilityFixtures.js';

package/dist/esm/scheduler/resourceStrategy.js

@@ -0,0 +1,2 @@
+export * from './resourceStrategyContracts.js';
+export * from './resourceStrategyValidation.js';