vessels-sdk 0.12.0 → 0.13.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"
 });
@@ -361,6 +382,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);

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<{
@@ -233,6 +241,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 +345,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<{
@@ -233,6 +241,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 +345,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"
 });
@@ -359,6 +380,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);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vessels-sdk",
-	"version": "0.12.0",
+	"version": "0.13.0",
 	"description": "Let your agent reach you. Official Vessels SDK.",
 	"type": "module",
 	"exports": {