@dakkitor/api-contracts 1.1.154 → 1.5.0

package/dist/trades/trades.contract.js

@@ -1,28 +1,76 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.tradesContract = exports.TradeArraySchema = exports.UpdateTradeSchema = exports.CreateTradeSchema = exports.TradeSchema = void 0;
+exports.tradesContract = exports.TradeArraySchema = exports.UpdateTradeSchema = exports.CreateTradeSchema = exports.TradeSchema = exports.TradeRateBenchmarksSchema = void 0;
 const core_1 = require("@ts-rest/core");
 const zod_1 = require("zod");
 const error_schemas_1 = require("../common/error-schemas");
 const c = (0, core_1.initContract)();
 // --- Schemas ---
+const HourlyRateValueSchema = zod_1.z.coerce.number().positive().multipleOf(0.01);
+const TradeRateBenchmarkResponseFields = {
+    minimumHourlyRate: HourlyRateValueSchema.nullable().describe('Minimum acceptable hourly rate in GBP'),
+    averageHourlyRate: HourlyRateValueSchema.nullable().describe('Average market hourly rate in GBP'),
+    optimalHourlyRate: HourlyRateValueSchema.nullable().describe('Optimal target hourly rate in GBP'),
+};
+const TradeRateBenchmarkInputFields = {
+    minimumHourlyRate: TradeRateBenchmarkResponseFields.minimumHourlyRate.optional(),
+    averageHourlyRate: TradeRateBenchmarkResponseFields.averageHourlyRate.optional(),
+    optimalHourlyRate: TradeRateBenchmarkResponseFields.optimalHourlyRate.optional(),
+};
+function validateBenchmarkOrder(value, ctx) {
+    const { minimumHourlyRate, averageHourlyRate, optimalHourlyRate } = value;
+    if (minimumHourlyRate != null &&
+        averageHourlyRate != null &&
+        minimumHourlyRate > averageHourlyRate) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['averageHourlyRate'],
+            message: 'Average hourly rate must be at least the minimum hourly rate',
+        });
+    }
+    if (averageHourlyRate != null &&
+        optimalHourlyRate != null &&
+        averageHourlyRate > optimalHourlyRate) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['optimalHourlyRate'],
+            message: 'Optimal hourly rate must be at least the average hourly rate',
+        });
+    }
+    if (averageHourlyRate == null &&
+        minimumHourlyRate != null &&
+        optimalHourlyRate != null &&
+        minimumHourlyRate > optimalHourlyRate) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['optimalHourlyRate'],
+            message: 'Optimal hourly rate must be at least the minimum hourly rate',
+        });
+    }
+}
+exports.TradeRateBenchmarksSchema = zod_1.z
+    .object(TradeRateBenchmarkInputFields)
+    .superRefine(validateBenchmarkOrder);
 exports.TradeSchema = zod_1.z
     .object({
     id: zod_1.z.string().uuid().describe('Unique identifier for the trade'),
     name: zod_1.z.string().describe('Name of the trade'),
     description: zod_1.z.string().nullable().describe('Description of the trade'),
+    ...TradeRateBenchmarkResponseFields,
 })
     .openapi({ title: 'Trade' });
 exports.CreateTradeSchema = zod_1.z
     .object({
     name: zod_1.z.string().min(1).max(255).describe('Name of the trade'),
     description: zod_1.z.string().optional().describe('Description of the trade'),
+    ...TradeRateBenchmarkInputFields,
 })
     .openapi({ title: 'CreateTrade' });
 exports.UpdateTradeSchema = zod_1.z
     .object({
     name: zod_1.z.string().min(1).max(255).optional().describe('Name of the trade'),
     description: zod_1.z.string().optional().describe('Description of the trade'),
+    ...TradeRateBenchmarkInputFields,
 })
     .openapi({ title: 'UpdateTrade' });
 exports.TradeArraySchema = zod_1.z

