@oomol-lab/open-connector 1.9.0 → 1.9.2

package/src/providers/hrmos_kintai/operations.js

@@ -0,0 +1,278 @@
+export const hrmosOperations = {
+    list_employees: {
+        path: "/users",
+        method: "GET",
+        response: "list",
+    },
+    list_departments: {
+        path: "/departments",
+        method: "GET",
+        response: "list",
+    },
+    list_employment_types: {
+        path: "/employments",
+        method: "GET",
+        response: "list",
+    },
+    list_workplaces: {
+        path: "/lodgments",
+        method: "GET",
+        response: "list",
+    },
+    list_work_segments: {
+        path: "/segments",
+        method: "GET",
+        response: "list",
+    },
+    list_leave_types: {
+        path: "/paid_holidays",
+        method: "GET",
+        response: "list",
+    },
+    list_daily_attendance: {
+        path: "/work_outputs/daily/{day}",
+        method: "GET",
+        response: "list",
+    },
+    list_monthly_attendance: {
+        path: "/work_outputs/monthly/{month}",
+        method: "GET",
+        response: "list",
+    },
+    list_monthly_reports: {
+        path: "/work_output_months/monthly/{month}",
+        method: "GET",
+        response: "list",
+    },
+    list_daily_stamp_logs: {
+        path: "/stamp_logs/daily/{day}",
+        method: "GET",
+        response: "list",
+    },
+    list_employee_stamp_logs: {
+        path: "/stamp_logs/user/{user_id}",
+        method: "GET",
+        response: "list",
+    },
+    list_employee_leave_history: {
+        path: "/paid_holidays/{id}/users/{user_id}/year/{year}",
+        method: "GET",
+        response: "list",
+    },
+    list_daily_attendance_differences: {
+        path: "/work_output_diffs/daily/{day}",
+        method: "GET",
+        response: "list",
+    },
+    list_monthly_attendance_differences: {
+        path: "/work_output_diffs/monthly/{month}",
+        method: "GET",
+        response: "list",
+        aliases: {
+            employeeId: "user_id",
+        },
+    },
+    list_daily_time_band_totals: {
+        path: "/work_output_original_aggregates/daily/{month}",
+        method: "GET",
+        response: "list",
+        aliases: {
+            employeeId: "user_id",
+            timeBandId: "original_aggregate_id",
+        },
+    },
+    list_monthly_time_band_totals: {
+        path: "/work_output_original_aggregates/monthly/{month}",
+        method: "GET",
+        response: "list",
+        aliases: {
+            employeeId: "user_id",
+            timeBandId: "original_aggregate_id",
+        },
+    },
+    get_monthly_report_definitions: {
+        path: "/work_output_months/work_report_definitions",
+        method: "GET",
+        response: "definitions",
+    },
+    list_monthly_report_values: {
+        path: "/work_output_months/monthly/{month}/work_report",
+        method: "GET",
+        response: "list",
+        aliases: {
+            employeeNumbers: "number",
+            statuses: "status",
+        },
+    },
+    get_time_band_report_definitions: {
+        path: "/work_output_original_aggregates/work_report_definitions",
+        method: "GET",
+        response: "definitions",
+    },
+    list_time_band_report_values: {
+        path: "/work_output_original_aggregates/monthly/{month}/work_report",
+        method: "GET",
+        response: "list",
+    },
+    list_prefectures: {
+        path: "/prefecturals",
+        method: "GET",
+        response: "list",
+    },
+    update_attendance: {
+        path: "/work",
+        method: "PUT",
+        response: "record",
+        bodyField: "data",
+    },
+    upsert_external_attendance: {
+        path: "/work/other_systems",
+        method: "POST",
+        response: "record",
+        bodyField: "data",
+    },
+    upsert_employee: {
+        path: "/users",
+        method: "POST",
+        response: "record",
+        bodyField: "data",
+    },
+    create_stamp: {
+        path: "/stamp_logs",
+        method: "POST",
+        response: "record",
+        bodyField: "data",
+    },
+    export_dependent_declaration: {
+        path: "/nnc/reports/{year}/fuyo_shinkoku_csv",
+        method: "GET",
+        response: "file",
+    },
+    export_next_year_dependent_declaration: {
+        path: "/nnc/reports/{year}/fuyo_shinkoku_rainen_csv",
+        method: "GET",
+        response: "file",
+    },
+    export_insurance_deduction_declaration: {
+        path: "/nnc/reports/{year}/hokenryo_shinkoku_csv",
+        method: "GET",
+        response: "file",
+    },
+    export_income_deduction_declaration: {
+        path: "/nnc/reports/{year}/kihaisho_shinkoku_csv",
+        method: "GET",
+        response: "file",
+    },
+    export_housing_loan_declaration: {
+        path: "/nnc/reports/{year}/jutaku_loan_shinkoku_csv",
+        method: "GET",
+        response: "file",
+    },
+    export_previous_employment_withholding: {
+        path: "/nnc/reports/{year}/zenshoku_gensen_choshuhyo_csv",
+        method: "GET",
+        response: "file",
+    },
+    list_contracts: {
+        path: "/deal_contracts",
+        method: "GET",
+        response: "list",
+        aliases: {
+            employeeId: "user_id",
+            partnerId: "business_partner_id",
+        },
+    },
+    create_contract: {
+        path: "/deal_contracts",
+        method: "POST",
+        response: "record",
+        aliases: {},
+        bodyField: "data",
+    },
+    update_contract: {
+        path: "/deal_contracts/{id}",
+        method: "PUT",
+        response: "record",
+        aliases: {
+            contractId: "id",
+        },
+        bodyField: "data",
+    },
+    delete_contract: {
+        path: "/deal_contracts/{id}",
+        method: "DELETE",
+        response: "record",
+        aliases: {
+            contractId: "id",
+        },
+    },
+    list_business_partners: {
+        path: "/business_partners",
+        method: "GET",
+        response: "list",
+        aliases: {
+            partnerId: "id",
+            closeOut: "close_out",
+        },
+    },
+    create_business_partner: {
+        path: "/business_partners",
+        method: "POST",
+        response: "record",
+        aliases: {},
+        bodyField: "data",
+    },
+    update_business_partner: {
+        path: "/business_partners/{id}",
+        method: "PUT",
+        response: "record",
+        aliases: {
+            partnerId: "id",
+        },
+        bodyField: "data",
+    },
+    delete_business_partner: {
+        path: "/business_partners/{id}",
+        method: "DELETE",
+        response: "record",
+        aliases: {
+            partnerId: "id",
+        },
+    },
+    list_partner_contacts: {
+        path: "/business_partners/{business_partner_id}/business_partner_users",
+        method: "GET",
+        response: "list",
+        aliases: {
+            partnerId: "business_partner_id",
+        },
+    },
+    create_partner_contact: {
+        path: "/business_partners/{business_partner_id}/business_partner_users",
+        method: "POST",
+        response: "record",
+        aliases: {
+            partnerId: "business_partner_id",
+        },
+        bodyField: "data",
+    },
+    update_partner_contact: {
+        path: "/business_partners/{business_partner_id}/business_partner_users/{id}",
+        method: "PUT",
+        response: "record",
+        aliases: {
+            partnerId: "business_partner_id",
+            contactId: "id",
+        },
+        bodyField: "data",
+    },
+    delete_partner_contact: {
+        path: "/business_partners/{business_partner_id}/business_partner_users/{id}",
+        method: "DELETE",
+        response: "record",
+        aliases: {
+            partnerId: "business_partner_id",
+            contactId: "id",
+        },
+    },
+};

