@patimweb/pi-zep 1.0.0

package/src/session.ts

@@ -0,0 +1,86 @@
+/**
+ * Wiring between stored configuration and a live ZepClient.
+ *
+ * A cached session is tried first and verified with a cheap read. Only when
+ * that fails do we log in again - important because ZEP locks an account
+ * after 5 failed password attempts.
+ */
+
+import { clearSession, getActiveProfileName, getProfile, getSession, saveSession } from "./config.ts";
+import { ZepClient, ZepError } from "./clients/zep-client.ts";
+
+export interface ClientHandle {
+  readonly client: ZepClient;
+  readonly profileName: string;
+  /** How the current session was obtained. */
+  readonly sessionSource: "cache" | "fresh";
+}
+
+export async function createClient(profileName?: string): Promise<ClientHandle> {
+  const name = profileName ?? getActiveProfileName();
+  if (!name) {
+    throw new ZepError("No ZEP profile configured. Call zep_setup first.");
+  }
+  const account = getProfile(name);
+
+  let source: "cache" | "fresh" = "cache";
+  const client = new ZepClient(account, {
+    onSession: (session) => saveSession(name, session),
+  });
+
+  const cached = getSession(name);
+  if (cached) {
+    client.applySession(cached);
+    try {
+      const alive = await client.probe();
+      if (alive) {
+        return { client, profileName: name, sessionSource: "cache" };
+      }
+    } catch {
+      // fall through to a fresh login
+    }
+    clearSession(name);
+  }
+
+  source = "fresh";
+  const result = await client.login();
+  if (!result.ok) {
+    throw new ZepError(
+      `${result.message ?? "Login failed"}${
+        result.attemptsLeft !== undefined
+          ? ` - ${result.attemptsLeft} password attempt(s) left before ZEP locks the account`
+          : ""
+      }`,
+      result.attemptsLeft,
+    );
+  }
+  return { client, profileName: name, sessionSource: source };
+}
+
+/**
+ * Force a fresh login for a profile, discarding any cached session.
+ * Used by zep_login force=true.
+ */
+export async function loginProfile(profileName: string): Promise<ZepClient> {
+  const account = getProfile(profileName);
+  clearSession(profileName);
+
+  const client = new ZepClient(account, {
+    onSession: (session) => saveSession(profileName, session),
+  });
+
+  const result = await client.login();
+  if (!result.ok) {
+    throw new ZepError(
+      `${result.message ?? "Login failed"}${
+        result.attemptsLeft !== undefined
+          ? ` - ${result.attemptsLeft} password attempt(s) left before ZEP locks the account`
+          : ""
+      }`,
+      result.attemptsLeft,
+    );
+  }
+  return client;
+}
+
+export { ZepError };

package/src/tools/shared.ts

@@ -0,0 +1,44 @@
+/**
+ * Small helpers shared by the ZEP tools.
+ */
+
+export interface ToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+}
+
+export function textResult(text: string, details: Record<string, unknown> = {}): ToolResult {
+  return { content: [{ type: "text", text }], details };
+}
+
+export function errorResult(text: string, details: Record<string, unknown> = {}): ToolResult {
+  return { content: [{ type: "text", text: `Error: ${text}` }], details: { ...details, error: true } };
+}
+
+/** Normalise ISO-ish date input; falls back to today. */
+export function toIsoDate(value: string | undefined): string {
+  if (!value) return new Date().toISOString().slice(0, 10);
+  const trimmed = value.trim();
+  const direct = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+  if (direct) return trimmed;
+  const german = /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/.exec(trimmed);
+  if (german) {
+    const [, d, m, y] = german;
+    return `${y}-${m!.padStart(2, "0")}-${d!.padStart(2, "0")}`;
+  }
+  const parsed = new Date(trimmed);
+  if (!Number.isNaN(parsed.getTime())) return parsed.toISOString().slice(0, 10);
+  throw new Error(`Unparseable date: "${value}" (use YYYY-MM-DD)`);
+}
+
+/** Accept `8:00`, `08:00`, `0800`; return `HH:MM`. */
+export function toHhMm(value: string): string {
+  const trimmed = value.trim();
+  const colon = /^(\d{1,2}):(\d{2})$/.exec(trimmed);
+  if (colon) return `${colon[1]!.padStart(2, "0")}:${colon[2]}`;
+  const compact = /^(\d{2})(\d{2})$/.exec(trimmed);
+  if (compact) return `${compact[1]}:${compact[2]}`;
+  const hourOnly = /^(\d{1,2})$/.exec(trimmed);
+  if (hourOnly) return `${hourOnly[1]!.padStart(2, "0")}:00`;
+  throw new Error(`Unparseable time: "${value}" (use HH:MM)`);
+}

