@memberjunction/core 6.2.0-edge.5 → 6.2.0-edge.6

package/dist/generic/contextTokens.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Context tokens and property defaults.
+ *
+ * A property (a User View property, a dashboard property, a query's server-set variable) can
+ * default to a fixed value or to a context token: a name from a closed list, worked out from the
+ * context user and the clock alone. The same resolver runs in the browser and on the server, so
+ * the two can differ only in the time zone they are given.
+ *
+ * - User tokens (`Context.UserID`, `Context.UserEmail`, `Context.UserName`) need a context user;
+ *   without one they throw rather than resolve to a blank.
+ * - **WARNING — SQL template escaping (`| sqlString`):** `Context.UserEmail` and `Context.UserName`
+ *   resolve to raw, unescaped strings (for example `O'Brien`) and reach Nunjucks query templates with
+ *   `autoescape: false`. Query templates **must** pipe them through `| sqlString`
+ *   (e.g. `WHERE Email = {{ Context.UserEmail | sqlString }}` or
+ *   `WHERE Name = {{ Context.UserName | sqlString }}`). Rendering `{{ Context.UserEmail }}` or
+ *   `{{ Context.UserName }}` bare produces broken SQL on apostrophes and opens SQL injection.
+ *   (User View properties are escaped automatically by `UserViewPropertyWhereClause`.)
+ * - Date tokens give a `YYYY-MM-DD` date in the given zone (`Context.Today`, `Context.StartOf*`),
+ *   or an ISO 8601 instant (`Context.Now`). Only date tokens take an offset.
+ * - The zone is an IANA name, `'UTC'` when none is given. Weeks start on Monday (ISO 8601) unless
+ *   the context says Sunday.
+ */
+/** Every context token. The list is closed: an app's own context is a property value, never a token. */
+export declare const CONTEXT_TOKENS: readonly ["Context.UserID", "Context.UserEmail", "Context.UserName", "Context.Now", "Context.Today", "Context.StartOfWeek", "Context.StartOfMonth", "Context.StartOfQuarter", "Context.StartOfYear"];
+/** A context token: one of {@link CONTEXT_TOKENS}. */
+export type ContextToken = typeof CONTEXT_TOKENS[number];
+/**
+ * The version of what {@link CONTEXT_TOKENS} means. Approval fingerprints include it, so an approval
+ * given under one meaning is stale under another. Bump it whenever a token is added, removed or
+ * worked out differently (a new week start, a different date format, a different user field).
+ */
+export declare const CONTEXT_TOKEN_CONTRACT_VERSION = 1;
+/** The value types a property can declare. */
+export declare const PROPERTY_VALUE_TYPES: readonly ["string", "number", "boolean", "date", "uuid"];
+/** A property's value type: one of {@link PROPERTY_VALUE_TYPES}. */
+export type PropertyValueType = typeof PROPERTY_VALUE_TYPES[number];
+/** The units an offset can move a date token by. */
+export declare const PROPERTY_OFFSET_UNITS: readonly ["day", "week", "month", "quarter", "year"];
+/** An offset unit: one of {@link PROPERTY_OFFSET_UNITS}. */
+export type PropertyOffsetUnit = typeof PROPERTY_OFFSET_UNITS[number];
+/** Moves a date token: `{ Amount: -30, Unit: 'day' }` is thirty days earlier. */
+export interface PropertyDefaultOffset {
+    /** A whole number; negative moves back. */
+    Amount: number;
+    Unit: PropertyOffsetUnit;
+}
+/** A property value, fixed or resolved. */
+export type PropertyValue = string | number | boolean | null;
+/**
+ * A property's default: a fixed value, or a token worked out when the value is used. Set exactly
+ * one of `Value` and `Token`. This is the shape the `MJ: User Views.Properties` JSON stores.
+ */
+export interface PropertyDefault {
+    /** A fixed value. Set this or Token, not both. */
+    Value?: PropertyValue;
+    /** A context token. Set this or Value, not both. */
+    Token?: ContextToken;
+    /** Moves a date token; refused on a user token and on a fixed value. */
+    Offset?: PropertyDefaultOffset;
+}
+/** The comparison a User View property's value drives. */
+export type UserViewPropertyOperator = '=' | '<>' | 'IN' | '>' | '>=' | '<' | '<=';
+/** The field a User View property filters, and how. */
+export interface UserViewPropertyTarget {
+    /** A field of the view's entity. */
+    Field: string;
+    Operator: UserViewPropertyOperator;
+}
+/**
+ * One declared property of a User View: a named, typed input that adds one predicate on its
+ * target field when a run gives it a value or it has a default. Stored as a JSON array in the
+ * `Properties` column of `MJ: User Views`.
+ */
+export interface UserViewProperty {
+    /** Unique within the view. */
+    Name: string;
+    /** The value's type. A value of another type is refused. */
+    Type: PropertyValueType;
+    /** Shown to whoever sets the property. */
+    Description?: string;
+    /** Used when a run gives no value: a fixed value or a context token. */
+    Default?: PropertyDefault;
+    /** True: a run with no value and no default is refused. */
+    IsRequired?: boolean;
+    /** False: only server code may set it, and a client value is refused. Default true. */
+    AllowOverride?: boolean;
+    /** The predicate the value drives. */
+    Target: UserViewPropertyTarget;
+}
+/** What a token is worked out from. */
+export interface PropertyResolutionContext {
+    /** The context user. Required by the user tokens. `UserInfo` fits. */
+    User?: {
+        ID: string;
+        Email?: string;
+        Name?: string;
+    };
+    /** The clock. Defaults to the current time. */
+    Now?: Date;
+    /** IANA time zone the date tokens are worked out in. Defaults to `'UTC'`. */
+    TimeZone?: string;
+    /** First day of the week for `Context.StartOfWeek`: 1 = Monday (default, ISO 8601), 0 = Sunday. */
+    WeekStartsOn?: 0 | 1;
+}
+/**
+ * The request header that carries the caller's IANA time zone. `GraphQLDataProvider` sends it;
+ * MJServer reads it into `UserPayload.TimeZone`.
+ */
+export declare const TIME_ZONE_HEADER = "x-mj-timezone";
+/** True when `name` is a time zone this runtime's `Intl` accepts (an IANA name such as `'Europe/Paris'`). */
+export declare function IsValidTimeZone(name: string | null | undefined): boolean;
+/** This runtime's own IANA time zone, or undefined where `Intl` gives none. */
+export declare function GetLocalTimeZone(): string | undefined;
+/** True when `token` is one of {@link CONTEXT_TOKENS}. */
+export declare function IsContextToken(token: string | null | undefined): token is ContextToken;
+/**
+ * Works out a property default: the fixed value, or the token resolved by {@link ResolveContextToken}.
+ * @throws when the default is malformed (see {@link ValidatePropertyDefault}) or the token cannot be resolved
+ */
+export declare function ResolvePropertyDefault(def: PropertyDefault, ctx: PropertyResolutionContext): PropertyValue;
+/**
+ * Works out one context token.
+ * @returns the user's ID, email or name; a `YYYY-MM-DD` date in the context's zone; or, for
+ *   `Context.Now`, an ISO 8601 instant
+ * @throws on an unknown token, a bad offset, an offset on a user token, a user token with no
+ *   context user, or an invalid time zone
+ */
+export declare function ResolveContextToken(token: ContextToken, offset: PropertyDefaultOffset | undefined, ctx: PropertyResolutionContext): string;
+/**
+ * Checks a property default against the property's type, as when the definition is saved.
+ * @returns the problems found; empty when the default is valid
+ */
+export declare function ValidatePropertyDefault(def: PropertyDefault, type: PropertyValueType): string[];
+/** True when a value fits the property type: a finite number, a boolean, a valid UUID or ISO date, or a string. Null fits every type. */
+export declare function IsPropertyValueOfType(value: PropertyValue, type: PropertyValueType): boolean;
+//# sourceMappingURL=contextTokens.d.ts.map

package/dist/generic/contextTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextTokens.d.ts","sourceRoot":"","sources":["../../src/generic/contextTokens.ts"],"names":[],"mappings":"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"}

package/dist/generic/contextTokens.js

@@ -0,0 +1,319 @@
+/**
+ * Context tokens and property defaults.
+ *
+ * A property (a User View property, a dashboard property, a query's server-set variable) can
+ * default to a fixed value or to a context token: a name from a closed list, worked out from the
+ * context user and the clock alone. The same resolver runs in the browser and on the server, so
+ * the two can differ only in the time zone they are given.
+ *
+ * - User tokens (`Context.UserID`, `Context.UserEmail`, `Context.UserName`) need a context user;
+ *   without one they throw rather than resolve to a blank.
+ * - **WARNING — SQL template escaping (`| sqlString`):** `Context.UserEmail` and `Context.UserName`
+ *   resolve to raw, unescaped strings (for example `O'Brien`) and reach Nunjucks query templates with
+ *   `autoescape: false`. Query templates **must** pipe them through `| sqlString`
+ *   (e.g. `WHERE Email = {{ Context.UserEmail | sqlString }}` or
+ *   `WHERE Name = {{ Context.UserName | sqlString }}`). Rendering `{{ Context.UserEmail }}` or
+ *   `{{ Context.UserName }}` bare produces broken SQL on apostrophes and opens SQL injection.
+ *   (User View properties are escaped automatically by `UserViewPropertyWhereClause`.)
+ * - Date tokens give a `YYYY-MM-DD` date in the given zone (`Context.Today`, `Context.StartOf*`),
+ *   or an ISO 8601 instant (`Context.Now`). Only date tokens take an offset.
+ * - The zone is an IANA name, `'UTC'` when none is given. Weeks start on Monday (ISO 8601) unless
+ *   the context says Sunday.
+ */
+import { IsValidUUID } from '@memberjunction/global';
+/** Every context token. The list is closed: an app's own context is a property value, never a token. */
+export const CONTEXT_TOKENS = [
+    'Context.UserID',
+    'Context.UserEmail',
+    'Context.UserName',
+    'Context.Now',
+    'Context.Today',
+    'Context.StartOfWeek',
+    'Context.StartOfMonth',
+    'Context.StartOfQuarter',
+    'Context.StartOfYear',
+];
+/**
+ * The version of what {@link CONTEXT_TOKENS} means. Approval fingerprints include it, so an approval
+ * given under one meaning is stale under another. Bump it whenever a token is added, removed or
+ * worked out differently (a new week start, a different date format, a different user field).
+ */
+export const CONTEXT_TOKEN_CONTRACT_VERSION = 1;
+/** The value types a property can declare. */
+export const PROPERTY_VALUE_TYPES = ['string', 'number', 'boolean', 'date', 'uuid'];
+/** The units an offset can move a date token by. */
+export const PROPERTY_OFFSET_UNITS = ['day', 'week', 'month', 'quarter', 'year'];
+/**
+ * The request header that carries the caller's IANA time zone. `GraphQLDataProvider` sends it;
+ * MJServer reads it into `UserPayload.TimeZone`.
+ */
+export const TIME_ZONE_HEADER = 'x-mj-timezone';
+/** Longer than any IANA name; a longer header value is refused without asking `Intl`. */
+const MAX_TIME_ZONE_LENGTH = 64;
+const USER_TOKENS = ['Context.UserID', 'Context.UserEmail', 'Context.UserName'];
+/** The property types each token's value can fill. */
+const TOKEN_VALUE_TYPES = {
+    'Context.UserID': ['uuid', 'string'],
+    'Context.UserEmail': ['string'],
+    'Context.UserName': ['string'],
+    'Context.Now': ['date', 'string'],
+    'Context.Today': ['date', 'string'],
+    'Context.StartOfWeek': ['date', 'string'],
+    'Context.StartOfMonth': ['date', 'string'],
+    'Context.StartOfQuarter': ['date', 'string'],
+    'Context.StartOfYear': ['date', 'string'],
+};
+/** `YYYY-MM-DD`, optionally followed by an ISO 8601 time and zone. */
+const ISO_DATE_VALUE = /^(\d{4})-(\d{2})-(\d{2})(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})?)?$/;
+/** True when `name` is a time zone this runtime's `Intl` accepts (an IANA name such as `'Europe/Paris'`). */
+export function IsValidTimeZone(name) {
+    if (typeof name !== 'string' || name.length === 0 || name.length > MAX_TIME_ZONE_LENGTH) {
+        return false;
+    }
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: name });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** This runtime's own IANA time zone, or undefined where `Intl` gives none. */
+export function GetLocalTimeZone() {
+    try {
+        const zone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        return IsValidTimeZone(zone) ? zone : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when `token` is one of {@link CONTEXT_TOKENS}. */
+export function IsContextToken(token) {
+    return typeof token === 'string' && CONTEXT_TOKENS.includes(token);
+}
+/**
+ * Works out a property default: the fixed value, or the token resolved by {@link ResolveContextToken}.
+ * @throws when the default is malformed (see {@link ValidatePropertyDefault}) or the token cannot be resolved
+ */
+export function ResolvePropertyDefault(def, ctx) {
+    const errors = shapeErrors(def);
+    if (errors.length > 0) {
+        throw new Error(`Invalid property default: ${errors.join(' ')}`);
+    }
+    return def.Token !== undefined ? ResolveContextToken(def.Token, def.Offset, ctx) : (def.Value ?? null);
+}
+/**
+ * Works out one context token.
+ * @returns the user's ID, email or name; a `YYYY-MM-DD` date in the context's zone; or, for
+ *   `Context.Now`, an ISO 8601 instant
+ * @throws on an unknown token, a bad offset, an offset on a user token, a user token with no
+ *   context user, or an invalid time zone
+ */
+export function ResolveContextToken(token, offset, ctx) {
+    const errors = tokenErrors(token, offset);
+    if (errors.length > 0) {
+        throw new Error(errors.join(' '));
+    }
+    if (USER_TOKENS.includes(token)) {
+        return resolveUserToken(token, ctx);
+    }
+    const timeZone = ctx.TimeZone ?? 'UTC';
+    if (!IsValidTimeZone(timeZone)) {
+        throw new Error(`Invalid time zone "${timeZone}".`);
+    }
+    const now = ctx.Now ?? new Date();
+    if (isNaN(now.getTime())) {
+        throw new Error('The context clock (Now) is not a valid date.');
+    }
+    const local = wallClockIn(now, timeZone);
+    if (token === 'Context.Now') {
+        return offset ? wallClockToInstant({ ...local, ...addOffset(local, offset) }, timeZone).toISOString() : now.toISOString();
+    }
+    const start = startOfToken(token, local, ctx.WeekStartsOn === 0 ? 0 : 1);
+    return formatCalendarDate(offset ? addOffset(start, offset) : start);
+}
+/**
+ * Checks a property default against the property's type, as when the definition is saved.
+ * @returns the problems found; empty when the default is valid
+ */
+export function ValidatePropertyDefault(def, type) {
+    if (!PROPERTY_VALUE_TYPES.includes(type)) {
+        return [`Unknown property type "${type}". Allowed: ${PROPERTY_VALUE_TYPES.join(', ')}.`];
+    }
+    const errors = shapeErrors(def);
+    if (errors.length > 0) {
+        return errors;
+    }
+    if (def.Token !== undefined) {
+        return TOKEN_VALUE_TYPES[def.Token].includes(type) ? [] : [`${def.Token} cannot default a ${type} property.`];
+    }
+    return IsPropertyValueOfType(def.Value ?? null, type) ? [] : [`Value ${JSON.stringify(def.Value)} is not a valid ${type}.`];
+}
+/** Problems with a default's shape that need no property type: Value vs Token, the token, the offset. */
+function shapeErrors(def) {
+    if (def === null || typeof def !== 'object' || Array.isArray(def)) {
+        return ['A default must be an object with Value or Token.'];
+    }
+    const hasValue = def.Value !== undefined;
+    const hasToken = def.Token !== undefined;
+    if (hasValue && hasToken) {
+        return ['Set Value or Token, not both.'];
+    }
+    if (!hasValue && !hasToken) {
+        return ['Set Value or Token.'];
+    }
+    if (hasValue) {
+        return def.Offset !== undefined ? ['Offset applies only to a token.'] : [];
+    }
+    return tokenErrors(def.Token, def.Offset);
+}
+/** Problems with a token and its offset. */
+function tokenErrors(token, offset) {
+    if (!IsContextToken(token)) {
+        return [`Unknown token "${token}". Allowed: ${CONTEXT_TOKENS.join(', ')}.`];
+    }
+    if (offset === undefined) {
+        return [];
+    }
+    if (USER_TOKENS.includes(token)) {
+        return [`${token} cannot take an offset; offsets apply to date tokens only.`];
+    }
+    if (offset === null || typeof offset !== 'object') {
+        return ['Offset must be an object with Amount and Unit.'];
+    }
+    const errors = [];
+    if (!PROPERTY_OFFSET_UNITS.includes(offset.Unit)) {
+        errors.push(`Unknown offset unit "${offset.Unit}". Allowed: ${PROPERTY_OFFSET_UNITS.join(', ')}.`);
+    }
+    if (!Number.isInteger(offset.Amount)) {
+        errors.push(`Offset Amount must be a whole number; got ${JSON.stringify(offset.Amount)}.`);
+    }
+    return errors;
+}
+function resolveUserToken(token, ctx) {
+    const user = ctx.User;
+    if (!user?.ID) {
+        throw new Error(`${token} needs a context user, and none was given.`);
+    }
+    const value = token === 'Context.UserID' ? user.ID : token === 'Context.UserEmail' ? user.Email : user.Name;
+    if (!value) {
+        throw new Error(`${token}: the context user has no value for it.`);
+    }
+    return value;
+}
+/** True when a value fits the property type: a finite number, a boolean, a valid UUID or ISO date, or a string. Null fits every type. */
+export function IsPropertyValueOfType(value, type) {
+    if (value === null) {
+        return true;
+    }
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'uuid':
+            return typeof value === 'string' && IsValidUUID(value);
+        case 'date':
+            return typeof value === 'string' && isValidDateValue(value);
+        default:
+            return false;
+    }
+}
+/** An ISO 8601 date or date-time whose date part is a real calendar day (no 30 February). */
+function isValidDateValue(value) {
+    const match = ISO_DATE_VALUE.exec(value);
+    if (!match || isNaN(Date.parse(value))) {
+        return false;
+    }
+    const date = { year: Number(match[1]), month: Number(match[2]), day: Number(match[3]) };
+    return date.month >= 1 && date.month <= 12 && date.day >= 1 && date.day <= daysInMonth(date.year, date.month);
+}
+/** The first day of the period a date token names, from today's date in the zone. */
+function startOfToken(token, today, weekStartsOn) {
+    switch (token) {
+        case 'Context.StartOfWeek': {
+            const dayOfWeek = new Date(Date.UTC(today.year, today.month - 1, today.day)).getUTCDay();
+            return addDays(today, -((dayOfWeek - weekStartsOn + 7) % 7));
+        }
+        case 'Context.StartOfMonth':
+            return { year: today.year, month: today.month, day: 1 };
+        case 'Context.StartOfQuarter':
+            return { year: today.year, month: Math.floor((today.month - 1) / 3) * 3 + 1, day: 1 };
+        case 'Context.StartOfYear':
+            return { year: today.year, month: 1, day: 1 };
+        default:
+            return { year: today.year, month: today.month, day: today.day };
+    }
+}
+/** Moves a date by an offset. Month-based units land on the target month's last day when it is shorter. */
+function addOffset(date, offset) {
+    switch (offset.Unit) {
+        case 'day':
+            return addDays(date, offset.Amount);
+        case 'week':
+            return addDays(date, offset.Amount * 7);
+        case 'month':
+            return addMonths(date, offset.Amount);
+        case 'quarter':
+            return addMonths(date, offset.Amount * 3);
+        case 'year':
+            return addMonths(date, offset.Amount * 12);
+        default:
+            throw new Error(`Unknown offset unit "${offset.Unit}".`);
+    }
+}
+function addDays(date, days) {
+    const moved = new Date(Date.UTC(date.year, date.month - 1, date.day + days));
+    return { year: moved.getUTCFullYear(), month: moved.getUTCMonth() + 1, day: moved.getUTCDate() };
+}
+function addMonths(date, months) {
+    const index = date.year * 12 + (date.month - 1) + months;
+    const year = Math.floor(index / 12);
+    const month = index - year * 12 + 1;
+    return { year, month, day: Math.min(date.day, daysInMonth(year, month)) };
+}
+function daysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+function formatCalendarDate(date) {
+    const pad = (n, width) => String(n).padStart(width, '0');
+    return `${pad(date.year, 4)}-${pad(date.month, 2)}-${pad(date.day, 2)}`;
+}
+/** The calendar date and wall-clock time of an instant in a zone. */
+function wallClockIn(instant, timeZone) {
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+        second: 'numeric',
+    }).formatToParts(instant);
+    const part = (type) => Number(parts.find((p) => p.type === type)?.value);
+    return {
+        year: part('year'),
+        month: part('month'),
+        day: part('day'),
+        hour: part('hour') % 24, // some engines write midnight as 24 even with h23
+        minute: part('minute'),
+        second: part('second'),
+        millisecond: instant.getUTCMilliseconds(),
+    };
+}
+/** The instant a wall-clock time in a zone names. Two passes settle the zone offset across a DST change. */
+function wallClockToInstant(local, timeZone) {
+    const asUTC = Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute, local.second, local.millisecond);
+    const firstGuess = asUTC - zoneOffsetMs(asUTC, timeZone);
+    return new Date(asUTC - zoneOffsetMs(firstGuess, timeZone));
+}
+/** How far the zone's wall clock is ahead of UTC at an instant, in milliseconds. */
+function zoneOffsetMs(instantMs, timeZone) {
+    const local = wallClockIn(new Date(instantMs), timeZone);
+    return Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute, local.second, local.millisecond) - instantMs;
+}
+//# sourceMappingURL=contextTokens.js.map

