@netscript/plugin-triggers

NetScript plugin for trigger ingress, scheduling, file watching, and the trigger runtime APIs. This page is written against the package's public surface reported by deno doc. For the full index of packages and plugins return to the reference overview.

The plugin's root entrypoint (@netscript/plugin-triggers) exposes the public plugin manifest surface — the manifest value and its metadata constants. Shared manifest inspection is provided by inspectPlugin from @netscript/plugin. The handler-first authoring DSL (defineWebhook, defineScheduledTrigger, defineFileWatch, enqueueJob) and the runtime ports live in the sibling @netscript/plugin-triggers-core package, which has its own canonical reference page.

Additional integration entrypoints are published as sub-path exports: ./public, ./plugin, ./runtime, ./scaffolding, ./aspire, ./cli, ./services, ./streams, and ./streams/server. Their reference detail is documented against their own deno doc surface.

Plugin manifest

Manifest constants

Manifest types

Sub-path exports

The following entrypoints are published alongside the root export.

Scaffolding (./scaffolding)

Aspire (./aspire)

Core package

The separately published @netscript/plugin-triggers-core page is canonical for the handler-first DSL, ingress and processor runtimes, ports, configuration, and testing exports. This page stays focused on the deployable plugin's manifest and integration entrypoints. The testing example below uses core APIs intentionally; exhaustive core entrypoint and symbol tables live only on its reference page.

Testing and Verification

Verifying trigger routing, security verification, manual replays, and real-time execution monitoring can be performed using in-memory doubles without launching live HTTP hosts or databases.

import { assertEquals, assertExists } from "@std/assert";
import {
  defineWebhook,
  type TriggerEventSubscriptionMessage,
} from "@netscript/plugin-triggers-core";
import { MemoryTriggerEventStore, InlineTriggerProcessor } from "@netscript/plugin-triggers-core/testing";
import { HmacSha256WebhookVerifier } from "@netscript/plugin-triggers-core/adapters";
import {
  createTriggerIngress,
  createWebhookTestDelivery,
  createManualDispatcher,
  createEventSubscription,
} from "@netscript/plugin-triggers-core";

Deno.test("Trigger operator, manual dispatch, test delivery, and lifecycle subscriptions", async () => {
  // Define a webhook trigger spec
  const webhookDef = defineWebhook(() => Promise.resolve([]), {
    id: "orders-webhook",
    path: "/orders",
    verifier: "hmac-sha256",
    secretEnv: "ORDERS_SECRET",
  });

  const eventStore = new MemoryTriggerEventStore();
  const processor = new InlineTriggerProcessor();
  const verifier = new HmacSha256WebhookVerifier({ signatureHeader: "x-hub-signature-256" });

  // 1. Create a trigger ingress and webhook test delivery
  const ingress = createTriggerIngress({
    definitions: [webhookDef],
    eventStore,
    processor,
    verifier,
    resolveSecret: () => "webhook-secret-key",
  });

  const delivery = createWebhookTestDelivery({
    ingress,
    resolveSecret: () => "webhook-secret-key",
  });

  // Signed webhook test delivery
  const deliveryResponse = await delivery.deliver(webhookDef, {
    payload: { orderId: "ord_123", amount: 99.99 },
    idempotencyKey: "idem-webhook-test",
  });

  assertEquals(deliveryResponse.accepted, true);
  assertEquals(deliveryResponse.status, "pending");

  // 2. Manual Replay / Fire dispatcher
  const dispatcher = createManualDispatcher({
    eventStore,
    processor,
  });

  const replayResponse = await dispatcher.fire(webhookDef, {
    payload: { orderId: "ord_123", amount: 99.99 },
    reason: "Manual event replay due to consumer downtime",
    firedBy: "admin-operator",
  });

  assertEquals(replayResponse.accepted, true);
  assertExists(replayResponse.eventId);

  // 3. Lifecycle event observation via createEventSubscription
  const subscriptionHub = createEventSubscription();
  const observedEvents: TriggerEventSubscriptionMessage[] = [];
  const abortController = new AbortController();

  const subscriptionPromise = (async () => {
    for await (const msg of subscriptionHub.subscribe({}, { signal: abortController.signal })) {
      observedEvents.push(msg);
    }
  })();

  const triggerEvent = await eventStore.load(replayResponse.eventId);
  if (triggerEvent) {
    await subscriptionHub.publish({
      type: "trigger:accepted",
      timestamp: new Date().toISOString(),
      event: triggerEvent,
    });
  }

  abortController.abort();
  await subscriptionPromise;

  assertEquals(observedEvents.length, 1);
  assertEquals(observedEvents[0].type, "trigger:accepted");
  assertEquals(observedEvents[0].event.triggerId, webhookDef.id);
});

Back to the reference overview.