@happyvertical/smrt-support 0.39.2

package/dist/services/support-intake-service.d.ts

@@ -0,0 +1,106 @@
+import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { SupportCase } from '../models/support-case.js';
+import { SupportChannelBinding, SupportChannelBindingCollection } from '../models/support-channel-binding.js';
+import { SupportInteraction } from '../models/support-interaction.js';
+import { SupportCaseService } from './support-case-service.js';
+/** Qualified source types intake understands. */
+export declare const CHAT_MESSAGE_SOURCE_TYPE = "@happyvertical/smrt-chat:ChatMessage";
+export declare const CHAT_ROOM_TARGET_TYPE = "@happyvertical/smrt-chat:ChatRoom";
+export declare const EMAIL_SOURCE_TYPE = "@happyvertical/smrt-messages:Email";
+export declare const EMAIL_ACCOUNT_TARGET_TYPE = "@happyvertical/smrt-messages:EmailAccount";
+export interface InboundChatMessage {
+    messageId: string;
+    roomId: string;
+    threadId?: string | null;
+    senderProfileId: string;
+    /** Chat role; only `user` messages are client inbound. */
+    role?: string;
+    content: string;
+    tenantId?: string | null;
+    occurredAt?: Date;
+}
+export interface InboundEmail {
+    emailId: string;
+    accountId: string;
+    fromAddress: string;
+    fromName?: string;
+    subject?: string;
+    body: string;
+    /** RFC 822 Message-ID of this email. */
+    rfcMessageId?: string | null;
+    /** RFC 822 Message-ID this email replies to. */
+    inReplyTo?: string | null;
+    tenantId?: string | null;
+    occurredAt?: Date;
+}
+export interface IntakeResult {
+    outcome: 'created' | 'joined' | 'reopened' | 'skipped';
+    reason?: string;
+    supportCase?: SupportCase;
+    interaction?: SupportInteraction;
+    binding?: SupportChannelBinding;
+}
+export interface SupportIntakeOptions extends SmrtObjectOptions {
+    /**
+     * Resolve the Client profile for an inbound email sender. When omitted and
+     * the binding has no default client, the case is parked with
+     * `metadata.unresolvedClient = true` for operator triage.
+     */
+    resolveClientProfileId?: (input: {
+        email: string;
+        name?: string;
+        tenantId?: string | null;
+    }) => Promise<string | null>;
+    /**
+     * Called after intake creates or updates a case — the AI workflow and the
+     * target engine attach here without a hard dependency cycle.
+     */
+    onCaseIntake?: (result: IntakeResult) => Promise<void>;
+}
+export declare class SupportIntakeService {
+    readonly caseService: SupportCaseService;
+    readonly bindings: SupportChannelBindingCollection;
+    private readonly options;
+    private readonly conversationMutex;
+    protected constructor(caseService: SupportCaseService, bindings: SupportChannelBindingCollection, options: SupportIntakeOptions);
+    static create(options: SupportIntakeOptions): Promise<SupportIntakeService>;
+    /** Conversation key for a chat room/thread. */
+    static chatThreadKey(roomId: string, threadId?: string | null): string;
+    /** Idempotency key for a chat message. */
+    static chatSourceKey(messageId: string): string;
+    /** Idempotency key for an email. */
+    static emailSourceKey(emailId: string): string;
+    /**
+     * Ingest one inbound chat message from a bound room: create-or-join the
+     * conversation's case and record the interaction.
+     */
+    ingestChatMessage(input: InboundChatMessage): Promise<IntakeResult>;
+    /**
+     * Ingest one inbound email from a bound account: joins the RFC thread's
+     * case when `inReplyTo` references a known interaction, else creates a new
+     * case keyed by the message id. Mail sent FROM the binding's own addresses
+     * is skipped (our outbound side of the conversation).
+     */
+    ingestEmail(input: InboundEmail): Promise<IntakeResult>;
+    /** The shared create-or-join core (deterministic per conversation key). */
+    private createOrJoin;
+    private createOrJoinExclusive;
+    private findResolvedByThreadKey;
+    private findInteractionByRfcMessageId;
+}
+/** Interceptor name used for registration/unregistration. */
+export declare const SUPPORT_INTAKE_INTERCEPTOR = "smrt-support:intake";
+/**
+ * Opt-in ambient intake: observe saves of `ChatMessage` and `Email` rows via
+ * core `GlobalInterceptors` and feed them through the intake service. Only
+ * containers with an enabled {@link SupportChannelBinding} produce cases;
+ * everything else passes through untouched. Errors are logged, never thrown —
+ * intake must not break the source package's save path.
+ *
+ * @returns An unregister function.
+ */
+export declare function registerSupportIntake(intake: SupportIntakeService, options?: {
+    onError?: (error: unknown, instance: SmrtObject) => void;
+}): () => void;
+export default SupportIntakeService;
+//# sourceMappingURL=support-intake-service.d.ts.map

