@ketvietlab/ketsuite 0.1.2 → 0.1.3

package/dist/modules/attendance/channel-routes.js

@@ -0,0 +1,234 @@
+// Attendance on the staff channel.
+//
+// The first vertical to answer on /api/staff/v1/, and a thin one on purpose:
+// every route here hands the session's own employee to a function that already
+// existed. Nothing about who the caller is arrives from the client — the
+// framework resolves the actor from the session, and attendance resolves the
+// employee from the actor, so an operator can only ever punch their own clock.
+import { channelError, defineChannelRoute, routesOf } from '../channel_api/core.js';
+const string = { type: 'string' };
+const nullableString = { type: ['string', 'null'] };
+const envelope = (data) => ({
+    type: 'object',
+    properties: { data, error: {}, meta: { type: 'object' } },
+});
+const object = { type: 'object' };
+const clockStatus = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        onClock: { type: 'boolean' },
+        sessionId: nullableString,
+        startAt: { ...nullableString, format: 'date-time' },
+        branchId: nullableString,
+    },
+    required: ['onClock'],
+};
+const attendanceSession = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        id: string,
+        branchId: string,
+        startAt: { ...string, format: 'date-time' },
+        stopAt: { ...nullableString, format: 'date-time' },
+        correctedStartAt: { ...nullableString, format: 'date-time' },
+        correctedStopAt: { ...nullableString, format: 'date-time' },
+        state: string,
+        workedHours: { type: 'string', pattern: '^\\d+(?:\\.\\d{2})$' },
+    },
+    required: [
+        'id',
+        'branchId',
+        'startAt',
+        'stopAt',
+        'correctedStartAt',
+        'correctedStopAt',
+        'state',
+        'workedHours',
+    ],
+};
+const attendancePage = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        dateFrom: { ...string, format: 'date' },
+        dateTo: { ...string, format: 'date' },
+        items: { type: 'array', items: attendanceSession },
+        nextCursor: nullableString,
+    },
+    required: ['dateFrom', 'dateTo', 'items', 'nextCursor'],
+};
+const punchResult = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        kind: { type: 'string', enum: ['in', 'out'] },
+        occurredAt: { ...string, format: 'date-time' },
+        sessionId: string,
+    },
+    required: ['kind', 'occurredAt', 'sessionId'],
+};
+const idempotencyKey = (ctx, url, req) => {
+    const key = String(req.headers['idempotency-key'] ?? '').trim();
+    if (key.length >= 8 && key.length <= 200)
+        return key;
+    return {
+        status: 400,
+        error: channelError(ctx, url, req, 'channel_api.idempotencyRequired', {
+            messageKey: 'channel_api.error.idempotencyRequired',
+        }),
+    };
+};
+const localDate = (value) => {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    return new Date(`${value}T00:00:00.000Z`).toISOString().slice(0, 10) === value;
+};
+const recordsQuery = (ctx, url, req, today) => {
+    const defaultFrom = new Date(`${today}T00:00:00.000Z`);
+    defaultFrom.setUTCDate(defaultFrom.getUTCDate() - 30);
+    const dateFrom = url.searchParams.get('dateFrom') ?? defaultFrom.toISOString().slice(0, 10);
+    const dateTo = url.searchParams.get('dateTo') ?? today;
+    const cursor = url.searchParams.get('cursor') ?? '0';
+    const limitText = url.searchParams.get('limit') ?? '20';
+    const offset = /^\d+$/.test(cursor) ? Number(cursor) : -1;
+    const limit = /^\d+$/.test(limitText) ? Number(limitText) : -1;
+    const days = localDate(dateFrom) && localDate(dateTo)
+        ? (Date.parse(`${dateTo}T00:00:00.000Z`) - Date.parse(`${dateFrom}T00:00:00.000Z`)) / 86_400_000
+        : -1;
+    if (days < 0 || days > 93 || offset < 0 || limit < 1 || limit > 100) {
+        return {
+            status: 400,
+            error: channelError(ctx, url, req, 'channel_api.validation', {
+                messageKey: 'channel_api.error.validation',
+            }),
+        };
+    }
+    return { dateFrom, dateTo, offset, limit };
+};
+/** A domain refusal, carried out with the key the module already translates. */
+const refused = (ctx, url, req, result, status = 422) => {
+    const first = (result?.errors ?? [])[0] ?? {};
+    const messageKey = first.code ?? 'attendance.error.invalid';
+    return {
+        status,
+        error: channelError(ctx, url, req, messageKey, {
+            messageKey,
+            ...(first.field
+                ? { fieldErrors: { [first.field]: { code: messageKey, messageKey, params: {} } } }
+                : {}),
+        }),
+    };
+};
+const punch = (expect) => async (ctx, url, req, identity) => {
+    const key = idempotencyKey(ctx, url, req);
+    if (typeof key !== 'string')
+        return key;
+    const namespace = `staff:${identity.companyId ?? 'none'}:${identity.userId}:attendance.punch.self:${expect}`;
+    // ctx.call, not callUnchecked: whether this operator may punch at all is the
+    // framework's answer, from the permissions their session carries.
+    const result = (await ctx.call('attendance.punch.self', { expect }, url, req, {
+        idempotencyKey: key,
+        idempotencyNamespace: namespace,
+    }));
+    return result.ok
+        ? {
+            status: 201,
+            data: { kind: result.kind, occurredAt: result.occurredAt, sessionId: result.sessionId },
+        }
+        : refused(ctx, url, req, result, 409);
+};
+export const channelRoutes = routesOf(defineChannelRoute({
+    profile: 'staff',
+    method: 'GET',
+    path: 'attendance/status',
+    operationId: 'staff.attendance.status',
+    summary: 'Whether the signed-in operator is on the clock, and since when.',
+    auth: 'required',
+    capability: { key: 'attendance.records', action: 'read' },
+    responses: { '200': envelope(clockStatus) },
+    handler: async (ctx, url, req) => ({
+        data: await ctx.call('attendance.clock.mine', {}, url, req),
+    }),
+}), defineChannelRoute({
+    profile: 'staff',
+    method: 'GET',
+    path: 'attendance/records',
+    operationId: 'staff.attendance.records.list',
+    summary: 'The operator’s own attendance sessions, newest first.',
+    auth: 'required',
+    capability: { key: 'attendance.records', action: 'read' },
+    request: {
+        query: {
+            type: 'object',
+            properties: {
+                dateFrom: { type: 'string', format: 'date' },
+                dateTo: { type: 'string', format: 'date' },
+                cursor: { type: 'string', pattern: '^\\d+$' },
+                limit: { type: 'integer', minimum: 1, maximum: 100 },
+            },
+        },
+    },
+    responses: { '200': envelope(attendancePage) },
+    handler: async (ctx, url, req) => {
+        const calendar = (await ctx.call('attendance.calendar.mine', {}, url, req));
+        const query = recordsQuery(ctx, url, req, calendar.today);
+        if ('status' in query)
+            return query;
+        const rows = (await ctx.call('attendance.session.mine', {
+            dateFrom: query.dateFrom,
+            dateTo: query.dateTo,
+            offset: query.offset,
+            limit: query.limit + 1,
+        }, url, req));
+        const hasMore = rows.length > query.limit;
+        return {
+            data: {
+                dateFrom: query.dateFrom,
+                dateTo: query.dateTo,
+                items: rows.slice(0, query.limit),
+                nextCursor: hasMore ? String(query.offset + query.limit) : null,
+            },
+        };
+    },
+}), defineChannelRoute({
+    profile: 'staff',
+    method: 'POST',
+    path: 'attendance/check-in',
+    operationId: 'staff.attendance.checkIn',
+    summary: 'Start a shift. Refused when one is already open.',
+    auth: 'required',
+    capability: { key: 'attendance.records', action: 'check_in' },
+    request: {
+        headers: {
+            type: 'object',
+            properties: { 'Idempotency-Key': { type: 'string', minLength: 8, maxLength: 200 } },
+            required: ['Idempotency-Key'],
+        },
+        body: object,
+    },
+    responses: { '201': envelope(punchResult) },
+    idempotent: true,
+    handler: (ctx, url, req, _params, request) => punch('in')(ctx, url, req, request.identity),
+}), defineChannelRoute({
+    profile: 'staff',
+    method: 'POST',
+    path: 'attendance/check-out',
+    operationId: 'staff.attendance.checkOut',
+    summary: 'End the open shift. Refused when there is none.',
+    auth: 'required',
+    capability: { key: 'attendance.records', action: 'check_out' },
+    request: {
+        headers: {
+            type: 'object',
+            properties: { 'Idempotency-Key': { type: 'string', minLength: 8, maxLength: 200 } },
+            required: ['Idempotency-Key'],
+        },
+        body: object,
+    },
+    responses: { '201': envelope(punchResult) },
+    idempotent: true,
+    handler: (ctx, url, req, _params, request) => punch('out')(ctx, url, req, request.identity),
+}));
+//# sourceMappingURL=channel-routes.js.map