package/src/providers/hrmos_kintai/runtime.d.ts

@@ -0,0 +1,10 @@
+import type { ApiKeyProviderContext } from "../provider-runtime.ts";
+import { ProviderRequestError } from "../provider-runtime.ts";
+export declare function normalizeCompany(value: unknown): string;
+export declare function hrmosBaseUrl(company: string): string;
+export declare function readHrmosError(response: Response): Promise<ProviderRequestError>;
+export declare function authenticate(company: string, apiKey: string, fetcher: typeof fetch, signal?: AbortSignal, force?: boolean): Promise<string>;
+export interface HrmosContext extends ApiKeyProviderContext {
+    company: string;
+}
+export declare function executeHrmosAction(actionName: string, parameters: Record<string, unknown>, context: HrmosContext): Promise<unknown>;

package/src/providers/hrmos_kintai/runtime.js

@@ -0,0 +1,217 @@
+import { sha256Hex } from "../../core/aws-sigv4.js";
+import { optionalRecord, optionalString } from "../../core/cast.js";
+import { storeResponseInTransit } from "../../core/request.js";
+import { basicAuthorizationHeader, isAbortLikeError, providerInputError, providerResponseError, providerUserAgent, ProviderRequestError, requiredInputString, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+import { hrmosOperations } from "./operations.js";
+export function normalizeCompany(value) {
+    let company = requiredInputString(value, "companyUrl");
+    if (company.startsWith("https://")) {
+        let url;
+        try {
+            url = new URL(company);
+        }
+        catch {
+            throw providerInputError("companyUrl must be a valid HRMOS login URL");
+        }
+        if (url.origin !== "https://ieyasu.co" || url.username || url.password || url.search || url.hash) {
+            throw providerInputError("Use an HRMOS company login URL on https://ieyasu.co");
+        }
+        company = url.pathname.slice(1);
+        if (company.endsWith("/"))
+            company = company.slice(0, -1);
+        const segments = company.split("/");
+        if (segments.length === 2 && segments[1] === "login")
+            company = segments[0];
+    }
+    const allowed = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-";
+    if (!company || [...company].some((character) => !allowed.includes(character))) {
+        throw providerInputError("companyUrl must be the company slug or its https://ieyasu.co login URL");
+    }
+    return company;
+}
+export function hrmosBaseUrl(company) {
+    return `https://ieyasu.co/api/${normalizeCompany(company)}/v1`;
+}
+export async function readHrmosError(response) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        if (isAbortLikeError(error))
+            throw error;
+    }
+    // The generic 401 response cannot distinguish keys, tokens and permissions.
+    return new ProviderRequestError(response.status, optionalString(optionalRecord(body)?.message) ?? `HRMOS Kintai request failed (${response.status})`, undefined, response.status === 429 ? "rate_limited" : "provider_error");
+}
+async function readJson(response) {
+    if (!response.ok)
+        throw await readHrmosError(response);
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        if (isAbortLikeError(error))
+            throw error;
+        throw providerResponseError("HRMOS Kintai returned invalid JSON");
+    }
+}
+function paginationInteger(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null || raw.trim() === "")
+        return null;
+    const value = Number(raw);
+    return Number.isInteger(value) && value >= 0 ? value : null;
+}
+const tokens = new Map();
+export async function authenticate(company, apiKey, fetcher, signal, force = false) {
+    const cacheKey = sha256Hex(JSON.stringify([company, apiKey]));
+    if (force)
+        tokens.delete(cacheKey);
+    const cached = tokens.get(cacheKey);
+    if (cached) {
+        const result = await cached;
+        if (result.expiresAt > Date.now())
+            return result.token;
+        if (tokens.get(cacheKey) !== cached)
+            return authenticate(company, apiKey, fetcher, signal);
+        tokens.delete(cacheKey);
+    }
+    const pending = runProviderRequest({ label: "HRMOS Kintai authentication", signal }, async (requestSignal) => {
+        const response = await fetcher(`${hrmosBaseUrl(company)}/authentication/token`, {
+            method: "GET",
+            headers: {
+                // HRMOS encodes the Secret Key itself, with no trailing Basic-auth colon.
+                authorization: basicAuthorizationHeader(apiKey),
+                accept: "application/json",
+                "content-type": "application/json",
+                "user-agent": providerUserAgent,
+            },
+            signal: requestSignal,
+        });
+        const body = requiredResponseRecord(await readJson(response), "HRMOS Kintai token response");
+        const token = optionalString(body.token);
+        const expiresAt = Date.parse(optionalString(body.expired_at) ?? "");
+        if (!token?.trim() || !Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+            throw providerResponseError("HRMOS Kintai returned an invalid or expired token");
+        }
+        return { token, expiresAt: expiresAt - Math.min(60_000, (expiresAt - Date.now()) / 2) };
+    });
+    tokens.set(cacheKey, pending);
+    if (tokens.size > 500) {
+        const oldest = tokens.keys().next().value;
+        if (oldest !== undefined)
+            tokens.delete(oldest);
+    }
+    try {
+        return (await pending).token;
+    }
+    catch (error) {
+        if (tokens.get(cacheKey) === pending)
+            tokens.delete(cacheKey);
+        throw error;
+    }
+}
+export async function executeHrmosAction(actionName, parameters, context) {
+    const { company, apiKey, fetcher, transitFiles } = context;
+    const operation = hrmosOperations[actionName];
+    if (!operation)
+        throw providerInputError("Unknown HRMOS Kintai action");
+    if (operation.response === "file" && !transitFiles) {
+        throw new ProviderRequestError(500, "HRMOS CSV export requires transit storage");
+    }
+    let path = operation.path;
+    const aliases = {
+        employeeId: "user_id",
+        leaveTypeId: "id",
+        prefectureId: "prefectural_id",
+        stampType: "stamp_type",
+        employeeNumbers: "number",
+        statuses: "status",
+        ...operation.aliases,
+    };
+    const query = new URLSearchParams();
+    for (const [name, value] of Object.entries(parameters)) {
+        if (value === undefined || name === operation.bodyField)
+            continue;
+        const upstream = aliases[name] ?? name;
+        const marker = `{${upstream}}`;
+        if (path.includes(marker))
+            path = path.replace(marker, encodeURIComponent(String(value)));
+        else if (name === "employeeNumbers" && Array.isArray(value)) {
+            // OpenAPI form + explode arrays use repeated parameter names.
+            for (const number of value)
+                query.append("number", String(number));
+        }
+        else
+            query.set(upstream, Array.isArray(value) ? value.join(",") : String(value));
+    }
+    const token = await authenticate(company, apiKey, fetcher, context.signal);
+    return runProviderRequest({
+        label: "HRMOS Kintai",
+        signal: context.signal,
+        timeoutMs: operation.response === "file" ? 120_000 : undefined,
+    }, async (signal) => {
+        const url = new URL(`${hrmosBaseUrl(company)}${path}`);
+        url.search = query.toString();
+        const response = await fetcher(url, {
+            method: operation.method,
+            headers: {
+                authorization: `Token ${token}`,
+                "content-type": "application/json",
+                accept: operation.response === "file" ? "text/csv" : "application/json",
+                "user-agent": providerUserAgent,
+            },
+            body: operation.bodyField ? JSON.stringify(parameters[operation.bodyField]) : undefined,
+            signal,
+        });
+        if (response.status === 401)
+            tokens.delete(sha256Hex(JSON.stringify([company, apiKey])));
+        if (operation.response === "file") {
+            if (!response.ok)
+                throw await readHrmosError(response);
+            const mimeType = response.headers.get("content-type") || "text/csv";
+            if (mimeType.includes("text/html") || mimeType.includes("application/json")) {
+                await response.body?.cancel();
+                throw providerResponseError("HRMOS Kintai returned a non-CSV export response");
+            }
+            const name = `hrmos-${actionName.slice("export_".length)}-${parameters.year}.csv`;
+            const file = await storeResponseInTransit(response, transitFiles, {
+                name,
+                mimeType,
+                signal,
+                maxBytes: 64 * 1024 * 1024,
+                fieldName: "HRMOS Kintai CSV export",
+                createError: providerResponseError,
+            });
+            if (file.sizeBytes === 0) {
+                await transitFiles.delete(file.fileId);
+                throw providerResponseError("HRMOS Kintai returned an empty CSV export");
+            }
+            return { file };
+        }
+        const payload = await readJson(response);
+        if (operation.response === "record") {
+            return { record: requiredResponseRecord(payload, "HRMOS Kintai operation response") };
+        }
+        if (operation.response === "definitions") {
+            const definitions = requiredResponseRecord(payload, "HRMOS Kintai report definitions");
+            if (!Array.isArray(definitions.items)) {
+                throw providerResponseError("HRMOS Kintai definitions must include items");
+            }
+            return definitions;
+        }
+        if (!Array.isArray(payload))
+            throw providerResponseError("HRMOS Kintai list response must be an array");
+        const page = Number(parameters.page ?? 1);
+        const totalPages = paginationInteger(response.headers, "X-Total-Page");
+        return {
+            items: payload,
+            page,
+            totalCount: paginationInteger(response.headers, "X-Total-Count"),
+            totalPages,
+            nextPage: totalPages !== null && page < totalPages ? page + 1 : null,
+            useHourHoliday: response.headers.get("X-Use-Hour-Holiday"),
+        };
+    });
+}

