@patimweb/pi-zep 1.0.0

package/src/tools/zep-projects.ts

@@ -0,0 +1,78 @@
+/**
+ * zep_projects -- discover bookable projects, Vorgänge and Tätigkeiten.
+ */
+
+import { Type } from "typebox";
+
+import { createClient } from "../session.ts";
+import { formatFormData } from "../formatting/formatters.ts";
+import { errorResult, textResult, type ToolResult } from "./shared.ts";
+
+export const ZepProjectsTool = {
+  name: "zep_projects",
+  label: "ZEP Projects",
+  description:
+    "List the ZEP projects available for time booking, plus the Vorgänge (work packages) and Tätigkeiten of the selected project. Use it to resolve ids before calling zep_book. Pass 'projekt' to make ZEP re-render the form for a specific project so its Vorgänge can be read.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    projekt: Type.Optional(
+      Type.String({
+        description:
+          "Project id (e.g. '413') or part of its label. ZEP re-renders the booking form for this project so its Vorgänge become visible.",
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string; projekt?: string },
+  ): Promise<ToolResult> {
+    try {
+      const { client, profileName } = await createClient(params.profile);
+      const { form } = await client.loadForm();
+
+      if (!params.projekt) {
+        return textResult(formatFormData(form), {
+          profile: profileName,
+          projects: form.projects,
+          selected: form.selected,
+        });
+      }
+
+      const resolved = resolveProject(form, params.projekt);
+      if (!resolved) return errorResult(`No project matches "${params.projekt}".`);
+
+      const refreshed = await client.refreshFormForProject(resolved.id);
+      const merged = {
+        ...form,
+        vorgaenge: refreshed.vorgaenge.length ? refreshed.vorgaenge : form.vorgaenge,
+        taetigkeiten: refreshed.taetigkeiten.length ? refreshed.taetigkeiten : form.taetigkeiten,
+        selected: { ...form.selected, projektId: resolved.id },
+      };
+
+      return textResult(`${formatFormData(merged)}\n\n(resolved "${params.projekt}" -> ${resolved.id} ${resolved.label})`, {
+        profile: profileName,
+        project: resolved,
+        vorgaenge: merged.vorgaenge,
+      });
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  },
+};
+
+export function resolveProject(
+  form: { projects: ReadonlyArray<{ id: string; label: string }> },
+  reference: string,
+): { id: string; label: string } | null {
+  const needle = reference.trim().toLowerCase();
+  const byId = form.projects.find((p) => p.id === reference.trim());
+  if (byId) return byId;
+  const exact = form.projects.find((p) => p.label.toLowerCase() === needle);
+  if (exact) return exact;
+  const partial = form.projects.filter((p) => p.label.toLowerCase().includes(needle));
+  if (partial.length >= 1) return partial[0]!;
+  return null;
+}

package/src/tools/zep-setup.ts

@@ -0,0 +1,74 @@
+/**
+ * zep_setup -- store the ZEP account (userid + password + Mandant).
+ */
+
+import { Type } from "typebox";
+
+import { DEFAULT_BASE_URL, DEFAULT_MANDANT, getProfile, saveProfile, useProfile } from "../config.ts";
+import type { SetupParams, ZepAccount } from "../types.ts";
+import { errorResult, textResult, type ToolResult } from "./shared.ts";
+
+export const ZepSetupTool = {
+  name: "zep_setup",
+  label: "ZEP Setup",
+  description:
+    "Configure a ZEP (zep-online.de) account for time tracking: userid, password and Mandant. Call this before any other zep_* tool. Credentials are stored in ~/.pi/zep-config.json (file mode 0600).",
+  parameters: Type.Object({
+    name: Type.String({
+      description: "Profile name, e.g. 'work'. Use a short, memorable name.",
+    }),
+    userid: Type.String({
+      description: "ZEP user id as used in the ZEP login form, e.g. 'patrick.weppelmann'.",
+    }),
+    password: Type.String({
+      description:
+        "ZEP password. WARNING: ZEP locks the account after 5 failed login attempts, so make sure this is correct.",
+    }),
+    mandant: Type.Optional(
+      Type.String({
+        description: `Mandant / tenant path segment in the ZEP URL, e.g. '${DEFAULT_MANDANT}'. Defaults to '${DEFAULT_MANDANT}'.`,
+      }),
+    ),
+    baseUrl: Type.Optional(
+      Type.String({
+        description: `ZEP origin, defaults to '${DEFAULT_BASE_URL}'.`,
+      }),
+    ),
+  }),
+
+  async execute(_toolCallId: string, params: SetupParams): Promise<ToolResult> {
+    try {
+      const existing = (() => {
+        try {
+          return getProfile(params.name);
+        } catch {
+          return undefined;
+        }
+      })();
+
+      const account: ZepAccount = {
+        name: params.name,
+        baseUrl: (params.baseUrl ?? existing?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""),
+        mandant: (params.mandant ?? existing?.mandant ?? DEFAULT_MANDANT).replace(/^\/+|\/+$/g, ""),
+        userid: params.userid,
+        password: params.password,
+        ...(existing?.lastProjektId ? { lastProjektId: existing.lastProjektId } : {}),
+        ...(existing?.lastVorgangId ? { lastVorgangId: existing.lastVorgangId } : {}),
+        ...(existing?.lastTaetigkeit ? { lastTaetigkeit: existing.lastTaetigkeit } : {}),
+      };
+
+      saveProfile(params.name, account);
+      useProfile(params.name);
+
+      return textResult(
+        `ZEP profile "${params.name}" saved and set as active.\n` +
+          `  URL:      ${account.baseUrl}/${account.mandant}\n` +
+          `  User:     ${account.userid}\n` +
+          `\nNext: run zep_status to verify the login, then zep_week / zep_book.`,
+        { profile: params.name, mandant: account.mandant },
+      );
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  },
+};

package/src/tools/zep-status.ts

@@ -0,0 +1,103 @@
+/**
+ * zep_status -- report configuration, session state and a successful login.
+ */
+
+import { Type } from "typebox";
+
+import { configPath, getActiveProfileName, listProfiles, sessionPath } from "../config.ts";
+import { ZepClient } from "../clients/zep-client.ts";
+import { createClient, ZepError } from "../session.ts";
+import { formatFormData } from "../formatting/formatters.ts";
+import { errorResult, textResult, type ToolResult } from "./shared.ts";
+
+export const ZepStatusTool = {
+  name: "zep_status",
+  label: "ZEP Status",
+  description:
+    "Show the configured ZEP profiles and verify the live session by logging in and reading the booking form. Use the 'probe' flag to also confirm that the Projektzeiten page is reachable.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    probe: Type.Optional(
+      Type.Boolean({
+        description: "Also load the booking form (project list) to prove the session works.",
+      }),
+    ),
+    relogin: Type.Optional(
+      Type.Boolean({
+        description: "Discard any cached session and log in from scratch.",
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string; probe?: boolean; relogin?: boolean },
+  ): Promise<ToolResult> {
+    const lines: string[] = [];
+    const profiles = listProfiles();
+
+    lines.push(`Config file:  ${configPath()}`);
+    lines.push(`Session file: ${sessionPath()}`);
+    lines.push(`Profiles:     ${profiles.length ? profiles.join(", ") : "(none)"}`);
+    lines.push(`Active:       ${getActiveProfileName() ?? "(none)"}`);
+    lines.push("");
+
+    if (profiles.length === 0) {
+      lines.push("No ZEP profile configured yet. Call zep_setup with userid, password and mandant.");
+      return textResult(lines.join("\n"), { profiles: 0 });
+    }
+
+    try {
+      if (params.relogin) {
+        const { getActiveProfileName: active, getProfile, saveSession } = await import("../config.ts");
+        const name = params.profile ?? active()!;
+        const account = getProfile(name);
+        const client = new ZepClient(account, { onSession: (s) => saveSession(name, s) });
+        const result = await client.login();
+        if (!result.ok) {
+          lines.push(`Login FAILED: ${result.message}`);
+          if (result.attemptsLeft !== undefined) {
+            lines.push(`Attempts left before lockout: ${result.attemptsLeft}`);
+          }
+          return errorResult(lines.join("\n"));
+        }
+        lines.push(`Login OK (fresh). CLIENTSESSID=${result.clientsessid}`);
+        lines.push(`Request token: ${client.token ?? "(none)"}`);
+        if (params.probe) {
+          const { form } = await client.loadForm();
+          lines.push("");
+          lines.push(formatFormData(form, "Projekte"));
+        }
+        return textResult(lines.join("\n"), { ok: true, freshLogin: true });
+      }
+
+      const handle = await createClient(params.profile);
+      lines.push(`Session for "${handle.profileName}": OK (${handle.sessionSource})`);
+      lines.push(`CLIENTSESSID:  ${handle.client.sessionId}`);
+      lines.push(`Request token: ${handle.client.token ?? "(none)"}`);
+
+      if (params.probe) {
+        const { form } = await handle.client.loadForm();
+        lines.push("");
+        lines.push(formatFormData(form, "Projekte"));
+      } else {
+        const alive = await handle.client.probe();
+        lines.push(`Week read:    ${alive ? "OK" : "FAILED"}`);
+      }
+
+      return textResult(lines.join("\n"), {
+        ok: true,
+        sessionSource: handle.sessionSource,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (error instanceof ZepError && error.attemptsLeft !== undefined) {
+        lines.push(`Attempts left before lockout: ${error.attemptsLeft}`);
+      }
+      lines.push(message);
+      return errorResult(lines.join("\n"));
+    }
+  },
+};

package/src/tools/zep-week.ts

@@ -0,0 +1,45 @@
+/**
+ * zep_week -- read the Projektzeiten week overview.
+ */
+
+import { Type } from "typebox";
+
+import { createClient } from "../session.ts";
+import { formatWeek } from "../formatting/formatters.ts";
+import { errorResult, textResult, toIsoDate, type ToolResult } from "./shared.ts";
+
+export const ZepWeekTool = {
+  name: "zep_week",
+  label: "ZEP Week",
+  description:
+    "Show the ZEP Projektzeiten week overview: per day the bookings with id, times, duration, project, Vorgang, Tätigkeit and comment, plus the daily sum and whether the day is under-booked. Read-only.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    date: Type.Optional(
+      Type.String({
+        description:
+          "Any date inside the wanted ISO week (YYYY-MM-DD or DD.MM.YYYY). Defaults to the current week.",
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string; date?: string },
+  ): Promise<ToolResult> {
+    try {
+      const iso = toIsoDate(params.date);
+      const { client, profileName } = await createClient(params.profile);
+      const week = await client.week(iso);
+      return textResult(formatWeek(week), {
+        profile: profileName,
+        kwDate: week.kwDate,
+        days: week.days.length,
+      });
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  },
+};

package/src/types.ts

@@ -0,0 +1,151 @@
+/**
+ * Data types for the pi ZEP extension.
+ *
+ * Everything here is a plain immutable-shaped interface: no behaviour,
+ * no classes. I/O lives in clients/, formatting in formatting/.
+ */
+
+// ---------------------------------------------------------------- configuration
+
+/**
+ * One ZEP account/mandant ("Mandant" = the tenant path segment, e.g. `zepneoimpulse`).
+ */
+export interface ZepAccount {
+  readonly name: string;
+  /** Origin of the ZEP installation, e.g. `https://zep-online.de`. */
+  readonly baseUrl: string;
+  /** Mandant / client path segment, e.g. `zepneoimpulse`. */
+  readonly mandant: string;
+  /** ZEP user id as used on the login form, e.g. `patrick.weppelmann`. */
+  readonly userid: string;
+  readonly password: string;
+  /** Last used booking selection, so repeat bookings need fewer parameters. */
+  readonly lastProjektId?: string;
+  readonly lastVorgangId?: string;
+  readonly lastTaetigkeit?: string;
+}
+
+export interface ZepConfigFile {
+  readonly profiles: Record<string, ZepAccount>;
+  readonly activeProfile: string | null;
+}
+
+/**
+ * Cached server-side session. ZEP binds a session to `CLIENTSESSID`
+ * (URL parameter) plus a `PHPSESSID` cookie - both are needed.
+ */
+export interface ZepSession {
+  readonly clientsessid: string;
+  /** CSRF-ish token; rotates on every server response. */
+  readonly requesttoken: string | null;
+  readonly cookies: Record<string, string>;
+  readonly savedAt: string;
+}
+
+/** Result of a login attempt. */
+export interface LoginResult {
+  readonly ok: boolean;
+  readonly clientsessid?: string;
+  readonly message?: string;
+  /** Remaining password attempts before ZEP locks the account. */
+  readonly attemptsLeft?: number;
+}
+
+// ---------------------------------------------------------------- domain
+
+export interface ZepOption {
+  readonly id: string;
+  readonly label: string;
+  readonly selected?: boolean;
+  readonly disabled?: boolean;
+}
+
+export interface ZepFormData {
+  /** Project options from the booking form (#projektId). */
+  readonly projects: ReadonlyArray<ZepOption>;
+  /** Vorgang (sub-project / work package) options for the currently selected project. */
+  readonly vorgaenge: ReadonlyArray<ZepOption>;
+  /** Activity options (#taetigkeit). */
+  readonly taetigkeiten: ReadonlyArray<ZepOption>;
+  /** Location options (#ort). */
+  readonly orte: ReadonlyArray<ZepOption>;
+  /** Currently selected ids. */
+  readonly selected: {
+    readonly projektId: string | null;
+    readonly vorgangId: string | null;
+    readonly taetigkeit: string | null;
+    readonly ort: string | null;
+  };
+}
+
+/** One row of the week overview table. */
+export interface ZepBooking {
+  /** Server-side id, needed to edit/delete the row. */
+  readonly objectId: string | null;
+  /** e.g. `Do 17.09.` */
+  readonly dayLabel: string;
+  /** ISO date when known, e.g. `2026-09-17`. */
+  readonly date: string | null;
+  readonly from: string;
+  readonly to: string;
+  readonly duration: string;
+  readonly project: string;
+  readonly vorgang: string;
+  readonly taetigkeit: string;
+  readonly billable: boolean;
+  readonly comment: string;
+}
+
+export interface ZepWeekDay {
+  readonly dayLabel: string;
+  readonly date: string | null;
+  readonly bookings: ReadonlyArray<ZepBooking>;
+  /** Sum line: total duration, e.g. `8,00`. */
+  readonly total: string | null;
+  /** `payments x,00` marker when the day is billable. */
+  readonly billableTotal: string | null;
+  /** True when the day has no booking at all and no target hours. */
+  readonly empty: boolean;
+  /** True when the day is under-booked (`pzminuszeit`). */
+  readonly underBooked: boolean;
+  /** True when the day lies in the future. */
+  readonly future: boolean;
+  /** True for today. */
+  readonly today: boolean;
+}
+
+export interface ZepWeek {
+  /** Monday of the shown week, ISO date. */
+  readonly kwDate: string;
+  readonly days: ReadonlyArray<ZepWeekDay>;
+}
+
+/** A booking request to send to ZEP. */
+export interface ZepBookingRequest {
+  readonly date: string;
+  readonly from: string;
+  readonly to: string;
+  readonly duration: string;
+  readonly projektId: string;
+  readonly vorgangId: string;
+  readonly taetigkeit: string;
+  readonly comment: string;
+  readonly ort?: string;
+}
+
+export interface ZepSaveResult {
+  readonly ok: boolean;
+  /** Server error text, e.g. the "Plan Stunden überschritten" notice. */
+  readonly error?: string;
+  readonly message?: string;
+}
+
+// ---------------------------------------------------------------- tool params
+
+export interface SetupParams {
+  name: string;
+  userid: string;
+  password: string;
+  mandant?: string;
+  baseUrl?: string;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": false,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true
+  },
+  "include": ["index.ts", "src/**/*.ts", "tests/**/*.ts", "scripts/**/*.ts", "sentinel.config.ts"]
+}