@oomol-lab/open-connector 1.9.0 → 1.9.1

package/src/providers/github/app-installation.js

@@ -0,0 +1,233 @@
+import { importPKCS8, SignJWT } from "jose";
+import { sha256Hex } from "../../core/aws-sigv4.js";
+import { base64Bytes, optionalRecord, optionalString, stringRecord } from "../../core/cast.js";
+import { ProviderRequestError, requiredInputString, runProviderRequest } from "../provider-runtime.js";
+import { githubRequestJson } from "./runtime-shared.js";
+/**
+ * GitHub App installation credentials.
+ *
+ * A GitHub App authenticates in two steps: the App's private key signs a short
+ * RS256 JWT that identifies the App, and that JWT is exchanged for an
+ * installation access token scoped to one installation (an account that
+ * installed the App and the repositories it selected). Installation tokens are
+ * what the REST API accepts on repository endpoints; they expire after one hour
+ * and cannot be refreshed, only minted again.
+ *
+ * The stored credential therefore holds the three inputs of that exchange —
+ * `appId`, `installationId`, `privateKey` — and the runtime mints tokens on
+ * demand, reusing one across calls until shortly before it expires.
+ */
+/** GitHub refuses an App JWT older than ten minutes; nine leaves room for clock skew. */
+const appJwtLifetimeSeconds = 9 * 60;
+/** Issued-at is backdated so a runtime clock slightly ahead of GitHub's still validates. */
+const appJwtClockSkewSeconds = 60;
+/** A cached installation token is replaced this long before GitHub expires it. */
+const installationTokenRenewalMarginMs = 5 * 60 * 1000;
+const pkcs8Marker = "-----BEGIN PRIVATE KEY-----";
+const pkcs1Marker = "-----BEGIN RSA PRIVATE KEY-----";
+export function readGitHubAppInstallationCredential(values) {
+    const appId = requiredInputString(values.appId, "appId").trim();
+    if (!/^\d+$/u.test(appId)) {
+        throw new ProviderRequestError(400, "appId must be the numeric App ID shown on the GitHub App's settings page");
+    }
+    const installationId = requiredInputString(values.installationId, "installationId").trim();
+    if (!/^\d+$/u.test(installationId)) {
+        throw new ProviderRequestError(400, "installationId must be the numeric installation id from the installation's settings URL or the post-install redirect");
+    }
+    return { appId, installationId, privateKey: normalizePrivateKey(values.privateKey) };
+}
+/**
+ * Accept the key as GitHub downloads it (PKCS#1, `BEGIN RSA PRIVATE KEY`) or
+ * already converted to PKCS#8, with literal or escaped line breaks.
+ */
+function normalizePrivateKey(value) {
+    const pem = requiredInputString(value, "privateKey").replaceAll("\\n", "\n").trim();
+    if (pem.includes(pkcs8Marker)) {
+        return pem;
+    }
+    if (pem.includes(pkcs1Marker)) {
+        return pkcs1ToPkcs8Pem(pem);
+    }
+    throw new ProviderRequestError(400, "privateKey must be the PEM contents of the GitHub App private key (.pem) file, starting with -----BEGIN RSA PRIVATE KEY-----");
+}
+/**
+ * Wrap a PKCS#1 RSAPrivateKey in the PKCS#8 PrivateKeyInfo structure WebCrypto
+ * imports. The wrapper is fixed for RSA: version 0, the rsaEncryption algorithm
+ * identifier with a NULL parameter, then the PKCS#1 DER as an OCTET STRING.
+ */
+export function pkcs1ToPkcs8Pem(pkcs1Pem) {
+    const base64 = pkcs1Pem.replace(pkcs1Marker, "").replace("-----END RSA PRIVATE KEY-----", "").replace(/\s+/gu, "");
+    const pkcs1 = base64ToBytes(base64);
+    const algorithm = Uint8Array.from([
+        0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00,
+    ]);
+    const version = Uint8Array.from([0x02, 0x01, 0x00]);
+    const keyOctets = derTlv(0x04, pkcs1);
+    const body = concatBytes(version, algorithm, keyOctets);
+    const pkcs8 = derTlv(0x30, body);
+    const lines = bytesToBase64(pkcs8).match(/.{1,64}/gu) ?? [];
+    return `${pkcs8Marker}\n${lines.join("\n")}\n-----END PRIVATE KEY-----`;
+}
+function derTlv(tag, value) {
+    return concatBytes(Uint8Array.from([tag]), derLength(value.byteLength), value);
+}
+function derLength(length) {
+    if (length < 0x80) {
+        return Uint8Array.from([length]);
+    }
+    const bytes = [];
+    for (let remaining = length; remaining > 0; remaining = Math.floor(remaining / 0x100)) {
+        bytes.unshift(remaining % 0x100);
+    }
+    return Uint8Array.from([0x80 | bytes.length, ...bytes]);
+}
+function concatBytes(...parts) {
+    const out = new Uint8Array(parts.reduce((total, part) => total + part.byteLength, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}
+function base64ToBytes(base64) {
+    return base64Bytes(base64, "privateKey", () => new ProviderRequestError(400, "privateKey is not a valid PEM: its body is not base64"));
+}
+/**
+ * Encode DER bytes for a PEM body. These are key bytes assembled one at a
+ * time, so the binary string is Latin-1 by construction; the `btoa` fallback
+ * is the same shape the provider source guard allowlists for gitea and
+ * pi_hole, and it never sees a credential string.
+ */
+function bytesToBase64(bytes) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+/** Sign the App JWT GitHub's App endpoints and the token mint take as bearer. */
+export async function signGitHubAppJwt(credential) {
+    let signingKey;
+    try {
+        signingKey = await importPKCS8(credential.privateKey, "RS256");
+    }
+    catch {
+        throw new ProviderRequestError(400, "privateKey must be an RSA private key in PEM format, as downloaded from the GitHub App's settings page");
+    }
+    const now = Math.floor(Date.now() / 1000);
+    return new SignJWT({})
+        .setProtectedHeader({ alg: "RS256", typ: "JWT" })
+        .setIssuer(credential.appId)
+        .setIssuedAt(now - appJwtClockSkewSeconds)
+        .setExpirationTime(now - appJwtClockSkewSeconds + appJwtLifetimeSeconds)
+        .sign(signingKey);
+}
+/** Describe the installation the credential names, authenticated as the App. */
+export async function fetchGitHubAppInstallation(credential, fetcher, signal) {
+    return runProviderRequest({ label: "GitHub installation", signal }, async (signal) => githubRequestJson({
+        path: `/app/installations/${encodeURIComponent(credential.installationId)}`,
+        accessToken: await signGitHubAppJwt(credential),
+        fetcher,
+        signal,
+    }));
+}
+/** Mint an installation access token with the App's full granted permissions. */
+export async function mintGitHubInstallationToken(credential, fetcher, signal) {
+    return runProviderRequest({ label: "GitHub installation token", signal }, async (signal) => {
+        const minted = await githubRequestJson({
+            method: "POST",
+            path: `/app/installations/${encodeURIComponent(credential.installationId)}/access_tokens`,
+            body: {},
+            accessToken: await signGitHubAppJwt(credential),
+            fetcher,
+            signal,
+        });
+        const token = optionalString(minted.token);
+        const expiresAt = optionalString(minted.expires_at);
+        if (!token || !expiresAt) {
+            throw new ProviderRequestError(500, "GitHub returned an installation token without a token or expiry", 502);
+        }
+        return {
+            token,
+            expiresAt,
+            permissions: stringRecord(optionalRecord(minted.permissions) ?? {}),
+            repositorySelection: optionalString(minted.repository_selection),
+        };
+    });
+}
+/**
+ * Installation tokens shared across action runs in this process, keyed by App,
+ * installation and private-key digest. A token is reused until five minutes before GitHub expires
+ * it; a failed mint evicts itself so the next run retries instead of inheriting
+ * the rejection.
+ */
+const installationTokens = new Map();
+export function clearGitHubInstallationTokenCache() {
+    installationTokens.clear();
+}
+function cachedInstallationToken(credential, fetcher) {
+    const key = `${credential.appId}:${credential.installationId}:${sha256Hex(credential.privateKey)}`;
+    const cached = installationTokens.get(key);
+    if (!cached) {
+        return refreshInstallationToken(key, credential, fetcher);
+    }
+    // No rejection handler, deliberately. A caller that joined an in-flight mint
+    // is told that the mint failed; the eviction in `refreshInstallationToken`
+    // has already made the NEXT call start over, so retrying here would turn one
+    // failure into a burst of one retry per waiting caller.
+    return cached.then((token) => {
+        if (isFresh(token)) {
+            return token;
+        }
+        // Stale. Another caller may already have started the replacement while
+        // this one was waiting on the old promise; join it rather than minting a
+        // second token for the same installation.
+        const latest = installationTokens.get(key);
+        return latest && latest !== cached ? latest : refreshInstallationToken(key, credential, fetcher);
+    });
+}
+function refreshInstallationToken(key, credential, fetcher) {
+    const current = installationTokens.get(key);
+    const minting = mintGitHubInstallationToken(credential, fetcher);
+    installationTokens.set(key, minting);
+    void minting.catch(() => {
+        if (installationTokens.get(key) === minting) {
+            if (current) {
+                installationTokens.set(key, current);
+            }
+            else {
+                installationTokens.delete(key);
+            }
+        }
+    });
+    return minting;
+}
+function isFresh(token) {
+    const expiresAt = Date.parse(token.expiresAt);
+    return Number.isFinite(expiresAt) && expiresAt - Date.now() > installationTokenRenewalMarginMs;
+}
+/** Resolve installation tokens without letting one caller cancel a shared mint. */
+export function createGitHubInstallationTokenResolver(values, fetcher) {
+    const credential = readGitHubAppInstallationCredential(values);
+    return async (signal) => {
+        signal?.throwIfAborted();
+        const pending = cachedInstallationToken(credential, fetcher);
+        if (!signal)
+            return (await pending).token;
+        return new Promise((resolve, reject) => {
+            const abort = () => reject(signal.reason);
+            signal.addEventListener("abort", abort, { once: true });
+            void pending.then((token) => {
+                signal.removeEventListener("abort", abort);
+                resolve(token.token);
+            }, (error) => {
+                signal.removeEventListener("abort", abort);
+                reject(error);
+            });
+        });
+    };
+}

package/src/providers/github/executors.js

@@ -1,4 +1,5 @@
-import { combineProviderActionHandlers, defineProviderExecutors, defineProviderProxy, requireBearerCredential, } from "../provider-runtime.js";
+import { combineProviderActionHandlers, defineProviderExecutors, defineProviderProxy, ProviderRequestError, requireBearerCredential, } from "../provider-runtime.js";
+import { createGitHubInstallationTokenResolver, fetchGitHubAppInstallation, mintGitHubInstallationToken, readGitHubAppInstallationCredential, } from "./app-installation.js";
 import { activityActionHandlers } from "./runtime-activity.js";
 import { issueActionHandlers } from "./runtime-issue.js";
 import { pullRequestActionHandlers } from "./runtime-pull-request.js";
@@ -9,29 +10,68 @@ import { githubApiBaseUrl, githubApiVersion, githubDefaultAcceptHeader, githubRe
 import { githubRepoEvent } from "./trigger-on-repo-event.js";
 import { githubPullRequestListener } from "./trigger-watch-pull-request.js";
 const service = "github";
-export const executors = defineProviderExecutors({
-    service,
-    handlers: combineProviderActionHandlers(service, activityActionHandlers, repositoryActionHandlers, issueActionHandlers, pullRequestActionHandlers, releaseActionHandlers, searchActionHandlers),
-    async createContext(context, fetcher) {
-        const credential = await requireBearerCredential(context, service);
-        return {
-            accessToken: credential.accessToken,
-            fetcher,
-            transitFiles: context.transitFiles,
-            signal: context.signal,
-        };
-    },
-});
+const { get_current_user, ...installationHandlers } = combineProviderActionHandlers(service, activityActionHandlers, repositoryActionHandlers, issueActionHandlers, pullRequestActionHandlers, releaseActionHandlers, searchActionHandlers);
+export const executors = {
+    ...defineProviderExecutors({
+        service,
+        handlers: installationHandlers,
+        async createContext(context, fetcher) {
+            const credential = await context.getCredential(service);
+            if (credential?.authType === "custom_credential") {
+                return {
+                    accessToken: await createGitHubInstallationTokenResolver(credential.values, fetcher)(context.signal),
+                    fetcher,
+                    transitFiles: context.transitFiles,
+                    signal: context.signal,
+                    installation: true,
+                };
+            }
+            const bearer = await requireBearerCredential(context, service);
+            return {
+                accessToken: bearer.accessToken,
+                fetcher,
+                transitFiles: context.transitFiles,
+                signal: context.signal,
+            };
+        },
+    }),
+    ...defineProviderExecutors({
+        service,
+        handlers: { get_current_user },
+        async createContext(context, fetcher) {
+            const credential = await context.getCredential(service);
+            if (credential?.authType === "custom_credential") {
+                throw new ProviderRequestError(400, "get_current_user requires a personal access token or OAuth user credential. This connection uses a GitHub App installation.");
+            }
+            const bearer = await requireBearerCredential(context, service);
+            return { accessToken: bearer.accessToken, fetcher, signal: context.signal };
+        },
+    }),
+};
 export const proxy = defineProviderProxy({
     service,
     baseUrl: githubApiBaseUrl,
-    auth: { type: "bearer" },
+    // Resolved rather than `bearer`, because an installation credential has no
+    // stored token: it is minted from the App key at request time.
+    auth: {
+        type: "bearer_resolver",
+        async resolve({ context, fetcher }) {
+            return { accessToken: await resolveGitHubAccessToken(context, fetcher) };
+        },
+    },
     skipDnsValidation: true,
     customizeRequest({ headers }) {
         headers.set("accept", githubDefaultAcceptHeader);
         headers.set("x-github-api-version", githubApiVersion);
     },
 });
+async function resolveGitHubAccessToken(context, fetcher) {
+    const credential = await context.getCredential(service);
+    if (credential?.authType === "custom_credential") {
+        return createGitHubInstallationTokenResolver(credential.values, fetcher)(context.signal);
+    }
+    return (await requireBearerCredential(context, service)).accessToken;
+}
 export const credentialValidators = {
     async apiKey(input, { fetcher }) {
         return validateGitHubToken(input.apiKey, fetcher);
@@ -39,6 +79,9 @@ export const credentialValidators = {
     async oauth2(input, { fetcher }) {
         return validateGitHubToken(input.accessToken, fetcher);
     },
+    async customCredential(input, { fetcher, signal }) {
+        return validateGitHubAppInstallation(input.values, fetcher, signal);
+    },
 };
 async function validateGitHubToken(accessToken, fetcher) {
     const user = await githubRequestJson({
@@ -59,6 +102,41 @@ async function validateGitHubToken(accessToken, fetcher) {
         },
     };
 }
+/**
+ * Prove the three inputs agree with each other and with GitHub: the key signs
+ * for this App (the installation lookup accepts the JWT), the installation
+ * belongs to it, and a token can actually be minted. The profile is the
+ * installation's account, identifying where the App is installed.
+ */
+async function validateGitHubAppInstallation(values, fetcher, signal) {
+    const credential = readGitHubAppInstallationCredential(values);
+    const installation = await fetchGitHubAppInstallation(credential, fetcher, signal);
+    const minted = await mintGitHubInstallationToken(credential, fetcher, signal);
+    const account = installation.account ?? {};
+    const login = typeof account.login === "string" ? account.login : undefined;
+    const accountId = account.id === undefined ? undefined : String(account.id);
+    const accountType = typeof account.type === "string" ? account.type : undefined;
+    if (!login && !accountId) {
+        throw new ProviderRequestError(500, "GitHub described the installation without an account", 502);
+    }
+    return {
+        profile: {
+            accountId: login ?? accountId ?? `github:installation:${credential.installationId}`,
+            displayName: `GitHub App installation on ${login ?? accountId}`,
+            // Installation permissions are the closest thing to scopes an App has;
+            // they are reported as `<permission>:<level>` so a consumer can see what
+            // the credential may read without knowing GitHub's OAuth scope names.
+            grantedScopes: Object.entries(minted.permissions).map(([permission, level]) => `${permission}:${level}`),
+        },
+        metadata: {
+            appId: credential.appId,
+            installationId: credential.installationId,
+            accountType: accountType ?? null,
+            repositorySelection: minted.repositorySelection ?? installation.repository_selection ?? null,
+            permissions: minted.permissions,
+        },
+    };
+}
 export const triggers = [
     githubRepoEvent,
     githubPullRequestListener,

package/src/providers/github/runtime-repository.js

@@ -9,7 +9,10 @@ export const repositoryActionHandlers = {
             fetcher,
         });
     },
-    list_my_repositories(input, { accessToken, fetcher }) {
+    list_my_repositories(input, { accessToken, fetcher, installation }) {
+        if (installation) {
+            return listInstallationRepositories(input, accessToken, fetcher);
+        }
         return listMyRepositories(input, accessToken, fetcher);
     },
     create_repository(input, { accessToken, fetcher }) {
@@ -295,6 +298,23 @@ async function listMyRepositories(input, accessToken, fetcher) {
     });
     return { repositories };
 }
+async function listInstallationRepositories(input, accessToken, fetcher) {
+    for (const field of ["visibility", "sort", "direction"]) {
+        if (input[field] !== undefined) {
+            throw new ProviderRequestError(400, `${field} is not supported with a GitHub App installation credential. Omit it to list the installation's repositories.`);
+        }
+    }
+    const page = await githubRequestJson({
+        path: "/installation/repositories",
+        query: compactObject({
+            per_page: optionalInteger(input.perPage),
+            page: optionalInteger(input.page),
+        }),
+        accessToken,
+        fetcher,
+    });
+    return { repositories: page.repositories ?? [] };
+}
 async function deleteRepository(input, accessToken, fetcher) {
     await githubRequestNoContent({
         method: "DELETE",

package/src/providers/github/runtime-shared.d.ts

@@ -11,9 +11,11 @@ export type GitHubActionContext = {
     fetcher: typeof fetch;
     transitFiles?: TransitFileWriter;
     signal?: AbortSignal;
+    installation?: boolean;
 };
 export type GitHubActionHandler = (input: Record<string, unknown>, context: GitHubActionContext) => Promise<unknown>;
 interface GitHubJsonRequest {
+    signal?: AbortSignal;
     method?: string;
     path: string;
     query?: Record<string, string | number | boolean | undefined>;

package/src/providers/github/runtime-shared.js

@@ -9,6 +9,7 @@ export async function githubRequestJson(input) {
     const url = buildGitHubUrl(input.path, input.query);
     const response = await input.fetcher(url, {
         method: input.method ?? "GET",
+        signal: input.signal,
         headers: githubHeaders(input.accessToken, input.body !== undefined),
         body: input.body === undefined ? undefined : JSON.stringify(input.body),
     });

package/src/providers/googledrive/runtime-request.js

@@ -1,5 +1,5 @@
 import { looseArray, optionalRecord, optionalString } from "../../core/cast.js";
-import { createProviderTimeout, isAbortLikeError, providerUserAgent, ProviderRequestError, } from "../provider-runtime.js";
+import { createProviderTimeout, isAbortLikeError, providerUserAgent, ProviderRequestError, providerInputError, providerResponseError, } from "../provider-runtime.js";
 const defaultService = "googledrive";
 const googleDefaultRequestTimeoutMs = 30_000;
 export async function googleJsonRequest(url, input) {
@@ -29,7 +29,7 @@ export async function googleRequest(url, input) {
     const hasRequestBody = input.rawBody != null || hasJsonBody;
     const method = (input.method ?? (hasRequestBody ? "POST" : "GET")).toUpperCase();
     if ((method === "GET" || method === "HEAD") && hasRequestBody) {
-        throw new ProviderRequestError(400, `${service} ${method} request must not include a body`);
+        throw providerInputError(`${service} ${method} request must not include a body`);
     }
     const requestInit = {
         method,
@@ -51,7 +51,7 @@ export async function googleRequest(url, input) {
         if (timeout.didTimeout() && isAbortLikeError(error)) {
             const timeoutSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
             const unit = timeoutSeconds === 1 ? "second" : "seconds";
-            throw new ProviderRequestError(502, `${service} request timed out after ${timeoutSeconds} ${unit}`);
+            throw providerResponseError(`${service} request timed out after ${timeoutSeconds} ${unit}`);
         }
         throw error;
     }

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

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

package/src/providers/hrmos_kintai/actions.js

@@ -0,0 +1,139 @@
+import { s } from "../../core/json-schema.js";
+import { defineProviderAction } from "../../core/provider-definition.js";
+import { attendanceActions } from "./attendance-actions.js";
+import { businessActions } from "./business-actions.js";
+import { exportActions } from "./export-actions.js";
+import { pagination, employeeRecord, namedRecord, segmentRecord, attendanceRecord, reportRecord, stampRecord, leaveRecord, listOutput, } from "./schemas.js";
+export const hrmosKintaiActions = [
+    ...attendanceActions,
+    ...businessActions,
+    ...exportActions,
+    defineProviderAction("hrmos_kintai", {
+        name: "list_employees",
+        operationType: "read",
+        description: "List employees in the connected HRMOS Kintai company.",
+        inputSchema: s.object("Filters for list_employees.", {
+            ...pagination,
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(employeeRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_departments",
+        operationType: "read",
+        description: "List departments in the connected company.",
+        inputSchema: s.object("Filters for list_departments.", {
+            ...pagination,
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(namedRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_employment_types",
+        operationType: "read",
+        description: "List employment types in the connected company.",
+        inputSchema: s.object("Filters for list_employment_types.", {
+            ...pagination,
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(namedRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_workplaces",
+        operationType: "read",
+        description: "List workplaces, optionally filtered by prefecture.",
+        inputSchema: s.object("Filters for list_workplaces.", {
+            ...pagination,
+            prefectureId: s.integer("Filter workplaces by prefecture ID."),
+        }, { optional: ["prefectureId", "limit", "page", "from", "to"] }),
+        outputSchema: listOutput(namedRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_work_segments",
+        operationType: "read",
+        description: "List work classifications and their configured working hours.",
+        inputSchema: s.object("Filters for list_work_segments.", {
+            ...pagination,
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(segmentRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_leave_types",
+        operationType: "read",
+        description: "List leave settings used to query employee leave balances and history.",
+        inputSchema: s.object("Filters for list_leave_types.", {
+            ...pagination,
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(namedRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_daily_attendance",
+        operationType: "read",
+        description: "List attendance records for all employees on a specified day.",
+        inputSchema: s.object("Filters for list_daily_attendance.", {
+            ...pagination,
+            day: s.string("Target date in YYYY-MM-DD format.", { format: "date" }),
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(attendanceRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_monthly_attendance",
+        operationType: "read",
+        description: "List daily attendance records for a month, respecting each employee's cutoff date. Optionally filter by employee ID.",
+        inputSchema: s.object("Filters for list_monthly_attendance.", {
+            ...pagination,
+            month: s.string("Target month in YYYY-MM format. Attendance detail respects employee cutoff dates.", {
+                pattern: "^[0-9]{4}-(0[1-9]|1[0-2])$",
+            }),
+            employeeId: s.integer("HRMOS employee ID."),
+        }, { optional: ["employeeId", "limit", "page", "from", "to"] }),
+        outputSchema: listOutput(attendanceRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_monthly_reports",
+        operationType: "read",
+        description: "List monthly attendance summaries, optionally filtered by employee numbers and month-closing statuses.",
+        inputSchema: s.object("Filters for list_monthly_reports.", {
+            ...pagination,
+            month: s.string("Target month in YYYY-MM format. Attendance detail respects employee cutoff dates.", {
+                pattern: "^[0-9]{4}-(0[1-9]|1[0-2])$",
+            }),
+            employeeNumbers: s.array("Employee numbers to include; omit to include all employees.", s.string("Employee number.", { minLength: 1 }), { minItems: 1 }),
+            statuses: s.array("Month-closing statuses: 0 not submitted, 1 ready, 2 pending, 3 approved, 99 forcibly approved.", { ...s.integer("One month-closing status."), enum: [0, 1, 2, 3, 99] }, { minItems: 1, uniqueItems: true }),
+        }, { optional: ["employeeNumbers", "statuses", "limit", "page", "from", "to"] }),
+        outputSchema: listOutput(reportRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_daily_stamp_logs",
+        operationType: "read",
+        description: "List clock-in, clock-out and break punch history for a specified day.",
+        inputSchema: s.object("Filters for list_daily_stamp_logs.", {
+            ...pagination,
+            day: s.string("Target date in YYYY-MM-DD format.", { format: "date" }),
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(stampRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_employee_stamp_logs",
+        operationType: "read",
+        description: "List an employee's punch history, optionally filtered by punch type and update time.",
+        inputSchema: s.object("Filters for list_employee_stamp_logs.", {
+            ...pagination,
+            employeeId: s.integer("HRMOS employee ID."),
+            stampType: {
+                ...s.integer("Punch type: 1 clock-in, 2 clock-out, 7 break start, 8 break end."),
+                enum: [1, 2, 7, 8],
+            },
+        }, { optional: ["stampType", "limit", "page", "from", "to"] }),
+        outputSchema: listOutput(stampRecord),
+    }),
+    defineProviderAction("hrmos_kintai", {
+        name: "list_employee_leave_history",
+        operationType: "read",
+        description: "List an employee's leave grants, usage, adjustments and remaining balances for a leave setting and year.",
+        inputSchema: s.object("Filters for list_employee_leave_history.", {
+            ...pagination,
+            leaveTypeId: s.integer("Leave setting ID returned by list_leave_types."),
+            employeeId: s.integer("HRMOS employee ID."),
+            year: s.integer("Target leave year."),
+        }, { optional: ["limit", "page", "from", "to"] }),
+        outputSchema: listOutput(leaveRecord),
+    }),
+];

package/src/providers/hrmos_kintai/attendance-actions.d.ts

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