@vellumai/assistant 0.3.4 → 0.3.6

package/src/doordash/types.ts

@@ -0,0 +1,367 @@
+/**
+ * Type definitions for DoorDash GraphQL API responses.
+ * These model the raw shapes returned by the API before extraction
+ * into the public-facing interfaces (SearchResult, StoreInfo, etc.).
+ */
+
+// ---------------------------------------------------------------------------
+// Shared / reusable fragments
+// ---------------------------------------------------------------------------
+
+export interface DDTextAttributes {
+  textStyle?: string;
+  textColor?: string;
+}
+
+export interface DDText {
+  title?: string;
+  titleTextAttributes?: DDTextAttributes;
+  subtitle?: string;
+  subtitleTextAttributes?: DDTextAttributes;
+  accessory?: string;
+  accessoryTextAttributes?: DDTextAttributes;
+  description?: string;
+}
+
+export interface DDImage {
+  uri?: string;
+}
+
+export interface DDImages {
+  main?: DDImage;
+}
+
+export interface DDClickEvent {
+  data?: string;
+}
+
+export interface DDEvents {
+  click?: DDClickEvent;
+}
+
+export interface DDAddress {
+  displayAddress?: string;
+}
+
+export interface DDRatings {
+  averageRating?: number;
+  numRatingsDisplayString?: string;
+}
+
+export interface DDFeeLayout {
+  title?: string;
+}
+
+export interface DDPrice {
+  display_string?: string;
+  displayString?: string;
+  unit_amount?: number;
+  unitAmount?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Search / Feed responses
+// ---------------------------------------------------------------------------
+
+export interface DDFacetItem {
+  id?: string;
+  childrenCount?: number;
+  component?: { id?: string; category?: string };
+  name?: string;
+  text?: DDText;
+  images?: DDImages;
+  events?: DDEvents;
+  childrenMap?: DDFacetItem[];
+}
+
+export interface DDFeedSection {
+  id?: string;
+  header?: DDFacetItem;
+  body?: DDFacetItem[];
+  layout?: { omitFooter?: boolean };
+}
+
+export interface DDFacetFeed {
+  body?: DDFeedSection[];
+  page?: DDFacetItem;
+  header?: DDFacetItem;
+  footer?: DDFacetItem;
+  custom?: string;
+  logging?: string;
+}
+
+export interface DDSearchClickData {
+  store_id?: string | number;
+  storeId?: string | number;
+}
+
+// ---------------------------------------------------------------------------
+// Store page responses
+// ---------------------------------------------------------------------------
+
+export interface DDStoreHeader {
+  id?: string;
+  name?: string;
+  description?: string;
+  address?: DDAddress;
+  ratings?: DDRatings;
+  deliveryFeeLayout?: DDFeeLayout;
+  deliveryTimeLayout?: DDFeeLayout;
+  priceRangeDisplayString?: string;
+}
+
+export interface DDMenuCategory {
+  id?: string;
+  name?: string;
+  numItems?: number;
+}
+
+export interface DDMenuBook {
+  menuCategories?: DDMenuCategory[];
+}
+
+export interface DDStoreItem {
+  id?: string;
+  name?: string;
+  description?: string;
+  displayPrice?: string;
+  imageUrl?: string;
+  imgUrl?: string;
+  storeId?: string;
+}
+
+export interface DDItemList {
+  items?: DDStoreItem[];
+}
+
+export interface DDCarousel {
+  items?: DDStoreItem[];
+}
+
+export interface DDStorepageFeed {
+  storeHeader?: DDStoreHeader;
+  menuBook?: DDMenuBook;
+  itemLists?: DDItemList[];
+  carousels?: DDCarousel[];
+}
+
+// ---------------------------------------------------------------------------
+// Retail store feed responses
+// ---------------------------------------------------------------------------
+
+export interface DDRetailStoreStatus {
+  delivery?: { etaDisplayString?: string };
+}
+
+export interface DDRetailStoreHeader {
+  name?: string;
+  description?: string;
+  address?: DDAddress;
+  ratings?: DDRatings;
+  deliveryFeeLayout?: DDFeeLayout;
+  priceRangeDisplayString?: string;
+  status?: DDRetailStoreStatus;
+}
+
+export interface DDRetailStoreDetails {
+  id?: string;
+  name?: string;
+  storeHeader?: DDRetailStoreHeader;
+}
+
+export interface DDRetailProduct {
+  id?: string;
+  name?: string;
+  description?: string;
+  displayPrice?: string;
+  imageUrl?: string;
+  imgUrl?: string;
+  storeId?: string;
+  price?: DDPrice;
+}
+
+export interface DDRetailCollection {
+  products?: DDRetailProduct[];
+  items?: DDRetailProduct[];
+}
+
+export interface DDRetailL1Category {
+  id?: string;
+  name?: string;
+  numItems?: number;
+}
+
+export interface DDRetailStorePageFeed {
+  storeDetails?: DDRetailStoreDetails;
+  l1Categories?: DDRetailL1Category[];
+  collections?: DDRetailCollection[];
+  page?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Retail search responses
+// ---------------------------------------------------------------------------
+
+export interface DDRetailItemImage {
+  remote?: { uri?: string };
+}
+
+export interface DDRetailItemPrice {
+  display_string?: string;
+  unit_amount?: number;
+}
+
+export interface DDRetailItemData {
+  item_id?: string | number;
+  item_name?: string;
+  description?: string;
+  store_id?: string | number;
+  menu_id?: string | number;
+  price?: DDRetailItemPrice;
+}
+
+export interface DDRetailItemCustom {
+  item_data?: DDRetailItemData;
+  image?: DDRetailItemImage;
+}
+
+export interface DDLegoRetailItem {
+  custom?: string;
+}
+
+export interface DDSearchSummary {
+  totalCount?: number;
+  suggestedSearchKeyword?: string;
+}
+
+export interface DDRetailSearchResult {
+  legoRetailItems?: DDLegoRetailItem[];
+  searchSummary?: DDSearchSummary;
+}
+
+// ---------------------------------------------------------------------------
+// Item page responses
+// ---------------------------------------------------------------------------
+
+export interface DDItemHeader {
+  id?: string;
+  name?: string;
+  description?: string;
+  displayString?: string;
+  unitAmount?: number;
+  currency?: string;
+  imgUrl?: string;
+  menuId?: string;
+}
+
+export interface DDOptionChoice {
+  id?: string;
+  name?: string;
+  displayString?: string;
+  unitAmount?: number;
+  defaultQuantity?: number;
+  nestedExtrasList?: DDNestedExtra[];
+}
+
+export interface DDNestedExtra {
+  id?: string;
+  name?: string;
+  isOptional?: boolean;
+  options?: DDNestedExtraChoice[];
+}
+
+export interface DDNestedExtraChoice {
+  id?: string;
+  name?: string;
+  displayString?: string;
+}
+
+export interface DDOptionList {
+  id?: string;
+  name?: string;
+  isOptional?: boolean;
+  minNumOptions?: number;
+  maxNumOptions?: number;
+  options?: DDOptionChoice[];
+}
+
+export interface DDSpecialInstructions {
+  characterMaxLength?: number;
+  placeholderText?: string;
+  isEnabled?: boolean;
+}
+
+export interface DDItemPreferences {
+  specialInstructions?: DDSpecialInstructions;
+}
+
+export interface DDItemPage {
+  itemHeader?: DDItemHeader;
+  optionLists?: DDOptionList[];
+  itemPreferences?: DDItemPreferences;
+}
+
+// ---------------------------------------------------------------------------
+// Cart responses
+// ---------------------------------------------------------------------------
+
+export interface DDCartItemDetail {
+  name?: string;
+}
+
+export interface DDOrderItem {
+  id?: string;
+  item?: DDCartItemDetail;
+  quantity?: number;
+  priceDisplayString?: string;
+}
+
+export interface DDOrder {
+  orderItems?: DDOrderItem[];
+}
+
+export interface DDCartRestaurant {
+  id?: string;
+  name?: string;
+}
+
+export interface DDCart {
+  id?: string;
+  restaurant?: DDCartRestaurant;
+  orders?: DDOrder[];
+  subtotal?: number;
+  total?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Dropoff options responses
+// ---------------------------------------------------------------------------
+
+export interface DDDropoffOption {
+  id?: string;
+  displayString?: string;
+  isDefault?: boolean;
+  isEnabled?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Payment method responses
+// ---------------------------------------------------------------------------
+
+export interface DDPaymentMethod {
+  id?: string;
+  type?: string;
+  last4?: string;
+  isDefault?: boolean;
+  paymentMethodUuid?: string;
+  uuid?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Order responses
+// ---------------------------------------------------------------------------
+
+export interface DDCreateOrderResult {
+  cartId?: string;
+  orderUuid?: string;
+}

package/src/email/providers/agentmail.ts

@@ -7,6 +7,7 @@
 import type { AgentMailClient } from 'agentmail';
 import type { EmailProvider, SetupDomainOpts, CreateInboxOpts, EnsureInboxesOpts, SetupWebhookOpts, CreateDraftOpts, ListDraftsOpts, ListMessagesOpts, ListThreadsOpts } from '../provider.js';
 import type { EmailDomain, DnsRecord, EmailInbox, EmailDraft, EmailMessage, EmailThread, EmailWebhook, ProviderHealth, SendResult } from '../types.js';
+import { ConfigError } from '../../util/errors.js';
 
 const DEFAULT_INBOX_PREFIXES = ['hello', 'support', 'ops'];
 
@@ -201,7 +202,7 @@ export class AgentMailProvider implements EmailProvider {
     if (inboxes.inboxes.length > 0) {
       return inboxes.inboxes[0].inboxId;
     }
-    throw new Error('No inboxes found. Run: vellum email setup inboxes --domain <domain>');
+    throw new ConfigError('No inboxes found. Run: vellum email setup inboxes --domain <domain>');
   }
 }
 

package/src/email/providers/index.ts

@@ -7,6 +7,7 @@
 import type { EmailProvider } from '../provider.js';
 import { getSecureKey } from '../../security/secure-keys.js';
 import { loadRawConfig, getNestedValue } from '../../config/loader.js';
+import { ConfigError } from '../../util/errors.js';
 
 export const SUPPORTED_PROVIDERS = ['agentmail'] as const;
 export type SupportedProvider = (typeof SUPPORTED_PROVIDERS)[number];
@@ -44,7 +45,7 @@ export async function createProvider(name?: SupportedProvider): Promise<EmailPro
         if (apiKey) break;
       }
       if (!apiKey) {
-        throw new Error(
+        throw new ConfigError(
           'No AgentMail API key configured. Run: vellum keys set agentmail <key>',
         );
       }
@@ -53,6 +54,6 @@ export async function createProvider(name?: SupportedProvider): Promise<EmailPro
       return new AgentMailProvider(new AgentMailClient({ apiKey }));
     }
     default:
-      throw new Error(`Unknown email provider: ${providerName}`);
+      throw new ConfigError(`Unknown email provider: ${providerName}`);
   }
 }

package/src/email/service.ts

@@ -31,6 +31,7 @@ import {
 } from '../cli/email-guardrails.js';
 import { createProvider, getActiveProviderName, type SupportedProvider } from './providers/index.js';
 import { loadRawConfig, setNestedValue, saveRawConfig } from '../config/loader.js';
+import { ConfigError } from '../util/errors.js';
 
 // ---------------------------------------------------------------------------
 // Guardrail error
@@ -156,12 +157,12 @@ export class EmailService {
     // Resolve inbox from the "from" address — fail fast if not found
     const health = await p.health();
     if (health.inboxes.length === 0) {
-      throw new Error('No inboxes found. Run: vellum email setup inboxes --domain <domain>');
+      throw new ConfigError('No inboxes found. Run: vellum email setup inboxes --domain <domain>');
     }
     const inbox = health.inboxes.find(i => i.address === input.from || i.id === input.from);
     if (!inbox) {
       const available = health.inboxes.map(i => i.address || i.id).join(', ');
-      throw new Error(`No inbox matches --from "${input.from}". Available: ${available}`);
+      throw new ConfigError(`No inbox matches --from "${input.from}". Available: ${available}`);
     }
     const inboxId = inbox.id;
     return p.createDraft({

package/src/errors.ts

@@ -0,0 +1,43 @@
+/**
+ * Central export point for the Vellum error hierarchy.
+ *
+ * Import from this module to access any named error class:
+ *
+ *   import { VellumError, BackendUnavailableError, RateLimitError, ... } from '../errors.js';
+ *
+ * Full hierarchy (defined in util/errors.ts):
+ *
+ *   VellumError                     — root base
+ *   ├─ BackendError                 — infrastructure / external-service failures
+ *   │  ├─ BackendUnavailableError   — service not reachable or not configured
+ *   │  └─ RateLimitError            — request or token quota exceeded
+ *   ├─ UserError                    — user input / policy violations
+ *   └─ AssistantError               — assistant-logic errors (carries ErrorCode)
+ *      ├─ ProviderError
+ *      ├─ ToolError
+ *      ├─ PermissionDeniedError
+ *      ├─ ConfigError
+ *      ├─ DaemonError
+ *      ├─ IpcError
+ *      ├─ PlatformError
+ *      ├─ IntegrityError
+ *      └─ IngressBlockedError
+ */
+export {
+  ErrorCode,
+  VellumError,
+  BackendError,
+  BackendUnavailableError,
+  RateLimitError,
+  UserError,
+  AssistantError,
+  ProviderError,
+  ToolError,
+  PermissionDeniedError,
+  ConfigError,
+  DaemonError,
+  IpcError,
+  PlatformError,
+  IntegrityError,
+  IngressBlockedError,
+} from './util/errors.js';

package/src/home-base/prebuilt/seed.ts

@@ -94,7 +94,7 @@ export function ensurePrebuiltHomeBaseSeeded(): { appId: string; created: boolea
 
   const metadata = loadSeedMetadata();
   const html = loadPrebuiltHtml();
-  if (html === null) {
+  if (html == null) {
     log.warn('Skipping Home Base seed — prebuilt HTML not available');
     return null;
   }

package/src/hooks/cli.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
-import { existsSync, cpSync, readFileSync, chmodSync, rmSync } from 'node:fs';
+import { cpSync, readFileSync, chmodSync, rmSync } from 'node:fs';
+import { pathExists } from '../util/fs.js';
 import { join, resolve, sep } from 'node:path';
 import { discoverHooks, isValidInstallManifest } from './discovery.js';
 import { setHookEnabled, ensureHookInConfig, removeHook } from './config.js';
@@ -79,13 +80,13 @@ export function registerHooksCommand(program: Command): void {
     .description('Install a hook from a directory')
     .action((hookPath: string) => {
       const srcDir = resolve(hookPath);
-      if (!existsSync(srcDir)) {
+      if (!pathExists(srcDir)) {
         log.error(`Directory not found: ${srcDir}`);
         process.exit(1);
       }
 
       const manifestPath = join(srcDir, 'hook.json');
-      if (!existsSync(manifestPath)) {
+      if (!pathExists(manifestPath)) {
         log.error(`No hook.json found in ${srcDir}`);
         process.exit(1);
       }
@@ -117,7 +118,7 @@ export function registerHooksCommand(program: Command): void {
         process.exit(1);
       }
 
-      if (existsSync(targetDir)) {
+      if (pathExists(targetDir)) {
         log.error(`Hook already installed: ${manifest.name}`);
         process.exit(1);
       }
@@ -125,7 +126,7 @@ export function registerHooksCommand(program: Command): void {
       cpSync(srcDir, targetDir, { recursive: true });
 
       // Make script executable
-      if (existsSync(scriptPath)) {
+      if (pathExists(scriptPath)) {
         chmodSync(scriptPath, 0o755);
       }
 

package/src/hooks/config.ts

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { ensureDir, readTextFileSync } from '../util/fs.js';
 import { getHooksDir } from '../util/platform.js';
 import { getLogger } from '../util/logger.js';
 import type { HookConfig, HookConfigEntry, HookManifest } from './types.js';
@@ -14,14 +15,14 @@ function getConfigPath(): string {
 
 export function loadHooksConfig(): HookConfig {
   const configPath = getConfigPath();
-  if (!existsSync(configPath)) {
+  const raw = readTextFileSync(configPath);
+  if (raw == null) {
     return { version: HOOKS_CONFIG_VERSION, hooks: {} };
   }
 
   try {
-    const raw = readFileSync(configPath, 'utf-8');
     const parsed = JSON.parse(raw) as HookConfig;
-    if (typeof parsed.version !== 'number' || typeof parsed.hooks !== 'object' || parsed.hooks === null) {
+    if (typeof parsed.version !== 'number' || typeof parsed.hooks !== 'object' || parsed.hooks == null) {
       log.warn({ configPath }, 'Invalid hooks config, using defaults');
       return { version: HOOKS_CONFIG_VERSION, hooks: {} };
     }
@@ -34,10 +35,7 @@ export function loadHooksConfig(): HookConfig {
 
 export function saveHooksConfig(config: HookConfig): void {
   const configPath = getConfigPath();
-  const dir = dirname(configPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
+  ensureDir(dirname(configPath));
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
 }
 

package/src/hooks/discovery.ts

@@ -1,5 +1,6 @@
-import { readdirSync, readFileSync, existsSync, type Dirent } from 'node:fs';
+import { readdirSync, readFileSync, type Dirent } from 'node:fs';
 import { join, resolve, relative } from 'node:path';
+import { pathExists } from '../util/fs.js';
 import { getHooksDir } from '../util/platform.js';
 import { loadHooksConfig } from './config.js';
 import { getLogger } from '../util/logger.js';
@@ -23,7 +24,7 @@ const VALID_EVENTS = new Set<string>([
  * (created before those fields were added) continue to be discovered.
  */
 export function isValidManifest(manifest: unknown): manifest is HookManifest {
-  if (typeof manifest !== 'object' || manifest === null) return false;
+  if (typeof manifest !== 'object' || manifest == null) return false;
   const m = manifest as Record<string, unknown>;
   if (typeof m.name !== 'string' || !m.name) return false;
   if (typeof m.script !== 'string' || !m.script) return false;
@@ -50,7 +51,7 @@ export function isValidInstallManifest(manifest: unknown): manifest is HookManif
 
 export function discoverHooks(hooksDir?: string): DiscoveredHook[] {
   const dir = hooksDir ?? getHooksDir();
-  if (!existsSync(dir)) return [];
+  if (!pathExists(dir)) return [];
 
   const config = loadHooksConfig();
   const hooks: DiscoveredHook[] = [];
@@ -68,7 +69,7 @@ export function discoverHooks(hooksDir?: string): DiscoveredHook[] {
 
     const hookDir = join(dir, entry.name);
     const manifestPath = join(hookDir, 'hook.json');
-    if (!existsSync(manifestPath)) continue;
+    if (!pathExists(manifestPath)) continue;
 
     let manifest: unknown;
     try {
@@ -92,7 +93,7 @@ export function discoverHooks(hooksDir?: string): DiscoveredHook[] {
       log.warn({ hookDir, script: manifest.script }, 'Hook script path traversal detected, skipping');
       continue;
     }
-    if (!existsSync(scriptPath)) {
+    if (!pathExists(scriptPath)) {
       log.warn({ hookDir, script: manifest.script }, 'Hook script not found, skipping');
       continue;
     }

package/src/hooks/manager.ts

@@ -1,4 +1,5 @@
-import { watch, existsSync, type FSWatcher } from 'node:fs';
+import { watch, type FSWatcher } from 'node:fs';
+import { pathExists } from '../util/fs.js';
 import { discoverHooks } from './discovery.js';
 import { runHookScript } from './runner.js';
 import { getLogger, isDebug } from '../util/logger.js';
@@ -49,7 +50,7 @@ export class HookManager {
     for (const hook of hooks) {
       try {
         const result = await runHookScript(hook, eventData);
-        if (result.exitCode !== null && result.exitCode !== 0) {
+        if (result.exitCode != null && result.exitCode !== 0) {
           // Blocking hooks on pre-* events cancel the action
           if (isPreEvent && hook.manifest.blocking) {
             log.info({ hook: hook.name, event, exitCode: result.exitCode }, 'Blocking hook rejected action');
@@ -77,7 +78,7 @@ export class HookManager {
 
   watch(): void {
     const hooksDir = getHooksDir();
-    if (!existsSync(hooksDir)) return;
+    if (!pathExists(hooksDir)) return;
 
     this.stopWatching();
 

package/src/hooks/runner.ts

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { basename, extname, join } from 'node:path';
+import { pathExists } from '../util/fs.js';
 import { homedir } from 'node:os';
 import { getRootDir, getWorkspaceDir } from '../util/platform.js';
 import { getHookSettings } from './config.js';
@@ -24,7 +24,7 @@ function resolveBunPath(): string {
   if (found) return found;
 
   const fallback = join(homedir(), '.bun', 'bin', 'bun');
-  if (existsSync(fallback)) return fallback;
+  if (pathExists(fallback)) return fallback;
 
   throw new Error(
     'Cannot find a bun runtime to execute .ts hooks. ' +

package/src/hooks/templates.ts

@@ -1,6 +1,6 @@
-import { existsSync, readdirSync, readFileSync, cpSync, chmodSync, rmSync } from 'node:fs';
+import { readdirSync, readFileSync, cpSync, chmodSync, rmSync, type Dirent } from 'node:fs';
 import { join } from 'node:path';
-import type { Dirent } from 'node:fs';
+import { pathExists } from '../util/fs.js';
 import { getHooksDir } from '../util/platform.js';
 import { ensureHookInConfig } from './config.js';
 import { getLogger } from '../util/logger.js';
@@ -15,7 +15,7 @@ const log = getLogger('hooks-templates');
  */
 export function installTemplates(): void {
   const templatesDir = join(import.meta.dirname ?? __dirname, '../../hook-templates');
-  if (!existsSync(templatesDir)) return;
+  if (!pathExists(templatesDir)) return;
 
   const hooksDir = getHooksDir();
   const entries = readdirSync(templatesDir, { withFileTypes: true }) as Dirent[];
@@ -24,7 +24,7 @@ export function installTemplates(): void {
     if (!entry.isDirectory()) continue;
 
     const targetDir = join(hooksDir, entry.name);
-    if (existsSync(targetDir)) continue; // Never overwrite user hooks
+    if (pathExists(targetDir)) continue; // Never overwrite user hooks
 
     try {
       // Copy template directory
@@ -32,7 +32,7 @@ export function installTemplates(): void {
 
       // Make script executable
       const manifestPath = join(targetDir, 'hook.json');
-      if (existsSync(manifestPath)) {
+      if (pathExists(manifestPath)) {
         const manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
         if (manifest.script) {
           chmodSync(join(targetDir, manifest.script), 0o755);