@shipfox/api-triggers 2.0.0

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+$ shipfox-swc
+Successfully compiled: 56 files with swc (93.82ms)

package/.turbo/turbo-type$colon$emit.log

@@ -0,0 +1 @@
+$ shipfox-tsc-emit

package/.turbo/turbo-type.log

@@ -0,0 +1 @@
+$ shipfox-tsc-check

package/CHANGELOG.md

@@ -0,0 +1,224 @@
+# @shipfox/api-triggers
+
+## 2.0.0
+
+### Minor Changes
+
+- 1b0d344: Publishes the complete API runtime closure with packed-consumer-safe internal imports and records its exact package set in application releases.
+
+### Patch Changes
+
+- Updated dependencies [0cd6dd4]
+- Updated dependencies [a68458a]
+- Updated dependencies [6eba800]
+- Updated dependencies [1b0d344]
+- Updated dependencies [521e006]
+  - @shipfox/node-module@0.2.0
+  - @shipfox/node-temporal@0.2.0
+  - @shipfox/api-auth-context@2.0.0
+  - @shipfox/api-definitions-dto@2.0.0
+  - @shipfox/api-integration-core-dto@2.0.0
+  - @shipfox/api-projects@2.0.0
+  - @shipfox/api-triggers-dto@2.0.0
+  - @shipfox/api-workflows@2.0.0
+  - @shipfox/api-workflows-dto@2.0.0
+  - @shipfox/config@1.2.1
+  - @shipfox/expression@1.1.1
+  - @shipfox/node-drizzle@0.2.1
+  - @shipfox/node-fastify@0.2.1
+  - @shipfox/node-opentelemetry@0.5.0
+  - @shipfox/node-outbox@0.2.1
+  - @shipfox/node-postgres@0.4.1
+  - @shipfox/workflow-document@2.0.1
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [705dd43]
+  - @shipfox/node-outbox@0.2.0
+  - @shipfox/api-projects@0.1.2
+  - @shipfox/api-workflows@0.1.2
+  - @shipfox/node-module@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [ec75cd5]
+- Updated dependencies [6a1fb54]
+  - @shipfox/node-drizzle@0.2.0
+  - @shipfox/node-postgres@0.4.0
+  - @shipfox/api-projects@0.1.1
+  - @shipfox/api-workflows@0.1.1
+  - @shipfox/node-module@0.1.1
+  - @shipfox/node-outbox@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- a460020: Add trigger event detail decisions with stored subscription names, run links, and payload inspection.
+- 5ec8367: Adds trigger event inspection endpoints with matching DTO schemas for listing received events and reading event decisions.
+
+### Patch Changes
+
+- ae7a63c: Adds daily dispatched outbox row retention with bounded cleanup batches and retention indexes on module outbox tables.
+- 555299c: Add the append-only `triggers_received_events` and `triggers_decisions` tables that back the trigger event history. DB layer only: Drizzle schema, inferred types, and row→domain mappers, folded into the triggers module's baseline migration. No write or read path is wired yet.
+- 9a4807d: Add the hourly Temporal prune cron and `TRIGGER_EVENT_RETENTION_DAYS` config var that bound trigger event history growth. The cron deletes `triggers_received_events` older than the retention window (default 30 days); `triggers_decisions` go with them via FK cascade.
+- e5d2f13: Add the workspace **Events** page in Settings: a filterable, cursor-paginated table of
+  trigger events (status dot, source/event, routing summary, delivery id, received time)
+  mounted at `/workspaces/$wid/settings/events` and wired into the settings sub-nav. Filters
+  (date range, source, event, outcome) live in the URL via `validateSearch`, so a filtered
+  view is shareable. Source and event filters are populated by a new
+  `GET /trigger-events/facets` endpoint that returns each workspace's distinct source/event
+  values with counts (top 50, backed by `(workspace_id, source)` / `(workspace_id, event)`
+  indexes); the list still renders if facets fail to load.
+- a982f20: Stop a permanently-broken trigger subscription from starving its siblings or wedging the outbox. Integration dispatch now attempts every matched subscription and classifies each `runWorkflow` failure: a permanent error (deleted definition or project mismatch) is recorded and skipped, while a transient one re-throws so the outbox replays the event and converges. The event reaches a terminal outcome once no transient error remains (`routed` when any run was created, otherwise the new `errored` outcome), with a guarded write that never records `errored` over an event that already produced a run. The manual-fire path records the same terminal outcome, and `@shipfox/api-workflows` exports an `isPermanentRunWorkflowError` classifier. The trigger-events read API (`triggerEventOutcomeSchema`) accepts the new `errored` outcome for serialization and filtering.
+- 3dcd751: Adds listener filter snapshots to job activation events and persists them on listener subscriptions.
+- 6077301: Adds shared timestamp/id keyset pagination helpers and migrates workflow run and trigger event lists onto them.
+- 3bea87f: Adds a typed `subscriberFactory` that binds each outbox event name to its payload type at construction, so subscriber handlers receive a typed `(payload, event)` and the per-handler `event.payload as X` casts are gone; a private brand makes the factory the only way to build a module subscriber.
+- b74f635: Adds workflow run interpolation context resolution while preserving authored step configuration for reruns and diagnostics.
+- e192d86: Adds the cron firing engine: a once-per-minute tick fans out bounded drain activities that claim due schedules (FOR UPDATE SKIP LOCKED), advance their next fire time, and fire the workflow deduplicated and crash-safe, recorded in trigger history with a `cron` origin and surfaced through cron fire and backlog metrics.
+- 638ac4d: Adds cron trigger schedule persistence and deterministic next-fire computation for resolved workflow definitions.
+- Updated dependencies [eb40964]
+- Updated dependencies [7bc7498]
+- Updated dependencies [5c18360]
+- Updated dependencies [2c156d2]
+- Updated dependencies [26fea4b]
+- Updated dependencies [0cf66c4]
+- Updated dependencies [34ba284]
+- Updated dependencies [a56748d]
+- Updated dependencies [8f51daf]
+- Updated dependencies [5707d6d]
+- Updated dependencies [e689abf]
+- Updated dependencies [59ba68b]
+- Updated dependencies [7a9943d]
+- Updated dependencies [ce3e5ca]
+- Updated dependencies [f788565]
+- Updated dependencies [b9c3f32]
+- Updated dependencies [c17dd6e]
+- Updated dependencies [a81b68c]
+- Updated dependencies [115655e]
+- Updated dependencies [c0a883c]
+- Updated dependencies [72ce351]
+- Updated dependencies [cdf8989]
+- Updated dependencies [e47f8da]
+- Updated dependencies [736249b]
+- Updated dependencies [2bc5595]
+- Updated dependencies [b1f57d1]
+- Updated dependencies [1127ba2]
+- Updated dependencies [36f871d]
+- Updated dependencies [e7b01dd]
+- Updated dependencies [d546b88]
+- Updated dependencies [58c05ed]
+- Updated dependencies [ce062a9]
+- Updated dependencies [9086e65]
+- Updated dependencies [7b175f5]
+- Updated dependencies [7ca4c65]
+- Updated dependencies [e9056c7]
+- Updated dependencies [8e9c6cb]
+- Updated dependencies [97162dd]
+- Updated dependencies [b694b09]
+- Updated dependencies [c47be09]
+- Updated dependencies [f9f059e]
+- Updated dependencies [940696a]
+- Updated dependencies [f3614ae]
+- Updated dependencies [f98c2be]
+- Updated dependencies [e9396c9]
+- Updated dependencies [ae7a63c]
+- Updated dependencies [5729548]
+- Updated dependencies [f92122b]
+- Updated dependencies [e250c4c]
+- Updated dependencies [b525dcd]
+- Updated dependencies [f8f339a]
+- Updated dependencies [857fd73]
+- Updated dependencies [e5d2f13]
+- Updated dependencies [a982f20]
+- Updated dependencies [7fa8f0b]
+- Updated dependencies [998eba3]
+- Updated dependencies [5327934]
+- Updated dependencies [314e84e]
+- Updated dependencies [a460020]
+- Updated dependencies [3afb7e3]
+- Updated dependencies [139e3be]
+- Updated dependencies [eb7d5e8]
+- Updated dependencies [247cbd6]
+- Updated dependencies [5d53ed4]
+- Updated dependencies [c652a68]
+- Updated dependencies [121b42e]
+- Updated dependencies [75520ff]
+- Updated dependencies [e87731a]
+- Updated dependencies [795f440]
+- Updated dependencies [3dcd751]
+- Updated dependencies [c0a883c]
+- Updated dependencies [362b3eb]
+- Updated dependencies [b8e49ff]
+- Updated dependencies [d6d4862]
+- Updated dependencies [c0a883c]
+- Updated dependencies [6077301]
+- Updated dependencies [f85b223]
+- Updated dependencies [9c1c947]
+- Updated dependencies [f0afdf8]
+- Updated dependencies [9d3b43a]
+- Updated dependencies [d635979]
+- Updated dependencies [3bea87f]
+- Updated dependencies [82d22e4]
+- Updated dependencies [d69b164]
+- Updated dependencies [69d02e5]
+- Updated dependencies [2fb3e87]
+- Updated dependencies [01be723]
+- Updated dependencies [f63c6b0]
+- Updated dependencies [e0fee57]
+- Updated dependencies [b74f635]
+- Updated dependencies [fa67aa3]
+- Updated dependencies [e192d86]
+- Updated dependencies [9a5aac4]
+- Updated dependencies [30d1c82]
+- Updated dependencies [5ec8367]
+- Updated dependencies [ef1e917]
+- Updated dependencies [51eb38a]
+- Updated dependencies [61de795]
+- Updated dependencies [c6eb2ee]
+- Updated dependencies [e2fbef8]
+- Updated dependencies [8ecba0f]
+- Updated dependencies [f9153e8]
+- Updated dependencies [27770eb]
+- Updated dependencies [2933c33]
+- Updated dependencies [2ad300c]
+- Updated dependencies [a314b05]
+- Updated dependencies [43fd0c1]
+- Updated dependencies [950ebef]
+- Updated dependencies [6181819]
+- Updated dependencies [a8905ed]
+- Updated dependencies [1ea2f6a]
+- Updated dependencies [e699508]
+- Updated dependencies [ad6056b]
+- Updated dependencies [282e66a]
+- Updated dependencies [0dd23a7]
+- Updated dependencies [9c149d1]
+- Updated dependencies [f88aac9]
+- Updated dependencies [e1d4972]
+- Updated dependencies [f9bf446]
+- Updated dependencies [a856155]
+- Updated dependencies [78527ce]
+- Updated dependencies [b8919da]
+- Updated dependencies [8ecc121]
+- Updated dependencies [d7b9596]
+  - @shipfox/workflow-document@2.0.0
+  - @shipfox/api-workflows@0.1.0
+  - @shipfox/api-workflows-dto@0.1.0
+  - @shipfox/expression@1.1.0
+  - @shipfox/node-fastify@0.2.0
+  - @shipfox/node-drizzle@0.1.0
+  - @shipfox/api-definitions-dto@0.0.1
+  - @shipfox/api-auth-context@0.1.0
+  - @shipfox/api-integration-core-dto@0.1.0
+  - @shipfox/api-projects@0.1.0
+  - @shipfox/node-opentelemetry@0.4.2
+  - @shipfox/node-postgres@0.3.2
+  - @shipfox/node-temporal@0.1.1
+  - @shipfox/node-module@0.1.0
+  - @shipfox/node-outbox@0.1.0
+  - @shipfox/api-triggers-dto@0.1.0
+  - @shipfox/config@1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipfox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,300 @@
+# Shipfox API Triggers
+
+Shipfox API Triggers decides when a workflow run starts. It projects the
+`triggers` map from each workflow YAML into an indexed subscription table,
+matches incoming integration events against those subscriptions, and starts
+a workflow run for every match. It also exposes HTTP routes that fire manual
+runs and inspect received trigger events.
+
+## Example
+
+Register the module with the API module runner:
+
+```ts
+import {triggersModule} from '@shipfox/api-triggers';
+import {createApp, listen} from '@shipfox/node-fastify';
+import {initializeModules, startModuleWorkers} from '@shipfox/node-module';
+
+const {auth, routes, workers} = await initializeModules({
+  modules: [triggersModule /* and other modules */],
+});
+
+await createApp({auth, routes});
+await startModuleWorkers({workers});
+await listen();
+```
+
+This adds:
+
+- triggers database migrations from `libs/api/triggers/drizzle`
+- the `POST /workflow-definitions/:definitionId/fire-manual` route
+- the `GET /trigger-events`, `GET /trigger-events/facets`, and `GET /trigger-events/:id` inspection routes
+- subscribers for `DEFINITION_RESOLVED`, `DEFINITION_DELETED`, and
+  `INTEGRATION_EVENT_RECEIVED`
+- the `triggers` outbox publisher
+- the hourly `triggers-prune-trigger-events` Temporal cron, which deletes old
+  rows from `triggers_received_events`
+
+A workflow YAML opts into triggers like this:
+
+```yaml
+triggers:
+  on_demand:
+    source: manual
+  on_push:
+    source: github_acme
+    event: push
+    on: main
+```
+
+Each source is an integration connection slug. Each map key is the trigger's `name`. A workflow may declare any number of
+integration triggers and at most one `source: manual` trigger; the manual
+invariant is enforced at parse time so the fire route stays unambiguous.
+The `event` field is optional when `source: manual` and defaults to
+`fire`.
+
+Integration triggers may include a CEL `filter` predicate. Dispatch evaluates
+the predicate for every subscription that matches `(workspace_id, source,
+event)` with the context `{event: payload, trigger: {source, event}}`. A
+missing filter matches; `true` creates a run; `false` or a non-boolean result
+skips the subscription and can leave the event `discarded`; an evaluation
+failure records a `filter-error` decision and fails closed without creating a
+run.
+
+Webhook triggers use the webhook connection slug as `source` and the fixed
+event name `received`. A delivery to `POST /webhook/:connectionId` publishes
+an `INTEGRATION_EVENT_RECEIVED` envelope with `provider: webhook`,
+`source: <connection.slug>`, `event: received`, and payload
+`{method, headers, query, body}`. Trigger dispatch matches only on
+`(workspace_id, source, event)`, so a workflow that listens to a webhook uses
+the slug plus `event: received`:
+
+```yaml
+triggers:
+  on_stripe:
+    source: stripe_prod
+    event: received
+```
+
+Workflow interpolation exposes the webhook envelope as `event`, so steps can
+read values such as `${{ event.body.payment_id }}` and
+`${{ event.headers["x-stripe-signature"] }}`. Header/body-derived event
+subtypes are not part of this contract.
+
+GitHub triggers use the raw GitHub webhook resource name, plus the payload
+`action` when one is present. For example, a pull request open event is
+`pull_request.opened`, an issue close event is `issues.closed`, and a
+release publish event is `release.published`. Events without an action use
+the bare resource name, such as `push` or `fork`. Common GitHub events are:
+`push`, `pull_request.opened`, `pull_request.closed`, `issues.opened`,
+`issues.closed`, `issue_comment.created`, `release.published`,
+`workflow_run.completed`, `installation.created`, and
+`installation_repositories.added`. GitHub only sends events that the GitHub
+App is subscribed to in its Permissions & events settings.
+
+## Setup
+
+Install the package from the registry:
+
+```sh
+pnpm add @shipfox/api-triggers
+```
+
+The matching HTTP contract lives in
+[`@shipfox/api-triggers-dto`](../triggers-dto). Import Zod schemas and DTO
+types from there when you call the route from the client.
+
+The package reads `TRIGGER_EVENT_RETENTION_DAYS` to decide how many days of
+received trigger events to keep before the maintenance cron deletes them.
+It also depends on the API database connection from `@shipfox/node-postgres`.
+
+## Routes
+
+The routes are mounted by the host app under the `/workflow-definitions` and
+`/trigger-events` prefixes.
+
+| Method | Path | Auth | Result |
+| --- | --- | --- | --- |
+| `POST` | `/workflow-definitions/:definitionId/fire-manual` | bearer token | Fires the workflow's manual trigger and returns the new `workflow_run_id`. Optional `inputs` in the body are forwarded to the run. |
+| `GET` | `/trigger-events?workspace_id=:workspaceId` | bearer token | Lists received trigger events for a workspace, newest first. Supports source, event, outcome, received-at window, limit, and cursor filters. |
+| `GET` | `/trigger-events/facets?workspace_id=:workspaceId` | bearer token | Returns the workspace's distinct `source` and `event` filter values with counts (top 50 each, by count). Backs the Events page filter dropdowns. |
+| `GET` | `/trigger-events/:id` | bearer token | Returns one received trigger event with its full payload and routing decisions. Cross-workspace ids return `404`. |
+
+The manual route is keyed by workflow definition id, not subscription id. The
+server resolves the manual subscription for the workflow internally; the
+"at most one manual trigger per workflow" invariant from the parser keeps
+that lookup unambiguous. Integration sources (github, etc.) fire through
+the event bus and have no HTTP entry point.
+
+## Vocabulary
+
+Three words, used the same way at every layer.
+
+| Word | Meaning | Examples |
+| --- | --- | --- |
+| **source** | Where the trigger came from. | `github`, `gitlab`, `sentry`, `manual`, `cron` |
+| **event** | The specific thing that happened, scoped to a source. | `push`, `issue_comment`, `alert_triggered`, `fire`, `tick` |
+| **payload** | The data carried by the event, set by the producing integration. Triggers passes it through opaquely. | GitHub's raw webhook JSON for `(github, push)` |
+
+The `name` field on a subscription is the YAML map key (for example
+`on_push`). It identifies the trigger inside a workflow definition and is
+unique per `(workflow_definition_id, name)`.
+
+### Words we do not use
+
+- `provider` — reserved for the integration module's identity
+  (`integrations_connections.provider`). Trigger code says `source`.
+- `eventType` / `type` — replaced by `event`. The bare word `type` would
+  collide with TypeScript discriminators and with the `IntegrationProvider`
+  capability `type` field.
+- `triggerContext` — the runtime payload on a run is called
+  `triggerPayload`.
+- `kind` — every trigger is identified by `(source, event)`. There is no
+  separate axis.
+
+## Architecture
+
+Triggers flow through three layers. The YAML map is the source of truth,
+the subscription table is the queryable projection, and the workflow run
+table is the immutable history.
+
+```
+                ┌─────────────────────────────────────────────────────┐
+                │  workflow_definitions.definition (JSONB)            │
+                │  triggers: {on_push: {source, event, ...}}          │
+                └──────────────────────────┬──────────────────────────┘
+                                           │
+                                           │  DEFINITION_RESOLVED
+                                           │  / DEFINITION_DELETED
+                                           ▼
+                ┌─────────────────────────────────────────────────────┐
+                │  triggers_subscriptions                             │
+                │  (workspace_id, project_id,                         │
+                │   workflow_definition_id, name,                     │
+                │   source, event, config)                            │
+                └──────────────────────────┬──────────────────────────┘
+                                           │
+INTEGRATION_EVENT_RECEIVED → match on (workspace, source, event)
+or POST /workflow-definitions/:definitionId/fire-manual → look up manual subscription
+                                           │
+                                           ▼
+                ┌─────────────────────────────────────────────────────┐
+                │  workflow_runs                                      │
+                │  trigger_source, trigger_event (indexed text)       │
+                │  trigger_payload (jsonb)                            │
+                └─────────────────────────────────────────────────────┘
+```
+
+### Layer 1 — workflow definition (source of truth)
+
+The YAML `triggers` map lives inside `workflow_definitions.definition`
+(JSONB owned by the definitions module). That is the only place trigger
+declarations live in raw form.
+
+### Layer 2 — projection (queryable)
+
+`triggers_subscriptions` is rebuilt from `DEFINITION_RESOLVED` events,
+which carry the parsed `triggers` map. The triggers module never reads the
+definitions table — the event is the contract.
+
+Cron triggers also project into `triggers_cron_schedules`, keyed by
+`subscription_id`. That table stores the resolved cron expression, timezone,
+next fire time, and last fire time used by the cron firing engine.
+
+Indexes:
+
+- `(workflow_definition_id, name)` — unique. One row per YAML trigger.
+- `(workspace_id, source, event)` — the hot path for matching incoming
+  integration events at workspace scope.
+- `(workflow_definition_id)` — used to clean up the projection on
+  `DEFINITION_DELETED`.
+- `triggers_cron_schedules.next_fire_at` — used to drain due cron schedules
+  in next-fire order.
+
+### Layer 3 — run history (immutable)
+
+`workflow_runs.trigger_source` and `trigger_event` are indexed text
+columns. `trigger_payload` is a JSONB column typed by `TriggerPayload`:
+`manual`/`cron` carry their own typed shapes, while integration events use
+a generic `{source, event, deliveryId, data}` shape that forwards the raw
+event payload as `data`. The `triggerSource` value on a row always equals
+`triggerPayload.source`. The duplication is deliberate: the indexed column
+is for filtering, the payload is for inspection.
+
+## Events
+
+| Event | Published by | Consumed by | Purpose |
+| --- | --- | --- | --- |
+| `INTEGRATION_EVENT_RECEIVED` | `integration/*` | triggers, projects | An integration received a webhook and validated it. The payload is the integration's domain event. |
+| `DEFINITION_RESOLVED` | definitions | triggers | A workflow definition was created or updated. The payload includes the parsed `triggers` map. |
+| `DEFINITION_DELETED` | definitions | triggers | A workflow definition was soft-deleted. Subscription rows are removed. |
+
+## API
+
+The package exports the module entry point:
+
+```ts
+import {triggersModule} from '@shipfox/api-triggers';
+```
+
+It also exports lower-level pieces for tests and advanced wiring:
+
+- `fireManualSubscription()`: core function used by the route. Throws
+  `TriggerSubscriptionNotFoundError`,
+  `TriggerSubscriptionNotManualError`, or
+  `TriggerWorkspaceMismatchError`.
+- `ManualTriggerNotFoundError`: thrown by the route handler when the
+  caller's workspace cannot reach the workflow, or the workflow declares
+  no manual trigger. Surfaced as `404 manual-trigger-not-found`.
+- `findMatchingSubscriptions()`: hot-path lookup by
+  `(workspace_id, source, event)`.
+- `getManualSubscriptionByDefinitionId()`: resolves the single manual
+  subscription for a workflow definition (or `undefined` if none).
+- `getTriggerSubscriptionById()` and
+  `listSubscriptionsByWorkflowDefinitionIds()`: read helpers.
+- `db`, `migrationsPath`, and `triggersOutbox`: the Drizzle handle,
+  migration path, and outbox table.
+- Entity type: `TriggerSubscription`.
+
+## Adding a new source
+
+To wire a new integration source (for example GitLab):
+
+1. Add a payload type for each supported event to
+   `@shipfox/api-integration-core-dto` (for example `GitlabPushPayload`).
+2. In the new `integration/<source>` package, receive webhooks and publish
+   `INTEGRATION_EVENT_RECEIVED` with `source: '<name>'`,
+   `event: '<type>'`, and the payload.
+
+That is the whole list. The triggers subscriber is source-agnostic: it
+matches subscriptions on `(workspace, source, event)` and forwards the raw
+payload through the generic `TriggerPayload` shape, so no change to the
+triggers module, the projection schema, the run table, or `TriggerPayload`
+is needed for a new source. Author workflows that subscribe to the new
+`(source, event)` and narrow `triggerPayload.data` themselves.
+
+For Sentry's supported `(source, event)` values, see
+[`@shipfox/api-integration-sentry`](../integration/sentry).
+
+## Development
+
+Run checks for this package:
+
+```sh
+turbo check --filter=@shipfox/api-triggers
+turbo type --filter=@shipfox/api-triggers
+turbo test --filter=@shipfox/api-triggers
+```
+
+Tests use Vitest and a real PostgreSQL database. Start local services
+before running the test suite:
+
+```sh
+docker compose up -d
+```
+
+The test environment uses the `api_test` database, set in `test/env.ts`.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export declare const config: Readonly<{
+    TRIGGER_EVENT_RETENTION_DAYS: number;
+    TRIGGER_CRON_JITTER_WINDOW_SECONDS: number;
+    TRIGGER_CRON_FANOUT: number;
+    TRIGGER_CRON_CLAIM_BATCH: number;
+} & import("@shipfox/config").CleanedEnvAccessors>;
+export declare function assertRetentionDaysWithinBounds(days: number): void;
+export declare function assertCronConfigWithinBounds(jitterWindowSeconds: number): void;
+export declare function assertCronThroughputWithinBounds(fanout: number, claimBatch: number): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,MAAM;;;;;kDAiBjB,CAAC;AAEH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMlE;AAID,wBAAgB,4BAA4B,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAM9E;AAID,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CASzF"}

