@etazio/agent-sdk 0.1.0

package/types/shared/generator.d.ts

@@ -0,0 +1,317 @@
+import { z } from 'zod';
+/**
+ * KI-Office-Generator (G1b/G1c, specs/ai-office-generator-spec.md §4–§5): Auftrag, Zustände, Fortschritt.
+ * Brief/Plan sind hier untypisiert (`unknown`) – ihre Schemata (`officeBriefSchema`, `officePlanSchema`) leben in
+ * @huddle/scene-schema, damit shared nicht davon abhängt; API und Client prüfen sie dort.
+ */
+export declare const GENERATION_STATUSES: readonly ['queued', 'analyzing', 'briefing', 'awaiting_brief', 'planning', 'compiling', 'validating', 'ready', 'applied', 'failed', 'cancelled'];
+export type GenerationStatus = (typeof GENERATION_STATUSES)[number];
+/** Zustände, in denen der Job noch läuft oder auf den Nutzer wartet */
+export declare const ACTIVE_GENERATION_STATUSES: ReadonlySet<GenerationStatus>;
+export declare const GENERATION_STATUS_LABELS: Record<GenerationStatus, string>;
+export declare const GENERATOR_LIMITS: {
+    readonly maxPrompt: 2000;
+    /** Jobs je Tag und Workspace (Default; Server: GENERATOR_DAILY_LIMIT) */
+    readonly dailyDefault: 20;
+    /** Verlauf: letzte Jobs */
+    readonly historySize: 20;
+};
+/** Referenz-Uploads (G2/G3, SPA-121): Grundriss oder Stil-/Inhaltsbild */
+export declare const GENERATOR_FILE_LIMITS: {
+    readonly maxFiles: 6;
+    readonly maxBytes: number;
+    /** PDF: so viele Seiten werden höchstens betrachtet */
+    readonly maxPdfPages: 20;
+    /** Lange Kante nach der Normalisierung */
+    readonly maxEdge: 2048;
+    /** Uploads je Nutzer und Stunde */
+    readonly perHour: 30;
+    readonly maxName: 120;
+};
+export declare const GENERATOR_FILE_MIMES: readonly ['image/jpeg', 'image/png', 'image/webp', 'application/pdf'];
+export type GeneratorFileMime = (typeof GENERATOR_FILE_MIMES)[number];
+export declare const GENERATOR_FILE_ROLES: readonly ['floorplan', 'style'];
+export type GeneratorFileRole = (typeof GENERATOR_FILE_ROLES)[number];
+export declare const GENERATOR_FILE_ROLE_LABELS: Record<GeneratorFileRole, string>;
+/** Upload als Data-URL (wie die Bildmediathek) – der Typ wird aus den Bytes bestimmt */
+export declare const generatorFileUploadSchema: z.ZodObject<{
+    name: z.ZodString;
+    data: z.ZodString;
+}, z.core.$strip>;
+export declare const generatorFileIdSchema: z.ZodString;
+export declare const generatorFileRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    role: z.ZodEnum<{
+        floorplan: "floorplan";
+        style: "style";
+    }>;
+    page: z.ZodOptional<z.ZodNumber>;
+    scaleMeters: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type GeneratorFileRef = z.infer<typeof generatorFileRefSchema>;
+export interface GeneratorFileDto {
+    id: string;
+    name: string;
+    mime: GeneratorFileMime;
+    bytes: number;
+    /** Maße des normalisierten Bildes (bei PDF: Seite 1) */
+    width: number;
+    height: number;
+    pages: number;
+    suggestedRole: GeneratorFileRole;
+    roleConfidence: number;
+    roleReason: string;
+    createdAt: string;
+}
+/** Auswertung einer Referenz am Job */
+export interface GenerationFileDto {
+    id: string;
+    name: string;
+    role: GeneratorFileRole;
+    page: number;
+    scaleMeters: number | null;
+    width: number;
+    height: number;
+    status: 'pending' | 'ok' | 'failed' | 'skipped';
+    error: string | null;
+    /** Kurzfassung der Extraktion (Anzeige) */
+    summary: string;
+}
+/** Overlay in Schritt 2: Grundriss halbtransparent unter dem Raster */
+export interface FloorplanOverlayDto {
+    fileId: string;
+    page: number;
+    /** Bildlage im Kachel-Rahmen (Meter; Kachel i reicht von 2i−1 bis 2i+1) */
+    image: {
+        minX: number;
+        maxX: number;
+        minZ: number;
+        maxZ: number;
+    };
+    grid: {
+        minI: number;
+        maxI: number;
+        minJ: number;
+        maxJ: number;
+    };
+    rooms: Array<{
+        id: string;
+        name: string;
+        kind: string;
+        rect: {
+            minI: number;
+            maxI: number;
+            minJ: number;
+            maxJ: number;
+        };
+        source: {
+            minX: number;
+            maxX: number;
+            minZ: number;
+            maxZ: number;
+        } | null;
+        deviation: number;
+        doors: Array<{
+            a: [number, number];
+            b: [number, number];
+        }>;
+    }>;
+    entrance: {
+        roomId: string;
+        a: [number, number];
+        b: [number, number];
+    };
+    scale: {
+        widthMeters: number;
+        heightMeters: number;
+        source: string;
+        buildingMeters: {
+            w: number;
+            h: number;
+        };
+    };
+    maxDeviation: number;
+    strongRounding: boolean;
+    notes: string[];
+}
+export declare const generatorParamsSchema: z.ZodObject<{
+    seats: z.ZodOptional<z.ZodNumber>;
+    meetingRooms: z.ZodOptional<z.ZodNumber>;
+    lounge: z.ZodOptional<z.ZodBoolean>;
+    fun: z.ZodOptional<z.ZodBoolean>;
+    kitchen: z.ZodOptional<z.ZodBoolean>;
+    focus: z.ZodOptional<z.ZodBoolean>;
+    outdoor: z.ZodOptional<z.ZodBoolean>;
+    style: z.ZodOptional<z.ZodEnum<{
+        bunt: "bunt";
+        homeoffice: "homeoffice";
+        industrial: "industrial";
+        minimal: "minimal";
+        skandinavisch: "skandinavisch";
+    }>>;
+    sky: z.ZodOptional<z.ZodEnum<{
+        day: "day";
+        evening: "evening";
+        night: "night";
+    }>>;
+    size: z.ZodOptional<z.ZodEnum<{
+        grosszuegig: "grosszuegig";
+        kompakt: "kompakt";
+        normal: "normal";
+    }>>;
+}, z.core.$strip>;
+export type GeneratorParams = z.infer<typeof generatorParamsSchema>;
+export declare const createGenerationJobSchema: z.ZodObject<{
+    prompt: z.ZodDefault<z.ZodString>;
+    params: z.ZodDefault<z.ZodObject<{
+        seats: z.ZodOptional<z.ZodNumber>;
+        meetingRooms: z.ZodOptional<z.ZodNumber>;
+        lounge: z.ZodOptional<z.ZodBoolean>;
+        fun: z.ZodOptional<z.ZodBoolean>;
+        kitchen: z.ZodOptional<z.ZodBoolean>;
+        focus: z.ZodOptional<z.ZodBoolean>;
+        outdoor: z.ZodOptional<z.ZodBoolean>;
+        style: z.ZodOptional<z.ZodEnum<{
+            bunt: "bunt";
+            homeoffice: "homeoffice";
+            industrial: "industrial";
+            minimal: "minimal";
+            skandinavisch: "skandinavisch";
+        }>>;
+        sky: z.ZodOptional<z.ZodEnum<{
+            day: "day";
+            evening: "evening";
+            night: "night";
+        }>>;
+        size: z.ZodOptional<z.ZodEnum<{
+            grosszuegig: "grosszuegig";
+            kompakt: "kompakt";
+            normal: "normal";
+        }>>;
+    }, z.core.$strip>>;
+    template: z.ZodOptional<z.ZodString>;
+    mode: z.ZodDefault<z.ZodEnum<{
+        neu: "neu";
+    }>>;
+    skipBrief: z.ZodDefault<z.ZodBoolean>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    files: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodEnum<{
+            floorplan: "floorplan";
+            style: "style";
+        }>;
+        page: z.ZodOptional<z.ZodNumber>;
+        scaleMeters: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CreateGenerationJobInput = z.input<typeof createGenerationJobSchema>;
+export declare const confirmBriefSchema: z.ZodObject<{
+    brief: z.ZodUnknown;
+    answers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export declare const applyGenerationSchema: z.ZodObject<{
+    baseVersion: z.ZodNumber;
+}, z.core.$strip>;
+export declare const revertGenerationSchema: z.ZodObject<{
+    baseVersion: z.ZodNumber;
+}, z.core.$strip>;
+export declare const generationJobIdSchema: z.ZodString;
+export interface GenerationUsageDto {
+    inputTokens: number;
+    outputTokens: number;
+    calls: number;
+}
+export interface GenerationStatsDto {
+    rooms: number;
+    seatsPlanned: number;
+    seatsBuilt: number;
+    placements: number;
+    ops: number;
+    batches: number;
+    dropped: number;
+    repairs: number;
+}
+export interface GenerationJobDto {
+    id: string;
+    officeId: string;
+    status: GenerationStatus;
+    /** Fortschritt 0–100 und Meldung der aktuellen Stufe */
+    progress: number;
+    message: string;
+    prompt: string;
+    params: GeneratorParams;
+    template: string | null;
+    mode: 'neu';
+    seed: number;
+    model: string;
+    createdBy: {
+        userId: string;
+        displayName: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+    /** OfficeBrief (Schema in scene-schema) – ab `awaiting_brief` */
+    brief: unknown | null;
+    briefConfirmedAt: string | null;
+    /** Ergebnis (ab `ready`) */
+    stats: GenerationStatsDto | null;
+    issues: Array<{
+        code: string;
+        message: string;
+        targetId?: string;
+        otherId?: string;
+    }>;
+    dropped: Array<{
+        roomId: string;
+        reason: string;
+        message: string;
+    }>;
+    /** Raum-ID → Rechteck in Metern (Karte/Kamera) */
+    roomBounds: Record<string, {
+        minX: number;
+        maxX: number;
+        minZ: number;
+        maxZ: number;
+    }> | null;
+    notes: string[];
+    /** Entwurfsversion nach dem Übernehmen (für „Verwerfen“) */
+    appliedDraftVersion: number | null;
+    error: string | null;
+    usage: GenerationUsageDto;
+    /** Referenzen und ihre Auswertung (G2/G3) */
+    files: GenerationFileDto[];
+    /** Gerasterter Grundriss für das Overlay (G3) */
+    floorplan: FloorplanOverlayDto | null;
+}
+export interface GeneratorStatusDto {
+    /** LLM verfügbar (Key gesetzt) – ohne ist nur die Vorlagen-Variante möglich */
+    llm: boolean;
+    provider: string;
+    model: string;
+    dailyLimit: number;
+    usedToday: number;
+    /** Laufender Job dieses Offices (höchstens einer) */
+    activeJobId: string | null;
+    templates: Array<{
+        id: string;
+        label: string;
+        description: string;
+    }>;
+    /** Referenz-Uploads möglich (Grundriss braucht die KI; PDF braucht pdftoppm auf dem Server) */
+    uploads: {
+        enabled: boolean;
+        pdf: boolean;
+        floorplanNeedsLlm: boolean;
+        limits: typeof GENERATOR_FILE_LIMITS;
+    };
+}
+/** Socket `generator:progress` */
+export interface GeneratorProgressPayload {
+    workspaceId: string;
+    officeId: string;
+    jobId: string;
+    status: GenerationStatus;
+    progress: number;
+    message: string;
+}

package/types/shared/images.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+/**
+ * Bild-Uploads (Phase 7d): ein Workspace hat eine kleine Bildmediathek. Die Bilder hängen anschließend in
+ * Rahmen/Postern/Logoflächen (Katalogfeld `picture`, Vertrag v2.5) und können als Diashow am Fernseher laufen.
+ * Gespeichert wird die Datei im Volume, die Metadaten in Mongo; der Objektzustand trägt nur die Id.
+ */
+export declare const IMAGE_LIMITS: {
+    /** Rohbytes je Bild (der Upload kommt als Base64 in JSON – der Body darf ~4/3 davon groß sein) */
+    readonly maxBytes: number;
+    /** Kantenlänge und Gesamtfläche (Schutz gegen Dekomprimierungsbomben) */
+    readonly maxDimension: 8000;
+    readonly maxPixels: 40000000;
+    /** Bilder je Workspace */
+    readonly maxPerWorkspace: 300;
+    readonly maxNameLength: 80;
+};
+export declare const IMAGE_MIME_TYPES: readonly ['image/png', 'image/jpeg', 'image/webp'];
+export type ImageMime = (typeof IMAGE_MIME_TYPES)[number];
+export declare const IMAGE_EXTENSIONS: Record<ImageMime, string>;
+export interface WorkspaceImageDto {
+    id: string;
+    name: string;
+    mime: ImageMime;
+    bytes: number;
+    width: number;
+    height: number;
+    /** Seitenverhältnis w/h – der Browser rechnet damit `cover`/`contain` aus, bevor die Datei geladen ist */
+    ar: number;
+    createdAt: string;
+    createdBy: string | null;
+    createdByName: string | null;
+}
+/** Pfad der Bilddatei (gleicher Origin wie die API, Cookie-Auth, unveränderlich cachebar) */
+export declare function imageFileUrl(workspaceId: string, imageId: string): string;
+/** Eintrag einer Diashow: entweder eine hochgeladene Bild-Id (`img:<id>`) oder eine https-Adresse */
+export declare const SLIDESHOW_IMAGE_PREFIX = "img:";
+export declare function slideshowEntryUrl(workspaceId: string, entry: string): string;
+export declare const imageIdSchema: z.ZodString;
+export declare const imageNameSchema: z.ZodString;
+/** Upload: Dateiname und Datei als Data-URL. Die Bytes prüft der Server zusätzlich am Kopf der Datei. */
+export declare const imageUploadSchema: z.ZodObject<{
+    name: z.ZodString;
+    data: z.ZodString;
+}, z.core.$strip>;
+export type ImageUploadInput = z.infer<typeof imageUploadSchema>;
+export declare const imageRenameSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Zuschnitt einer Bildfläche: `cover` füllt formatfüllend und schneidet über, `contain` passt vollständig ein
+ * und lässt den Rest durchsichtig. Der Katalog (`picture.fit`) gibt die Voreinstellung je Asset vor (SPA-58),
+ * seit SPA-91 darf jeder Rahmen davon abweichen.
+ */
+export declare const PICTURE_FITS: readonly ['cover', 'contain'];
+export type PictureFit = (typeof PICTURE_FITS)[number];
+export declare function isPictureFit(v: unknown): v is PictureFit;
+/**
+ * Bildzustand eines Rahmens (Objektzustand bzw. `placement.state`): `{ picture: '<id>', fit?: 'cover'|'contain' }`,
+ * leer = kein Bild. Das Seitenverhältnis steht weiter fest im Katalog (`picture.ar`) – es gehört zur Fläche,
+ * nicht zum Bild. Ohne `fit` gilt der Katalogwert.
+ */
+export interface PictureState {
+    picture?: string;
+    fit?: PictureFit;
+}
+export declare function validatePictureState(state: Record<string, unknown>): {
+    ok: true;
+    state: PictureState;
+} | {
+    ok: false;
+    error: string;
+};
+/** Welche Bild-Id hängt hier? Laufzeitzustand schlägt den Editor-Standard. */
+export declare function pictureIdOf(state: Record<string, unknown> | undefined, defaults: Record<string, unknown> | undefined): string | null;
+/**
+ * Welcher Zuschnitt gilt hier (SPA-91)? Laufzeitzustand → Editor-Standard → Katalog. Ein Zustand ohne `fit`
+ * überspringt die Stufe, statt den Katalogwert zu erzwingen – ein Rahmen ohne eigene Wahl folgt dem Katalog.
+ */
+export declare function pictureFitOf(state: Record<string, unknown> | undefined, defaults: Record<string, unknown> | undefined, fallback: PictureFit): PictureFit;

package/types/shared/index.d.ts

@@ -0,0 +1,17 @@
+export * from './roles.js';
+export * from './errors.js';
+export * from './chat.js';
+export * from './markdown.js';
+export * from './schemas.js';
+export * from './dto.js';
+export * from './events.js';
+export * from './avatar.js';
+export * from './agents.js';
+export * from './view.js';
+export * from './board.js';
+export * from './tv.js';
+export * from './generator.js';
+export * from './web.js';
+export * from './images.js';
+export * from './sso.js';
+export * from './calendar.js';

package/types/shared/markdown.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Markdown für Chat-Nachrichten (SPA-117).
+ *
+ * Der Parser lebt bewusst hier und nicht im UI-Paket: er erzeugt einen reinen Datenbaum, kein HTML
+ * und keine React-Knoten. Damit ist er ohne Browser testbar (die Sanitizing-Proben laufen in der
+ * API-Suite mit) und die Darstellung kann nichts einschleusen, was der Parser nicht vorgesehen hat.
+ * Es gibt keinen Weg von Nutzertext zu Markup: aus einem HTML-Schnipsel wird ein Textknoten, aus
+ * `javascript:…` ein Textknoten statt eines Links.
+ *
+ * Absichtlich klein gehalten: Fett, kursiv, durchgestrichen, Code (inline und Block), Zitate,
+ * Listen, Links, Trennlinien, Erwähnungen, Kanalverweise. Kein HTML, keine Tabellen, keine Bilder.
+ */
+export type MdInline = {
+    t: 'text';
+    v: string;
+} | {
+    t: 'code';
+    v: string;
+} | {
+    t: 'strong';
+    c: MdInline[];
+} | {
+    t: 'em';
+    c: MdInline[];
+} | {
+    t: 'del';
+    c: MdInline[];
+} | {
+    t: 'link';
+    href: string;
+    c: MdInline[];
+}
+/** `@Name` – die Darstellung macht daraus einen klickbaren Chip */
+ | {
+    t: 'mention';
+    name: string;
+}
+/** `#raum` – Verweis auf einen Kanal */
+ | {
+    t: 'channel';
+    name: string;
+} | {
+    t: 'br';
+};
+export type MdBlock = {
+    t: 'p';
+    c: MdInline[];
+} | {
+    t: 'quote';
+    c: MdBlock[];
+} | {
+    t: 'code';
+    lang: string | null;
+    v: string;
+} | {
+    t: 'list';
+    ordered: boolean;
+    start: number;
+    items: MdInline[][];
+} | {
+    t: 'hr';
+};
+export interface MarkdownOptions {
+    /** Bekannte Namen für `@`-Erwähnungen. Namen dürfen Leerzeichen enthalten, deshalb die Liste. */
+    names?: readonly string[];
+}
+/**
+ * Prüft eine Ziel-Adresse und gibt sie normalisiert zurück – oder `null`, wenn daraus kein Link
+ * werden darf. `javascript:`, `data:`, `vbscript:` und alles Unbekannte fallen hier heraus, auch
+ * wenn sie mit Steuerzeichen oder Groß-/Kleinschreibung getarnt sind.
+ */
+export declare function safeHref(raw: string): string | null;
+/** Nachricht in Blöcke zerlegen. Eingabe ist immer Nutzertext – der Parser wirft nie. */
+export declare function parseMarkdown(src: string, opts?: MarkdownOptions): MdBlock[];
+/** Nachricht als reiner Text – für Vorschauen, Benachrichtigungen und die Seitenleiste. */
+export declare function markdownToPlain(src: string, opts?: MarkdownOptions): string;

package/types/shared/roles.d.ts

@@ -0,0 +1,29 @@
+/** Rollen pro Workspace (Roadmap §3). `owner` ist genau einmal pro Workspace vergeben. */
+export declare const WORKSPACE_ROLES: readonly ['owner', 'admin', 'member', 'guest'];
+export type WorkspaceRole = (typeof WORKSPACE_ROLES)[number];
+/** Rollen, die per Einladung oder Rollenänderung vergeben werden dürfen (nie `owner`; Eigentum wird übertragen). */
+export declare const ASSIGNABLE_ROLES: readonly ['admin', 'member', 'guest'];
+export type AssignableRole = (typeof ASSIGNABLE_ROLES)[number];
+export declare const PERMISSIONS: readonly ['workspace.delete', 'workspace.transfer', 'workspace.update', 'members.read', 'members.manage', 'invitations.manage', 'office.edit', 'office.publish', 'desk.assign', 'desk.editOwn', 
+/** Freien Schreibtisch selbst sichern und eigenen Platz freigeben (SPA-125) – nur wenn der Workspace es erlaubt */
+'desk.claim', 'avatar.edit', 'meeting.join', 'audit.read', 
+/** KI-Agenten sehen (SPA-66) */
+'agents.read', 
+/** KI-Agenten anlegen, Scopes setzen, Token rotieren, abschalten (SPA-66) */
+'agents.manage'];
+export type Permission = (typeof PERMISSIONS)[number];
+/** Sichtbare Rollennamen – eine Quelle für UI, Mails und Agenten-Texte. */
+export declare const ROLE_LABELS: Record<WorkspaceRole, string>;
+/** Ein Satz je Rolle, in Kundensprache – erklärt, was die Rolle darf. */
+export declare const ROLE_HINTS: Record<WorkspaceRole, string>;
+/** Dieselbe Aussage in der Anrede – für Mails an die betroffene Person. */
+export declare const ROLE_HINTS_YOU: Record<WorkspaceRole, string>;
+export declare function can(role: WorkspaceRole, permission: Permission): boolean;
+/**
+ * Darf `actor` die Rolle von `target` auf `next` setzen?
+ * - Nur `owner` vergibt/entzieht nichts am Owner (Transfer ist ein eigener Vorgang).
+ * - Admins verwalten Admins, Mitglieder und Gäste, aber nicht den Owner.
+ * - `owner` ist nie Zielrolle einer Rollenänderung.
+ */
+export declare function canChangeRole(actor: WorkspaceRole, target: WorkspaceRole, next: WorkspaceRole): boolean;
+export declare function canRemoveMember(actor: WorkspaceRole, target: WorkspaceRole, isSelf: boolean): boolean;