package/dist/trades/trades.contract.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=trades.contract.spec.d.ts.map

package/dist/trades/trades.contract.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trades.contract.spec.d.ts","sourceRoot":"","sources":["../../contracts/trades/trades.contract.spec.ts"],"names":[],"mappings":""}

package/dist/trades/trades.contract.spec.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const trades_contract_1 = require("./trades.contract");
+const VALID_TRADE_ID = '11111111-1111-4111-8111-111111111111';
+const validTradeResponse = {
+    id: VALID_TRADE_ID,
+    name: 'Electrician',
+    description: null,
+    minimumHourlyRate: 29,
+    averageHourlyRate: 30,
+    optimalHourlyRate: 31,
+};
+function expectIssuePath(result, path) {
+    expect(result.success).toBe(false);
+    if (!result.success) {
+        expect(result.error.issues.map((issue) => issue.path.join('.'))).toContain(path);
+    }
+}
+describe('TradeSchema rate benchmarks', () => {
+    it('coerces PostgreSQL numeric strings to JavaScript numbers', () => {
+        const result = trades_contract_1.TradeSchema.safeParse({
+            ...validTradeResponse,
+            minimumHourlyRate: '29.50',
+            averageHourlyRate: '30.75',
+            optimalHourlyRate: '31.25',
+        });
+        expect(result.success).toBe(true);
+        if (result.success) {
+            expect(result.data.minimumHourlyRate).toBe(29.5);
+            expect(result.data.averageHourlyRate).toBe(30.75);
+            expect(result.data.optimalHourlyRate).toBe(31.25);
+        }
+    });
+    it.each([
+        'minimumHourlyRate',
+        'averageHourlyRate',
+        'optimalHourlyRate',
+    ])('requires the %s response field', (field) => {
+        const response = { ...validTradeResponse };
+        delete response[field];
+        expectIssuePath(trades_contract_1.TradeSchema.safeParse(response), field);
+    });
+    it('allows all response benchmark values to be null', () => {
+        expect(trades_contract_1.TradeSchema.safeParse({
+            ...validTradeResponse,
+            minimumHourlyRate: null,
+            averageHourlyRate: null,
+            optimalHourlyRate: null,
+        }).success).toBe(true);
+    });
+});
+describe('trade benchmark input schemas', () => {
+    it('accepts create input with absent benchmarks', () => {
+        expect(trades_contract_1.CreateTradeSchema.safeParse({ name: 'Electrician' }).success).toBe(true);
+    });
+    it('accepts create input with null benchmarks', () => {
+        expect(trades_contract_1.CreateTradeSchema.safeParse({
+            name: 'Electrician',
+            minimumHourlyRate: null,
+            averageHourlyRate: null,
+            optimalHourlyRate: null,
+        }).success).toBe(true);
+    });
+    it.each([
+        ['minimumHourlyRate', 0],
+        ['averageHourlyRate', -1],
+        ['optimalHourlyRate', 30.001],
+    ])('rejects invalid %s value %s on create', (field, value) => {
+        const result = trades_contract_1.CreateTradeSchema.safeParse({
+            name: 'Electrician',
+            [field]: value,
+        });
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error.issues.map((issue) => issue.path.join('.'))).toContain(field);
+        }
+    });
+    it('keeps create and update as plain ZodObjects that accept out-of-order benchmarks', () => {
+        expect(trades_contract_1.CreateTradeSchema).toBeInstanceOf(zod_1.z.ZodObject);
+        expect(trades_contract_1.UpdateTradeSchema).toBeInstanceOf(zod_1.z.ZodObject);
+        expect(trades_contract_1.CreateTradeSchema.safeParse({
+            name: 'Electrician',
+            minimumHourlyRate: 31,
+            averageHourlyRate: 30,
+            optimalHourlyRate: 29,
+        }).success).toBe(true);
+        expect(trades_contract_1.UpdateTradeSchema.safeParse({
+            minimumHourlyRate: 31,
+            averageHourlyRate: 30,
+            optimalHourlyRate: 29,
+        }).success).toBe(true);
+    });
+    it.each([
+        [
+            {
+                minimumHourlyRate: 31,
+                averageHourlyRate: 30,
+                optimalHourlyRate: 32,
+            },
+            'averageHourlyRate',
+        ],
+        [
+            {
+                minimumHourlyRate: 29,
+                averageHourlyRate: 32,
+                optimalHourlyRate: 31,
+            },
+            'optimalHourlyRate',
+        ],
+        [
+            {
+                minimumHourlyRate: 32,
+                optimalHourlyRate: 31,
+            },
+            'optimalHourlyRate',
+        ],
+    ])('rejects out-of-order merged benchmarks at %s', (benchmarks, issuePath) => {
+        const result = trades_contract_1.TradeRateBenchmarksSchema.safeParse(benchmarks);
+        expect(result.success).toBe(false);
+        if (!result.success) {
+            expect(result.error.issues.map((issue) => issue.path.join('.'))).toContain(issuePath);
+        }
+    });
+    it.each([
+        {},
+        {
+            minimumHourlyRate: null,
+            averageHourlyRate: null,
+            optimalHourlyRate: null,
+        },
+        {
+            minimumHourlyRate: 29,
+            averageHourlyRate: null,
+            optimalHourlyRate: null,
+        },
+        {
+            minimumHourlyRate: null,
+            averageHourlyRate: 30,
+            optimalHourlyRate: null,
+        },
+        {
+            minimumHourlyRate: null,
+            averageHourlyRate: null,
+            optimalHourlyRate: 31,
+        },
+        {
+            minimumHourlyRate: null,
+            averageHourlyRate: 30,
+            optimalHourlyRate: 31,
+        },
+        {
+            minimumHourlyRate: 29,
+            averageHourlyRate: null,
+            optimalHourlyRate: 31,
+        },
+        {
+            minimumHourlyRate: 29,
+            averageHourlyRate: 30,
+            optimalHourlyRate: null,
+        },
+        {
+            minimumHourlyRate: 29,
+            averageHourlyRate: 30,
+            optimalHourlyRate: 31,
+        },
+    ])('accepts nullable merged benchmark combination %#', (benchmarks) => {
+        expect(trades_contract_1.TradeRateBenchmarksSchema.safeParse(benchmarks).success).toBe(true);
+    });
+    it('accepts a partial update benchmark object at the schema boundary', () => {
+        expect(trades_contract_1.UpdateTradeSchema.safeParse({ averageHourlyRate: 30 }).success).toBe(true);
+    });
+});