package/dist/services/support-intake-service.d.ts.map

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

package/dist/services/support-plan-admin-service.d.ts

@@ -0,0 +1,45 @@
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { SupportCompensationPlan, SupportCompensationPlanCollection } from '../models/support-compensation-plan.js';
+import { SupportPlan, SupportPlanCollection } from '../models/support-plan.js';
+import { SupportPrincipal } from '../permissions.js';
+/** Thrown when a plan write is attempted without the manage-plans split. */
+export declare class PlanAdminDeniedError extends Error {
+    constructor(message: string);
+}
+export interface PlanAdminActor {
+    principal: SupportPrincipal;
+}
+export declare class SupportPlanAdminService {
+    readonly plans: SupportPlanCollection;
+    readonly compensationPlans: SupportCompensationPlanCollection;
+    protected constructor(collections: {
+        plans: SupportPlanCollection;
+        compensationPlans: SupportCompensationPlanCollection;
+    });
+    static create(options: SmrtObjectOptions): Promise<SupportPlanAdminService>;
+    /** Create (or overwrite via natural key) a Managed Support Plan. */
+    savePlan(input: PlanAdminActor & {
+        fields: Record<string, unknown>;
+    }): Promise<SupportPlan>;
+    /** Update an existing Managed Support Plan's fields. */
+    updatePlan(planId: string, input: PlanAdminActor & {
+        fields: Record<string, unknown>;
+    }): Promise<SupportPlan>;
+    /** Archive a Managed Support Plan (soft retirement; history untouched). */
+    archivePlan(planId: string, input: PlanAdminActor): Promise<SupportPlan>;
+    /** Create a Support Compensation Plan (effective-dated earning terms). */
+    saveCompensationPlan(input: PlanAdminActor & {
+        fields: Record<string, unknown>;
+    }): Promise<SupportCompensationPlan>;
+    /** Update an existing Support Compensation Plan's fields. */
+    updateCompensationPlan(planId: string, input: PlanAdminActor & {
+        fields: Record<string, unknown>;
+    }): Promise<SupportCompensationPlan>;
+    /** Archive a Support Compensation Plan. */
+    archiveCompensationPlan(planId: string, input: PlanAdminActor): Promise<SupportCompensationPlan>;
+    protected assertManager(principal: SupportPrincipal | undefined, act: string): void;
+    /** Cross-tenant plan writes are refused when both sides carry a tenant. */
+    protected assertTenant(principal: SupportPrincipal, planTenantId: string | null): void;
+}
+export default SupportPlanAdminService;
+//# sourceMappingURL=support-plan-admin-service.d.ts.map