package/dist/modules/attendance/channel-routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-routes.js","sourceRoot":"","sources":["../../../../../../../packages/ketsuite/src/modules/attendance/channel-routes.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,6EAA6E;AAC7E,+EAA+E;AAE/E,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAMnF,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;AACjC,MAAM,cAAc,GAAG,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAA;AACnD,MAAM,QAAQ,GAAG,CAAC,IAAa,EAAE,EAAE,CAAC,CAAC;IACnC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;CAC1D,CAAC,CAAA;AACF,MAAM,MAAM,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;AACjC,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE;QAC5B,SAAS,EAAE,cAAc;QACzB,OAAO,EAAE,EAAE,GAAG,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE;QACnD,QAAQ,EAAE,cAAc;KACzB;IACD,QAAQ,EAAE,CAAC,SAAS,CAAC;CACtB,CAAA;AACD,MAAM,iBAAiB,GAAG;IACxB,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,EAAE,EAAE,MAAM;QACV,QAAQ,EAAE,MAAM;QAChB,OAAO,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE;QAC3C,MAAM,EAAE,EAAE,GAAG,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE;QAClD,gBAAgB,EAAE,EAAE,GAAG,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE;QAC5D,eAAe,EAAE,EAAE,GAAG,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE;QAC3D,KAAK,EAAE,MAAM;QACb,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,EAAE;KAChE;IACD,QAAQ,EAAE;QACR,IAAI;QACJ,UAAU;QACV,SAAS;QACT,QAAQ;QACR,kBAAkB;QAClB,iBAAiB;QACjB,OAAO;QACP,aAAa;KACd;CACF,CAAA;AACD,MAAM,cAAc,GAAG;IACrB,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,QAAQ,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;QACvC,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;QACrC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE;QAClD,UAAU,EAAE,cAAc;KAC3B;IACD,QAAQ,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC;CACxD,CAAA;AACD,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,QAAQ;IACd,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;QACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE;QAC7C,UAAU,EAAE,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE;QAC9C,SAAS,EAAE,MAAM;KAClB;IACD,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,CAAC;CAC9C,CAAA;AAED,MAAM,cAAc,GAAG,CAAC,GAAiB,EAAE,GAAQ,EAAE,GAAQ,EAAE,EAAE;IAC/D,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAC/D,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,GAAG,CAAA;IACpD,OAAO;QACL,MAAM,EAAE,GAAG;QACX,KAAK,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,iCAAiC,EAAE;YACpE,UAAU,EAAE,uCAAuC;SACpD,CAAC;KACH,CAAA;AACH,CAAC,CAAA;AAED,MAAM,SAAS,GAAG,CAAC,KAAa,EAAW,EAAE;IAC3C,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACpD,OAAO,IAAI,IAAI,CAAC,GAAG,KAAK,gBAAgB,CAAC,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,CAAA;AAChF,CAAC,CAAA;AAED,MAAM,YAAY,GAAG,CAAC,GAAiB,EAAE,GAAQ,EAAE,GAAQ,EAAE,KAAa,EAAE,EAAE;IAC5E,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,GAAG,KAAK,gBAAgB,CAAC,CAAA;IACtD,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,CAAA;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,WAAW,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAC3F,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAA;IACtD,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAA;IACpD,MAAM,SAAS,GAAG,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,CAAA;IACvD,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9D,MAAM,IAAI,GACR,SAAS,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC;QACtC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,MAAM,gBAAgB,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,QAAQ,gBAAgB,CAAC,CAAC,GAAG,UAAU;QAChG,CAAC,CAAC,CAAC,CAAC,CAAA;IACR,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,IAAI,MAAM,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;QACpE,OAAO;YACL,MAAM,EAAE,GAAG;YACX,KAAK,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,wBAAwB,EAAE;gBAC3D,UAAU,EAAE,8BAA8B;aAC3C,CAAC;SACH,CAAA;IACH,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC5C,CAAC,CAAA;AAED,gFAAgF;AAChF,MAAM,OAAO,GAAG,CAAC,GAAiB,EAAE,GAAQ,EAAE,GAAQ,EAAE,MAAe,EAAE,MAAM,GAAG,GAAG,EAAE,EAAE;IACvF,MAAM,KAAK,GAAG,CAAE,MAA+B,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IACvE,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,IAAI,0BAA0B,CAAA;IAC3D,OAAO;QACL,MAAM;QACN,KAAK,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,UAAU,EAAE;YAC7C,UAAU;YACV,GAAG,CAAC,KAAK,CAAC,KAAK;gBACb,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE;gBAClF,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;KACH,CAAA;AACH,CAAC,CAAA;AAED,MAAM,KAAK,GACT,CAAC,MAAoB,EAAE,EAAE,CACzB,KAAK,EAAE,GAAiB,EAAE,GAAQ,EAAE,GAAQ,EAAE,QAAsD,EAAE,EAAE;IACtG,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;IACzC,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAA;IACvC,MAAM,SAAS,GAAG,SAAS,QAAQ,CAAC,SAAS,IAAI,MAAM,IAAI,QAAQ,CAAC,MAAM,0BAA0B,MAAM,EAAE,CAAA;IAC5G,6EAA6E;IAC7E,kEAAkE;IAClE,MAAM,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE;QAC5E,cAAc,EAAE,GAAG;QACnB,oBAAoB,EAAE,SAAS;KAChC,CAAC,CAMD,CAAA;IACD,OAAO,MAAM,CAAC,EAAE;QACd,CAAC,CAAC;YACE,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE;SACxF;QACH,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,CAAA;AACzC,CAAC,CAAA;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CACnC,kBAAkB,CAAC;IACjB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,mBAAmB;IACzB,WAAW,EAAE,yBAAyB;IACtC,OAAO,EAAE,iEAAiE;IAC1E,IAAI,EAAE,UAAU;IAChB,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,EAAE;IACzD,SAAS,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE;IAC3C,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QACjC,IAAI,EAAE,MAAM,GAAG,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC;KAC5D,CAAC;CACH,CAAC,EACF,kBAAkB,CAAC;IACjB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE,+BAA+B;IAC5C,OAAO,EAAE,uDAAuD;IAChE,IAAI,EAAE,UAAU;IAChB,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,EAAE;IACzD,OAAO,EAAE;QACP,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;gBAC5C,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE;gBAC1C,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;gBAC7C,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE;aACrD;SACF;KACF;IACD,SAAS,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,cAAc,CAAC,EAAE;IAC9C,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC/B,MAAM,QAAQ,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAsB,CAAA;QAChG,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAA;QACzD,IAAI,QAAQ,IAAI,KAAK;YAAE,OAAO,KAAK,CAAA;QACnC,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAC1B,yBAAyB,EACzB;YACE,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC;SACvB,EACD,GAAG,EACH,GAAG,CACJ,CAAmC,CAAA;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAA;QACzC,OAAO;YACL,IAAI,EAAE;gBACJ,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC;gBACjC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;aAChE;SACF,CAAA;IACH,CAAC;CACF,CAAC,EACF,kBAAkB,CAAC;IACjB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EAAE,0BAA0B;IACvC,OAAO,EAAE,kDAAkD;IAC3D,IAAI,EAAE,UAAU;IAChB,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,UAAU,EAAE;IAC7D,OAAO,EAAE;QACP,OAAO,EAAE;YACP,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE;YACnF,QAAQ,EAAE,CAAC,iBAAiB,CAAC;SAC9B;QACD,IAAI,EAAE,MAAM;KACb;IACD,SAAS,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE;IAC3C,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,QAAS,CAAC;CAC5F,CAAC,EACF,kBAAkB,CAAC;IACjB,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,sBAAsB;IAC5B,WAAW,EAAE,2BAA2B;IACxC,OAAO,EAAE,iDAAiD;IAC1D,IAAI,EAAE,UAAU;IAChB,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,EAAE,MAAM,EAAE,WAAW,EAAE;IAC9D,OAAO,EAAE;QACP,OAAO,EAAE;YACP,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE,iBAAiB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE;YACnF,QAAQ,EAAE,CAAC,iBAAiB,CAAC;SAC9B;QACD,IAAI,EAAE,MAAM;KACb;IACD,SAAS,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE;IAC3C,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,QAAS,CAAC;CAC7F,CAAC,CACH,CAAA"}

