@amalgm/automations 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,128 @@
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+interface TriggerBase {
+    id: string;
+    enabled?: boolean;
+}
+export interface CronTrigger extends TriggerBase {
+    kind: 'cron';
+    cron: string;
+    timezone?: string;
+}
+export interface EventTrigger extends TriggerBase {
+    kind: 'event';
+    source?: string;
+    event?: string;
+    secret: string;
+}
+export type Trigger = CronTrigger | EventTrigger;
+export interface WorkflowDefinition {
+    id: string;
+    name?: string;
+    script: string;
+    compiled?: Json;
+    allowlist?: Json;
+    limits?: Json;
+}
+export interface AutomationDefinition {
+    id: string;
+    targetId: string;
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    trigger: Trigger;
+    workflow: WorkflowDefinition;
+}
+/** The only authenticated identity Automations accepts from Core. */
+export interface AutomationTarget {
+    userId: string;
+    targetId: string;
+}
+export type PreparedTrigger = (CronTrigger & {
+    enabled: boolean;
+    timezone: string;
+    nextRunAt: string;
+}) | (EventTrigger & {
+    enabled: boolean;
+    source: string;
+    event: string;
+});
+export interface PreparedAutomation extends Omit<AutomationDefinition, 'enabled' | 'trigger'> {
+    userId: string;
+    enabled: boolean;
+    trigger: PreparedTrigger;
+}
+interface StoredTriggerBase {
+    userId: string;
+    automationId: string;
+    triggerId: string;
+    targetId: string;
+}
+export interface StoredEventTrigger extends StoredTriggerBase {
+    kind: 'event';
+    source: string;
+    event: string;
+    secret: string;
+}
+export interface DueCronTrigger extends StoredTriggerBase {
+    kind: 'cron';
+    cron: string;
+    timezone: string;
+    nextRunAt: string;
+}
+export type RunInput = {
+    kind: 'event';
+    source: string;
+    event: string;
+    payload: Json;
+} | {
+    kind: 'cron';
+    scheduledFor: string;
+};
+export type RunStatus = 'pending' | 'sent' | 'running' | 'completed' | 'failed';
+export interface AutomationRun {
+    id: string;
+    userId: string;
+    targetId: string;
+    automationId: string;
+    triggerId: string;
+    workflowId: string;
+    automation: Json;
+    input: RunInput;
+    status: RunStatus;
+    createdAt: string;
+    sentAt?: string;
+    startedAt?: string;
+    finishedAt?: string;
+    output?: Json;
+    error?: string;
+}
+export interface RunUpdate {
+    status: 'running' | 'completed' | 'failed';
+    startedAt?: string;
+    finishedAt?: string;
+    output?: Json;
+    error?: string;
+}
+export interface AutomationStore {
+    saveAutomation(automation: PreparedAutomation): Promise<void>;
+    deleteAutomation(userId: string, automationId: string): Promise<boolean>;
+    eventTriggers(target: AutomationTarget): Promise<StoredEventTrigger[]>;
+    dueCronTriggers(now: Date): Promise<DueCronTrigger[]>;
+    enqueueEvent(trigger: StoredEventTrigger, input: Extract<RunInput, {
+        kind: 'event';
+    }>, now: Date): Promise<AutomationRun | null>;
+    enqueueCron(trigger: DueCronTrigger, nextRunAt: string, now: Date): Promise<AutomationRun | null>;
+    pendingRuns(target: AutomationTarget): Promise<AutomationRun[]>;
+    listRuns(userId: string, automationId?: string): Promise<AutomationRun[]>;
+    markSent(runId: string, target: AutomationTarget, now: Date): Promise<boolean>;
+    updateRun(target: AutomationTarget, runId: string, update: RunUpdate): Promise<AutomationRun | null>;
+}
+/** The complete transport capability Automations needs from Core. */
+export interface AutomationTransport {
+    isOnline(target: AutomationTarget): boolean;
+    send(run: AutomationRun): Promise<boolean>;
+}
+export type AutomationLog = (event: 'event.rejected' | 'run.pending' | 'drain.started' | 'run.sent' | 'run.failed', details: Readonly<Record<string, string>>) => void;
+export {};

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/validation.d.ts

