@smthrs/triggers 0.0.0-stage → 1.0.0-rc.3

package/package.json

@@ -1,6 +1,244 @@
 {
   "name": "@smthrs/triggers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "1.0.0-rc.3",
+  "license": "MIT",
+  "smthrs": {
+    "group": "agent"
+  },
+  "description": "Durable cron triggers and channel contracts for flows",
+  "homepage": "https://github.com/smithersai/smithers",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smithersai/smithers.git",
+    "directory": "packages/smithers/agent/triggers"
+  },
+  "bugs": {
+    "url": "https://github.com/smithersai/smithers/issues"
+  },
+  "tags": [
+    "typescript",
+    "effect",
+    "flow",
+    "triggers"
+  ],
+  "keywords": [
+    "typescript",
+    "effect",
+    "flow",
+    "triggers"
+  ],
+  "engines": {
+    "node": ">=26.4.0"
+  },
+  "sideEffects": [],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./migrations/*": null,
+    "./internal/*": null,
+    "./*/index": null,
+    "./CatchUp": {
+      "import": {
+        "types": "./dist/esm/CatchUp.d.ts",
+        "default": "./dist/esm/CatchUp.js"
+      },
+      "require": {
+        "types": "./dist/cjs/CatchUp.d.ts",
+        "default": "./dist/cjs/CatchUp.js"
+      }
+    },
+    "./Channel": {
+      "import": {
+        "types": "./dist/esm/Channel.d.ts",
+        "default": "./dist/esm/Channel.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Channel.d.ts",
+        "default": "./dist/cjs/Channel.js"
+      }
+    },
+    "./Cron": {
+      "import": {
+        "types": "./dist/esm/Cron.d.ts",
+        "default": "./dist/esm/Cron.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Cron.d.ts",
+        "default": "./dist/cjs/Cron.js"
+      }
+    },
+    "./DispatchReader": {
+      "import": {
+        "types": "./dist/esm/DispatchReader.d.ts",
+        "default": "./dist/esm/DispatchReader.js"
+      },
+      "require": {
+        "types": "./dist/cjs/DispatchReader.d.ts",
+        "default": "./dist/cjs/DispatchReader.js"
+      }
+    },
+    "./Overlap": {
+      "import": {
+        "types": "./dist/esm/Overlap.d.ts",
+        "default": "./dist/esm/Overlap.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Overlap.d.ts",
+        "default": "./dist/cjs/Overlap.js"
+      }
+    },
+    "./Schedule": {
+      "import": {
+        "types": "./dist/esm/Schedule.d.ts",
+        "default": "./dist/esm/Schedule.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Schedule.d.ts",
+        "default": "./dist/cjs/Schedule.js"
+      }
+    },
+    "./Scheduler": {
+      "import": {
+        "types": "./dist/esm/Scheduler.d.ts",
+        "default": "./dist/esm/Scheduler.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Scheduler.d.ts",
+        "default": "./dist/cjs/Scheduler.js"
+      }
+    },
+    "./SqlTriggerStore": {
+      "import": {
+        "types": "./dist/esm/SqlTriggerStore.d.ts",
+        "default": "./dist/esm/SqlTriggerStore.js"
+      },
+      "require": {
+        "types": "./dist/cjs/SqlTriggerStore.d.ts",
+        "default": "./dist/cjs/SqlTriggerStore.js"
+      }
+    },
+    "./Trigger": {
+      "import": {
+        "types": "./dist/esm/Trigger.d.ts",
+        "default": "./dist/esm/Trigger.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Trigger.d.ts",
+        "default": "./dist/cjs/Trigger.js"
+      }
+    },
+    "./TriggerError": {
+      "import": {
+        "types": "./dist/esm/TriggerError.d.ts",
+        "default": "./dist/esm/TriggerError.js"
+      },
+      "require": {
+        "types": "./dist/cjs/TriggerError.d.ts",
+        "default": "./dist/cjs/TriggerError.js"
+      }
+    },
+    "./TriggerStore": {
+      "import": {
+        "types": "./dist/esm/TriggerStore.d.ts",
+        "default": "./dist/esm/TriggerStore.js"
+      },
+      "require": {
+        "types": "./dist/cjs/TriggerStore.d.ts",
+        "default": "./dist/cjs/TriggerStore.js"
+      }
+    },
+    "./Webhook": {
+      "import": {
+        "types": "./dist/esm/Webhook.d.ts",
+        "default": "./dist/esm/Webhook.js"
+      },
+      "require": {
+        "types": "./dist/cjs/Webhook.d.ts",
+        "default": "./dist/cjs/Webhook.js"
+      }
+    },
+    "./index": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./test/TestTriggers": {
+      "import": {
+        "types": "./dist/esm/test/TestTriggers.d.ts",
+        "default": "./dist/esm/test/TestTriggers.js"
+      },
+      "require": {
+        "types": "./dist/cjs/test/TestTriggers.d.ts",
+        "default": "./dist/cjs/test/TestTriggers.js"
+      }
+    }
+  },
+  "files": [
+    "src/**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "dist/**/package.json",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "tag": "next"
+  },
+  "dependencies": {
+    "@smthrs/control": "1.0.0-rc.3",
+    "@smthrs/database": "1.0.0-rc.3"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.115"
+  },
+  "devDependencies": {
+    "@effect/language-service": "0.87.2",
+    "@effect/vitest": "4.0.0-rc.115",
+    "@eslint/js": "9.39.5",
+    "@types/node": "26.4.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "dprint": "0.57.1",
+    "effect": "4.0.0-rc.115",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "eslint-import-resolver-typescript": "4.4.5",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-jsdoc": "64.3.4",
+    "eslint-plugin-unicorn": "65.0.0",
+    "madge": "8.0.0",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.69.0",
+    "vitest": "5.0.0"
+  },
+  "scripts": {
+    "lint": "eslint src --max-warnings=0 && dprint check",
+    "format": "dprint fmt",
+    "build": "node scripts/build.mjs",
+    "check": "tsc -b tsconfig.json && tsc -p tsconfig.test.json --noEmit",
+    "circular": "node scripts/circular.mjs",
+    "test": "vitest",
+    "coverage": "node ../../flows/database/scripts/test-matrix.mjs",
+    "test:matrix": "node ../../flows/database/scripts/test-matrix.mjs"
+  }
 }

