@slatesvideo/shared 0.1.0 → 0.4.0

package/README.md

@@ -0,0 +1,5 @@
+# @slatesvideo/shared
+
+Internal shared layer for the [Slates](https://slates.video) MCP server and CLI: the auth/connection-file reader, the cloud and desktop HTTP clients, and the single operations array both surfaces register. You almost certainly want [@slatesvideo/mcp-server](https://www.npmjs.com/package/@slatesvideo/mcp-server) (MCP clients like Claude Desktop and Cursor) or [@slatesvideo/cli](https://www.npmjs.com/package/@slatesvideo/cli) (the `slates` command) instead — this package is published only as their dependency.
+
+Source: [github.com/EricDisero/slates-mcp](https://github.com/EricDisero/slates-mcp)

package/dist/clients/cloud.js

@@ -1,5 +1,29 @@
 import { requireCloudToken } from '../auth.js';
-export const DEFAULT_CLOUD_BASE_URL = process.env.SLATES_CLOUD_BASE_URL ?? 'https://slates-api.fly.dev';
+const FALLBACK_CLOUD_BASE_URL = 'https://slates-api.fly.dev';
+// The slates_sk_ bearer is attached to every cloud request. SLATES_CLOUD_BASE_URL
+// may override the host for dev/staging, but ONLY over https (or http to
+// localhost) — otherwise the token could be exfiltrated to an arbitrary host
+// or sent in cleartext. An invalid/insecure override is ignored (falls back to
+// production) rather than silently leaking the token.
+function resolveCloudBaseUrl() {
+    const override = process.env.SLATES_CLOUD_BASE_URL;
+    if (!override)
+        return FALLBACK_CLOUD_BASE_URL;
+    try {
+        const u = new URL(override);
+        const isLoopback = u.hostname === 'localhost' || u.hostname === '127.0.0.1';
+        if (u.protocol === 'https:' || (u.protocol === 'http:' && isLoopback)) {
+            return override.replace(/\/+$/, '');
+        }
+        console.error(`[slates] Ignoring SLATES_CLOUD_BASE_URL="${override}": must be https:// (or http://localhost). ` +
+            `Falling back to ${FALLBACK_CLOUD_BASE_URL} so the auth token is not exposed.`);
+    }
+    catch {
+        console.error(`[slates] Ignoring invalid SLATES_CLOUD_BASE_URL="${override}". Falling back to ${FALLBACK_CLOUD_BASE_URL}.`);
+    }
+    return FALLBACK_CLOUD_BASE_URL;
+}
+export const DEFAULT_CLOUD_BASE_URL = resolveCloudBaseUrl();
 // Thin client for slates-api. Used for credit-aware ops that route through
 // the user's account (generation proxy, credits balance, model registry,
 // license checks). The desktop client below is the local equivalent.
@@ -37,6 +61,13 @@ export class SlatesCloudClient {
             // fall through
         }
         if (!res.ok) {
+            // 401 = the slates_sk_ token is missing, expired, or was revoked
+            // (Disconnect in Slates Settings kills it server-side). Point at the
+            // two recovery paths instead of echoing an opaque auth error.
+            if (res.status === 401) {
+                throw new Error(`slates-api ${path} rejected the auth token (401) — it's expired or was revoked. ` +
+                    'To reconnect, run `slates login` (CLI) or reconnect in Slates → Settings → Agent Control');
+            }
             const detail = parsed && typeof parsed === 'object' && 'error' in parsed
                 ? parsed.error
                 : text || res.statusText;

package/dist/clients/desktop.d.ts

@@ -1,3 +1,10 @@
+export interface DesktopHealth {
+    ok: true;
+    service: string;
+    version?: string;
+    agentApiVersion?: number;
+    capabilities?: string[];
+}
 export declare class SlatesDesktopClient {
     private readonly token;
     private readonly port;
@@ -6,12 +13,11 @@ export declare class SlatesDesktopClient {
         port?: number;
     });
     private get baseUrl();
-    healthz(): Promise<{
-        ok: true;
-        service: string;
-    }>;
+    healthz(): Promise<DesktopHealth>;
+    requireCapability(cap: string, friendlyFeature: string): Promise<void>;
     get<T>(path: string, params?: Record<string, string | number | boolean | null | undefined>): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
+    private fetchOrFriendly;
     private handle;
 }
 //# sourceMappingURL=desktop.d.ts.map

package/dist/clients/desktop.js

@@ -1,8 +1,44 @@
 import { requireDesktop } from '../auth.js';
-// Thin client for the local Slates desktop HTTP server (127.0.0.1:PORT).
-// All workflow/state ops (projects, characters, storyboards, frames,
-// asset slot binding) go here. Generation routes through cloud, but the
-// generated assets are saved into desktop projects via this client.
+// Friendly message for the by-far-most-common failure: the desktop app
+// isn't running (or the connection file holds a stale port). A raw
+// "fetch failed" tells the agent nothing actionable.
+const DESKTOP_UNREACHABLE_MESSAGE = 'Slates desktop app is not reachable — open the Slates app and retry. ' +
+    'Not installed? https://slates.video/download';
+// Timeout-class failures are NOT "app not running": undici's default 300s
+// headers timeout fires on long blocking calls (export_video encoding can
+// exceed 5 min) while the desktop is still mid-work. Mislabeling that as
+// unreachable invites a retry that double-spends.
+const DESKTOP_TIMEOUT_MESSAGE = 'The Slates desktop app did not respond in time but may still be working ' +
+    '(long renders and video generations can exceed the HTTP timeout). ' +
+    'For video generation use background: true and poll with slates_get_generation_status. ' +
+    'For exports, check whether the output file landed on disk before retrying.';
+const CONNECTION_ERROR_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EHOSTUNREACH']);
+const TIMEOUT_ERROR_CODES = new Set(['UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'ETIMEDOUT']);
+// fetch wraps the real failure in TypeError('fetch failed', { cause }).
+// The cause carries the code — sometimes directly, sometimes (connect
+// failures) as an AggregateError whose sub-errors carry it. Collect all.
+function fetchErrorCodes(err) {
+    const codes = [];
+    const cause = err?.cause;
+    const code = cause?.code;
+    if (typeof code === 'string')
+        codes.push(code);
+    const subErrors = cause?.errors;
+    if (Array.isArray(subErrors)) {
+        for (const sub of subErrors) {
+            const c = sub?.code;
+            if (typeof c === 'string')
+                codes.push(c);
+        }
+    }
+    return codes;
+}
+// Module-level health cache so capability checks don't re-hit /agent/healthz
+// on every op call. 60s TTL — long enough to amortize a multi-op workflow,
+// short enough that an app update mid-session is picked up. Keyed by port
+// (each desktop instance = one port).
+const HEALTH_CACHE_TTL_MS = 60_000;
+const healthCache = new Map();
 export class SlatesDesktopClient {
     token;
     port;
@@ -21,12 +57,33 @@ export class SlatesDesktopClient {
         return `http://127.0.0.1:${this.port}`;
     }
     async healthz() {
-        const res = await fetch(`${this.baseUrl}/agent/healthz`);
+        const res = await this.fetchOrFriendly(`${this.baseUrl}/agent/healthz`);
         if (!res.ok) {
             throw new Error(`Desktop healthz failed (${res.status})`);
         }
         return res.json();
     }
+    // Version handshake. New ops (timeline, export, background generation,
+    // edit-image, image references) exist only on agent API v2 desktops.
+    // Calling a missing route on an old desktop would 404 with an opaque
+    // error — this check turns that into an actionable "update Slates"
+    // message BEFORE the op's first real request.
+    async requireCapability(cap, friendlyFeature) {
+        const cached = healthCache.get(this.port);
+        let health;
+        if (cached && Date.now() - cached.fetchedAt < HEALTH_CACHE_TTL_MS) {
+            health = cached.health;
+        }
+        else {
+            health = await this.healthz();
+            healthCache.set(this.port, { health, fetchedAt: Date.now() });
+        }
+        if (health.agentApiVersion === undefined || !health.capabilities?.includes(cap)) {
+            throw new Error(`Your Slates desktop app doesn't support ${friendlyFeature} yet ` +
+                `(agent API v${health.agentApiVersion ?? 1}, need v2 with '${cap}'). ` +
+                `Update Slates (Settings → Check for Updates) and retry.`);
+        }
+    }
     async get(path, params) {
         const url = new URL(`${this.baseUrl}${path}`);
         if (params) {
@@ -36,13 +93,13 @@ export class SlatesDesktopClient {
                 url.searchParams.set(k, String(v));
             }
         }
-        const res = await fetch(url.toString(), {
+        const res = await this.fetchOrFriendly(url.toString(), {
             headers: { Authorization: `Bearer ${this.token}` },
         });
         return this.handle(path, res);
     }
     async post(path, body) {
-        const res = await fetch(`${this.baseUrl}${path}`, {
+        const res = await this.fetchOrFriendly(`${this.baseUrl}${path}`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -52,6 +109,37 @@ export class SlatesDesktopClient {
         });
         return this.handle(path, res);
     }
+    // Network-level failures surface as a generic TypeError from fetch.
+    // Classify by the underlying error code: connection-class (ECONNREFUSED
+    // on a closed app, stale port after an app restart) → "open the app";
+    // timeout-class (undici headers/body timeout on a long blocking render,
+    // caller abort) → "may still be working — don't blind-retry"; anything
+    // else → rethrow with context, NOT a misleading unreachable message.
+    // HTTP-level errors still flow to handle().
+    async fetchOrFriendly(url, init) {
+        try {
+            return await fetch(url, init);
+        }
+        catch (err) {
+            const codes = fetchErrorCodes(err);
+            if (codes.some((c) => CONNECTION_ERROR_CODES.has(c))) {
+                throw new Error(DESKTOP_UNREACHABLE_MESSAGE);
+            }
+            const name = err?.name;
+            if (name === 'AbortError' || codes.some((c) => TIMEOUT_ERROR_CODES.has(c))) {
+                throw new Error(DESKTOP_TIMEOUT_MESSAGE);
+            }
+            let path = url;
+            try {
+                path = new URL(url).pathname;
+            }
+            catch {
+                // keep the full url
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`slates-desktop request to ${path} failed: ${message}`, { cause: err });
+        }
+    }
     async handle(path, res) {
         const text = await res.text();
         let parsed = null;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './auth.js';
 export { SlatesCloudClient, type SlatesUserInfo, type CreditsBalance, type ModelRegistryResponse } from './clients/cloud.js';
-export { SlatesDesktopClient } from './clients/desktop.js';
+export { SlatesDesktopClient, type DesktopHealth } from './clients/desktop.js';
+export { SKILLS } from './skills/content.js';
 export * as operations from './operations/index.js';
 export { ALL_OPERATIONS, defaultContext, type Operation, type OperationContext, type OperationResult } from './operations/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './auth.js';
 export { SlatesCloudClient } from './clients/cloud.js';
 export { SlatesDesktopClient } from './clients/desktop.js';
+export { SKILLS } from './skills/content.js';
 export * as operations from './operations/index.js';
 export { ALL_OPERATIONS, defaultContext } from './operations/index.js';
 //# sourceMappingURL=index.js.map

package/dist/operations/index.d.ts

@@ -44,6 +44,13 @@ export declare const getAssetImage: Operation<{
     id: string;
     fullRes?: boolean;
 }>;
+export declare const getAssetsBatch: Operation<{
+    ids: string[];
+}>;
+export declare const getAssetVideoFrames: Operation<{
+    id: string;
+    count?: number;
+}>;
 export declare const uploadReferenceImage: Operation<{
     projectId: string;
     filePath?: string;
@@ -113,11 +120,210 @@ export declare const addFrame: Operation<{
 }>;
 export declare const generateImage: Operation<{
     prompt: string;
+    model?: 'nano-banana-2' | 'flux-2-max' | 'seedream-5-lite';
+    projectId?: string;
     resolution?: '1k' | '2k' | '4k';
-    aspectRatio?: string;
+    aspectRatio?: '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '21:9' | '9:21' | '4:5' | '5:4' | '2:3' | '3:2';
     count?: number;
     referenceImageUrls?: string[];
+    referenceAssetIds?: string[];
+    background?: boolean;
+    confirm?: boolean;
+}>;
+export declare const editImage: Operation<{
+    projectId: string;
+    sourceAssetId: string;
+    prompt: string;
+    editModel?: 'nano-banana-2' | 'flux-2-max' | 'seedream-5-lite';
+    referenceAssetIds?: string[];
+    resolution?: '1k' | '2k' | '4k';
+    aspectRatio?: string;
     confirm?: boolean;
+    background?: boolean;
+}>;
+declare const VIDEO_MODELS: readonly ["kling-v3.0-std", "kling-v3.0-pro", "kling-v3.0-omni", "veo-3.1-fast", "veo-3.1-standard", "seedance-2-fast", "seedance-2-std"];
+type VideoModel = (typeof VIDEO_MODELS)[number];
+export declare const generateVideo: Operation<{
+    prompt: string;
+    model: VideoModel;
+    projectId?: string;
+    aspectRatio?: '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '21:9' | '9:21' | '4:5' | '5:4' | '2:3' | '3:2';
+    duration?: number;
+    videoResolution?: '720p' | '1080p' | '4k';
+    seedanceSpeed?: 'economy' | 'priority';
+    firstFrameAssetId?: string;
+    lastFrameAssetId?: string;
+    ingredientAssetIds?: string[];
+    sound?: boolean;
+    audioLanguage?: 'EN' | 'ZH' | 'JA' | 'KO' | 'ES';
+    generateMusic?: boolean;
+    negativePrompt?: string;
+    background?: boolean;
+    confirm?: boolean;
+}>;
+export declare const generateLipSync: Operation<{
+    projectId: string;
+    sourceAssetId: string;
+    sourceType: 'image' | 'video';
+    audioMethod: 'tts' | 'upload';
+    ttsText?: string;
+    ttsVoice?: string;
+    ttsLanguage?: 'EN' | 'ZH' | 'JA' | 'KO' | 'ES';
+    ttsSpeed?: number;
+    audioFilePath?: string;
+    avatarModel?: 'avatar-standard' | 'avatar-pro';
+    background?: boolean;
+    confirm?: boolean;
+}>;
+export declare const generateMotionTransfer: Operation<{
+    projectId: string;
+    sourceVideoAssetId: string;
+    targetImageAssetId: string;
+    motionModel?: 'kling-mc-std' | 'kling-mc-pro';
+    characterOrientation?: 'video' | 'image';
+    prompt?: string;
+    background?: boolean;
+    confirm?: boolean;
+}>;
+export declare const getGenerationStatus: Operation<{
+    generationId: string;
+}>;
+export declare const listGenerations: Operation<{
+    projectId?: string;
+    status?: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+    limit?: number;
+}>;
+export declare const getTimeline: Operation<{
+    projectId: string;
+}>;
+export declare const addClipToTimeline: Operation<{
+    projectId: string;
+    assetId: string;
+    trackId?: string;
+    startFrame?: number;
+    sourceInFrame?: number;
+    sourceOutFrame?: number;
+}>;
+export declare const reorderClips: Operation<{
+    trackId: string;
+    clipIds: string[];
+}>;
+export declare const removeClip: Operation<{
+    clipId: string;
+}>;
+export declare const exportVideo: Operation<{
+    projectId?: string;
+    timelineId?: string;
+    outputPath: string;
+    overwrite?: boolean;
+}>;
+export declare const exportTimelineXml: Operation<{
+    projectId?: string;
+    timelineId?: string;
+    outputPath: string;
+    overwrite?: boolean;
+}>;
+export declare const revealFile: Operation<{
+    path: string;
+}>;
+export declare const updateProject: Operation<{
+    id: string;
+    name?: string;
+    description?: string;
+}>;
+export declare const deleteProject: Operation<{
+    id: string;
+    confirm?: boolean;
+}>;
+export declare const getProjectDirectory: Operation<{
+    id: string;
+}>;
+export declare const deleteAsset: Operation<{
+    id: string;
+}>;
+export declare const renameFolder: Operation<{
+    folderId: string;
+    name: string;
+}>;
+export declare const deleteFolder: Operation<{
+    folderId: string;
+}>;
+export declare const setFolderCover: Operation<{
+    folderId: string;
+    assetId: string | null;
+}>;
+export declare const updateCharacter: Operation<{
+    characterId: string;
+    name?: string;
+    description?: string;
+    style?: 'realistic' | 'anime' | 'pixar' | 'comic-book';
+}>;
+export declare const deleteCharacter: Operation<{
+    characterId: string;
+}>;
+export declare const updateEnvironment: Operation<{
+    environmentId: string;
+    name?: string;
+    description?: string;
+    style?: 'realistic' | 'anime' | 'pixar' | 'comic-book';
+    gridAssetId?: string | null;
+}>;
+export declare const deleteEnvironment: Operation<{
+    environmentId: string;
+}>;
+export declare const listStyles: Operation<{
+    projectId: string;
+}>;
+export declare const createStyle: Operation<{
+    projectId: string;
+    name: string;
+    description?: string;
+}>;
+export declare const updateStyle: Operation<{
+    styleId: string;
+    name?: string;
+    description?: string;
+    imageAssetId?: string | null;
+}>;
+export declare const deleteStyle: Operation<{
+    styleId: string;
+}>;
+export declare const updateStoryboard: Operation<{
+    storyboardId: string;
+    name?: string;
+    description?: string;
+}>;
+export declare const deleteStoryboard: Operation<{
+    storyboardId: string;
+}>;
+export declare const updateScene: Operation<{
+    sceneId: string;
+    name?: string;
+    position?: number;
+}>;
+export declare const deleteScene: Operation<{
+    sceneId: string;
+}>;
+export declare const reorderScenes: Operation<{
+    storyboardId: string;
+    sceneIds: string[];
+}>;
+export declare const updateFrame: Operation<{
+    frameId: string;
+    shotLabel?: string;
+    notes?: string;
+    assetId?: string | null;
+    sceneId?: string | null;
+    position?: number;
+    frameType?: 'first' | 'last' | 'ingredient' | null;
+    motionPrompt?: string | null;
+}>;
+export declare const deleteFrame: Operation<{
+    frameId: string;
+}>;
+export declare const getPromptingGuide: Operation<{
+    topic: string;
 }>;
 export declare const ALL_OPERATIONS: ReadonlyArray<Operation<unknown>>;
+export {};
 //# sourceMappingURL=index.d.ts.map