package/dist/user-access-grants/build-user-access-grant-rules.d.ts

@@ -0,0 +1,10 @@
+import type { AbilityRule } from '../abilities/abilities.contract';
+import type { EffectiveUserAccessGrantScope } from './user-access-grants.contract';
+/**
+ * Pure compiler: normalized effective scopes -> CASL rules. Consumed by BOTH
+ * the API CaslAbilityFactory and the web computeAbilityRules; rules must be
+ * inserted BEFORE role rules so role-level prohibitions keep precedence.
+ * Never consumes database-provided conditions or field lists.
+ */
+export declare function buildUserAccessGrantRules(scopes: EffectiveUserAccessGrantScope[]): AbilityRule[];
+//# sourceMappingURL=build-user-access-grant-rules.d.ts.map

package/dist/user-access-grants/build-user-access-grant-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-user-access-grant-rules.d.ts","sourceRoot":"","sources":["../../contracts/user-access-grants/build-user-access-grant-rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAEnE,OAAO,KAAK,EACV,6BAA6B,EAE9B,MAAM,+BAA+B,CAAC;AAqCvC;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,6BAA6B,EAAE,GACtC,WAAW,EAAE,CAqCf"}

package/dist/user-access-grants/build-user-access-grant-rules.js

@@ -0,0 +1,69 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUserAccessGrantRules = buildUserAccessGrantRules;
+const user_access_grant_templates_json_1 = __importDefault(require("./user-access-grant-templates.json"));
+const TEMPLATES = user_access_grant_templates_json_1.default;
+/**
+ * Version-controlled ownership mapping (see the design spec's Product
+ * Semantics). One positive rule per owner column; multiple rules on the same
+ * subject are an implicit OR under CASL and abilityToQuery().
+ */
+const OWNER_COLUMNS = {
+    BOOKING: ['userId', 'faUserId'],
+    ACTIVE: ['saUserId', 'faUserId'],
+    WORKER: ['createdByUserId'],
+};
+const RESOURCE_ORDER = [
+    'BOOKING',
+    'ACTIVE',
+    'WORKER',
+];
+const SHARED_REFERENCE_RULES = [
+    { action: 'read', subject: 'Trade' },
+    { action: 'read', subject: 'Qualification' },
+    { action: 'read', subject: 'QualificationType' },
+];
+/**
+ * Pure compiler: normalized effective scopes -> CASL rules. Consumed by BOTH
+ * the API CaslAbilityFactory and the web computeAbilityRules; rules must be
+ * inserted BEFORE role rules so role-level prohibitions keep precedence.
+ * Never consumes database-provided conditions or field lists.
+ */
+function buildUserAccessGrantRules(scopes) {
+    const rules = [];
+    const supporting = [];
+    let anyGrant = false;
+    for (const resource of RESOURCE_ORDER) {
+        const scope = scopes.find((candidate) => candidate.resource === resource && candidate.action === 'READ');
+        if (!scope)
+            continue;
+        const targets = [...new Set(scope.targetUserIds)].sort();
+        if (targets.length === 0)
+            continue;
+        anyGrant = true;
+        const template = TEMPLATES[resource];
+        for (const ownerColumn of OWNER_COLUMNS[resource]) {
+            rules.push({
+                action: 'read',
+                subject: template.subject,
+                fields: template.fields,
+                conditions: { [ownerColumn]: { $in: targets } },
+            });
+        }
+        for (const inverted of template.inverted) {
+            rules.push({
+                action: 'read',
+                subject: inverted.subject,
+                fields: inverted.fields,
+                inverted: true,
+            });
+        }
+        supporting.push(...template.supporting);
+    }
+    if (!anyGrant)
+        return [];
+    return [...rules, ...supporting, ...SHARED_REFERENCE_RULES];
+}