@@ -0,0 +1,11 @@
+import type { Json, PageQuery } from './contract.js';
+export declare const IDENTIFIER: RegExp;
+export declare function newId(prefix: string): string;
+export declare function id(value: string, label: string): string;
+export declare function optionalText(value: string | null | undefined, label: string): string | null | undefined;
+export declare function requiredText(value: string, label: string): string;
+export declare function webhookSecret(value: string): string;
+export declare function schedule(cron: string, timezone: string): void;
+export declare function json(value: unknown, label: string): asserts value is Json;
+export declare function page(query: PageQuery | undefined): Required<PageQuery>;
+export declare function nonEmptyPatch(patch: object, label: string): void;

package/dist/src/validation.js

@@ -0,0 +1,69 @@
+import { randomUUID } from 'node:crypto';
+import { CronExpressionParser } from 'cron-parser';
+import { ValidationError } from './errors.js';
+export const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+const MAX_PAGE_SIZE = 100;
+export function newId(prefix) {
+    return `${prefix}_${randomUUID()}`;
+}
+export function id(value, label) {
+    if (!IDENTIFIER.test(value))
+        throw new ValidationError(`${label} is invalid`);
+    return value;
+}
+export function optionalText(value, label) {
+    if (value === undefined || value === null)
+        return value;
+    if (!value.trim())
+        throw new ValidationError(`${label} cannot be blank`);
+    return value;
+}
+export function requiredText(value, label) {
+    if (!value || !value.trim())
+        throw new ValidationError(`${label} is required`);
+    return value;
+}
+export function webhookSecret(value) {
+    if (value.length < 16)
+        throw new ValidationError('Webhook secret must be at least 16 characters');
+    return value;
+}
+export function schedule(cron, timezone) {
+    requiredText(cron, 'Schedule cron');
+    requiredText(timezone, 'Schedule timezone');
+    try {
+        CronExpressionParser.parse(cron, { currentDate: new Date(0), tz: timezone });
+    }
+    catch {
+        throw new ValidationError('Schedule cron or timezone is invalid');
+    }
+}
+export function json(value, label) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item) => json(item, label));
+        return;
+    }
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        Object.values(value).forEach((item) => json(item, label));
+        return;
+    }
+    throw new ValidationError(`${label} must be JSON`);
+}
+export function page(query) {
+    const limit = query?.limit ?? 20;
+    const offset = query?.offset ?? 0;
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_PAGE_SIZE) {
+        throw new ValidationError(`limit must be an integer from 1 to ${MAX_PAGE_SIZE}`);
+    }
+    if (!Number.isInteger(offset) || offset < 0)
+        throw new ValidationError('offset must be a non-negative integer');
+    return { limit, offset };
+}
+export function nonEmptyPatch(patch, label) {
+    if (Object.keys(patch).length === 0)
+        throw new ValidationError(`${label} must include a change`);
+}

package/dist/src/webhook.d.ts

@@ -0,0 +1,18 @@
+import type { Json, StoredEventTrigger } from './types.js';
+export declare function normalizeHeaders(headers: Record<string, string>): Record<string, string>;
+export declare function verifyEventSecret(secret: string, headers: Record<string, string>, body: Buffer): boolean;
+export declare function matchesEvent(trigger: Pick<StoredEventTrigger, 'source' | 'event'>, source: string, event: string): boolean;
+export declare function eventReferences(headers: Record<string, string>, payload: Json): {
+    primary: {
+        source: string;
+        event: string;
+    };
+    fallback?: {
+        source: string;
+        event: string;
+    };
+};
+export declare function eventReference(headers: Record<string, string>, payload: Json): {
+    source: string;
+    event: string;
+};

package/dist/src/webhook.js