package/dist/services/support-plan-admin-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support-plan-admin-service.d.ts","sourceRoot":"","sources":["../../src/services/support-plan-admin-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EACL,KAAK,uBAAuB,EAC5B,iCAAiC,EAClC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EACL,KAAK,WAAW,EAChB,qBAAqB,EACtB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,4EAA4E;AAC5E,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,gBAAgB,CAAC;CAC7B;AAED,qBAAa,uBAAuB;IAClC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,iCAAiC,CAAC;IAE9D,SAAS,aAAa,WAAW,EAAE;QACjC,KAAK,EAAE,qBAAqB,CAAC;QAC7B,iBAAiB,EAAE,iCAAiC,CAAC;KACtD;WAKY,MAAM,CACjB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,uBAAuB,CAAC;IAQnC,oEAAoE;IAC9D,QAAQ,CACZ,KAAK,EAAE,cAAc,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAC1D,OAAO,CAAC,WAAW,CAAC;IASvB,wDAAwD;IAClD,UAAU,CACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAC1D,OAAO,CAAC,WAAW,CAAC;IAYvB,2EAA2E;IACrE,WAAW,CACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,WAAW,CAAC;IAOvB,0EAA0E;IACpE,oBAAoB,CACxB,KAAK,EAAE,cAAc,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAC1D,OAAO,CAAC,uBAAuB,CAAC;IASnC,6DAA6D;IACvD,sBAAsB,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAC1D,OAAO,CAAC,uBAAuB,CAAC;IAYnC,2CAA2C;IACrC,uBAAuB,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,uBAAuB,CAAC;IAOnC,SAAS,CAAC,aAAa,CACrB,SAAS,EAAE,gBAAgB,GAAG,SAAS,EACvC,GAAG,EAAE,MAAM,GACV,IAAI;IAQP,2EAA2E;IAC3E,SAAS,CAAC,YAAY,CACpB,SAAS,EAAE,gBAAgB,EAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,IAAI;CAUR;AAED,eAAe,uBAAuB,CAAC"}

package/dist/services/support-routing-service.d.ts