package/src/providers/hrmos_kintai/schemas.d.ts

@@ -0,0 +1,10 @@
+import type { JsonSchema } from "../../core/types.ts";
+export declare const pagination: Record<string, JsonSchema>;
+export declare const employeeRecord: JsonSchema;
+export declare const namedRecord: JsonSchema;
+export declare const segmentRecord: JsonSchema;
+export declare const attendanceRecord: JsonSchema;
+export declare const reportRecord: JsonSchema;
+export declare const stampRecord: JsonSchema;
+export declare const leaveRecord: JsonSchema;
+export declare function listOutput(record: JsonSchema): JsonSchema;

package/src/providers/hrmos_kintai/schemas.js

@@ -0,0 +1,70 @@
+import { s } from "../../core/json-schema.js";
+export const pagination = {
+    limit: s.integer("Maximum records per page (1–100); defaults to 25.", {
+        minimum: 1,
+        maximum: 100,
+        default: 25,
+    }),
+    page: s.integer("Page number, starting at 1.", { minimum: 1, default: 1 }),
+    from: s.string("Include records updated at or after this timestamp.", { format: "date-time" }),
+    to: s.string("Include records updated at or before this timestamp.", { format: "date-time" }),
+};
+export const employeeRecord = s.looseObject("HRMOS employee record; additional upstream fields are preserved.", {
+    id: s.nullable(s.integer("Record ID.")),
+    number: s.nullable(s.string("Employee number.")),
+    first_name: s.nullable(s.string("Employee given name.")),
+    last_name: s.nullable(s.string("Employee family name.")),
+    department_id: s.nullable(s.integer("Department ID.")),
+    employment_id: s.nullable(s.integer("Employment type ID.")),
+    lodgment_id: s.nullable(s.integer("Workplace ID.")),
+});
+export const namedRecord = s.looseObject("HRMOS named record; additional upstream fields are preserved.", {
+    id: s.nullable(s.integer("Record ID.")),
+    name: s.nullable(s.string("Display name.")),
+});
+export const segmentRecord = s.looseObject("HRMOS segment record; additional upstream fields are preserved.", {
+    title: s.nullable(s.string("Work classification title.")),
+    display_title: s.nullable(s.string("Work classification display title.")),
+});
+export const attendanceRecord = s.looseObject("HRMOS attendance record; additional upstream fields are preserved.", {
+    user_id: s.nullable(s.integer("Employee ID.")),
+    number: s.nullable(s.string("Employee number.")),
+    full_name: s.nullable(s.string("Employee full name.")),
+    month: s.nullable(s.string("Attendance month as returned by HRMOS.")),
+    day: s.nullable(s.string("Attendance date.")),
+    actual_working_hours: s.nullable(s.string("Actual working duration in the HRMOS representation.")),
+    total_working_hours: s.nullable(s.string("Total working duration in the HRMOS representation.")),
+});
+export const reportRecord = s.looseObject("HRMOS report record; additional upstream fields are preserved.", {
+    user_id: s.nullable(s.integer("Employee ID.")),
+    number: s.nullable(s.string("Employee number.")),
+    month: s.nullable(s.string("Attendance month as returned by HRMOS.")),
+    actual_working_hours: s.nullable(s.string("Actual working duration in the HRMOS representation.")),
+    total_working_hours: s.nullable(s.string("Total working duration in the HRMOS representation.")),
+    over_work_time: s.nullable(s.string("Overtime duration in the HRMOS representation.")),
+    remain_paid_holidays: s.nullable(s.string("Remaining paid leave days as reported in the monthly summary.")),
+});
+export const stampRecord = s.looseObject("HRMOS stamp record; additional upstream fields are preserved.", {
+    user_id: s.nullable(s.integer("Employee ID.")),
+    stamp_type: s.nullable(s.integer("Punch type: 1 clock-in, 2 clock-out, 7 break start, 8 break end.")),
+    created_at: s.nullable(s.string("Record creation timestamp.")),
+    lodgment_id: s.nullable(s.integer("Workplace ID.")),
+});
+export const leaveRecord = s.looseObject("HRMOS leave record; additional upstream fields are preserved.", {
+    user_id: s.nullable(s.integer("Employee ID.")),
+    date: s.nullable(s.string("Leave history date.")),
+    remaining_days: s.nullable(s.number("Remaining leave days.")),
+    remaining_hours: s.nullable(s.number("Remaining leave hours.")),
+    taken_days: s.nullable(s.number("Leave days taken.")),
+    received_days: s.nullable(s.number("Leave days granted.")),
+});
+export function listOutput(record) {
+    return s.requiredObject("A page of HRMOS Kintai records with pagination metadata.", {
+        items: s.array("Records with original HRMOS field names and additional upstream fields preserved.", record),
+        page: s.integer("Current page number."),
+        totalCount: s.nullable(s.integer("Total records reported by HRMOS, or null when unavailable.")),
+        totalPages: s.nullable(s.integer("Total pages reported by HRMOS, or null when unavailable.")),
+        nextPage: s.nullable(s.integer("Next page number, or null when there is no known next page.")),
+        useHourHoliday: s.nullable(s.string("Raw X-Use-Hour-Holiday value for leave history, or null when absent.")),
+    });
+}

package/src/providers/humor_api/actions.d.ts

@@ -0,0 +1,2 @@
+import type { ActionDefinition } from "../../core/types.ts";
+export declare const humorApiActions: readonly ActionDefinition[];