@ossy/platform 3.1.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -45,16 +45,16 @@
     "@aws-sdk/util-format-url": "^3.972.17",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@ossy/config": "^3.0.9",
-    "@ossy/event-store": "^3.0.9",
+    "@ossy/event-store": "^3.2.0",
     "@ossy/locale": "^3.0.9",
     "@ossy/manifest": "^3.0.9",
     "@ossy/observability": "^3.0.9",
     "@ossy/policies": "^3.0.9",
     "@ossy/schema": "^3.0.9",
-    "@ossy/sdk": "^3.0.9",
+    "@ossy/sdk": "^3.3.0",
     "@ossy/tokens": "^3.0.9",
-    "@ossy/users": "^3.0.9",
-    "@ossy/workspaces": "^3.1.0",
+    "@ossy/users": "^3.2.0",
+    "@ossy/workspaces": "^3.2.0",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -74,5 +74,5 @@
     "src",
     "Dockerfile"
   ],
-  "gitHead": "9b146fb6fd9769f800863806c5bd16016508b218"
+  "gitHead": "19e8bae4c1e9df79270218f28c0c9391f4f9871c"
 }

package/src/tasks/task-service.js

@@ -99,10 +99,19 @@ export class TaskService {
 
     const audit = context.audit !== false && task.metadata.audit !== false
 
+    // GET/API handlers often omit integrations; default like dispatch/scheduler so
+    // tasks can always use integrations.get('email') (including local delivery).
+    const invokeContext = {
+      ...context,
+      sdk: context.sdk ?? TaskService._sdk,
+      integrations: context.integrations ?? IntegrationService,
+      log: context.log ?? createLogger(id),
+    }
+
     return TaskRunService.execute({
       taskId: id,
       handler: task.handler,
-      context,
+      context: invokeContext,
       trigger: 'invoke',
       triggeredBy: {
         channel: context.req ? undefined : 'api',

package/src/test/flow-click.js

@@ -0,0 +1,43 @@
+/**
+ * Normalize a declarative flow `click` step into a Playwright locator click.
+ * Prefer `{ action }` for `data-action` controls; use `click` for structural hooks
+ * (e.g. overlay backdrop) that are not action POJOs.
+ *
+ * @param {unknown} click
+ * @returns {{ selector: string, position?: { x: number, y: number } }}
+ */
+export function resolveClickTarget (click) {
+  if (typeof click === 'string') {
+    const selector = click.trim()
+    if (!selector) {
+      throw new Error('click step requires a non-empty CSS selector')
+    }
+    return { selector }
+  }
+
+  if (click != null && typeof click === 'object' && !Array.isArray(click)) {
+    const selector = typeof click.selector === 'string' ? click.selector.trim() : ''
+    if (!selector) {
+      throw new Error('click step requires a non-empty CSS selector')
+    }
+
+    const out = { selector }
+    if (click.position != null) {
+      if (
+        typeof click.position !== 'object'
+        || Array.isArray(click.position)
+        || !Number.isFinite(Number(click.position.x))
+        || !Number.isFinite(Number(click.position.y))
+      ) {
+        throw new Error('click.position requires { x, y } with finite numbers')
+      }
+      out.position = {
+        x: Number(click.position.x),
+        y: Number(click.position.y),
+      }
+    }
+    return out
+  }
+
+  throw new Error('click step requires a non-empty CSS selector')
+}

package/src/test/flow-click.spec.js

@@ -0,0 +1,42 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveClickTarget } from './flow-click.js'
+
+describe('resolveClickTarget', () => {
+  it('accepts a bare selector string', () => {
+    expect(resolveClickTarget('[data-overlay]')).toEqual({
+      selector: '[data-overlay]',
+    })
+  })
+
+  it('accepts { selector } and trims whitespace', () => {
+    expect(resolveClickTarget({ selector: ' [data-ossy-mobile-shell-nav-overlay] ' })).toEqual({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+    })
+  })
+
+  it('accepts optional { position: { x, y } }', () => {
+    expect(resolveClickTarget({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+      position: { x: 360, y: 200 },
+    })).toEqual({
+      selector: '[data-ossy-mobile-shell-nav-overlay]',
+      position: { x: 360, y: 200 },
+    })
+  })
+
+  it('rejects empty or invalid values', () => {
+    expect(() => resolveClickTarget('')).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget('   ')).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget(null)).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget({ selector: '' })).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget([])).toThrow(/non-empty CSS selector/)
+    expect(() => resolveClickTarget({
+      selector: '[data-overlay]',
+      position: { x: 'left' },
+    })).toThrow(/position requires/)
+    expect(() => resolveClickTarget({
+      selector: '[data-overlay]',
+      position: 10,
+    })).toThrow(/position requires/)
+  })
+})

