@happyvertical/smrt-timesheets 0.0.0-stage → 0.53.0

package/dist/models/index.d.ts

@@ -0,0 +1,3 @@
+export { ServiceChargeSnapshot, ServiceChargeSnapshotCollection, ServiceCompensationSnapshot, ServiceCompensationSnapshotCollection, } from './service-snapshots.js';
+export { SERVICE_TIME_ENTRY_FROZEN_FIELDS, ServiceTimeEntry, ServiceTimeEntryCollection, } from './service-time-entry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/models/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/models/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,2BAA2B,EAC3B,qCAAqC,GACtC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC"}

package/dist/models/json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse a JSON value stored as text, returning `fallback` on malformed input.
+ * Stored JSON may predate a schema change, so reads never throw.
+ */
+export declare function parseTimesheetJson<T>(value: string, fallback: T): T;
+//# sourceMappingURL=json.d.ts.map

package/dist/models/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/models/json.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAMnE"}

package/dist/models/service-snapshots.d.ts

@@ -0,0 +1,66 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+/**
+ * Refuse an amount that is not a JavaScript-safe integer number of minor
+ * units. SQLite stores `19.99` in an INTEGER column without complaint and
+ * PostgreSQL rejects it only at the driver, so the model boundary is the one
+ * place both engines (and every writer: collections, `ServiceEvidenceService`,
+ * resolvers) get the same answer. Sign is not constrained here.
+ */
+export declare function assertSnapshotMinorUnits(model: string, amount: unknown): void;
+/**
+ * Immutable client-charge snapshot for one approved time entry. Money is
+ * integer minor units, consistent with smrt-commerce (#2401).
+ */
+export declare class ServiceChargeSnapshot extends SmrtObject {
+    tenantId: string | null;
+    timeEntryId: string;
+    /**
+     * Client charge in **integer minor units** of {@link currency} — `$19.99` is
+     * `1999`. The `= 0` initializer is load-bearing: SMRT maps an integer literal
+     * to INTEGER and a decimal literal to DECIMAL (#2401).
+     *
+     * Copied verbatim from the upstream `ClientCharge.amount`, so the two carry
+     * the same unit by construction; a split would land cents in a major-units
+     * column with no error anywhere.
+     */
+    amount: number;
+    currency: string;
+    pricingVersion: string;
+    strategy: string;
+    rateSnapshot: string;
+    sourceChargeRef: string;
+    createdAt: Date;
+    initialize(): Promise<this>;
+    save(): Promise<this>;
+}
+/**
+ * Immutable provider-compensation snapshot for one approved time entry,
+ * kept separate from the client charge so the margin is `charge - compensation`.
+ */
+export declare class ServiceCompensationSnapshot extends SmrtObject {
+    tenantId: string | null;
+    timeEntryId: string;
+    /**
+     * Provider earning in **integer minor units** of {@link currency} (#2401).
+     *
+     * Converts with {@link ServiceChargeSnapshot.amount}: the delivery margin is
+     * `charge - compensation`, so a mixed pair would make that subtraction
+     * meaningless.
+     */
+    amount: number;
+    currency: string;
+    termsVersion: string;
+    rateSnapshot: string;
+    createdAt: Date;
+    initialize(): Promise<this>;
+    save(): Promise<this>;
+}
+/** Collection over `service_charge_snapshots`. */
+export declare class ServiceChargeSnapshotCollection extends SmrtCollection<ServiceChargeSnapshot> {
+    static readonly _itemClass: typeof ServiceChargeSnapshot;
+}
+/** Collection over `service_compensation_snapshots`. */
+export declare class ServiceCompensationSnapshotCollection extends SmrtCollection<ServiceCompensationSnapshot> {
+    static readonly _itemClass: typeof ServiceCompensationSnapshot;
+}
+//# sourceMappingURL=service-snapshots.d.ts.map

