@etazio/agent-sdk 0.1.0

package/types/shared/avatar.d.ts

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+/**
+ * Avatar-Profil (Phase 4, Roadmap §6 Charakter-Editor / §8 AvatarProfile). Ein Profil je Nutzer,
+ * gilt in allen Workspaces. Alle Varianten sitzen auf dem gemeinsamen Rig `avatar_base` (v2) und
+ * sind als eigene Meshes `part_<gruppe>_<variante>` in derselben GLB enthalten – der Client blendet
+ * sie ein/aus, Farben gehen über die freigegebenen Material-Slots. Kuratiert, damit nichts clippt
+ * (Roadmap §12): freie Mesh-Uploads und Morphs kommen erst nach dem stabilen Avatar-System.
+ */
+export declare const AVATAR_RIG_VERSION = 2;
+export declare const AVATAR_BODIES: readonly ['slim', 'standard', 'broad'];
+export declare const AVATAR_HEIGHTS: readonly ['short', 'medium', 'tall'];
+export declare const AVATAR_HAIRS: readonly ['none', 'short', 'long', 'bun'];
+export declare const AVATAR_TOPS: readonly ['tshirt', 'longsleeve', 'hoodie'];
+export declare const AVATAR_ACCESSORIES: readonly ['glasses', 'headphones', 'cap'];
+export declare const AVATAR_COLOR_SLOTS: readonly ['skin', 'hair', 'shirt', 'pants', 'shoes', 'accent'];
+export type AvatarBody = (typeof AVATAR_BODIES)[number];
+export type AvatarHeight = (typeof AVATAR_HEIGHTS)[number];
+export type AvatarHair = (typeof AVATAR_HAIRS)[number];
+export type AvatarTop = (typeof AVATAR_TOPS)[number];
+export type AvatarAccessory = (typeof AVATAR_ACCESSORIES)[number];
+export type AvatarColorSlot = (typeof AVATAR_COLOR_SLOTS)[number];
+export declare const avatarProfileSchema: z.ZodPipe<z.ZodObject<{
+    rigVersion: z.ZodDefault<z.ZodLiteral<2>>;
+    body: z.ZodDefault<z.ZodEnum<{
+        broad: "broad";
+        slim: "slim";
+        standard: "standard";
+    }>>;
+    height: z.ZodDefault<z.ZodEnum<{
+        medium: "medium";
+        short: "short";
+        tall: "tall";
+    }>>;
+    hair: z.ZodDefault<z.ZodEnum<{
+        bun: "bun";
+        long: "long";
+        none: "none";
+        short: "short";
+    }>>;
+    top: z.ZodDefault<z.ZodEnum<{
+        hoodie: "hoodie";
+        longsleeve: "longsleeve";
+        tshirt: "tshirt";
+    }>>;
+    accessories: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        cap: "cap";
+        glasses: "glasses";
+        headphones: "headphones";
+    }>>>;
+    colors: z.ZodPrefault<z.ZodObject<{
+        skin: z.ZodDefault<z.ZodString>;
+        hair: z.ZodDefault<z.ZodString>;
+        shirt: z.ZodDefault<z.ZodString>;
+        pants: z.ZodDefault<z.ZodString>;
+        shoes: z.ZodDefault<z.ZodString>;
+        accent: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodTransform<{
+    rigVersion: 2;
+    body: "broad" | "slim" | "standard";
+    height: "medium" | "short" | "tall";
+    hair: "bun" | "long" | "none" | "short";
+    top: "hoodie" | "longsleeve" | "tshirt";
+    colors: {
+        skin: string;
+        hair: string;
+        shirt: string;
+        pants: string;
+        shoes: string;
+        accent: string;
+    };
+    accessories: ("cap" | "glasses" | "headphones")[];
+}, {
+    rigVersion: 2;
+    body: "broad" | "slim" | "standard";
+    height: "medium" | "short" | "tall";
+    hair: "bun" | "long" | "none" | "short";
+    top: "hoodie" | "longsleeve" | "tshirt";
+    accessories: ("cap" | "glasses" | "headphones")[];
+    colors: {
+        skin: string;
+        hair: string;
+        shirt: string;
+        pants: string;
+        shoes: string;
+        accent: string;
+    };
+}>>;
+export type AvatarProfile = z.output<typeof avatarProfileSchema>;
+export type AvatarProfileInput = z.input<typeof avatarProfileSchema>;
+export declare function defaultAvatarProfile(): AvatarProfile;
+/** Kuratierte Hauttöne (Roadmap §6); weitere Farben sind erlaubt, die UI bietet diese an. */
+export declare const SKIN_TONES: readonly ['#f5dcc4', '#deae8c', '#c98f6a', '#a86d4b', '#7d4a2e', '#4f2e1c'];
+export declare const HAIR_COLORS: readonly ['#1a1412', '#402b1f', '#7a4a2a', '#b8793a', '#d9b37a', '#8c8c8c', '#c94f3d', '#5a3f8c'];
+export declare const CLOTH_COLORS: readonly ['#386b9e', '#2f7a5a', '#b04a3c', '#d97340', '#6a5acd', '#333642', '#8a8f99', '#e8e2d5', '#1f1f21', '#f0c46a'];
+/** Sichtbare Varianten-Teile der GLB für ein Profil (Namen aus assets/blender/scripts/build_avatar.py). */
+export declare function avatarPartsFor(profile: AvatarProfile): string[];
+/** Skalierung des Avatars (Körperbau × Größe); Kopf und Anker bleiben proportional. */
+export declare function avatarScaleFor(profile: AvatarProfile): [number, number, number];
+/** Material-Slot der GLB je Farbslot des Profils. */
+export declare const AVATAR_SLOT_MATERIALS: Record<AvatarColorSlot, string>;
+export declare const AVATAR_LABELS: {
+    readonly body: {
+        readonly slim: 'Schlank';
+        readonly standard: 'Normal';
+        readonly broad: 'Kräftig';
+    };
+    readonly height: {
+        readonly short: 'Klein';
+        readonly medium: 'Mittel';
+        readonly tall: 'Groß';
+    };
+    readonly hair: {
+        readonly none: 'Ohne';
+        readonly short: 'Kurz';
+        readonly long: 'Lang';
+        readonly bun: 'Dutt';
+    };
+    readonly top: {
+        readonly tshirt: 'T-Shirt';
+        readonly longsleeve: 'Langarm';
+        readonly hoodie: 'Hoodie';
+    };
+    readonly accessories: {
+        readonly glasses: 'Brille';
+        readonly headphones: 'Kopfhörer';
+        readonly cap: 'Kappe';
+    };
+    readonly colors: {
+        readonly skin: 'Haut';
+        readonly hair: 'Haare';
+        readonly shirt: 'Oberteil';
+        readonly pants: 'Hose';
+        readonly shoes: 'Schuhe';
+        readonly accent: 'Accessoires';
+    };
+};

package/types/shared/board.d.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod';
+/**
+ * Whiteboard (Phase 7b): Operationen auf einem gemeinsamen Board. Koordinaten sind auf 0–1 normiert
+ * (u = links→rechts, v = oben→unten), damit 3D-Textur und Overlay dasselbe Bild zeichnen. Striche und Notizen
+ * sind kommutativ; nur `clear` prüft die Basisversion. Der Server vergibt `version` je Operation.
+ */
+export declare const BOARD_LIMITS: {
+    /** Punkte je Strich (inkl. Verlängerungen) */
+    readonly maxPoints: 500;
+    /** Punkte je Operation (Segment beim Live-Zeichnen) */
+    readonly maxSegment: 120;
+    readonly maxText: 200;
+    /** Operationen im Log je Board; darüber verlangt der Server einen Snapshot */
+    readonly maxOps: 5000;
+    /** Nach so vielen Operationen seit dem Snapshot lädt der Client ein neues Snapshot-PNG hoch */
+    readonly snapshotEvery: 200;
+    /** Snapshot-PNG als Base64, Bytes */
+    readonly maxSnapshotBytes: 1500000;
+    /** Operationen je Teilnehmer und Sekunde */
+    readonly opsPerSecond: 30;
+    /** Zeigerpositionen je Sekunde */
+    readonly cursorHz: 10;
+};
+export declare const BOARD_COLORS: readonly ['#1c1c1e', '#2f4dff', '#12a594', '#e0871f', '#d63b3b', '#8b5cf6', '#6b7280', '#ffffff'];
+export declare const BOARD_WIDTHS: readonly [2, 4, 8];
+export declare const boardOpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"stroke">;
+    id: z.ZodString;
+    color: z.ZodString;
+    width: z.ZodNumber;
+    points: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"extend">;
+    id: z.ZodString;
+    points: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"note">;
+    id: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    text: z.ZodString;
+    color: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"move">;
+    id: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"erase">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"clear">;
+}, z.core.$strip>], "type">;
+export type BoardOp = z.infer<typeof boardOpSchema>;
+export declare const boardOpEnvelopeSchema: z.ZodObject<{
+    placementId: z.ZodString;
+    opId: z.ZodString;
+    baseVersion: z.ZodNumber;
+    op: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"stroke">;
+        id: z.ZodString;
+        color: z.ZodString;
+        width: z.ZodNumber;
+        points: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"extend">;
+        id: z.ZodString;
+        points: z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"note">;
+        id: z.ZodString;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        text: z.ZodString;
+        color: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"move">;
+        id: z.ZodString;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"erase">;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"clear">;
+    }, z.core.$strip>], "type">;
+}, z.core.$strip>;
+export type BoardOpEnvelope = z.infer<typeof boardOpEnvelopeSchema>;
+export declare const boardSyncRequestSchema: z.ZodObject<{
+    placementId: z.ZodString;
+}, z.core.$strip>;
+export declare const boardCursorSchema: z.ZodObject<{
+    placementId: z.ZodString;
+    x: z.ZodNullable<z.ZodNumber>;
+    y: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const boardSnapshotSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    png: z.ZodString;
+}, z.core.$strip>;
+/** Sichtbares Element auf dem Board (aus dem Op-Log gefaltet) */
+export type BoardItem = {
+    kind: 'stroke';
+    id: string;
+    color: string;
+    width: number;
+    points: Array<[number, number]>;
+} | {
+    kind: 'note';
+    id: string;
+    x: number;
+    y: number;
+    text: string;
+    color: string;
+};
+export interface BoardModel {
+    /** Elemente in Zeichenreihenfolge */
+    items: BoardItem[];
+    /** Version der letzten angewandten Operation */
+    version: number;
+}
+export declare function emptyBoard(): BoardModel;
+/** Wendet eine Operation auf das Modell an (in place). Unbekannte IDs werden still ignoriert (kommutativ). */
+export declare function applyBoardOp(model: BoardModel, op: BoardOp, version?: number): void;