package/src/test/flow-context.js

@@ -0,0 +1,44 @@
+/**
+ * Flow-run context helpers — `$email`-style placeholders for declarative steps.
+ */
+
+/**
+ * Escape a value for use inside a double-quoted CSS attribute selector.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeCssAttrValue (value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+/**
+ * Resolve a whole-string `$token` placeholder from the run context.
+ * Non-strings and strings that do not start with `$` are returned as-is.
+ *
+ * @param {unknown} value
+ * @param {{ fields?: Record<string, unknown>, [key: string]: unknown }} context
+ */
+export function resolveContextValue (value, context) {
+  if (typeof value !== 'string' || !value.startsWith('$')) return value
+  const key = value.slice(1)
+  return context[key] ?? context.fields?.[key]
+}
+
+/**
+ * Replace `$token` placeholders embedded in a string (e.g. selectors).
+ * Unknown tokens are left unchanged.
+ *
+ * @param {unknown} template
+ * @param {{ fields?: Record<string, unknown>, [key: string]: unknown }} context
+ * @param {{ escape?: (value: unknown) => string }} [options]
+ * @returns {unknown}
+ */
+export function interpolateContextString (template, context, options = {}) {
+  if (typeof template !== 'string' || !template.includes('$')) return template
+  const escape = typeof options.escape === 'function' ? options.escape : (value) => String(value)
+  return template.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, key) => {
+    const value = context[key] ?? context.fields?.[key]
+    if (value == null) return match
+    return escape(value)
+  })
+}

package/src/test/flow-context.spec.js

@@ -0,0 +1,44 @@
+import { describe, expect, it } from '@jest/globals'
+import {
+  escapeCssAttrValue,
+  interpolateContextString,
+  resolveContextValue,
+} from './flow-context.js'
+
+describe('flow-context', () => {
+  const context = {
+    email: 'new@example.com',
+    fields: { firstName: 'Ada', email: 'field@example.com' },
+  }
+
+  it('resolves whole-string $placeholders from context then fields', () => {
+    expect(resolveContextValue('$email', context)).toBe('new@example.com')
+    expect(resolveContextValue('$firstName', context)).toBe('Ada')
+    expect(resolveContextValue('literal', context)).toBe('literal')
+    expect(resolveContextValue('$missing', context)).toBeUndefined()
+  })
+
+  it('interpolates embedded $placeholders in selectors', () => {
+    expect(
+      interpolateContextString('[data-user-email="$email"]', context),
+    ).toBe('[data-user-email="new@example.com"]')
+  })
+
+  it('escapes quotes and backslashes when an escape fn is provided', () => {
+    const tricky = {
+      email: 'a"b\\c@example.com',
+      fields: {},
+    }
+    expect(
+      interpolateContextString('[data-user-email="$email"]', tricky, {
+        escape: escapeCssAttrValue,
+      }),
+    ).toBe('[data-user-email="a\\"b\\\\c@example.com"]')
+  })
+
+  it('leaves unknown embedded tokens unchanged', () => {
+    expect(
+      interpolateContextString('[data-x="$missing"]', context),
+    ).toBe('[data-x="$missing"]')
+  })
+})

package/src/test/flow-press.js

@@ -0,0 +1,25 @@
+/**
+ * Normalize a declarative flow `press` step into a Playwright keyboard key.
+ *
+ * @param {unknown} press
+ * @returns {string}
+ */
+export function resolvePressKey (press) {
+  if (typeof press === 'string') {
+    const key = press.trim()
+    if (!key) {
+      throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+    }
+    return key
+  }
+
+  if (press != null && typeof press === 'object' && !Array.isArray(press)) {
+    const key = typeof press.key === 'string' ? press.key.trim() : ''
+    if (!key) {
+      throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+    }
+    return key
+  }
+
+  throw new Error('press step requires a non-empty key string (e.g. "Escape")')
+}

