vessels-sdk 0.12.0 → 0.14.0

package/dist/index.cjs

@@ -75,7 +75,10 @@ var CardFieldSchema = zod.z.object({
   value: zod.z.string()
 });
 var CardSchema = zod.z.object({
-  title: zod.z.string().min(1),
+  // Optional: a glance-facts card under a surface takes its heading from the
+  // surface `title`, so a card title is redundant there. Still allowed (e.g. a
+  // standalone card on a bubble, or a pinned card).
+  title: zod.z.string().min(1).optional(),
   fields: zod.z.array(CardFieldSchema)
 });
 var AttachmentSchema = zod.z.discriminatedUnion("type", [
@@ -83,6 +86,8 @@ var AttachmentSchema = zod.z.discriminatedUnion("type", [
   zod.z.object({ type: zod.z.literal("file"), url: zod.z.string().url(), filename: zod.z.string().optional() })
 ]);
 var VesselStatusSchema = zod.z.enum(["active", "waiting", "resolved"]);
+var DisplaySchema = zod.z.enum(["bubble", "document"]);
+var KindSchema = zod.z.enum(["bubble", "surface"]);
 var PushPayloadSchema = zod.z.object({
   message: zod.z.string().min(1).max(1e4).optional(),
   vessel: zod.z.string().optional(),
@@ -107,7 +112,13 @@ var PushPayloadSchema = zod.z.object({
    * window, not a transcript: send the tail you want shown (the SDK trims to the
    * last 8000 chars). Plaintext, like agentActivity. Vanishes when cleared.
    */
-  tokenStream: zod.z.string().max(8e3).optional()
+  tokenStream: zod.z.string().max(8e3).optional(),
+  /** Bubble (chat) vs surface (composed artifact). Defaults from interaction/card. */
+  kind: KindSchema.optional(),
+  /** Surface heading. Ignored on bubbles. */
+  title: zod.z.string().max(200).optional(),
+  /** @deprecated legacy presentation hint — use `kind`. 'document' → surface. */
+  display: DisplaySchema.optional()
 }).refine((d) => d.message || d.agentActivity || d.tokenStream, {
   message: "One of message, agentActivity, or tokenStream is required"
 });
@@ -124,7 +135,11 @@ var PushManyPayloadSchema = zod.z.object({
   metadata: zod.z.record(zod.z.unknown()).refine(
     (v) => JSON.stringify(v).length < 16e3,
     "metadata exceeds 16KB limit"
-  ).optional()
+  ).optional(),
+  kind: KindSchema.optional(),
+  title: zod.z.string().max(200).optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.optional()
 });
 zod.z.object({
   content: zod.z.string().min(1).max(1e4).optional(),
@@ -133,7 +148,13 @@ zod.z.object({
   suggestions: zod.z.array(zod.z.string().min(1).max(500)).max(5).nullable().optional(),
   agentActivity: AgentActivitySchema.nullable().optional(),
   /** Replace the live token-stream window, or `null` to clear it (block vanishes). */
-  tokenStream: zod.z.string().max(8e3).nullable().optional()
+  tokenStream: zod.z.string().max(8e3).nullable().optional(),
+  /** Switch kind: 'surface' = full-width artifact, 'bubble' or null = chat bubble. */
+  kind: KindSchema.nullable().optional(),
+  /** Update the surface heading, or `null` to clear it. */
+  title: zod.z.string().max(200).nullable().optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.nullable().optional()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
@@ -193,6 +214,11 @@ var WebhookInteractionResponsePayloadSchema = zod.z.object({
     vessel: WebhookVesselSchema
   })
 });
+var SupersededInteractionSchema = zod.z.object({
+  message_id: zod.z.string(),
+  interaction_type: InteractionTypeSchema,
+  prompt: zod.z.string().nullable()
+});
 var WebhookUserMessagePayloadSchema = zod.z.object({
   event: zod.z.literal("message.user"),
   vessel_id: zod.z.string(),
@@ -202,7 +228,8 @@ var WebhookUserMessagePayloadSchema = zod.z.object({
     message_id: zod.z.string(),
     content: zod.z.string(),
     vessel: WebhookVesselSchema,
-    context: zod.z.array(WebhookContextMessageSchema)
+    context: zod.z.array(WebhookContextMessageSchema),
+    superseded_interaction: SupersededInteractionSchema.optional()
   })
 });
 var WebhookVesselCreatedPayloadSchema = zod.z.object({
@@ -361,6 +388,31 @@ var Vessels = class {
       replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
+  /**
+   * Create a **surface** — a full-width composed artifact the human reviews and
+   * optionally acts on, rendered as one piece: a `title` heading, an optional
+   * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+   * lists, blockquotes, bold headings, links), and an optional `interaction`
+   * (the action bar). Use this for an email/message draft, a quote, an invoice
+   * review, a proposal, a report — anything substantial and structured.
+   *
+   * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+   * message content. For conversation, status updates and quick questions, use
+   * {@link push} instead (a chat **bubble** — the human just replies).
+   *
+   * @example
+   * await vessels.surface({
+   *   vessel: 'inv-42',
+   *   title: 'GreenTurf Invoice #GTL-2025-042',
+   *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+   *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+   *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+   * });
+   */
+  async surface(options) {
+    const { body, ...rest } = options;
+    return this.push({ ...rest, message: body, kind: "surface" });
+  }
   async pushMany(payload) {
     const { idempotencyKey, ...body } = payload;
     const check = PushManyPayloadSchema.safeParse(body);
@@ -623,7 +675,12 @@ var Vessels = class {
         timestamp: e.timestamp,
         vessel,
         message: { id: e.message?.id, content: e.message?.content ?? null },
-        context: []
+        context: [],
+        supersededInteraction: e.superseded_interaction ? {
+          messageId: e.superseded_interaction.message_id,
+          interactionType: e.superseded_interaction.interaction_type,
+          prompt: e.superseded_interaction.prompt ?? null
+        } : null
       };
     });
     return { ok: true, events, hasMore: data.has_more ?? false };
@@ -724,7 +781,12 @@ var Vessels = class {
             source: m.source,
             content: m.content ?? null,
             createdAt: m.created_at
-          }))
+          })),
+          supersededInteraction: raw.data.superseded_interaction ? {
+            messageId: raw.data.superseded_interaction.message_id,
+            interactionType: raw.data.superseded_interaction.interaction_type,
+            prompt: raw.data.superseded_interaction.prompt ?? null
+          } : null
         };
       }
       return null;

