@slopmachine/core 0.1.25 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @slopmachine/core
+
+## 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,9 +1,120 @@
-type ImageAspectRatio = "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "4:5" | "5:4" | "9:16" | "16:9" | "21:9";
+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.
      */
-    bucketId: string;
+    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.
+     */
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -18,7 +129,7 @@ interface SlopImageOptions {
      * The aspect ratio of the generated image. Defaults to "1:1".
      * Common values: "1:1", "16:9", "9:16", "4:3", "3:4".
      */
-    aspectRatio?: ImageAspectRatio;
+    aspectRatio?: AspectRatio;
     /**
      * Dynamic variables to interpolate into the prompt.
      * E.g., if prompt is "A photo of a {color} dog", pass { color: "brown" }.
@@ -49,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.
  */
@@ -61,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>;
-type VideoAspectRatio = "9:16" | "16:9";
 interface SlopVideoOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
      */
-    bucketId: string;
+    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.
+     */
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -116,6 +246,8 @@ interface SlopVideoOptions {
 /**
  * Builds a URL to render or retrieve a video from Slop Machine.
  *
+ * 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.
  */
@@ -131,8 +263,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.
@@ -161,6 +311,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.
  */
@@ -173,6 +325,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.
  *
@@ -184,4 +350,4 @@ declare function uploadTempAttachment(base64: string, mimeType: string): Promise
     url: string;
 }>;
 
-export { type ImageAspectRatio, type SlopImageOptions, type SlopTextOptions, type SlopVideoOptions, type VideoAspectRatio, 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,9 +1,120 @@
-type ImageAspectRatio = "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "4:5" | "5:4" | "9:16" | "16:9" | "21:9";
+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.
      */
-    bucketId: string;
+    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.
+     */
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -18,7 +129,7 @@ interface SlopImageOptions {
      * The aspect ratio of the generated image. Defaults to "1:1".
      * Common values: "1:1", "16:9", "9:16", "4:3", "3:4".
      */
-    aspectRatio?: ImageAspectRatio;
+    aspectRatio?: AspectRatio;
     /**
      * Dynamic variables to interpolate into the prompt.
      * E.g., if prompt is "A photo of a {color} dog", pass { color: "brown" }.
@@ -49,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.
  */
@@ -61,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>;
-type VideoAspectRatio = "9:16" | "16:9";
 interface SlopVideoOptions {
     /**
      * The unique identifier of your Slop Machine bucket.
+     * Required when using a bucket unless pipelineId is provided.
      */
-    bucketId: string;
+    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.
+     */
+    metadata?: Record<string, any>;
     /**
      * The specific version of the prompt/settings to use.
      * If omitted, the latest version will be used.
@@ -116,6 +246,8 @@ interface SlopVideoOptions {
 /**
  * Builds a URL to render or retrieve a video from Slop Machine.
  *
+ * 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.
  */
@@ -131,8 +263,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.
@@ -161,6 +311,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.
  */
@@ -173,6 +325,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.
  *
@@ -184,4 +350,4 @@ declare function uploadTempAttachment(base64: string, mimeType: string): Promise
     url: string;
 }>;
 
-export { type ImageAspectRatio, type SlopImageOptions, type SlopTextOptions, type SlopVideoOptions, type VideoAspectRatio, 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 };