package/dist/modules/attendance/functions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../../../../../packages/ketsuite/src/modules/attendance/functions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAO,MAAM,EAAO,MAAM,mBAAmB,CAAA;AA8QzD,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuiB5C,CAAA"}
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../../../../../../packages/ketsuite/src/modules/attendance/functions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAO,MAAM,EAAO,MAAM,mBAAmB,CAAA;AAqTzD,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqqB5C,CAAA"}

package/dist/modules/attendance/functions.js

@@ -1,5 +1,5 @@
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import { defineFn, eq, from, localDateTimeToUtc } from '@ketvietlab/ketjs';
+import { dateTimeFormatter, defineFn, desc, eq, from, gte, localDateTimeToUtc, lt } from '@ketvietlab/ketjs';
 import { hashPassword, verifyPassword } from '../user/password.js';
 const issue = (field, code, params) => ({
     field,
@@ -33,6 +33,32 @@ const policyFor = async (ctx) => (await ctx.db.select('attendance.Policy', { id:
     roundingMinutes: 1,
     overtimeMinimumMinutes: 30,
 };
+const currentMonth = (timezone) => {
+    const parts = dateTimeFormatter('en', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+    }).formatToParts(new Date());
+    const year = parts.find((part) => part.type === 'year')?.value;
+    const month = parts.find((part) => part.type === 'month')?.value;
+    if (!year || !month)
+        throw new Error('month');
+    return `${year}-${month}`;
+};
+const currentDate = (timezone) => {
+    const parts = dateTimeFormatter('en', {
+        timeZone: timezone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(new Date());
+    const year = parts.find((part) => part.type === 'year')?.value;
+    const month = parts.find((part) => part.type === 'month')?.value;
+    const day = parts.find((part) => part.type === 'day')?.value;
+    if (!year || !month || !day)
+        throw new Error('date');
+    return `${year}-${month}-${day}`;
+};
 const monthBounds = (month, timezone) => {
     if (!/^\d{4}-\d{2}$/.test(month))
         throw new Error('month');
@@ -87,6 +113,9 @@ const clock = async (ctx, input) => {
         }
         const version = Number(state.version);
         const punchId = randomUUID();
+        const heading = state.openSessionId ? 'out' : 'in';
+        if (input.expect && input.expect !== heading)
+            return invalid(issue('expect', `attendance.error.already${heading === 'out' ? 'In' : 'Out'}`));
         if (!state.openSessionId) {
             const sessionId = randomUUID();
             const claimed = await tx.db.compareAndSet('attendance.ClockState', { id: stateId }, { version, openSessionId: null }, { openSessionId: sessionId, version: version + 1 });
@@ -256,13 +285,19 @@ export const functions = {
     'kiosk.manageIssue': defineFn({
         input: { id: 'id?', name: 'text', branchId: 'id' },
         output: { ok: 'bool', id: 'id?', secret: 'text?', errors: 'json?' },
-        effects: ['write:attendance.Kiosk'],
+        effects: ['read:attendance.Kiosk', 'write:attendance.Kiosk'],
+        exposure: 'internal',
         idempotent: true,
-        agent: true,
+        agent: false,
         handler: async (ctx, a) => {
             if (!ctx.scope.branch || String(a.branchId) !== ctx.scope.branch)
                 return invalid(issue('branchId', 'attendance.error.branch'));
-            const id = String(a.id ?? randomUUID()), value = secret();
+            if (!clean(a.name))
+                return invalid(issue('name', 'attendance.error.required'));
+            const id = String(a.id ?? randomUUID());
+            if ((await ctx.db.select('attendance.Kiosk', { id }))[0])
+                return invalid(issue('requestKey', 'attendance.error.credentialReplay'));
+            const value = secret();
             await ctx.db.insert('attendance.Kiosk', {
                 id,
                 name: clean(a.name),
@@ -278,8 +313,9 @@ export const functions = {
         input: { employeeId: 'id', pin: 'text' },
         output: { ok: 'bool', id: 'id?', errors: 'json?' },
         effects: ['read:attendance.Credential', 'write:attendance.Credential'],
+        exposure: 'internal',
         idempotent: true,
-        agent: true,
+        agent: false,
         handler: async (ctx, a) => {
             const pin = clean(a.pin);
             if (!/^\d{4,12}$/.test(pin))
@@ -294,19 +330,45 @@ export const functions = {
             return { ok: true, id };
         },
     }),
+    'credential.manageOptions': defineFn({
+        input: {},
+        output: { id: 'id', code: 'text', name: 'text' },
+        effects: [
+            'read:attendance.Kiosk',
+            'write:attendance.Kiosk',
+            'read:attendance.Credential',
+            'write:attendance.Credential',
+            'read:hr.Employee',
+            'read:partner.Partner',
+        ],
+        agent: false,
+        handler: async (ctx) => {
+            const E = ctx.table('hr.Employee');
+            return (await ctx.db.all(from(E).preload('partner').where(eq(E.active, true)))).map((row) => ({
+                id: row.id,
+                code: row.code,
+                name: String(row.partner?.name ?? row.code),
+            }));
+        },
+    }),
     'credential.manageQr': defineFn({
-        input: { employeeId: 'id' },
+        input: { employeeId: 'id', requestKey: 'text?' },
         output: { ok: 'bool', id: 'id?', secret: 'text?', errors: 'json?' },
         effects: ['read:attendance.Credential', 'write:attendance.Credential'],
+        exposure: 'internal',
         idempotent: true,
-        agent: true,
+        agent: false,
         handler: async (ctx, a) => {
-            const value = qrSecret();
             const existing = (await ctx.db.select('attendance.Credential', { employeeId: a.employeeId }))[0];
+            const requestKey = clean(a.requestKey);
+            if (requestKey && existing?.qrRequestKey === requestKey)
+                return invalid(issue('requestKey', 'attendance.error.credentialReplay'));
+            const value = qrSecret();
             const id = String(existing?.id ?? `employee:${a.employeeId}`);
             const values = {
                 employeeId: a.employeeId,
                 qrDigest: digest(value),
+                qrRequestKey: requestKey || null,
                 qrIssuedAt: now(),
                 active: true,
                 updatedAt: now(),
@@ -398,7 +460,7 @@ export const functions = {
         },
     }),
     'punch.self': defineFn({
-        input: {},
+        input: { expect: 'text?' },
         output: {
             ok: 'bool',
             employeeId: 'id?',
@@ -416,20 +478,64 @@ export const functions = {
             'write:attendance.Session',
             'write:attendance.Punch',
         ],
-        handler: async (ctx) => {
+        idempotent: true,
+        handler: async (ctx, a) => {
             const employee = await employeeForActor(ctx);
             if (!employee)
                 return invalid(issue('employeeId', 'attendance.error.employeeUser'));
+            const expect = a.expect == null ? undefined : String(a.expect);
+            if (expect !== undefined && expect !== 'in' && expect !== 'out')
+                return invalid(issue('expect', 'attendance.error.invalid'));
             return clock(ctx, {
                 employee,
                 branchId: String(employee.homeBranchId),
                 source: 'account',
                 actorUserId: ctx.actor ?? undefined,
+                ...(expect ? { expect } : {}),
             });
         },
     }),
+    /** Whether this employee is on the clock right now, and since when. */
+    'clock.mine': defineFn({
+        input: {},
+        output: { onClock: 'bool', sessionId: 'id?', startAt: 'datetime?', branchId: 'id?' },
+        effects: ['read:hr.Employee', 'read:attendance.ClockState', 'read:attendance.Session'],
+        handler: async (ctx) => {
+            const employee = await employeeForActor(ctx);
+            if (!employee)
+                return { onClock: false };
+            const state = (await ctx.db.select('attendance.ClockState', { id: String(employee.id) }))[0];
+            if (!state?.openSessionId)
+                return { onClock: false };
+            const session = (await ctx.db.select('attendance.Session', { id: state.openSessionId }))[0];
+            return {
+                onClock: true,
+                sessionId: state.openSessionId,
+                startAt: session?.startAt ?? null,
+                branchId: session?.branchId ?? null,
+            };
+        },
+    }),
+    /** The attendance policy's local calendar date for channel defaults. */
+    'calendar.mine': defineFn({
+        input: {},
+        output: { today: 'text', timezone: 'text' },
+        effects: ['read:attendance.Policy'],
+        handler: async (ctx) => {
+            const policy = await policyFor(ctx);
+            const timezone = String(policy.timezone);
+            return { today: currentDate(timezone), timezone };
+        },
+    }),
     'session.mine': defineFn({
-        input: { month: 'text?' },
+        input: {
+            month: 'text?',
+            currentMonth: 'bool?',
+            dateFrom: 'text?',
+            dateTo: 'text?',
+            offset: 'int?',
+            limit: 'int?',
+        },
         output: {
             id: 'id',
             branchId: 'id',
@@ -438,17 +544,45 @@ export const functions = {
             correctedStartAt: 'datetime?',
             correctedStopAt: 'datetime?',
             state: 'text',
+            workedHours: 'text',
         },
         effects: ['read:hr.Employee', 'read:attendance.Session', 'read:attendance.Policy'],
         handler: async (ctx, a) => {
             const employee = await employeeForActor(ctx);
             if (!employee)
                 return [];
-            const rows = await ctx.db.select('attendance.Session', { employeeId: employee.id });
-            if (!a.month)
-                return rows;
-            const policy = await policyFor(ctx), [from, to] = monthBounds(String(a.month), String(policy.timezone));
-            return rows.filter((row) => String(row.startAt) >= from && String(row.startAt) < to);
+            const policy = await policyFor(ctx);
+            const S = ctx.table('attendance.Session');
+            let query = from(S).where(eq(S.employeeId, employee.id));
+            if (a.dateFrom) {
+                query = query.where(gte(S.startAt, localDateTimeToUtc(`${String(a.dateFrom)}T00:00`, String(policy.timezone))));
+            }
+            if (a.dateTo) {
+                const next = new Date(`${String(a.dateTo)}T00:00:00.000Z`);
+                next.setUTCDate(next.getUTCDate() + 1);
+                query = query.where(lt(S.startAt, localDateTimeToUtc(`${next.toISOString().slice(0, 10)}T00:00`, String(policy.timezone))));
+            }
+            // A month label and its UTC bounds must come from the same timezone.
+            // Letting the caller derive "current" from an employee timezone while
+            // these bounds use policy time can skip a whole month at the boundary.
+            if (a.month || a.currentMonth) {
+                const month = a.currentMonth ? currentMonth(String(policy.timezone)) : String(a.month);
+                const [from, to] = monthBounds(month, String(policy.timezone));
+                query = query.where(gte(S.startAt, from), lt(S.startAt, to));
+            }
+            query = query.orderBy(desc(S.startAt), desc(S.id));
+            if (a.offset != null)
+                query = query.offset(Math.max(0, Number(a.offset)));
+            if (a.limit != null)
+                query = query.limit(Math.max(1, Math.min(101, Number(a.limit))));
+            const rows = await ctx.db.all(query);
+            const rounding = Math.max(1, Number(policy.roundingMinutes));
+            return rows.map((row) => {
+                const stop = effectiveStop(row);
+                const rawMinutes = stop ? minutes(Date.parse(stop) - Date.parse(effectiveStart(row))) : 0;
+                const workedMinutes = Math.round(rawMinutes / rounding) * rounding;
+                return { ...row, workedHours: (workedMinutes / 60).toFixed(2) };
+            });
         },
     }),
     'correction.request': defineFn({
@@ -553,7 +687,7 @@ export const functions = {
         },
     }),
     'period.report': defineFn({
-        input: { month: 'text' },
+        input: { month: 'text?' },
         output: { id: 'id', month: 'text', timezone: 'text', state: 'text', version: 'int', entries: 'json?' },
         effects: [
             'read:attendance.Policy',
@@ -569,10 +703,11 @@ export const functions = {
         ],
         agent: true,
         handler: async (ctx, a) => {
-            const month = String(a.month);
             let policy;
+            let month;
             try {
                 policy = await policyFor(ctx);
+                month = clean(a.month) || currentMonth(String(policy.timezone));
                 monthBounds(month, String(policy.timezone));
             }
             catch {
@@ -601,7 +736,7 @@ export const functions = {
         },
     }),
     'period.manageClose': defineFn({
-        input: { month: 'text' },
+        input: { month: 'text', expectedVersion: 'int?' },
         output: { ok: 'bool', id: 'id?', version: 'int?', errors: 'json?' },
         effects: [
             'read:attendance.Policy',
@@ -645,6 +780,8 @@ export const functions = {
             }
             if (period.state === 'locked')
                 return { ok: true, id: period.id, version: period.version };
+            if (a.expectedVersion != null && Number(period.version) !== Number(a.expectedVersion))
+                return invalid(issue('version', 'attendance.error.invalid'));
             const open = (await ctx.db.select('attendance.Session', {})).some((row) => row.state === 'open' && String(row.startAt) >= bounds[0] && String(row.startAt) < bounds[1]);
             if (open)
                 return invalid(issue('month', 'attendance.error.periodOpenSession'));
@@ -661,12 +798,17 @@ export const functions = {
             if (pendingCorrections || pendingOvertime)
                 return invalid(issue('month', 'attendance.error.periodPending'));
             const version = Number(period.version) + 1;
-            await ctx.db.update('attendance.Period', { id: period.id }, { state: 'locked', version, lockedAt: now(), lockedBy: ctx.actor ?? null });
+            const changed = await ctx.db.compareAndSet('attendance.Period', { id: period.id }, {
+                state: 'open',
+                ...(a.expectedVersion == null ? {} : { version: Number(a.expectedVersion) }),
+            }, { state: 'locked', version, lockedAt: now(), lockedBy: ctx.actor ?? null });
+            if (!('dryRun' in changed) && !changed.matched)
+                return invalid(issue('version', 'attendance.error.invalid'));
             return { ok: true, id: period.id, version };
         },
     }),
     'period.manageReopen': defineFn({
-        input: { month: 'text', reason: 'text' },
+        input: { month: 'text', reason: 'text', expectedVersion: 'int?' },
         output: { ok: 'bool', id: 'id?', version: 'int?', errors: 'json?' },
         effects: ['read:attendance.Period', 'write:attendance.Period'],
         idempotent: true,
@@ -679,14 +821,21 @@ export const functions = {
                 return invalid(issue('month', 'attendance.error.missing'));
             if (period.state === 'open')
                 return { ok: true, id: period.id, version: period.version };
+            if (a.expectedVersion != null && Number(period.version) !== Number(a.expectedVersion))
+                return invalid(issue('version', 'attendance.error.invalid'));
             const version = Number(period.version) + 1;
-            await ctx.db.update('attendance.Period', { id: period.id }, {
+            const changed = await ctx.db.compareAndSet('attendance.Period', { id: period.id }, {
+                state: 'locked',
+                ...(a.expectedVersion == null ? {} : { version: Number(a.expectedVersion) }),
+            }, {
                 state: 'open',
                 version,
                 reopenedAt: now(),
                 reopenedBy: ctx.actor ?? null,
                 reopenReason: clean(a.reason),
             });
+            if (!('dryRun' in changed) && !changed.matched)
+                return invalid(issue('version', 'attendance.error.invalid'));
             return { ok: true, id: period.id, version };
         },
     }),