package/src/CatchUp.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure catch-up policy decisions.
+ *
+ * @since 0.1.0
+ */
+
+import * as Effect from "effect/Effect"
+import type { Cron } from "./Cron.ts"
+import * as CronSchedule from "./Cron.ts"
+import type { CatchUp as Policy } from "./Schedule.ts"
+import { TriggerError } from "./TriggerError.ts"
+
+/**
+ * The occurrences a trigger owes since it last fired, bounded by
+ * `maxCatchUp` and by the policy named in `Schedule.CatchUp`: `none` owes
+ * nothing, `one` owes only the most recent, and `all` owes every missed tick.
+ *
+ * Every policy answers to `maxCatchUp`, `one` included: a bound of zero says
+ * no occurrence may be caught up, so a missed occurrence under `one` is
+ * `catch_up_bound_exceeded` exactly as three missed occurrences under `all`
+ * are. The bound is validated before any policy branch, so an unusable bound
+ * is refused even where the policy owes nothing.
+ *
+ * @category computation
+ * @since 0.1.0
+ */
+export const occurrences = (
+  policy: Policy,
+  maxCatchUp: number,
+  lastFiredAt: Date | undefined,
+  now: Date,
+  cron: Cron
+): Effect.Effect<ReadonlyArray<Date>, TriggerError> => {
+  if (!Number.isSafeInteger(maxCatchUp) || maxCatchUp < 0) {
+    return Effect.fail(
+      new TriggerError({
+        code: "catch_up_bound_exceeded",
+        message: `maxCatchUp must be a non-negative safe integer, received ${maxCatchUp}`,
+        path: "maxCatchUp"
+      })
+    )
+  }
+  if (lastFiredAt === undefined) return Effect.succeed([])
+  if (policy === "none") return Effect.succeed([])
+  if (policy === "one") {
+    return CronSchedule.previousAtOrBefore(cron, now).pipe(
+      Effect.flatMap((latest) =>
+        latest.getTime() <= lastFiredAt.getTime()
+          ? Effect.succeed<ReadonlyArray<Date>>([])
+          : maxCatchUp < 1
+          ? Effect.fail(
+            new TriggerError({
+              code: "catch_up_bound_exceeded",
+              message: `missed 1 occurrence; maxCatchUp is ${maxCatchUp}`
+            })
+          )
+          : Effect.succeed<ReadonlyArray<Date>>([latest])
+      )
+    )
+  }
+  return CronSchedule.occurrencesBetween(cron, lastFiredAt, now, maxCatchUp + 1).pipe(
+    Effect.flatMap((missed) =>
+      missed.length > maxCatchUp
+        ? Effect.fail(
+          new TriggerError({
+            code: "catch_up_bound_exceeded",
+            message: `missed ${missed.length} occurrences; maxCatchUp is ${maxCatchUp}`
+          })
+        )
+        : Effect.succeed(missed)
+    )
+  )
+}

