@kromatv/sdk 0.1.39-canary.3579809

package/types/client/src/api/jobs/client.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import type { RequestContext } from '../../core/client';
+import type { JobKey, JobRunId } from './ids';
+import { type JobPatch } from './schemas';
+/** The scheduled jobs behind the admin console's Tâches screen. */
+export default function jobsApi(ctx: RequestContext): {
+    list: () => Promise<{
+        jobs: {
+            key: string & z.$brand<"JobKey">;
+            name: string;
+            description: string;
+            category: "acquisition" | "library" | "maintenance" | "pipeline" | "recommendations";
+            schedule: string | null;
+            defaultSchedule: string | null;
+            customized: boolean;
+            enabled: boolean;
+            running: boolean;
+            runId: (string & z.$brand<"JobRunId">) | null;
+            progressDone: number | null;
+            progressTotal: number | null;
+            nextRunAt: number | null;
+            lastRun: {
+                id: string & z.$brand<"JobRunId">;
+                jobKey: string & z.$brand<"JobKey">;
+                trigger: string;
+                status: string;
+                startedAt: number;
+                finishedAt: number | null;
+                durationMs: number | null;
+                progressDone: number | null;
+                progressTotal: number | null;
+                error: string | null;
+            } | null;
+        }[];
+    }>;
+    detail: (key: JobKey) => Promise<{
+        info: {
+            key: string & z.$brand<"JobKey">;
+            name: string;
+            description: string;
+            category: "acquisition" | "library" | "maintenance" | "pipeline" | "recommendations";
+            schedule: string | null;
+            defaultSchedule: string | null;
+            customized: boolean;
+            enabled: boolean;
+            running: boolean;
+            runId: (string & z.$brand<"JobRunId">) | null;
+            progressDone: number | null;
+            progressTotal: number | null;
+            nextRunAt: number | null;
+            lastRun: {
+                id: string & z.$brand<"JobRunId">;
+                jobKey: string & z.$brand<"JobKey">;
+                trigger: string;
+                status: string;
+                startedAt: number;
+                finishedAt: number | null;
+                durationMs: number | null;
+                progressDone: number | null;
+                progressTotal: number | null;
+                error: string | null;
+            } | null;
+        };
+        runs: {
+            id: string & z.$brand<"JobRunId">;
+            jobKey: string & z.$brand<"JobKey">;
+            trigger: string;
+            status: string;
+            startedAt: number;
+            finishedAt: number | null;
+            durationMs: number | null;
+            progressDone: number | null;
+            progressTotal: number | null;
+            error: string | null;
+        }[];
+    }>;
+    run: (key: JobKey) => Promise<{
+        runId: string & z.$brand<"JobRunId">;
+    }>;
+    cancel: (key: JobKey) => Promise<{
+        cancelled: boolean;
+    }>;
+    update: (key: JobKey, patch: JobPatch) => Promise<void>;
+    runLogs: (runId: JobRunId) => Promise<{
+        logs: {
+            ts: number;
+            level: string;
+            message: string;
+        }[];
+    }>;
+};
+declare module '../../core/client' {
+    interface Domains {
+        jobs: ReturnType<typeof jobsApi>;
+    }
+}

package/types/client/src/api/jobs/ids.d.ts

@@ -0,0 +1,5 @@
+import type { z } from 'zod';
+export declare const JobKey: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+export type JobKey = z.infer<typeof JobKey>;
+export declare const JobRunId: z.core.$ZodBranded<z.ZodString, "JobRunId", "out">;
+export type JobRunId = z.infer<typeof JobRunId>;

package/types/client/src/api/jobs/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './ids';
+export * from './schemas';

package/types/client/src/api/jobs/schemas.d.ts