package/src/tools/zep-book.ts

@@ -0,0 +1,323 @@
+/**
+ * zep_book -- create Projektzeit bookings.
+ *
+ * This is the replacement for the paid ZEP API: the same HTTP call the web
+ * form makes, minus the browser.
+ */
+
+import { Type } from "typebox";
+
+import { createClient } from "../session.ts";
+import { durationBetween } from "../clients/zep-parse.ts";
+import { ZepError } from "../clients/zep-client.ts";
+import { updateProfile } from "../config.ts";
+import type { ZepBookingRequest, ZepFormData, ZepOption } from "../types.ts";
+import { errorResult, textResult, toHhMm, toIsoDate, type ToolResult } from "./shared.ts";
+
+interface EntryParam {
+  von: string;
+  bis: string;
+  bemerkung?: string;
+  datum?: string;
+  projekt?: string;
+  vorgang?: string;
+  taetigkeit?: string;
+  ort?: string;
+}
+
+interface BookParams {
+  profile?: string;
+  datum?: string;
+  von?: string;
+  bis?: string;
+  bemerkung?: string;
+  projekt?: string;
+  vorgang?: string;
+  taetigkeit?: string;
+  ort?: string;
+  entries?: EntryParam[];
+  dryRun?: boolean;
+}
+
+/** A project plus the Vorgang/Tätigkeit options ZEP offers for it. */
+interface ProjectScope {
+  readonly project: ZepOption | undefined;
+  readonly vorgaenge: ReadonlyArray<ZepOption>;
+  readonly taetigkeiten: ReadonlyArray<ZepOption>;
+  readonly selectedVorgangId: string | null;
+}
+
+export const ZepBookTool = {
+  name: "zep_book",
+  label: "ZEP Book",
+  description:
+    "Book time in ZEP (Projektzeiten) over plain HTTP. Give a day with 'datum' (default today) and either one von/bis pair or an 'entries' array for several blocks. Project and Vorgang accept an id or part of the label. Use dryRun to see the exact request without saving. ZEP rejects a booking that would exceed the Vorgang's planned hours; such a rejection is reported, never retried silently.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    datum: Type.Optional(
+      Type.String({ description: "Day to book (YYYY-MM-DD or DD.MM.YYYY). Defaults to today." }),
+    ),
+    von: Type.Optional(Type.String({ description: "Start time, e.g. '08:00'." })),
+    bis: Type.Optional(Type.String({ description: "End time, e.g. '12:00'." })),
+    bemerkung: Type.Optional(
+      Type.String({
+        description:
+          "Comment. Convention: include the ticket/story numbers (e.g. '3447 Ladeanzeige nach Pick, 3455 Fach-HU-Nummer').",
+      }),
+    ),
+    projekt: Type.Optional(
+      Type.String({
+        description:
+          "Project id (e.g. '413' for Julabo) or part of its label (e.g. 'Julabo'). Falls back to the project ZEP has selected for this user.",
+      }),
+    ),
+    vorgang: Type.Optional(
+      Type.String({
+        description:
+          "Vorgang id (e.g. '3284') or part of its label (e.g. '90-01'). Falls back to the Vorgang ZEP has selected for this user.",
+      }),
+    ),
+    taetigkeit: Type.Optional(
+      Type.String({
+        description: "Activity code, usually 'co' (Consulting), 'co_nb' (non-billable) or 're' (Reisen). Defaults to the last used one.",
+      }),
+    ),
+    ort: Type.Optional(
+      Type.String({ description: "Location code, e.g. 'D-Office' or 'D'. Defaults to 'NULL' (first place of work)." }),
+    ),
+    entries: Type.Optional(
+      Type.Array(
+        Type.Object({
+          von: Type.String({ description: "Start time, e.g. '13:00'." }),
+          bis: Type.String({ description: "End time, e.g. '17:00'." }),
+          bemerkung: Type.Optional(Type.String({ description: "Comment for this block." })),
+          datum: Type.Optional(Type.String({ description: "Overrides the top-level datum." })),
+          projekt: Type.Optional(Type.String({ description: "Overrides the top-level projekt." })),
+          vorgang: Type.Optional(Type.String({ description: "Overrides the top-level vorgang." })),
+          taetigkeit: Type.Optional(Type.String({ description: "Overrides the top-level taetigkeit." })),
+          ort: Type.Optional(Type.String({ description: "Overrides the top-level ort." })),
+        }),
+        { description: "Several blocks in one call, e.g. 08:00-12:00 and 13:00-17:00." },
+      ),
+    ),
+    dryRun: Type.Optional(
+      Type.Boolean({
+        description: "Resolve everything and show exactly what would be sent, without saving.",
+      }),
+    ),
+  }),
+
+  async execute(_toolCallId: string, params: BookParams): Promise<ToolResult> {
+    try {
+      if (!params.entries?.length && (!params.von || !params.bis)) {
+        return errorResult("Give 'von' and 'bis', or an 'entries' array.");
+      }
+
+      const handle = await createClient(params.profile);
+      const { client, profileName } = handle;
+      const { form } = await client.loadForm();
+
+      const entries: EntryParam[] = params.entries?.length
+        ? params.entries
+        : [{ von: params.von!, bis: params.bis!, bemerkung: params.bemerkung }];
+
+      // Which projects does this call touch?
+      const wantedRefs = new Set<string>();
+      for (const entry of entries) {
+        const ref = entry.projekt ?? params.projekt;
+        if (ref) wantedRefs.add(ref.trim());
+      }
+
+      const scopes = new Map<string, ProjectScope>();
+      const baseProjectId = form.selected.projektId;
+
+      const scopeFor = async (projectId: string, current: ZepFormData): Promise<ProjectScope> => {
+        const cached = scopes.get(projectId);
+        if (cached) return cached;
+
+        // The page only renders Vorgänge for the project it was rendered for.
+        let scopeForm = current;
+        if (projectId !== current.selected.projektId) {
+          const refreshed = await client.refreshFormForProject(projectId);
+          if (refreshed.vorgaenge.length) {
+            scopeForm = {
+              ...current,
+              vorgaenge: refreshed.vorgaenge,
+              taetigkeiten: refreshed.taetigkeiten.length ? refreshed.taetigkeiten : current.taetigkeiten,
+              selected: { ...current.selected, projektId: projectId },
+            };
+          }
+        }
+
+        const scope: ProjectScope = {
+          project: current.projects.find((p) => p.id === projectId),
+          vorgaenge: scopeForm.vorgaenge,
+          taetigkeiten: scopeForm.taetigkeiten,
+          selectedVorgangId:
+            scopeForm.selected.projektId === projectId ? scopeForm.selected.vorgangId : null,
+        };
+        scopes.set(projectId, scope);
+        return scope;
+      };
+
+      // Resolve every project reference up front so all Vorgang lists are known.
+      for (const ref of wantedRefs) {
+        const resolved = matchOption(form.projects, ref);
+        if (!resolved) {
+          return errorResult(
+            `No project matches "${ref}". Known projects: ${form.projects
+              .map((p) => `${p.id}=${p.label}`)
+              .join(" | ")}`,
+          );
+        }
+        await scopeFor(resolved.id, form);
+      }
+
+      if (baseProjectId && !scopes.has(baseProjectId)) {
+        scopes.set(baseProjectId, {
+          project: form.projects.find((p) => p.id === baseProjectId),
+          vorgaenge: form.vorgaenge,
+          taetigkeiten: form.taetigkeiten,
+          selectedVorgangId: form.selected.vorgangId,
+        });
+      }
+
+      // ------------------------------------------------------------ build plan
+      const planned: Array<{ request: ZepBookingRequest; label: string }> = [];
+
+      for (const entry of entries) {
+        const date = toIsoDate(entry.datum ?? params.datum);
+        const from = toHhMm(entry.von);
+        const to = toHhMm(entry.bis);
+        const duration = durationBetween(from, to);
+        if (!duration) {
+          return errorResult(`Invalid time range ${from}-${to} on ${date}: end must be after start.`);
+        }
+
+        const projektRef = entry.projekt ?? params.projekt;
+        const projectId = projektRef
+          ? matchOption(form.projects, projektRef)?.id
+          : form.selected.projektId;
+
+        if (!projectId) {
+          return errorResult(
+            "No project determined. Pass 'projekt' (id or label), or book once manually so ZEP preselects one.",
+          );
+        }
+
+        const scope = scopes.get(projectId) ?? (await scopeFor(projectId, form));
+
+        const vorgangRef = entry.vorgang ?? params.vorgang;
+        const vorgangId =
+          (vorgangRef ? matchOption(scope.vorgaenge, vorgangRef)?.id : undefined) ??
+          scope.selectedVorgangId ??
+          (scope.vorgaenge.length === 1 ? scope.vorgaenge[0]!.id : undefined);
+
+        if (!vorgangId) {
+          return errorResult(
+            `No Vorgang determined for project ${projectId}. Available: ${scope.vorgaenge
+              .map((v) => `${v.id}=${v.label}`)
+              .join(" | ") || "(none readable)"}`,
+          );
+        }
+
+        const taetigkeit = resolveTaetigkeit(scope, entry.taetigkeit ?? params.taetigkeit);
+        const ort = entry.ort ?? params.ort ?? "NULL";
+        const comment = entry.bemerkung ?? params.bemerkung ?? "";
+
+        const vorgangLabel = scope.vorgaenge.find((v) => v.id === vorgangId)?.label;
+
+        planned.push({
+          request: {
+            date,
+            from,
+            to,
+            duration,
+            projektId: projectId,
+            vorgangId,
+            taetigkeit,
+            comment,
+            ort,
+          },
+          label:
+            `${date}  ${from}-${to}  (${duration})\n` +
+            `         project ${projectId}${scope.project ? ` "${scope.project.label}"` : ""}\n` +
+            `         Vorgang ${vorgangId}${vorgangLabel ? ` "${vorgangLabel}"` : ""}\n` +
+            `         Tätigkeit ${taetigkeit}${ort === "NULL" ? "" : `, Ort ${ort}`}` +
+            `${comment ? `\n         "${comment}"` : ""}`,
+        });
+      }
+
+      if (params.dryRun) {
+        return textResult(
+          `DRY RUN - nothing saved (session: ${handle.sessionSource}).\n\n${planned
+            .map((p) => p.label)
+            .join("\n\n")}`,
+          { dryRun: true, planned: planned.map((p) => p.request) },
+        );
+      }
+
+      // ---------------------------------------------------------------- execute
+      const results: string[] = [];
+      let failures = 0;
+      let firstFailure: string | null = null;
+
+      for (const item of planned) {
+        const result = await client.book(item.request);
+        if (result.ok) {
+          results.push(`OK       ${item.request.date} ${item.request.from}-${item.request.to}`);
+        } else {
+          failures += 1;
+          firstFailure ??= result.error ?? "unknown error";
+          results.push(
+            `REJECTED ${item.request.date} ${item.request.from}-${item.request.to}\n         ${result.error ?? "unknown error"}`,
+          );
+        }
+      }
+
+      if (failures === 0) {
+        updateProfile(profileName, {
+          lastProjektId: planned[0]!.request.projektId,
+          lastVorgangId: planned[0]!.request.vorgangId,
+          lastTaetigkeit: planned[0]!.request.taetigkeit,
+        });
+      }
+
+      const summary =
+        `${planned.length - failures}/${planned.length} booking(s) saved.` +
+        (failures ? `\nFirst error: ${firstFailure}` : "");
+
+      const text = `${summary}\n\n${results.join("\n")}`;
+      return failures ? errorResult(text, { failures }) : textResult(text, { saved: planned.length });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (error instanceof ZepError && error.attemptsLeft !== undefined) {
+        return errorResult(`${message} (${error.attemptsLeft} password attempts left)`);
+      }
+      return errorResult(message);
+    }
+  },
+};
+
+/** Match an id exactly first, then an exact label, then a label substring. */
+function matchOption(
+  options: ReadonlyArray<{ id: string; label: string }>,
+  reference: string,
+): { id: string; label: string } | undefined {
+  const needle = reference.trim().toLowerCase();
+  return (
+    options.find((o) => o.id === reference.trim()) ??
+    options.find((o) => o.label.toLowerCase() === needle) ??
+    options.find((o) => o.label.toLowerCase().includes(needle))
+  );
+}
+
+function resolveTaetigkeit(scope: ProjectScope, reference: string | undefined): string {
+  if (reference) {
+    const match = matchOption(scope.taetigkeiten, reference);
+    if (match) return match.id;
+  }
+  return scope.taetigkeiten.find((t) => t.selected)?.id ?? scope.taetigkeiten[0]?.id ?? "co";
+}