@@ -0,0 +1,60 @@
+import crypto from 'node:crypto';
+const HMAC_HEADERS = ['x-webhook-signature', 'x-hub-signature-256', 'x-hub-signature'];
+const TOKEN_HEADERS = ['x-amalgm-webhook-secret', 'x-webhook-secret', 'x-gitlab-token'];
+function equal(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+export function normalizeHeaders(headers) {
+    return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
+}
+export function verifyEventSecret(secret, headers, body) {
+    const normalized = normalizeHeaders(headers);
+    for (const name of HMAC_HEADERS) {
+        const supplied = normalized[name];
+        if (!supplied)
+            continue;
+        const algorithm = supplied.startsWith('sha1=') ? 'sha1' : 'sha256';
+        const expected = `${algorithm}=${crypto.createHmac(algorithm, secret).update(body).digest('hex')}`;
+        return equal(supplied, expected);
+    }
+    const bearer = normalized.authorization?.match(/^Bearer\s+(.+)$/i)?.[1];
+    if (bearer && equal(bearer, secret))
+        return true;
+    for (const name of TOKEN_HEADERS) {
+        if (normalized[name] && equal(normalized[name], secret))
+            return true;
+    }
+    return false;
+}
+export function matchesEvent(trigger, source, event) {
+    return (trigger.source === '*' || trigger.source === source)
+        && (trigger.event === '*' || trigger.event === event);
+}
+export function eventReferences(headers, payload) {
+    const h = normalizeHeaders(headers);
+    // Source-label precedence is kernel law (@amalgm/core pickSourceLabel):
+    // github → stripe → linear → gitlab.
+    if (h['x-github-event'])
+        return { primary: { source: 'github', event: h['x-github-event'] } };
+    if (h['stripe-signature'])
+        return { primary: { source: 'stripe', event: 'webhook' } };
+    if (h['x-linear-event'])
+        return { primary: { source: 'linear', event: h['x-linear-event'] } };
+    if (h['x-gitlab-event'])
+        return { primary: { source: 'gitlab', event: h['x-gitlab-event'] } };
+    const object = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : {};
+    const declaredByHeader = h['x-amalgm-source'] || h['x-amalgm-event'];
+    const declaredByBody = typeof object.source === 'string' || typeof object.event === 'string';
+    const primary = {
+        source: h['x-amalgm-source'] || (typeof object.source === 'string' ? object.source : 'external'),
+        event: h['x-amalgm-event'] || (typeof object.event === 'string' ? object.event : 'webhook'),
+    };
+    return declaredByBody && !declaredByHeader
+        ? { primary, fallback: { source: 'external', event: 'webhook' } }
+        : { primary };
+}
+export function eventReference(headers, payload) {
+    return eventReferences(headers, payload).primary;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@amalgm/automations",
+  "version": "0.1.0",
+  "description": "Amalgm's automation product: Supabase-backed configuration plus the delivery rail (receipts, leases, retries).",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amalgm-inc/amalgm-automations.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "private": false,
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./cli": {
+      "types": "./dist/src/cli.d.ts",
+      "import": "./dist/src/cli.js"
+    },
+    "./mcp": {
+      "types": "./dist/src/mcp.d.ts",
+      "import": "./dist/src/mcp.js"
+    }
+  },
+  "bin": {
+    "amalgm-automations": "./dist/src/cli-main.js",
+    "amalgm-automations-mcp": "./dist/src/mcp-main.js"
+  },
+  "files": [
+    "dist",
+    "supabase",
+    "AXIOMS.md",
+    "PURPOSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "check": "tsx scripts/check-tree.ts && tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:supabase": "tsx --test test/integration/postgres.test.ts",
+    "verify": "npm run check && npm test && npm run build",
+    "release:check": "npm run verify && npm run test:supabase",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "cron-parser": "^5.4.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "@types/pg": "^8.20.1",
+    "pg": "^8.16.3",
+    "tsx": "^4.23.1",
+    "typescript": "^7.0.2"
+  }
+}