package/dist/user-access-grants/build-user-access-grant-rules.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=build-user-access-grant-rules.spec.d.ts.map

package/dist/user-access-grants/build-user-access-grant-rules.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-user-access-grant-rules.spec.d.ts","sourceRoot":"","sources":["../../contracts/user-access-grants/build-user-access-grant-rules.spec.ts"],"names":[],"mappings":""}

package/dist/user-access-grants/build-user-access-grant-rules.spec.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const bun_test_1 = require("bun:test");
+const build_user_access_grant_rules_1 = require("./build-user-access-grant-rules");
+const A = '00000000-0000-4000-8000-00000000000a';
+const B = '00000000-0000-4000-8000-00000000000b';
+const scope = (resource, targetUserIds) => ({
+    action: 'READ',
+    resource,
+    targetUserIds,
+});
+(0, bun_test_1.describe)('buildUserAccessGrantRules', () => {
+    (0, bun_test_1.it)('produces no rules for no scopes or empty target sets', () => {
+        (0, bun_test_1.expect)((0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([])).toEqual([]);
+        (0, bun_test_1.expect)((0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([scope('BOOKING', [])])).toEqual([]);
+    });
+    (0, bun_test_1.it)('emits two Booking rules (userId, faUserId) with sorted $in targets', () => {
+        const rules = (0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([scope('BOOKING', [B, A])]);
+        const booking = rules.filter((rule) => rule.subject === 'Booking' && !rule.inverted);
+        (0, bun_test_1.expect)(booking).toHaveLength(2);
+        (0, bun_test_1.expect)(booking[0].conditions).toEqual({ userId: { $in: [A, B] } });
+        (0, bun_test_1.expect)(booking[1].conditions).toEqual({ faUserId: { $in: [A, B] } });
+        (0, bun_test_1.expect)(booking[0].fields).toBeDefined();
+        (0, bun_test_1.expect)(booking[0].fields.length).toBeGreaterThan(0);
+    });
+    (0, bun_test_1.it)('emits two Active rules (saUserId, faUserId) whose fields exclude pay.receivedRate', () => {
+        const rules = (0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([scope('ACTIVE', [A])]);
+        const active = rules.filter((rule) => rule.subject === 'Active' && !rule.inverted);
+        (0, bun_test_1.expect)(active).toHaveLength(2);
+        (0, bun_test_1.expect)(active.map((rule) => Object.keys(rule.conditions ?? {})[0]).sort()).toEqual(['faUserId', 'saUserId']);
+        for (const rule of active) {
+            (0, bun_test_1.expect)(rule.fields).not.toContain('pay.receivedRate');
+        }
+    });
+    (0, bun_test_1.it)('emits one Worker rule on createdByUserId with an explicit allowlist and an inverted createdBy rule', () => {
+        const rules = (0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([scope('WORKER', [A])]);
+        const positive = rules.filter((rule) => rule.subject === 'Worker' && !rule.inverted);
+        (0, bun_test_1.expect)(positive).toHaveLength(1);
+        (0, bun_test_1.expect)(positive[0].conditions).toEqual({
+            createdByUserId: { $in: [A] },
+        });
+        (0, bun_test_1.expect)(positive[0].fields).toBeDefined();
+        (0, bun_test_1.expect)(positive[0].fields).not.toContain('createdBy');
+        const inverted = rules.filter((rule) => rule.subject === 'Worker' && rule.inverted);
+        (0, bun_test_1.expect)(inverted).toHaveLength(1);
+        (0, bun_test_1.expect)(inverted[0].fields).toEqual(['createdBy']);
+    });
+    (0, bun_test_1.it)('adds filter/sort supporting rules and shared reference reads exactly once', () => {
+        const rules = (0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([
+            scope('BOOKING', [A]),
+            scope('ACTIVE', [A]),
+        ]);
+        const referenceReads = rules.filter((rule) => ['Trade', 'Qualification', 'QualificationType'].includes(rule.subject));
+        (0, bun_test_1.expect)(referenceReads).toHaveLength(3);
+        (0, bun_test_1.expect)(referenceReads.every((rule) => rule.action === 'read' && !rule.inverted)).toBe(true);
+        (0, bun_test_1.expect)(rules.some((rule) => rule.subject === 'FilterBookingSchema')).toBe(true);
+        (0, bun_test_1.expect)(rules.some((rule) => rule.subject === 'FilterActiveSchema')).toBe(true);
+    });
+    (0, bun_test_1.it)('is deterministic regardless of scope order', () => {
+        const forward = (0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([
+            scope('WORKER', [A]),
+            scope('BOOKING', [B]),
+        ]);
+        const backward = (0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([
+            scope('BOOKING', [B]),
+            scope('WORKER', [A]),
+        ]);
+        (0, bun_test_1.expect)(forward).toEqual(backward);
+    });
+    (0, bun_test_1.it)('deduplicates target IDs', () => {
+        const rules = (0, build_user_access_grant_rules_1.buildUserAccessGrantRules)([scope('WORKER', [A, A])]);
+        const positive = rules.find((rule) => rule.subject === 'Worker' && !rule.inverted);
+        (0, bun_test_1.expect)(positive.conditions).toEqual({
+            createdByUserId: { $in: [A] },
+        });
+    });
+});