@@ -0,0 +1,168 @@
+import { z } from 'zod';
+/** Which part of the system a scheduled job belongs to. */
+export declare const Category: z.ZodEnum<{
+    acquisition: "acquisition";
+    library: "library";
+    maintenance: "maintenance";
+    pipeline: "pipeline";
+    recommendations: "recommendations";
+}>;
+export type Category = z.infer<typeof Category>;
+/** One recorded execution of a job. */
+export declare const JobRun: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "JobRunId", "out">;
+    jobKey: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+    trigger: z.ZodString;
+    status: z.ZodString;
+    startedAt: z.ZodNumber;
+    finishedAt: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    progressDone: z.ZodNullable<z.ZodNumber>;
+    progressTotal: z.ZodNullable<z.ZodNumber>;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type JobRun = z.infer<typeof JobRun>;
+/** A job's definition + current state, as listed in the admin console. */
+export declare const JobInfo: z.ZodObject<{
+    key: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<{
+        acquisition: "acquisition";
+        library: "library";
+        maintenance: "maintenance";
+        pipeline: "pipeline";
+        recommendations: "recommendations";
+    }>;
+    schedule: z.ZodNullable<z.ZodString>;
+    defaultSchedule: z.ZodNullable<z.ZodString>;
+    customized: z.ZodBoolean;
+    enabled: z.ZodBoolean;
+    running: z.ZodBoolean;
+    runId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "JobRunId", "out">>;
+    progressDone: z.ZodNullable<z.ZodNumber>;
+    progressTotal: z.ZodNullable<z.ZodNumber>;
+    nextRunAt: z.ZodNullable<z.ZodNumber>;
+    lastRun: z.ZodNullable<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "JobRunId", "out">;
+        jobKey: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+        trigger: z.ZodString;
+        status: z.ZodString;
+        startedAt: z.ZodNumber;
+        finishedAt: z.ZodNullable<z.ZodNumber>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        progressDone: z.ZodNullable<z.ZodNumber>;
+        progressTotal: z.ZodNullable<z.ZodNumber>;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type JobInfo = z.infer<typeof JobInfo>;
+/** `PATCH /api/admin/jobs/:key` body. A `null` schedule clears it. */
+export declare const JobPatch: z.ZodObject<{
+    schedule: z.ZodExactOptional<z.ZodNullable<z.ZodString>>;
+    enabled: z.ZodExactOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type JobPatch = z.infer<typeof JobPatch>;
+/** One persisted log line of a run. */
+export declare const JobLog: z.ZodObject<{
+    ts: z.ZodNumber;
+    level: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type JobLog = z.infer<typeof JobLog>;
+/** `GET /api/admin/jobs/:key` a job plus its recent run history. */
+export declare const JobDetail: z.ZodObject<{
+    info: z.ZodObject<{
+        key: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+        name: z.ZodString;
+        description: z.ZodString;
+        category: z.ZodEnum<{
+            acquisition: "acquisition";
+            library: "library";
+            maintenance: "maintenance";
+            pipeline: "pipeline";
+            recommendations: "recommendations";
+        }>;
+        schedule: z.ZodNullable<z.ZodString>;
+        defaultSchedule: z.ZodNullable<z.ZodString>;
+        customized: z.ZodBoolean;
+        enabled: z.ZodBoolean;
+        running: z.ZodBoolean;
+        runId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "JobRunId", "out">>;
+        progressDone: z.ZodNullable<z.ZodNumber>;
+        progressTotal: z.ZodNullable<z.ZodNumber>;
+        nextRunAt: z.ZodNullable<z.ZodNumber>;
+        lastRun: z.ZodNullable<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "JobRunId", "out">;
+            jobKey: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+            trigger: z.ZodString;
+            status: z.ZodString;
+            startedAt: z.ZodNumber;
+            finishedAt: z.ZodNullable<z.ZodNumber>;
+            durationMs: z.ZodNullable<z.ZodNumber>;
+            progressDone: z.ZodNullable<z.ZodNumber>;
+            progressTotal: z.ZodNullable<z.ZodNumber>;
+            error: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    runs: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "JobRunId", "out">;
+        jobKey: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+        trigger: z.ZodString;
+        status: z.ZodString;
+        startedAt: z.ZodNumber;
+        finishedAt: z.ZodNullable<z.ZodNumber>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        progressDone: z.ZodNullable<z.ZodNumber>;
+        progressTotal: z.ZodNullable<z.ZodNumber>;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type JobDetail = z.infer<typeof JobDetail>;
+/** What every "start this now" endpoint answers: the run it queued. */
+export declare const JobStarted: z.ZodObject<{
+    runId: z.core.$ZodBranded<z.ZodString, "JobRunId", "out">;
+}, z.core.$strip>;
+export type JobStarted = z.infer<typeof JobStarted>;
+/** What every "stop this" endpoint answers. */
+export declare const JobCancelled: z.ZodObject<{
+    cancelled: z.ZodBoolean;
+}, z.core.$strip>;
+export type JobCancelled = z.infer<typeof JobCancelled>;
+/** `GET /api/admin/jobs`. */
+export declare const JobsView: z.ZodObject<{
+    jobs: z.ZodArray<z.ZodObject<{
+        key: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+        name: z.ZodString;
+        description: z.ZodString;
+        category: z.ZodEnum<{
+            acquisition: "acquisition";
+            library: "library";
+            maintenance: "maintenance";
+            pipeline: "pipeline";
+            recommendations: "recommendations";
+        }>;
+        schedule: z.ZodNullable<z.ZodString>;
+        defaultSchedule: z.ZodNullable<z.ZodString>;
+        customized: z.ZodBoolean;
+        enabled: z.ZodBoolean;
+        running: z.ZodBoolean;
+        runId: z.ZodNullable<z.core.$ZodBranded<z.ZodString, "JobRunId", "out">>;
+        progressDone: z.ZodNullable<z.ZodNumber>;
+        progressTotal: z.ZodNullable<z.ZodNumber>;
+        nextRunAt: z.ZodNullable<z.ZodNumber>;
+        lastRun: z.ZodNullable<z.ZodObject<{
+            id: z.core.$ZodBranded<z.ZodString, "JobRunId", "out">;
+            jobKey: z.core.$ZodBranded<z.ZodString, "JobKey", "out">;
+            trigger: z.ZodString;
+            status: z.ZodString;
+            startedAt: z.ZodNumber;
+            finishedAt: z.ZodNullable<z.ZodNumber>;
+            durationMs: z.ZodNullable<z.ZodNumber>;
+            progressDone: z.ZodNullable<z.ZodNumber>;
+            progressTotal: z.ZodNullable<z.ZodNumber>;
+            error: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type JobsView = z.infer<typeof JobsView>;

package/types/client/src/api/library/client.d.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import type { RequestContext } from '../../core/client';
+import { LibraryId } from '../media';
+import { type LibraryBody, type LibraryPatch } from './schemas';
+/** Admin library management: folders, scans, and the server-side folder picker. */
+export default function libraryApi(ctx: RequestContext): {
+    /** Libraries with folders, size and item counts (needs an admin capability). */
+    list: () => Promise<{
+        libraries: {
+            id: string & z.$brand<"LibraryId">;
+            name: string;
+            kind: string;
+            folders: string[];
+            itemCount: number;
+            sizeBytes: number;
+            lastScan: string | null;
+            autoScan: boolean;
+        }[];
+    }>;
+    /** Add a library and trigger a rescan (requires `library.manage`). */
+    create: (body: LibraryBody) => Promise<{
+        id: string & z.$brand<"LibraryId">;
+    }>;
+    /** Rename, change folders or toggle auto-scan for a library. */
+    update: (id: LibraryId, patch: LibraryPatch) => Promise<void>;
+    /** Remove a library (its items are dropped on the ensuing rescan). */
+    delete: (id: LibraryId) => Promise<void>;
+    /** Kick a full rescan (from the libraries page). */
+    scan: (id: LibraryId) => Promise<void>;
+    /** Browse server-side directories for the folder picker. An empty or absent
+     * `path` returns the roots (NAS volumes, or `/` in dev). */
+    browse: (path?: string) => Promise<{
+        path: string;
+        parent: string | null;
+        entries: {
+            name: string;
+            path: string;
+        }[];
+    }>;
+};
+declare module '../../core/client' {
+    interface Domains {
+        library: ReturnType<typeof libraryApi>;
+    }
+}

package/types/client/src/api/library/index.d.ts

@@ -0,0 +1,2 @@
+export * from './client';
+export * from './schemas';

package/types/client/src/api/library/schemas.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+/** A named, multi-folder library (`GET /api/admin/libraries`). */
+export declare const AdminLibrary: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "LibraryId", "out">;
+    name: z.ZodString;
+    kind: z.ZodString;
+    folders: z.ZodArray<z.ZodString>;
+    itemCount: z.ZodNumber;
+    sizeBytes: z.ZodNumber;
+    lastScan: z.ZodNullable<z.ZodString>;
+    autoScan: z.ZodBoolean;
+}, z.core.$strip>;
+export type AdminLibrary = z.infer<typeof AdminLibrary>;
+/** `POST /api/admin/libraries` body. */
+export declare const LibraryBody: z.ZodObject<{
+    name: z.ZodString;
+    folders: z.ZodArray<z.ZodString>;
+    kind: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LibraryBody = z.infer<typeof LibraryBody>;
+/** `PATCH /api/admin/libraries/:id` body: only the keys present are changed. */
+export declare const LibraryPatch: z.ZodObject<{
+    name: z.ZodExactOptional<z.ZodString>;
+    kind: z.ZodExactOptional<z.ZodString>;
+    folders: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+    autoScan: z.ZodExactOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type LibraryPatch = z.infer<typeof LibraryPatch>;

package/types/client/src/api/llm/client.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import type { RequestContext } from '../../core/client';
+import { type LlmProbe, type LlmSave } from './schemas';
+/** The LLM provider configuration behind the admin's AI settings. */
+export default function llmApi(ctx: RequestContext): {
+    /** API keys are never returned. */
+    config: () => Promise<{
+        enabled: boolean;
+        defaultId: string;
+        providers: {
+            id: string & z.$brand<"LlmProviderId">;
+            name: string;
+            provider: string;
+            baseUrl: string;
+            model: string;
+            hasApiKey: boolean;
+            temperature: number;
+            maxTokens: number;
+            reasoning: boolean;
+        }[];
+    }>;
+    save: (body: LlmSave) => Promise<void>;
+    models: (probe: LlmProbe) => Promise<{
+        models: string[];
+        error?: string | undefined;
+    }>;
+    /** Never rejects on a bad endpoint: failures come back as `{ ok: false }`. */
+    test: (probe: LlmProbe) => Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+};
+declare module '../../core/client' {
+    interface Domains {
+        llm: ReturnType<typeof llmApi>;
+    }
+}

package/types/client/src/api/llm/ids.d.ts

@@ -0,0 +1,3 @@
+import type { z } from 'zod';
+export declare const LlmProviderId: z.core.$ZodBranded<z.ZodString, "LlmProviderId", "out">;
+export type LlmProviderId = z.infer<typeof LlmProviderId>;

package/types/client/src/api/llm/index.d.ts

@@ -0,0 +1,3 @@
+export * from './client';
+export * from './ids';
+export * from './schemas';

package/types/client/src/api/llm/schemas.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+/** One configured provider as shown to the admin (the API key never returns). */
+export declare const LlmProviderView: z.ZodObject<{
+    id: z.core.$ZodBranded<z.ZodString, "LlmProviderId", "out">;
+    name: z.ZodString;
+    provider: z.ZodString;
+    baseUrl: z.ZodString;
+    model: z.ZodString;
+    hasApiKey: z.ZodBoolean;
+    temperature: z.ZodNumber;
+    maxTokens: z.ZodNumber;
+    reasoning: z.ZodBoolean;
+}, z.core.$strip>;
+export type LlmProviderView = z.infer<typeof LlmProviderView>;
+/** `GET /api/admin/llm` the multi-provider LLM configuration. */
+export declare const LlmAdminConfig: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    defaultId: z.ZodString;
+    providers: z.ZodArray<z.ZodObject<{
+        id: z.core.$ZodBranded<z.ZodString, "LlmProviderId", "out">;
+        name: z.ZodString;
+        provider: z.ZodString;
+        baseUrl: z.ZodString;
+        model: z.ZodString;
+        hasApiKey: z.ZodBoolean;
+        temperature: z.ZodNumber;
+        maxTokens: z.ZodNumber;
+        reasoning: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LlmAdminConfig = z.infer<typeof LlmAdminConfig>;
+/** One provider as saved. A blank or omitted `apiKey` keeps the stored secret,
+ * and a BLANK `id` asks the server to mint one: a provider the admin has just
+ * added has no id until it is saved. */
+export declare const LlmProviderInput: z.ZodObject<{
+    name: z.ZodString;
+    provider: z.ZodString;
+    baseUrl: z.ZodString;
+    model: z.ZodString;
+    temperature: z.ZodNumber;
+    maxTokens: z.ZodNumber;
+    reasoning: z.ZodBoolean;
+    id: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "LlmProviderId", "out">, z.ZodLiteral<"">]>;
+    apiKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LlmProviderInput = z.infer<typeof LlmProviderInput>;
+/** `PUT /api/admin/llm` body. The default is identified by index, not id: a
+ * not-yet-saved provider has no id until the server assigns one. */
+export declare const LlmSave: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    defaultIndex: z.ZodNumber;
+    providers: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        provider: z.ZodString;
+        baseUrl: z.ZodString;
+        model: z.ZodString;
+        temperature: z.ZodNumber;
+        maxTokens: z.ZodNumber;
+        reasoning: z.ZodBoolean;
+        id: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "LlmProviderId", "out">, z.ZodLiteral<"">]>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type LlmSave = z.infer<typeof LlmSave>;
+/** What a connection probe needs. Blank fields fall back to the saved provider
+ * identified by `id`, notably a masked API key. */
+export declare const LlmProbe: z.ZodObject<{
+    provider: z.ZodExactOptional<z.ZodString>;
+    baseUrl: z.ZodExactOptional<z.ZodString>;
+    model: z.ZodExactOptional<z.ZodString>;
+    id: z.ZodExactOptional<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "LlmProviderId", "out">, z.ZodLiteral<"">]>>;
+    apiKey: z.ZodExactOptional<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type LlmProbe = z.infer<typeof LlmProbe>;

package/types/client/src/api/media/artwork-scale.d.ts

@@ -0,0 +1,6 @@
+/** The `?w=` a surface drawn `displayWidth` wide must ask for: device pixels,
+ * capped at the widest rendition the server keeps, scaled by the device's
+ * artwork-quality setting, then snapped up to a rendition that exists. The one
+ * place a drawn size becomes a request, so `resolveArt` and `sizedImageUrl`
+ * cannot drift apart. */
+export declare function artworkWidth(displayWidth: number, scale?: number): number;

package/types/client/src/api/media/artwork.d.ts

@@ -0,0 +1,31 @@
+import type { RequestContext } from '../../core/http';
+import type { Metadata } from './credits';
+import type { ItemId, ShowId } from './ids';
+import type { MediaItem, Show } from './schemas';
+/** Artwork URLs: resolving stored art against the server, at the size it is drawn. */
+export declare function artworkApi(ctx: RequestContext): {
+    resolve: (url?: string | null, width?: number) => string | null;
+    posterUrl: (id: ItemId) => string;
+    showPosterUrl: (id: ShowId) => string;
+    /** Best poster for a movie/episode: real cached TMDB art if resolved, else
+     * the generated SVG placeholder. */
+    posterFor: (x: {
+        id: ItemId;
+        metadata?: Metadata | null;
+    }, width?: number) => string;
+    /** Best poster for a show: real cached TMDB art if resolved, else the SVG. */
+    showPosterFor: (x: Pick<Show, 'id' | 'metadata'>, width?: number) => string;
+    /** Cover/backdrop art for a movie or show, or `null` when none resolved. */
+    backdropFor: (x: {
+        metadata?: Metadata | null;
+    }, width?: number) => string | null;
+    /** Plex-style theme song for a movie or show, or `null` when none resolved.
+     * Only TV shows carry one (a cached `/api/themes/<tvdb>.mp3`). */
+    themeFor: (x: {
+        metadata?: Metadata | null;
+    }) => string | null;
+    /** Real poster bytes (cached TMDB art) for the OS "Now Playing" artwork;
+     * prefers a raster over the generated SVG placeholder, which NSImage cannot
+     * render. */
+    posterBlob: (item: Pick<MediaItem, 'id' | 'metadata'>) => Promise<Blob>;
+};