@fabriktor/fx 0.0.114 → 0.0.116

package/dist/src/billable/billable.d.ts

@@ -1,6 +1,7 @@
 import { type BillableOperator } from "@fabriktor/client";
 import { type Bill, BillableFolder, Charge, Equipment, Item, LaborRate, MeterReading, Quantifier, Tax, TmpBillNumber, VendorInvoice, Warehouse } from "@fabriktor/schema";
-import type { ContactsFXOperator, EmploymentOwnerScope } from "../contacts/contacts.js";
+import type { ContactsFXOperator, EmploymentOwnerScopeOptions } from "../contacts/contacts.js";
+import { type EmploymentReadContext } from "../contacts/scope.js";
 import type { MultiCreateCheckpoint } from "../core/multi-create.js";
 import { type OwnerSearchOptions, type SearchOptions, type SearchPage, type SearchQuery } from "../core/search.js";
 type GenerateBillPayload = Parameters<BillableOperator["generateBill"]>[0];
@@ -98,16 +99,8 @@ export type BillableFXOptions = {
     billable: BillableOperator;
     contacts_fx: ContactsFXOperator;
 };
-export type LoadBillableReadContextOptions = {
-    owner_id: string;
-    uid: string;
-    active_mode: string;
-};
-export type BillableReadContext = {
-    owner_id: string;
-    active_mode: string;
-    employment: EmploymentOwnerScope;
-};
+export type LoadBillableReadContextOptions = EmploymentOwnerScopeOptions;
+export type BillableReadContext = EmploymentReadContext;
 export declare const BillableReadResource: {
     readonly Bill: "bill";
     readonly BillableFolder: "billable_folder";

package/dist/src/billable/billable.js

@@ -5,6 +5,8 @@
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 import { mergeQueryOptions, queryNestedParam, queryParams, } from "@fabriktor/client";
 import { BillTypeDynamic, BillTypeFixed, UserTypeEmployee, UserTypeEmployer, } from "@fabriktor/schema";
+import { employmentActivityOwnerIDs, employmentCatalogOwnerIDs as catalogOwnerIDs, employmentEmployerIDs, employmentManagesRecord, employmentOwnsRecord, loadEmploymentReadContext, } from "../contacts/scope.js";
+import { restrictOwnerIDs } from "../core/scope.js";
 import { isZeroDateTime } from "../core/date.js";
 import { errRequired, errResolveFailed, errValidation } from "../core/err.js";
 import { requiredOperationID, resolvedID } from "../core/id.js";
@@ -109,23 +111,7 @@ export class BillableFX {
         this.contacts_fx = opts.contacts_fx;
     }
     async loadReadContext(opts) {
-        const owner_id = opts.owner_id.trim();
-        if (owner_id === "") {
-            throw errRequired({
-                field: "owner_id",
-                msg: msgOwnerIDRequired,
-            });
-        }
-        const employment = await this.contacts_fx.employmentOwnerScope({
-            owner_id,
-            uid: opts.uid,
-            active_mode: opts.active_mode,
-        });
-        return {
-            owner_id,
-            active_mode: opts.active_mode,
-            employment,
-        };
+        return await loadEmploymentReadContext(this.contacts_fx, opts);
     }
     async searchBills(opts) {
         return await runOwnerSearch({
@@ -175,12 +161,12 @@ export class BillableFX {
         });
     }
     async searchReadableCharges(opts) {
-        const employer_ids = activityEmployerScopeIDs(opts);
+        const employer_ids = employmentEmployerIDs(opts.context, opts.employer_scope_ids);
         return await this.searchReadable({
             ...opts,
             // owner_id identifies the creator; employer_id identifies their employer.
             // An explicitly empty authorized employer set must not become All.
-            allowed_owner_ids: employer_ids?.size === 0 ? [] : activityOwnerIDs(opts.context),
+            allowed_owner_ids: employer_ids?.length === 0 ? [] : employmentActivityOwnerIDs(opts.context, true),
             query: mergeQueryOptions(opts.query, chargeSearchQuery(opts), employer_ids === undefined ? undefined : queryParams({
                 employer_id: [...employer_ids],
             })),
@@ -284,11 +270,11 @@ export class BillableFX {
         });
     }
     async searchReadableMeterReadings(opts) {
-        const employer_ids = activityEmployerScopeIDs(opts);
+        const employer_ids = employmentEmployerIDs(opts.context, opts.employer_scope_ids);
         return await this.searchReadable({
             ...opts,
             // An explicitly empty authorized scope must stay empty, not become All.
-            allowed_owner_ids: employer_ids?.size === 0 ? [] : activityOwnerIDs(opts.context),
+            allowed_owner_ids: employer_ids?.length === 0 ? [] : employmentActivityOwnerIDs(opts.context, true),
             query: mergeQueryOptions(opts.query, meterReadingSearchQuery(opts), employer_ids === undefined ? undefined : queryParams({
                 employer_id: [...employer_ids],
             })),
@@ -743,28 +729,14 @@ export function billableCanDeleteRecord(context, resource, record) {
     return billableCanWriteRecord(context, resource, record);
 }
 export function billableOwnsRecord(context, record) {
-    return record !== null && record !== undefined && record.owner_id === context.owner_id;
+    return employmentOwnsRecord(context, record);
 }
 export function billableCatalogOwnerIDs(context) {
     return catalogOwnerIDs(context);
 }
 function billableRecordBelongsToActor(context, resource, record) {
-    if (record === null || record === undefined) {
-        return false;
-    }
-    if (record.owner_id === context.owner_id) {
-        return true;
-    }
-    return (context.active_mode === UserTypeEmployer &&
-        (resource === BillableReadResource.Charge ||
-            resource === BillableReadResource.MeterReading) &&
-        record.employer_id === context.owner_id);
-}
-function catalogOwnerIDs(context, employer_scope_ids) {
-    if (context.active_mode === UserTypeEmployee) {
-        return restrictOwnerIDs(context.employment.active_employer_ids, employer_scope_ids);
-    }
-    return uniqueIDs([context.owner_id]);
+    return employmentOwnsRecord(context, record) || ((resource === BillableReadResource.Charge || resource === BillableReadResource.MeterReading) &&
+        employmentManagesRecord(context, record));
 }
 function itemSearchQuery(opts) {
     return mergeQueryOptions(queryParams({
@@ -815,33 +787,6 @@ function meterReadingSearchQuery(opts) {
             : { equipment_id: resolvedID(opts.equipment_id) }),
     });
 }
-function activityEmployerScopeIDs(opts) {
-    if (opts.context.active_mode === UserTypeEmployer) {
-        return new Set([opts.context.owner_id]);
-    }
-    if (opts.context.active_mode !== UserTypeEmployee ||
-        opts.employer_scope_ids === undefined) {
-        return undefined;
-    }
-    return new Set(restrictOwnerIDs(opts.context.employment.active_employer_ids, opts.employer_scope_ids));
-}
-function activityOwnerIDs(context) {
-    if (context.active_mode === UserTypeEmployer) {
-        return uniqueIDs([context.owner_id, ...context.employment.related_employee_ids]);
-    }
-    return uniqueIDs([context.owner_id]);
-}
-function restrictOwnerIDs(allowed, requested) {
-    const allowed_ids = uniqueIDs(allowed);
-    if (requested === undefined) {
-        return allowed_ids;
-    }
-    const allowed_set = new Set(allowed_ids);
-    return uniqueIDs(requested).filter((id) => allowed_set.has(id));
-}
-function uniqueIDs(ids) {
-    return [...new Set([...ids].map((id) => id.trim()).filter((id) => id !== ""))];
-}
 export function newBillableFX(opts) {
     return new BillableFX(opts);
 }

package/dist/src/contacts/contacts.js

@@ -6,7 +6,8 @@
 import { queryParam, } from "@fabriktor/client";
 import { Friend, Hired, IDKey, Na, OldHire, UserTypeEmployee, UserTypeEmployer, } from "@fabriktor/schema";
 import { errRequired, errResolveFailed, errValidation } from "../core/err.js";
-import { requiredOperationID } from "../core/id.js";
+import { normalizeIDs, requiredOperationID } from "../core/id.js";
+import { mergeRecordsByID } from "../core/scope.js";
 import { runSearch } from "../core/search.js";
 const presenceIntervalMS = 120_000;
 const employmentUserBatchSize = 30;
@@ -245,7 +246,7 @@ export class ContactsFX {
         });
     }
     async usersByIDs(uid, ids) {
-        const values = uniqueIDs(ids);
+        const values = normalizeIDs(ids);
         if (values.length === 0) {
             return [];
         }
@@ -257,13 +258,7 @@ export class ContactsFX {
                 uid,
             }),
         })));
-        const users = new Map();
-        for (const page of pages) {
-            for (const user of page.results) {
-                users.set(user.id, user);
-            }
-        }
-        return [...users.values()];
+        return mergeRecordsByID(pages.map((page) => page.results));
     }
     async findContact(id) {
         const out = await this.contacts.findOneContact({
@@ -290,9 +285,6 @@ export function emptyEmploymentOwnerScope() {
         related_employee_ids: [],
     };
 }
-function uniqueIDs(ids) {
-    return [...new Set([...ids].map((id) => id.trim()).filter((id) => id !== ""))];
-}
 function chunks(values, size) {
     const out = [];
     for (let i = 0; i < values.length; i += size) {

package/dist/src/contacts/scope.d.ts

@@ -0,0 +1,14 @@
+import { type Owner, type User, type WeekSheet } from "@fabriktor/schema";
+import type { ContactsFXOperator, EmploymentOwnerScope, EmploymentOwnerScopeOptions } from "./contacts.js";
+export type EmploymentActor = Owner & Pick<User, "active_mode">;
+export type EmploymentReadContext = EmploymentActor & {
+    employment: EmploymentOwnerScope;
+};
+export declare function loadEmploymentReadContext(contacts: ContactsFXOperator, opts: EmploymentOwnerScopeOptions): Promise<EmploymentReadContext>;
+export declare function employmentCanRead(context: EmploymentActor): boolean;
+export declare function employmentOwnsRecord(context: EmploymentActor, record: Owner | null | undefined): boolean;
+export declare function employmentManagesRecord(context: EmploymentActor, record: Partial<Pick<WeekSheet, "employer_id">> | null | undefined): boolean;
+export declare function employmentEmployeeIDs(context: EmploymentReadContext): string[];
+export declare function employmentActivityOwnerIDs(context: EmploymentReadContext, include_employer?: boolean): string[];
+export declare function employmentEmployerIDs(context: EmploymentReadContext, requested?: Iterable<string>): string[] | undefined;
+export declare function employmentCatalogOwnerIDs(context: EmploymentReadContext, requested?: Iterable<string>): string[];

package/dist/src/contacts/scope.js

@@ -0,0 +1,49 @@
+import { UserTypeEmployee, UserTypeEmployer, } from "@fabriktor/schema";
+import { resolvedID } from "../core/id.js";
+import { restrictOwnerIDs } from "../core/scope.js";
+export async function loadEmploymentReadContext(contacts, opts) {
+    const owner_id = opts.owner_id.trim();
+    const employment = await contacts.employmentOwnerScope({ ...opts, owner_id });
+    return { owner_id, active_mode: opts.active_mode, employment };
+}
+export function employmentCanRead(context) {
+    return resolvedID(context.owner_id) !== undefined && (context.active_mode === UserTypeEmployee || context.active_mode === UserTypeEmployer);
+}
+export function employmentOwnsRecord(context, record) {
+    return record != null && record.owner_id === context.owner_id;
+}
+export function employmentManagesRecord(context, record) {
+    return record != null && context.active_mode === UserTypeEmployer &&
+        record.employer_id === context.owner_id;
+}
+export function employmentEmployeeIDs(context) {
+    return employmentCanRead(context) && context.active_mode === UserTypeEmployer
+        ? restrictOwnerIDs(context.employment.related_employee_ids)
+        : [];
+}
+export function employmentActivityOwnerIDs(context, include_employer = false) {
+    if (!employmentCanRead(context))
+        return [];
+    return context.active_mode === UserTypeEmployer
+        ? restrictOwnerIDs([
+            ...(include_employer ? [context.owner_id] : []),
+            ...employmentEmployeeIDs(context),
+        ])
+        : restrictOwnerIDs([context.owner_id]);
+}
+export function employmentEmployerIDs(context, requested) {
+    if (!employmentCanRead(context))
+        return [];
+    if (context.active_mode === UserTypeEmployer)
+        return restrictOwnerIDs([context.owner_id], requested);
+    return requested === undefined
+        ? undefined
+        : restrictOwnerIDs(context.employment.active_employer_ids, requested);
+}
+export function employmentCatalogOwnerIDs(context, requested) {
+    if (!employmentCanRead(context))
+        return [];
+    return context.active_mode === UserTypeEmployee
+        ? restrictOwnerIDs(context.employment.active_employer_ids, requested)
+        : restrictOwnerIDs([context.owner_id]);
+}

package/dist/src/core/id.d.ts

@@ -1,3 +1,4 @@
 import { type OperationResult } from "@fabriktor/schema";
 export declare function requiredOperationID(out: OperationResult, msg: string): string;
 export declare function resolvedID(value?: string): string | undefined;
+export declare function normalizeIDs(ids: Iterable<string>): string[];

package/dist/src/core/id.js

@@ -22,3 +22,12 @@ export function resolvedID(value) {
     }
     return id;
 }
+export function normalizeIDs(ids) {
+    const values = new Set();
+    for (const raw of ids) {
+        const id = resolvedID(raw);
+        if (id !== undefined)
+            values.add(id);
+    }
+    return [...values];
+}

package/dist/src/core/query.d.ts

@@ -0,0 +1,9 @@
+import type { FieldOf, OperationResultOf, QueryOptions, QueryOptionsCRUD } from "@fabriktor/client";
+import { type IdentifiedRecord } from "./scope.js";
+export type OwnerScopeQueryOptions<T> = QueryOptionsCRUD & {
+    owner_ids: Iterable<string>;
+    fetch: (opts: QueryOptionsCRUD) => Promise<OperationResultOf<T[]>>;
+};
+export declare function withOwnerQuery(owner_id: string, query?: QueryOptions): QueryOptions;
+export declare function queryRecordParams<T>(field: FieldOf<T>, query: QueryOptions): QueryOptions;
+export declare function runOwnerScopeQuery<T extends IdentifiedRecord>(opts: OwnerScopeQueryOptions<T>): Promise<T[]>;

package/dist/src/core/query.js

@@ -0,0 +1,15 @@
+import { OwnerIDKey } from "@fabriktor/schema";
+import { mapOwnerScope, mergeRecordsByID } from "./scope.js";
+export function withOwnerQuery(owner_id, query) {
+    return { ...query, [OwnerIDKey]: owner_id };
+}
+export function queryRecordParams(field, query) {
+    return Object.fromEntries(Object.entries(query).map(([key, value]) => [`${field}.${key}`, value]));
+}
+export async function runOwnerScopeQuery(opts) {
+    const responses = await mapOwnerScope(opts.owner_ids, (owner_id) => opts.fetch({
+        query: withOwnerQuery(owner_id, opts.query),
+        signal: opts.signal,
+    }), opts.signal);
+    return mergeRecordsByID(responses.map((response) => response.value ?? []));
+}

package/dist/src/core/scope.d.ts

@@ -0,0 +1,5 @@
+import { IDKey, type Common } from "@fabriktor/schema";
+export type IdentifiedRecord = Pick<Common, typeof IDKey>;
+export declare function restrictOwnerIDs(allowed: Iterable<string>, requested?: Iterable<string>): string[];
+export declare function mapOwnerScope<T>(owner_ids: Iterable<string>, fetch: (owner_id: string) => Promise<T>, signal?: AbortSignal): Promise<T[]>;
+export declare function mergeRecordsByID<T extends IdentifiedRecord>(groups: Iterable<Iterable<T>>): T[];

package/dist/src/core/scope.js

@@ -0,0 +1,23 @@
+import { IDKey } from "@fabriktor/schema";
+import { normalizeIDs } from "./id.js";
+export function restrictOwnerIDs(allowed, requested) {
+    const ids = normalizeIDs(allowed);
+    if (requested === undefined)
+        return ids;
+    const allowed_ids = new Set(ids);
+    return normalizeIDs(requested).filter((id) => allowed_ids.has(id));
+}
+export async function mapOwnerScope(owner_ids, fetch, signal) {
+    signal?.throwIfAborted();
+    const results = await Promise.all(normalizeIDs(owner_ids).map(fetch));
+    signal?.throwIfAborted();
+    return results;
+}
+export function mergeRecordsByID(groups) {
+    const values = new Map();
+    for (const group of groups) {
+        for (const value of group)
+            values.set(value[IDKey], value);
+    }
+    return [...values.values()];
+}

package/dist/src/core/search.d.ts

@@ -1,4 +1,6 @@
 import type { OperationResultOf, SearchManyOptionsCRUD, SearchResultOf } from "@fabriktor/client";
+import { type IdentifiedRecord } from "./scope.js";
+export { withOwnerQuery } from "./query.js";
 export type SearchQuery = NonNullable<SearchManyOptionsCRUD["query"]>;
 export type SearchPaginationOptions = {
     page?: number;
@@ -42,14 +44,9 @@ export type SearchPage<T> = {
     done: boolean;
 };
 export declare function collectSearchResults<T>(search: (page: number) => Promise<SearchPage<T>>): Promise<T[]>;
-export declare function withOwnerQuery(owner_id: string, query?: SearchQuery): SearchQuery;
 export declare function runOwnerSearch<T>(opts: RunOwnerSearchOptions<T>): Promise<SearchPage<T>>;
-export declare function runOwnerScopeSearch<T extends {
-    id: string;
-}>(opts: OwnerScopeSearchOptions<T>): Promise<SearchPage<T>>;
-export declare function runOwnerScopeFilteredSearch<T extends {
-    id: string;
-}>(opts: OwnerScopeFilteredSearchOptions<T>): Promise<SearchPage<T>>;
+export declare function runOwnerScopeSearch<T extends IdentifiedRecord>(opts: OwnerScopeSearchOptions<T>): Promise<SearchPage<T>>;
+export declare function runOwnerScopeFilteredSearch<T extends IdentifiedRecord>(opts: OwnerScopeFilteredSearchOptions<T>): Promise<SearchPage<T>>;
 export declare function runSearch<T>(opts: RunSearchOptions<T>): Promise<SearchPage<T>>;
 export declare function normalizeSearchPage(value?: number): number;
 export declare function normalizeSearchPerPage(value?: number): number;

package/dist/src/core/search.js

@@ -3,7 +3,11 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may
 // not use this file except in compliance with the License. You may obtain
 // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
-import { OwnerIDKey, SearchPageKey, SearchPerPageKey, SearchQueryKey, SearchResultResultsKey, } from "@fabriktor/schema";
+import { SearchPageKey, SearchPerPageKey, SearchQueryKey, SearchResultResultsKey, } from "@fabriktor/schema";
+import { normalizeIDs } from "./id.js";
+import { withOwnerQuery } from "./query.js";
+import { mapOwnerScope, mergeRecordsByID } from "./scope.js";
+export { withOwnerQuery } from "./query.js";
 const firstSearchPage = 1;
 const defaultSearchPerPage = 30;
 export async function collectSearchResults(search) {
@@ -21,12 +25,6 @@ export async function collectSearchResults(search) {
         page = out.next_page;
     }
 }
-export function withOwnerQuery(owner_id, query) {
-    return {
-        ...query,
-        [OwnerIDKey]: owner_id,
-    };
-}
 export async function runOwnerSearch(opts) {
     const { owner_id, query, ...searchOpts } = opts;
     return await runSearch({
@@ -35,13 +33,13 @@ export async function runOwnerSearch(opts) {
     });
 }
 export async function runOwnerScopeSearch(opts) {
-    const owner_ids = uniqueOwnerIDs(opts.owner_ids);
+    const owner_ids = normalizeIDs(opts.owner_ids);
     const page = normalizeSearchPage(opts.page);
     const per_page = normalizeSearchPerPage(opts.per_page);
     if (owner_ids.length === 0) {
         return emptySearchPage(page, per_page);
     }
-    const pages = await Promise.all(owner_ids.map((owner_id) => runOwnerSearch({
+    const pages = await mapOwnerScope(owner_ids, (owner_id) => runOwnerSearch({
         owner_id,
         q: opts.q,
         page,
@@ -49,18 +47,13 @@ export async function runOwnerScopeSearch(opts) {
         query: opts.query,
         search: opts.search,
         signal: opts.signal,
-    })));
-    const results = new Map();
-    for (const ownerPage of pages) {
-        for (const result of ownerPage.results) {
-            results.set(result.id, result);
-        }
-    }
+    }), opts.signal);
+    const results = mergeRecordsByID(pages.map((ownerPage) => ownerPage.results));
     const has_more = pages.some((ownerPage) => ownerPage.has_more);
     const total_count = sumDefined(pages.map((ownerPage) => ownerPage.total_count));
     const last_page = maxDefined(pages.map((ownerPage) => ownerPage.last_page));
     return {
-        results: [...results.values()],
+        results,
         page,
         per_page,
         total_count,
@@ -75,7 +68,7 @@ export async function runOwnerScopeSearch(opts) {
 // intentionally heavier than runOwnerScopeSearch and should only be used when
 // the backend model cannot express the requested relationship as a query rule.
 export async function runOwnerScopeFilteredSearch(opts) {
-    const owner_ids = uniqueOwnerIDs(opts.owner_ids);
+    const owner_ids = normalizeIDs(opts.owner_ids);
     const page = normalizeSearchPage(opts.page);
     const per_page = normalizeSearchPerPage(opts.per_page);
     if (owner_ids.length === 0) {
@@ -86,7 +79,7 @@ export async function runOwnerScopeFilteredSearch(opts) {
     let source_page = 1;
     while (done.size < owner_ids.length) {
         const active_owner_ids = owner_ids.filter((owner_id) => !done.has(owner_id));
-        const pages = await Promise.all(active_owner_ids.map(async (owner_id) => ({
+        const pages = await mapOwnerScope(active_owner_ids, async (owner_id) => ({
             owner_id,
             page: await runOwnerSearch({
                 owner_id,
@@ -97,7 +90,7 @@ export async function runOwnerScopeFilteredSearch(opts) {
                 search: opts.search,
                 signal: opts.signal,
             }),
-        })));
+        }), opts.signal);
         for (const owner_page of pages) {
             if (owner_page.page.done) {
                 done.add(owner_page.owner_id);
@@ -208,9 +201,6 @@ function hasMoreSearchResults(opts) {
     }
     return opts.result_count >= opts.per_page;
 }
-function uniqueOwnerIDs(ids) {
-    return [...new Set([...ids].map((id) => id.trim()).filter((id) => id !== ""))];
-}
 function emptySearchPage(page, per_page) {
     return {
         results: [],

package/dist/src/fx.js

@@ -108,6 +108,8 @@ export class FX {
         });
         this.timesheets = newTimesheetsFX({
             timesheets: opts.timesheets,
+            contacts_fx: this.contacts,
+            billable: opts.billable,
         });
         this.users = newUsersFX({
             users: opts.users,

package/dist/src/index.d.ts

@@ -5,14 +5,17 @@ export * from "./chat/chat.js";
 export * from "./chat/optimistic.js";
 export * from "./chat/send-queue.js";
 export * from "./contacts/contacts.js";
+export * from "./contacts/scope.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/id.js";
 export * from "./core/multi-create.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
+export * from "./core/query.js";
 export * from "./core/queue-store.js";
 export * from "./core/queue.js";
+export * from "./core/scope.js";
 export * from "./core/search-controller.js";
 export * from "./core/search.js";
 export * from "./feed/feed.js";
@@ -30,7 +33,9 @@ export * from "./processes/processes.js";
 export * from "./routes/routes.js";
 export * from "./session/session.js";
 export * from "./storage/storage.js";
+export * from "./timesheets/access.js";
 export * from "./timesheets/timesheets.js";
+export * from "./timesheets/workspace.js";
 export * from "./users/email.js";
 export * from "./users/phone.js";
 export * from "./users/username.js";

package/dist/src/index.js

@@ -5,14 +5,17 @@ export * from "./chat/chat.js";
 export * from "./chat/optimistic.js";
 export * from "./chat/send-queue.js";
 export * from "./contacts/contacts.js";
+export * from "./contacts/scope.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/id.js";
 export * from "./core/multi-create.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
+export * from "./core/query.js";
 export * from "./core/queue-store.js";
 export * from "./core/queue.js";
+export * from "./core/scope.js";
 export * from "./core/search-controller.js";
 export * from "./core/search.js";
 export * from "./feed/feed.js";
@@ -30,7 +33,9 @@ export * from "./processes/processes.js";
 export * from "./routes/routes.js";
 export * from "./session/session.js";
 export * from "./storage/storage.js";
+export * from "./timesheets/access.js";
 export * from "./timesheets/timesheets.js";
+export * from "./timesheets/workspace.js";
 export * from "./users/email.js";
 export * from "./users/phone.js";
 export * from "./users/username.js";

package/dist/src/jobs/jobs.js

@@ -7,7 +7,7 @@ import { Cancelled, Completed, Pending, RecurrenceEndTypeAfterDate, RecurrenceEn
 import { queryParams } from "@fabriktor/client";
 import { isZeroDate, normalizeInputDate, zeroInputDate, } from "../core/date.js";
 import { errRequired, errResolveFailed, errValidation, } from "../core/err.js";
-import { requiredOperationID, resolvedID } from "../core/id.js";
+import { normalizeIDs, requiredOperationID, resolvedID } from "../core/id.js";
 import { runPreActionCheck } from "../core/pre-action.js";
 import { runOwnerSearch, runSearch, withOwnerQuery, } from "../core/search.js";
 const msgJobIDRequired = "Job ID is required.";
@@ -664,19 +664,6 @@ function requiredID(v, field, msg) {
     }
     return out;
 }
-function normalizeIDs(ids) {
-    const seen = new Set();
-    const out = [];
-    for (const raw of ids) {
-        const id = resolvedID(raw);
-        if (id === undefined || seen.has(id)) {
-            continue;
-        }
-        seen.add(id);
-        out.push(id);
-    }
-    return out;
-}
 function removedIDs(before, after) {
     const current = new Set(normalizeIDs(after));
     return normalizeIDs(before).filter((id) => !current.has(id));

package/dist/src/timesheets/access.d.ts

@@ -0,0 +1,27 @@
+import { type Summary, type WeekSheet } from "@fabriktor/schema";
+import type { EmploymentOwnerScopeOptions } from "../contacts/contacts.js";
+import { type EmploymentActor, type EmploymentReadContext } from "../contacts/scope.js";
+import { type TimesheetFilters } from "./workspace.js";
+export type LoadTimesheetsReadContextOptions = EmploymentOwnerScopeOptions;
+export type TimesheetsReadContext = EmploymentReadContext;
+export type TimesheetsActor = EmploymentActor;
+export type TimesheetsReadOptions = TimesheetFilters & {
+    context: TimesheetsReadContext;
+};
+export type QueryTimesheetSyncDestinationsOptions = {
+    context: TimesheetsReadContext;
+    source: WeekSheet;
+    signal?: AbortSignal;
+};
+type TimesheetRecord = WeekSheet | Summary;
+export declare function timesheetCanReadResource(context: TimesheetsActor): boolean;
+export declare function timesheetCanCreateWeek(context: TimesheetsActor): boolean;
+export declare function timesheetCanReadRecord(context: TimesheetsActor, record: TimesheetRecord | null | undefined): boolean;
+export declare function timesheetCanWriteRecord(context: TimesheetsActor, record: TimesheetRecord | null | undefined): boolean;
+export declare function timesheetCanDeleteRecord(context: TimesheetsActor, record: TimesheetRecord | null | undefined): boolean;
+export declare function timesheetCanApproveRecord(context: TimesheetsActor, record: WeekSheet | null | undefined): boolean;
+export declare function timesheetCanEditDay(context: TimesheetsActor, record: WeekSheet | null | undefined, week_day: number): boolean;
+export declare function timesheetCanSyncDestination(context: TimesheetsActor, source: WeekSheet, destination: WeekSheet): boolean;
+export declare function timesheetEmployeeScopeIDs(context: TimesheetsReadContext): string[];
+export declare function timesheetReadFilters(opts: TimesheetsReadOptions): TimesheetFilters;
+export {};

package/dist/src/timesheets/access.js

@@ -0,0 +1,48 @@
+import { PunchStatusWorking, UserTypeEmployee, } from "@fabriktor/schema";
+import { employmentActivityOwnerIDs, employmentCanRead, employmentEmployeeIDs, employmentEmployerIDs, employmentManagesRecord, employmentOwnsRecord, } from "../contacts/scope.js";
+import { restrictOwnerIDs } from "../core/scope.js";
+import { timesheetCanApprove, timesheetCanSync, timesheetHasWorkingPunches, timesheetIsMutable, } from "./workspace.js";
+export function timesheetCanReadResource(context) {
+    return employmentCanRead(context);
+}
+export function timesheetCanCreateWeek(context) {
+    return timesheetCanReadResource(context) && context.active_mode === UserTypeEmployee;
+}
+export function timesheetCanReadRecord(context, record) {
+    return timesheetCanReadResource(context) && record != null && (employmentOwnsRecord(context, record) || employmentManagesRecord(context, record));
+}
+export function timesheetCanWriteRecord(context, record) {
+    return record != null && timesheetCanReadRecord(context, record) && (!("sheets" in record) || timesheetIsMutable(record));
+}
+export function timesheetCanDeleteRecord(context, record) {
+    return record != null && timesheetCanWriteRecord(context, record) && (!("sheets" in record) || !timesheetHasWorkingPunches(record));
+}
+export function timesheetCanApproveRecord(context, record) {
+    return record != null && timesheetCanReadResource(context) &&
+        employmentManagesRecord(context, record) && timesheetCanApprove(record);
+}
+export function timesheetCanEditDay(context, record, week_day) {
+    if (record == null || !timesheetCanCreateWeek(context) ||
+        !employmentOwnsRecord(context, record) || !timesheetIsMutable(record))
+        return false;
+    const day = record.sheets.find((value) => value.week_day === week_day);
+    return day !== undefined && day.punches.length > 0 &&
+        day.punches.every((punch) => punch.punch_status !== PunchStatusWorking);
+}
+export function timesheetCanSyncDestination(context, source, destination) {
+    return timesheetCanApproveRecord(context, source) &&
+        timesheetCanWriteRecord(context, destination) && timesheetCanSync(source, destination);
+}
+export function timesheetEmployeeScopeIDs(context) {
+    return employmentEmployeeIDs(context);
+}
+export function timesheetReadFilters(opts) {
+    const { context, ...filters } = opts;
+    if (!timesheetCanReadResource(context))
+        return { ...filters, owner_ids: [] };
+    return {
+        ...filters,
+        owner_ids: restrictOwnerIDs(employmentActivityOwnerIDs(context), opts.owner_ids),
+        employer_ids: employmentEmployerIDs(context, opts.employer_ids),
+    };
+}

package/dist/src/timesheets/timesheets.d.ts

@@ -1,5 +1,8 @@
 import { type Date as SchemaDate, type OperationResult, type Summary, type WeekSheet } from "@fabriktor/schema";
-import type { TimesheetsOperator } from "@fabriktor/client";
+import type { BillableOperator, TimesheetsOperator } from "@fabriktor/client";
+import type { ContactsFXOperator } from "../contacts/contacts.js";
+import { type LoadTimesheetsReadContextOptions, type QueryTimesheetSyncDestinationsOptions, type TimesheetsReadContext, type TimesheetsReadOptions } from "./access.js";
+import { TimesheetsWorkspace } from "./workspace.js";
 type PunchPayload = Parameters<TimesheetsOperator["punch"]>[0];
 type WeekSheetReplaceOptions = Parameters<TimesheetsOperator["replaceOneWeekSheet"]>[0];
 type SummaryReplaceOptions = Parameters<TimesheetsOperator["replaceOneSummary"]>[0];
@@ -7,6 +10,9 @@ export type ReplaceWeekSheetOptions = WeekSheetReplaceOptions;
 export type ReplaceSummaryOptions = SummaryReplaceOptions;
 export type TimesheetsFXOptions = {
     timesheets: TimesheetsOperator;
+    contacts_fx: ContactsFXOperator;
+    billable?: BillableOperator;
+    now?: () => globalThis.Date;
 };
 export type PunchContext = Pick<PunchPayload, "timezone" | "location_id" | "employer_id">;
 export type PunchInOptions = PunchContext & {
@@ -61,6 +67,11 @@ export type ApproveWeekSheetsOptions = {
     week_sheets: WeekSheet[];
 };
 export interface TimesheetsFXOperator {
+    readonly workspace: TimesheetsWorkspace;
+    loadReadContext(opts: LoadTimesheetsReadContextOptions): Promise<TimesheetsReadContext>;
+    queryReadableWeekSheets(opts: TimesheetsReadOptions): Promise<WeekSheet[]>;
+    queryReadableSummaries(opts: TimesheetsReadOptions): Promise<Summary[]>;
+    querySyncDestinations(opts: QueryTimesheetSyncDestinationsOptions): Promise<WeekSheet[]>;
     replaceWeekSheet(opts: ReplaceWeekSheetOptions): Promise<WeekSheet>;
     replaceSummary(opts: ReplaceSummaryOptions): Promise<Summary>;
     punchControls(opts: PunchControlsOptions): PunchControls;
@@ -76,9 +87,15 @@ export interface TimesheetsFXOperator {
     approveWeekSheets(opts: ApproveWeekSheetsOptions): Promise<void>;
 }
 export declare class TimesheetsFX implements TimesheetsFXOperator {
+    readonly workspace: TimesheetsWorkspace;
     private timesheets;
+    private contacts_fx;
     private punch_in_progress;
     constructor(opts: TimesheetsFXOptions);
+    loadReadContext(opts: LoadTimesheetsReadContextOptions): Promise<TimesheetsReadContext>;
+    queryReadableWeekSheets(opts: TimesheetsReadOptions): Promise<WeekSheet[]>;
+    queryReadableSummaries(opts: TimesheetsReadOptions): Promise<Summary[]>;
+    querySyncDestinations(opts: QueryTimesheetSyncDestinationsOptions): Promise<WeekSheet[]>;
     replaceWeekSheet(opts: ReplaceWeekSheetOptions): Promise<WeekSheet>;
     replaceSummary(opts: ReplaceSummaryOptions): Promise<Summary>;
     punchControls(opts: PunchControlsOptions): PunchControls;

package/dist/src/timesheets/timesheets.js

@@ -6,6 +6,11 @@
 import { PunchModeDefault, PunchModeDelete, PunchModeReplace, PunchModeWeekSheet, PunchStatusPending, PunchStatusWorking, PunchTypeIn, PunchTypeOut, PunchTypeRideIn, PunchTypeRideOut, ZeroID, } from "@fabriktor/schema";
 import { zeroDate } from "../core/date.js";
 import { errRequired, errResolveFailed, errValidation, } from "../core/err.js";
+import { normalizeIDs } from "../core/id.js";
+import { loadEmploymentReadContext } from "../contacts/scope.js";
+import { PreActionBlocked } from "../core/pre-action.js";
+import { timesheetCanApproveRecord, timesheetCanSyncDestination, timesheetReadFilters, } from "./access.js";
+import { TimesheetsWorkspace, TimesheetsBlock, timesheetCanApprove, timesheetCanSync, timesheetIsMutable, } from "./workspace.js";
 const allWeekDays = [0, 1, 2, 3, 4, 5, 6];
 const minuteStep = 15;
 const msgPunchInProgress = "A punch action is already in progress.";
@@ -27,11 +32,39 @@ const resourceSummary = "summary";
 const msgWeekSheetMissing = "Week sheet could not be resolved after the mutation.";
 const msgSummaryMissing = "Summary could not be resolved after the mutation.";
 export class TimesheetsFX {
+    workspace;
     timesheets;
+    contacts_fx;
     punch_in_progress;
     constructor(opts) {
         this.timesheets = opts.timesheets;
+        this.contacts_fx = opts.contacts_fx;
         this.punch_in_progress = false;
+        this.workspace = new TimesheetsWorkspace(opts.timesheets, this, opts.billable, opts.now);
+    }
+    async loadReadContext(opts) {
+        return await loadEmploymentReadContext(this.contacts_fx, opts);
+    }
+    async queryReadableWeekSheets(opts) {
+        return await this.workspace.weeks(timesheetReadFilters(opts));
+    }
+    async queryReadableSummaries(opts) {
+        return await this.workspace.summaries(timesheetReadFilters(opts));
+    }
+    async querySyncDestinations(opts) {
+        const source = await this.workspace.week(opts.source.id, opts.signal);
+        if (source.updated_at !== opts.source.updated_at)
+            throw new PreActionBlocked(TimesheetsBlock.Changed);
+        if (!timesheetCanApproveRecord(opts.context, source))
+            throw new PreActionBlocked(TimesheetsBlock.InvalidSync);
+        const weeks = await this.queryReadableWeekSheets({
+            context: opts.context,
+            employer_ids: [source.employer_id],
+            period_indexes: [source.period_index],
+            is_archived: false,
+            signal: opts.signal,
+        });
+        return weeks.filter((week) => timesheetCanSyncDestination(opts.context, source, week));
     }
     async replaceWeekSheet(opts) {
         await this.timesheets.replaceOneWeekSheet(opts);
@@ -43,7 +76,7 @@ export class TimesheetsFX {
     }
     punchControls(opts) {
         validateWeekDay(opts.week_day, "week_day");
-        if (opts.week_sheet?.is_archived) {
+        if (opts.week_sheet && !timesheetIsMutable(opts.week_sheet)) {
             return disabledPunchControls();
         }
         const day = opts.week_sheet?.sheets.find((sheet) => sheet.week_day === opts.week_day);
@@ -207,7 +240,13 @@ export class TimesheetsFX {
             });
         }
         const ids = [];
-        for (const week_sheet of opts.week_sheets) {
+        for (const expected of opts.week_sheets) {
+            // Query cleaners can return partial days. Always authorize the whole fresh record.
+            const week_sheet = await this.findWeekSheet(expected.id);
+            if (week_sheet.updated_at !== expected.updated_at)
+                throw new PreActionBlocked(TimesheetsBlock.Changed);
+            if (!timesheetCanApprove(week_sheet))
+                throw new PreActionBlocked(TimesheetsBlock.Locked);
             const id = requiredID(week_sheet.id, "week_sheets", msgWeekSheetIDRequired);
             if (week_sheet.employer_id !== employer_id) {
                 throw errValidation({
@@ -266,6 +305,12 @@ export class TimesheetsFX {
         return summary;
     }
     async syncSheets(opts) {
+        const source = await this.findWeekSheet(opts.from.id);
+        if (source.updated_at !== opts.from.updated_at)
+            throw new PreActionBlocked(TimesheetsBlock.Changed);
+        if (!timesheetCanApprove(source))
+            throw new PreActionBlocked(TimesheetsBlock.InvalidSync);
+        opts = { ...opts, from: source };
         const from_id = requiredID(opts.from.id, "from", msgWeekSheetIDRequired);
         if (opts.to.length === 0) {
             throw errRequired({
@@ -274,20 +319,19 @@ export class TimesheetsFX {
             });
         }
         const to_ids = [];
-        for (const week_sheet of opts.to) {
+        for (const expected of opts.to) {
+            const week_sheet = await this.findWeekSheet(expected.id);
+            if (week_sheet.updated_at !== expected.updated_at)
+                throw new PreActionBlocked(TimesheetsBlock.Changed);
             const id = requiredID(week_sheet.id, "to", msgWeekSheetIDRequired);
-            if (week_sheet.is_archived) {
-                throw errValidation({
-                    field: "to",
-                    msg: msgWeekSheetArchived,
-                });
-            }
             if (week_sheet.employer_id !== opts.from.employer_id) {
                 throw errValidation({
                     field: "to",
                     msg: msgSyncEmployerMismatch,
                 });
             }
+            if (!timesheetCanSync(opts.from, week_sheet))
+                throw new PreActionBlocked(TimesheetsBlock.InvalidSync);
             to_ids.push(id);
         }
         const input = {
@@ -420,16 +464,3 @@ function requiredText(v, field, msg) {
     }
     return out;
 }
-function normalizeIDs(ids) {
-    const seen = new Set();
-    const out = [];
-    for (const raw of ids) {
-        const id = raw.trim();
-        if (id === "" || id === ZeroID || seen.has(id)) {
-            continue;
-        }
-        seen.add(id);
-        out.push(id);
-    }
-    return out;
-}

package/dist/src/timesheets/workspace.d.ts

@@ -0,0 +1,79 @@
+import { type BillableOperator, type TimesheetsOperator } from "@fabriktor/client";
+import { PunchTypeIn, PunchTypeOut, PunchTypeRideIn, PunchTypeRideOut, type InDate, type Punch, type Summary, type WeekSheet } from "@fabriktor/schema";
+import type { TimesheetsFXOperator } from "./timesheets.js";
+export type TimesheetFilters = {
+    owner_ids?: WeekSheet["owner_id"][];
+    employer_ids?: WeekSheet["employer_id"][];
+    period_indexes?: WeekSheet["period_index"][];
+    location_ids?: Punch["location_id"][];
+    is_archived?: WeekSheet["is_archived"];
+    punch_status?: Punch["punch_status"];
+    signal?: AbortSignal;
+};
+export type PunchStateOptions = {
+    owner_id: string;
+    employer_id: string;
+    timezone: string;
+    date?: InDate;
+};
+export type TimesheetPunchState = {
+    week_sheet?: WeekSheet;
+    punch?: Punch;
+    week_day: number;
+    stale_day: boolean;
+};
+export type TimesheetPunchAction = typeof PunchTypeIn | typeof PunchTypeOut | typeof PunchTypeRideIn | typeof PunchTypeRideOut;
+export type CheckedPunchOptions = PunchStateOptions & {
+    location_id: string;
+    action: TimesheetPunchAction;
+    expected: TimesheetPunchState;
+    total_pause_minutes?: number;
+    total_meal_minutes?: number;
+};
+export type SaveTimesheetDayOptions = PunchStateOptions & {
+    location_id: string;
+    start: InDate;
+    end: InDate;
+    total_pause_minutes: number;
+    total_meal_minutes: number;
+    replace?: WeekSheet;
+};
+export declare const TimesheetsBlock: {
+    readonly Changed: "timesheets_changed";
+    readonly Locked: "timesheets_locked";
+    readonly Active: "timesheets_active";
+    readonly InvalidDay: "timesheets_invalid_day";
+    readonly InvalidSync: "timesheets_invalid_sync";
+    readonly Unconfirmed: "timesheets_unconfirmed";
+};
+export declare function timesheetPunches(sheet: WeekSheet): Punch[];
+export declare function timesheetHasWorkingPunches(sheet: WeekSheet): boolean;
+export declare function timesheetIsMutable(sheet: WeekSheet): boolean;
+export declare function timesheetCanApprove(sheet: WeekSheet): boolean;
+export declare function timesheetCanSync(source: WeekSheet, destination: WeekSheet): boolean;
+export declare function timesheetStateKey(state: TimesheetPunchState): string;
+export declare function timesheetWeekDay(date: InDate): number;
+export declare class TimesheetsWorkspace {
+    private readonly client;
+    private readonly actions;
+    private readonly billable?;
+    private readonly now;
+    constructor(client: TimesheetsOperator, actions: TimesheetsFXOperator, billable?: BillableOperator | undefined, now?: () => Date);
+    weeks(opts: TimesheetFilters): Promise<WeekSheet[]>;
+    summaries(opts: TimesheetFilters): Promise<Summary[]>;
+    week(id: string, signal?: AbortSignal): Promise<WeekSheet>;
+    summary(id: string, signal?: AbortSignal): Promise<Summary>;
+    periods(employer_id: string, start: InDate, end?: InDate): Promise<number[]>;
+    punchState(opts: PunchStateOptions): Promise<TimesheetPunchState>;
+    punch(opts: CheckedPunchOptions): Promise<WeekSheet>;
+    saveDay(opts: SaveTimesheetDayOptions): Promise<WeekSheet>;
+    removeDay(owner_id: string, expected: WeekSheet, date: InDate): Promise<void>;
+    removeWeek(actor_id: string, expected: WeekSheet): Promise<void>;
+    blankWeek(opts: PunchStateOptions & {
+        location_id: string;
+        date: InDate;
+    }): Promise<WeekSheet>;
+    private queryOwners;
+    private checkedWeek;
+    private validateDay;
+}

package/dist/src/timesheets/workspace.js

@@ -0,0 +1,331 @@
+import { mergeQueryOptions, queryNestedParam, queryParams, } from "@fabriktor/client";
+import { PunchStatusApproved, PunchStatusPending, PunchStatusWorking, PunchTypeIn, PunchTypeOut, PunchTypeRideIn, PunchTypeRideOut, } from "@fabriktor/schema";
+import { inDateAtTimestamp, zeroDate } from "../core/date.js";
+import { errRequired } from "../core/err.js";
+import { PreActionBlocked } from "../core/pre-action.js";
+import { queryRecordParams, runOwnerScopeQuery, } from "../core/query.js";
+export const TimesheetsBlock = {
+    Changed: "timesheets_changed",
+    Locked: "timesheets_locked",
+    Active: "timesheets_active",
+    InvalidDay: "timesheets_invalid_day",
+    InvalidSync: "timesheets_invalid_sync",
+    Unconfirmed: "timesheets_unconfirmed",
+};
+function requireState(allowed, reason) {
+    if (!allowed)
+        throw new PreActionBlocked(reason);
+}
+export function timesheetPunches(sheet) {
+    return sheet.sheets.flatMap((day) => day.punches);
+}
+export function timesheetHasWorkingPunches(sheet) {
+    return timesheetPunches(sheet).some((punch) => punch.punch_status === PunchStatusWorking);
+}
+export function timesheetIsMutable(sheet) {
+    return (!sheet.is_archived &&
+        !timesheetPunches(sheet).some((p) => p.punch_status === PunchStatusApproved));
+}
+export function timesheetCanApprove(sheet) {
+    const punches = timesheetPunches(sheet);
+    return (timesheetIsMutable(sheet) &&
+        punches.length > 0 &&
+        punches.every((p) => p.punch_status === PunchStatusPending));
+}
+export function timesheetCanSync(source, destination) {
+    return timesheetCanApprove(source) && timesheetIsMutable(destination) &&
+        !timesheetHasWorkingPunches(destination) &&
+        destination.employer_id === source.employer_id &&
+        destination.id !== source.id &&
+        destination.period_index === source.period_index &&
+        destination.timezone === source.timezone;
+}
+export function timesheetStateKey(state) {
+    return JSON.stringify([
+        state.week_sheet?.id,
+        state.week_sheet?.updated_at,
+        state.week_sheet?.is_archived,
+        state.week_day,
+        state.punch,
+    ]);
+}
+export function timesheetWeekDay(date) {
+    // Calendar arithmetic on explicit date parts; never the device timezone.
+    return new Date(Date.UTC(date.y, date.m - 1, date.d)).getUTCDay();
+}
+function sameDay(a, b) {
+    return a.y === b.y && a.m === b.m && a.d === b.d;
+}
+function wallTime(date) {
+    return Date.UTC(date.y, date.m - 1, date.d, date.h, date.min);
+}
+function schemaDate(date) {
+    // The backend computes UTC from the supplied wall-clock fields and tz.
+    return { ...zeroDate(), ...date };
+}
+export class TimesheetsWorkspace {
+    client;
+    actions;
+    billable;
+    now;
+    constructor(client, actions, billable, now = () => new Date()) {
+        this.client = client;
+        this.actions = actions;
+        this.billable = billable;
+        this.now = now;
+    }
+    async weeks(opts) {
+        return await this.queryOwners(opts, mergeQueryOptions(query(opts), queryParams({ is_archived: opts.is_archived }), queryRecordParams("sheets", mergeQueryOptions(queryNestedParam(["punches", "location_id"], opts.location_ids), queryNestedParam(["punches", "punch_status"], opts.punch_status)))), (queryOpts) => this.client.queryWeekSheets(queryOpts));
+    }
+    async summaries(opts) {
+        return await this.queryOwners(opts, mergeQueryOptions(query(opts), queryNestedParam(["location_records", "location_id"], opts.location_ids)), (queryOpts) => this.client.querySummaries(queryOpts));
+    }
+    async week(id, signal) {
+        const { value } = await this.client.findOneWeekSheet({ id, signal });
+        requireState(!!value, TimesheetsBlock.Changed);
+        return value;
+    }
+    async summary(id, signal) {
+        const { value } = await this.client.findOneSummary({ id, signal });
+        requireState(!!value, TimesheetsBlock.Changed);
+        return value;
+    }
+    async periods(employer_id, start, end = start) {
+        requireState(!!this.billable && !!employer_id, TimesheetsBlock.InvalidDay);
+        const result = await this.billable.periodsFromDates({
+            employer_id,
+            start,
+            end,
+        });
+        requireState(!!result.value?.ints.length, TimesheetsBlock.InvalidDay);
+        return result.value.ints;
+    }
+    async punchState(opts) {
+        requireState(!!opts.owner_id && !!opts.timezone, TimesheetsBlock.InvalidDay);
+        const today = opts.date ?? inDateAtTimestamp(this.now().toISOString(), opts.timezone);
+        const week_day = timesheetWeekDay(today);
+        // Check every open work punch, including other employers/locations/weeks.
+        // A scope selection must never hide an already open shift.
+        const active = await this.weeks({
+            owner_ids: [opts.owner_id],
+            is_archived: false,
+            punch_status: PunchStatusWorking,
+        });
+        const open = active.flatMap((week_sheet) => week_sheet.sheets.flatMap((day) => day.punches
+            .filter((p) => p.punch_status === PunchStatusWorking)
+            .map((punch) => ({ week_sheet, punch, week_day: day.week_day }))));
+        requireState(open.length <= 1, TimesheetsBlock.Active);
+        if (open[0]) {
+            const current = open[0];
+            const date = inDateAtTimestamp(this.now().toISOString(), current.punch.timezone);
+            return {
+                ...current,
+                stale_day: !sameDay(current.punch.punch_in_time, opts.date ?? date),
+            };
+        }
+        if (!opts.employer_id)
+            return { week_day, stale_day: false };
+        const indexes = await this.periods(opts.employer_id, today);
+        const weeks = await this.weeks({
+            owner_ids: [opts.owner_id],
+            employer_ids: [opts.employer_id],
+            period_indexes: indexes,
+        });
+        requireState(weeks.length <= 1, TimesheetsBlock.Changed);
+        const week_sheet = weeks[0];
+        const punch = week_sheet?.sheets
+            .find((day) => day.week_day === week_day)
+            ?.punches.at(-1);
+        return { week_sheet, punch, week_day, stale_day: false };
+    }
+    async punch(opts) {
+        if (opts.date)
+            this.validateDay(opts.date, opts.timezone);
+        const current = await this.punchState(opts);
+        requireState(timesheetStateKey(current) === timesheetStateKey(opts.expected), TimesheetsBlock.Changed);
+        requireState(!current.stale_day, TimesheetsBlock.InvalidDay);
+        requireState(!current.week_sheet || timesheetIsMutable(current.week_sheet), TimesheetsBlock.Locked);
+        const controls = this.actions.punchControls(current);
+        const allowed = {
+            [PunchTypeIn]: controls.can_punch_in,
+            [PunchTypeOut]: controls.can_punch_out,
+            [PunchTypeRideIn]: controls.can_ride_in,
+            [PunchTypeRideOut]: controls.can_ride_out,
+        };
+        requireState(allowed[opts.action], TimesheetsBlock.Changed);
+        if (opts.action !== PunchTypeIn) {
+            requireState(current.punch?.location_id === opts.location_id &&
+                current.punch.employer_id === opts.employer_id &&
+                current.punch.timezone === opts.timezone, TimesheetsBlock.Changed);
+        }
+        if (opts.date && current.punch && opts.action !== PunchTypeIn) {
+            requireState(sameDay(opts.date, current.punch.punch_in_time) &&
+                wallTime(opts.date) >= wallTime(current.punch.punch_in_time), TimesheetsBlock.InvalidDay);
+        }
+        const context = {
+            employer_id: opts.employer_id,
+            location_id: opts.location_id,
+            timezone: opts.timezone,
+            explicit_date: opts.date ? schemaDate(opts.date) : undefined,
+        };
+        const result = opts.action === PunchTypeIn
+            ? await this.actions.punchIn(context)
+            : opts.action === PunchTypeOut
+                ? await this.actions.punchOut({
+                    ...context,
+                    total_pause_minutes: opts.total_pause_minutes ?? 0,
+                    total_meal_minutes: opts.total_meal_minutes ?? 0,
+                })
+                : opts.action === PunchTypeRideIn
+                    ? await this.actions.rideIn(context)
+                    : await this.actions.rideOut(context);
+        requireState(!!result.id, TimesheetsBlock.Unconfirmed);
+        const sheet = await this.week(result.id);
+        const last = sheet.sheets
+            .find((day) => day.week_day === current.week_day)
+            ?.punches.at(-1);
+        requireState(!!last &&
+            last.location_id === opts.location_id &&
+            !sheet.is_archived &&
+            (opts.action === PunchTypeOut
+                ? last.punch_status === PunchStatusPending
+                : last.punch_status === PunchStatusWorking) &&
+            (opts.action !== PunchTypeRideIn ||
+                last.rides.at(-1)?.is_active === true) &&
+            (opts.action !== PunchTypeRideOut ||
+                last.rides.at(-1)?.is_active === false), TimesheetsBlock.Unconfirmed);
+        return sheet;
+    }
+    async saveDay(opts) {
+        this.validateDay(opts.start, opts.timezone);
+        this.validateDay(opts.end, opts.timezone);
+        requireState(sameDay(opts.start, opts.end) &&
+            wallTime(opts.end) > wallTime(opts.start), TimesheetsBlock.InvalidDay);
+        const indexes = await this.periods(opts.employer_id, opts.start);
+        const matches = await this.weeks({
+            owner_ids: [opts.owner_id],
+            employer_ids: [opts.employer_id],
+            period_indexes: indexes,
+        });
+        requireState(matches.length <= 1, TimesheetsBlock.Changed);
+        const sheet = matches[0];
+        const day = sheet?.sheets.find((d) => d.week_day === timesheetWeekDay(opts.start));
+        if (opts.replace) {
+            requireState(sheet?.id === opts.replace.id &&
+                sheet.updated_at === opts.replace.updated_at, TimesheetsBlock.Changed);
+        }
+        else {
+            // A new manual entry must not silently replace an existing day.
+            requireState(!day?.punches.length, TimesheetsBlock.Changed);
+        }
+        requireState(!sheet || timesheetIsMutable(sheet), TimesheetsBlock.Locked);
+        requireState(!day?.punches.some((p) => p.punch_status === PunchStatusWorking), TimesheetsBlock.Active);
+        const open = await this.weeks({
+            owner_ids: [opts.owner_id],
+            is_archived: false,
+            punch_status: PunchStatusWorking,
+        });
+        requireState(open.length === 0, TimesheetsBlock.Active);
+        const result = await this.actions.replaceDay({
+            employer_id: opts.employer_id,
+            location_id: opts.location_id,
+            timezone: opts.timezone,
+            punch_in_date: schemaDate(opts.start),
+            punch_out_date: schemaDate(opts.end),
+            total_pause_minutes: opts.total_pause_minutes,
+            total_meal_minutes: opts.total_meal_minutes,
+        });
+        requireState(!!result.punch_out.id, TimesheetsBlock.Unconfirmed);
+        return this.week(result.punch_out.id);
+    }
+    async removeDay(owner_id, expected, date) {
+        const sheet = await this.checkedWeek(expected);
+        requireState(sheet.owner_id === owner_id, TimesheetsBlock.Locked);
+        const day = sheet.sheets.find((d) => d.week_day === timesheetWeekDay(date));
+        requireState(!!day?.punches.length &&
+            !day.punches.some((p) => p.punch_status === PunchStatusWorking), TimesheetsBlock.Active);
+        const punch = day.punches[0];
+        requireState(sameDay(date, punch.punch_in_time), TimesheetsBlock.InvalidDay);
+        await this.actions.deleteDay({
+            employer_id: sheet.employer_id,
+            location_id: punch.location_id,
+            timezone: punch.timezone,
+            explicit_date: schemaDate(date),
+        });
+    }
+    async removeWeek(actor_id, expected) {
+        const sheet = await this.checkedWeek(expected);
+        requireState(sheet.owner_id === actor_id || sheet.employer_id === actor_id, TimesheetsBlock.Locked);
+        requireState(!timesheetHasWorkingPunches(sheet), TimesheetsBlock.Active);
+        await this.client.deleteOneWeekSheet({ id: sheet.id });
+    }
+    async blankWeek(opts) {
+        this.validateDay(opts.date, opts.timezone);
+        const indexes = await this.periods(opts.employer_id, opts.date);
+        const matches = await this.weeks({
+            owner_ids: [opts.owner_id],
+            employer_ids: [opts.employer_id],
+            period_indexes: indexes,
+        });
+        requireState(matches.length === 0, TimesheetsBlock.Changed);
+        const result = await this.actions.createBlankWeekSheet({
+            ...opts,
+            explicit_date: schemaDate(opts.date),
+        });
+        requireState(!!result.id, TimesheetsBlock.Unconfirmed);
+        return this.week(result.id);
+    }
+    async queryOwners(opts, query, fetch) {
+        if (emptyScope(opts))
+            return [];
+        if (opts.owner_ids === undefined) {
+            throw errRequired({
+                field: "owner_ids",
+                msg: "Owner IDs are required for a timesheet query.",
+            });
+        }
+        return await runOwnerScopeQuery({
+            owner_ids: opts.owner_ids,
+            query,
+            signal: opts.signal,
+            fetch,
+        });
+    }
+    async checkedWeek(expected) {
+        const sheet = await this.week(expected.id);
+        requireState(sheet.updated_at === expected.updated_at, TimesheetsBlock.Changed);
+        requireState(timesheetIsMutable(sheet), TimesheetsBlock.Locked);
+        return sheet;
+    }
+    validateDay(date, timezone) {
+        const now = inDateAtTimestamp(this.now().toISOString(), timezone);
+        const calendar = new Date(Date.UTC(date.y, date.m - 1, date.d));
+        requireState(!!now &&
+            date.tz === timezone &&
+            date.y > 1 &&
+            date.m >= 1 &&
+            date.m <= 12 &&
+            calendar.getUTCDate() === date.d &&
+            Number.isInteger(date.h) &&
+            date.h >= 0 &&
+            date.h < 24 &&
+            Number.isInteger(date.min) &&
+            date.min >= 0 &&
+            date.min < 60 &&
+            wallTime(date) <= wallTime(now), TimesheetsBlock.InvalidDay);
+    }
+}
+function emptyScope(opts) {
+    return [
+        opts.owner_ids,
+        opts.employer_ids,
+        opts.period_indexes,
+        opts.location_ids,
+    ].some((ids) => ids?.length === 0);
+}
+function query(opts) {
+    return queryParams({
+        employer_id: opts.employer_ids,
+        period_index: opts.period_indexes,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.114",
+  "version": "0.0.116",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.86",
+    "@fabriktor/client": "0.0.87",
     "@fabriktor/fx": "0.0.94",
     "@fabriktor/schema": "0.0.63"
   }