@shware/workflow 0.0.0-stage → 0.1.0

package/dist/cloudflare/router.d.cts

@@ -0,0 +1,157 @@
+import { TriggerIR } from "../ir.cjs";
+import { Contract } from "../contract.cjs";
+import { JourneyEnv } from "./bindings.cjs";
+import { JourneyStore, ProfileProps } from "../store/index.cjs";
+//#region src/cloudflare/router.d.ts
+/**
+ * Ingest router. An incoming event does four things: it is stored, it wakes
+ * waiting instances, it is matched against event triggers, and it re-evaluates
+ * segment-trigger membership. Plus /deploy (persist a bundle) and /identify
+ * (merge a profile — which wakes property-condition waits via
+ * PROFILE_UPDATED_EVENT and re-evaluates segment triggers too).
+ *
+ * Storage goes through a JourneyStore; the `store` argument defaults to the
+ * D1 + KV store built from the env's bindings, so a Worker that only has those
+ * calls these functions exactly as before.
+ */
+export interface IngestInput {
+  userId: string;
+  event: string;
+  payload?: Record<string, unknown>;
+  ts?: number;
+  /**
+   * This occurrence's identity, and with it the idempotency of sending it.
+   *
+   * Only the sender can know whether two deliveries describe one occurrence or
+   * two, so the engine does not decide: an id it has already stored makes the
+   * second delivery a no-op. That matters because ingest is reachable from two
+   * retrying callers — an HTTP client retrying a 500, and the interpreter's
+   * send_event step being retried after it already committed its row — and a
+   * second copy of an event silently changes every count- and window-based
+   * condition that reads the log.
+   *
+   * Callers that retry should send an id they can reproduce. Omitting it gets
+   * a fresh one, which records the event as its own occurrence.
+   */
+  id?: string;
+}
+export interface IngestResult {
+  /** The occurrence's identity: the caller's `id`, or the one minted for it. */
+  id: string;
+  /** False when that id was already in the log: nothing was written this time. */
+  stored: boolean;
+  woke: number;
+  started: string[];
+}
+export declare function ingestEvent(env: JourneyEnv, input: IngestInput, store?: JourneyStore): Promise<IngestResult>;
+/**
+ * Segment-entry triggers, maintained lazily: on each ingest/identify for a
+ * user, re-evaluate every trigger-routed segment for that user and act on the
+ * membership transition (enter → start journeys, leave → drop membership so a
+ * later re-entry is observable). Purely time-driven drift (an inactivity
+ * segment turning true by clock alone) has no event to ride on: the scheduled
+ * sweep catches it (`sweepSegments`).
+ */
+export declare function refreshSegmentTriggers(env: JourneyEnv, store: JourneyStore, userId: string, ts: number): Promise<string[]>;
+export interface SweepResult {
+  users: number;
+  /** Journeys the segments' entries started. */
+  started: string[];
+  /** Each deployed segment's size after the sweep (empty when the store keeps no reporting). */
+  sizes: {
+    segment: string;
+    size: number;
+  }[];
+}
+/**
+ * The scheduled sweep: every deployed segment evaluated for every known user — the evaluator a
+ * journey's conditions run on, so a member is exactly who a journey would see in it. Membership
+ * follows (joiners keep the time they joined, leavers are removed), segment triggers start the
+ * journeys of whoever entered by the clock alone, and the store records each segment's size.
+ * It walks users one by one: fine for thousands, a large audience wants SQL-side evaluation.
+ */
+export declare function sweepSegments(env: JourneyEnv, store: JourneyStore, now?: number): Promise<SweepResult>;
+export interface IdentifyResult {
+  ok: true;
+  props: ProfileProps;
+  woke: number;
+  started: string[];
+}
+/**
+ * Merge-patch profile properties (a null removes one), then wake property waits
+ * and re-evaluate segment triggers. The merge is one statement in the store, so
+ * two identifies landing together cannot lose each other's fields.
+ */
+export declare function identifyUser(env: JourneyEnv, userId: string, props: ProfileProps, store?: JourneyStore): Promise<IdentifyResult>;
+export interface DeviceRegistration {
+  userId: string;
+  token: string;
+  platform: string;
+  ts?: number;
+}
+/**
+ * A push token registered for the user (or moved to them from another account: a token belongs
+ * to one user at a time). Wakes the waits that read devices (`reachable('push')` inside
+ * `waitUntil`), for the new owner and the previous one.
+ */
+export declare function registerDevice(env: JourneyEnv, device: DeviceRegistration, store?: JourneyStore): Promise<{
+  ok: true;
+  woke: number;
+}>;
+/**
+ * Forget a user (a deleted account): the request is recorded first, then carried out. An
+ * instance that will not stop leaves it pending — nothing erased yet — and the scheduled sweep
+ * retries it; `erased: false` says so.
+ */
+export declare function forgetUser(env: JourneyEnv, userId: string, store?: JourneyStore, now?: number): Promise<{
+  ok: true;
+  erased: boolean;
+  pending: string[];
+}>;
+/**
+ * The user signed out on the device: the token stays registered, bound to nobody, so the next
+ * sign-in only has to bind it again. Wakes the former owner's device waits (`reachable('push')`
+ * may no longer hold).
+ */
+export declare function unbindDevice(env: JourneyEnv, token: string, store?: JourneyStore): Promise<{
+  ok: true;
+  woke: number;
+}>;
+/** A push token forgotten for good (the push service reports it gone); wakes its owner's device waits. */
+export declare function removeDevice(env: JourneyEnv, token: string, store?: JourneyStore): Promise<{
+  ok: true;
+  woke: number;
+}>;
+export interface DeployResult {
+  workflows: string[];
+  /**
+   * Workflows whose trigger type has no runtime routing yet — they deploy (the
+   * IR is stored and versioned) but will never start until the routing lands.
+   * Currently: date (TODO — needs cron + Queues, instance creation is
+   * rate-limited and a date trigger fans out to the whole audience at once)
+   * and webhook (TODO — needs endpoint allocation).
+   */
+  unrouted: {
+    workflow: string;
+    trigger: TriggerIR['type'];
+  }[];
+}
+/** A bundle whose declared hashes do not describe its contents — rejected before anything is written. */
+export declare class BundleIntegrityError extends Error {
+  constructor(message: string);
+}
+/** Bundle deploy, terraform-apply style: workflow bodies first (content-addressed, so a failed deploy leaves only harmless orphans), then the routing swap. */
+export declare function deployBundle(env: JourneyEnv, bundle: unknown, store?: JourneyStore): Promise<DeployResult>;
+/**
+ * How the ingest API applies a contract: 'enforce' refuses an invalid event or
+ * patch with a 400 before anything is stored, woken or started; 'report' logs
+ * the issues (event id, name, field paths — never the payload) and accepts it,
+ * for checking real producers before turning enforcement on.
+ */
+export interface IngestValidation {
+  contract?: Contract | undefined;
+  mode?: 'enforce' | 'report' | undefined;
+}
+export declare function handleRequest(request: Request, env: JourneyEnv, store?: JourneyStore, validation?: IngestValidation): Promise<Response>;
+//#endregion
+//# sourceMappingURL=router.d.cts.map

