vessels-sdk 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @vessels/sdk
+
+Node.js SDK for [Vessels](https://vessels.app) — push messages from your agent to your phone and verify webhook callbacks.
+
+## Installation
+
+```bash
+npm install @vessels/sdk
+```
+
+## Usage
+
+### Push a message with a card and approval interaction
+
+```typescript
+import { Vessels } from '@vessels/sdk';
+
+const vessels = new Vessels({ apiKey: process.env.VESSELS_API_KEY! });
+
+const response = await vessels.push({
+  thread: 'booking-123',
+  threadTitle: 'Sarah Martinez',
+  message: 'New booking request received.',
+  card: {
+    title: 'Booking Details',
+    fields: [
+      { label: 'Date', value: 'Saturday 14 June' },
+      { label: 'Time', value: '2:00 PM' },
+      { label: 'Players', value: '4' },
+    ],
+  },
+  interaction: vessels.approval({
+    prompt: 'Confirm this booking?',
+    approveLabel: 'Confirm',
+    rejectLabel: 'Decline',
+  }),
+});
+
+console.log(response.messageId); // the created message ID
+console.log(response.threadId);  // the upserted thread ID
+```
+
+### Verify a webhook in an Express handler
+
+```typescript
+import express from 'express';
+import { Vessels } from '@vessels/sdk';
+
+const vessels = new Vessels({ apiKey: process.env.VESSELS_API_KEY! });
+const app = express();
+
+app.post(
+  '/webhooks/vessels',
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const signature = req.headers['x-vessels-signature'] as string;
+    const body = req.body.toString('utf8');
+
+    if (!vessels.verifyWebhook(body, signature)) {
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    const event = JSON.parse(body);
+
+    if (event.type === 'interaction.response') {
+      const { interactionType, response } = event.data;
+      console.log(`User responded to ${interactionType}:`, response);
+      // e.g. { action: 'approved' } for an approval card
+    }
+
+    res.status(200).json({ received: true });
+  },
+);
+
+app.listen(3000);
+```
+
+## API
+
+### `new Vessels(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | required | Your `vsl_` prefixed API key |
+| `baseUrl` | `string` | `https://vessels.app` | Override for self-hosted or local dev |
+
+### `vessels.push(payload)`
+
+Push a message to a thread. Returns `{ ok, messageId, threadId, createdAt }`.
+
+Throws `VesselsAuthError` (401), `VesselsRateLimitError` (429), or `VesselsValidationError` (400) on failure.
+
+### Interaction helpers
+
+All helpers return a typed interaction object to pass as `payload.interaction`.
+
+| Method | Card type |
+|--------|-----------|
+| `vessels.approval(opts)` | Yes/no decision |
+| `vessels.choice(opts)` | Pick one option |
+| `vessels.checklist(opts)` | Pick multiple options |
+| `vessels.textInput(opts)` | Free-form text |
+| `vessels.confirmPreview(opts)` | Approve with external preview link |
+
+### `vessels.verifyWebhook(body, signature)`
+
+Verifies the `X-Vessels-Signature` header using HMAC-SHA256. Pass the **raw** request body as a string. Returns `true` if valid.

package/dist/index.cjs

@@ -0,0 +1,131 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/index.ts
+var VesselsAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VesselsAuthError";
+  }
+};
+var VesselsValidationError = class extends Error {
+  details;
+  constructor(message, details) {
+    super(message);
+    this.name = "VesselsValidationError";
+    this.details = details;
+  }
+};
+var VesselsRateLimitError = class extends Error {
+  retryAfter;
+  constructor(message, retryAfter) {
+    super(message);
+    this.name = "VesselsRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var Vessels = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl?.replace(/\/$/, "") ?? "https://vessels-two.vercel.app";
+  }
+  async push(payload) {
+    const res = await fetch(`${this.baseUrl}/api/v1/push`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(payload)
+    });
+    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 === 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
+    };
+  }
+  // Interaction helpers
+  approval(opts) {
+    return { type: "approval", ...opts };
+  }
+  choice(opts) {
+    return { type: "choice", ...opts };
+  }
+  checklist(opts) {
+    return { type: "checklist", ...opts };
+  }
+  textInput(opts) {
+    return { type: "text_input", ...opts };
+  }
+  confirmPreview(opts) {
+    return { type: "confirm_preview", ...opts };
+  }
+  async poll(options = {}) {
+    const { since, limit = 50, ack = true } = options;
+    const params = new URLSearchParams();
+    if (since) params.set("since", since);
+    params.set("limit", String(limit));
+    params.set("ack", String(ack));
+    const res = await fetch(`${this.baseUrl}/api/v1/poll?${params}`, {
+      headers: { "Authorization": `Bearer ${this.apiKey}` }
+    });
+    const data = await res.json();
+    if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
+    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+    const events = (data.events ?? []).map((e) => {
+      const vessel = {
+        id: e.vessel?.id,
+        externalId: e.vessel?.external_id ?? null,
+        title: e.vessel?.title ?? null,
+        metadata: e.vessel?.metadata ?? {}
+      };
+      if (e.type === "interaction.response") {
+        return {
+          id: e.id,
+          type: "interaction.response",
+          timestamp: e.timestamp,
+          vessel,
+          messageId: e.message_id,
+          interactionType: e.interaction_type,
+          response: e.response,
+          user: e.user ?? null
+        };
+      }
+      return {
+        id: e.id,
+        type: "message.user",
+        timestamp: e.timestamp,
+        vessel,
+        message: { id: e.message?.id, content: e.message?.content ?? null }
+      };
+    });
+    return { ok: true, events, hasMore: data.has_more ?? false };
+  }
+  // Webhook verification — call this in your webhook handler
+  // body: raw request body string, signature: X-Vessels-Signature header value
+  verifyWebhook(body, signature) {
+    if (!signature.startsWith("sha256=")) return false;
+    const expected = crypto.createHmac("sha256", this.apiKey).update(body).digest("hex");
+    const received = signature.slice(7);
+    if (expected.length !== received.length) return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+      diff |= expected.charCodeAt(i) ^ received.charCodeAt(i);
+    }
+    return diff === 0;
+  }
+};
+
+exports.Vessels = Vessels;
+exports.VesselsAuthError = VesselsAuthError;
+exports.VesselsRateLimitError = VesselsRateLimitError;
+exports.VesselsValidationError = VesselsValidationError;