package/dist/generic/contextTokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextTokens.js","sourceRoot":"","sources":["../../src/generic/contextTokens.ts"],"names":[],"mappings":"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"}

package/dist/generic/databaseProviderBase.d.ts

@@ -18,6 +18,29 @@ export type FieldChange = {
     oldValue: unknown;
     newValue: unknown;
 };
+/**
+ * Options controlling how {@link Metadata.GetRecordDependencies} discovers dependent records.
+ */
+export interface GetRecordDependenciesOptions {
+    /**
+     * Which category of foreign-key links to inspect:
+     * - `'both'` (default): Both hard database foreign keys (`EntityField.RelatedEntityID`) and
+     *   polymorphic / soft foreign keys (`EntityField.EntityIDFieldName`).
+     * - `'hard'`: Only direct foreign-key relationships (`RelatedEntityID` is set and `EntityIDFieldName` is empty).
+     * - `'soft'`: Only polymorphic foreign-key relationships (`EntityIDFieldName` is set).
+     */
+    LinkType?: 'both' | 'hard' | 'soft';
+    /**
+     * Whether to include high-volume system audit/telemetry entities (`MJ: Record Changes`,
+     * `MJ: Audit Logs`, `MJ: User Record Logs`, `MJ: User RecordAccess`).
+     * Defaults to `true` for delete/merge safety checks; UI record-link viewers pass `false`.
+     */
+    IncludeSystemEntities?: boolean;
+    /**
+     * Optional allow-list of entity names to restrict the dependency scan to.
+     */
+    EntityNames?: string[];
+}
 /**
  * Result of save SQL generation. Subclasses populate this from their dialect-specific
  * SQL generators (stored procedure calls, function calls, etc.).
@@ -340,17 +363,21 @@ export declare abstract class DatabaseProviderBase extends ProviderBase {
     /**
      * Builds SQL for hard-link (foreign key) dependency queries.
      * Returns a UNION ALL query across all dependent entities.
-     * @param entityDependencies The entity-level dependency metadata
+     * @param entityDependencies The entity-level dependency metadata (or entity name to resolve dependencies for)
      * @param compositeKey The primary key of the record being checked
+     * @param options Optional filtering options for dependency discovery
+     * @param contextUser Optional user context for permission filtering
      */
