@sguild/external-actions

External Actions Queue producer SDK for Sguild domains, per ADR-0011 and the external-actions queue contract (coordination/contracts/external-actions/README.md).

The External Actions Queue is the outbound-side mirror of the dispatcher: one action goes to one destination with retry, response correlation, and dead-letter. This package is the producer-facing surface of that queue. The queue runner, the retry and dead-letter machinery, and the operator and reconciliation routes are Platform-side and are not part of this package.

What this package provides

• enqueueExternalAction(input) — enqueue one outbound action. Pass client: tx from inside prisma.$transaction(...) so the action row and the producer-side row write land atomically (the producer-transactional-guarantee seam).
• cancelExternalAction(input) — producer-driven cancellation of an action that has not yet executed.
• registerExternalActionHandler(handler) — register a per-(provider, actionKind) handler implementing the ExternalActionHandler interface.
• The handler and payload types (ExternalActionHandler, HandlerContext, HandlerResult, and the input and DTO types).

Setup

The SDK does not import any domain's generated Prisma client. Inject yours once at process startup, the same way the dispatcher SDK is configured:

import { configureExternalActions } from "@sguild/external-actions";
import { prisma } from "./lib/db/prisma";

configureExternalActions({ prismaClient: prisma });

Enqueues that pass a per-call client (an interactive-transaction tx) do not need the injected client; the injected client is the default for enqueues and cancels with no caller-supplied transaction.

Enqueue

import { enqueueExternalAction } from "@sguild/external-actions";

await prisma.$transaction(async (tx) => {
  await tx.surveySend.create({ data: { ... } });
  await enqueueExternalAction({
    producer: "delivery",
    provider: "quo",
    actionKind: "quo.sms.send",
    payload: { ... },
    client: tx,
  });
});

Distribution

This package ships built (dist/) and versioned independently of the external-actions queue contract version, the same way @sguild/dispatcher is versioned independently of the event-envelope contract. Producer domains add it as a dependency rather than vendoring a copy of the source.

Related

• ADR-0011 (coordination/adrs/ADR-0011-external-actions-at-platform.md)
• External Actions Queue contract (coordination/contracts/external-actions/README.md)
• @sguild/dispatcher, the inbound-side sibling SDK (ADR-0009)