package/dist/config.js

@@ -0,0 +1,42 @@
+import { createConfig, num } from '@shipfox/config';
+export const config = createConfig({
+    TRIGGER_EVENT_RETENTION_DAYS: num({
+        desc: 'How many days a recorded trigger event (and its decisions) is kept before the hourly prune cron deletes it. Must be at least 1; a smaller value moves the cutoff to now or the future and would delete freshly recorded events. Defaults to 30.',
+        default: 30
+    }),
+    TRIGGER_CRON_JITTER_WINDOW_SECONDS: num({
+        desc: 'Maximum number of seconds added as deterministic jitter to a cron trigger fire time. Use 0 to disable jitter. Values below about 60 seconds are usually no-ops when cron ticking runs at minute resolution; multi-minute windows spread large schedule herds.',
+        default: 0
+    }),
+    TRIGGER_CRON_FANOUT: num({
+        desc: 'How many drain activities the once-per-minute cron tick runs in parallel. Each activity claims and fires one bounded batch, so the per-minute ceiling is TRIGGER_CRON_FANOUT times TRIGGER_CRON_CLAIM_BATCH runs. Raise it (and pod count) to fire more schedules per minute. Must be at least 1. Defaults to 2.',
+        default: 2
+    }),
+    TRIGGER_CRON_CLAIM_BATCH: num({
+        desc: 'How many due cron schedules a single drain activity claims and fires per tick. Bounds the load a cron burst can put on the database and the run-creation path. Must be at least 1. Defaults to 100.',
+        default: 100
+    })
+});
+export function assertRetentionDaysWithinBounds(days) {
+    if (!Number.isFinite(days) || days < 1) {
+        throw new Error(`TRIGGER_EVENT_RETENTION_DAYS must be a finite number of at least 1, received ${days}.`);
+    }
+}
+assertRetentionDaysWithinBounds(config.TRIGGER_EVENT_RETENTION_DAYS);
+export function assertCronConfigWithinBounds(jitterWindowSeconds) {
+    if (!Number.isFinite(jitterWindowSeconds) || jitterWindowSeconds < 0) {
+        throw new Error(`TRIGGER_CRON_JITTER_WINDOW_SECONDS must be a finite non-negative number, received ${jitterWindowSeconds}.`);
+    }
+}
+assertCronConfigWithinBounds(config.TRIGGER_CRON_JITTER_WINDOW_SECONDS);
+export function assertCronThroughputWithinBounds(fanout, claimBatch) {
+    if (!Number.isInteger(fanout) || fanout < 1) {
+        throw new Error(`TRIGGER_CRON_FANOUT must be an integer of at least 1, received ${fanout}.`);
+    }
+    if (!Number.isInteger(claimBatch) || claimBatch < 1) {
+        throw new Error(`TRIGGER_CRON_CLAIM_BATCH must be an integer of at least 1, received ${claimBatch}.`);
+    }
+}
+assertCronThroughputWithinBounds(config.TRIGGER_CRON_FANOUT, config.TRIGGER_CRON_CLAIM_BATCH);
+
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["import {createConfig, num} from '@shipfox/config';\n\nexport const config = createConfig({\n  TRIGGER_EVENT_RETENTION_DAYS: num({\n    desc: 'How many days a recorded trigger event (and its decisions) is kept before the hourly prune cron deletes it. Must be at least 1; a smaller value moves the cutoff to now or the future and would delete freshly recorded events. Defaults to 30.',\n    default: 30,\n  }),\n  TRIGGER_CRON_JITTER_WINDOW_SECONDS: num({\n    desc: 'Maximum number of seconds added as deterministic jitter to a cron trigger fire time. Use 0 to disable jitter. Values below about 60 seconds are usually no-ops when cron ticking runs at minute resolution; multi-minute windows spread large schedule herds.',\n    default: 0,\n  }),\n  TRIGGER_CRON_FANOUT: num({\n    desc: 'How many drain activities the once-per-minute cron tick runs in parallel. Each activity claims and fires one bounded batch, so the per-minute ceiling is TRIGGER_CRON_FANOUT times TRIGGER_CRON_CLAIM_BATCH runs. Raise it (and pod count) to fire more schedules per minute. Must be at least 1. Defaults to 2.',\n    default: 2,\n  }),\n  TRIGGER_CRON_CLAIM_BATCH: num({\n    desc: 'How many due cron schedules a single drain activity claims and fires per tick. Bounds the load a cron burst can put on the database and the run-creation path. Must be at least 1. Defaults to 100.',\n    default: 100,\n  }),\n});\n\nexport function assertRetentionDaysWithinBounds(days: number): void {\n  if (!Number.isFinite(days) || days < 1) {\n    throw new Error(\n      `TRIGGER_EVENT_RETENTION_DAYS must be a finite number of at least 1, received ${days}.`,\n    );\n  }\n}\n\nassertRetentionDaysWithinBounds(config.TRIGGER_EVENT_RETENTION_DAYS);\n\nexport function assertCronConfigWithinBounds(jitterWindowSeconds: number): void {\n  if (!Number.isFinite(jitterWindowSeconds) || jitterWindowSeconds < 0) {\n    throw new Error(\n      `TRIGGER_CRON_JITTER_WINDOW_SECONDS must be a finite non-negative number, received ${jitterWindowSeconds}.`,\n    );\n  }\n}\n\nassertCronConfigWithinBounds(config.TRIGGER_CRON_JITTER_WINDOW_SECONDS);\n\nexport function assertCronThroughputWithinBounds(fanout: number, claimBatch: number): void {\n  if (!Number.isInteger(fanout) || fanout < 1) {\n    throw new Error(`TRIGGER_CRON_FANOUT must be an integer of at least 1, received ${fanout}.`);\n  }\n  if (!Number.isInteger(claimBatch) || claimBatch < 1) {\n    throw new Error(\n      `TRIGGER_CRON_CLAIM_BATCH must be an integer of at least 1, received ${claimBatch}.`,\n    );\n  }\n}\n\nassertCronThroughputWithinBounds(config.TRIGGER_CRON_FANOUT, config.TRIGGER_CRON_CLAIM_BATCH);\n"],"names":["createConfig","num","config","TRIGGER_EVENT_RETENTION_DAYS","desc","default","TRIGGER_CRON_JITTER_WINDOW_SECONDS","TRIGGER_CRON_FANOUT","TRIGGER_CRON_CLAIM_BATCH","assertRetentionDaysWithinBounds","days","Number","isFinite","Error","assertCronConfigWithinBounds","jitterWindowSeconds","assertCronThroughputWithinBounds","fanout","claimBatch","isInteger"],"mappings":"AAAA,SAAQA,YAAY,EAAEC,GAAG,QAAO,kBAAkB;AAElD,OAAO,MAAMC,SAASF,aAAa;IACjCG,8BAA8BF,IAAI;QAChCG,MAAM;QACNC,SAAS;IACX;IACAC,oCAAoCL,IAAI;QACtCG,MAAM;QACNC,SAAS;IACX;IACAE,qBAAqBN,IAAI;QACvBG,MAAM;QACNC,SAAS;IACX;IACAG,0BAA0BP,IAAI;QAC5BG,MAAM;QACNC,SAAS;IACX;AACF,GAAG;AAEH,OAAO,SAASI,gCAAgCC,IAAY;IAC1D,IAAI,CAACC,OAAOC,QAAQ,CAACF,SAASA,OAAO,GAAG;QACtC,MAAM,IAAIG,MACR,CAAC,6EAA6E,EAAEH,KAAK,CAAC,CAAC;IAE3F;AACF;AAEAD,gCAAgCP,OAAOC,4BAA4B;AAEnE,OAAO,SAASW,6BAA6BC,mBAA2B;IACtE,IAAI,CAACJ,OAAOC,QAAQ,CAACG,wBAAwBA,sBAAsB,GAAG;QACpE,MAAM,IAAIF,MACR,CAAC,kFAAkF,EAAEE,oBAAoB,CAAC,CAAC;IAE/G;AACF;AAEAD,6BAA6BZ,OAAOI,kCAAkC;AAEtE,OAAO,SAASU,iCAAiCC,MAAc,EAAEC,UAAkB;IACjF,IAAI,CAACP,OAAOQ,SAAS,CAACF,WAAWA,SAAS,GAAG;QAC3C,MAAM,IAAIJ,MAAM,CAAC,+DAA+D,EAAEI,OAAO,CAAC,CAAC;IAC7F;IACA,IAAI,CAACN,OAAOQ,SAAS,CAACD,eAAeA,aAAa,GAAG;QACnD,MAAM,IAAIL,MACR,CAAC,oEAAoE,EAAEK,WAAW,CAAC,CAAC;IAExF;AACF;AAEAF,iCAAiCd,OAAOK,mBAAmB,EAAEL,OAAOM,wBAAwB"}