package/src/test/flow-press.spec.js

@@ -0,0 +1,25 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolvePressKey } from './flow-press.js'
+
+describe('resolvePressKey', () => {
+  it('accepts a bare key string', () => {
+    expect(resolvePressKey('Escape')).toBe('Escape')
+    expect(resolvePressKey('Enter')).toBe('Enter')
+    expect(resolvePressKey('Tab')).toBe('Tab')
+    expect(resolvePressKey('Shift+Tab')).toBe('Shift+Tab')
+  })
+
+  it('accepts { key } and trims whitespace', () => {
+    expect(resolvePressKey({ key: ' Escape ' })).toBe('Escape')
+    expect(resolvePressKey({ key: ' Shift+Tab ' })).toBe('Shift+Tab')
+  })
+
+  it('rejects empty or invalid values', () => {
+    expect(() => resolvePressKey('')).toThrow(/non-empty key/)
+    expect(() => resolvePressKey('   ')).toThrow(/non-empty key/)
+    expect(() => resolvePressKey(null)).toThrow(/non-empty key/)
+    expect(() => resolvePressKey({ key: '' })).toThrow(/non-empty key/)
+    expect(() => resolvePressKey({ key: 27 })).toThrow(/non-empty key/)
+    expect(() => resolvePressKey([])).toThrow(/non-empty key/)
+  })
+})

package/src/test/flow-runner.js

@@ -14,6 +14,23 @@ import { faker } from '@faker-js/faker'
 import { Router } from '@ossy/router'
 import { Schema } from '@ossy/schema'
 import { test, expect } from '@playwright/test'
+import {
+  escapeCssAttrValue,
+  interpolateContextString,
+  resolveContextValue,
+} from './flow-context.js'
+import { resolveClickTarget } from './flow-click.js'
+import { resolvePressKey } from './flow-press.js'
+import { resolveViewportSize } from './flow-viewport.js'
+
+export {
+  escapeCssAttrValue,
+  interpolateContextString,
+  resolveContextValue,
+} from './flow-context.js'
+export { resolveClickTarget } from './flow-click.js'
+export { resolvePressKey } from './flow-press.js'
+export { resolveViewportSize } from './flow-viewport.js'
 
 const FLOW_PATTERN = /\.flow\.(mjs|cjs|js)$/
 
@@ -110,13 +127,6 @@ function resolveActionService (action, fallback) {
   return fallback
 }
 