package/dist/cloudflare/router.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.cts","names":[],"sources":["../../src/cloudflare/router.ts"],"mappings":";;;;;;;;;;;;;;;;iBAuCiB;EACf;EACA;EACA,UAAU;EACV;;;;;;;;;;;;;;;EAeA;;iBAGe;;EAEf;;EAEA;EACA;EACA;;wBAGoB,YACpB,KAAK,YACL,OAAO,aACP,QAAO,eACN,QAAQ;;;;;;;;;wBAsGW,uBACpB,KAAK,YACL,OAAO,cACP,gBACA,aACC;iBAgFc;EACf;;EAEA;;EAEA;IAAS;IAAiB;;;;;;;;;;wBAUN,cACpB,KAAK,YACL,OAAO,cACP,eACC,QAAQ;iBAqFM;EACf;EACA,OAAO;EACP;EACA;;;;;;;wBAQoB,aACpB,KAAK,YACL,gBACA,OAAO,cACP,QAAO,eACN,QAAQ;iBAUM;EACf;EACA;EACA;EACA;;;;;;;wBAQoB,eACpB,KAAK,YACL,QAAQ,oBACR,QAAO,eACN;EAAU;EAAU;;;;;;;wBAoED,WACpB,KAAK,YACL,gBACA,QAAO,cACP,eACC;EAAU;EAAU;EAAiB;;;;;;;wBAUlB,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;;wBAQD,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;iBASN;EACf;;;;;;;;EAQA;IAAY;IAAkB,SAAS;;;;qBAI5B,6BAA6B;EACxC,YAAY;;;wBAyCQ,aACpB,KAAK,YACL,iBACA,QAAO,eACN,QAAQ;;;;;;;iBA+CM;EACf,WAAW;EACX;;wBAGoB,cACpB,SAAS,SACT,KAAK,YACL,QAAO,cACP,aAAY,mBACX,QAAQ"}

