@amalgm/automations 0.2.2 → 0.2.4

package/AXIOMS.md

@@ -24,49 +24,57 @@
 9. Supabase is authoritative for automations, triggers, workflow source, and
    permanent run history. A definition edit or deletion never rewrites prior
    runs.
-10. Webhook secrets are persisted but write-only: normal reads reveal only that
-   a secret is configured.
-11. Run history is read-only in the control plane and always scoped to its
+10. A webhook URL is a rotatable bearer capability for exactly one trigger.
+    Possession plus any configured provider proof admits that trigger; source
+    and event labels never form a second routing gate. Its random locator is not
+    sufficient without the hosted service's HMAC, and caller input never
+    supplies an owner or target.
+11. Optional provider signing secrets are persisted but write-only: normal
+    reads reveal only that a secret is configured.
+12. Run history is read-only in the control plane and always scoped to its
     automation's owner.
-12. Storage records, Supabase RPCs, HTTP details, and MCP protocol details are
+13. Storage records, Supabase RPCs, HTTP details, and MCP protocol details are
     implementation concerns, not SDK concepts.
-13. The control-plane SDK is the only configuration write path. The delivery
+14. The control-plane SDK is the only configuration write path. The delivery
     rail reads that configuration and writes only schedule clocks and run
     state; it never owns a second automation-definition API.
-14. Admitting a run atomically verifies the current enabled configuration,
+15. Admitting a run atomically verifies the current enabled configuration,
     stores a secret-free snapshot, and, for a schedule, advances exactly the
     firing instant that was claimed.
-15. Legacy local automation storage is not a compatibility authority. Engine
-    cutover migrates callers to this SDK and then deletes the old store.
-16. Event ingress returns success only after every admitted run is durable in
-    Supabase. Its recent-event list is a bounded, secret-free operational view,
-    never a second event or run authority.
-17. A finite schedule decrements its durable remaining occurrence count in the
+16. Legacy local automation storage is not a compatibility authority. Engine
+    is deprecated read-only evidence; active callers use this SDK and its
+    standalone service, and no old store may run beside them.
+17. Event ingress returns success only after its admitted run is durable in
+    Supabase. A repeated explicit delivery id resolves to the same run.
+18. A finite schedule decrements its durable remaining occurrence count in the
     same transaction that admits a run; zero disables the trigger.
-18. A machine receives work only by exclusively leasing runs whose persisted
+19. A machine receives work only by exclusively leasing runs whose persisted
     target equals the `computer_id` in its DPoP-bound access token.
-19. The configured public origin, never forwarding headers, reconstructs the
+20. The configured public origin, never forwarding headers, reconstructs the
     DPoP request URL behind the Fly proxy.
-20. Machine execution consumes the immutable workflow snapshot stored on the
+21. Machine execution consumes the immutable workflow snapshot stored on the
     run. It never rediscovers or silently updates the automation definition.
-21. A compiled workflow is a small declarative sequence of one or more tool actions. The
+22. A compiled workflow is a small declarative sequence of one or more tool actions. The
     executor receives tool calling as a host capability and never embeds a
     Channels, Shell, CLI, or provider special case.
-22. Automations is a standalone hosted service. Gateway owns none of its API,
+23. Automations is a standalone hosted service. Gateway owns none of its API,
     scheduling, claim, execution, or persistence path.
-23. The durable run ledger is the offline queue. The platform never keeps a
+24. The durable run ledger is the offline queue. The platform never keeps a
     second online-machine delivery buffer and never drops an unclaimed run.
-24. A run advances through its immutable plan in order. Every step transition
+25. A run advances through its immutable plan in order. Every step transition
     commits under the run's current lease before execution advances, and a
     completed step is never intentionally invoked again.
-25. A machine may begin an action only after the service confirms its current
+26. A machine may begin an action only after the service confirms its current
     lease. It renews that lease while the action is running and stops advancing
     when renewal fails.
-26. One run-step pair has one stable idempotency key. Step ids are unique in a
+27. One run-step pair has one stable idempotency key. Step ids are unique in a
     plan, and every action host receives that key and a cancellation signal.