package/dist/models/service-snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-snapshots.d.ts","sourceRoot":"","sources":["../../src/models/service-snapshots.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,cAAc,EACd,UAAU,EAGX,MAAM,0BAA0B,CAAC;AAGlC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAa7E;AAoDD;;;GAGG;AACH,qBAYa,qBAAsB,SAAQ,UAAU;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACT,WAAW,EAAE,MAAM,CAAM;IAC7E;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAK;IACM,QAAQ,EAAE,MAAM,CAAS;IACzB,cAAc,EAAE,MAAM,CAAM;IAC5B,QAAQ,EAAE,MAAM,CAAM;IACtB,YAAY,EAAE,MAAM,CAAQ;IAC5B,eAAe,EAAE,MAAM,CAAM;IACtD,SAAS,EAAE,IAAI,CAAc;IAEd,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAkBrC;AAED;;;GAGG;AACH,qBAYa,2BAA4B,SAAQ,UAAU;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACT,WAAW,EAAE,MAAM,CAAM;IAC7E;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAK;IACM,QAAQ,EAAE,MAAM,CAAS;IACzB,YAAY,EAAE,MAAM,CAAM;IAC1B,YAAY,EAAE,MAAM,CAAQ;IACrD,SAAS,EAAE,IAAI,CAAc;IAEd,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAkBrC;AAED,kDAAkD;AAClD,qBAAa,+BAAgC,SAAQ,cAAc,CAAC,qBAAqB,CAAC;IACxF,MAAM,CAAC,QAAQ,CAAC,UAAU,+BAAyB;CACpD;AACD,wDAAwD;AACxD,qBAAa,qCAAsC,SAAQ,cAAc,CAAC,2BAA2B,CAAC;IACpG,MAAM,CAAC,QAAQ,CAAC,UAAU,qCAA+B;CAC1D"}

package/dist/models/service-time-entry.d.ts

@@ -0,0 +1,66 @@
+import { SmrtCollection, SmrtObject } from '@happyvertical/smrt-core';
+import { type ServiceEvidence, type ServiceParticipantKind, type ServiceTimeEntrySource, type ServiceTimeEntryStatus } from '../types.js';
+/**
+ * Fields that may not change once an entry is approved (or corrected). A
+ * subtype that adds its own work context extends the list through
+ * {@link ServiceTimeEntry.frozenFieldNames}.
+ */
+export declare const SERVICE_TIME_ENTRY_FROZEN_FIELDS: readonly ["tenantId", "workRefType", "workRefId", "participantKind", "participantProfileId", "agentRef", "source", "description", "startedAt", "endedAt", "durationSeconds", "evidence", "correctionOfId"];
+/**
+ * A person or agent worked this long on this thing, and someone approved it.
+ *
+ * The base entry carries a generic work reference (`workRefType` qualified
+ * class name + `workRefId`) and no domain-specific foreign key; a domain adds
+ * its own context by subclassing over the same `service_time_entries` table
+ * (smrt-support's subtype adds `caseId` / `specialistId`). Entries carry no
+ * rate: charge and compensation live on the immutable snapshot models.
+ *
+ * Status moves `draft → submitted → approved | rejected`; an approved entry
+ * never changes, and a correction is a new row whose `correctionOfId` points
+ * at the entry it corrects, which flips to `corrected`.
+ */
+export declare class ServiceTimeEntry extends SmrtObject {
+    tenantId: string | null;
+    workRefType: string | null;
+    workRefId: string | null;
+    participantKind: ServiceParticipantKind;
+    participantProfileId: string | null;
+    agentRef: string;
+    source: ServiceTimeEntrySource;
+    description: string;
+    startedAt: Date | null;
+    endedAt: Date | null;
+    durationSeconds: number;
+    evidence: string;
+    status: ServiceTimeEntryStatus;
+    submittedAt: Date | null;
+    submittedByProfileId: string | null;
+    approvedAt: Date | null;
+    approvedByProfileId: string | null;
+    approvalPath: string;
+    rejectedAt: Date | null;
+    rejectedByProfileId: string | null;
+    rejectionReason: string;
+    correctionOfId: string | null;
+    metadata: string;
+    getEvidence(): ServiceEvidence[];
+    setEvidence(value: ServiceEvidence[]): void;
+    getMetadata(): Record<string, unknown>;
+    setMetadata(value: Record<string, unknown>): void;
+    durationHours(): number;
+    /**
+     * Fields frozen once the entry is approved. Subtypes that add work context
+     * (e.g. a support case) return `[...super.frozenFieldNames(), ...]`.
+     */
+    protected frozenFieldNames(): readonly string[];
+    initialize(): Promise<this>;
+    save(): Promise<this>;
+    private readPrior;
+}
+/** Collection over `service_time_entries`. */
+export declare class ServiceTimeEntryCollection extends SmrtCollection<ServiceTimeEntry> {
+    static readonly _itemClass: typeof ServiceTimeEntry;
+    forWork(workRefType: string, workRefId: string): Promise<ServiceTimeEntry[]>;
+    pendingApproval(): Promise<ServiceTimeEntry[]>;
+}
+//# sourceMappingURL=service-time-entry.d.ts.map