package/dist/cloudflare/router.d.mts

@@ -0,0 +1,157 @@
+import { TriggerIR } from "../ir.mjs";
+import { Contract } from "../contract.mjs";
+import { JourneyEnv } from "./bindings.mjs";
+import { JourneyStore, ProfileProps } from "../store/index.mjs";
+//#region src/cloudflare/router.d.ts
+/**
+ * Ingest router. An incoming event does four things: it is stored, it wakes
+ * waiting instances, it is matched against event triggers, and it re-evaluates
+ * segment-trigger membership. Plus /deploy (persist a bundle) and /identify
+ * (merge a profile — which wakes property-condition waits via
+ * PROFILE_UPDATED_EVENT and re-evaluates segment triggers too).
+ *
+ * Storage goes through a JourneyStore; the `store` argument defaults to the
+ * D1 + KV store built from the env's bindings, so a Worker that only has those
+ * calls these functions exactly as before.
+ */
+export interface IngestInput {
+  userId: string;
+  event: string;
+  payload?: Record<string, unknown>;
+  ts?: number;
+  /**
+   * This occurrence's identity, and with it the idempotency of sending it.
+   *
+   * Only the sender can know whether two deliveries describe one occurrence or
+   * two, so the engine does not decide: an id it has already stored makes the
+   * second delivery a no-op. That matters because ingest is reachable from two
+   * retrying callers — an HTTP client retrying a 500, and the interpreter's
+   * send_event step being retried after it already committed its row — and a
+   * second copy of an event silently changes every count- and window-based
+   * condition that reads the log.
+   *
+   * Callers that retry should send an id they can reproduce. Omitting it gets
+   * a fresh one, which records the event as its own occurrence.
+   */
+  id?: string;
+}
+export interface IngestResult {
+  /** The occurrence's identity: the caller's `id`, or the one minted for it. */
+  id: string;
+  /** False when that id was already in the log: nothing was written this time. */
+  stored: boolean;
+  woke: number;
+  started: string[];
+}
+export declare function ingestEvent(env: JourneyEnv, input: IngestInput, store?: JourneyStore): Promise<IngestResult>;
+/**
+ * Segment-entry triggers, maintained lazily: on each ingest/identify for a
+ * user, re-evaluate every trigger-routed segment for that user and act on the
+ * membership transition (enter → start journeys, leave → drop membership so a
+ * later re-entry is observable). Purely time-driven drift (an inactivity
+ * segment turning true by clock alone) has no event to ride on: the scheduled
+ * sweep catches it (`sweepSegments`).
+ */
+export declare function refreshSegmentTriggers(env: JourneyEnv, store: JourneyStore, userId: string, ts: number): Promise<string[]>;
+export interface SweepResult {
+  users: number;
+  /** Journeys the segments' entries started. */
+  started: string[];
+  /** Each deployed segment's size after the sweep (empty when the store keeps no reporting). */
+  sizes: {
+    segment: string;
+    size: number;
+  }[];
+}
+/**
+ * The scheduled sweep: every deployed segment evaluated for every known user — the evaluator a
+ * journey's conditions run on, so a member is exactly who a journey would see in it. Membership
+ * follows (joiners keep the time they joined, leavers are removed), segment triggers start the
+ * journeys of whoever entered by the clock alone, and the store records each segment's size.
+ * It walks users one by one: fine for thousands, a large audience wants SQL-side evaluation.
+ */
+export declare function sweepSegments(env: JourneyEnv, store: JourneyStore, now?: number): Promise<SweepResult>;
+export interface IdentifyResult {
+  ok: true;
+  props: ProfileProps;
+  woke: number;
+  started: string[];
+}
+/**
+ * Merge-patch profile properties (a null removes one), then wake property waits
+ * and re-evaluate segment triggers. The merge is one statement in the store, so
+ * two identifies landing together cannot lose each other's fields.
+ */
+export declare function identifyUser(env: JourneyEnv, userId: string, props: ProfileProps, store?: JourneyStore): Promise<IdentifyResult>;
+export interface DeviceRegistration {
+  userId: string;
+  token: string;
+  platform: string;
+  ts?: number;
+}
+/**
+ * A push token registered for the user (or moved to them from another account: a token belongs
+ * to one user at a time). Wakes the waits that read devices (`reachable('push')` inside
+ * `waitUntil`), for the new owner and the previous one.
+ */
+export declare function registerDevice(env: JourneyEnv, device: DeviceRegistration, store?: JourneyStore): Promise<{
+  ok: true;
+  woke: number;
+}>;
+/**
+ * Forget a user (a deleted account): the request is recorded first, then carried out. An
+ * instance that will not stop leaves it pending — nothing erased yet — and the scheduled sweep
+ * retries it; `erased: false` says so.
+ */
+export declare function forgetUser(env: JourneyEnv, userId: string, store?: JourneyStore, now?: number): Promise<{
+  ok: true;
+  erased: boolean;
+  pending: string[];
+}>;
+/**
+ * The user signed out on the device: the token stays registered, bound to nobody, so the next
+ * sign-in only has to bind it again. Wakes the former owner's device waits (`reachable('push')`
+ * may no longer hold).
+ */
+export declare function unbindDevice(env: JourneyEnv, token: string, store?: JourneyStore): Promise<{
+  ok: true;
+  woke: number;
+}>;
+/** A push token forgotten for good (the push service reports it gone); wakes its owner's device waits. */
+export declare function removeDevice(env: JourneyEnv, token: string, store?: JourneyStore): Promise<{
+  ok: true;
+  woke: number;
+}>;
+export interface DeployResult {
+  workflows: string[];
+  /**
+   * Workflows whose trigger type has no runtime routing yet — they deploy (the
+   * IR is stored and versioned) but will never start until the routing lands.
+   * Currently: date (TODO — needs cron + Queues, instance creation is
+   * rate-limited and a date trigger fans out to the whole audience at once)
+   * and webhook (TODO — needs endpoint allocation).
+   */
+  unrouted: {
+    workflow: string;
+    trigger: TriggerIR['type'];
+  }[];
+}
+/** A bundle whose declared hashes do not describe its contents — rejected before anything is written. */
+export declare class BundleIntegrityError extends Error {
+  constructor(message: string);
+}
+/** Bundle deploy, terraform-apply style: workflow bodies first (content-addressed, so a failed deploy leaves only harmless orphans), then the routing swap. */
+export declare function deployBundle(env: JourneyEnv, bundle: unknown, store?: JourneyStore): Promise<DeployResult>;
+/**
+ * How the ingest API applies a contract: 'enforce' refuses an invalid event or
+ * patch with a 400 before anything is stored, woken or started; 'report' logs
+ * the issues (event id, name, field paths — never the payload) and accepts it,
+ * for checking real producers before turning enforcement on.
+ */
+export interface IngestValidation {
+  contract?: Contract | undefined;
+  mode?: 'enforce' | 'report' | undefined;
+}
+export declare function handleRequest(request: Request, env: JourneyEnv, store?: JourneyStore, validation?: IngestValidation): Promise<Response>;
+//#endregion
+//# sourceMappingURL=router.d.mts.map