-    protected abstract BuildHardLinkDependencySQL(entityDependencies: EntityDependency[], compositeKey: CompositeKey): string;
+    protected abstract BuildHardLinkDependencySQL(entityDependencies: EntityDependency[] | string, compositeKey: CompositeKey, options?: GetRecordDependenciesOptions, contextUser?: UserInfo): string;
     /**
      * Builds SQL for soft-link dependency queries (entities using EntityIDFieldName pattern).
      * Returns a UNION ALL query across all soft-linked entities.
      * @param entityName The entity name being checked for dependencies
      * @param compositeKey The primary key of the record
+     * @param options Optional filtering options for dependency discovery
+     * @param contextUser Optional user context for permission filtering
      */
-    protected abstract BuildSoftLinkDependencySQL(entityName: string, compositeKey: CompositeKey): string;
+    protected abstract BuildSoftLinkDependencySQL(entityName: string, compositeKey: CompositeKey, options?: GetRecordDependenciesOptions, contextUser?: UserInfo): string;
     /**
      * Generates the SQL (and optional parameters) for a Save (Create or Update) operation.
      * Each provider produces its own dialect: SQL Server generates T-SQL EXEC statements,
@@ -556,6 +583,39 @@ export declare abstract class DatabaseProviderBase extends ProviderBase {
     /**************************************************************************/
     /**************************************************************************/
     /**************************************************************************/