package/dist/index.d.cts

@@ -106,6 +106,14 @@ interface PushResponse {
     /** True when this response is a replay of an earlier request with the same idempotency key. */
     replayed: boolean;
 }
+/**
+ * Options for {@link Vessels.surface}. Same as a push, but the artifact text is
+ * `body` (not `message`) and `kind` is forced to `'surface'`.
+ */
+type SurfaceOptions = Omit<_vessels_types.PushOptions, 'message' | 'kind'> & {
+    /** The artifact body — block markdown (tables, lists, blockquotes, bold headings, links). */
+    body: string;
+};
 interface PushManyResult {
     ok: true;
     results: Array<{
@@ -170,6 +178,16 @@ interface UserMessageEvent {
         content: string | null;
         createdAt: string;
     }>;
+    /**
+     * Set when this message arrived while an agent interaction was still live — it
+     * expired that card. The "they ignored what I presented and said this instead"
+     * signal; null when the message didn't supersede anything.
+     */
+    supersededInteraction: {
+        messageId: string;
+        interactionType: _vessels_types.InteractionType;
+        prompt: string | null;
+    } | null;
 }
 /**
  * Fired when a human opens a new typed vessel from the app (user-initiated
@@ -233,6 +251,28 @@ declare class Vessels {
     /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
     validatePushMany(payload: _vessels_types.PushManyOptions): ValidationResult;
     push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
+    /**
+     * Create a **surface** — a full-width composed artifact the human reviews and
+     * optionally acts on, rendered as one piece: a `title` heading, an optional
+     * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+     * lists, blockquotes, bold headings, links), and an optional `interaction`
+     * (the action bar). Use this for an email/message draft, a quote, an invoice
+     * review, a proposal, a report — anything substantial and structured.
+     *
+     * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+     * message content. For conversation, status updates and quick questions, use
+     * {@link push} instead (a chat **bubble** — the human just replies).
+     *
+     * @example
+     * await vessels.surface({
+     *   vessel: 'inv-42',
+     *   title: 'GreenTurf Invoice #GTL-2025-042',
+     *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+     *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+     *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+     * });
+     */
+    surface(options: SurfaceOptions): Promise<PushResponse>;
     pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
@@ -315,4 +355,4 @@ declare class Vessels {
     parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent | MessageCancelledEvent | null>;
 }
 
-export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type StreamHandle, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };
+export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type StreamHandle, type SurfaceOptions, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };

package/dist/index.d.ts

@@ -106,6 +106,14 @@ interface PushResponse {
     /** True when this response is a replay of an earlier request with the same idempotency key. */
     replayed: boolean;
 }