-27. Only transient transport failures retry. They release the same run with a
+28. Only transient transport failures retry. They release the same run with a
     bounded future retry time and retain completed step output; invalid plans,
     missing actions, authorization failures, and other deterministic errors
     are terminal.
-28. The selected target executes every action effect. The hosted service owns
+29. The selected target executes every action effect. The hosted service owns
     only configuration, admission, leases, the step journal, and run history.
+30. Run Now is triggerless manual admission. It atomically snapshots the
+    current enabled automation and compiled workflow into the pending ledger;
+    it never executes inline or changes a trigger's schedule state.

package/PURPOSE.md

@@ -3,7 +3,7 @@
 ## Purpose
 
 Automations is the sole owner of Amalgm automation behavior and data. It lets an
-authenticated user create, inspect, change, and delete automation
+authenticated user create, inspect, change, delete, and manually run automation
 configuration — an automation belongs to one user and one target, may own any
 number of scheduled and webhook triggers, and may own one workflow script — and
 have each trigger occurrence run on the selected existing Amalgm machine.
@@ -13,7 +13,7 @@ complete workflow, and permanent run history.
 The product has two composable halves over that one state:
 
 - **The configuration control plane** — one ergonomic, auth-bound SDK contract
-  for automation CRUD and run-history reads. The HTTP API, CLI, MCP server, and
+  for automation CRUD, manual run admission, and run-history reads. The HTTP API, CLI, MCP server, and
   skill are adapters over that contract; they do not access Supabase directly
   or implement lifecycle rules.
 - **The delivery rail** — trigger admission, scheduling, and run state: the
@@ -42,10 +42,15 @@ occurrence count in durable state, so “every minute for ten minutes” means t
 admitted runs and then an automatically disabled trigger — not a timer that a
 machine must remember.
 
-The event HTTP adapter is one thin door over that delivery rail. It bounds and
-parses the webhook body, resolves the authenticated target supplied by the
-host, and returns only after matching runs have been stored in Supabase. Its
-recent-event response is an ephemeral, secret-free operational projection.
+The event HTTP adapter is one thin door over that delivery rail. Every webhook
+trigger owns one opaque URL under `automations.amalgm.ai`; the URL resolves the
+trigger, owner, and target, so a caller never supplies routing identity. The
+adapter bounds and parses the body, optionally verifies the provider's signing
+secret, deduplicates explicit provider delivery ids, and returns only after the
+run has been stored in Supabase. Provider source and event labels describe the
+occurrence; they are not a second routing gate after the URL has selected the
+trigger. The signed URL can be rotated without changing the automation, and its
+usable bearer token cannot be reconstructed from the database alone.
 
 Amalgm supplies a resolved authenticated principal from its user session or
 HMAC-refresh flow; future API keys resolve to the same principal capability.
@@ -57,7 +62,8 @@ connectivity, and narrow host capabilities. The product receives identity and
 scopes — never raw credentials or Core storage — and neither side reaches into
 the other's storage or reimplements the other's decisions.
 
-This extraction is complete only when every Automations surface in Engine calls
-this product service, product state has one writer, migrated behavior has parity
-tests, and the local `amalgm-mcp` automation implementation and storage are
-deleted rather than retained as a compatibility layer.
+This repository and its standalone Fly host are the active Automations
+authority. Shell calls the published machine-claim and execution contracts
+directly; the UI calls the hosted control plane through the published client.
+Any remaining Engine automation code is deprecated migration/parity evidence,
+not a cutover dependency or compatibility authority.

package/README.md

@@ -25,12 +25,19 @@ await sdk.triggers.schedule.create(automation.id, {
   timezone: 'America/Los_Angeles',
   maxOccurrences: 10,
 });
