vessels-sdk 0.6.0 → 0.8.0

package/dist/index.cjs

@@ -160,6 +160,8 @@ 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({
@@ -202,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
@@ -237,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;
@@ -270,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 {
@@ -311,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) {
@@ -396,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,
@@ -470,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,
@@ -517,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,6 +56,8 @@ 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[];
 }
@@ -91,6 +101,21 @@ interface UserMessageEvent {
         createdAt: string;
     }>;
 }
+/**
+ * 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;
@@ -103,7 +128,7 @@ interface Message {
     metadata: Record<string, unknown>;
     createdAt: string;
 }
-type PollEvent = InteractionResponseEvent | UserMessageEvent;
+type PollEvent = InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent;
 interface PollResponse {
     ok: true;
     events: PollEvent[];
@@ -115,8 +140,8 @@ 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;
     }>;
@@ -182,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 Message, type OriginMessage, 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,6 +56,8 @@ 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[];
 }
@@ -91,6 +101,21 @@ interface UserMessageEvent {
         createdAt: string;
     }>;
 }
+/**
+ * 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;
@@ -103,7 +128,7 @@ interface Message {
     metadata: Record<string, unknown>;
     createdAt: string;
 }
-type PollEvent = InteractionResponseEvent | UserMessageEvent;
+type PollEvent = InteractionResponseEvent | UserMessageEvent | VesselCreatedEvent;
 interface PollResponse {
     ok: true;
     events: PollEvent[];
@@ -115,8 +140,8 @@ 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;
     }>;
@@ -182,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 Message, type OriginMessage, 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

@@ -158,6 +158,8 @@ 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({
@@ -200,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
@@ -235,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;
@@ -268,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 {
@@ -309,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) {
@@ -394,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,
@@ -468,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,
@@ -512,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.6.0",
+	"version": "0.8.0",
 	"description": "Let your agent reach you. Official Vessels SDK.",
 	"type": "module",
 	"exports": {