+/**
+ * Options for {@link Vessels.surface}. Same as a push, but the artifact text is
+ * `body` (not `message`) and `kind` is forced to `'surface'`.
+ */
+type SurfaceOptions = Omit<_vessels_types.PushOptions, 'message' | 'kind'> & {
+    /** The artifact body — block markdown (tables, lists, blockquotes, bold headings, links). */
+    body: string;
+};
 interface PushManyResult {
     ok: true;
     results: Array<{
@@ -170,6 +178,16 @@ interface UserMessageEvent {
         content: string | null;
         createdAt: string;
     }>;
+    /**
+     * Set when this message arrived while an agent interaction was still live — it
+     * expired that card. The "they ignored what I presented and said this instead"
+     * signal; null when the message didn't supersede anything.
+     */
+    supersededInteraction: {
+        messageId: string;
+        interactionType: _vessels_types.InteractionType;
+        prompt: string | null;
+    } | null;
 }
 /**
  * Fired when a human opens a new typed vessel from the app (user-initiated
@@ -233,6 +251,28 @@ declare class Vessels {
     /** Like {@link validatePush}, but for a `pushMany()` broadcast payload. */
     validatePushMany(payload: _vessels_types.PushManyOptions): ValidationResult;
     push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
+    /**
+     * Create a **surface** — a full-width composed artifact the human reviews and
+     * optionally acts on, rendered as one piece: a `title` heading, an optional
+     * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+     * lists, blockquotes, bold headings, links), and an optional `interaction`
+     * (the action bar). Use this for an email/message draft, a quote, an invoice
+     * review, a proposal, a report — anything substantial and structured.
+     *
+     * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+     * message content. For conversation, status updates and quick questions, use
+     * {@link push} instead (a chat **bubble** — the human just replies).
+     *
+     * @example
+     * await vessels.surface({
+     *   vessel: 'inv-42',
+     *   title: 'GreenTurf Invoice #GTL-2025-042',
+     *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+     *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+     *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+     * });
+     */
+    surface(options: SurfaceOptions): Promise<PushResponse>;
     pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
@@ -315,4 +355,4 @@ declare class Vessels {
     parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent | MessageCancelledEvent | null>;
 }
 
-export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type StreamHandle, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };
+export { type ActivityHandle, AgentActivityTypes, type InteractionResponseEvent, type Message, type MessageCancelledEvent, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type StreamHandle, type SurfaceOptions, type UserMessageEvent, type ValidationResult, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };

package/dist/index.js

