vessels-sdk 0.5.1 → 0.8.0

package/README.md

@@ -38,14 +38,20 @@ const { messageId, vesselId } = await vessels.push({
 });
 ```
 
-Get your API key from Settings → API Keys in the [Vessels app](https://vessels.app), or via the CLI:
+Get your API key via the CLI (Claude Code / AI assistants — fully non-interactive):
 
 ```bash
 npm install -g vessels
-vessels login
-vessels keys create
+
+# Step 1: send OTP to your email
+vessels init --email me@example.com
+
+# Step 2: verify with the code from your inbox — prints VESSELS_API_KEY=vsl_xxx
+vessels init --email me@example.com --otp 847293
 ```
 
+Or sign in at [vessels.app](https://vessels.app) → Settings → API Keys.
+
 ---
 
 ## API reference

package/dist/index.cjs

@@ -3,6 +3,14 @@
 var zod = require('zod');
 
 // ../types/src/index.ts
+var SourceSchema = zod.z.enum(["agent", "user", "system"]);
+var InteractionTypeSchema = zod.z.enum([
+  "approval",
+  "choice",
+  "checklist",
+  "text_input",
+  "confirm_preview"
+]);
 var ApprovalInteractionSchema = zod.z.object({
   type: zod.z.literal("approval"),
   prompt: zod.z.string().min(1),
@@ -152,11 +160,20 @@ var WebhookVesselSchema = zod.z.object({
   id: zod.z.string(),
   external_id: zod.z.string().nullable(),
   title: zod.z.string().nullable(),
+  /** The vessel's type (e.g. "Ticket"). Nullable — agent-created vessels have no type. */
+  type: zod.z.string().nullable().optional(),
   metadata: zod.z.record(zod.z.unknown())
 });
 var WebhookContextMessageSchema = zod.z.object({
-  source: zod.z.string(),
+  source: SourceSchema,
+  content: zod.z.string().nullable(),
+  created_at: zod.z.string()
+});
+var WebhookOriginMessageSchema = zod.z.object({
+  id: zod.z.string(),
   content: zod.z.string().nullable(),
+  interaction: zod.z.record(zod.z.unknown()).nullable(),
+  metadata: zod.z.record(zod.z.unknown()),
   created_at: zod.z.string()
 });
 var WebhookInteractionResponsePayloadSchema = zod.z.object({
@@ -166,10 +183,12 @@ var WebhookInteractionResponsePayloadSchema = zod.z.object({
   timestamp: zod.z.string(),
   data: zod.z.object({
     message_id: zod.z.string(),
-    interaction_type: zod.z.string(),
+    interaction_type: InteractionTypeSchema,
     response: zod.z.record(zod.z.unknown()),
     response_id: zod.z.string(),
     metadata: zod.z.record(zod.z.unknown()).optional(),
+    /** The agent message that carried the interaction (prompt, content, metadata). */
+    message: WebhookOriginMessageSchema,
     vessel: WebhookVesselSchema
   })
 });
@@ -185,9 +204,24 @@ var WebhookUserMessagePayloadSchema = zod.z.object({
     context: zod.z.array(WebhookContextMessageSchema)
   })
 });
+var WebhookVesselCreatedPayloadSchema = zod.z.object({
+  event: zod.z.literal("vessel.created"),
+  vessel_id: zod.z.string(),
+  workspace_id: zod.z.string(),
+  timestamp: zod.z.string(),
+  data: zod.z.object({
+    vessel: WebhookVesselSchema,
+    message: zod.z.object({
+      message_id: zod.z.string(),
+      content: zod.z.string().nullable(),
+      created_at: zod.z.string()
+    })
+  })
+});
 var WebhookPayloadSchema = zod.z.discriminatedUnion("event", [
   WebhookInteractionResponsePayloadSchema,
-  WebhookUserMessagePayloadSchema
+  WebhookUserMessagePayloadSchema,
+  WebhookVesselCreatedPayloadSchema
 ]);
 
 // src/index.ts
@@ -220,6 +254,12 @@ var VesselsRateLimitError = class extends Error {
     this.retryAfter = retryAfter;
   }
 };
+var VesselsConflictError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VesselsConflictError";
+  }
+};
 var Vessels = class {
   apiKey;
   baseUrl;
@@ -253,38 +293,45 @@ var Vessels = class {
     return res;
   }
   async push(payload) {
+    const { idempotencyKey, ...body } = payload;
     const res = await this._fetch(`${this.baseUrl}/api/v1/push`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
+        "Authorization": `Bearer ${this.apiKey}`,
+        ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
       },
-      body: JSON.stringify(payload)
+      body: JSON.stringify(body)
     });
     const data = await res.json();
     if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
     if (res.status === 429) throw new VesselsRateLimitError(data.error ?? "Rate limited", Number(res.headers.get("retry-after")));
+    if (res.status === 409) throw new VesselsConflictError(data.error ?? "Idempotent request in progress");
     if (res.status === 400) throw new VesselsValidationError(data.error ?? "Validation failed", data.details);
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return {
       ok: true,
       messageId: data.message_id,
       vesselId: data.vessel_id,
-      createdAt: data.created_at
+      createdAt: data.created_at,
+      replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
   async pushMany(payload) {
+    const { idempotencyKey, ...body } = payload;
     const res = await this._fetch(`${this.baseUrl}/api/v1/push/many`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
+        "Authorization": `Bearer ${this.apiKey}`,
+        ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
       },
-      body: JSON.stringify(payload)
+      body: JSON.stringify(body)
     });
     const data = await res.json();
     if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
     if (res.status === 429) throw new VesselsRateLimitError(data.error ?? "Rate limited", Number(res.headers.get("retry-after")));
+    if (res.status === 409) throw new VesselsConflictError(data.error ?? "Idempotent request in progress");
     if (res.status === 400) throw new VesselsValidationError(data.error ?? "Validation failed", data.details);
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return {
@@ -294,7 +341,8 @@ var Vessels = class {
         messageId: r.message_id,
         vesselId: r.vessel_id,
         ...r.error ? { error: r.error } : {}
-      }))
+      })),
+      replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
   async editMessage(messageId, patch) {
@@ -314,6 +362,38 @@ var Vessels = class {
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return { ok: true };
   }
+  /**
+   * Read a vessel's message history — the human-facing record, for re-reading
+   * the channel (e.g. a stateless or just-restarted worker reconciling state).
+   * This is NOT your agent's memory; keep your canonical history in your own
+   * system. `vessel` is your own external_id string by default; pass
+   * { byUuid: true } if you hold a Vessels UUID. Newest-last, paginate with `before`.
+   */
+  async getMessages(opts) {
+    const params = new URLSearchParams();
+    if (opts.limit != null) params.set("limit", String(opts.limit));
+    if (opts.before) params.set("before", opts.before);
+    const path = opts.byUuid ? `/api/v1/vessels/${encodeURIComponent(opts.vessel)}/messages` : `/api/v1/vessels/by-external/${encodeURIComponent(opts.vessel)}/messages`;
+    const res = await this._fetch(`${this.baseUrl}${path}?${params}`, {
+      headers: { "Authorization": `Bearer ${this.apiKey}` }
+    });
+    const data = await res.json();
+    if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
+    if (res.status === 404) throw new Error(data.error ?? "Vessel not found");
+    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+    const messages = (data.messages ?? []).map((m) => ({
+      id: m.id,
+      source: m.source,
+      content: m.content ?? null,
+      card: m.card ?? null,
+      interaction: m.interaction ?? null,
+      attachments: m.attachments ?? [],
+      suggestions: m.suggestions ?? [],
+      metadata: m.metadata ?? {},
+      createdAt: m.created_at
+    }));
+    return { messages, hasMore: data.has_more ?? false };
+  }
   // Interaction helpers
   approval(opts) {
     return { type: "approval", ...opts };
@@ -347,9 +427,19 @@ var Vessels = class {
         id: e.vessel?.id,
         externalId: e.vessel?.external_id ?? null,
         title: e.vessel?.title ?? null,
+        type: e.vessel?.type ?? null,
         metadata: e.vessel?.metadata ?? {},
         labels: e.vessel?.labels ?? []
       };
+      if (e.type === "vessel.created") {
+        return {
+          id: e.id,
+          type: "vessel.created",
+          timestamp: e.timestamp,
+          vessel,
+          message: { id: e.message?.id, content: e.message?.content ?? null }
+        };
+      }
       if (e.type === "interaction.response") {
         return {
           id: e.id,
@@ -360,6 +450,13 @@ var Vessels = class {
           interactionType: e.interaction_type,
           response: e.response,
           interactionMetadata: e.interaction_metadata ?? null,
+          originMessage: e.message ? {
+            id: e.message.id,
+            content: e.message.content ?? null,
+            interaction: e.message.interaction ?? null,
+            metadata: e.message.metadata ?? {},
+            createdAt: e.message.created_at
+          } : null,
           user: e.user ?? null
         };
       }
@@ -414,9 +511,22 @@ var Vessels = class {
         id: v.id,
         externalId: v.external_id ?? null,
         title: v.title ?? null,
+        type: v.type ?? null,
         metadata: v.metadata ?? {},
         labels: v.labels ?? []
       };
+      if (raw.event === "vessel.created") {
+        return {
+          id: raw.vessel_id,
+          type: "vessel.created",
+          timestamp: raw.timestamp,
+          vessel,
+          message: {
+            id: raw.data.message?.message_id,
+            content: raw.data.message?.content ?? null
+          }
+        };
+      }
       if (raw.event === "interaction.response") {
         return {
           id: raw.data.response_id,
@@ -427,6 +537,13 @@ var Vessels = class {
           interactionType: raw.data.interaction_type,
           response: raw.data.response,
           interactionMetadata: raw.data.metadata ?? null,
+          originMessage: raw.data.message ? {
+            id: raw.data.message.id,
+            content: raw.data.message.content ?? null,
+            interaction: raw.data.message.interaction ?? null,
+            metadata: raw.data.message.metadata ?? {},
+            createdAt: raw.data.message.created_at
+          } : null,
           user: raw.data.user ?? null
         };
       }
@@ -454,8 +571,10 @@ var Vessels = class {
 exports.AgentActivityTypes = AgentActivityTypes;
 exports.Vessels = Vessels;
 exports.VesselsAuthError = VesselsAuthError;
+exports.VesselsConflictError = VesselsConflictError;
 exports.VesselsRateLimitError = VesselsRateLimitError;
 exports.VesselsValidationError = VesselsValidationError;
 exports.WebhookInteractionResponsePayloadSchema = WebhookInteractionResponsePayloadSchema;
 exports.WebhookPayloadSchema = WebhookPayloadSchema;
 exports.WebhookUserMessagePayloadSchema = WebhookUserMessagePayloadSchema;
+exports.WebhookVesselCreatedPayloadSchema = WebhookVesselCreatedPayloadSchema;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _vessels_types from '@vessels/types';
-export { AgentActivity, AgentActivityType, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, MessagePatch, PushManyPayload, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema } from '@vessels/types';
+export { AgentActivity, AgentActivityType, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, MessagePatch, PushManyOptions, PushManyPayload, PushOptions, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema, WebhookVesselCreatedPayload, WebhookVesselCreatedPayloadSchema } from '@vessels/types';
 
 declare const AgentActivityTypes: {
     readonly thinking: "thinking";
@@ -19,6 +19,10 @@ declare class VesselsRateLimitError extends Error {
     retryAfter?: number;
     constructor(message: string, retryAfter?: number);
 }
+/** Thrown on HTTP 409 — an identical idempotent request is still in flight. Back off and retry. */
+declare class VesselsConflictError extends Error {
+    constructor(message: string);
+}
 interface VesselsConfig {
     apiKey: string;
     baseUrl?: string;
@@ -29,6 +33,8 @@ interface PushResponse {
     messageId: string;
     vesselId: string;
     createdAt: string;
+    /** True when this response is a replay of an earlier request with the same idempotency key. */
+    replayed: boolean;
 }
 interface PushManyResult {
     ok: true;
@@ -38,6 +44,8 @@ interface PushManyResult {
         vesselId: string;
         error?: string;
     }>;
+    /** True when this response is a replay of an earlier request with the same idempotency key. */
+    replayed: boolean;
 }
 interface PollOptions {
     since?: string;
@@ -48,18 +56,31 @@ interface VesselContext {
     id: string;
     externalId: string | null;
     title: string | null;
+    /** The vessel's type (e.g. "Ticket"). Null for agent-created vessels. */
+    type: string | null;
     metadata: Record<string, unknown>;
     labels: string[];
 }
+/** The agent message an interaction was attached to. */
+interface OriginMessage {
+    id: string;
+    content: string | null;
+    /** The interaction object you originally pushed (type, prompt, options, labels…). */
+    interaction: Record<string, unknown> | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
 interface InteractionResponseEvent {
     id: string;
     type: 'interaction.response';
     timestamp: string;
     vessel: VesselContext;
     messageId: string;
-    interactionType: string;
+    interactionType: _vessels_types.InteractionType;
     response: Record<string, unknown>;
     interactionMetadata: Record<string, unknown> | null;
+    /** The message that carried the interaction — so you know WHAT was responded to. */
+    originMessage: OriginMessage | null;
     user: {
         id: string;
         email: string;
@@ -75,12 +96,39 @@ interface UserMessageEvent {
         content: string | null;
     };
     context: Array<{
-        source: string;
+        source: _vessels_types.Source;
         content: string | null;
         createdAt: string;
     }>;
 }
-type PollEvent = InteractionResponseEvent | UserMessageEvent;
+/**
+ * Fired when a human opens a new typed vessel from the app (user-initiated
+ * vessels). `message` is the first thing the human typed; `vessel.type` is the
+ * vessel's type (e.g. "Ticket").
+ */
+interface VesselCreatedEvent {
+    id: string;
+    type: 'vessel.created';
+    timestamp: string;
+    vessel: VesselContext;
+    message: {
+        id: string;
+        content: string | null;
+    };
+}
+/** A message in a vessel, as returned by getMessages — the human-facing record. */
+interface Message {
+    id: string;
+    source: _vessels_types.Source;
+    content: string | null;
+    card: Record<string, unknown> | null;
+    interaction: Record<string, unknown> | null;
+    attachments: Array<Record<string, unknown>>;
+    suggestions: string[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+type PollEvent = InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent;
 interface PollResponse {
     ok: true;
     events: PollEvent[];
@@ -92,11 +140,27 @@ declare class Vessels {
     private _debug;
     constructor(config: VesselsConfig);
     private _fetch;
-    push(payload: _vessels_types.PushPayload): Promise<PushResponse>;
-    pushMany(payload: _vessels_types.PushManyPayload): Promise<PushManyResult>;
+    push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
+    pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
     }>;
+    /**
+     * Read a vessel's message history — the human-facing record, for re-reading
+     * the channel (e.g. a stateless or just-restarted worker reconciling state).
+     * This is NOT your agent's memory; keep your canonical history in your own
+     * system. `vessel` is your own external_id string by default; pass
+     * { byUuid: true } if you hold a Vessels UUID. Newest-last, paginate with `before`.
+     */
+    getMessages(opts: {
+        vessel: string;
+        byUuid?: boolean;
+        limit?: number;
+        before?: string;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+    }>;
     approval(opts: {
         prompt: string;
         approveLabel?: string;
@@ -143,7 +207,7 @@ declare class Vessels {
     }): _vessels_types.ConfirmPreviewInteraction;
     poll(options?: PollOptions): Promise<PollResponse>;
     verifyWebhook(body: string, signature: string, webhookSecret: string): Promise<boolean>;
-    parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | null>;
+    parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent | null>;
 }
 
-export { AgentActivityTypes, type InteractionResponseEvent, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, type VesselContext, Vessels, VesselsAuthError, type VesselsConfig, VesselsRateLimitError, VesselsValidationError };
+export { AgentActivityTypes, type InteractionResponseEvent, type Message, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _vessels_types from '@vessels/types';
-export { AgentActivity, AgentActivityType, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, MessagePatch, PushManyPayload, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema } from '@vessels/types';
+export { AgentActivity, AgentActivityType, ApprovalInteraction, Attachment, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, MessagePatch, PushManyOptions, PushManyPayload, PushOptions, PushPayload, TextInputInteraction, WebhookInteractionResponsePayload, WebhookInteractionResponsePayloadSchema, WebhookPayload, WebhookPayloadSchema, WebhookUserMessagePayload, WebhookUserMessagePayloadSchema, WebhookVesselCreatedPayload, WebhookVesselCreatedPayloadSchema } from '@vessels/types';
 
 declare const AgentActivityTypes: {
     readonly thinking: "thinking";
@@ -19,6 +19,10 @@ declare class VesselsRateLimitError extends Error {
     retryAfter?: number;
     constructor(message: string, retryAfter?: number);
 }
+/** Thrown on HTTP 409 — an identical idempotent request is still in flight. Back off and retry. */
+declare class VesselsConflictError extends Error {
+    constructor(message: string);
+}
 interface VesselsConfig {
     apiKey: string;
     baseUrl?: string;
@@ -29,6 +33,8 @@ interface PushResponse {
     messageId: string;
     vesselId: string;
     createdAt: string;
+    /** True when this response is a replay of an earlier request with the same idempotency key. */
+    replayed: boolean;
 }
 interface PushManyResult {
     ok: true;
@@ -38,6 +44,8 @@ interface PushManyResult {
         vesselId: string;
         error?: string;
     }>;
+    /** True when this response is a replay of an earlier request with the same idempotency key. */
+    replayed: boolean;
 }
 interface PollOptions {
     since?: string;
@@ -48,18 +56,31 @@ interface VesselContext {
     id: string;
     externalId: string | null;
     title: string | null;
+    /** The vessel's type (e.g. "Ticket"). Null for agent-created vessels. */
+    type: string | null;
     metadata: Record<string, unknown>;
     labels: string[];
 }
+/** The agent message an interaction was attached to. */
+interface OriginMessage {
+    id: string;
+    content: string | null;
+    /** The interaction object you originally pushed (type, prompt, options, labels…). */
+    interaction: Record<string, unknown> | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
 interface InteractionResponseEvent {
     id: string;
     type: 'interaction.response';
     timestamp: string;
     vessel: VesselContext;
     messageId: string;
-    interactionType: string;
+    interactionType: _vessels_types.InteractionType;
     response: Record<string, unknown>;
     interactionMetadata: Record<string, unknown> | null;
+    /** The message that carried the interaction — so you know WHAT was responded to. */
+    originMessage: OriginMessage | null;
     user: {
         id: string;
         email: string;
@@ -75,12 +96,39 @@ interface UserMessageEvent {
         content: string | null;
     };
     context: Array<{
-        source: string;
+        source: _vessels_types.Source;
         content: string | null;
         createdAt: string;
     }>;
 }
-type PollEvent = InteractionResponseEvent | UserMessageEvent;
+/**
+ * Fired when a human opens a new typed vessel from the app (user-initiated
+ * vessels). `message` is the first thing the human typed; `vessel.type` is the
+ * vessel's type (e.g. "Ticket").
+ */
+interface VesselCreatedEvent {
+    id: string;
+    type: 'vessel.created';
+    timestamp: string;
+    vessel: VesselContext;
+    message: {
+        id: string;
+        content: string | null;
+    };
+}
+/** A message in a vessel, as returned by getMessages — the human-facing record. */
+interface Message {
+    id: string;
+    source: _vessels_types.Source;
+    content: string | null;
+    card: Record<string, unknown> | null;
+    interaction: Record<string, unknown> | null;
+    attachments: Array<Record<string, unknown>>;
+    suggestions: string[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+type PollEvent = InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent;
 interface PollResponse {
     ok: true;
     events: PollEvent[];
@@ -92,11 +140,27 @@ declare class Vessels {
     private _debug;
     constructor(config: VesselsConfig);
     private _fetch;
-    push(payload: _vessels_types.PushPayload): Promise<PushResponse>;
-    pushMany(payload: _vessels_types.PushManyPayload): Promise<PushManyResult>;
+    push(payload: _vessels_types.PushOptions): Promise<PushResponse>;
+    pushMany(payload: _vessels_types.PushManyOptions): Promise<PushManyResult>;
     editMessage(messageId: string, patch: _vessels_types.MessagePatch): Promise<{
         ok: true;
     }>;
+    /**
+     * Read a vessel's message history — the human-facing record, for re-reading
+     * the channel (e.g. a stateless or just-restarted worker reconciling state).
+     * This is NOT your agent's memory; keep your canonical history in your own
+     * system. `vessel` is your own external_id string by default; pass
+     * { byUuid: true } if you hold a Vessels UUID. Newest-last, paginate with `before`.
+     */
+    getMessages(opts: {
+        vessel: string;
+        byUuid?: boolean;
+        limit?: number;
+        before?: string;
+    }): Promise<{
+        messages: Message[];
+        hasMore: boolean;
+    }>;
     approval(opts: {
         prompt: string;
         approveLabel?: string;
@@ -143,7 +207,7 @@ declare class Vessels {
     }): _vessels_types.ConfirmPreviewInteraction;
     poll(options?: PollOptions): Promise<PollResponse>;
     verifyWebhook(body: string, signature: string, webhookSecret: string): Promise<boolean>;
-    parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | null>;
+    parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent | null>;
 }
 
-export { AgentActivityTypes, type InteractionResponseEvent, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, type VesselContext, Vessels, VesselsAuthError, type VesselsConfig, VesselsRateLimitError, VesselsValidationError };
+export { AgentActivityTypes, type InteractionResponseEvent, type Message, type OriginMessage, type PollEvent, type PollOptions, type PollResponse, type PushManyResult, type PushResponse, type UserMessageEvent, type VesselContext, type VesselCreatedEvent, Vessels, VesselsAuthError, type VesselsConfig, VesselsConflictError, VesselsRateLimitError, VesselsValidationError };

package/dist/index.js

@@ -1,6 +1,14 @@
 import { z } from 'zod';
 
 // ../types/src/index.ts
+var SourceSchema = z.enum(["agent", "user", "system"]);
+var InteractionTypeSchema = z.enum([
+  "approval",
+  "choice",
+  "checklist",
+  "text_input",
+  "confirm_preview"
+]);
 var ApprovalInteractionSchema = z.object({
   type: z.literal("approval"),
   prompt: z.string().min(1),
@@ -150,11 +158,20 @@ var WebhookVesselSchema = z.object({
   id: z.string(),
   external_id: z.string().nullable(),
   title: z.string().nullable(),
+  /** The vessel's type (e.g. "Ticket"). Nullable — agent-created vessels have no type. */
+  type: z.string().nullable().optional(),
   metadata: z.record(z.unknown())
 });
 var WebhookContextMessageSchema = z.object({
-  source: z.string(),
+  source: SourceSchema,
+  content: z.string().nullable(),
+  created_at: z.string()
+});
+var WebhookOriginMessageSchema = z.object({
+  id: z.string(),
   content: z.string().nullable(),
+  interaction: z.record(z.unknown()).nullable(),
+  metadata: z.record(z.unknown()),
   created_at: z.string()
 });
 var WebhookInteractionResponsePayloadSchema = z.object({
@@ -164,10 +181,12 @@ var WebhookInteractionResponsePayloadSchema = z.object({
   timestamp: z.string(),
   data: z.object({
     message_id: z.string(),
-    interaction_type: z.string(),
+    interaction_type: InteractionTypeSchema,
     response: z.record(z.unknown()),
     response_id: z.string(),
     metadata: z.record(z.unknown()).optional(),
+    /** The agent message that carried the interaction (prompt, content, metadata). */
+    message: WebhookOriginMessageSchema,
     vessel: WebhookVesselSchema
   })
 });
@@ -183,9 +202,24 @@ var WebhookUserMessagePayloadSchema = z.object({
     context: z.array(WebhookContextMessageSchema)
   })
 });
+var WebhookVesselCreatedPayloadSchema = z.object({
+  event: z.literal("vessel.created"),
+  vessel_id: z.string(),
+  workspace_id: z.string(),
+  timestamp: z.string(),
+  data: z.object({
+    vessel: WebhookVesselSchema,
+    message: z.object({
+      message_id: z.string(),
+      content: z.string().nullable(),
+      created_at: z.string()
+    })
+  })
+});
 var WebhookPayloadSchema = z.discriminatedUnion("event", [
   WebhookInteractionResponsePayloadSchema,
-  WebhookUserMessagePayloadSchema
+  WebhookUserMessagePayloadSchema,
+  WebhookVesselCreatedPayloadSchema
 ]);
 
 // src/index.ts
@@ -218,6 +252,12 @@ var VesselsRateLimitError = class extends Error {
     this.retryAfter = retryAfter;
   }
 };
+var VesselsConflictError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VesselsConflictError";
+  }
+};
 var Vessels = class {
   apiKey;
   baseUrl;
@@ -251,38 +291,45 @@ var Vessels = class {
     return res;
   }
   async push(payload) {
+    const { idempotencyKey, ...body } = payload;
     const res = await this._fetch(`${this.baseUrl}/api/v1/push`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
+        "Authorization": `Bearer ${this.apiKey}`,
+        ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
       },
-      body: JSON.stringify(payload)
+      body: JSON.stringify(body)
     });
     const data = await res.json();
     if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
     if (res.status === 429) throw new VesselsRateLimitError(data.error ?? "Rate limited", Number(res.headers.get("retry-after")));
+    if (res.status === 409) throw new VesselsConflictError(data.error ?? "Idempotent request in progress");
     if (res.status === 400) throw new VesselsValidationError(data.error ?? "Validation failed", data.details);
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return {
       ok: true,
       messageId: data.message_id,
       vesselId: data.vessel_id,
-      createdAt: data.created_at
+      createdAt: data.created_at,
+      replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
   async pushMany(payload) {
+    const { idempotencyKey, ...body } = payload;
     const res = await this._fetch(`${this.baseUrl}/api/v1/push/many`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "Authorization": `Bearer ${this.apiKey}`
+        "Authorization": `Bearer ${this.apiKey}`,
+        ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
       },
-      body: JSON.stringify(payload)
+      body: JSON.stringify(body)
     });
     const data = await res.json();
     if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
     if (res.status === 429) throw new VesselsRateLimitError(data.error ?? "Rate limited", Number(res.headers.get("retry-after")));
+    if (res.status === 409) throw new VesselsConflictError(data.error ?? "Idempotent request in progress");
     if (res.status === 400) throw new VesselsValidationError(data.error ?? "Validation failed", data.details);
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return {
@@ -292,7 +339,8 @@ var Vessels = class {
         messageId: r.message_id,
         vesselId: r.vessel_id,
         ...r.error ? { error: r.error } : {}
-      }))
+      })),
+      replayed: res.headers.get("Idempotent-Replayed") === "true"
     };
   }
   async editMessage(messageId, patch) {
@@ -312,6 +360,38 @@ var Vessels = class {
     if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
     return { ok: true };
   }
+  /**
+   * Read a vessel's message history — the human-facing record, for re-reading
+   * the channel (e.g. a stateless or just-restarted worker reconciling state).
+   * This is NOT your agent's memory; keep your canonical history in your own
+   * system. `vessel` is your own external_id string by default; pass
+   * { byUuid: true } if you hold a Vessels UUID. Newest-last, paginate with `before`.
+   */
+  async getMessages(opts) {
+    const params = new URLSearchParams();
+    if (opts.limit != null) params.set("limit", String(opts.limit));
+    if (opts.before) params.set("before", opts.before);
+    const path = opts.byUuid ? `/api/v1/vessels/${encodeURIComponent(opts.vessel)}/messages` : `/api/v1/vessels/by-external/${encodeURIComponent(opts.vessel)}/messages`;
+    const res = await this._fetch(`${this.baseUrl}${path}?${params}`, {
+      headers: { "Authorization": `Bearer ${this.apiKey}` }
+    });
+    const data = await res.json();
+    if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
+    if (res.status === 404) throw new Error(data.error ?? "Vessel not found");
+    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+    const messages = (data.messages ?? []).map((m) => ({
+      id: m.id,
+      source: m.source,
+      content: m.content ?? null,
+      card: m.card ?? null,
+      interaction: m.interaction ?? null,
+      attachments: m.attachments ?? [],
+      suggestions: m.suggestions ?? [],
+      metadata: m.metadata ?? {},
+      createdAt: m.created_at
+    }));
+    return { messages, hasMore: data.has_more ?? false };
+  }
   // Interaction helpers
   approval(opts) {
     return { type: "approval", ...opts };
@@ -345,9 +425,19 @@ var Vessels = class {
         id: e.vessel?.id,
         externalId: e.vessel?.external_id ?? null,
         title: e.vessel?.title ?? null,
+        type: e.vessel?.type ?? null,
         metadata: e.vessel?.metadata ?? {},
         labels: e.vessel?.labels ?? []
       };
+      if (e.type === "vessel.created") {
+        return {
+          id: e.id,
+          type: "vessel.created",
+          timestamp: e.timestamp,
+          vessel,
+          message: { id: e.message?.id, content: e.message?.content ?? null }
+        };
+      }
       if (e.type === "interaction.response") {
         return {
           id: e.id,
@@ -358,6 +448,13 @@ var Vessels = class {
           interactionType: e.interaction_type,
           response: e.response,
           interactionMetadata: e.interaction_metadata ?? null,
+          originMessage: e.message ? {
+            id: e.message.id,
+            content: e.message.content ?? null,
+            interaction: e.message.interaction ?? null,
+            metadata: e.message.metadata ?? {},
+            createdAt: e.message.created_at
+          } : null,
           user: e.user ?? null
         };
       }
@@ -412,9 +509,22 @@ var Vessels = class {
         id: v.id,
         externalId: v.external_id ?? null,
         title: v.title ?? null,
+        type: v.type ?? null,
         metadata: v.metadata ?? {},
         labels: v.labels ?? []
       };
+      if (raw.event === "vessel.created") {
+        return {
+          id: raw.vessel_id,
+          type: "vessel.created",
+          timestamp: raw.timestamp,
+          vessel,
+          message: {
+            id: raw.data.message?.message_id,
+            content: raw.data.message?.content ?? null
+          }
+        };
+      }
       if (raw.event === "interaction.response") {
         return {
           id: raw.data.response_id,
@@ -425,6 +535,13 @@ var Vessels = class {
           interactionType: raw.data.interaction_type,
           response: raw.data.response,
           interactionMetadata: raw.data.metadata ?? null,
+          originMessage: raw.data.message ? {
+            id: raw.data.message.id,
+            content: raw.data.message.content ?? null,
+            interaction: raw.data.message.interaction ?? null,
+            metadata: raw.data.message.metadata ?? {},
+            createdAt: raw.data.message.created_at
+          } : null,
           user: raw.data.user ?? null
         };
       }
@@ -449,4 +566,4 @@ var Vessels = class {
   }
 };
 
-export { AgentActivityTypes, Vessels, VesselsAuthError, VesselsRateLimitError, VesselsValidationError, WebhookInteractionResponsePayloadSchema, WebhookPayloadSchema, WebhookUserMessagePayloadSchema };
+export { AgentActivityTypes, Vessels, VesselsAuthError, VesselsConflictError, VesselsRateLimitError, VesselsValidationError, WebhookInteractionResponsePayloadSchema, WebhookPayloadSchema, WebhookUserMessagePayloadSchema, WebhookVesselCreatedPayloadSchema };

package/package.json

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