package/src/tools/zep-delete.ts

@@ -0,0 +1,42 @@
+/**
+ * zep_delete -- remove a Projektzeit booking by its row id.
+ */
+
+import { Type } from "typebox";
+
+import { createClient } from "../session.ts";
+import { mondayOf } from "../clients/zep-parse.ts";
+import { errorResult, textResult, toIsoDate, type ToolResult } from "./shared.ts";
+
+export const ZepDeleteTool = {
+  name: "zep_delete",
+  label: "ZEP Delete",
+  description:
+    "Delete a ZEP Projektzeit booking. Get the row id from zep_week (shown as #<id>). Prefer passing 'datum' so ZEP re-renders the right week.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    objectId: Type.String({ description: "Booking row id from zep_week, e.g. '163533'." }),
+    datum: Type.Optional(
+      Type.String({ description: "Day the booking sits on (YYYY-MM-DD). Defaults to today." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string; objectId: string; datum?: string },
+  ): Promise<ToolResult> {
+    try {
+      const iso = toIsoDate(params.datum);
+      const kwDate = mondayOf(new Date(`${iso}T12:00:00Z`));
+      const { client, profileName } = await createClient(params.profile);
+      const result = await client.remove(params.objectId, kwDate);
+      return result.ok
+        ? textResult(`Booking #${params.objectId} deleted.`, { profile: profileName, objectId: params.objectId })
+        : errorResult(`Delete of #${params.objectId} failed: ${result.error ?? "unknown error"}`);
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  },
+};

package/src/tools/zep-login.ts

@@ -0,0 +1,75 @@
+/**
+ * zep_login -- establish a ZEP session.
+ *
+ * ZEP does not offer a token exchange: a session is a `PHPSESSID` cookie
+ * bound 1:1 to a `CLIENTSESSID` query parameter, and both are only issued by
+ * the login POST. That is why this tool exists separately from zep_setup:
+ * zep_setup stores the credentials, zep_login proves they work and caches the
+ * resulting session.
+ */
+
+import { Type } from "typebox";
+
+import { getActiveProfileName, getProfile } from "../config.ts";
+import { createClient, loginProfile } from "../session.ts";
+import { errorResult, textResult, type ToolResult } from "./shared.ts";
+
+export const ZepLoginTool = {
+  name: "zep_login",
+  label: "ZEP Login",
+  description:
+    "Log in to ZEP with the stored credentials and cache the session in ~/.pi/zep-session.json. Use force to ignore a cached session. Reports the remaining password attempts when the login fails (ZEP locks the account after 5).",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to use. Defaults to the active profile." }),
+    ),
+    force: Type.Optional(
+      Type.Boolean({
+        description: "Ignore a cached session and log in from scratch.",
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string; force?: boolean },
+  ): Promise<ToolResult> {
+    try {
+      const name = params.profile ?? getActiveProfileName();
+      if (!name) return errorResult("No ZEP profile configured. Call zep_setup first.");
+      const account = getProfile(name);
+
+      if (!params.force) {
+        const handle = await createClient(params.profile);
+        if (handle.sessionSource === "cache") {
+          return textResult(
+            `Cached session for "${name}" is still valid - no login needed.\n` +
+              `CLIENTSESSID:  ${handle.client.sessionId}\n` +
+              `Request token: ${handle.client.token}\n` +
+              `(use force=true to log in again)`,
+            { profile: name, sessionSource: "cache" },
+          );
+        }
+        return textResult(
+          `Logged in to ZEP as "${account.userid}" (profile "${name}").\n` +
+            `URL:           ${account.baseUrl}/${account.mandant}\n` +
+            `CLIENTSESSID:  ${handle.client.sessionId}\n` +
+            `Request token: ${handle.client.token}`,
+          { profile: name, clientsessid: handle.client.sessionId, sessionSource: "fresh" },
+        );
+      }
+
+      const client = await loginProfile(name);
+      return textResult(
+        `Logged in to ZEP as "${account.userid}" (profile "${name}").\n` +
+          `URL:           ${account.baseUrl}/${account.mandant}\n` +
+          `CLIENTSESSID:  ${client.sessionId}\n` +
+          `Request token: ${client.token}`,
+        { profile: name, clientsessid: client.sessionId, sessionSource: "fresh" },
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return errorResult(message);
+    }
+  },
+};

package/src/tools/zep-profile.ts

@@ -0,0 +1,73 @@
+/**
+ * zep_profile -- list, switch or delete ZEP profiles.
+ */
+
+import { Type } from "typebox";
+
+import {
+  clearSession,
+  deleteProfile,
+  getActiveProfileName,
+  listProfiles,
+  useProfile,
+} from "../config.ts";
+import { errorResult, textResult, type ToolResult } from "./shared.ts";
+
+export const ZepProfileTool = {
+  name: "zep_profile",
+  label: "ZEP Profile",
+  description:
+    "List configured ZEP profiles, switch the active one, or delete a profile. Without arguments it lists all profiles.",
+  parameters: Type.Object({
+    action: Type.Optional(
+      Type.String({ description: "One of: list, use, delete. Defaults to list." }),
+    ),
+    name: Type.Optional(
+      Type.String({ description: "Profile name for 'use' and 'delete'." }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { action?: string; name?: string },
+  ): Promise<ToolResult> {
+    const action = params.action ?? "list";
+    try {
+      if (action === "list") {
+        const profiles = listProfiles();
+        if (profiles.length === 0) {
+          return textResult("No ZEP profiles configured. Call zep_setup first.", { profiles: [] });
+        }
+        const active = getActiveProfileName();
+        const lines = profiles.map((p) => `${p === active ? "*" : " "} ${p}`).join("\n");
+        return textResult(`ZEP profiles (${profiles.length})\n${lines}`, { profiles, active });
+      }
+
+      if (!params.name) return errorResult(`Action "${action}" needs a profile name.`);
+
+      if (action === "use") {
+        useProfile(params.name);
+        return textResult(`Active ZEP profile is now "${params.name}".`, { active: params.name });
+      }
+
+      if (action === "delete") {
+        deleteProfile(params.name);
+        return textResult(
+          `ZEP profile "${params.name}" deleted (including its cached session).`,
+          { deleted: params.name },
+        );
+      }
+
+      if (action === "clear-session") {
+        clearSession(params.name);
+        return textResult(`Cached ZEP session for "${params.name}" cleared.`, {
+          cleared: params.name,
+        });
+      }
+
+      return errorResult(`Unknown action "${action}". Use list, use, delete or clear-session.`);
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  },
+};