@engine9/schemas 1.9.0

package/source_code/ui.console.json5

@@ -0,0 +1,31 @@
+{
+  routes: {
+    '/person/:id/*': {
+      components: {
+        sidebar: {
+          items: [
+            {
+              component: 'Link',
+              properties: {
+                label: 'Timeline',
+                to: 'timeline'
+              }
+            }
+          ]
+        },
+        main: [
+          {
+            path: 'timeline',
+            label: 'Timeline',
+            component: 'RecordDisplay',
+            properties: {
+              table: 'timeline',
+              conditions: [{ eql: 'person_id={{person_id}}' }],
+              rows: ['{{email}}']
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/stacks/limited-pii/index.js

@@ -0,0 +1,8 @@
+import stack from './stack.json' with { type: 'json' };
+
+const metadata = { ...stack };
+const include = stack.include;
+const exclude = stack.exclude;
+
+export { metadata, include, exclude };
+export default { metadata };

package/stacks/limited-pii/stack.json

@@ -0,0 +1,22 @@
+{
+  "name": "@engine9/schemas/stacks/limited-pii",
+  "description": "PII-minimized Engine9 stack: hash identifiers instead of plaintext email, phone, or postal address. Excludes person_email, person_phone, and person_address even if requested.",
+  "version": "1.1.0",
+  "unique": true,
+  "include": [
+    "@engine9/schemas/plugin",
+    "@engine9/schemas/person",
+    "@engine9/schemas/person_remote",
+    "@engine9/schemas/segment",
+    "@engine9/schemas/timeline",
+    "@engine9/schemas/source_code",
+    "@engine9/schemas/transaction/core",
+    "@engine9/schemas/transaction/contact_details",
+    "@engine9/schemas/person_hash"
+  ],
+  "exclude": [
+    "@engine9/schemas/person_email",
+    "@engine9/schemas/person_phone",
+    "@engine9/schemas/person_address"
+  ]
+}

package/stacks/stacks.test.js

@@ -0,0 +1,27 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { metadata as standard } from './standard/index.js';
+import { metadata as limitedPii } from './limited-pii/index.js';
+
+test('standard stack includes plaintext contact plugins and does not exclude them', () => {
+  assert.equal(standard.name, '@engine9/schemas/stacks/standard');
+  assert.ok(standard.include.includes('@engine9/schemas/person_email'));
+  assert.ok(standard.include.includes('@engine9/schemas/person_phone'));
+  assert.ok(standard.include.includes('@engine9/schemas/person_address'));
+  assert.ok(standard.include.includes('@engine9/schemas/timeline'));
+  assert.ok(standard.include.includes('@engine9/schemas/source_code'));
+  assert.ok(standard.include.includes('@engine9/schemas/transaction/core'));
+  assert.ok(!standard.include.includes('@engine9/plugins/reports/people'));
+  assert.deepEqual(standard.exclude, []);
+});
+
+test('limited-pii stack includes person_hash and excludes plaintext contact plugins', () => {
+  assert.equal(limitedPii.name, '@engine9/schemas/stacks/limited-pii');
+  assert.ok(limitedPii.include.includes('@engine9/schemas/person_hash'));
+  assert.ok(!limitedPii.include.includes('@engine9/schemas/person_email'));
+  assert.ok(!limitedPii.include.includes('@engine9/schemas/person_phone'));
+  assert.ok(!limitedPii.include.includes('@engine9/schemas/person_address'));
+  assert.ok(limitedPii.exclude.includes('@engine9/schemas/person_email'));
+  assert.ok(limitedPii.exclude.includes('@engine9/schemas/person_phone'));
+  assert.ok(limitedPii.exclude.includes('@engine9/schemas/person_address'));
+});

package/stacks/standard/index.js

@@ -0,0 +1,7 @@
+import stack from './stack.json' with { type: 'json' };
+
+const metadata = { ...stack };
+const include = stack.include;
+
+export { metadata, include };
+export default { metadata };

package/stacks/standard/stack.json

@@ -0,0 +1,20 @@
+{
+  "name": "@engine9/schemas/stacks/standard",
+  "description": "Opt-in Engine9 schema stack: person, plaintext email, phone, and postal address, timeline, source codes, and transactions. Reports install separately.",
+  "version": "1.0.0",
+  "unique": true,
+  "include": [
+    "@engine9/schemas/plugin",
+    "@engine9/schemas/person",
+    "@engine9/schemas/person_remote",
+    "@engine9/schemas/segment",
+    "@engine9/schemas/person_email",
+    "@engine9/schemas/person_phone",
+    "@engine9/schemas/person_address",
+    "@engine9/schemas/timeline",
+    "@engine9/schemas/source_code",
+    "@engine9/schemas/transaction/core",
+    "@engine9/schemas/transaction/contact_details"
+  ],
+  "exclude": []
+}

package/tag/index.js

@@ -0,0 +1,13 @@
+import schema from './schema.js';
+const metadata = {
+  name: '@engine9/schemas/tag',
+  dependencies: {
+    '@engine9/schemas/person': '>=1.9.0'
+  }
+};
+export { metadata };
+export { schema };
+export default {
+  metadata,
+  schema
+};

package/tag/schema.js

@@ -0,0 +1,23 @@
+export const tables = [
+  {
+    name: 'tag',
+    columns: {
+      id: 'uuid',
+      table_name: 'string',
+      tag_category: 'string',
+      tag: 'string'
+    }
+  },
+  {
+    name: 'tag_row',
+    columns: {
+      id: 'id',
+      tag_id: 'foreign_uuid',
+      row_id: 'id',
+      modified_at: 'modified_at'
+    }
+  }
+];
+export default {
+  tables
+};

package/task/index.js

@@ -0,0 +1,13 @@
+import schema from './schema.js';
+
+const metadata = {
+  name: '@engine9/schemas/task',
+  schemas: ['schema.js']
+};
+
+export { metadata };
+export { schema };
+export default {
+  metadata,
+  schema
+};

package/task/schema.js

@@ -0,0 +1,54 @@
+export const tables = [
+  {
+    name: 'task_run',
+    columns: {
+      id: 'id_uuid',
+      account_id: 'string',
+      originator: { type: 'string', nullable: false, default_value: 'sql' },
+      flow_run_id: 'id_uuid',
+      task_key: 'string',
+      dynamic_key: { type: 'string', nullable: false, default_value: '0' },
+      name: 'string',
+      cache_key: 'string',
+      cache_expiration: 'datetime',
+      task_version: 'string',
+      empirical_policy: 'json',
+      tags: 'json',
+      labels: 'json',
+      state_id: 'id_uuid',
+      state_type: {
+        type: 'enum',
+        nullable: false,
+        default_value: 'PENDING',
+        values: ['PENDING', 'RUNNING', 'COMPLETED', 'FAILED', 'CANCELLED', 'CRASHED']
+      },
+      state_name: 'string',
+      state: 'json',
+      task_inputs: 'json',
+      run_count: 'int',
+      flow_run_run_count: 'int',
+      expected_start_time: 'datetime',
+      next_scheduled_start_time: 'datetime',
+      start_time: 'datetime',
+      end_time: 'datetime',
+      total_run_time: 'double',
+      estimated_run_time: 'double',
+      estimated_start_time_delta: 'double',
+      created_at: 'created_at',
+      modified_at: 'modified_at'
+    },
+    indexes: [
+      { columns: 'id', primary: true },
+      { columns: ['account_id'] },
+      { columns: ['originator'] },
+      { columns: ['flow_run_id'] },
+      { columns: ['state_type'] },
+      { columns: ['task_key'] },
+      { columns: ['created_at'] }
+    ]
+  }
+];
+
+export default {
+  tables
+};

package/task/ui.console.json5

@@ -0,0 +1,60 @@
+{
+  menu: {
+    'data-menu': {
+      title: 'Data',
+      icon: 'data',
+      type: 'collapse',
+      children: {
+        task: {
+          title: 'Tasks',
+          icon: 'forklift',
+          url: '/task'
+        }
+      }
+    }
+  },
+  routes: {
+    task: {
+      layout: 'full_width',
+      components: {
+        header: ['Tasks'],
+        main: [
+          {
+            component: 'RecordTable',
+            properties: {
+              table: 'task_run',
+              columns: [
+                { title: 'Id', dataIndex: 'id', sorter: true, width: '24%' },
+                { title: 'Created', dataIndex: 'created_at', sorter: true, width: '18%' },
+                { title: 'State', dataIndex: 'state_type', sorter: true, width: '14%' },
+                { title: 'Task Key', dataIndex: 'task_key', sorter: true, width: '22%' },
+                { title: 'Flow Run', dataIndex: 'flow_run_id', sorter: true, width: '22%' }
+              ],
+              onRecord: {
+                onClick: {
+                  action: 'navigate',
+                  url: '/task/{{record.id}}'
+                }
+              }
+            }
+          }
+        ]
+      }
+    },
+    'task/:id/*': {
+      layout: 'full_width',
+      components: {
+        main: [
+          {
+            component: 'RecordForm',
+            properties: {
+              table: 'task_run',
+              title: 'Task Run {{record.id}}',
+              readOnly: true
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/timeline/index.js

@@ -0,0 +1,18 @@
+import schema from './schema.js';
+import upsert from './transforms/inbound/upsert_tables.js';
+const metadata = {
+  name: '@engine9/schemas/timeline',
+  dependencies: {
+    '@engine9/schemas/person': '>=1.9.0'
+  }
+};
+export const transforms = {
+  upsert
+};
+export { metadata };
+export { schema };
+export default {
+  metadata,
+  schema,
+  transforms
+};

package/timeline/schema.js

@@ -0,0 +1,18 @@
+export const tables = [
+  {
+    name: 'timeline',
+    columns: {
+      id: 'id_uuid',
+      ts: 'datetime',
+      input_id: 'uuid', // keep as uuid because it's required
+      entry_type_id: 'int',
+      person_id: 'person_id',
+      source_code_id: 'source_code_id',
+      created_at: 'created_at'
+    },
+    indexes: [{ columns: 'id', primary: true }, { columns: 'ts' }, { columns: 'person_id' }, { columns: 'input_id' }]
+  }
+];
+export default {
+  tables
+};

package/timeline/transforms/inbound/upsert_tables.js

@@ -0,0 +1,22 @@
+export const bindings = {
+  tablesToUpsert: { path: 'sql.tables.upsert' }
+};
+export async function transform({ batch, tablesToUpsert }) {
+  tablesToUpsert.timeline = tablesToUpsert.timeline || [];
+  batch.forEach((o) => {
+    if (o.timeline_id) {
+      tablesToUpsert.timeline.push({
+        id: o.timeline_id,
+        ts: o.ts || new Date(),
+        input_id: o.input_id,
+        entry_type_id: o.entry_type_id,
+        person_id: o.person_id,
+        source_code_id: o.source_code_id
+      });
+    }
+  });
+}
+export default {
+  bindings,
+  transform
+};

package/timeline/ui.console.json5

@@ -0,0 +1,31 @@
+{
+  routes: {
+    '/person/:id/*': {
+      components: {
+        sidebar: {
+          items: [
+            {
+              component: 'Link',
+              properties: {
+                label: 'Timeline',
+                to: 'timeline'
+              }
+            }
+          ]
+        },
+        main: [
+          {
+            path: 'timeline',
+            label: 'Timeline',
+            component: 'RecordDisplay',
+            properties: {
+              table: 'timeline',
+              conditions: [{ eql: 'person_id={{person_id}}' }],
+              rows: ['{{email}}']
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/transaction/contact_details/index.js

@@ -0,0 +1,11 @@
+import schema from './schema.js';
+
+const metadata = {
+  name: '@engine9/schemas/transaction/contact_details',
+  dependencies: {
+    '@engine9/schemas/transaction/core': '>=1.9.0'
+  }
+};
+
+export { metadata, schema };
+export default { metadata, schema };

package/transaction/contact_details/schema.js

@@ -0,0 +1,22 @@
+// Contact details captured on a transaction: address, email, phone, employer, and occupation.
+export const tables = [
+  {
+    name: 'transaction',
+    prefix: false,
+    columns: {
+      street_1: 'string',
+      street_2: 'string',
+      city: 'string',
+      region: 'string',
+      postal_code: { type: 'string', length: 16 },
+      country: 'string',
+      email: 'string',
+      phone: { type: 'string', length: 24 },
+      employer: 'string',
+      occupation: 'string'
+    },
+    indexes: []
+  }
+];
+
+export default { tables };

package/transaction/core/README.md

@@ -0,0 +1,79 @@
+# Transaction Core Schema Plugin
+
+The `@engine9/schemas/transaction/core` plugin stores payment and gift transactions for people and provides the common transaction search, metrics, and segment used by imports, reports, and exports.
+
+It depends on `@engine9/schemas/person` because every transaction belongs to a person through `person_id`.
+
+## Data Model
+
+The plugin creates the `transaction` table. Each row is a dated amount tied to a person, an input, and optional source-code / message attribution.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `id_uuid` | Primary row identifier. |
+| `ts` | `datetime` | When the transaction occurred. |
+| `input_id` | `uuid` | Input that produced the row. Required. |
+| `entry_type_id` | `int` | Timeline entry type for the transaction. |
+| `person_id` | `person_id` | Person the transaction is assigned to. |
+| `amount` | `currency` | Transaction amount. |
+| `remote_entry_id` | `string` | Remote system transaction id when available. |
+| `remote_page_name` | `string` | Remote page or form name when available. |
+| `remote_recurring_id` | `string` | Remote recurring-series id when available. |
+| `recurs_id` | `int` | Recurring frequency. `0` is one-time. Defaults to `0`. |
+| `recurring_number` | `int` | Sequence number in a recurring series. |
+| `refund_amount` | `currency` | Refunded amount when applicable. |
+| `given_name` / `family_name` / `email` | `string` | Snapshot of payer identity on the transaction. |
+| `source_code_id` | `source_code_id` | Source code captured on the transaction. |
+| `override_source_code_id` | `source_code_id` | Manual source-code override. |
+| `final_source_code_id` | `source_code_id` | Source code after attribution. |
+| `recommended_message_id` | `uuid` | Message suggested by last-click attribution. |
+| `override_message_id` | `uuid` | Manual message override. |
+| `final_message_id` | `uuid` | Message after attribution. |
+| `extra` | `json` | Additional payload from the source system. |
+| `created_at` | `created_at` | Timestamp when the row was created. |
+| `modified_at` | `modified_at` | Timestamp when the row was last modified. |
+
+Indexes:
+
+- primary `id`
+- `ts`
+- `person_id`
+- `remote_entry_id`
+- `modified_at`
+
+## Inbound Behavior
+
+The inbound `upsert` transform writes rows to `transaction`.
+
+- Each row gets an `id` from the timeline-entry UUID helper and an `entry_type_id` from the entry type.
+- When recurring fields are present, `recurs_id` is derived from `recurs` (`daily` through `annually`) or from `recurring_number` when no frequency is set.
+
+## Outbound Behavior
+
+`appendTransactionSummary` looks up a person's transactions and attaches summary fields such as count, revenue, first/last/smallest/largest gifts, and recurring totals.
+
+## Search
+
+- `all` finds people who have any transaction, optionally filtered by `plugin_id` and a `start` / `end` window on `ts` (ISO datetimes or relative expressions such as `-30d`).
+- `minimum` finds people who have a transaction of at least a given `amount`.
+
+## Metrics
+
+`summaryByDate` is a monthly card: record count and summed `amount` grouped by month of `ts`.
+
+## Segments
+
+Predefined audiences shipped with this schema plugin. On install, each key becomes a `segment` row whose definition path is `@engine9/schemas/transaction/core:segments:<key>`.
+
+### Customers
+
+| | |
+| --- | --- |
+| **Key** | `customers` |
+| **Definition path** | `@engine9/schemas/transaction/core:segments:customers` |
+| **Who is included** | People who have at least one row in `transaction` |
+| **Who is excluded** | People with no transactions |
+| **How it is built** | A `transaction` table search that selects `person_id` with no extra filters |
+| **Universe** | None — any transaction from any plugin, date, or amount counts |
+
+Refunds, recurring gifts, and $0 rows are not filtered out. If a person has ever appeared on a transaction row, they are a customer.