+
+const run = await sdk.runs.runNow(automation.id, {
+  input: { requestedFrom: 'automation-page' },
+  idempotencyKey: crypto.randomUUID(),
+});
 ```
 
 That schedule admits exactly ten durable runs, then disables itself. If the
 machine is offline, the runs remain pending. Shell later claims only work whose
 target matches its DPoP `computer_id`, executes the immutable tool-action plan,
-and commits the result.
+and commits the result. Run Now returns the newly admitted `pending` run; it
+uses that same machine execution path and never executes workflow effects in
+the API request.
 
 ## Surfaces
 
@@ -49,7 +56,8 @@ or depend on Amalgm Gateway.
 An automation belongs to one user and target. It owns any number of schedule
 or webhook triggers and zero or one workflow. Supabase owns definitions,
 schedule clocks, immutable run snapshots, machine leases, and permanent run
-history. Webhook secrets are write-only.
+history. Every webhook trigger has one rotatable URL; an optional provider
+signing secret is write-only.
 
 Executable workflows use one small, non-empty format:
 
@@ -71,11 +79,31 @@ one action-calling capability, and each step receives the stable idempotency key
 
 The control API lives under `/v1/automations`. The machine execution API is:
 
+```text
+POST /v1/automations/:automationId/runs
+```
+
+The optional JSON body contains `input` and an `idempotencyKey`. Reusing the
+key for the same automation returns the same admitted run.
+
+The machine execution API is:
+
 ```text
 POST  /v1/machine/runs/claim
 PATCH /v1/machine/runs/:runId
 ```
 
+Public webhook admission uses the URL returned on each webhook trigger:
+
+```text
+POST https://automations.amalgm.ai/e/<opaque-capability>
+```
+
+That URL selects the exact trigger. Provider source and event labels are
+recorded as occurrence metadata, not used as another routing condition.
+`Idempotency-Key` and common provider delivery-id headers deduplicate retries
+against the same trigger. The caller never supplies a user or target id.
+
 The target is never accepted in a machine request. It comes from the verified
 access token. Run leases expire and are safely reclaimable; terminal updates
 must present the active lease token.

package/dist/host/config.d.ts

@@ -1,6 +1,8 @@
 export interface AutomationsHostConfig {
     readonly port: number;
     readonly publicOrigin: string;
+    readonly webhookOrigin: string;
+    readonly webhookTokenKey: string;
     readonly supabaseUrl: string;
     readonly supabaseServiceRoleKey: string;
     readonly authorizationIssuer: string;

package/dist/host/config.js

@@ -2,6 +2,8 @@ export function automationsHostConfig(env = process.env) {
     return Object.freeze({
         port: integer(env.PORT, 8080, 1, 65_535),
         publicOrigin: url(env.AMALGAM_PUBLIC_ORIGIN, 'AMALGAM_PUBLIC_ORIGIN'),
+        webhookOrigin: url(env.AUTOMATIONS_WEBHOOK_ORIGIN, 'AUTOMATIONS_WEBHOOK_ORIGIN'),
+        webhookTokenKey: secret(env.AUTOMATIONS_WEBHOOK_TOKEN_KEY, 'AUTOMATIONS_WEBHOOK_TOKEN_KEY'),
         supabaseUrl: url(env.SUPABASE_URL ?? env.NEXT_PUBLIC_SUPABASE_URL, 'SUPABASE_URL'),
         supabaseServiceRoleKey: required(env.SUPABASE_SERVICE_ROLE_KEY, 'SUPABASE_SERVICE_ROLE_KEY'),
         authorizationIssuer: url(env.AMALGM_AUTHORIZATION_ISSUER, 'AMALGM_AUTHORIZATION_ISSUER'),
@@ -13,6 +15,12 @@ function required(value, name) {
         throw new Error(`${name} is required`);
     return value.trim();
 }
+function secret(value, name) {
+    const result = required(value, name);
+    if (Buffer.byteLength(result) < 32)
+        throw new Error(`${name} must contain at least 32 bytes`);
+    return result;
+}
 function url(value, name) {
     const parsed = new URL(required(value, name));
     const local = parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1';

package/dist/host/main.js

@@ -8,6 +8,7 @@ import { createMachineRunsApi } from '../src/machine-http.js';
 import { SupabaseAutomationCrudRepository } from '../src/supabase-crud.js';
 import { SupabaseMachineRunRepository } from '../src/supabase-machine.js';
 import { SupabaseStore } from '../src/supabase-store.js';
+import { WebhookEndpoints } from '../src/webhook.js';
 import { createAutomationsAuthenticators } from './auth.js';
 import { automationsHostConfig } from './config.js';
 import { createAutomationsHost } from './server.js';
@@ -19,9 +20,10 @@ const authentication = createAutomationsAuthenticators({
     issuer: config.authorizationIssuer,
     supabase,
 });
+const webhooks = new WebhookEndpoints(config.webhookOrigin, config.webhookTokenKey);
 const delivery = new Automations(new SupabaseStore(supabase), (event, details) => log(event, details));
 const controlApi = createAutomationApi({
-    service: new AutomationCrudService(new SupabaseAutomationCrudRepository(supabase)),
+    service: new AutomationCrudService(new SupabaseAutomationCrudRepository(supabase), () => new Date(), webhooks),
     authenticate: authentication.control,
 });
 const machineRepository = new SupabaseMachineRunRepository(supabase);
@@ -31,7 +33,7 @@ const machineApi = createMachineRunsApi({
 });
 const eventsApi = createAutomationEventsApi({
     delivery,
-    target: async (request) => eventTarget(request),
+    endpoints: webhooks,
 });
 const host = createAutomationsHost({
     publicOrigin: config.publicOrigin,
@@ -49,11 +51,3 @@ for (const signal of ['SIGINT', 'SIGTERM']) {
 function log(event, details = {}) {
     console.log(JSON.stringify({ service: 'amalgm-automations', event, ...details }));
 }
-function eventTarget(request) {
-    const userId = request.headers.get('x-amalgm-user-id')?.trim() ?? '';
-    const targetId = request.headers.get('x-amalgm-target-id')?.trim() ?? '';
-    if (!/^[0-9a-f]{8}-[0-9a-f-]{27}$/i.test(userId) || !targetId) {
-        throw Object.assign(new Error('Webhook routing headers are required'), { status: 400 });
-    }
-    return { userId, targetId };
-}

package/dist/host/server.js

@@ -19,7 +19,7 @@ export function createAutomationsHost(options) {
                 return send(outgoing, Response.json({ ok: true }));
             const request = await webRequest(incoming, options.publicOrigin, options.maxRequestBodyBytes ?? 2 * 1024 * 1024);
             const pathname = new URL(request.url).pathname;
-            const api = pathname === '/events' && options.eventsApi
+            const api = pathname.startsWith('/e/') && options.eventsApi
                 ? options.eventsApi
                 : pathname.startsWith('/v1/machine/') ? options.machineApi : options.controlApi;
             await send(outgoing, await api(request));

package/dist/src/automations.d.ts

@@ -1,7 +1,15 @@
-import type { AutomationLog, AutomationRun, AutomationStore, AutomationTarget, Json } from './types.js';
+import type { AutomationLog, AutomationRun, AutomationStore, Json } from './types.js';
 export declare class EventRejectedError extends Error {
     constructor();
 }
+export declare class EventEndpointNotFoundError extends Error {
+    constructor();
+}
+export interface EventAdmission {
+    run: AutomationRun | null;
+    source: string;
+    event: string;
+}
 /** Admits trigger occurrences to the durable run ledger. It never delivers them. */
 export declare class Automations {
     #private;
@@ -9,13 +17,14 @@ export declare class Automations {
     readonly log: AutomationLog;
     constructor(store: AutomationStore, log?: AutomationLog);
     receiveEvent(input: {
-        target: AutomationTarget;
+        endpointId: string;
         headers: Record<string, string>;
         body: Buffer;
         payload: Json;
+        deliveryKey: string | null;
         source?: string;
         event?: string;
         now?: Date;
-    }): Promise<AutomationRun[]>;
+    }): Promise<EventAdmission>;
     fireDueCrons(now?: Date, maximumRuns?: number): Promise<AutomationRun[]>;
 }

package/dist/src/automations.js

@@ -1,5 +1,5 @@
 import { nextCronAt } from './schedule.js';
-import { eventReferences, matchesEvent, verifyEventSecret } from './webhook.js';
+import { eventReferences, verifyEventSecret } from './webhook.js';
 const noop = () => { };
 export class EventRejectedError extends Error {
     constructor() {
@@ -7,6 +7,12 @@ export class EventRejectedError extends Error {
         this.name = 'EventRejectedError';
     }
 }
+export class EventEndpointNotFoundError extends Error {
+    constructor() {
+        super('Webhook endpoint was not found');
+        this.name = 'EventEndpointNotFoundError';
+    }
+}
 /** Admits trigger occurrences to the durable run ledger. It never delivers them. */
 export class Automations {
     store;
@@ -17,28 +23,24 @@ export class Automations {
     }
     async receiveEvent(input) {
         assertJson(input.payload, 'Event payload');
-        const candidates = await this.store.eventTriggers(input.target);
-        const authenticated = candidates.filter((trigger) => (verifyEventSecret(trigger.secret, input.headers, input.body)));
-        if (authenticated.length === 0) {
-            this.log('event.rejected', { targetId: input.target.targetId });
+        const trigger = await this.store.eventTrigger(input.endpointId);
+        if (!trigger)
+            throw new EventEndpointNotFoundError();
+        if (!verifyEventSecret(trigger.secret, input.headers, input.body)) {
+            this.log('event.rejected', { triggerId: trigger.triggerId });
             throw new EventRejectedError();
         }
         const references = input.source && input.event
             ? { primary: { source: input.source, event: input.event } }
             : eventReferences(input.headers, input.payload);
-        let reference = references.primary;
-        let triggers = authenticated.filter((trigger) => matchesEvent(trigger, reference.source, reference.event));
-        if (triggers.length === 0 && references.fallback) {
-            reference = references.fallback;
-            triggers = authenticated.filter((trigger) => matchesEvent(trigger, reference.source, reference.event));
-        }
-        if (triggers.length === 0)
-            return [];
+        const reference = references.primary;
         const now = input.now || new Date();
         const runInput = { kind: 'event', ...reference, payload: input.payload };
-        const runs = (await Promise.all(triggers.map((trigger) => (this.store.enqueueEvent(trigger, runInput, now))))).filter((run) => run !== null);
-        this.#logPending(runs);
-        return runs;
+        const run = await this.store.enqueueEvent(trigger, runInput, now, input.deliveryKey);
+        if (!run)
+            return { run: null, ...reference };
+        this.#logPending([run]);
+        return { run, ...reference };
     }
     async fireDueCrons(now = new Date(), maximumRuns = 1_000) {
         if (!Number.isInteger(maximumRuns) || maximumRuns < 1)

package/dist/src/cli.d.ts

@@ -2,7 +2,7 @@ import type { AutomationCrud } from './contract.js';
 interface Output {
     write(chunk: string): unknown;
 }
-export declare const automationCliHelp = "Usage: amalgm-automations <resource> <action>\n\nautomations  create|list|get|update|delete\ntriggers     list | schedule <create|list|get|update|delete> | webhook <create|list|get|update|delete>\nworkflow     create|get|update|delete\nruns         list|get\n\nList filters:\n  automations list [--target-id ID] [--enabled true|false] [--limit N] [--offset N]\n  triggers schedule|webhook list AUTOMATION_ID [--limit N] [--offset N]\n  runs list AUTOMATION_ID [--status STATUS] [--limit N] [--offset N]\n";
+export declare const automationCliHelp = "Usage: amalgm-automations <resource> <action>\n\nautomations  create|list|get|update|delete\ntriggers     list | schedule <create|list|get|update|delete> | webhook <create|list|get|update|delete>\nworkflow     create|get|update|delete\nruns         run-now|list|get\n\nList filters:\n  automations list [--target-id ID] [--enabled true|false] [--limit N] [--offset N]\n  triggers schedule|webhook list AUTOMATION_ID [--limit N] [--offset N]\n  runs list AUTOMATION_ID [--status STATUS] [--limit N] [--offset N]\n";
 export declare function runAutomationCli(argv: string[], sdk: AutomationCrud, output?: {
     stdout?: Output;
     stderr?: Output;

package/dist/src/cli.js

@@ -4,7 +4,7 @@ export const automationCliHelp = `Usage: amalgm-automations <resource> <action>
 automations  create|list|get|update|delete
 triggers     list | schedule <create|list|get|update|delete> | webhook <create|list|get|update|delete>
 workflow     create|get|update|delete