@@ -0,0 +1,117 @@
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { SupportCase } from '../models/support-case.js';
+import { SupportAvailabilityCollection, SupportQualificationCollection, SupportSpecialistCollection } from '../models/support-specialist.js';
+import { SupportPrincipal } from '../permissions.js';
+import { SupportActorKind } from '../types.js';
+import { SupportCaseService } from './support-case-service.js';
+/**
+ * Named scoring weights, so the ranking is auditable against the code.
+ * Factors carry the raw signals; the score composes them with these weights.
+ */
+export declare const ROUTING_WEIGHTS: {
+    /** Case/plan preferred specialist (FR-30) — considered first. */
+    readonly PREFERRED_SPECIALIST: 100;
+    /** Effective `expert` Project Support Qualification. */
+    readonly QUALIFICATION_EXPERT: 30;
+    /** Effective `qualified` Project Support Qualification. */
+    readonly QUALIFICATION_QUALIFIED: 20;
+    /** Effective `trainee` Project Support Qualification. */
+    readonly QUALIFICATION_TRAINEE: 5;
+    /** An active on-call span at the routing instant. */
+    readonly ON_CALL: 25;
+    /** A weekly availability window covering the routing instant. */
+    readonly WEEKLY_AVAILABLE: 15;
+    /** Maximum workload-headroom bonus (scaled by free capacity). */
+    readonly WORKLOAD_HEADROOM_MAX: 10;
+    /** Case language ∈ specialist languages. */
+    readonly LANGUAGE_MATCH: 10;
+};
+/** One specialist's routing evaluation for a case. */
+export interface RankedSpecialist {
+    specialistId: string;
+    displayName: string;
+    score: number;
+    /** Whether every hard eligibility filter passed. */
+    eligible: boolean;
+    /** The raw signals behind the score/eligibility (rationale display). */
+    factors: Record<string, number | string | boolean>;
+}
+/** Result of an {@link SupportRoutingService.autoAssign} attempt. */
+export interface AutoAssignResult {
+    assigned: boolean;
+    specialistId?: string;
+    ranking: RankedSpecialist[];
+}
+/** Thrown when a manual reassignment is refused (permission or tenant). */
+export declare class ReassignDeniedError extends Error {
+    constructor(message: string);
+}
+/** Options for {@link SupportRoutingService.create}. */
+export interface SupportRoutingServiceOptions extends SmrtObjectOptions {
+    /** Share an existing case service (and its collections) with the router. */
+    caseService?: SupportCaseService;
+}
+/**
+ * The routing engine. Construct with {@link SupportRoutingService.create}.
+ */
+export declare class SupportRoutingService {
+    readonly caseService: SupportCaseService;
+    readonly specialists: SupportSpecialistCollection;
+    readonly qualifications: SupportQualificationCollection;
+    readonly availabilities: SupportAvailabilityCollection;
+    protected constructor(collections: {
+        caseService: SupportCaseService;
+        specialists: SupportSpecialistCollection;
+        qualifications: SupportQualificationCollection;
+        availabilities: SupportAvailabilityCollection;
+    });
+    static create(options: SupportRoutingServiceOptions): Promise<SupportRoutingService>;
+    private resolveCase;
+    /**
+     * Rank every Support Specialist for a case at an instant.
+     *
+     * Hard eligibility filters — each recorded as a factor:
+     * - `status` must be `active`;
+     * - when the case carries a `projectId`, an *effective* Project Support
+     *   Qualification for that project (`projectQualification` is the level,
+     *   or `'expired'`/`'none'` on failure);
+     * - open assigned cases below `maxConcurrentCases` (`openCases`,
+     *   `workloadExceeded`);
+     * - available at `at`: a weekly window in the specialist's own timezone or
+     *   an active on-call span, and not inside a time-off span
+     *   (`weeklyAvailable`, `onCall`, `timeOff`).
+     *
+     * Ineligible specialists are returned too (`eligible: false`) so the UI
+     * can show the failing factor. Sorted by score descending, then display
+     * name, then id.
+     */
+    rankSpecialists(caseRef: SupportCase | string, opts?: {
+        at?: Date;
+        exclude?: string[];
+    }): Promise<RankedSpecialist[]>;
+    private evaluateSpecialist;
+    /**
+     * Assign the top eligible ranked specialist, recording the rationale
+     * (winning factors plus the compact top of the ranking) on the assignment
+     * event. When no one is eligible, records an unrouted `note` event with
+     * the full ranking and returns `assigned: false`.
+     */
+    autoAssign(caseRef: SupportCase | string, opts?: {
+        at?: Date;
+        exclude?: string[];
+        actorKind?: SupportActorKind;
+    }): Promise<AutoAssignResult>;
+    /**
+     * Manual reassignment override (FR-30). Requires the
+     * `support.reassign-case` permission split on the acting principal and
+     * refuses cross-tenant acts; the assignment event carries
+     * `{ manual: true, note }` as its rationale.
+     */
+    reassign(caseRef: SupportCase | string, input: {
+        specialistId: string;
+        principal: SupportPrincipal;
+        note?: string;
+    }): Promise<SupportCase>;
+}
+export default SupportRoutingService;
+//# sourceMappingURL=support-routing-service.d.ts.map

package/dist/services/support-routing-service.d.ts.map

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

package/dist/services/time-entry-approval-service.d.ts