+    /**
+     * High-volume system audit/telemetry entities excluded when `options.IncludeSystemEntities === false`.
+     */
+    private static readonly _systemDependencyEntityNames;
+    /**
+     * Normalizes `(contextUserOrOptions, options)` so callers can invoke `GetRecordDependencies`
+     * with either `(entityName, key, options)` or `(entityName, key, contextUser, options)`.
+     */
+    protected resolveRecordDependencyArgs(contextUserOrOptions?: UserInfo | GetRecordDependenciesOptions, options?: GetRecordDependenciesOptions): {
+        contextUser?: UserInfo;
+        options?: GetRecordDependenciesOptions;
+    };
+    /**
+     * Determines whether `relatedEntity` should be included in a record dependency scan
+     * based on `options` (`IncludeSystemEntities`, `EntityNames`) and `contextUser` read permissions.
+     */
+    protected shouldIncludeDependencyEntity(relatedEntity: EntityInfo, options?: GetRecordDependenciesOptions, contextUser?: UserInfo): boolean;
+    /**
+     * Checks name-based dependency filters (`IncludeSystemEntities` and `EntityNames`)
+     * when only the entity name is available.
+     */
+    protected shouldIncludeDependencyEntityName(relatedEntityName: string, options?: GetRecordDependenciesOptions): boolean;
+    /**
+     * Resolves an `EntityDependency[] | string` argument to an `EntityDependency[]` array.
+     * Supports passing either a pre-resolved `EntityDependency[]` list or an `entityName` string.
+     */
+    protected resolveEntityDependencies(entityDependenciesOrName: EntityDependency[] | string): EntityDependency[];
+    /**
+     * Selects `relatedEntity.BaseTable` when `BaseTable` is defined, the entity is not virtual,
+     * and all referenced columns (`PrimaryKeys` plus `referencedFieldNames`) are physical (`!f.IsVirtual`).
+     * Falls back to `relatedEntity.BaseView` when any referenced column is virtual or `BaseTable` is absent.
+     */
+    protected resolveDependencySourceObject(relatedEntity: EntityInfo, referencedFieldNames: string[]): string;
     /**
      * Returns a list of record-level dependencies — records in other entities linked to
      * the specified entity/record via foreign keys (hard links) or EntityIDFieldName
@@ -563,9 +623,10 @@ export declare abstract class DatabaseProviderBase extends ProviderBase {
      *
      * @param entityName The entity name to check
      * @param compositeKey The primary key(s) of the record
-     * @param contextUser Optional context user
+     * @param contextUser Optional context user (or options when called with 3 args)
+     * @param options Optional filtering options (`LinkType`, `IncludeSystemEntities`, `EntityNames`)
      */
-    GetRecordDependencies(entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo): Promise<RecordDependency[]>;
+    GetRecordDependencies(entityName: string, compositeKey: CompositeKey, contextUser?: UserInfo | GetRecordDependenciesOptions, options?: GetRecordDependenciesOptions): Promise<RecordDependency[]>;
     /**
      * The value to write into a dependent record's link column so it points at the surviving record
      * of a merge.