@vertesia/tools-sdk 1.5.0-dev.20260725.083715Z → 1.5.0-dev.20260806.125520Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/tools-sdk",
-  "version": "1.5.0-dev.20260725.083715Z",
+  "version": "1.5.0-dev.20260806.125520Z",
   "description": "Tools SDK - utilities for building remote tools",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,19 +18,19 @@
   },
   "devDependencies": {
     "@types/node": "^24.13.3",
-    "typescript": "^6.0.3",
+    "typescript": "7.0.2",
     "vitest": "^4.1.10",
     "@vertesia/tsconfig": "0.1.0"
   },
   "peerDependencies": {
-    "hono": "^4.12.30"
+    "hono": "^4.12.34"
   },
   "dependencies": {
-    "jose": "^6.2.3",
+    "jose": "^6.2.4",
     "zod": "^4.4.3",
-    "@vertesia/client": "1.5.0-dev.20260725.083715Z",
-    "@vertesia/common": "1.5.0-dev.20260725.083715Z",
-    "@llumiverse/common": "1.5.0-dev.20260725.065646Z"
+    "@llumiverse/common": "1.5.0-dev.20260806.124634Z",
+    "@vertesia/common": "1.5.0-dev.20260806.125520Z",
+    "@vertesia/client": "1.5.0-dev.20260806.125520Z"
   },
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
     "agents",
     "typescript"
   ],
