@fabriktor/fx 0.0.122 → 0.0.124

package/dist/src/core/multi-create.d.ts

@@ -11,6 +11,7 @@ export type MultiCreateStatus = (typeof MultiCreateStatus)[keyof typeof MultiCre
 export type MultiCreateCheckpoint = {
     created_id?: string;
     on_created?: (id: string) => void;
+    on_rejected?: () => void;
     before_request?: () => void;
 };
 export type MultiCreateAttempt = MultiCreateCheckpoint & {
@@ -46,6 +47,7 @@ export declare class MultiCreatePool {
 export type MultiCreateOptions<Input, Result> = {
     run: (input: Input, attempt: MultiCreateAttempt) => Promise<Result>;
     pool?: MultiCreatePool;
+    retry_same_request?: boolean;
     before_request?: () => void;
     on_failed?: (entry: MultiCreateEntry<Input, Result>) => void;
     on_settled?: (outcome: MultiCreateOutcome<Input, Result>) => void;

package/dist/src/core/multi-create.js

@@ -115,10 +115,12 @@ export class MultiCreator {
             return this.completion;
         // Explicit user retry is a new creation attempt when no ID was acknowledged.
         // A known ID always resumes retrieval with the original request key.
+        if (this.opts.retry_same_request && entry.attempted && input !== undefined)
+            throw new Error("A submitted request cannot be edited while retrying.");
         const next = {
             ...entry,
             input: input === undefined ? entry.input : structuredClone(input),
-            idempotency_key: entry.created_id
+            idempotency_key: entry.created_id || (this.opts.retry_same_request && entry.attempted)
                 ? entry.idempotency_key
                 : crypto.randomUUID(),
             status: MultiCreateStatus.Pending,
@@ -159,6 +161,10 @@ export class MultiCreator {
                         current = { ...current, created_id: id };
                         this.replace(current);
                     },
+                    on_rejected: () => {
+                        current = { ...current, attempted: false };
+                        this.replace(current);
+                    },
                 });
                 this.replace({
                     ...current,

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

@@ -51,6 +51,7 @@ export declare function runSearch<T>(opts: RunSearchOptions<T>): Promise<SearchP
 export declare function normalizeSearchPage(value?: number): number;
 export declare function normalizeSearchPerPage(value?: number): number;
 export declare function normalizeSearchQuery(value?: string): string | undefined;
+export declare function emptySearchPage<T>(page?: number, per_page?: number): SearchPage<T>;
 export type SearchResultWithID = {
     readonly id: string;
 };

package/dist/src/core/search.js

@@ -201,7 +201,7 @@ function hasMoreSearchResults(opts) {
     }
     return opts.result_count >= opts.per_page;
 }
-function emptySearchPage(page, per_page) {
+export function emptySearchPage(page = firstSearchPage, per_page = defaultSearchPerPage) {
     return {
         results: [],
         page,

package/dist/src/fx.js

@@ -82,6 +82,7 @@ export class FX {
         });
         this.payrolls = newPayrollsFX({
             payrolls: opts.payrolls,
+            billable: opts.billable,
         });
         this.preferences = newPreferencesFX({
             preferences: opts.preferences,

package/dist/src/index.d.ts

@@ -28,6 +28,7 @@ export * from "./memos/memos.js";
 export * from "./notifications/notifications.js";
 export * from "./payments/payments.js";
 export * from "./payrolls/payrolls.js";
+export * from "./payrolls/workspace.js";
 export * from "./preferences/preferences.js";
 export * from "./privacy/privacy.js";
 export * from "./processes/processes.js";

package/dist/src/index.js

@@ -28,6 +28,7 @@ export * from "./memos/memos.js";
 export * from "./notifications/notifications.js";
 export * from "./payments/payments.js";
 export * from "./payrolls/payrolls.js";
+export * from "./payrolls/workspace.js";
 export * from "./preferences/preferences.js";
 export * from "./privacy/privacy.js";
 export * from "./processes/processes.js";

package/dist/src/payments/payments.d.ts

@@ -21,6 +21,13 @@ type PmtPublicSessionInsertOptions = Parameters<PaymentsOperator["insertOnePmtPu
 type PmtPublicSessionReplaceOptions = Parameters<PaymentsOperator["replaceOnePmtPublicSession"]>[0];
 type CreditLedgerEntryInsertOptions = Parameters<PaymentsOperator["insertOneCreditLedgerEntry"]>[0];
 type CreditLedgerEntryReplaceOptions = Parameters<PaymentsOperator["replaceOneCreditLedgerEntry"]>[0];
+export type EntityPaymentHistoryOptions = {
+    owner_id: string;
+    entity_id: string;
+    type: Payment["type"];
+    recipient_id?: string;
+    signal?: AbortSignal;
+};
 export type CreatePaymentOptions = PaymentInsertOptions;
 export type ReplacePaymentOptions = PaymentReplaceOptions;
 export type SearchPaymentsOptions = OwnerSearchOptions;
@@ -105,6 +112,7 @@ export type PaymentsFXOptions = {
     payments: PaymentsOperator;
 };
 export interface PaymentsFXOperator {
+    entityPaymentHistory(opts: EntityPaymentHistoryOptions): Promise<Payment[]>;
     createPayment(opts: CreatePaymentOptions): Promise<Payment>;
     replacePayment(opts: ReplacePaymentOptions): Promise<Payment>;
     searchPayments(opts: SearchPaymentsOptions): Promise<SearchPaymentsPage>;
@@ -143,6 +151,7 @@ export declare class PaymentsFX implements PaymentsFXOperator {
     private payments;
     private submittedPublicSessionIDs;
     constructor(opts: PaymentsFXOptions);
+    entityPaymentHistory(opts: EntityPaymentHistoryOptions): Promise<Payment[]>;
     createPayment(opts: CreatePaymentOptions): Promise<Payment>;
     replacePayment(opts: ReplacePaymentOptions): Promise<Payment>;
     searchPayments(opts: SearchPaymentsOptions): Promise<SearchPaymentsPage>;

package/dist/src/payments/payments.js

@@ -3,7 +3,7 @@
 // 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 { CreditLedgerSourceAndroidIAP, CreditLedgerSourceAppleIAP, CreditLedgerSourceStripe, ZeroID, } from "@fabriktor/schema";
+import { CreditLedgerSourceAndroidIAP, CreditLedgerSourceAppleIAP, CreditLedgerSourceStripe, ZeroID, PaymentKindMain, } from "@fabriktor/schema";
 import { queryParams } from "@fabriktor/client";
 import { errResolveFailed, errValidation } from "../core/err.js";
 import { requiredOperationID, resolvedID } from "../core/id.js";
@@ -101,6 +101,17 @@ export class PaymentsFX {
         this.payments = opts.payments;
         this.submittedPublicSessionIDs = new Set();
     }
+    async entityPaymentHistory(opts) {
+        if (!resolvedID(opts.owner_id) || !resolvedID(opts.entity_id) || !opts.type.trim()) {
+            throw errValidation({ field: "entity_id", msg: "Payment history requires an owner, entity, and type." });
+        }
+        const response = await this.payments.queryPayments({
+            signal: opts.signal,
+            query: queryParams({ owner_id: opts.owner_id, entity_id: opts.entity_id, type: opts.type, kind: PaymentKindMain, recipient_id: opts.recipient_id }),
+        });
+        // Preserve the backend's chronological order; do not infer settlement from PSP payment balance flags.
+        return response.value ?? [];
+    }
     async createPayment(opts) {
         const out = await this.payments.insertOnePayment(opts);
         const id = requiredOperationID(out, msgCreatedPaymentIDMissing);

package/dist/src/payrolls/payrolls.d.ts

@@ -1,4 +1,5 @@
-import type { PayrollsOperator } from "@fabriktor/client";
+import { PayrollsWorkspace } from "./workspace.js";
+import type { BillableOperator, PayrollsOperator } from "@fabriktor/client";
 import type { Payable, Payroll, PayConfig, HourBank, Adjustment, AdjustmentFolder, AdjustmentRecord, AdjustmentAggregate, EmployeePayConfig, PayrollProgram } from "@fabriktor/schema";
 import { type OwnerSearchOptions, type SearchPage } from "../core/search.js";
 type PayableInsertOptions = Parameters<PayrollsOperator["insertOnePayable"]>[0];
@@ -88,8 +89,10 @@ export type SetEmployeePayConfigArchivedResult = Awaited<ReturnType<PayrollsOper
 export type SetPayrollProgramEnabledResult = Awaited<ReturnType<PayrollsOperator["replaceOnePayrollProgram"]>>;
 export type PayrollsFXOptions = {
     payrolls: PayrollsOperator;
+    billable?: BillableOperator;
 };
 export interface PayrollsFXOperator {
+    readonly workspace: PayrollsWorkspace;
     createPayable(opts: CreatePayableOptions): Promise<Payable>;
     replacePayable(opts: ReplacePayableOptions): Promise<Payable>;
     searchPayables(opts: SearchPayablesOptions): Promise<SearchPayablesPage>;
@@ -127,6 +130,7 @@ export interface PayrollsFXOperator {
     setPayrollProgramEnabled(opts: SetPayrollProgramEnabledOptions): Promise<SetPayrollProgramEnabledResult>;
 }
 export declare class PayrollsFX implements PayrollsFXOperator {
+    readonly workspace: PayrollsWorkspace;
     private payrolls;
     constructor(opts: PayrollsFXOptions);
     createPayable(opts: CreatePayableOptions): Promise<Payable>;

package/dist/src/payrolls/payrolls.js

@@ -3,6 +3,7 @@
 // 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 { PayrollsWorkspace } from "./workspace.js";
 import { errResolveFailed } from "../core/err.js";
 import { requiredOperationID } from "../core/id.js";
 import { runOwnerSearch, } from "../core/search.js";
@@ -37,9 +38,11 @@ const resourcePayrollProgram = "payroll_program";
 const msgCreatedPayrollProgramIDMissing = "Created payroll program response did not contain an ID.";
 const msgPayrollProgramMissing = "Payroll program could not be resolved after the mutation.";
 export class PayrollsFX {
+    workspace;
     payrolls;
     constructor(opts) {
         this.payrolls = opts.payrolls;
+        this.workspace = new PayrollsWorkspace(opts.payrolls, opts.billable);
     }
     async createPayable(opts) {
         const out = await this.payrolls.insertOnePayable(opts);

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

@@ -0,0 +1,210 @@
+import type { BillableOperator, PayrollsOperator, QueryOptions } from "@fabriktor/client";
+import { ColPayrollsPayrolls, ColPayrollsHourBanks, ColPayrollsPayables, ColPayrollsAdjustments, ColPayrollsAdjustmentFolders, ColPayrollsPayConfigs, ColPayrollsEmployeePayConfigs, ColPayrollsAdjustmentRecords, ColPayrollsAdjustmentAggregates, ColPayrollsPayrollPrograms, type Payroll, type HourBank, type Payable, type Adjustment, type AdjustmentFolder, type PayConfig, type EmployeePayConfig, type AdjustmentRecord, type AdjustmentAggregate, type PayrollProgram, type InPayroll, type InAdjustment, type InAdjustmentFolder, type InPayConfig, type InEmployeePayConfig, type InPayrollProgram, type InAdjustmentAggregate, type PLPayrollsGeneratePayrollFromEntities, type InDate, type Period } from "@fabriktor/schema";
+import type { EmploymentActor, EmploymentReadContext } from "../contacts/scope.js";
+import { type SearchOptions, type SearchPage } from "../core/search.js";
+import type { MultiCreateAttempt } from "../core/multi-create.js";
+export declare const PayrollResource: {
+    readonly Payrolls: "payrolls";
+    readonly HourBanks: "hour_banks";
+    readonly Payables: "payables";
+    readonly Adjustments: "adjustments";
+    readonly Folders: "adjustment_folders";
+    readonly PayConfigs: "pay_configs";
+    readonly EmployeeConfigs: "employee_pay_configs";
+    readonly Records: "adjustment_records";
+    readonly Aggregates: "adjustment_aggregates";
+    readonly Programs: "payroll_programs";
+};
+export type PayrollResource = (typeof PayrollResource)[keyof typeof PayrollResource];
+export type PayrollRecordMap = {
+    [ColPayrollsPayrolls]: Payroll;
+    [ColPayrollsHourBanks]: HourBank;
+    [ColPayrollsPayables]: Payable;
+    [ColPayrollsAdjustments]: Adjustment;
+    [ColPayrollsAdjustmentFolders]: AdjustmentFolder;
+    [ColPayrollsPayConfigs]: PayConfig;
+    [ColPayrollsEmployeePayConfigs]: EmployeePayConfig;
+    [ColPayrollsAdjustmentRecords]: AdjustmentRecord;
+    [ColPayrollsAdjustmentAggregates]: AdjustmentAggregate;
+    [ColPayrollsPayrollPrograms]: PayrollProgram;
+};
+export type PayrollRecord = PayrollRecordMap[PayrollResource];
+export type PayrollFilters = {
+    employee_id?: string[];
+    employee_pay_config_id?: string[];
+    pay_config_id?: string[];
+    payroll_id?: string[];
+    hour_bank_id?: string[];
+    folder_id?: string[];
+    period_index?: number[];
+    period_indexes?: number[];
+    currency?: string;
+    timezone?: string;
+    is_archived?: boolean;
+    is_payrolled?: boolean;
+    is_banked?: boolean;
+    is_problematic?: boolean;
+    is_enabled?: boolean;
+    is_employer_contribution?: boolean;
+    type?: string[];
+    name?: string[];
+};
+export declare const payrollPolicies: {
+    payrolls: {
+        create: true;
+        remove: true;
+        report: true;
+        filters: ("timezone" | "currency" | "employee_id" | "employee_pay_config_id" | "hour_bank_id" | "period_indexes" | "is_banked" | "is_problematic")[];
+        employee_read: boolean;
+        searchable: boolean;
+        archive: boolean;
+    };
+    hour_banks: {
+        searchable: false;
+        filters: ("timezone" | "currency" | "employee_id" | "period_indexes" | "is_payrolled")[];
+        employee_read: boolean;
+        create: boolean;
+        archive: boolean;
+        remove: boolean;
+        report: boolean;
+    };
+    payables: {
+        filters: ("period_index" | "currency" | "employee_id" | "payroll_id" | "is_payrolled")[];
+        employee_read: boolean;
+        searchable: boolean;
+        create: boolean;
+        archive: boolean;
+        remove: boolean;
+        report: boolean;
+    };
+    adjustments: {
+        filters: ("is_archived" | "type" | "currency" | "folder_id" | "name" | "is_employer_contribution")[];
+        employee_read: boolean;
+        searchable: boolean;
+        create: boolean;
+        archive: boolean;
+        remove: boolean;
+        report: boolean;
+    };
+    adjustment_folders: {
+        filters: "is_archived"[];
+        employee_read: boolean;
+        searchable: boolean;
+        create: boolean;
+        archive: boolean;
+        remove: boolean;
+        report: boolean;
+    };
+    pay_configs: {
+        filters: ("is_archived" | "type" | "currency" | "name")[];
+        employee_read: boolean;
+        searchable: boolean;
+        create: boolean;
+        archive: boolean;
+        remove: boolean;
+        report: boolean;
+    };
+    employee_pay_configs: {
+        employee_read: true;
+        filters: ("is_archived" | "currency" | "name" | "employee_id" | "pay_config_id")[];
+        searchable: boolean;
+        create: boolean;
+        archive: boolean;
+        remove: boolean;
+        report: boolean;
+    };
+    adjustment_records: {
+        filters: ("period_index" | "currency" | "employee_id" | "payroll_id")[];
+        employee_read: boolean;
+        searchable: boolean;
+        create: boolean;
+        archive: boolean;
+        remove: boolean;
+        report: boolean;
+    };
+    adjustment_aggregates: {
+        employee_read: false;
+        create: true;
+        report: true;
+        filters: ("currency" | "period_indexes")[];
+        searchable: boolean;
+        archive: boolean;
+        remove: boolean;
+    };
+    payroll_programs: {
+        searchable: false;
+        create: true;
+        remove: true;
+        filters: ("timezone" | "currency" | "employee_id" | "employee_pay_config_id" | "is_enabled")[];
+        employee_read: boolean;
+        archive: boolean;
+        report: boolean;
+    };
+};
+export declare const payrollPayTypes: readonly ["per_hour", "fixed"];
+export declare const payrollAdjustmentTypes: readonly ["rate", "per_period", "per_hour"];
+export declare const payrollRecurrenceTypes: readonly ["daily", "weekly", "monthly", "yearly"];
+export declare const payrollPercentageScale = 1000;
+export type PayrollCommand = {
+    resource: typeof PayrollResource.Payrolls;
+    input: InPayroll;
+} | {
+    resource: typeof PayrollResource.HourBanks | typeof PayrollResource.Payables;
+    input: PLPayrollsGeneratePayrollFromEntities;
+} | {
+    resource: typeof PayrollResource.Adjustments;
+    input: InAdjustment;
+} | {
+    resource: typeof PayrollResource.Folders;
+    input: InAdjustmentFolder;
+} | {
+    resource: typeof PayrollResource.PayConfigs;
+    input: InPayConfig;
+} | {
+    resource: typeof PayrollResource.EmployeeConfigs;
+    input: InEmployeePayConfig;
+} | {
+    resource: typeof PayrollResource.Aggregates;
+    input: InAdjustmentAggregate;
+} | {
+    resource: typeof PayrollResource.Programs;
+    input: InPayrollProgram;
+};
+export type PayrollBrowseOptions = SearchOptions & {
+    resource: PayrollResource;
+    context: EmploymentReadContext;
+    employer_ids?: string[];
+    filters?: PayrollFilters;
+};
+export declare class PayrollWorkflowError extends Error {
+    readonly reason: "access" | "reference" | "source" | "invalid" | "changed" | "pending_source";
+    constructor(reason: "access" | "reference" | "source" | "invalid" | "changed" | "pending_source");
+}
+export declare function payrollCanManage(actor: EmploymentActor, record?: PayrollRecord | null): boolean;
+export declare function payrollCanRead(actor: EmploymentActor, resource: PayrollResource): boolean;
+export declare function payrollFilterQuery(resource: PayrollResource, filters?: PayrollFilters): QueryOptions;
+export declare class PayrollsWorkspace {
+    private readonly payrolls;
+    private readonly billable?;
+    private readonly ports;
+    private readonly submitted;
+    private consuming;
+    private readonly sourceRequests;
+    constructor(payrolls: PayrollsOperator, billable?: BillableOperator | undefined);
+    browse(opts: PayrollBrowseOptions): Promise<SearchPage<PayrollRecord>>;
+    find<K extends PayrollResource>(resource: K, id: string, signal?: AbortSignal): Promise<PayrollRecordMap[K]>;
+    periods(owner_id: string, ranges: readonly {
+        start: InDate;
+        end: InDate;
+    }[]): Promise<Period[]>;
+    create(actor: EmploymentActor, command: PayrollCommand, attempt: MultiCreateAttempt): Promise<PayrollRecord>;
+    private createChecked;
+    private owned;
+    private active;
+    private adjustments;
+    private config;
+    private validateCommand;
+    setArchived(actor: EmploymentActor, resource: PayrollResource, record: PayrollRecord, value: boolean): Promise<void>;
+    setEnabled(actor: EmploymentActor, record: PayrollProgram, is_enabled: boolean): Promise<void>;
+    remove(actor: EmploymentActor, resource: PayrollResource, record: PayrollRecord): Promise<void>;
+}

package/dist/src/payrolls/workspace.js

@@ -0,0 +1,522 @@
+import { isHTTPClientErr } from "@fabriktor/client";
+import { ColPayrollsPayrolls, ColPayrollsHourBanks, ColPayrollsPayables, ColPayrollsAdjustments, ColPayrollsAdjustmentFolders, ColPayrollsPayConfigs, ColPayrollsEmployeePayConfigs, ColPayrollsAdjustmentRecords, ColPayrollsAdjustmentAggregates, ColPayrollsPayrollPrograms, UserTypeEmployer, UserTypeEmployee, AdjustmentTypeRate, AdjustmentTypePerHour, AdjustmentTypePerPeriod, PayTypeFixed, PayTypePerHour, RecurrenceTypeDaily, RecurrenceTypeWeekly, RecurrenceTypeMonthly, RecurrenceTypeYearly, } from "@fabriktor/schema";
+import { employmentCanRead, employmentCatalogOwnerIDs, employmentOwnsRecord, } from "../contacts/scope.js";
+import { normalizeIDs, requiredOperationID } from "../core/id.js";
+import { runOwnerScopeQuery } from "../core/query.js";
+import { runOwnerScopeSearch, emptySearchPage, } from "../core/search.js";
+export const PayrollResource = {
+    Payrolls: ColPayrollsPayrolls,
+    HourBanks: ColPayrollsHourBanks,
+    Payables: ColPayrollsPayables,
+    Adjustments: ColPayrollsAdjustments,
+    Folders: ColPayrollsAdjustmentFolders,
+    PayConfigs: ColPayrollsPayConfigs,
+    EmployeeConfigs: ColPayrollsEmployeePayConfigs,
+    Records: ColPayrollsAdjustmentRecords,
+    Aggregates: ColPayrollsAdjustmentAggregates,
+    Programs: ColPayrollsPayrollPrograms,
+};
+const generated = {
+    employee_read: true,
+    searchable: true,
+    create: false,
+    archive: false,
+    remove: false,
+    report: false,
+    filters: [],
+};
+const catalog = {
+    ...generated,
+    employee_read: false,
+    create: true,
+    archive: true,
+};
+// The service README and record Rules() define this capability/filter table.
+// A generic CRUD method in the client is not permission to edit an immutable record.
+export const payrollPolicies = {
+    [PayrollResource.Payrolls]: {
+        ...generated,
+        create: true,
+        remove: true,
+        report: true,
+        filters: [
+            "employee_id",
+            "employee_pay_config_id",
+            "hour_bank_id",
+            "is_banked",
+            "is_problematic",
+            "period_indexes",
+            "currency",
+            "timezone",
+        ],
+    },
+    [PayrollResource.HourBanks]: {
+        ...generated,
+        searchable: false,
+        filters: [
+            "employee_id",
+            "is_payrolled",
+            "period_indexes",
+            "currency",
+            "timezone",
+        ],
+    },
+    [PayrollResource.Payables]: {
+        ...generated,
+        filters: [
+            "employee_id",
+            "payroll_id",
+            "is_payrolled",
+            "period_index",
+            "currency",
+        ],
+    },
+    [PayrollResource.Adjustments]: {
+        ...catalog,
+        filters: [
+            "name",
+            "type",
+            "is_employer_contribution",
+            "folder_id",
+            "currency",
+            "is_archived",
+        ],
+    },
+    [PayrollResource.Folders]: { ...catalog, filters: ["is_archived"] },
+    [PayrollResource.PayConfigs]: {
+        ...catalog,
+        filters: ["type", "name", "currency", "is_archived"],
+    },
+    [PayrollResource.EmployeeConfigs]: {
+        ...catalog,
+        employee_read: true,
+        filters: [
+            "employee_id",
+            "pay_config_id",
+            "name",
+            "currency",
+            "is_archived",
+        ],
+    },
+    [PayrollResource.Records]: {
+        ...generated,
+        filters: ["employee_id", "payroll_id", "currency", "period_index"],
+    },
+    [PayrollResource.Aggregates]: {
+        ...generated,
+        employee_read: false,
+        create: true,
+        report: true,
+        filters: ["currency", "period_indexes"],
+    },
+    [PayrollResource.Programs]: {
+        ...generated,
+        searchable: false,
+        create: true,
+        remove: true,
+        filters: [
+            "employee_id",
+            "employee_pay_config_id",
+            "is_enabled",
+            "currency",
+            "timezone",
+        ],
+    },
+};
+export const payrollPayTypes = [PayTypePerHour, PayTypeFixed];
+export const payrollAdjustmentTypes = [
+    AdjustmentTypeRate,
+    AdjustmentTypePerPeriod,
+    AdjustmentTypePerHour,
+];
+export const payrollRecurrenceTypes = [
+    RecurrenceTypeDaily,
+    RecurrenceTypeWeekly,
+    RecurrenceTypeMonthly,
+    RecurrenceTypeYearly,
+];
+// record/config.go pctMoney uses basis.X100000. A displayed percentage is 100 times the fraction.
+export const payrollPercentageScale = 1000;
+// Validation and access denials reject these transactional generation requests.
+// A 409 can also come from idempotency middleware, so it cannot release a request.
+const payrollGenerationRejectionStatuses = [400, 403];
+export class PayrollWorkflowError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Payroll workflow: ${reason}`);
+        this.reason = reason;
+        this.name = "PayrollWorkflowError";
+    }
+}
+function requirePayroll(value, reason) {
+    if (!value)
+        throw new PayrollWorkflowError(reason);
+}
+export function payrollCanManage(actor, record) {
+    return (employmentCanRead(actor) &&
+        actor.active_mode === UserTypeEmployer &&
+        (!record || employmentOwnsRecord(actor, record)));
+}
+export function payrollCanRead(actor, resource) {
+    return (employmentCanRead(actor) &&
+        (actor.active_mode === UserTypeEmployer ||
+            payrollPolicies[resource].employee_read));
+}
+export function payrollFilterQuery(resource, filters = {}) {
+    const allowed = payrollPolicies[resource].filters;
+    return Object.fromEntries(Object.entries(filters).filter(([key, value]) => allowed.includes(key) && value !== undefined));
+}
+export class PayrollsWorkspace {
+    payrolls;
+    billable;
+    ports;
+    // Only holds in-flight/ambiguous requests. Successful POSTs are checkpointed then removed.
+    submitted = new Map();
+    consuming = Promise.resolve();
+    sourceRequests = new Map();
+    constructor(payrolls, billable) {
+        this.payrolls = payrolls;
+        this.billable = billable;
+        this.ports = {
+            [PayrollResource.Payrolls]: {
+                query: (o) => payrolls.queryPayrolls(o),
+                search: (o) => payrolls.searchManyPayrolls(o),
+                find: (o) => payrolls.findOnePayroll(o),
+            },
+            [PayrollResource.HourBanks]: {
+                query: (o) => payrolls.queryHourBanks(o),
+                search: (o) => payrolls.searchManyHourBanks(o),
+                find: (o) => payrolls.findOneHourBank(o),
+            },
+            [PayrollResource.Payables]: {
+                query: (o) => payrolls.queryPayables(o),
+                search: (o) => payrolls.searchManyPayables(o),
+                find: (o) => payrolls.findOnePayable(o),
+            },
+            [PayrollResource.Adjustments]: {
+                query: (o) => payrolls.queryAdjustments(o),
+                search: (o) => payrolls.searchManyAdjustments(o),
+                find: (o) => payrolls.findOneAdjustment(o),
+            },
+            [PayrollResource.Folders]: {
+                query: (o) => payrolls.queryAdjustmentFolders(o),
+                search: (o) => payrolls.searchManyAdjustmentFolders(o),
+                find: (o) => payrolls.findOneAdjustmentFolder(o),
+            },
+            [PayrollResource.PayConfigs]: {
+                query: (o) => payrolls.queryPayConfigs(o),
+                search: (o) => payrolls.searchManyPayConfigs(o),
+                find: (o) => payrolls.findOnePayConfig(o),
+            },
+            [PayrollResource.EmployeeConfigs]: {
+                query: (o) => payrolls.queryEmployeePayConfigs(o),
+                search: (o) => payrolls.searchManyEmployeePayConfigs(o),
+                find: (o) => payrolls.findOneEmployeePayConfig(o),
+            },
+            [PayrollResource.Records]: {
+                query: (o) => payrolls.queryAdjustmentRecords(o),
+                search: (o) => payrolls.searchManyAdjustmentRecords(o),
+                find: (o) => payrolls.findOneAdjustmentRecord(o),
+            },
+            [PayrollResource.Aggregates]: {
+                query: (o) => payrolls.queryAdjustmentAggregates(o),
+                search: (o) => payrolls.searchManyAdjustmentAggregates(o),
+                find: (o) => payrolls.findOneAdjustmentAggregate(o),
+            },
+            [PayrollResource.Programs]: {
+                query: (o) => payrolls.queryPayrollPrograms(o),
+                search: (o) => payrolls.searchManyPayrollPrograms(o),
+                find: (o) => payrolls.findOnePayrollProgram(o),
+            },
+        };
+    }
+    async browse(opts) {
+        if (!payrollCanRead(opts.context, opts.resource))
+            return emptySearchPage(opts.page, opts.per_page);
+        const owner_ids = employmentCatalogOwnerIDs(opts.context, opts.employer_ids);
+        const query = payrollFilterQuery(opts.resource, opts.filters);
+        if (opts.context.active_mode === UserTypeEmployee)
+            query.employee_id = opts.context.owner_id;
+        const port = this.ports[opts.resource];
+        if (payrollPolicies[opts.resource].searchable) {
+            return runOwnerScopeSearch({
+                ...opts,
+                owner_ids,
+                query,
+                search: port.search,
+            });
+        }
+        requirePayroll(!opts.q?.trim(), "invalid");
+        const results = await runOwnerScopeQuery({
+            owner_ids,
+            query,
+            fetch: port.query,
+            signal: opts.signal,
+        });
+        return {
+            ...emptySearchPage(opts.page, opts.per_page),
+            results,
+            total_count: results.length,
+        };
+    }
+    async find(resource, id, signal) {
+        const value = (await this.ports[resource].find({ id, signal })).value;
+        requirePayroll(value, "reference");
+        return value;
+    }
+    async periods(owner_id, ranges) {
+        requirePayroll(owner_id && this.billable && ranges.length, "invalid");
+        const periods = new Map();
+        for (const range of ranges) {
+            const response = await this.billable.periodsFromDates({
+                employer_id: owner_id,
+                ...range,
+            });
+            const values = response.value?.periods?.periods;
+            requirePayroll(values?.length, "invalid");
+            for (const period of values)
+                periods.set(period.period_index, period);
+        }
+        return [...periods.values()].sort((a, b) => a.period_index - b.period_index);
+    }
+    async create(actor, command, attempt) {
+        if (command.resource !== PayrollResource.HourBanks &&
+            command.resource !== PayrollResource.Payables)
+            return this.createChecked(actor, command, attempt);
+        // Consumption transactions must re-read sources after the previous one settles.
+        // This also prevents two entries in the shared concurrent creator consuming the same hours.
+        const running = this.consuming.then(() => this.createChecked(actor, command, attempt));
+        this.consuming = running.catch(() => undefined);
+        return running;
+    }
+    async createChecked(actor, command, attempt) {
+        requirePayroll(payrollCanManage(actor), "access");
+        const resource = command.resource === PayrollResource.HourBanks ||
+            command.resource === PayrollResource.Payables
+            ? PayrollResource.Payrolls
+            : command.resource;
+        if (attempt.created_id)
+            return this.owned(actor, resource, attempt.created_id, attempt.signal);
+        const fingerprint = JSON.stringify({ owner_id: actor.owner_id, command });
+        const previous = this.submitted.get(attempt.idempotency_key);
+        requirePayroll(!previous || previous === fingerprint, "changed");
+        const sourceKeys = command.resource === PayrollResource.HourBanks ||
+            command.resource === PayrollResource.Payables
+            ? command.input.ids.map((id) => `${actor.owner_id}:${command.resource}:${id}`)
+            : [];
+        for (const key of sourceKeys)
+            requirePayroll(!this.sourceRequests.has(key) ||
+                this.sourceRequests.get(key) === attempt.idempotency_key, "pending_source");
+        if (!previous)
+            await this.validateCommand(actor, command, attempt.signal);
+        attempt.before_request?.();
+        attempt.signal.throwIfAborted();
+        this.submitted.set(attempt.idempotency_key, fingerprint);
+        for (const key of sourceKeys)
+            this.sourceRequests.set(key, attempt.idempotency_key);
+        const p = this.payrolls;
+        const request = {
+            signal: attempt.signal,
+            idempotency_key: attempt.idempotency_key,
+        };
+        const out = await (() => {
+            switch (command.resource) {
+                case PayrollResource.Payrolls:
+                    return p.generatePayroll(command.input, request);
+                case PayrollResource.HourBanks:
+                    return p.generatePayrollFromHourBanks(command.input, request);
+                case PayrollResource.Payables:
+                    return p.generatePayrollFromPayables(command.input, request);
+                case PayrollResource.Aggregates:
+                    return p.aggregateAdjustments(command.input, request);
+                case PayrollResource.Adjustments:
+                    return p.insertOneAdjustment({ in: command.input, ...request });
+                case PayrollResource.Folders:
+                    return p.insertOneAdjustmentFolder({ in: command.input, ...request });
+                case PayrollResource.PayConfigs:
+                    return p.insertOnePayConfig({ in: command.input, ...request });
+                case PayrollResource.EmployeeConfigs:
+                    return p.insertOneEmployeePayConfig({
+                        in: command.input,
+                        ...request,
+                    });
+                case PayrollResource.Programs:
+                    return p.insertOnePayrollProgram({ in: command.input, ...request });
+            }
+        })().catch((error) => {
+            // Generation from configurations, hour banks and payables returns a payroll.
+            // A rejection on retry does not settle an earlier ambiguous submission.
+            if (!previous &&
+                resource === PayrollResource.Payrolls &&
+                isHTTPClientErr(error) &&
+                error.status !== undefined &&
+                payrollGenerationRejectionStatuses.includes(error.status)) {
+                this.submitted.delete(attempt.idempotency_key);
+                for (const key of sourceKeys)
+                    this.sourceRequests.delete(key);
+                attempt.on_rejected?.();
+            }
+            throw error;
+        });
+        const id = requiredOperationID(out, "Generated payroll record response did not contain an ID.");
+        attempt.on_created?.(id);
+        this.submitted.delete(attempt.idempotency_key);
+        for (const key of sourceKeys)
+            this.sourceRequests.delete(key);
+        return this.owned(actor, resource, id, attempt.signal);
+    }
+    async owned(actor, resource, id, signal) {
+        const value = await this.find(resource, id, signal);
+        requirePayroll(payrollCanManage(actor, value), "access");
+        return value;
+    }
+    async active(actor, resource, id, currency, signal) {
+        const value = await this.owned(actor, resource, id, signal);
+        requirePayroll(!("is_archived" in value && value.is_archived) &&
+            (!currency || !("currency" in value) || value.currency === currency), "reference");
+        return value;
+    }
+    async adjustments(actor, ref, currency, signal) {
+        for (const [ids, contribution] of [
+            [ref.deduction_ids, false],
+            [ref.contribution_ids, true],
+        ]) {
+            requirePayroll(normalizeIDs(ids).length === ids.length, "invalid");
+            for (const id of ids) {
+                const value = await this.active(actor, PayrollResource.Adjustments, id, currency, signal);
+                requirePayroll(value.is_employer_contribution === contribution, "reference");
+            }
+        }
+    }
+    async config(actor, id, currency, signal) {
+        const value = await this.active(actor, PayrollResource.EmployeeConfigs, id, currency, signal);
+        const pay = await this.active(actor, PayrollResource.PayConfigs, value.pay_config_id, currency, signal);
+        await this.adjustments(actor, pay, currency, signal);
+        return value;
+    }
+    async validateCommand(actor, command, signal) {
+        const v = command.input;
+        const integerAmounts = [
+            "rate",
+            "unit_amount",
+            "work_normal_rate",
+            "work_overtime_rate",
+            "transport_normal_rate",
+            "transport_overtime_rate",
+            "default_fixed_hours",
+            "work_rate",
+            "transport_rate",
+        ];
+        for (const [key, value] of Object.entries(v))
+            if (integerAmounts.includes(key))
+                requirePayroll(typeof value === "number" &&
+                    Number.isSafeInteger(value) &&
+                    value >= 0, "invalid");
+        if ("sub_contributions" in v)
+            requirePayroll(v.sub_contributions.every((rule) => Number.isSafeInteger(rule.rate) && rule.rate >= 0), "invalid");
+        if ("periods" in v)
+            requirePayroll(v.periods.length &&
+                v.periods.every((period) => Number.isSafeInteger(period.period) &&
+                    period.period > 0 &&
+                    Number.isSafeInteger(period.period_year) &&
+                    period.period_year > 0), "invalid");
+        if ("currency" in v)
+            requirePayroll(v.currency.trim(), "invalid");
+        switch (command.resource) {
+            case PayrollResource.Payrolls:
+                requirePayroll(command.input.periods.length &&
+                    command.input.timezone === command.input.tz, "invalid");
+                await this.config(actor, command.input.employee_pay_config_id, command.input.currency, signal);
+                break;
+            case PayrollResource.Programs: {
+                const input = command.input;
+                const config = await this.config(actor, input.employee_pay_config_id, input.currency, signal);
+                requirePayroll(input.employee_id === config.employee_id &&
+                    input.timezone === input.next_payroll_date.tz &&
+                    Number.isSafeInteger(input.recurrence_rate) &&
+                    input.recurrence_rate > 0 &&
+                    payrollRecurrenceTypes.some((x) => x === input.recurrence_type), "invalid");
+                break;
+            }
+            case PayrollResource.HourBanks:
+            case PayrollResource.Payables: {
+                const input = command.input;
+                requirePayroll(input.employee_id &&
+                    input.ids.length &&
+                    normalizeIDs(input.ids).length === input.ids.length &&
+                    Number.isSafeInteger(input.period_index), "invalid");
+                for (const id of input.ids) {
+                    const source = await this.owned(actor, command.resource, id, signal);
+                    requirePayroll(!source.is_payrolled &&
+                        source.employee_id === input.employee_id &&
+                        source.currency === input.currency, "source");
+                }
+                await this.adjustments(actor, input.AdjustmentRef, input.currency, signal);
+                break;
+            }
+            case PayrollResource.EmployeeConfigs:
+                requirePayroll(command.input.employee_id && command.input.name.trim(), "invalid");
+                await this.active(actor, PayrollResource.PayConfigs, command.input.pay_config_id, command.input.currency, signal);
+                break;
+            case PayrollResource.PayConfigs:
+                requirePayroll(command.input.name.trim() &&
+                    payrollPayTypes.some((x) => x === command.input.type) &&
+                    Number.isSafeInteger(command.input.default_fixed_hours), "invalid");
+                await this.adjustments(actor, command.input, command.input.currency, signal);
+                break;
+            case PayrollResource.Adjustments: {
+                const input = command.input;
+                requirePayroll(input.name.trim() &&
+                    payrollAdjustmentTypes.some((x) => x === input.type), "invalid");
+                requirePayroll(!input.sub_contributions.length ||
+                    (!input.is_employer_contribution &&
+                        !input.is_accrued &&
+                        input.sub_contributions.every((x) => x.type === AdjustmentTypeRate && !x.is_accrued)), "invalid");
+                await this.active(actor, PayrollResource.Folders, input.folder_id, undefined, signal);
+                break;
+            }
+            case PayrollResource.Folders:
+                requirePayroll(command.input.folder_name.trim(), "invalid");
+                break;
+            case PayrollResource.Aggregates:
+                requirePayroll(command.input.employee_ids.length && command.input.periods.length, "invalid");
+                break;
+        }
+    }
+    async setArchived(actor, resource, record, value) {
+        requirePayroll(payrollCanManage(actor, record) && payrollPolicies[resource].archive, "access");
+        await this.owned(actor, resource, record.id);
+        const opts = { id: record.id, in: { is_archived: value } };
+        switch (resource) {
+            case PayrollResource.Adjustments:
+                await this.payrolls.replaceOneAdjustment(opts);
+                break;
+            case PayrollResource.Folders:
+                await this.payrolls.replaceOneAdjustmentFolder(opts);
+                break;
+            case PayrollResource.PayConfigs:
+                await this.payrolls.replaceOnePayConfig(opts);
+                break;
+            case PayrollResource.EmployeeConfigs:
+                await this.payrolls.replaceOneEmployeePayConfig(opts);
+                break;
+        }
+    }
+    async setEnabled(actor, record, is_enabled) {
+        const latest = await this.owned(actor, PayrollResource.Programs, record.id);
+        if (is_enabled)
+            await this.config(actor, latest.employee_pay_config_id, latest.currency);
+        await this.payrolls.replaceOnePayrollProgram({
+            id: record.id,
+            in: { is_enabled },
+        });
+    }
+    async remove(actor, resource, record) {
+        requirePayroll(payrollCanManage(actor, record) && payrollPolicies[resource].remove, "access");
+        await this.owned(actor, resource, record.id);
+        if (resource === PayrollResource.Payrolls)
+            await this.payrolls.deleteOnePayroll({ id: record.id });
+        else if (resource === PayrollResource.Programs)
+            await this.payrolls.deleteOnePayrollProgram({ id: record.id });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.122",
+  "version": "0.0.124",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.90",
+    "@fabriktor/client": "0.0.91",
     "@fabriktor/fx": "0.0.94",
     "@fabriktor/schema": "0.0.65"
   }