package/dist/cloudflare/router.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.mts","names":[],"sources":["../../src/cloudflare/router.ts"],"mappings":";;;;;;;;;;;;;;;;iBAuCiB;EACf;EACA;EACA,UAAU;EACV;;;;;;;;;;;;;;;EAeA;;iBAGe;;EAEf;;EAEA;EACA;EACA;;wBAGoB,YACpB,KAAK,YACL,OAAO,aACP,QAAO,eACN,QAAQ;;;;;;;;;wBAsGW,uBACpB,KAAK,YACL,OAAO,cACP,gBACA,aACC;iBAgFc;EACf;;EAEA;;EAEA;IAAS;IAAiB;;;;;;;;;;wBAUN,cACpB,KAAK,YACL,OAAO,cACP,eACC,QAAQ;iBAqFM;EACf;EACA,OAAO;EACP;EACA;;;;;;;wBAQoB,aACpB,KAAK,YACL,gBACA,OAAO,cACP,QAAO,eACN,QAAQ;iBAUM;EACf;EACA;EACA;EACA;;;;;;;wBAQoB,eACpB,KAAK,YACL,QAAQ,oBACR,QAAO,eACN;EAAU;EAAU;;;;;;;wBAoED,WACpB,KAAK,YACL,gBACA,QAAO,cACP,eACC;EAAU;EAAU;EAAiB;;;;;;;wBAUlB,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;;wBAQD,aACpB,KAAK,YACL,eACA,QAAO,eACN;EAAU;EAAU;;iBASN;EACf;;;;;;;;EAQA;IAAY;IAAkB,SAAS;;;;qBAI5B,6BAA6B;EACxC,YAAY;;;wBAyCQ,aACpB,KAAK,YACL,iBACA,QAAO,eACN,QAAQ;;;;;;;iBA+CM;EACf,WAAW;EACX;;wBAGoB,cACpB,SAAS,SACT,KAAK,YACL,QAAO,cACP,aAAY,mBACX,QAAQ"}