@slopmachine/core 0.1.26 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @slopmachine/core
+
+## 0.3.0
+
+### Minor Changes
+
+- fbdeaec: Omit default duration in buildVideoUrl so requests fall back to the bucket version's configured duration on the server
+
+## 0.2.0
+
+### Minor Changes
+
+- 15b923d: Switch pipeline execution parameters to use pipelineId (with optional siloId) instead of pipelineKey.

package/README.md

@@ -1,6 +1,6 @@
 # @slopmachine/core
 
-The core logic and shared utilities for the Slop Machine SDK.
+The core logic, URL builders, preloader utilities, and type definitions for the Slop Machine SDK.
 
 ## Installation
 
@@ -12,9 +12,28 @@ yarn add @slopmachine/core
 pnpm add @slopmachine/core
 ```
 
-## Usage
+## Features
 
-This package provides the core functions and type definitions used by the Slop Machine framework integrations (like `@slopmachine/react` and `@slopmachine/svelte`).
+- **URL Builders**: `buildImageUrl`, `buildVideoUrl`, `buildTextUrl`, and `buildPipelineUrl` for safe, deterministic API URL generation.
+- **Preloaders**: `preloadImage`, `preloadVideo`, and `preloadText` to cache assets ahead of time in client applications.
+- **Multi-Step Pipelines**: Programmatic execution via `executePipeline({ pipelineId, prompt, variables, metadata })`.
+- **Buckets & Pipelines Support**: Seamlessly switch between pre-templated Buckets and dynamic runtime Pipelines.
+
+## Programmatic Pipeline Execution
+
+```typescript
+import { executePipeline } from "@slopmachine/core";
+
+const result = await executePipeline({
+  pipelineId: "pipe_live_abc123",
+  prompt: "A cinematic tracking shot through a cyberpunk alleyway",
+  metadata: { userId: "usr_42" },
+});
+
+console.log("Output URL:", result.url);
+console.log("Fuel Cost:", result.totalFuelCost);
+console.log("Steps executed:", result.stepResults.length);
+```
 
 ## License
 

package/dist/index.d.mts

@@ -1,11 +1,120 @@
 import { AspectRatio, VideoAspectRatio } from '@pixerate/schemas';
 export { AspectRatio as ImageAspectRatio, VideoAspectRatio } from '@pixerate/schemas';
 
+interface PipelineStepResult {
+    stepId: string;
+    stepName?: string;
+    type: string;
+    outputUrl?: string;
+    outputText?: string;
+    outputData?: any;
+    computeTimeMs?: number;
+    fuelCost?: number;
+    error?: string;
+}
+interface PipelineResult {
+    id: string;
+    pipelineId: string;
+    siloId: string;
+    url?: string;
+    text?: string;
+    data?: any;
+    resultType: string;
+    status: "completed" | "failed" | "pending";
+    stepResults: PipelineStepResult[];
+    totalComputeTimeMs: number;
+    totalFuelCost: number;
+    metadata?: Record<string, any>;
+    timestamp: any;
+    error?: string;
+}
+interface SlopPipelineOptions {
+    /**
+     * The unique identifier of the pipeline to execute.
+     */
+    pipelineId: string;
+    /**
+     * Optional silo identifier for direct pipeline path resolution.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt to feed into the pipeline.
+     */
+    prompt?: string;
+    /**
+     * Variables to interpolate into prompt or step configs.
+     */
+    variables?: Record<string, string | number | undefined | null>;
+    /**
+     * Arbitrary user metadata to attach to the pipeline result document.
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Whether to wait for full execution (default true) or return a job ID immediately.
+     */
+    sync?: boolean;
+    /**
+     * Whether to redirect to the primary media output URL upon completion.
+     */
+    redirect?: boolean;
+    /**
+     * Result ID to retrieve a specific previously generated result.
+     */
+    resultId?: string;
+    /**
+     * Base URL for the renderPipeline cloud function endpoint.
+     */
+    baseUrl?: string;
+}
+interface ExecutePipelineOptions {
+    /**
+     * The unique identifier of the pipeline to execute.
+     */
+    pipelineId: string;
+    /**
+     * Optional silo identifier for direct pipeline path resolution.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt to feed into the pipeline.
+     */
+    prompt?: string;
+    /**
+     * Variables to interpolate into prompt or step configs.
+     */
+    variables?: Record<string, string | number | undefined | null>;
+    /**
+     * Arbitrary user metadata to attach to the pipeline result document.
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Base URL for the renderPipeline cloud function endpoint.
+     */
+    baseUrl?: string;
+}
 interface SlopImageOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
+     */
+    bucketId?: string;
+    /**
+     * The unique identifier of your Slop Machine pipeline.
+     * Required when targeting a pipeline instead of a bucket.
+     */
+    pipelineId?: string;
+    /**
+     * Optional silo identifier.
      */
-    bucketId: string;
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt (used when targeting a pipeline).
+     */
+    prompt?: string;
+    /**
+     * Arbitrary user metadata to attach to the generation request / result document.
+     */
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -51,6 +160,8 @@ declare function interpolatePrompt(prompt?: string, variables?: Record<string, s
 /**
  * Builds a URL to render or retrieve an image from Slop Machine.
  *
+ * Supports both standard Buckets (via `bucketId`) and multi-step Pipelines (via `pipelineId`).
+ *
  * @param options - Configuration options for the image generation.
  * @returns A string containing the fully constructed URL.
  */
@@ -63,12 +174,29 @@ declare function buildImageUrl(options: SlopImageOptions): string;
  * @returns A promise that resolves when the image has been loaded.
  */
 declare function preloadImage(options: SlopImageOptions): Promise<void>;
-
 interface SlopVideoOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
+     */
+    bucketId?: string;
+    /**
+     * The unique identifier of your Slop Machine pipeline.
+     * Required when targeting a pipeline instead of a bucket.
+     */
+    pipelineId?: string;
+    /**
+     * Optional silo identifier.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt (used when targeting a pipeline).
+     */
+    prompt?: string;
+    /**
+     * Arbitrary user metadata to attach to the generation request / result document.
      */
-    bucketId: string;
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -91,7 +219,7 @@ interface SlopVideoOptions {
     variables?: Record<string, string | number | undefined | null>;
     /**
      * The duration of the generated video in seconds.
-     * Must be between 4 and 8. Defaults to 4.
+     * If not specified, defaults to the bucket version's configured duration (or 4).
      */
     duration?: number;
     /**
@@ -106,17 +234,18 @@ interface SlopVideoOptions {
      */
     baseUrl?: string;
     /**
-     * If `true` (or `?raw=true`), bypasses the WebP optimized media and returns the original generated file.
-     * Defaults to false.
+     * If true, serves the original generated uncompressed asset directly from storage.
      */
     original?: boolean;
     /**
-     * Array of attachment URLs to include with the request.
+     * Array of runtime image attachments (URLs) to use with the video model.
+     * Only allowed if the bucket version has runtime attachments enabled.
      */
     attachments?: string[];
 }
 /**
- * Builds a URL to render or retrieve a video from Slop Machine.
+ * Builds the URL to render or stream an AI-generated video.
+ * Supports both standard Buckets (via `bucketId`) and multi-step Pipelines (via `pipelineId`).
  *
  * @param options - Configuration options for the video generation.
  * @returns A string containing the fully constructed URL.
@@ -133,8 +262,26 @@ declare function preloadVideo(options: SlopVideoOptions): Promise<void>;
 interface SlopTextOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
+     */
+    bucketId?: string;
+    /**
+     * The unique identifier of your Slop Machine pipeline.
+     * Required when targeting a pipeline instead of a bucket.
+     */
+    pipelineId?: string;
+    /**
+     * Optional silo identifier.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt (used when targeting a pipeline).
+     */
+    prompt?: string;
+    /**
+     * Arbitrary user metadata to attach to the generation request / result document.
      */
-    bucketId: string;
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -163,6 +310,8 @@ interface SlopTextOptions {
 /**
  * Builds a URL to render or retrieve text from Slop Machine.
  *
+ * Supports both standard Buckets (via `bucketId`) and multi-step Pipelines (via `pipelineId`).
+ *
  * @param options - Configuration options for the text generation.
  * @returns A string containing the fully constructed URL.
  */
@@ -175,6 +324,20 @@ declare function buildTextUrl(options: SlopTextOptions): string;
  * @returns A promise that resolves when the text preload request has been initiated.
  */
 declare function preloadText(options: SlopTextOptions): Promise<void>;
+/**
+ * Builds a URL to execute or inspect a multi-step Pipeline from Slop Machine.
+ *
+ * @param options - Configuration options for the pipeline execution.
+ * @returns A string containing the fully constructed URL.
+ */
+declare function buildPipelineUrl(options: SlopPipelineOptions): string;
+/**
+ * Executes a Slop Machine multi-step Pipeline programmatically and returns the full typed result payload.
+ *
+ * @param options - Execution parameters including the pipelineId and runtime prompt/variables/metadata.
+ * @returns A promise resolving to the completed PipelineResult document.
+ */
+declare function executePipeline(options: ExecutePipelineOptions): Promise<PipelineResult>;
 /**
  * Uploads a base64 encoded file as a temporary attachment to be used in generation requests.
  *
@@ -186,4 +349,4 @@ declare function uploadTempAttachment(base64: string, mimeType: string): Promise
     url: string;
 }>;
 
-export { type SlopImageOptions, type SlopTextOptions, type SlopVideoOptions, buildImageUrl, buildTextUrl, buildVideoUrl, interpolatePrompt, preloadImage, preloadText, preloadVideo, uploadTempAttachment };
+export { type ExecutePipelineOptions, type PipelineResult, type PipelineStepResult, type SlopImageOptions, type SlopPipelineOptions, type SlopTextOptions, type SlopVideoOptions, buildImageUrl, buildPipelineUrl, buildTextUrl, buildVideoUrl, executePipeline, interpolatePrompt, preloadImage, preloadText, preloadVideo, uploadTempAttachment };

package/dist/index.d.ts

@@ -1,11 +1,120 @@
 import { AspectRatio, VideoAspectRatio } from '@pixerate/schemas';
 export { AspectRatio as ImageAspectRatio, VideoAspectRatio } from '@pixerate/schemas';
 
+interface PipelineStepResult {
+    stepId: string;
+    stepName?: string;
+    type: string;
+    outputUrl?: string;
+    outputText?: string;
+    outputData?: any;
+    computeTimeMs?: number;
+    fuelCost?: number;
+    error?: string;
+}
+interface PipelineResult {
+    id: string;
+    pipelineId: string;
+    siloId: string;
+    url?: string;
+    text?: string;
+    data?: any;
+    resultType: string;
+    status: "completed" | "failed" | "pending";
+    stepResults: PipelineStepResult[];
+    totalComputeTimeMs: number;
+    totalFuelCost: number;
+    metadata?: Record<string, any>;
+    timestamp: any;
+    error?: string;
+}
+interface SlopPipelineOptions {
+    /**
+     * The unique identifier of the pipeline to execute.
+     */
+    pipelineId: string;
+    /**
+     * Optional silo identifier for direct pipeline path resolution.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt to feed into the pipeline.
+     */
+    prompt?: string;
+    /**
+     * Variables to interpolate into prompt or step configs.
+     */
+    variables?: Record<string, string | number | undefined | null>;
+    /**
+     * Arbitrary user metadata to attach to the pipeline result document.
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Whether to wait for full execution (default true) or return a job ID immediately.
+     */
+    sync?: boolean;
+    /**
+     * Whether to redirect to the primary media output URL upon completion.
+     */
+    redirect?: boolean;
+    /**
+     * Result ID to retrieve a specific previously generated result.
+     */
+    resultId?: string;
+    /**
+     * Base URL for the renderPipeline cloud function endpoint.
+     */
+    baseUrl?: string;
+}
+interface ExecutePipelineOptions {
+    /**
+     * The unique identifier of the pipeline to execute.
+     */
+    pipelineId: string;
+    /**
+     * Optional silo identifier for direct pipeline path resolution.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt to feed into the pipeline.
+     */
+    prompt?: string;
+    /**
+     * Variables to interpolate into prompt or step configs.
+     */
+    variables?: Record<string, string | number | undefined | null>;
+    /**
+     * Arbitrary user metadata to attach to the pipeline result document.
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Base URL for the renderPipeline cloud function endpoint.
+     */
+    baseUrl?: string;
+}
 interface SlopImageOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
+     */
+    bucketId?: string;
+    /**
+     * The unique identifier of your Slop Machine pipeline.
+     * Required when targeting a pipeline instead of a bucket.
+     */
+    pipelineId?: string;
+    /**
+     * Optional silo identifier.
      */
-    bucketId: string;
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt (used when targeting a pipeline).
+     */
+    prompt?: string;
+    /**
+     * Arbitrary user metadata to attach to the generation request / result document.
+     */
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -51,6 +160,8 @@ declare function interpolatePrompt(prompt?: string, variables?: Record<string, s
 /**
  * Builds a URL to render or retrieve an image from Slop Machine.
  *
+ * Supports both standard Buckets (via `bucketId`) and multi-step Pipelines (via `pipelineId`).
+ *
  * @param options - Configuration options for the image generation.
  * @returns A string containing the fully constructed URL.
  */
@@ -63,12 +174,29 @@ declare function buildImageUrl(options: SlopImageOptions): string;
  * @returns A promise that resolves when the image has been loaded.
  */
 declare function preloadImage(options: SlopImageOptions): Promise<void>;
-
 interface SlopVideoOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
+     */
+    bucketId?: string;
+    /**
+     * The unique identifier of your Slop Machine pipeline.
+     * Required when targeting a pipeline instead of a bucket.
+     */
+    pipelineId?: string;
+    /**
+     * Optional silo identifier.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt (used when targeting a pipeline).
+     */
+    prompt?: string;
+    /**
+     * Arbitrary user metadata to attach to the generation request / result document.
      */
-    bucketId: string;
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -91,7 +219,7 @@ interface SlopVideoOptions {
     variables?: Record<string, string | number | undefined | null>;
     /**
      * The duration of the generated video in seconds.
-     * Must be between 4 and 8. Defaults to 4.
+     * If not specified, defaults to the bucket version's configured duration (or 4).
      */
     duration?: number;
     /**
@@ -106,17 +234,18 @@ interface SlopVideoOptions {
      */
     baseUrl?: string;
     /**
-     * If `true` (or `?raw=true`), bypasses the WebP optimized media and returns the original generated file.
-     * Defaults to false.
+     * If true, serves the original generated uncompressed asset directly from storage.
      */
     original?: boolean;
     /**
-     * Array of attachment URLs to include with the request.
+     * Array of runtime image attachments (URLs) to use with the video model.
+     * Only allowed if the bucket version has runtime attachments enabled.
      */
     attachments?: string[];
 }
 /**
- * Builds a URL to render or retrieve a video from Slop Machine.
+ * Builds the URL to render or stream an AI-generated video.
+ * Supports both standard Buckets (via `bucketId`) and multi-step Pipelines (via `pipelineId`).
  *
  * @param options - Configuration options for the video generation.
  * @returns A string containing the fully constructed URL.
@@ -133,8 +262,26 @@ declare function preloadVideo(options: SlopVideoOptions): Promise<void>;
 interface SlopTextOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
+     */
+    bucketId?: string;
+    /**
+     * The unique identifier of your Slop Machine pipeline.
+     * Required when targeting a pipeline instead of a bucket.
+     */
+    pipelineId?: string;
+    /**
+     * Optional silo identifier.
+     */
+    siloId?: string;
+    /**
+     * Dynamic runtime prompt (used when targeting a pipeline).
+     */
+    prompt?: string;
+    /**
+     * Arbitrary user metadata to attach to the generation request / result document.
      */
-    bucketId: string;
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -163,6 +310,8 @@ interface SlopTextOptions {
 /**
  * Builds a URL to render or retrieve text from Slop Machine.
  *
+ * Supports both standard Buckets (via `bucketId`) and multi-step Pipelines (via `pipelineId`).
+ *
  * @param options - Configuration options for the text generation.
  * @returns A string containing the fully constructed URL.
  */
@@ -175,6 +324,20 @@ declare function buildTextUrl(options: SlopTextOptions): string;
  * @returns A promise that resolves when the text preload request has been initiated.
  */
 declare function preloadText(options: SlopTextOptions): Promise<void>;
+/**
+ * Builds a URL to execute or inspect a multi-step Pipeline from Slop Machine.
+ *
+ * @param options - Configuration options for the pipeline execution.
+ * @returns A string containing the fully constructed URL.
+ */
+declare function buildPipelineUrl(options: SlopPipelineOptions): string;
+/**
+ * Executes a Slop Machine multi-step Pipeline programmatically and returns the full typed result payload.
+ *
+ * @param options - Execution parameters including the pipelineId and runtime prompt/variables/metadata.
+ * @returns A promise resolving to the completed PipelineResult document.
+ */
+declare function executePipeline(options: ExecutePipelineOptions): Promise<PipelineResult>;
 /**
  * Uploads a base64 encoded file as a temporary attachment to be used in generation requests.
  *
@@ -186,4 +349,4 @@ declare function uploadTempAttachment(base64: string, mimeType: string): Promise
     url: string;
 }>;
 
-export { type SlopImageOptions, type SlopTextOptions, type SlopVideoOptions, buildImageUrl, buildTextUrl, buildVideoUrl, interpolatePrompt, preloadImage, preloadText, preloadVideo, uploadTempAttachment };
+export { type ExecutePipelineOptions, type PipelineResult, type PipelineStepResult, type SlopImageOptions, type SlopPipelineOptions, type SlopTextOptions, type SlopVideoOptions, buildImageUrl, buildPipelineUrl, buildTextUrl, buildVideoUrl, executePipeline, interpolatePrompt, preloadImage, preloadText, preloadVideo, uploadTempAttachment };