-  "gitHead": "57bcc2f27dd17b3387f27c18e89329c4c37f98ac",
+  "gitHead": "416423ef4182d8668809604902a871ca79629298",
   "scripts": {
     "lint": "biome lint src",
     "test": "vitest run",

package/src/server/app-package.test.ts

@@ -1,5 +1,5 @@
 import { PromptRole } from '@llumiverse/common';
-import { PROCESS_DEFINITION_FORMAT_VERSION, TemplateType } from '@vertesia/common';
+import { PROCESS_DEFINITION_FORMAT_VERSION, SystemRoles, TemplateType } from '@vertesia/common';
 import { describe, expect, it } from 'vitest';
 import { ContentTypesCollection } from '../ContentTypesCollection.js';
 import { InteractionCollection } from '../InteractionCollection.js';
@@ -75,6 +75,7 @@ describe('buildAppPackage', () => {
                 src: '/lib/plugin.js',
                 available_in: ['app_portal'],
             },
+            hooks: [{ kind: 'lifecycle', name: 'install', handler: async () => undefined }],
         } satisfies ToolServerConfig;
 
         const pkg = await buildAppPackage(config, {
@@ -87,6 +88,7 @@ describe('buildAppPackage', () => {
         expect(pkg.processes?.map((process) => process.id)).toEqual(['claims:intake']);
         expect(pkg.dashboards?.map((dashboard) => dashboard.id)).toEqual(['claims:ops']);
         expect(pkg.ui?.src).toBe('https://apps.example.test/lib/plugin.js');
+        expect(pkg.hooks).toEqual({ install: '/api/hooks/install' });
     });
 
     it('honors package scopes', async () => {
@@ -110,6 +112,132 @@ describe('buildAppPackage', () => {
         expect(pkg.types?.map((type) => type.id)).toEqual(['claim']);
         expect(pkg.interactions).toBeUndefined();
     });
+
+    it('returns lifecycle and event hook metadata for the hooks scope', async () => {
+        const config = {
+            interactions: [
+                new InteractionCollection({
+                    name: 'claims',
+                    interactions: [{ name: 'review', prompts: [] }],
+                }),
+            ],
+            hooks: [
+                { kind: 'lifecycle', name: 'install', handler: async () => undefined },
+                { kind: 'lifecycle', name: 'uninstall', handler: async () => undefined },
+                {
+                    kind: 'event',
+                    name: 'content-updated',
+                    description: 'Processes updated content.',
+                    handler: async () => undefined,
+                },
+            ],
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, { scope: 'hooks' });
+
+        expect(pkg.hooks).toEqual({
+            install: '/api/hooks/install',
+            uninstall: '/api/hooks/uninstall',
+            events: [
+                {
+                    name: 'content-updated',
+                    path: '/api/hooks/content-updated',
+                    description: 'Processes updated content.',
+                },
+            ],
+        });
+        expect(pkg.interactions).toBeUndefined();
+    });
+
+    it('returns subscriptions that reference registered event hooks', async () => {
+        const config = {
+            hooks: [
+                {
+                    kind: 'event',
+                    name: 'content-updated',
+                    handler: async () => undefined,
+                },
+            ],
+            subscriptions: [
+                {
+                    id: 'content-updated',
+                    name: 'Content updated',
+                    description: 'Refresh app-owned projections after content changes.',
+                    hook: 'content-updated',
+                    filter: { action: ['update'], resource_type: ['content_object'] },
+                    run_as_role: SystemRoles.automation,
+                    priority: 'normal',
+                },
+            ],
+        } satisfies ToolServerConfig;
+
+        const pkg = await buildAppPackage(config, { scope: 'subscriptions' });
+
+        expect(pkg.subscriptions).toEqual(config.subscriptions);
+        expect(pkg.hooks).toBeUndefined();
+    });
+
+    it('rejects subscriptions that reference missing or lifecycle hooks', async () => {
+        const missingHook = {
+            subscriptions: [
+                {
+                    id: 'content-updated',
+                    name: 'Content updated',
+                    hook: 'content-updated',
+                    filter: { action: ['update'] },
+                    run_as_role: SystemRoles.automation,
+                },
+            ],
+        } satisfies ToolServerConfig;
+        await expect(buildAppPackage(missingHook, { scope: 'subscriptions' })).rejects.toThrow(
+            /references missing hook 'content-updated'/,
+        );
+
+        const lifecycleHook = {
+            hooks: [{ kind: 'lifecycle', name: 'install', handler: async () => undefined }],
+            subscriptions: [
+                {
+                    id: 'on-install',
+                    name: 'On install',
+                    hook: 'install',
+                    filter: { action: ['installed'] },
+                    run_as_role: SystemRoles.automation,
+                },
+            ],
+        } satisfies ToolServerConfig;
+        await expect(buildAppPackage(lifecycleHook, { scope: 'subscriptions' })).rejects.toThrow(
+            /must reference an event hook/,
+        );
+    });
+
+    it('rejects duplicate or non-kebab-case subscription ids', async () => {
+        const eventHook = {
+            kind: 'event' as const,
+            name: 'content-updated',
+            handler: async () => undefined,
+        };
+        const subscription = {
+            id: 'content-updated',
+            name: 'Content updated',
+            hook: 'content-updated',
+            filter: { action: ['update'] },
+            run_as_role: SystemRoles.automation,
+        };
+
+        await expect(
+            buildAppPackage(
+                { hooks: [eventHook], subscriptions: [subscription, { ...subscription }] },
+                { scope: 'subscriptions' },
+            ),
+        ).rejects.toThrow(/Duplicate app event subscription id 'content-updated'/);
+
+        await expect(
+            buildAppPackage(
+                { hooks: [eventHook], subscriptions: [{ ...subscription, id: 'Content Updated' }] },
+                { scope: 'subscriptions' },
+            ),
+        ).rejects.toThrow(/must be kebab case/);
+    });
 });
 
 describe('buildAppPackage type identity', () => {

package/src/server/app-package.ts

@@ -158,6 +158,57 @@ const builders: Record<Exclude<AppPackageScope, 'all'>, AppPackageBuilder> = {
         }
         pkg.activities = allActivities;
     },
+    async hooks(pkg: AppPackage, config: ToolServerConfig) {
+        const prefix = config.prefix || '/api';
+        const lifecycleHooks = new Set(
+            config.hooks?.filter((hook) => hook.kind === 'lifecycle').map((hook) => hook.name),
+        );
+        const eventHooks = (config.hooks ?? [])
+            .filter((hook) => hook.kind === 'event')
+            .map((hook) => ({
+                name: hook.name,
+                path: `${prefix}/hooks/${hook.name}`,
+                ...(hook.description ? { description: hook.description } : {}),
+            }));
+        if (lifecycleHooks.size > 0 || eventHooks.length > 0) {
+            pkg.hooks = {
+                ...(lifecycleHooks.has('install') && { install: `${prefix}/hooks/install` }),
+                ...(lifecycleHooks.has('uninstall') && { uninstall: `${prefix}/hooks/uninstall` }),
+                ...(eventHooks.length > 0 && { events: eventHooks }),
+            };
+        }
+    },
+    async subscriptions(pkg: AppPackage, config: ToolServerConfig) {
+        const subscriptions = config.subscriptions ?? [];
+        const seenIds = new Set<string>();
+        const hooksByName = new Map((config.hooks ?? []).map((hook) => [hook.name, hook]));
+
+        for (const subscription of subscriptions) {
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(subscription.id)) {
+                throw new Error(
+                    `Invalid app event subscription id '${subscription.id}'. Subscription ids must be kebab case.`,
+                );
+            }
+            if (seenIds.has(subscription.id)) {
+                throw new Error(`Duplicate app event subscription id '${subscription.id}'.`);
+            }
+            seenIds.add(subscription.id);
+
+            const hook = hooksByName.get(subscription.hook);
+            if (!hook) {
+                throw new Error(
+                    `App event subscription '${subscription.id}' references missing hook '${subscription.hook}'.`,
+                );
+            }
+            if (hook.kind !== 'event') {
+                throw new Error(
+                    `App event subscription '${subscription.id}' must reference an event hook; '${subscription.hook}' is a lifecycle hook.`,
+                );
+            }
+        }
+
+        pkg.subscriptions = subscriptions.map((subscription) => ({ ...subscription }));
+    },
 };
 
 function normalizeScopes(scope: BuildAppPackageOptions['scope']): Set<AppPackageScope> {
@@ -184,6 +235,8 @@ export async function buildAppPackage(
         await builders.ui(pkg, config, options);
         await builders.settings(pkg, config, options);
         await builders.activities(pkg, config, options);
+        await builders.hooks(pkg, config, options);
+        await builders.subscriptions(pkg, config, options);
     } else {
         if (scopes.has('tools')) {
             await builders.tools(pkg, config, options);
@@ -218,6 +271,12 @@ export async function buildAppPackage(
         if (scopes.has('activities')) {
             await builders.activities(pkg, config, options);
         }
+        if (scopes.has('hooks')) {
+            await builders.hooks(pkg, config, options);
+        }
+        if (scopes.has('subscriptions')) {
+            await builders.subscriptions(pkg, config, options);
+        }
     }
 
     return pkg;

package/src/server/hooks.test.ts

@@ -0,0 +1,158 @@
+import type { AuthTokenPayload, PlatformEvent } from '@vertesia/common';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { AppEventHookPayload, AppLifecycleHookContext } from '../types.js';
+
+const authorizeMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../auth.js', () => ({ authorize: authorizeMock }));
+
+import { createToolServer } from '../server.js';
+
+const event = {
+    event_id: 'event-1',
+    root_event_id: 'event-1',
+    hop_count: 0,
+    event_category: 'content',
+    action: 'updated',
+    resource_type: 'content_object',
+    resource_id: 'object-1',
+    account_id: 'account-1',
+    project_id: 'project-1',
+    tenant_id: 'account-1_project-1',
+    timestamp: '2026-08-05T10:00:00.000Z',
+    source: 'zeno-server',
+} satisfies PlatformEvent;
+
+const eventPayload = {
+    event,
+    delivery: {
+        id: 'delivery-1',
+        subscription_id: 'subscription-1',
+        attempt: 1,
+    },
+} satisfies AppEventHookPayload;
+
+describe('app hooks', () => {
+    beforeEach(() => {
+        authorizeMock.mockReset();
+        authorizeMock.mockResolvedValue({
+            token: 'project-token',
+            payload: { project: { id: 'project-1' } } as AuthTokenPayload,
+            getClient: vi.fn(),
+        });
+    });
+
+    it('executes a registered hook with authenticated context and metadata', async () => {
+        const install = vi.fn(async (_context: AppLifecycleHookContext) => ({ message: 'installed' }));
+        const app = createToolServer({
+            disableHtml: true,
+            hooks: [{ kind: 'lifecycle', name: 'install', handler: install }],
+        });
+
+        const response = await app.request('/api/hooks/install', {
+            method: 'POST',
+            headers: { Authorization: 'Bearer project-token', 'Content-Type': 'application/json' },
+            body: JSON.stringify({ metadata: { app_install_id: 'install-1', app_settings: { locale: 'en' } } }),
+        });
+
+        expect(response.status).toBe(200);
+        await expect(response.json()).resolves.toEqual({ ok: true, message: 'installed' });
+        expect(install).toHaveBeenCalledWith(
+            expect.objectContaining({
+                token: 'project-token',
+                metadata: { app_install_id: 'install-1', app_settings: { locale: 'en' } },
+            }),
+        );
+    });
+
+    it('returns 404 when the hook is not registered', async () => {
+        const app = createToolServer({ disableHtml: true });
+
+        const response = await app.request('/api/hooks/uninstall', {
+            method: 'POST',
+            headers: { Authorization: 'Bearer project-token', 'Content-Type': 'application/json' },
+            body: '{}',
+        });
+
+        expect(response.status).toBe(404);
+        expect(authorizeMock).not.toHaveBeenCalled();
+    });
+
+    it('executes an event hook with the canonical delivery envelope and authenticated context', async () => {
+        const contentUpdated = vi.fn(async (_payload: AppEventHookPayload) => ({ message: 'processed' }));
+        const app = createToolServer({
+            disableHtml: true,
+            hooks: [
+                {
+                    kind: 'event',
+                    name: 'content-updated',
+                    description: 'Processes updated content.',
+                    handler: contentUpdated,
+                },
+            ],
+        });
+
+        const response = await app.request('/api/hooks/content-updated', {
+            method: 'POST',
+            headers: { Authorization: 'Bearer project-token', 'Content-Type': 'application/json' },
+            body: JSON.stringify(eventPayload),
+        });
+
+        expect(response.status).toBe(200);
+        await expect(response.json()).resolves.toEqual({ ok: true, message: 'processed' });
+        expect(contentUpdated).toHaveBeenCalledWith(
+            eventPayload,
+            expect.objectContaining({ token: 'project-token', payload: { project: { id: 'project-1' } } }),
+        );
+    });
+
+    it('rejects malformed event hook payloads before authentication', async () => {
+        const handler = vi.fn(async () => undefined);
+        const app = createToolServer({
+            disableHtml: true,
+            hooks: [{ kind: 'event', name: 'content-updated', handler }],
+        });
+
+        const response = await app.request('/api/hooks/content-updated', {
+            method: 'POST',
+            headers: { Authorization: 'Bearer project-token', 'Content-Type': 'application/json' },
+            body: JSON.stringify({ event: eventPayload.event }),
+        });
+
+        expect(response.status).toBe(400);
+        expect(handler).not.toHaveBeenCalled();
+        expect(authorizeMock).not.toHaveBeenCalled();
+    });
+
+    it.each(['install', 'uninstall'])('reserves the lifecycle hook name %s', (name) => {
+        expect(() =>
+            createToolServer({
+                disableHtml: true,
+                hooks: [{ kind: 'event', name, handler: async () => undefined }],
+            }),
+        ).toThrow(`App event hook name is reserved: ${name}`);
+    });
+
+    it('rejects event hook names that are not safe path segments', () => {
+        expect(() =>
+            createToolServer({
+                disableHtml: true,
+                hooks: [{ kind: 'event', name: 'content/updated', handler: async () => undefined }],
+            }),
+        ).toThrow('Invalid app event hook name: content/updated');
+    });
+
+    it('rejects duplicate lifecycle hook registrations', () => {
+        const handler = vi.fn(async () => undefined);
+
+        expect(() =>
+            createToolServer({
+                disableHtml: true,
+                hooks: [
+                    { kind: 'lifecycle', name: 'install', handler },
+                    { kind: 'lifecycle', name: 'install', handler },
+                ],
+            }),
+        ).toThrow('Duplicate app hook: install');
+    });
+});

package/src/server/hooks.ts

@@ -0,0 +1,95 @@
+import { AppEventHookPayloadSchema } from '@vertesia/common/api-schemas';
+import type { Context, Hono } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import { authorize } from '../auth.js';
+import type {
+    AppEventHookDefinition,
+    AppEventHookPayload,
+    AppLifecycleHookContext,
+    AppLifecycleHookDefinition,
+    AppLifecycleHookName,
+    AppLifecycleHookPayload,
+    AppLifecycleHookResult,
+} from '../types.js';
+import type { ToolContext, ToolServerConfig } from './types.js';
+
+const HOOK_NAMES = new Set<AppLifecycleHookName>(['install', 'uninstall']);
+const EVENT_HOOK_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export function createHooksRoute(app: Hono, basePath: string, config: ToolServerConfig) {
+    const hooks = new Map<string, AppLifecycleHookDefinition | AppEventHookDefinition>();
+    for (const hook of config.hooks ?? []) {
+        if (hook.kind === 'lifecycle' && !HOOK_NAMES.has(hook.name)) {
+            throw new Error(`Unknown app lifecycle hook: ${hook.name}`);
+        }
+        if (hook.kind === 'event' && !EVENT_HOOK_NAME_PATTERN.test(hook.name)) {
+            throw new Error(`Invalid app event hook name: ${hook.name}`);
+        }
+        if (hook.kind === 'event' && HOOK_NAMES.has(hook.name as AppLifecycleHookName)) {
+            throw new Error(`App event hook name is reserved: ${hook.name}`);
+        }
+        if (hooks.has(hook.name)) {
+            throw new Error(`Duplicate app hook: ${hook.name}`);
+        }
+        hooks.set(hook.name, hook);
+    }
+
+    app.post(`${basePath}/:name`, async (c: Context) => {
+        const name = c.req.param('name') ?? '';
+        const hook = hooks.get(name);
+        if (!hook) {
+            throw new HTTPException(404, { message: `App hook is not registered: ${name}` });
+        }
+
+        const requestContext = c as unknown as ToolContext;
+        if (hook.kind === 'event') {
+            return executeEventHook(c, requestContext, hook);
+        }
+
+        const payload = parseHookPayload(requestContext.requestBody);
+        const metadata = payload.metadata ?? {};
+        const session = await authorize(c, metadata.endpoints, { toolName: `hook:${name}` });
+        const context: AppLifecycleHookContext = {
+            token: session.token,
+            payload: session.payload,
+            getClient: () => session.getClient(),
+            metadata,
+        };
+        const result = await hook.handler(context);
+
+        return c.json({ ok: true, ...(result ?? {}) } satisfies { ok: true } & AppLifecycleHookResult);
+    });
+}
+
+async function executeEventHook(c: Context, requestContext: ToolContext, hook: AppEventHookDefinition) {
+    const eventPayload = parseEventHookPayload(requestContext.requestBody);
+    const session = await authorize(c, undefined, { toolName: `hook:${hook.name}` });
+    const context = {
+        token: session.token,
+        payload: session.payload,
+        getClient: () => session.getClient(),
+    };
+    const result = await hook.handler(eventPayload, context);
+
+    return c.json({ ok: true, ...(result ?? {}) } satisfies { ok: true } & AppLifecycleHookResult);
+}
+
+function parseHookPayload(body: unknown): AppLifecycleHookPayload {
+    if (body === undefined) return {};
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+        throw new HTTPException(400, { message: 'Invalid lifecycle hook payload' });
+    }
+    const metadata = (body as AppLifecycleHookPayload).metadata;
+    if (metadata !== undefined && (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))) {
+        throw new HTTPException(400, { message: 'Invalid lifecycle hook metadata' });
+    }
+    return { metadata };
+}
+
+function parseEventHookPayload(body: unknown): AppEventHookPayload {
+    const result = AppEventHookPayloadSchema.safeParse(body);
+    if (!result.success) {
+        throw new HTTPException(400, { message: 'Invalid event hook payload' });
+    }
+    return result.data;
+}

package/src/server/types.ts

@@ -14,7 +14,12 @@ import type { InteractionCollection } from '../InteractionCollection.js';
 import type { RenderingTemplateCollection } from '../RenderingTemplateCollection.js';
 import type { SkillCollection } from '../SkillCollection.js';
 import type { ToolCollection } from '../ToolCollection.js';
-import type { MCPConnectionDetails, ToolExecutionPayload } from '../types.js';
+import type {
+    AppEventSubscriptionDefinition,
+    AppHookDefinition,
+    MCPConnectionDetails,
+    ToolExecutionPayload,
+} from '../types.js';
 
 /**
  * Extended context with parsed payload for tool/skill execution
@@ -26,6 +31,8 @@ export interface ToolContext extends Context {
     toolUseId?: string;
     /** The tool_use.tool_name from the payload */
     toolName?: string;
+    /** Parsed JSON body for non-tool routes such as lifecycle hooks. */
+    requestBody?: unknown;
 }
 
 /**
@@ -90,6 +97,12 @@ export interface ToolServerConfig {
      */
     mcpProviders?: MCPProviderConfig[];
 
+    /** Authenticated application hooks aggregated from active application modules. */
+    hooks?: AppHookDefinition[];
+
+    /** App-owned subscriptions whose delivery target is a registered event hook. */
+    subscriptions?: AppEventSubscriptionDefinition[];
+
     /**
      * A JSON schema defining settings for the application using this server
      */

package/src/server.ts

@@ -6,6 +6,7 @@ import { createActivitiesRoute } from './server/activities.js';
 import { createPackageRoute } from './server/app-package.js';
 import { createContentTypesRoute } from './server/content-types.js';
 import { createDashboardsRoute } from './server/dashboards.js';
+import { createHooksRoute } from './server/hooks.js';
 import { createInteractionsRoute } from './server/interactions.js';
 import { createMcpRoute } from './server/mcp.js';
 import { createProcessesRoute } from './server/processes.js';
@@ -68,6 +69,7 @@ export function createToolServer(config: ToolServerConfig): Hono {
             try {
                 const text = await c.req.text();
                 const body = JSON.parse(text);
+                ctx.requestBody = body;
                 const result = ToolExecutionPayloadSchema.safeParse(body);
                 if (result.success) {
                     ctx.payload = result.data as ToolExecutionPayload;
@@ -112,6 +114,7 @@ export function createToolServer(config: ToolServerConfig): Hono {
     });
 
     createPackageRoute(app, `${prefix}/package`, config);
+    createHooksRoute(app, `${prefix}/hooks`, config);
     createToolsRoute(app, `${prefix}/tools`, config);
     createSkillsRoute(app, `${prefix}/skills`, config);
     createWidgetsRoute(app, `${prefix}/widgets`, config);