package/src/Channel.ts

@@ -0,0 +1,121 @@
+/**
+ * Authority-free channel declarations.
+ *
+ * A channel authenticates opaque transport input, maps verified payloads to
+ * control-plane starts or signals, and may project run state outbound. It
+ * carries no execution authority: the target flow's envelope and permission
+ * checks apply unchanged.
+ *
+ * @see packages/smithers/agent/triggers/docs/api.md
+ * @since 0.1.0
+ */
+
+import type { IdempotencyKey } from "@smthrs/control/ControlSchema"
+import type { CredentialRef } from "@smthrs/control/Credential"
+import type * as Effect from "effect/Effect"
+import type * as Redacted from "effect/Redacted"
+import type * as Schema from "effect/Schema"
+import type { TriggerError } from "./TriggerError.ts"
+
+/**
+ * Opaque inbound transport data. Verification must inspect this value before
+ * any payload decoding occurs.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RawInbound {
+  readonly body: Uint8Array
+  readonly headers: Readonly<Record<string, string | undefined>>
+  readonly idempotencyKey: IdempotencyKey
+}
+
+/**
+ * A verified request that starts a flow.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Start {
+  readonly start: {
+    readonly flowId: string
+    readonly input: unknown
+  }
+}
+
+/**
+ * A verified request that resolves a waiting flow step.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Signal {
+  readonly signal: {
+    readonly runId: string
+    readonly stepId: string
+    readonly value: unknown
+  }
+}
+
+/**
+ * The only operations an inbound channel may request.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Inbound = Start | Signal
+
+/**
+ * Authenticates raw request bytes and headers against a credential reference.
+ *
+ * The credential arrives as a redacted reference rather than a secret, and it
+ * arrives per request rather than at declaration time: a verifier resolves it
+ * through the host's resolver when it needs the bytes. Dropping this parameter
+ * left a verifier no way to reach a secret except by closing over it in plain
+ * memory at declaration time, which is the shape the reference exists to
+ * prevent. `packages/smithers/control/src/WebhookChannel.ts` states the same contract
+ * for the control-plane side of the boundary.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Verify = (
+  raw: RawInbound,
+  credential: Redacted.Redacted<CredentialRef>
+) => Effect.Effect<void, TriggerError>
+
+/**
+ * An authority-free bidirectional channel declaration.
+ *
+ * `inbound` only describes a control-plane start or signal. It cannot supply
+ * capabilities, grants, or an alternate execution envelope.
+ *
+ * @category declarations
+ * @since 0.1.0
+ */
+export interface Channel<Payload, Run = never, Outbound = never> {
+  readonly name: string
+  readonly verify: Verify
+  readonly inbound: (payload: Payload) => Inbound
+  readonly outbound?: ((run: Run) => Outbound) | undefined
+}
+
+/**
+ * Configuration for a schema-declared channel.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Config<Payload, Run = never, Outbound = never> extends Channel<Payload, Run, Outbound> {
+  readonly schema: Schema.Schema<Payload>
+}
+
+/**
+ * Declares a channel without adding authority or execution behavior.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const make = <Payload, Run = never, Outbound = never>(
+  config: Channel<Payload, Run, Outbound>
+): Channel<Payload, Run, Outbound> => config