@happyvertical/smrt-timesheets 0.56.0 → 0.56.2

package/dist/recipes.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Declared recipes for smrt-timesheets (#3590, #3604): user-facing units of
+ * functionality an app or agent can pick instead of the whole package.
+ * The scanner reads these statics into the `recipes` array of `manifest.json`
+ * and `smrt-knowledge.json`; nothing here runs at that point.
+ *
+ * @packageDocumentation
+ */
+import { SmrtRecipe } from '@happyvertical/smrt-core';
+import { ServiceTimeEntry } from './models/service-time-entry.js';
+/** Time entries: Record who worked how long on what, for approval. */
+export declare class TimeEntriesRecipe extends SmrtRecipe {
+    static id: string;
+    static help: string;
+    static label: string;
+    static summary: string;
+    static synonyms: string[];
+    static section: {
+        id: string;
+        label: string;
+        icon: string;
+        description: string;
+    };
+    static models: (typeof ServiceTimeEntry)[];
+    static nav: {
+        label: string;
+        model: typeof ServiceTimeEntry;
+        icon: string;
+        description: string;
+    }[];
+    static options: {
+        readonly ServiceTimeEntry: {
+            readonly fields: {
+                readonly participantProfileId: {
+                    readonly label: "Person";
+                    readonly order: 1;
+                };
+                readonly description: {
+                    readonly order: 2;
+                    readonly help: "What the time was spent on, in a few words.";
+                };
+                readonly startedAt: {
+                    readonly label: "Started";
+                    readonly order: 3;
+                };
+                readonly endedAt: {
+                    readonly label: "Ended";
+                    readonly order: 4;
+                };
+                readonly durationSeconds: {
+                    readonly label: "Duration (seconds)";
+                    readonly order: 5;
+                    readonly help: "Whole seconds: 3600 is one hour.";
+                };
+                readonly workRefId: {
+                    readonly label: "Work reference";
+                    readonly order: 6;
+                    readonly help: "The job, project or case this time belongs to.";
+                };
+                readonly workRefType: {
+                    readonly visibility: "hidden";
+                };
+                readonly participantKind: {
+                    readonly default: "human";
+                    readonly visibility: "hidden";
+                };
+                readonly agentRef: {
+                    readonly visibility: "hidden";
+                };
+                readonly source: {
+                    readonly default: "manual";
+                    readonly visibility: "hidden";
+                };
+                readonly evidence: {
+                    readonly visibility: "hidden";
+                };
+                readonly status: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly submittedAt: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly submittedByProfileId: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly approvedAt: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly approvedByProfileId: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly approvalPath: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly rejectedAt: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly rejectedByProfileId: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly rejectionReason: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly correctionOfId: {
+                    readonly visibility: "hidden";
+                    readonly locked: true;
+                };
+                readonly metadata: {
+                    readonly visibility: "hidden";
+                };
+            };
+        };
+    };
+}
+//# sourceMappingURL=recipes.d.ts.map

package/dist/recipes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.d.ts","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,sEAAsE;AACtE,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,MAAM,CAAC,EAAE,SAA6B;IACtC,MAAM,CAAC,IAAI,SAA8B;IACzC,MAAM,CAAC,KAAK,SAAkB;IAC9B,MAAM,CAAC,OAAO,SAAuD;IACrE,MAAM,CAAC,QAAQ,WAMb;IACF,MAAM,CAAC,OAAO;;;;;MAKZ;IACF,MAAM,CAAC,MAAM,8BAAsB;IACnC,MAAM,CAAC,GAAG;;;;;QAQR;IACF,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA0CH;CACZ"}

package/dist/rollup.js

@@ -1,2 +1,2 @@
-import { a as confirmedTimecardGuard, c as TimecardAdjustment, d as TimecardReopeningCollection, l as TimecardAdjustmentCollection, o as PeriodTimecard, s as PeriodTimecardCollection, t as PeriodRollupService, u as TimecardReopening } from "./chunks/rollup-CDqzCxI2.js";
+import { a as confirmedTimecardGuard, c as TimecardAdjustment, d as TimecardReopeningCollection, l as TimecardAdjustmentCollection, o as PeriodTimecard, s as PeriodTimecardCollection, t as PeriodRollupService, u as TimecardReopening } from "./chunks/rollup-C8p1PAXX.js";
 export { PeriodRollupService, PeriodTimecard, PeriodTimecardCollection, TimecardAdjustment, TimecardAdjustmentCollection, TimecardReopening, TimecardReopeningCollection, confirmedTimecardGuard };

package/dist/services/action-principal.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The acting principal for the generated service-backed time entry actions
+ * (#4001).
+ *
+ * Identity always comes from the ambient request context, never from the
+ * request body: the tenancy ALS (`withTenant`, the SvelteKit/Express
+ * adapters) first, then the authenticated smrt-users session-permission ALS
+ * (`createSessionHandler()` without `enterTenantContext`). This is the
+ * smrt-fields / smrt-preferences precedent. Authorization goes through
+ * smrt-users' `assertOperationPermission()` against the principal's published
+ * permission snapshot, so ceilings, super-admin and catalog presence behave
+ * exactly as they do for every other guarded operation.
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { type OperationPermissionCollectionInput } from '@happyvertical/smrt-users';
+/** A refused action with a 4xx status the generated transports serialize. */
+export declare class TimesheetActionError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly publicMessage: string;
+    constructor(status: number, code: string, message: string);
+}
+/** Who is acting, resolved from the ambient context. */
+export interface TimesheetActionPrincipal {
+    tenantId: string;
+    userId: string;
+    permissions: ReadonlySet<string>;
+    /** smrt-profiles Profile linked to the user; stamped into audit fields. */
+    profileId: string;
+    /** True when the tenancy ALS already carries this principal. */
+    fromTenancy: boolean;
+}
+/** True when the ambient principal holds `<collection>.<action>`. */
+export declare function principalHolds(collection: OperationPermissionCollectionInput, action: string, options: SmrtClassOptions): Promise<boolean>;
+/**
+ * Authorize `<collection>.<action>` for the ambient principal and resolve the
+ * profile it acts as. Fails closed (403) without an authenticated,
+ * tenant-bound principal, without the permission, or without a linked
+ * profile — an action always records who took it.
+ *
+ * System context never bypasses: trusted server code without a person calls
+ * `ServiceEvidenceService` directly. `allowSuperAdminBypass: false` is for
+ * money and separation-of-duties operations that need an explicit grant.
+ */
+export declare function authorizeTimesheetAction(collection: OperationPermissionCollectionInput, action: string, options: SmrtClassOptions, guard: {
+    allowSuperAdminBypass: boolean;
+}): Promise<TimesheetActionPrincipal>;
+/**
+ * Run `fn` with the tenancy ALS carrying `principal`, so the tenancy
+ * interceptor scopes every read and write. A session-only principal is
+ * entered with the same tenant, user and permissions; nothing is widened.
+ */
+export declare function withActionPrincipal<T>(principal: TimesheetActionPrincipal, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=action-principal.d.ts.map

package/dist/services/action-principal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-principal.d.ts","sourceRoot":"","sources":["../../src/services/action-principal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAGL,KAAK,kCAAkC,EAGxC,MAAM,2BAA2B,CAAC;AAEnC,6EAA6E;AAC7E,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBAEnB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAO1D;AAED,wDAAwD;AACxD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,WAAW,EAAE,OAAO,CAAC;CACtB;AAyDD,qEAAqE;AACrE,wBAAsB,cAAc,CAClC,UAAU,EAAE,kCAAkC,EAC9C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,kCAAkC,EAC9C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE;IAAE,qBAAqB,EAAE,OAAO,CAAA;CAAE,GACxC,OAAO,CAAC,wBAAwB,CAAC,CA0CnC;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,SAAS,EAAE,wBAAwB,EACnC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAUZ"}

package/dist/services/index.d.ts

@@ -1,5 +1,7 @@
+export { TimesheetActionError, type TimesheetActionPrincipal, } from './action-principal.js';
 export * from './dated-labour-commercial-resolver.js';
 export * from './dated-percentage-labour-commercial-resolver.js';
 export * from './labour-valuation-reconciliation.js';
 export * from './service-evidence-service.js';
+export * from './time-entry-actions.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC;AACtD,cAAc,kDAAkD,CAAC;AACjE,cAAc,sCAAsC,CAAC;AACrD,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAC/B,cAAc,uCAAuC,CAAC;AACtD,cAAc,kDAAkD,CAAC;AACjE,cAAc,sCAAsC,CAAC;AACrD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC"}

package/dist/services/time-entry-actions.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Service-backed write actions for `ServiceTimeEntry` (#4001).
+ *
+ * The generated CRUD writes stay closed: these are the only generated write
+ * path, and each delegates to {@link ServiceEvidenceService}, so the status
+ * machine, the submission/approval trail and the charge/compensation
+ * snapshots are set in exactly one place. The thin collection methods in
+ * `models/service-time-entry.ts` call in here.
+ */
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import type { ServiceTimeEntry, ServiceTimeEntryCollection } from '../models/service-time-entry.js';
+import type { ServiceEvidence } from '../types.js';
+import { type ServiceCommercialResolver } from './service-evidence-service.js';
+/** Approval path stamped by the generated `approve` action. */
+export declare const SERVICE_TIME_ENTRY_ACTION_APPROVAL_PATH = "operator";
+/**
+ * What `approve` prices with: a resolver, or a factory the action calls per
+ * request with the collection's options. Use the factory whenever the
+ * resolver writes (e.g. smrt-projects' `SubscriptionServiceCommercialResolver`
+ * records client charges): `options.db` is the request-bound executor, so
+ * those writes share the request's transaction and PostgreSQL RLS state
+ * instead of a connection captured at startup.
+ */
+export type ServiceTimeEntryCommercialResolverSource = ServiceCommercialResolver | ((context: {
+    options: SmrtClassOptions;
+}) => ServiceCommercialResolver | Promise<ServiceCommercialResolver>);
+/**
+ * Install what the generated `approve` action prices with. Pass `null` to
+ * remove it. Without one, `approve` refuses with 409
+ * (`approval_not_configured`) and writes nothing.
+ *
+ * @example
+ * ```ts
+ * setServiceTimeEntryCommercialResolver(({ options }) =>
+ *   SubscriptionServiceCommercialResolver.create(options, provider),
+ * );
+ * ```
+ */
+export declare function setServiceTimeEntryCommercialResolver(resolver: ServiceTimeEntryCommercialResolverSource | null): void;
+/** The source installed by {@link setServiceTimeEntryCommercialResolver}. */
+export declare function getServiceTimeEntryCommercialResolver(): ServiceTimeEntryCommercialResolverSource | null;
+/** Body of the `record` action. Identity and tenant come from the session. */
+export interface RecordServiceTimeActionInput {
+    workRefType: string;
+    workRefId: string;
+    /** Defaults to the acting user's profile; another person needs `approve`. */
+    participantProfileId?: string | null;
+    /** `manual` (default) or `timer`; imports and agents use the service. */
+    source?: 'manual' | 'timer';
+    description?: string;
+    /** ISO 8601 instant. */
+    startedAt?: string | null;
+    /** ISO 8601 instant. */
+    endedAt?: string | null;
+    durationSeconds?: number | null;
+    /** Exact positive decimal text; exclusive with seconds and timestamps. */
+    durationHours?: string;
+    evidence?: ServiceEvidence[];
+    metadata?: Record<string, unknown>;
+}
+/** Body of the `submit` and `approve` actions. */
+export interface ServiceTimeEntryActionTarget {
+    entryId: string;
+}
+/** `record`: create a draft entry through `ServiceEvidenceService.record()`. */
+export declare function recordServiceTimeAction(entries: ServiceTimeEntryCollection, input: unknown): Promise<ServiceTimeEntry>;
+/**
+ * `submit`: `draft | rejected → submitted` through
+ * `ServiceEvidenceService.submit()`, stamping `submittedAt` and the acting
+ * profile. Only the entry's participant may submit it, unless the caller
+ * holds `approve` (a supervisor submitting on someone's behalf).
+ */
+export declare function submitServiceTimeAction(entries: ServiceTimeEntryCollection, input: unknown): Promise<ServiceTimeEntry>;
+/**
+ * `approve`: `submitted → approved` through `ServiceEvidenceService.approve()`,
+ * which stamps `approvedAt`, the acting profile and the approval path, then
+ * writes the immutable charge and compensation snapshots through the
+ * installed {@link setServiceTimeEntryCommercialResolver resolver} (a factory
+ * is called per request with the collection's options). Money:
+ * super-admin bypass does not apply, the grant must be explicit.
+ */
+export declare function approveServiceTimeAction(entries: ServiceTimeEntryCollection, input: unknown): Promise<ServiceTimeEntry>;
+//# sourceMappingURL=time-entry-actions.d.ts.map

package/dist/services/time-entry-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-entry-actions.d.ts","sourceRoot":"","sources":["../../src/services/time-entry-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAKjE,OAAO,KAAK,EACV,gBAAgB,EAChB,0BAA0B,EAC3B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAQnD,OAAO,EACL,KAAK,yBAAyB,EAE/B,MAAM,+BAA+B,CAAC;AAEvC,+DAA+D;AAC/D,eAAO,MAAM,uCAAuC,aAAa,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,MAAM,wCAAwC,GAChD,yBAAyB,GACzB,CAAC,CAAC,OAAO,EAAE;IACT,OAAO,EAAE,gBAAgB,CAAC;CAC3B,KAAK,yBAAyB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC;AAK1E;;;;;;;;;;;GAWG;AACH,wBAAgB,qCAAqC,CACnD,QAAQ,EAAE,wCAAwC,GAAG,IAAI,GACxD,IAAI,CAEN;AAED,6EAA6E;AAC7E,wBAAgB,qCAAqC,IAAI,wCAAwC,GAAG,IAAI,CAEvG;AAED,8EAA8E;AAC9E,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,yEAAyE;IACzE,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,kDAAkD;AAClD,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAgHD,gFAAgF;AAChF,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,0BAA0B,EACnC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC,CAqF3B;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,0BAA0B,EACnC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC,CAuB3B;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,0BAA0B,EACnC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,gBAAgB,CAAC,CAkC3B"}