package/dist/core/compute-next-fire-at.d.ts

@@ -0,0 +1,9 @@
+export interface ComputeNextFireAtParams {
+    readonly cronExpression: string;
+    readonly timezone: string;
+    readonly from: Date;
+    readonly subscriptionId: string;
+    readonly jitterWindowSeconds: number;
+}
+export declare function computeNextFireAt(params: ComputeNextFireAtParams): Date;
+//# sourceMappingURL=compute-next-fire-at.d.ts.map

package/dist/core/compute-next-fire-at.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute-next-fire-at.d.ts","sourceRoot":"","sources":["../../src/core/compute-next-fire-at.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,CAUvE"}

package/dist/core/compute-next-fire-at.js

@@ -0,0 +1,28 @@
+import { CronExpressionParser } from 'cron-parser';
+export function computeNextFireAt(params) {
+    const iterator = CronExpressionParser.parse(params.cronExpression, {
+        currentDate: params.from,
+        tz: params.timezone
+    });
+    const occurrence = iterator.next().toDate();
+    const following = iterator.next().toDate();
+    const gapMs = following.getTime() - occurrence.getTime();
+    const offsetMs = jitterOffsetMs(params.subscriptionId, params.jitterWindowSeconds, gapMs);
+    return new Date(occurrence.getTime() + offsetMs);
+}
+function jitterOffsetMs(subscriptionId, windowSeconds, gapMs) {
+    const windowMs = Math.floor(windowSeconds * 1000);
+    const clampMs = Math.min(windowMs, gapMs);
+    if (clampMs <= 0) return 0;
+    return hashStringToUint32(subscriptionId) % clampMs;
+}
+function hashStringToUint32(value) {
+    let hash = 0x811c9dc5;
+    for(let index = 0; index < value.length; index += 1){
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+
+//# sourceMappingURL=compute-next-fire-at.js.map