-/** Resolve `$token`-style placeholders from the run context. */
-function resolveContextValue (value, context) {
-  if (typeof value !== 'string' || !value.startsWith('$')) return value
-  const key = value.slice(1)
-  return context[key] ?? context.fields?.[key]
-}
-
 function resolveContextObject (obj, context) {
   if (!obj || typeof obj !== 'object') return obj
   const out = {}
@@ -197,6 +207,31 @@ export async function runFlow (flow, options = {}) {
       continue
     }
 
+    if (step.viewport != null) {
+      if (!page) throw new Error('viewport step requires a Playwright page')
+      await page.setViewportSize(resolveViewportSize(step.viewport))
+      continue
+    }
+
+    if (step.press != null) {
+      if (!page) throw new Error('press step requires a Playwright page')
+      await page.keyboard.press(resolvePressKey(step.press))
+      continue
+    }
+
+    if (step.click != null) {
+      if (!page) throw new Error('click step requires a Playwright page')
+      const { selector, position } = resolveClickTarget(step.click)
+      const resolvedSelector = interpolateContextString(selector, context, {
+        escape: escapeCssAttrValue,
+      })
+      const locator = page.locator(resolvedSelector).first()
+      const clickTimeout = step.timeout ?? 15000
+      await locator.waitFor({ state: 'visible', timeout: clickTimeout })
+      await locator.click(position ? { position } : undefined)
+      continue
+    }
+
     if (step.form) {
       if (!page) throw new Error('form step requires a Playwright page')
       const formMeta = step.form
@@ -305,16 +340,37 @@ export async function runFlow (flow, options = {}) {
 
     if (step.result) {
       if (!page) throw new Error('result step requires a Playwright page')
-      const { text, url, page: pageRef, action, selector, timeout = 8000 } = step.result
+      const {
+        text,
+        url,
+        page: pageRef,
+        action,
+        selector,
+        hidden = false,
+        timeout = 8000,
+      } = step.result
+      const assertLocator = async (locator) => {
+        if (hidden) {
+          await expectFn(locator).toBeHidden({ timeout })
+          return
+        }
+        await expectFn(locator).toBeVisible({ timeout })
+      }
       if (action != null) {
         const actionId = resolveActionId(action)
         const service = resolveActionService(action, step.result.service)
-        await expectFn(page.locator(actionSelector(actionId, service)).first()).toBeVisible({ timeout })
+        await assertLocator(page.locator(actionSelector(actionId, service)).first())
       }
       if (selector != null) {
-        await expectFn(page.locator(selector).first()).toBeVisible({ timeout })
+        const resolvedSelector = interpolateContextString(selector, context, {
+          escape: escapeCssAttrValue,
+        })
+        await assertLocator(page.locator(resolvedSelector).first())
       }
       if (text != null) {
+        if (hidden) {
+          throw new Error('result.text cannot use hidden: true — assert via action or selector')
+        }
         const pattern = text instanceof RegExp ? text : new RegExp(text, 'i')
         await expectFn(page.getByText(pattern).first()).toBeVisible({ timeout })
       }

package/src/test/flow-viewport.js

@@ -0,0 +1,23 @@
+/**
+ * Normalize a declarative flow `viewport` step into Playwright setViewportSize input.
+ *
+ * @param {unknown} viewport
+ * @returns {{ width: number, height: number }}
+ */
+export function resolveViewportSize (viewport) {
+  if (viewport == null || typeof viewport !== 'object' || Array.isArray(viewport)) {
+    throw new Error('viewport step requires { width, height } with positive numbers')
+  }
+
+  const width = Number(viewport.width)
+  const height = Number(viewport.height)
+
+  if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+    throw new Error('viewport step requires { width, height } with positive numbers')
+  }
+
+  return {
+    width: Math.round(width),
+    height: Math.round(height),
+  }
+}

package/src/test/flow-viewport.spec.js

@@ -0,0 +1,26 @@
+import { describe, expect, it } from '@jest/globals'
+import { resolveViewportSize } from './flow-viewport.js'
+
+describe('resolveViewportSize', () => {
+  it('accepts positive width/height', () => {
+    expect(resolveViewportSize({ width: 390, height: 844 })).toEqual({
+      width: 390,
+      height: 844,
+    })
+  })
+
+  it('rounds fractional dimensions', () => {
+    expect(resolveViewportSize({ width: 389.6, height: 843.2 })).toEqual({
+      width: 390,
+      height: 843,
+    })
+  })
+
+  it('rejects missing or non-positive sizes', () => {
+    expect(() => resolveViewportSize(null)).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: 390 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: 0, height: 844 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize({ width: -1, height: 844 })).toThrow(/width, height/)
+    expect(() => resolveViewportSize('mobile')).toThrow(/width, height/)
+  })
+})

package/src/test/test.util.js

@@ -173,6 +173,30 @@ export class TestUtil {
     return ev.payload.token
   }
 
+  static async getLatestEmailChangeJwtForSubject(subjectId) {
+    const ev = await EventStore.Collection.findOne(
+      {
+        type: TOKEN_SCHEMA,
+        event: 'Created',
+        'payload.type': 'EmailChange',
+        'payload.subject': subjectId,
+      },
+      { sort: { created: -1 } },
+    )
+    if (!ev?.payload?.token) {
+      return Promise.reject(new Error('No EmailChange token found for subject'))
+    }
+    return ev.payload.token
+  }
+
+  static countEmailChangeTokenEvents() {
+    return EventStore.Collection.countDocuments({
+      type: TOKEN_SCHEMA,
+      event: 'Created',
+      'payload.type': 'EmailChange',
+    })
+  }
+
   static GetVerificationToken() {
     const email = `${casual.email}`
 
@@ -192,7 +216,7 @@ export class TestUtil {
 
     await TestUtil.AssertActionResponse({
       actionId: '@ossy/authentication/actions/sign-up',
-      body: TestUtil.signUpBody({ email }),
+      payload: { email, firstName: 'Test', lastName: 'User' },
       expectedResponseStatus: 200,
       expectedResponseBody: { ok: true },
     })