package/dist/models/service-time-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-time-entry.d.ts","sourceRoot":"","sources":["../../src/models/service-time-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,cAAc,EACd,UAAU,EAEX,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AAGrB;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,4MAcnC,CAAC;AAyBX;;;;;;;;;;;;GAYG;AACH,qBASa,gBAAiB,SAAQ,UAAU;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAClC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAChD,eAAe,EAAE,sBAAsB,CAAW;IAE3E,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAClB,QAAQ,EAAE,MAAM,CAAM;IACtB,MAAM,EAAE,sBAAsB,CAAY;IAC1C,WAAW,EAAE,MAAM,CAAM;IAClD,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAC9B,OAAO,EAAE,IAAI,GAAG,IAAI,CAAQ;IAC5B,eAAe,EAAE,MAAM,CAAK;IACH,QAAQ,EAAE,MAAM,CAAQ;IACxB,MAAM,EAAE,sBAAsB,CAAW;IAClE,WAAW,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEhC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC3C,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE/B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAQ;IACjB,YAAY,EAAE,MAAM,CAAM;IACnD,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE/B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAQ;IACjB,eAAe,EAAE,MAAM,CAAM;IACtB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC5C,QAAQ,EAAE,MAAM,CAAQ;IAEjD,WAAW,IAAI,eAAe,EAAE;IAGhC,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,IAAI;IAG3C,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAGtC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAGjD,aAAa,IAAI,MAAM;IAIvB;;;OAGG;IACH,SAAS,CAAC,gBAAgB,IAAI,SAAS,MAAM,EAAE;IAIhC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YA8BtB,SAAS;CA8BxB;AAED,8CAA8C;AAC9C,qBAAa,0BAA2B,SAAQ,cAAc,CAAC,gBAAgB,CAAC;IAC9E,MAAM,CAAC,QAAQ,CAAC,UAAU,0BAAoB;IACxC,OAAO,CACX,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAMxB,eAAe,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAMrD"}

package/dist/services/index.d.ts

@@ -0,0 +1,2 @@
+export * from './service-evidence-service.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}

package/dist/services/service-evidence-service.d.ts