package/types/shared/calendar.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Kalender-Tab der Office-Shell (SPA-132). MVP: Google Calendar, nur lesen, nur der eigene
+ * Hauptkalender des verbundenen Kontos. Verbindung gilt je Nutzer (nicht je Workspace).
+ */
+export declare const CALENDAR_PROVIDERS: readonly ['google'];
+export type CalendarProvider = (typeof CALENDAR_PROVIDERS)[number];
+/** Einziger Scope des MVP – Schreibzugriff kommt bewusst getrennt (Folgeticket). */
+export declare const GOOGLE_CALENDAR_SCOPE = "https://www.googleapis.com/auth/calendar.readonly";
+/**
+ * - `active`: Termine abrufbar
+ * - `expired`: Google hat das Refresh-Token nicht mehr angenommen (widerrufen, abgelaufen, Passwort geändert)
+ * - `scope_missing`: bei der Zustimmung wurde der Kalender-Haken abgewählt
+ */
+export type CalendarConnectionStatus = 'active' | 'expired' | 'scope_missing';
+export interface CalendarConnectionDto {
+    provider: CalendarProvider;
+    /** Google-Konto, dessen Kalender gelesen wird */
+    email: string | null;
+    status: CalendarConnectionStatus;
+    connectedAt: string;
+    lastError: string | null;
+}
+export interface CalendarStatusDto {
+    /** Server hat eine Google-App konfiguriert */
+    available: boolean;
+    connection: CalendarConnectionDto | null;
+    /** Anmeldung dieser Sitzung lief über Google → Konto für den Connect-Flow vorschlagen */
+    suggestedEmail: string | null;
+}
+export interface CalendarEventDto {
+    id: string;
+    title: string;
+    /** ISO-Zeitpunkt; bei ganztägigen Terminen `YYYY-MM-DD` */
+    start: string;
+    end: string;
+    allDay: boolean;
+    location: string | null;
+    /** Videokonferenz-Link (Meet o. ä.), falls vorhanden */
+    meetingUrl: string | null;
+    /** Link zum Termin in Google Calendar */
+    htmlLink: string | null;
+    /** eigene Antwort: accepted | declined | tentative | needsAction | null (eigener Termin ohne Gäste) */
+    response: 'accepted' | 'declined' | 'tentative' | 'needsAction' | null;
+    tentative: boolean;
+    attendees: number;
+}
+export interface CalendarEventsDto {
+    from: string;
+    to: string;
+    timeZone: string | null;
+    events: CalendarEventDto[];
+}
+/** Fehlercodes im `?calendar_error=` nach dem OAuth-Rückweg */
+export declare const CALENDAR_ERRORS: {
+    readonly unavailable: 'Google ist auf diesem Server nicht eingerichtet.';
+    readonly cancelled: 'Verbindung abgebrochen.';
+    readonly state: 'Der Anmeldevorgang ist abgelaufen – bitte erneut verbinden.';
+    readonly provider: 'Google hat die Verbindung abgelehnt. Bitte erneut versuchen.';
+    readonly scope_missing: 'Ohne den Haken „Kalender ansehen“ kann Etazio keine Termine zeigen.';
+    readonly no_refresh: 'Google hat keinen dauerhaften Zugriff erteilt. Bitte erneut verbinden.';
+};
+export type CalendarErrorCode = keyof typeof CALENDAR_ERRORS;
+/** Maximaler Abfragezeitraum in Tagen */
+export declare const CALENDAR_MAX_RANGE_DAYS = 42;