-runs         list|get
+runs         run-now|list|get
 
 List filters:
   automations list [--target-id ID] [--enabled true|false] [--limit N] [--offset N]
@@ -109,11 +109,14 @@ async function workflowCommand(action, args, sdk) {
 }
 async function runsCommand(action, args, sdk) {
     const automationId = required(args, 0, 'automation id');
+    if (action === 'run-now') {
+        return sdk.runs.runNow(automationId, args[1] ? await jsonFile(args[1]) : {});
+    }
     if (action === 'list')
         return sdk.runs.list(automationId, runListOptions(args.slice(1)));
     if (action === 'get')
         return sdk.runs.get(automationId, required(args, 1, 'run id'));
-    throw new Error('Usage: runs <list|get>');
+    throw new Error('Usage: runs <run-now|list|get>');
 }
 function automationListOptions(args) {
     const options = readOptions(args, new Set(['--target-id', '--enabled', '--limit', '--offset']));

package/dist/src/client.js

@@ -34,6 +34,7 @@ export function createAutomationClient(options) {
             delete: (automationId) => request(workflowPath(automationId), 'DELETE'),
         },
         runs: {
+            runNow: (automationId, input = {}) => request(runsPath(automationId), 'POST', input),
             list: (automationId, query = {}) => request(`${runsPath(automationId)}${queryString(query)}`, 'GET'),
             get: (automationId, runId) => request(`${runsPath(automationId)}/${part(runId)}`, 'GET', undefined, true),
         },

package/dist/src/contract.d.ts

@@ -1,8 +1,8 @@
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
-import type { AutomationRun, ListRuns } from './run-contract.js';
-export type { AutomationPlan, AutomationRun, AutomationRunJournal, AutomationStepRun, AutomationStepStatus, ListRuns, RunStatus, ToolActionStep, } from './run-contract.js';
+import type { AutomationRun, ListRuns, RunAutomationNow } from './run-contract.js';
+export type { AutomationPlan, AutomationRun, AutomationRunJournal, AutomationStepRun, AutomationStepStatus, ListRuns, RunAutomationNow, RunStatus, ToolActionStep, } from './run-contract.js';
 export type AutomationScope = 'automations:read' | 'automations:write' | 'runs:read' | 'runs:execute' | '*';
 /** Identity resolved by Amalgm before the SDK is bound to a caller. */
 export interface AutomationPrincipal {
@@ -68,6 +68,8 @@ export interface WebhookTrigger extends TriggerBase {
     kind: 'webhook';
     source: string;
     event: string;
+    /** Bearer-capability URL. Treat it as a credential and rotate it if exposed. */
+    webhookUrl: string;
     secretConfigured: boolean;
 }
 export type Trigger = ScheduleTrigger | WebhookTrigger;
@@ -90,13 +92,17 @@ export interface CreateWebhookTrigger {
     id?: string;
     source?: string;
     event?: string;
-    secret: string;
+    /** Optional provider signing secret; the generated webhook URL authenticates admission. */
+    secret?: string;
     enabled?: boolean;
 }
 export interface UpdateWebhookTrigger {
     source?: string;
     event?: string;
-    secret?: string;
+    /** Set null to remove provider-signature verification. */
+    secret?: string | null;
+    /** Invalidates the existing URL and returns its replacement. */
+    rotateUrl?: boolean;
     enabled?: boolean;
 }
 export interface Workflow {
@@ -157,6 +163,7 @@ export interface AutomationCrud {
         delete(automationId: string): Promise<void>;
     };
     readonly runs: {
+        runNow(automationId: string, input?: RunAutomationNow): Promise<AutomationRun>;
         list(automationId: string, query?: ListRuns): Promise<Page<AutomationRun>>;
         get(automationId: string, runId: string): Promise<AutomationRun | null>;
     };

package/dist/src/crud/context.d.ts

@@ -1,14 +1,16 @@
 import type { AutomationPrincipal } from '../contract.js';
 import type { AutomationCrudRepository } from './repository.js';
+import type { WebhookEndpoints } from '../webhook.js';
 export interface CrudContext {
     repository: AutomationCrudRepository;
     principal: AutomationPrincipal;
     clock: () => Date;
+    webhooks: WebhookEndpoints;
     read(): void;
     write(): void;
     runsRead(): void;
     exists(automationId: string): Promise<void>;
 }
-export declare function createContext(repository: AutomationCrudRepository, principal: AutomationPrincipal, clock: () => Date): CrudContext;
+export declare function createContext(repository: AutomationCrudRepository, principal: AutomationPrincipal, clock: () => Date, webhooks: WebhookEndpoints): CrudContext;
 export declare function assertTarget(principal: AutomationPrincipal, targetId: string): void;
 export declare function resolveTarget(principal: AutomationPrincipal, targetId?: string): string;

package/dist/src/crud/context.js

@@ -1,11 +1,12 @@
 import { ForbiddenError, NotFoundError, ValidationError } from '../errors.js';
 import { id, requiredText } from '../validation.js';
-export function createContext(repository, principal, clock) {
+export function createContext(repository, principal, clock, webhooks) {
     assertPrincipal(principal);
     return {
         repository,
         principal,
         clock,
+        webhooks,
         read: () => assertScope(principal, 'automations:read'),
         write: () => assertScope(principal, 'automations:write'),
         runsRead: () => assertScope(principal, 'runs:read'),

package/dist/src/crud/repository.d.ts

@@ -1,4 +1,4 @@
-import type { Automation, AutomationRun, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, ListAutomations, ListRuns, Page, PageQuery, ScheduleTrigger, Trigger, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow } from '../contract.js';
+import type { Automation, AutomationRun, CreateAutomation, CreateScheduleTrigger, CreateWebhookTrigger, CreateWorkflow, Json, ListAutomations, ListRuns, Page, PageQuery, ScheduleTrigger, UpdateAutomation, UpdateScheduleTrigger, UpdateWebhookTrigger, UpdateWorkflow, WebhookTrigger, Workflow } from '../contract.js';
 export type StoredScheduleCreate = Omit<Required<CreateScheduleTrigger>, 'maxOccurrences'> & {
     maxOccurrences: number | null;
     nextRunAt: string;
@@ -7,6 +7,16 @@ export type StoredScheduleUpdate = UpdateScheduleTrigger & {
     nextRunAt?: string;
     remainingOccurrences?: number | null;
 };
+export type WebhookTriggerRecord = Omit<WebhookTrigger, 'webhookUrl'> & {
+    endpointId: string;
+};
+export type StoredWebhookCreate = Omit<Required<CreateWebhookTrigger>, 'secret'> & {
+    secret: string | null;
+    endpointId: string;
+};
+export type StoredWebhookUpdate = Omit<UpdateWebhookTrigger, 'rotateUrl'> & {
+    endpointId?: string;
+};
 export type NormalizedListAutomations = Required<PageQuery> & Omit<ListAutomations, keyof PageQuery>;
 export type NormalizedListRuns = Required<PageQuery> & Omit<ListRuns, keyof PageQuery>;
 export interface AutomationCrudRepository {
@@ -20,16 +30,17 @@ export interface AutomationCrudRepository {
     getScheduleTrigger(userId: string, automationId: string, triggerId: string): Promise<ScheduleTrigger | null>;
     updateScheduleTrigger(userId: string, automationId: string, triggerId: string, patch: StoredScheduleUpdate): Promise<ScheduleTrigger | null>;
     deleteScheduleTrigger(userId: string, automationId: string, triggerId: string): Promise<boolean>;
-    createWebhookTrigger(userId: string, automationId: string, input: Required<CreateWebhookTrigger>): Promise<WebhookTrigger>;
-    listWebhookTriggers(userId: string, automationId: string, query: Required<PageQuery>): Promise<Page<WebhookTrigger>>;
-    getWebhookTrigger(userId: string, automationId: string, triggerId: string): Promise<WebhookTrigger | null>;
-    updateWebhookTrigger(userId: string, automationId: string, triggerId: string, patch: UpdateWebhookTrigger): Promise<WebhookTrigger | null>;
+    createWebhookTrigger(userId: string, automationId: string, input: StoredWebhookCreate): Promise<WebhookTriggerRecord>;
+    listWebhookTriggers(userId: string, automationId: string, query: Required<PageQuery>): Promise<Page<WebhookTriggerRecord>>;
+    getWebhookTrigger(userId: string, automationId: string, triggerId: string): Promise<WebhookTriggerRecord | null>;
+    updateWebhookTrigger(userId: string, automationId: string, triggerId: string, patch: StoredWebhookUpdate): Promise<WebhookTriggerRecord | null>;
     deleteWebhookTrigger(userId: string, automationId: string, triggerId: string): Promise<boolean>;
-    listTriggers(userId: string, automationId: string): Promise<Trigger[]>;
+    listTriggers(userId: string, automationId: string): Promise<Array<ScheduleTrigger | WebhookTriggerRecord>>;
     createWorkflow(userId: string, automationId: string, input: Required<CreateWorkflow>): Promise<Workflow>;
     getWorkflow(userId: string, automationId: string): Promise<Workflow | null>;
     updateWorkflow(userId: string, automationId: string, patch: UpdateWorkflow): Promise<Workflow | null>;
     deleteWorkflow(userId: string, automationId: string): Promise<boolean>;
     listRuns(userId: string, automationId: string, query: NormalizedListRuns): Promise<Page<AutomationRun>>;
     getRun(userId: string, automationId: string, runId: string): Promise<AutomationRun | null>;
+    runAutomationNow(userId: string, automationId: string, input: Json, idempotencyKey: string | null, now: Date): Promise<AutomationRun | null>;
 }

package/dist/src/crud/runs.d.ts

@@ -1,3 +1,3 @@
 import type { AutomationCrud } from '../contract.js';
-import type { CrudContext } from './context.js';
+import { type CrudContext } from './context.js';
 export declare function runOperations(context: CrudContext): AutomationCrud['runs'];

package/dist/src/crud/runs.js

@@ -1,8 +1,31 @@
-import { parseListRuns } from '../schema.js';
+import { AutomationError, NotFoundError, ValidationError } from '../errors.js';
+import { compiledAutomationPlan } from '../plan.js';
+import { parseListRuns, parseRunAutomationNow } from '../schema.js';
 import { id, page } from '../validation.js';
+import { assertTarget } from './context.js';
 export function runOperations(context) {
     const { principal, repository } = context;
     return {
+        runNow: async (automationId, input = {}) => {
+            context.write();
+            const automationKey = id(automationId, 'Automation id');
+            const parsed = parseRunAutomationNow(input);
+            const automation = await repository.getAutomation(principal.userId, automationKey);
+            if (!automation)
+                throw new NotFoundError('Automation');
+            assertTarget(principal, automation.targetId);
+            if (!automation.enabled)
+                throw new ValidationError('Automation must be enabled before it can run');
+            const workflow = await repository.getWorkflow(principal.userId, automationKey);
+            if (!workflow?.compiled)
+                throw new ValidationError('Automation needs a compiled workflow before it can run');
+            compiledAutomationPlan(workflow.compiled);
+            const run = await repository.runAutomationNow(principal.userId, automationKey, { kind: 'manual', payload: parsed.input ?? {} }, parsed.idempotencyKey ?? null, context.clock());
+            if (!run) {
+                throw new AutomationError('conflict', 'Automation changed before the run was admitted; inspect it and try again');
+            }
+            return run;
+        },
         list: async (automationId, query = {}) => {
             context.runsRead();
             const parsed = parseListRuns(query);