@@ -0,0 +1,67 @@
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { ServiceChargeSnapshotCollection, ServiceCompensationSnapshotCollection } from '../models/service-snapshots.js';
+import type { ServiceTimeEntry } from '../models/service-time-entry.js';
+import { ServiceTimeEntryCollection } from '../models/service-time-entry.js';
+import type { ServiceEvidence, ServiceParticipantKind, ServiceTimeEntrySource } from '../types.js';
+/**
+ * Input for {@link ServiceEvidenceService.record}. The work reference is the
+ * qualified class name and id of whatever the time was spent on.
+ */
+export interface RecordServiceTimeInput {
+    tenantId?: string | null;
+    workRefType?: string | null;
+    workRefId?: string | null;
+    participantKind: ServiceParticipantKind;
+    participantProfileId?: string | null;
+    agentRef?: string;
+    source: ServiceTimeEntrySource;
+    description: string;
+    startedAt?: Date | null;
+    endedAt?: Date | null;
+    durationSeconds?: number;
+    evidence?: ServiceEvidence[];
+    metadata?: Record<string, unknown>;
+}
+export interface CommercialSnapshot {
+    /**
+     * Integer minor units of `currency` — `$19.99` is `1999` (#2401).
+     *
+     * Written straight into `ServiceChargeSnapshot.amount` /
+     * `ServiceCompensationSnapshot.amount`, INTEGER columns whose `save()`
+     * refuses anything but a safe integer on every engine. A fractional
+     * major-unit value (`19.99`) is rejected; a whole one (`150` for $150.00)
+     * is not detectable and is stored 100× too small, so return minor units.
+     */
+    amount: number;
+    currency?: string;
+    version: string;
+    strategy?: string;
+    terms: Record<string, unknown>;
+    sourceRef?: string;
+}
+export interface ServiceCommercialResolver {
+    priceClient(entry: ServiceTimeEntry): Promise<CommercialSnapshot>;
+    compensateProvider(entry: ServiceTimeEntry): Promise<CommercialSnapshot>;
+}
+/**
+ * Records, submits, approves, and corrects time entries. Approval writes one
+ * immutable client-charge and one provider-compensation snapshot per entry;
+ * a correction is a new entry pointing at the approved one, which flips to
+ * `corrected` with its snapshots intact.
+ */
+export declare class ServiceEvidenceService {
+    private readonly entries;
+    private readonly charges;
+    private readonly compensation;
+    private readonly commercial?;
+    constructor(entries: ServiceTimeEntryCollection, charges: ServiceChargeSnapshotCollection, compensation: ServiceCompensationSnapshotCollection, commercial?: ServiceCommercialResolver | undefined);
+    static create(options?: SmrtClassOptions, commercial?: ServiceCommercialResolver): Promise<ServiceEvidenceService>;
+    record(input: RecordServiceTimeInput): Promise<ServiceTimeEntry>;
+    submit(entry: ServiceTimeEntry, profileId?: string): Promise<ServiceTimeEntry>;
+    approve(entry: ServiceTimeEntry, options: {
+        actorProfileId?: string;
+        approvalPath: string;
+    }): Promise<ServiceTimeEntry>;
+    correct(entry: ServiceTimeEntry, input: RecordServiceTimeInput): Promise<ServiceTimeEntry>;
+}
+//# sourceMappingURL=service-evidence-service.d.ts.map

package/dist/services/service-evidence-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-evidence-service.d.ts","sourceRoot":"","sources":["../../src/services/service-evidence-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EACL,+BAA+B,EAC/B,qCAAqC,EACtC,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,sBAAsB,CAAC;IACxC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,sBAAsB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,OAAO,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClE,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC1E;AAED;;;;;GAKG;AACH,qBAAa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAHX,OAAO,EAAE,0BAA0B,EACnC,OAAO,EAAE,+BAA+B,EACxC,YAAY,EAAE,qCAAqC,EACnD,UAAU,CAAC,EAAE,yBAAyB,YAAA;WAG5C,MAAM,CACjB,OAAO,GAAE,gBAAqB,EAC9B,UAAU,CAAC,EAAE,yBAAyB,GACrC,OAAO,CAAC,sBAAsB,CAAC;IAc5B,MAAM,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA4ChE,MAAM,CACV,KAAK,EAAE,gBAAgB,EACvB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,gBAAgB,CAAC;IAStB,OAAO,CACX,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GACzD,OAAO,CAAC,gBAAgB,CAAC;IA6GtB,OAAO,CACX,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,gBAAgB,CAAC;CAkB7B"}