@@ -0,0 +1,162 @@
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { ServiceTimeEntry, ServiceTimeEntryCollection } from '../models/service-time-entry.js';
+import { SupportCase } from '../models/support-case.js';
+import { SupportCompensationPlanCollection } from '../models/support-compensation-plan.js';
+import { SupportCharge, SupportChargeCollection, SupportCompensation, SupportCompensationCollection } from '../models/support-settlement.js';
+import { SupportPrincipal } from '../permissions.js';
+import { TimeApprovalPolicy, TimeEntryApprovalPath, TimeEntryEvidence } from '../types.js';
+import { SupportCaseService } from './support-case-service.js';
+/** Thrown when an approval-path or tenant gate refuses the acting principal. */
+export declare class TimeEntryApprovalDeniedError extends Error {
+    constructor(reason: string);
+}
+/** Options for {@link TimeEntryApprovalService.create}. */
+export interface TimeEntryApprovalServiceOptions extends SmrtObjectOptions {
+    /** Share an existing case facade (otherwise one is created internally). */
+    caseService?: SupportCaseService;
+}
+/**
+ * The plan terms governing one entry's approval and pricing, resolved from
+ * the case's frozen `planSnapshot` first, then the live plan row, else
+ * zero-rate defaults (operator approval, nothing charged).
+ */
+export interface ResolvedPlanTerms {
+    policy: TimeApprovalPolicy;
+    currency: string;
+    includedMinutes: number;
+    overageHourlyRate: number;
+    onCallHourlyRate: number;
+    planId: string | null;
+    planKey: string;
+}
+/** Input for {@link TimeEntryApprovalService.approve}. */
+export interface ApproveTimeEntryInput {
+    /** Acting principal; optional only for the `automatic` path. */
+    principal?: SupportPrincipal;
+    note?: string;
+    /** Approval instant (defaults to now); also the derivation timestamp. */
+    at?: Date;
+}
+/** Result of {@link TimeEntryApprovalService.approve}. */
+export interface ApproveTimeEntryResult {
+    entry: ServiceTimeEntry;
+    charge: SupportCharge;
+    compensation: SupportCompensation;
+    path: TimeEntryApprovalPath;
+}
+/** Input for {@link TimeEntryApprovalService.reject}. */
+export interface RejectTimeEntryInput {
+    principal: SupportPrincipal;
+    reason: string;
+}
+/** Input for {@link TimeEntryApprovalService.correct}. */
+export interface CorrectTimeEntryInput {
+    principal: SupportPrincipal;
+    patch: Partial<{
+        durationSeconds: number;
+        startedAt: Date;
+        endedAt: Date;
+        description: string;
+        evidence: TimeEntryEvidence[];
+    }>;
+    note?: string;
+}
+/** Result of {@link TimeEntryApprovalService.correct}. */
+export interface CorrectTimeEntryResult {
+    /** The superseded entry, now `corrected` with its snapshot intact. */
+    original: ServiceTimeEntry;
+    /** The new `draft` entry carrying the patch (flows submit → approve). */
+    correction: ServiceTimeEntry;
+}
+/** Charge math derived from the plan terms before any row is written. */
+interface ChargeDerivation {
+    billableSeconds: number;
+    includedSecondsBefore: number;
+    includedSecondsApplied: number;
+    hourlyRate: number;
+    rateSource: 'overage' | 'on_call' | 'none';
+    amount: number;
+}
+/**
+ * The approval gate. Construct with {@link TimeEntryApprovalService.create}.
+ */
+export declare class TimeEntryApprovalService {
+    readonly entries: ServiceTimeEntryCollection;
+    readonly charges: SupportChargeCollection;
+    readonly compensations: SupportCompensationCollection;
+    readonly compensationPlans: SupportCompensationPlanCollection;
+    readonly caseService: SupportCaseService;
+    private readonly approvalMutex;
+    protected constructor(collections: {
+        entries: ServiceTimeEntryCollection;
+        charges: SupportChargeCollection;
+        compensations: SupportCompensationCollection;
+        compensationPlans: SupportCompensationPlanCollection;
+        caseService: SupportCaseService;
+    });
+    static create(options: TimeEntryApprovalServiceOptions): Promise<TimeEntryApprovalService>;
+    /** Load an entry or throw a descriptive error. */
+    getEntry(entryRef: ServiceTimeEntry | string): Promise<ServiceTimeEntry>;
+    /**
+     * Resolve the plan terms governing an entry: the case's frozen
+     * `planSnapshot` wins field-by-field (history never rewritten by plan
+     * edits), the live plan row fills gaps, and with no case or plan at all the
+     * terms fall back to zero rates under operator approval.
+     */
+    resolvePlanTerms(entry: ServiceTimeEntry, supportCase?: SupportCase | null): Promise<ResolvedPlanTerms>;
+    /**
+     * Approve a `submitted` entry: gate the acting principal by the plan's
+     * approval policy, freeze the entry, and derive its charge and compensation
+     * snapshots. Throws {@link TimeEntryApprovalDeniedError} when the gate
+     * refuses.
+     */
+    approve(entryRef: ServiceTimeEntry | string, input?: ApproveTimeEntryInput): Promise<ApproveTimeEntryResult>;
+    private approveExclusive;
+    /**
+     * Reject a `submitted` entry with a reason (requires the
+     * `support.approve-time-entry` split).
+     */
+    reject(entryRef: ServiceTimeEntry | string, input: RejectTimeEntryInput): Promise<ServiceTimeEntry>;
+    /**
+     * Correct an `approved` entry (requires the `support.approve-time-entry`
+     * split): a NEW `draft` entry copies the original's context, participant,
+     * and source with the patch applied and links back via `correctionOfId`;
+     * the original flips to `corrected` with its frozen fields and snapshots
+     * untouched, and its charge/compensation rows are marked `corrected`. The
+     * correction then flows submit → approve normally, deriving fresh
+     * snapshots.
+     */
+    correct(entryRef: ServiceTimeEntry | string, input: CorrectTimeEntryInput): Promise<CorrectTimeEntryResult>;
+    /**
+     * Determine the approval path for an entry under a policy, or throw
+     * {@link TimeEntryApprovalDeniedError} when the acting principal does not
+     * satisfy it.
+     */
+    protected determinePath(entry: ServiceTimeEntry, policy: TimeApprovalPolicy, chargeAmount: number, principal: SupportPrincipal | undefined, supportCase: SupportCase | null): TimeEntryApprovalPath;
+    /**
+     * Charge math from the Managed Support Plan terms: remaining included time
+     * (per case — period windows are #1925's scope) absorbs first, the
+     * remainder meters at the overage (or on-call) hourly rate.
+     */
+    protected deriveCharge(entry: ServiceTimeEntry, terms: ResolvedPlanTerms): Promise<ChargeDerivation>;
+    /**
+     * Provider earning from the Support Compensation Plan effective at the work
+     * instant (`endedAt`, falling back to the approval instant). No specialist
+     * or no plan resolves to a zero-amount row so the entry still settles.
+     */
+    protected deriveCompensation(entry: ServiceTimeEntry, at: Date): Promise<SupportCompensation>;
+    /**
+     * Idempotent write of the entry's single charge row: an approval retry
+     * after a partial failure refreshes the existing row instead of colliding
+     * on the `time_entry_id` unique key.
+     */
+    protected upsertChargeRow(entry: ServiceTimeEntry, fields: Record<string, unknown>): Promise<SupportCharge>;
+    /** Idempotent write of the entry's single compensation row (see above). */
+    protected upsertCompensationRow(entry: ServiceTimeEntry, fields: Record<string, unknown>): Promise<SupportCompensation>;
+    /** Cross-tenant acts are refused when both sides carry a tenant. */
+    protected assertTenantMatch(entry: ServiceTimeEntry, principal: SupportPrincipal | undefined): void;
+    /** Require the operator permission split for a privileged act. */
+    protected assertOperator(principal: SupportPrincipal | undefined, act: string): void;
+}
+export default TimeEntryApprovalService;
+//# sourceMappingURL=time-entry-approval-service.d.ts.map

package/dist/services/time-entry-approval-service.d.ts.map

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