march-ai-sdk 0.3.0 → 0.4.0

package/dist/index.js

@@ -409,32 +409,6 @@ var Message = class _Message {
     return this.attachmentClient.downloadAsBase64(this.attachment.url);
   }
 };
-var ArtifactTypeSchema = z.enum([
-  "document",
-  "image",
-  "iframe",
-  "video",
-  "audio",
-  "code",
-  "link",
-  "file"
-]);
-var ArtifactSchema = z.object({
-  url: z.string(),
-  type: ArtifactTypeSchema,
-  title: z.string().optional(),
-  description: z.string().optional(),
-  metadata: z.record(z.string(), z.unknown()).optional()
-});
-function toArtifact(input) {
-  return ArtifactSchema.parse({
-    url: input.url,
-    type: input.type,
-    title: input.title,
-    description: input.description,
-    metadata: input.metadata
-  });
-}
 
 // src/streamer.ts
 var Streamer = class {
@@ -446,9 +420,7 @@ var Streamer = class {
   awaiting;
   responseSchema;
   messageMetadata;
-  artifacts = [];
   streamedContent = "";
-  firstChunkSent = false;
   finished = false;
   constructor(options) {
     this.agentName = options.agentName;
@@ -473,18 +445,22 @@ var Streamer = class {
     return this;
   }
   /**
-   * Add an artifact to the message (fluent API).
+   * Bind a structural streamer to this streamer for event sending.
+   *
+   * Returns the structural object itself with streaming capability enabled.
+   *
+   * @param structural - StructuralStreamer instance (Artifact, Surface, etc.)
+   * @returns The same structural object, now bound to this streamer
+   *
+   * @example
+   * ```typescript
+   * const artifact = new Artifact()
+   * s.streamBy(artifact).generating("Creating...")
+   * s.streamBy(artifact).done({ url: "...", type: "image" })
+   * ```
    */
-  addArtifact(artifact) {
-    this.artifacts.push(toArtifact(artifact));
-    return this;
-  }
-  /**
-   * Set all artifacts at once (replaces any existing).
-   */
-  setArtifacts(artifacts) {
-    this.artifacts = artifacts.map(toArtifact);
-    return this;
+  streamBy(structural) {
+    return structural._bindStreamer(this);
   }
   /**
    * Stream a content chunk.
@@ -498,7 +474,7 @@ var Streamer = class {
     if (persist) {
       this.streamedContent += content;
     }
-    this.send(content, false, persist, eventType);
+    this._send(content, false, persist, eventType);
   }
   /**
    * Alias for stream() - write a content chunk.
@@ -518,7 +494,7 @@ var Streamer = class {
     if (this.responseSchema && awaitingOverride !== false) {
       finalAwaiting = true;
     }
-    this.send("", true, false);
+    this._send("", true, false);
     if (this.responseSchema && this.conversationClient) {
       await this.setPendingResponseSchema();
     }
@@ -528,8 +504,9 @@ var Streamer = class {
   }
   /**
    * Send message to router via gateway.
+   * This method is used internally and by structural streamers.
    */
-  send(content, done, persist = true, eventType) {
+  _send(content, done, persist = true, eventType) {
     const headers = {
       conversationId: this.originalMessage.conversationId,
       userId: this.originalMessage.userId,
@@ -540,14 +517,10 @@ var Streamer = class {
     if (eventType) {
       headers.eventType = eventType;
     }
-    if (!this.firstChunkSent) {
-      this.firstChunkSent = true;
+    if (this.streamedContent.length === 0 && !this.finished) {
       if (this.messageMetadata) {
         headers.messageMetadata = JSON.stringify(this.messageMetadata);
       }
-      if (this.artifacts.length > 0) {
-        headers.artifacts = JSON.stringify(this.artifacts);
-      }
       if (this.responseSchema) {
         headers.responseSchema = JSON.stringify(this.responseSchema);
       }
@@ -1515,6 +1488,341 @@ var MarchAgentApp = class {
   }
 };
 
+// src/structural/base.ts
+var StructuralStreamer = class {
+  id;
+  _streamer;
+  constructor(id) {
+    this.id = id ?? this._generateId();
+  }
+  /**
+   * Bind this structural streamer to a Streamer instance.
+   * Called by Streamer.streamBy(). Returns self for chaining.
+   */
+  _bindStreamer(streamer) {
+    this._streamer = streamer;
+    return this;
+  }
+  /**
+   * Send an event through the bound streamer.
+   *
+   * Creates event payload and sends via streamer._send().
+   * Returns self for method chaining.
+   */
+  _sendEvent(action, data = {}) {
+    if (!this._streamer) {
+      throw new Error(
+        `${this.constructor.name} not bound to a Streamer. Call streamer.streamBy() first.`
+      );
+    }
+    const body = { id: this.id, ...data };
+    const eventType = `${this.getEventTypePrefix()}:${action}`;
+    this._streamer._send(
+      JSON.stringify(body),
+      false,
+      // done
+      false,
+      // persist
+      eventType
+    );
+    return this;
+  }
+};
+function generateShortId() {
+  return Math.random().toString(16).slice(2, 10);
+}
+
+// src/structural/artifact.ts
+var Artifact = class extends StructuralStreamer {
+  _generateId() {
+    return `artifact-${generateShortId()}`;
+  }
+  getEventTypePrefix() {
+    return "artifact";
+  }
+  /**
+   * Signal artifact is being generated.
+   *
+   * @param message - Status message (e.g., "Creating chart...")
+   * @param progress - Progress value 0.0-1.0
+   * @returns this for method chaining
+   */
+  generating(message, progress) {
+    const data = {};
+    if (message !== void 0) {
+      data.message = message;
+    }
+    if (progress !== void 0) {
+      data.progress = progress;
+    }
+    return this._sendEvent("generating", data);
+  }
+  /**
+   * Signal artifact is complete and persist to database.
+   *
+   * @param options - Artifact completion options
+   * @param options.url - URL to artifact
+   * @param options.type - Artifact type (image, iframe, document, video, audio, code, link, file)
+   * @param options.title - Display title
+   * @param options.description - Optional description
+   * @param options.metadata - Additional metadata (size, mimeType, dimensions, etc.)
+   * @returns this for method chaining
+   */
+  done(options) {
+    const data = {
+      url: options.url,
+      type: options.type
+    };
+    if (options.title) {
+      data.title = options.title;
+    }
+    if (options.description) {
+      data.description = options.description;
+    }
+    if (options.metadata) {
+      data.metadata = options.metadata;
+    }
+    return this._sendEvent("done", data);
+  }
+  /**
+   * Signal artifact generation failed.
+   *
+   * @param message - Error message
+   * @returns this for method chaining
+   */
+  error(message) {
+    return this._sendEvent("error", { message });
+  }
+};
+
+// src/structural/surface.ts
+var Surface = class extends StructuralStreamer {
+  _generateId() {
+    return `surface-${generateShortId()}`;
+  }
+  getEventTypePrefix() {
+    return "surface";
+  }
+  /**
+   * Signal surface is loading.
+   *
+   * @param message - Status message (e.g., "Loading calendar...")
+   * @param progress - Progress value 0.0-1.0
+   * @returns this for method chaining
+   */
+  generating(message, progress) {
+    const data = {};
+    if (message !== void 0) {
+      data.message = message;
+    }
+    if (progress !== void 0) {
+      data.progress = progress;
+    }
+    return this._sendEvent("generating", data);
+  }
+  /**
+   * Signal surface is ready and persist to database.
+   *
+   * @param options - Surface completion options
+   * @param options.url - URL to surface
+   * @param options.type - Surface type (default: iframe)
+   * @param options.title - Display title
+   * @param options.description - Optional description
+   * @param options.metadata - Additional metadata
+   * @returns this for method chaining
+   */
+  done(options) {
+    const data = {
+      url: options.url,
+      type: options.type ?? "iframe"
+    };
+    if (options.title) {
+      data.title = options.title;
+    }
+    if (options.description) {
+      data.description = options.description;
+    }
+    if (options.metadata) {
+      data.metadata = options.metadata;
+    }
+    return this._sendEvent("done", data);
+  }
+  /**
+   * Signal surface loading failed.
+   *
+   * @param message - Error message
+   * @returns this for method chaining
+   */
+  error(message) {
+    return this._sendEvent("error", { message });
+  }
+};
+
+// src/structural/text-block.ts
+var TextBlock = class extends StructuralStreamer {
+  initialTitle;
+  constructor(options) {
+    super(options?.id);
+    this.initialTitle = options?.title;
+  }
+  _generateId() {
+    return `text_block-${generateShortId()}`;
+  }
+  getEventTypePrefix() {
+    return "text_block";
+  }
+  /**
+   * Stream title content (appends to existing).
+   *
+   * @param content - Content to append to title
+   * @returns this for method chaining
+   */
+  streamTitle(content) {
+    return this._sendEvent("stream_title", { content });
+  }
+  /**
+   * Stream body content (appends to existing).
+   *
+   * @param content - Content to append to body
+   * @returns this for method chaining
+   */
+  streamBody(content) {
+    return this._sendEvent("stream_body", { content });
+  }
+  /**
+   * Replace entire title.
+   *
+   * @param title - New title (replaces existing)
+   * @returns this for method chaining
+   */
+  updateTitle(title) {
+    return this._sendEvent("update_title", { title });
+  }
+  /**
+   * Replace entire body.
+   *
+   * @param body - New body (replaces existing)
+   * @returns this for method chaining
+   */
+  updateBody(body) {
+    return this._sendEvent("update_body", { body });
+  }
+  /**
+   * Set visual variant.
+   *
+   * @param variant - Visual style (thinking, note, warning, error, success)
+   * @returns this for method chaining
+   */
+  setVariant(variant) {
+    return this._sendEvent("set_variant", { variant });
+  }
+  /**
+   * Mark text block as complete.
+   *
+   * @returns this for method chaining
+   */
+  done() {
+    return this._sendEvent("done");
+  }
+};
+
+// src/structural/stepper.ts
+var Stepper = class extends StructuralStreamer {
+  steps;
+  _initialized = false;
+  constructor(options) {
+    super(options?.id);
+    this.steps = options?.steps ?? [];
+  }
+  _generateId() {
+    return `stepper-${generateShortId()}`;
+  }
+  getEventTypePrefix() {
+    return "stepper";
+  }
+  /**
+   * Send initialization event with steps if not already sent.
+   * This is automatically called before any other stepper event.
+   */
+  _ensureInitialized() {
+    if (!this._initialized && this.steps.length > 0) {
+      this._sendEvent("init", { steps: this.steps });
+      this._initialized = true;
+    }
+    return this;
+  }
+  /**
+   * Mark step as in progress.
+   *
+   * @param index - Step index to start
+   * @returns this for method chaining
+   */
+  startStep(index) {
+    this._ensureInitialized();
+    return this._sendEvent("start_step", { index });
+  }
+  /**
+   * Mark step as complete.
+   *
+   * @param index - Step index to complete
+   * @returns this for method chaining
+   */
+  completeStep(index) {
+    this._ensureInitialized();
+    return this._sendEvent("complete_step", { index });
+  }
+  /**
+   * Mark step as failed.
+   *
+   * @param index - Step index that failed
+   * @param error - Optional error message
+   * @returns this for method chaining
+   */
+  failStep(index, error) {
+    this._ensureInitialized();
+    const data = { index };
+    if (error) {
+      data.error = error;
+    }
+    return this._sendEvent("fail_step", data);
+  }
+  /**
+   * Add a new step dynamically.
+   *
+   * @param label - Step label
+   * @param index - Optional position to insert at
+   * @returns this for method chaining
+   */
+  addStep(label, index) {
+    this._ensureInitialized();
+    const data = { label };
+    if (index !== void 0) {
+      data.index = index;
+    }
+    return this._sendEvent("add_step", data);
+  }
+  /**
+   * Update step label.
+   *
+   * @param index - Step index to update
+   * @param label - New label
+   * @returns this for method chaining
+   */
+  updateStepLabel(index, label) {
+    this._ensureInitialized();
+    return this._sendEvent("update_step_label", { index, label });
+  }
+  /**
+   * Mark stepper as complete (all steps finished).
+   *
+   * @returns this for method chaining
+   */
+  done() {
+    this._ensureInitialized();
+    return this._sendEvent("done");
+  }
+};
+
 // src/checkpoint-client.ts
 var CheckpointClient = class {
   baseUrl;
@@ -1688,8 +1996,8 @@ var AgentStateClient = class {
 };
 
 // src/index.ts
-var VERSION = "0.3.0";
+var VERSION = "0.4.0";
 
-export { AI_INVENTORY_PATHS, APIException, Agent, AgentStateClient, AttachmentClient, CONVERSATION_STORE_PATHS, CheckpointClient, ConfigurationError, Conversation, ConversationClient, ConversationMessage, GatewayClient, GatewayError, HeartbeatError, HeartbeatManager, KafkaError, MEMORY_PATHS, MarchAgentApp, MarchAgentError, Memory, MemoryClient, Message, RegistrationError, SERVICES, SenderFilter, Streamer, VERSION, createAttachmentInfo, toArtifact };
+export { AI_INVENTORY_PATHS, APIException, Agent, AgentStateClient, Artifact, AttachmentClient, CONVERSATION_STORE_PATHS, CheckpointClient, ConfigurationError, Conversation, ConversationClient, ConversationMessage, GatewayClient, GatewayError, HeartbeatError, HeartbeatManager, KafkaError, MEMORY_PATHS, MarchAgentApp, MarchAgentError, Memory, MemoryClient, Message, RegistrationError, SERVICES, SenderFilter, Stepper, Streamer, StructuralStreamer, Surface, TextBlock, VERSION, createAttachmentInfo };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map