package/types/shared/chat.d.ts

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+/**
+ * Strukturierte Nachrichteninhalte und Emoji-Regeln für den Chat (SPA-117).
+ *
+ * Eine Nachricht bleibt in erster Linie Text – `text` ist Pflicht und trägt Suche, Vorschau und
+ * Benachrichtigung. `blocks` kommt additiv dazu: eine Karte, die man anklickt, statt einer Frage,
+ * die man abtippt. Bestandsnachrichten ohne `blocks` bleiben gültig, eine Migration braucht es nicht.
+ */
+export declare const CHAT_GLYPH_LIMITS: {
+    /** Eine Reaktion ist genau ein sichtbares Zeichen – Skin-Tone und ZWJ-Sequenz eingeschlossen */
+    readonly maxClusters: 1;
+    /** Harte Klammer über die Rohlänge: eine Familien-Sequenz mit Skin-Tones ist lang, aber nicht beliebig */
+    readonly maxChars: 80;
+};
+/**
+ * Sichtbare Zeichen einer Zeichenkette. `👩\u{1F3FD}\u{200D}🚒` ist ein Zeichen und sieben Code-Einheiten – genau
+ * dieser Unterschied hat die alte Prüfung (`length <= 8`) Reaktionen ablehnen lassen, die es gibt.
+ */
+export declare function graphemeCount(s: string): number;
+/**
+ * Nur Emoji dürfen Reaktion sein. Ohne diese Prüfung wäre die Reaktionsleiste ein zweiter, kürzerer
+ * Nachrichtenkanal – mit allem, was man dort hineinschreiben kann.
+ */
+export declare function isEmojiGlyph(s: string): boolean;
+export declare const glyphSchema: z.ZodString;
+export declare const CHAT_BLOCK_LIMITS: {
+    /** Blöcke je Nachricht */
+    readonly maxBlocks: 3;
+    readonly maxTitle: 120;
+    readonly maxDescription: 600;
+    readonly maxFields: 10;
+    readonly maxFieldLabel: 60;
+    readonly maxFieldValue: 240;
+    readonly maxActions: 4;
+    readonly maxActionLabel: 40;
+    /** Weiter als das darf ein Ablaufzeitpunkt nicht in der Zukunft liegen */
+    readonly maxTtlMs: number;
+};
+export declare const CHAT_ACTION_STYLES: readonly ['primary', 'secondary', 'danger'];
+export type ChatActionStyle = (typeof CHAT_ACTION_STYLES)[number];
+export interface ChatBlockField {
+    label: string;
+    value: string;
+}
+export interface ChatBlockAction {
+    id: string;
+    label: string;
+    style: ChatActionStyle;
+}
+/** Wer die Karte entschieden hat und wann – steht in der Karte, nicht nur im Audit-Log. */
+export interface ChatBlockDecision {
+    actionId: string;
+    actionLabel: string;
+    userId: string;
+    userName: string;
+    at: string;
+}
+/**
+ * Bestätigungs-Karte: eine Frage mit festen Antworten. Genau einmal entscheidbar; danach sehen alle
+ * denselben Endzustand.
+ */
+export interface ChatConfirmBlock {
+    type: 'confirm';
+    id: string;
+    title: string;
+    description: string | null;
+    fields: ChatBlockField[];
+    actions: ChatBlockAction[];
+    expiresAt: string | null;
+    decision: ChatBlockDecision | null;
+}
+/**
+ * Union mit genau einem Mitglied – bewusst. `fields`, `image` und `select` kommen später als
+ * eigene `type`-Zweige dazu, ohne dass der bestehende Zweig sich ändert.
+ */
+export type ChatBlock = ChatConfirmBlock;
+export declare const blockIdSchema: z.ZodString;
+export declare const actionIdSchema: z.ZodString;
+/** Eingabe des Absenders: ohne `decision` – die entsteht erst durch einen Klick auf dem Server. */
+export declare const confirmBlockInputSchema: z.ZodObject<{
+    type: z.ZodLiteral<"confirm">;
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+    actions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        style: z.ZodDefault<z.ZodEnum<{
+            danger: "danger";
+            primary: "primary";
+            secondary: "secondary";
+        }>>;
+    }, z.core.$strip>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** Eingabe einer Bestätigungs-Karte ohne `type` – so, wie ein Agent sie zusammenstellt. */
+export interface ChatConfirmBlockInput {
+    id: string;
+    title: string;
+    description?: string | null;
+    fields?: ChatBlockField[];
+    actions: Array<{
+        id: string;
+        label: string;
+        style?: ChatActionStyle;
+    }>;
+    expiresAt?: string | null;
+}
+export declare const chatBlockInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"confirm">;
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+    actions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        style: z.ZodDefault<z.ZodEnum<{
+            danger: "danger";
+            primary: "primary";
+            secondary: "secondary";
+        }>>;
+    }, z.core.$strip>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>], "type">;
+export type ChatBlockInput = z.output<typeof chatBlockInputSchema>;
+export declare const chatBlocksInputSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"confirm">;
+    id: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+    actions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        style: z.ZodDefault<z.ZodEnum<{
+            danger: "danger";
+            primary: "primary";
+            secondary: "secondary";
+        }>>;
+    }, z.core.$strip>>;
+    expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>], "type">>;
+/** Klick auf eine Aktion: `POST /chat/messages/:messageId/actions`. */
+export declare const chatActionSchema: z.ZodObject<{
+    blockId: z.ZodString;
+    actionId: z.ZodString;
+}, z.core.$strip>;
+export type ChatActionInput = z.output<typeof chatActionSchema>;
+/** Ist die Karte abgelaufen? Abgelaufene Karten sind grau und nicht mehr klickbar. */
+export declare function blockExpired(block: Pick<ChatConfirmBlock, 'expiresAt'>, now?: number): boolean;