package/dist/index.d.cts

@@ -0,0 +1,113 @@
+import * as _vessels_types from '@vessels/types';
+export { ApprovalInteraction, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, PushPayload, TextInputInteraction } from '@vessels/types';
+
+declare class VesselsAuthError extends Error {
+    constructor(message: string);
+}
+declare class VesselsValidationError extends Error {
+    details?: unknown;
+    constructor(message: string, details?: unknown);
+}
+declare class VesselsRateLimitError extends Error {
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
+interface VesselsConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface PushResponse {
+    ok: true;
+    messageId: string;
+    vesselId: string;
+    createdAt: string;
+}
+interface PollOptions {
+    since?: string;
+    limit?: number;
+    ack?: boolean;
+}
+interface VesselContext {
+    id: string;
+    externalId: string | null;
+    title: string | null;
+    metadata: Record<string, unknown>;
+}
+interface InteractionResponseEvent {
+    id: string;
+    type: 'interaction.response';
+    timestamp: string;
+    vessel: VesselContext;
+    messageId: string;
+    interactionType: string;
+    response: Record<string, unknown>;
+    user: {
+        id: string;
+        email: string;
+    } | null;
+}
+interface UserMessageEvent {
+    id: string;
+    type: 'message.user';
+    timestamp: string;
+    vessel: VesselContext;
+    message: {
+        id: string;
+        content: string | null;
+    };
+}
+type PollEvent = InteractionResponseEvent | UserMessageEvent;
+interface PollResponse {
+    ok: true;
+    events: PollEvent[];
+    hasMore: boolean;
+}
+declare class Vessels {
+    private apiKey;
+    private baseUrl;
+    constructor(config: VesselsConfig);
+    push(payload: _vessels_types.PushPayload): Promise<PushResponse>;
+    approval(opts: {
+        prompt: string;
+        approveLabel?: string;
+        rejectLabel?: string;
+        reasonRequired?: boolean;
+    }): _vessels_types.ApprovalInteraction;
+    choice(opts: {
+        prompt: string;
+        options: Array<{
+            id: string;
+            label: string;
+        }>;
+        allowCustom?: boolean;
+        customPlaceholder?: string;
+    }): _vessels_types.ChoiceInteraction;
+    checklist(opts: {
+        prompt: string;
+        options: Array<{
+            id: string;
+            label: string;
+            checked?: boolean;
+        }>;
+        minSelections?: number;
+        submitLabel?: string;
+    }): _vessels_types.ChecklistInteraction;
+    textInput(opts: {
+        prompt: string;
+        placeholder?: string;
+        multiline?: boolean;
+        submitLabel?: string;
+    }): _vessels_types.TextInputInteraction;
+    confirmPreview(opts: {
+        prompt: string;
+        previewUrl: string;
+        previewLabel?: string;
+        approveLabel?: string;
+        rejectLabel?: string;
+        reasonRequiredOnReject?: boolean;
+    }): _vessels_types.ConfirmPreviewInteraction;
+    poll(options?: PollOptions): Promise<PollResponse>;
+    verifyWebhook(body: string, signature: string): boolean;
+}
+
+export { type InteractionResponseEvent, type PollEvent, type PollOptions, type PollResponse, type PushResponse, type UserMessageEvent, type VesselContext, Vessels, VesselsAuthError, type VesselsConfig, VesselsRateLimitError, VesselsValidationError };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import * as _vessels_types from '@vessels/types';
+export { ApprovalInteraction, Card, ChecklistInteraction, ChoiceInteraction, ConfirmPreviewInteraction, Interaction, PushPayload, TextInputInteraction } from '@vessels/types';
+
+declare class VesselsAuthError extends Error {
+    constructor(message: string);
+}
+declare class VesselsValidationError extends Error {
+    details?: unknown;
+    constructor(message: string, details?: unknown);
+}
+declare class VesselsRateLimitError extends Error {
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
+interface VesselsConfig {
+    apiKey: string;
+    baseUrl?: string;
+}
+interface PushResponse {
+    ok: true;
+    messageId: string;
+    vesselId: string;
+    createdAt: string;
+}
+interface PollOptions {
+    since?: string;
+    limit?: number;
+    ack?: boolean;
+}
+interface VesselContext {
+    id: string;
+    externalId: string | null;
+    title: string | null;
+    metadata: Record<string, unknown>;
+}
+interface InteractionResponseEvent {
+    id: string;
+    type: 'interaction.response';
+    timestamp: string;
+    vessel: VesselContext;
+    messageId: string;
+    interactionType: string;
+    response: Record<string, unknown>;
+    user: {
+        id: string;
+        email: string;
+    } | null;
+}
+interface UserMessageEvent {
+    id: string;
+    type: 'message.user';
+    timestamp: string;
+    vessel: VesselContext;
+    message: {
+        id: string;
+        content: string | null;
+    };
+}
+type PollEvent = InteractionResponseEvent | UserMessageEvent;
+interface PollResponse {
+    ok: true;
+    events: PollEvent[];
+    hasMore: boolean;
+}
+declare class Vessels {
+    private apiKey;
+    private baseUrl;
+    constructor(config: VesselsConfig);
+    push(payload: _vessels_types.PushPayload): Promise<PushResponse>;
+    approval(opts: {
+        prompt: string;
+        approveLabel?: string;
+        rejectLabel?: string;
+        reasonRequired?: boolean;
+    }): _vessels_types.ApprovalInteraction;
+    choice(opts: {
+        prompt: string;
+        options: Array<{
+            id: string;
+            label: string;
+        }>;
+        allowCustom?: boolean;
+        customPlaceholder?: string;
+    }): _vessels_types.ChoiceInteraction;
+    checklist(opts: {
+        prompt: string;
+        options: Array<{
+            id: string;
+            label: string;
+            checked?: boolean;
+        }>;
+        minSelections?: number;
+        submitLabel?: string;
+    }): _vessels_types.ChecklistInteraction;
+    textInput(opts: {
+        prompt: string;
+        placeholder?: string;
+        multiline?: boolean;
+        submitLabel?: string;
+    }): _vessels_types.TextInputInteraction;
+    confirmPreview(opts: {
+        prompt: string;
+        previewUrl: string;
+        previewLabel?: string;
+        approveLabel?: string;
+        rejectLabel?: string;
+        reasonRequiredOnReject?: boolean;
+    }): _vessels_types.ConfirmPreviewInteraction;
+    poll(options?: PollOptions): Promise<PollResponse>;
+    verifyWebhook(body: string, signature: string): boolean;
+}
+
+export { type InteractionResponseEvent, type PollEvent, type PollOptions, type PollResponse, type PushResponse, type UserMessageEvent, type VesselContext, Vessels, VesselsAuthError, type VesselsConfig, VesselsRateLimitError, VesselsValidationError };

package/dist/index.js

@@ -0,0 +1,126 @@
+import { createHmac } from 'crypto';
+
+// src/index.ts
+var VesselsAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VesselsAuthError";
+  }
+};
+var VesselsValidationError = class extends Error {
+  details;
+  constructor(message, details) {
+    super(message);
+    this.name = "VesselsValidationError";
+    this.details = details;
+  }
+};
+var VesselsRateLimitError = class extends Error {
+  retryAfter;
+  constructor(message, retryAfter) {
+    super(message);
+    this.name = "VesselsRateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var Vessels = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl?.replace(/\/$/, "") ?? "https://vessels-two.vercel.app";
+  }
+  async push(payload) {
+    const res = await fetch(`${this.baseUrl}/api/v1/push`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(payload)
+    });
+    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 === 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
+    };
+  }
+  // Interaction helpers
+  approval(opts) {
+    return { type: "approval", ...opts };
+  }
+  choice(opts) {
+    return { type: "choice", ...opts };
+  }
+  checklist(opts) {
+    return { type: "checklist", ...opts };
+  }
+  textInput(opts) {
+    return { type: "text_input", ...opts };
+  }
+  confirmPreview(opts) {
+    return { type: "confirm_preview", ...opts };
+  }
+  async poll(options = {}) {
+    const { since, limit = 50, ack = true } = options;
+    const params = new URLSearchParams();
+    if (since) params.set("since", since);
+    params.set("limit", String(limit));
+    params.set("ack", String(ack));
+    const res = await fetch(`${this.baseUrl}/api/v1/poll?${params}`, {
+      headers: { "Authorization": `Bearer ${this.apiKey}` }
+    });
+    const data = await res.json();
+    if (res.status === 401) throw new VesselsAuthError(data.error ?? "Unauthorized");
+    if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);
+    const events = (data.events ?? []).map((e) => {
+      const vessel = {
+        id: e.vessel?.id,
+        externalId: e.vessel?.external_id ?? null,
+        title: e.vessel?.title ?? null,
+        metadata: e.vessel?.metadata ?? {}
+      };
+      if (e.type === "interaction.response") {
+        return {
+          id: e.id,
+          type: "interaction.response",
+          timestamp: e.timestamp,
+          vessel,
+          messageId: e.message_id,
+          interactionType: e.interaction_type,
+          response: e.response,
+          user: e.user ?? null
+        };
+      }
+      return {
+        id: e.id,
+        type: "message.user",
+        timestamp: e.timestamp,
+        vessel,
+        message: { id: e.message?.id, content: e.message?.content ?? null }
+      };
+    });
+    return { ok: true, events, hasMore: data.has_more ?? false };
+  }
+  // Webhook verification — call this in your webhook handler
+  // body: raw request body string, signature: X-Vessels-Signature header value
+  verifyWebhook(body, signature) {
+    if (!signature.startsWith("sha256=")) return false;
+    const expected = createHmac("sha256", this.apiKey).update(body).digest("hex");
+    const received = signature.slice(7);
+    if (expected.length !== received.length) return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+      diff |= expected.charCodeAt(i) ^ received.charCodeAt(i);
+    }
+    return diff === 0;
+  }
+};
+
+export { Vessels, VesselsAuthError, VesselsRateLimitError, VesselsValidationError };

package/package.json

@@ -0,0 +1,33 @@
+{
+	"name": "vessels-sdk",
+	"version": "0.1.0",
+	"description": "Let your agent reach you. Official Vessels SDK.",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch"
+	},
+	"keywords": ["ai", "agents", "vessels", "llm", "notifications"],
+	"license": "MIT",
+	"devDependencies": {
+		"@types/node": "^25.5.2",
+		"tsup": "^8.5.1",
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"zod": "^3.22"
+	}
+}