@voyant-travel/max-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { type AgentCard, type AgentCardKind, type Block, extractCard, parseCard, } from "./cards.js";
+export { defineTool, file } from "./define-tool.js";
+export { type CreateHandlerOptions, createMaxToolsHandler } from "./handler.js";
+export { type ManifestOptions, toManifest, toToolDefinition } from "./manifest.js";
+export type { MaxTool, RemoteToolDefinition, RemoteToolsConfig, ToolCallContext, ToolConfig, ToolExample, ToolFileResult, ToolHandler, ToolTier, WithCard, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,KAAK,EACV,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,KAAK,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,EAAE,KAAK,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAClF,YAAY,EACV,OAAO,EACP,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,QAAQ,EACR,QAAQ,GACT,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+// The generative-UI card contract — optional. Tools can attach a `card` to
+// their result to render a rich widget instead of plain JSON.
+export { extractCard, parseCard, } from "./cards.js";
+export { defineTool, file } from "./define-tool.js";
+export { createMaxToolsHandler } from "./handler.js";
+export { toManifest, toToolDefinition } from "./manifest.js";

package/dist/manifest.d.ts

@@ -0,0 +1,25 @@
+import type { MaxTool, RemoteToolDefinition, RemoteToolsConfig } from "./types.js";
+/** Convert a single tool into its manifest (wire) definition. */
+export declare function toToolDefinition(tool: MaxTool): RemoteToolDefinition;
+export type ManifestOptions = {
+    /** Manifest version string. Defaults to `"1"`. */
+    version?: string;
+    /** Public base URL Voyant should call your tools at. */
+    callBaseUrl?: string;
+    /** Header Voyant sends the auth token in. Defaults to `Authorization`. */
+    authHeaderName?: string;
+};
+/**
+ * Build the manifest you register with Voyant from a set of tools. Each tool's
+ * Zod schema is converted to JSON Schema for the model.
+ *
+ * @example
+ * ```ts
+ * const manifest = toManifest([lookupBooking, createQuote], {
+ *   callBaseUrl: "https://acme.example.com",
+ * })
+ * // -> register `manifest` with Voyant for your operator
+ * ```
+ */
+export declare function toManifest(tools: readonly MaxTool[], options?: ManifestOptions): RemoteToolsConfig;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElF,iEAAiE;AACjE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,oBAAoB,CAWpE;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,OAAO,GAAE,eAAoB,GAC5B,iBAAiB,CAOnB"}

package/dist/manifest.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+/** Convert a single tool into its manifest (wire) definition. */
+export function toToolDefinition(tool) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        ...(tool.usageHints ? { usageHints: tool.usageHints } : {}),
+        ...(tool.examples ? { examples: tool.examples } : {}),
+        inputSchema: jsonSchema(tool.input),
+        ...(tool.outputKind ? { outputKind: tool.outputKind } : {}),
+        tier: tool.tier ?? "read",
+        requiredScopes: tool.requiredScopes ?? [],
+    };
+}
+/**
+ * Build the manifest you register with Voyant from a set of tools. Each tool's
+ * Zod schema is converted to JSON Schema for the model.
+ *
+ * @example
+ * ```ts
+ * const manifest = toManifest([lookupBooking, createQuote], {
+ *   callBaseUrl: "https://acme.example.com",
+ * })
+ * // -> register `manifest` with Voyant for your operator
+ * ```
+ */
+export function toManifest(tools, options = {}) {
+    return {
+        version: options.version ?? "1",
+        ...(options.callBaseUrl ? { callBaseUrl: options.callBaseUrl } : {}),
+        ...(options.authHeaderName ? { authHeaderName: options.authHeaderName } : {}),
+        tools: tools.map(toToolDefinition),
+    };
+}
+/** Zod -> JSON Schema, stripped of the `$schema` preamble. */
+function jsonSchema(schema) {
+    const out = z.toJSONSchema(schema, { target: "draft-7" });
+    delete out.$schema;
+    return out;
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+import type { z } from "zod";
+import type { AgentCard } from "./cards.js";
+/**
+ * How risky a tool is. Voyant uses this to decide whether a call runs
+ * automatically (`read`), is allowed with light guarding (`routine-write`), or
+ * needs explicit user approval before it executes (`destructive`).
+ */
+export type ToolTier = "read" | "routine-write" | "destructive";
+/** A worked example that helps the model call the tool with the right args. */
+export type ToolExample = {
+    /** Something a user might say that should trigger this tool. */
+    userMessage: string;
+    /** The arguments the model should produce for that message. */
+    args: Record<string, unknown>;
+    /** Optional note explaining the example. */
+    notes?: string;
+};
+/**
+ * Context Voyant sends with every tool call. Use it to scope the work to the
+ * calling operator / organization / end user. These ids come from Voyant — your
+ * webhook never has to supply them.
+ */
+export type ToolCallContext = {
+    /** The tool being invoked. */
+    toolName: string;
+    operatorId: string;
+    organizationId: string;
+    userId: string;
+};
+/**
+ * Return this from a handler (via {@link file}) to hand back a downloadable
+ * file — a generated PDF, an export, an image — instead of a JSON payload. Set
+ * the tool's `outputKind: "file"` so Voyant renders it as an attachment.
+ */
+export type ToolFileResult = {
+    type: "file";
+    label: string;
+    filename: string;
+    mediaType: string;
+    downloadUrl: string;
+    expiresAt?: string;
+};
+/**
+ * A plain JSON result optionally carrying a rich {@link AgentCard} that renders
+ * as a widget in the Max chat. Attach a card by returning `{ ...data, card }`.
+ */
+export type WithCard<T extends Record<string, unknown> = Record<string, unknown>> = T & {
+    card?: AgentCard;
+};
+export type ToolHandler<TInput> = (args: TInput, ctx: ToolCallContext) => unknown | Promise<unknown>;
+export type ToolConfig<TSchema extends z.ZodType> = {
+    /** Unique name. Letters, digits, `_` and `-` only. */
+    name: string;
+    /** What the tool does — shown to the model to decide when to call it. */
+    description: string;
+    /** Zod schema for the tool's arguments. Doubles as runtime validation. */
+    input: TSchema;
+    /** Defaults to `read`. */
+    tier?: ToolTier;
+    /** Voyant capability scopes the caller must hold to use the tool. */
+    requiredScopes?: readonly string[];
+    /** Short hints that nudge the model toward correct usage. */
+    usageHints?: readonly string[];
+    /** Worked examples (user message -> args). */
+    examples?: readonly ToolExample[];
+    /** `json` (default) or `file` when the handler returns a {@link ToolFileResult}. */
+    outputKind?: "json" | "file";
+    /** Runs when the tool is called. Receives validated args + call context. */
+    handler: ToolHandler<z.infer<TSchema>>;
+};
+export type MaxTool<TSchema extends z.ZodType = z.ZodType> = ToolConfig<TSchema>;
+/**
+ * The wire shape of a single tool in the manifest Voyant stores for an
+ * operator. Produced by {@link toToolDefinition}; you rarely build it by hand.
+ */
+export type RemoteToolDefinition = {
+    name: string;
+    description: string;
+    usageHints?: readonly string[];
+    examples?: readonly ToolExample[];
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    outputKind?: "json" | "file";
+    tier: ToolTier;
+    requiredScopes: readonly string[];
+};
+/**
+ * The manifest you register with Voyant so Max knows your tools exist and where
+ * to call them. Produced by {@link toManifest}.
+ */
+export type RemoteToolsConfig = {
+    version: string;
+    /** Base URL Voyant calls; tools are invoked at `{callBaseUrl}/v1/max/tools/{name}/call`. */
+    callBaseUrl?: string;
+    /** Header Voyant sends the auth token in. Defaults to `Authorization`. */
+    authHeaderName?: string;
+    /** Secret Voyant presents to your webhook. Stored encrypted by Voyant. */
+    authToken?: string;
+    tools: RemoteToolDefinition[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@voyant-travel/max-sdk",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Write custom tools for Max, Voyant's AI travel agent. Define tools with Zod, generate the manifest Voyant registers, and serve calls with a framework-agnostic request handler.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "biome check src",
+    "format": "biome check --write src",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm run build"
+  },
+  "dependencies": {
+    "zod": "4.3.6"
+  },
+  "devDependencies": {
+    "@voyant-travel/max-tsconfig": "workspace:*",
+    "typescript": "5.9.2",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/max.git",
+    "directory": "packages/sdk"
+  }
+}