@shware/workflow 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,192 @@
 {
   "name": "@shware/workflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShwareHQ/shware-sdk.git"
+  },
+  "files": [
+    "dist",
+    "src/cloudflare/schema.sql",
+    "src/cloudflare/workers.d.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./engine": {
+      "import": {
+        "types": "./dist/engine/index.d.mts",
+        "default": "./dist/engine/index.mjs"
+      },
+      "require": {
+        "types": "./dist/engine/index.d.cts",
+        "default": "./dist/engine/index.cjs"
+      }
+    },
+    "./schema.sql": "./dist/cloudflare/schema.sql",
+    "./cloudflare": {
+      "import": {
+        "types": "./dist/cloudflare/index.d.mts",
+        "default": "./dist/cloudflare/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cloudflare/index.d.cts",
+        "default": "./dist/cloudflare/index.cjs"
+      }
+    },
+    "./store": {
+      "import": {
+        "types": "./dist/store/index.d.mts",
+        "default": "./dist/store/index.mjs"
+      },
+      "require": {
+        "types": "./dist/store/index.d.cts",
+        "default": "./dist/store/index.cjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client.d.mts",
+        "default": "./dist/client.mjs"
+      },
+      "require": {
+        "types": "./dist/client.d.cts",
+        "default": "./dist/client.cjs"
+      }
+    },
+    "./postgres-js": {
+      "import": {
+        "types": "./dist/postgres-js.d.mts",
+        "default": "./dist/postgres-js.mjs"
+      },
+      "require": {
+        "types": "./dist/postgres-js.d.cts",
+        "default": "./dist/postgres-js.cjs"
+      }
+    },
+    "./react-email": {
+      "import": {
+        "types": "./dist/react-email.d.mts",
+        "default": "./dist/react-email.mjs"
+      },
+      "require": {
+        "types": "./dist/react-email.d.cts",
+        "default": "./dist/react-email.cjs"
+      }
+    },
+    "./push": {
+      "import": {
+        "types": "./dist/push.d.mts",
+        "default": "./dist/push.mjs"
+      },
+      "require": {
+        "types": "./dist/push.d.cts",
+        "default": "./dist/push.cjs"
+      }
+    },
+    "./apns": {
+      "import": {
+        "types": "./dist/apns.d.mts",
+        "default": "./dist/apns.mjs"
+      },
+      "require": {
+        "types": "./dist/apns.d.cts",
+        "default": "./dist/apns.cjs"
+      }
+    },
+    "./apns-relay": {
+      "import": {
+        "types": "./dist/apns-relay.d.mts",
+        "default": "./dist/apns-relay.mjs"
+      },
+      "require": {
+        "types": "./dist/apns-relay.d.cts",
+        "default": "./dist/apns-relay.cjs"
+      }
+    },
+    "./fcm": {
+      "import": {
+        "types": "./dist/fcm.d.mts",
+        "default": "./dist/fcm.mjs"
+      },
+      "require": {
+        "types": "./dist/fcm.d.cts",
+        "default": "./dist/fcm.cjs"
+      }
+    },
+    "./webpush": {
+      "import": {
+        "types": "./dist/webpush.d.mts",
+        "default": "./dist/webpush.mjs"
+      },
+      "require": {
+        "types": "./dist/webpush.d.cts",
+        "default": "./dist/webpush.cjs"
+      }
+    },
+    "./webhooks": {
+      "import": {
+        "types": "./dist/webhooks.d.mts",
+        "default": "./dist/webhooks.mjs"
+      },
+      "require": {
+        "types": "./dist/webhooks.d.cts",
+        "default": "./dist/webhooks.cjs"
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@slack/types": "^3.2.0",
+    "@types/ms": "^2.1.0",
+    "discord-api-types": "^0.38.56",
+    "ms": "^2.1.3",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.8",
+    "@repo/typescript-config": "0.0.0",
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "postgres": "^3.4.9",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.2"
+  },
+  "peerDependencies": {
+    "postgres": ">=3.4.0",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "peerDependenciesMeta": {
+    "postgres": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "dev": "tsc --watch",
+    "build": "tsdown",
+    "test": "vitest run --passWithNoTests",
+    "check-types": "tsc --noEmit",
+    "lint": "oxlint --type-aware src tests --fix"
+  }
 }

package/src/cloudflare/schema.sql

@@ -0,0 +1,127 @@
+-- Journey engine data plane (D1). Conditions are evaluated by querying at
+-- decision time: lazy, with no real-time segment materialisation.
+
+-- Raw event log. Every count- and window-based condition reads this table, so a
+-- duplicated row silently changes a journey's behaviour, and `id` is what stops
+-- that: it is the occurrence's identity, chosen by whoever sent it, and the key
+-- constraint makes a second delivery of the same occurrence a no-op. Ingest is
+-- reachable from two retrying callers (a client retrying a 500, and the
+-- interpreter's send_event step being retried after it already committed its
+-- row), so both pass an id they can reproduce.
+--
+-- Only the sender knows whether two deliveries describe one occurrence or two,
+-- so the engine never invents that answer: an ingest that arrives without an id
+-- is given a fresh one, which is a truthful "this is its own occurrence" rather
+-- than a guess.
+CREATE TABLE IF NOT EXISTS events (
+  id      TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT NOT NULL,
+  name    TEXT NOT NULL,
+  ts      INTEGER NOT NULL,
+  payload TEXT NOT NULL DEFAULT '{}'
+);
+CREATE INDEX IF NOT EXISTS idx_events_user_name_ts ON events (user_id, name, ts);
+
+CREATE TABLE IF NOT EXISTS profiles (
+  user_id TEXT PRIMARY KEY,
+  props   TEXT NOT NULL DEFAULT '{}'
+);
+
+-- Deploy artefacts: segment definitions (resolved by id during evaluation)
+-- and the trigger routing table.
+-- Push devices: one row per provider token, owned by the user who registered it last.
+-- user_id is null for a device whose user signed out: it stays registered until the next
+-- sign-in binds it again. A database created while it was NOT NULL needs the table rebuilt.
+CREATE TABLE IF NOT EXISTS devices (
+  token    TEXT PRIMARY KEY,
+  user_id  TEXT,
+  platform TEXT NOT NULL,
+  ts       INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_devices_user_ts ON devices (user_id, ts);
+
+CREATE TABLE IF NOT EXISTS segments (
+  id        TEXT PRIMARY KEY,
+  condition TEXT NOT NULL,
+  hash      TEXT NOT NULL
+);
+
+-- Event trigger routes. `where` gates on the triggering event's payload
+-- (a payload-only condition tree); `filter` gates on the profile.
+CREATE TABLE IF NOT EXISTS triggers (
+  workflow  TEXT PRIMARY KEY,
+  hash      TEXT NOT NULL,
+  event     TEXT NOT NULL,
+  "where"   TEXT,
+  filter    TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_triggers_event ON triggers (event);
+
+-- Segment-entry trigger routes.
+CREATE TABLE IF NOT EXISTS segment_triggers (
+  workflow TEXT PRIMARY KEY,
+  hash     TEXT NOT NULL,
+  segment  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_segment_triggers_segment ON segment_triggers (segment);
+
+-- Lazily maintained segment membership, covering only segments that something
+-- triggers on. Transitions are re-evaluated when the user is ingested or
+-- identified, and by the scheduled sweep (journeyWorker's `scheduled`), which
+-- also catches drift driven purely by the clock.
+CREATE TABLE IF NOT EXISTS segment_members (
+  segment TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  ts      INTEGER NOT NULL,
+  PRIMARY KEY (segment, user_id)
+);
+
+-- Workflows a segment entry still has to start for a member: written with the
+-- membership, removed as each starts, so a failed start is retried by the next
+-- evaluation instead of being hidden behind the membership.
+CREATE TABLE IF NOT EXISTS segment_starts (
+  segment  TEXT NOT NULL,
+  workflow TEXT NOT NULL,
+  user_id  TEXT NOT NULL,
+  ts       INTEGER NOT NULL,
+  PRIMARY KEY (segment, workflow, user_id)
+);
+
+-- Erasures in progress (forgetUser): the user's data stays until every running
+-- instance is stopped, and the scheduled sweep retries what is left.
+CREATE TABLE IF NOT EXISTS erasures (
+  user_id TEXT PRIMARY KEY,
+  ts      INTEGER NOT NULL
+);
+
+-- Entry ledger: the once-per-user policy, instance addressing, and the audit
+-- trail of which IR version each user was pinned to.
+--
+-- The primary key is what makes the policy atomic, and it is also the whole
+-- policy: a user who has entered cannot enter again. The one exception is a
+-- row left at 'failed', which records an instance that died rather than a
+-- journey the user received; the router takes such a row over so the entry can
+-- be retried (see startJourney). A general re-entry policy is a separate
+-- design question and deliberately not encoded here.
+CREATE TABLE IF NOT EXISTS entries (
+  workflow    TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  instance_id TEXT NOT NULL,
+  hash        TEXT NOT NULL,
+  status      TEXT NOT NULL,
+  ts          INTEGER NOT NULL,
+  PRIMARY KEY (workflow, user_id)
+);
+
+-- wait_until wake routing. `wake_handle` is an opaque handle (the instance id
+-- on Cloudflare, a callback id on AWS). The primary key makes the interpreter's
+-- re-subscription on every wait attempt idempotent, which its one-shot-callback
+-- contract requires.
+CREATE TABLE IF NOT EXISTS subscriptions (
+  user_id     TEXT NOT NULL,
+  event       TEXT NOT NULL,
+  wake_handle TEXT NOT NULL,
+  ts          INTEGER NOT NULL,
+  PRIMARY KEY (wake_handle, event)
+);
+CREATE INDEX IF NOT EXISTS idx_subs_user_event ON subscriptions (user_id, event);

package/src/cloudflare/workers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal ambient declaration for cloudflare:workers — only the surface
+ * JourneyRunner actually uses. @cloudflare/workers-types is avoided because its
+ * global types clash with react/DOM. Shapes follow the official API:
+ * https://developers.cloudflare.com/workflows/build/workers-api/
+ */
+declare module 'cloudflare:workers' {
+  export interface WorkflowEvent<Params = unknown> {
+    payload: Readonly<Params>;
+    timestamp: Date;
+    instanceId: string;
+  }
+
+  export interface WorkflowStepEvent<Payload = unknown> {
+    payload: Payload;
+    timestamp: Date;
+    type: string;
+  }
+
+  export interface WorkflowStep {
+    do<T>(name: string, callback: () => Promise<T>): Promise<T>;
+    sleep(name: string, durationMs: number | string): Promise<void>;
+    sleepUntil(name: string, timestamp: Date | number): Promise<void>;
+    waitForEvent<Payload = unknown>(
+      name: string,
+      options: { type: string; timeout?: number | string }
+    ): Promise<WorkflowStepEvent<Payload>>;
+  }
+
+  export abstract class WorkflowEntrypoint<Env = unknown, Params = unknown> {
+    /** The runtime constructs it with the execution context and the bindings. */
+    constructor(ctx: unknown, env: Env);
+    protected readonly ctx: unknown;
+    protected readonly env: Env;
+    abstract run(event: WorkflowEvent<Params>, step: WorkflowStep): Promise<unknown>;
+  }
+}
+
+/** The one export of cloudflare:workflows the runner uses: an error that ends the step without retries. */
+declare module 'cloudflare:workflows' {
+  export class NonRetryableError extends Error {
+    constructor(message: string, name?: string);
+  }
+}