vessels-sdk 0.5.1 → 0.6.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),
@@ -155,8 +163,15 @@ var WebhookVesselSchema = zod.z.object({
   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 +181,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
   })
 });
@@ -314,6 +331,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 };
@@ -360,6 +409,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
         };
       }
@@ -427,6 +483,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
         };
       }

package/dist/index.d.cts

@@ -51,15 +51,26 @@ interface VesselContext {
     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,11 +86,23 @@ interface UserMessageEvent {
         content: string | null;
     };
     context: Array<{
-        source: string;
+        source: _vessels_types.Source;
         content: string | null;
         createdAt: string;
     }>;
 }
+/** 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;
 interface PollResponse {
     ok: true;
@@ -97,6 +120,22 @@ declare class Vessels {
     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;
@@ -146,4 +185,4 @@ declare class Vessels {
     parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | 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, Vessels, VesselsAuthError, type VesselsConfig, VesselsRateLimitError, VesselsValidationError };

package/dist/index.d.ts

@@ -51,15 +51,26 @@ interface VesselContext {
     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,11 +86,23 @@ interface UserMessageEvent {
         content: string | null;
     };
     context: Array<{
-        source: string;
+        source: _vessels_types.Source;
         content: string | null;
         createdAt: string;
     }>;
 }
+/** 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;
 interface PollResponse {
     ok: true;
@@ -97,6 +120,22 @@ declare class Vessels {
     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;
@@ -146,4 +185,4 @@ declare class Vessels {
     parseWebhookEvent(body: string, signature: string, webhookSecret: string): Promise<InteractionResponseEvent | UserMessageEvent | 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, Vessels, VesselsAuthError, type VesselsConfig, 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),
@@ -153,8 +161,15 @@ var WebhookVesselSchema = z.object({
   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 +179,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
   })
 });
@@ -312,6 +329,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 };
@@ -358,6 +407,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
         };
       }
@@ -425,6 +481,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
         };
       }

package/package.json

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