@@ -73,7 +73,10 @@ var CardFieldSchema = z.object({
   value: z.string()
 });
 var CardSchema = z.object({
-  title: z.string().min(1),
+  // Optional: a glance-facts card under a surface takes its heading from the
+  // surface `title`, so a card title is redundant there. Still allowed (e.g. a
+  // standalone card on a bubble, or a pinned card).
+  title: z.string().min(1).optional(),
   fields: z.array(CardFieldSchema)
 });
 var AttachmentSchema = z.discriminatedUnion("type", [
@@ -81,6 +84,8 @@ var AttachmentSchema = z.discriminatedUnion("type", [
   z.object({ type: z.literal("file"), url: z.string().url(), filename: z.string().optional() })
 ]);
 var VesselStatusSchema = z.enum(["active", "waiting", "resolved"]);
+var DisplaySchema = z.enum(["bubble", "document"]);
+var KindSchema = z.enum(["bubble", "surface"]);
 var PushPayloadSchema = z.object({
   message: z.string().min(1).max(1e4).optional(),
   vessel: z.string().optional(),
@@ -105,7 +110,13 @@ var PushPayloadSchema = z.object({
    * window, not a transcript: send the tail you want shown (the SDK trims to the
    * last 8000 chars). Plaintext, like agentActivity. Vanishes when cleared.
    */
-  tokenStream: z.string().max(8e3).optional()
+  tokenStream: z.string().max(8e3).optional(),
+  /** Bubble (chat) vs surface (composed artifact). Defaults from interaction/card. */
+  kind: KindSchema.optional(),
+  /** Surface heading. Ignored on bubbles. */
+  title: z.string().max(200).optional(),
+  /** @deprecated legacy presentation hint — use `kind`. 'document' → surface. */
+  display: DisplaySchema.optional()
 }).refine((d) => d.message || d.agentActivity || d.tokenStream, {
   message: "One of message, agentActivity, or tokenStream is required"
 });
@@ -122,7 +133,11 @@ var PushManyPayloadSchema = z.object({
   metadata: z.record(z.unknown()).refine(
     (v) => JSON.stringify(v).length < 16e3,
     "metadata exceeds 16KB limit"
-  ).optional()
+  ).optional(),
+  kind: KindSchema.optional(),
+  title: z.string().max(200).optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.optional()
 });
 z.object({
   content: z.string().min(1).max(1e4).optional(),
@@ -131,7 +146,13 @@ z.object({
   suggestions: z.array(z.string().min(1).max(500)).max(5).nullable().optional(),
   agentActivity: AgentActivitySchema.nullable().optional(),
   /** Replace the live token-stream window, or `null` to clear it (block vanishes). */
-  tokenStream: z.string().max(8e3).nullable().optional()
+  tokenStream: z.string().max(8e3).nullable().optional(),
+  /** Switch kind: 'surface' = full-width artifact, 'bubble' or null = chat bubble. */
+  kind: KindSchema.nullable().optional(),
+  /** Update the surface heading, or `null` to clear it. */
+  title: z.string().max(200).nullable().optional(),
+  /** @deprecated use `kind`. */
+  display: DisplaySchema.nullable().optional()
 }).refine((d) => Object.values(d).some((v) => v !== void 0), {
   message: "At least one field required"
 });
@@ -191,6 +212,11 @@ var WebhookInteractionResponsePayloadSchema = z.object({
     vessel: WebhookVesselSchema
   })
 });
+var SupersededInteractionSchema = z.object({
+  message_id: z.string(),
+  interaction_type: InteractionTypeSchema,
+  prompt: z.string().nullable()
+});
 var WebhookUserMessagePayloadSchema = z.object({
   event: z.literal("message.user"),
   vessel_id: z.string(),
@@ -200,7 +226,8 @@ var WebhookUserMessagePayloadSchema = z.object({
     message_id: z.string(),
     content: z.string(),
     vessel: WebhookVesselSchema,
-    context: z.array(WebhookContextMessageSchema)
+    context: z.array(WebhookContextMessageSchema),
+    superseded_interaction: SupersededInteractionSchema.optional()
   })
 });
 var WebhookVesselCreatedPayloadSchema = z.object({
@@ -359,6 +386,31 @@ var Vessels = class {
       replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
+  /**
+   * Create a **surface** — a full-width composed artifact the human reviews and
+   * optionally acts on, rendered as one piece: a `title` heading, an optional
+   * `card` of glance-facts, a block-markdown `body` (tables, bullet/numbered
+   * lists, blockquotes, bold headings, links), and an optional `interaction`
+   * (the action bar). Use this for an email/message draft, a quote, an invoice
+   * review, a proposal, a report — anything substantial and structured.
+   *
+   * Sugar over {@link push}: it sets `kind: 'surface'` and maps `body` to the
+   * message content. For conversation, status updates and quick questions, use
+   * {@link push} instead (a chat **bubble** — the human just replies).
+   *
+   * @example
+   * await vessels.surface({
+   *   vessel: 'inv-42',
+   *   title: 'GreenTurf Invoice #GTL-2025-042',
+   *   card: { fields: [{ label: 'Amount Due', value: '$7,400' }] },
+   *   body: 'Invoice is **$1,200 over** the usual rate.\n\n| Item | Amount |\n|---|---:|\n| Overage | +$1,200 |',
+   *   interaction: vessels.approval({ prompt: 'Approve the $7,400 payment?' }),
+   * });
+   */
+  async surface(options) {
+    const { body, ...rest } = options;
+    return this.push({ ...rest, message: body, kind: "surface" });
+  }
   async pushMany(payload) {
     const { idempotencyKey, ...body } = payload;
     const check = PushManyPayloadSchema.safeParse(body);
@@ -621,7 +673,12 @@ var Vessels = class {
         timestamp: e.timestamp,
         vessel,
         message: { id: e.message?.id, content: e.message?.content ?? null },
-        context: []
+        context: [],
+        supersededInteraction: e.superseded_interaction ? {
+          messageId: e.superseded_interaction.message_id,
+          interactionType: e.superseded_interaction.interaction_type,
+          prompt: e.superseded_interaction.prompt ?? null
+        } : null
       };
     });
     return { ok: true, events, hasMore: data.has_more ?? false };
@@ -722,7 +779,12 @@ var Vessels = class {
             source: m.source,
             content: m.content ?? null,
             createdAt: m.created_at
-          }))
+          })),
+          supersededInteraction: raw.data.superseded_interaction ? {
+            messageId: raw.data.superseded_interaction.message_id,
+            interactionType: raw.data.superseded_interaction.interaction_type,
+            prompt: raw.data.superseded_interaction.prompt ?? null
+          } : null
         };
       }
       return null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vessels-sdk",
-	"version": "0.12.0",
+	"version": "0.14.0",
 	"description": "Let your agent reach you. Official Vessels SDK.",
 	"type": "module",
 	"exports": {
@@ -20,7 +20,13 @@
 		"build": "tsup",
 		"dev": "tsup --watch"
 	},
-	"keywords": ["ai", "agents", "vessels", "llm", "notifications"],
+	"keywords": [
+		"ai",
+		"agents",
+		"vessels",
+		"llm",
+		"notifications"
+	],
 	"license": "MIT",
 	"dependencies": {
 		"zod": "^3.22"