@ossy/platform 1.39.0 → 1.39.2

package/README.md

@@ -14,7 +14,7 @@ At startup `@ossy/platform`:
 6. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
 7. Registers all **actions** (`*.action.js`) with `ActionService`.
 8. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
-9. Auto-mounts every action at `POST /actions/:id`.
+9. Auto-mounts every action at `POST /actions` (`{ action, payload }`).
 
 ## Quick start
 
@@ -117,7 +117,7 @@ The platform is built around file conventions called **primitives**. Each primit
 | Page | `*.page.jsx` | Routable UI (SSR + hydration) |
 | API | `*.api.js` | HTTP endpoint (any method) |
 | Task | `*.task.js` | Event-driven or scheduled async work |
-| Action | `*.action.js` | Named command, auto-exposed at `POST /actions/:id` |
+| Action | `*.action.js` | Named intent, auto-exposed at `POST /actions` |
 | Integration | `*.integration.js` | Third-party client connected at startup |
 | Email | `*.email.jsx` | Transactional React email template |
 | Component | `*.component.jsx` | Injectable UI fragment |
@@ -130,7 +130,7 @@ The platform is built around file conventions called **primitives**. Each primit
 ```
 Incoming request
   │
-  ├─ POST /actions/:id  ──► ActionService.invoke() ──► action.run({ payload, sdk, log, integrations, req })
+  ├─ POST /actions  ──► ActionService.invoke() ──► TaskService.invoke() ──► task.run({ payload, sdk, log, integrations, req })
   │
   ├─ Match API route    ──► api.handle(req, res)
   │

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "1.39.0",
+  "version": "1.39.2",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -40,13 +40,13 @@
     "@aws-sdk/s3-request-presigner": "^3.1057.0",
     "@aws-sdk/util-create-request": "^3.972.26",
     "@aws-sdk/util-format-url": "^3.972.17",
-    "@ossy/event-store": "^1.8.0",
-    "@ossy/locale": "^1.40.0",
-    "@ossy/observability": "^1.8.0",
-    "@ossy/policies": "^1.13.0",
-    "@ossy/sdk": "^1.40.0",
-    "@ossy/tokens": "^1.13.0",
-    "@ossy/users": "^1.13.0",
+    "@ossy/event-store": "^1.8.2",
+    "@ossy/locale": "^1.40.2",
+    "@ossy/observability": "^1.8.2",
+    "@ossy/policies": "^1.13.2",
+    "@ossy/sdk": "^1.40.2",
+    "@ossy/tokens": "^1.13.2",
+    "@ossy/users": "^1.13.2",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -64,5 +64,5 @@
     "src",
     "Dockerfile"
   ],
-  "gitHead": "d9d31182be64a448d575da432af2830d909ad4b9"
+  "gitHead": "2b8745d57fee8b6c08787e2755b4df489291a5cd"
 }

package/src/actions/action.service.js

@@ -1,65 +1,55 @@
 import { createLogger } from '@ossy/observability'
+import { TaskService } from '../tasks/task-service.js'
 
 const log = createLogger('platform/actions')
 
-/** @type {Map<string, { id: string, access: string, run: Function }>} */
+/** @type {Map<string, { id: string, access: string }>} */
 const _actions = new Map()
 
 /**
- * Registry and invoker for `*.action.js` command handlers.
+ * Registry for action intent (`*.action.js` metadata only).
  *
- * Actions are named, discoverable functions exposed at `POST /actions/:id`.
- * Each action exports:
- *   - `id`     {string}   — unique slug, e.g. `'authentication/request-sign-in'`
- *   - `access` {string}   — `'public'` | `'authenticated'` | `'workspace'` (default `'authenticated'`)
- *   - `run`    {Function} — async handler receiving `{ payload, sdk, log, integrations, req }`
+ * Actions name what callers want: `{ id, access }`. Implementation lives in
+ * a task with the same id — see `TaskService.invoke`.
  */
 export const ActionService = {
   /**
-   * Register an action module (as imported from a bundled entry).
-   * Validates that `id` is a non-empty string and `run` is a function.
+   * Register action intent from a bundled `*.action.js` module.
    *
-   * @param {{ id: string, access?: string, run: Function }} mod
+   * @param {{ metadata: { id: string, access?: string } }} mod
    */
   register (mod) {
-    const { id, run, access = 'authenticated' } = mod ?? {}
+    const { id, access = 'authenticated' } = mod?.metadata ?? {}
 
     if (typeof id !== 'string' || id.trim() === '') {
-      throw new Error(`[ActionService] Action module must export a non-empty string "id" (got ${JSON.stringify(id)})`)
-    }
-    if (typeof run !== 'function') {
-      throw new Error(`[ActionService] Action "${id}" must export a "run" function`)
+      throw new Error(`[ActionService] Action module must export a non-empty string "metadata.id" (got ${JSON.stringify(id)})`)
     }
 
     if (_actions.has(id)) {
       log.warn(`[ActionService] Action "${id}" already registered — overwriting`)
     }
 
-    _actions.set(id, { id, access, run })
+    _actions.set(id, { id, access })
     log.info(`[ActionService] Registered action "${id}" (access: ${access})`)
   },
 
   /**
-   * Look up a registered action by id. Returns `null` when not found.
-   *
    * @param {string} id
-   * @returns {{ id: string, access: string, run: Function } | null}
+   * @returns {{ id: string, access: string } | null}
    */
   get (id) {
     return _actions.get(id) ?? null
   },
 
   /**
-   * Returns all registered actions.
-   *
-   * @returns {{ id: string, access: string, run: Function }[]}
+   * @returns {{ id: string, access: string }[]}
    */
   all () {
     return [..._actions.values()]
   },
 
   /**
-   * Invoke an action by id, forwarding the provided context.
+   * Invoke an action by id — enforces registration, delegates execution to TaskService.
    *
    * @param {string} id
    * @param {{ payload?: unknown, sdk?: unknown, log?: unknown, integrations?: unknown, req?: unknown }} context
@@ -68,6 +58,6 @@ export const ActionService = {
   async invoke (id, context = {}) {
     const action = _actions.get(id)
     if (!action) throw new Error(`[ActionService] Action not found: "${id}"`)
-    return action.run(context)
+    return TaskService.invoke(id, context)
   },
 }

package/src/server.js

@@ -6,8 +6,8 @@ import morgan from 'morgan'
 import { Router as OssyRouter } from '@ossy/router'
 import cookieParser from 'cookie-parser'
 import { ProxyInternal } from './proxy-internal.js'
-import { SDK } from '@ossy/sdk'
-import { AggregateRebuild } from '@ossy/event-store'
+import { SDK, resolveActionId } from '@ossy/sdk'
+import { AggregateRebuild, resolveMongoUrl } from '@ossy/event-store'
 import { TaskService } from './tasks/task-service.js'
 import { ChangeStream } from './tasks/change-stream.js'
 import { CONTENT_SLOT_NAME } from '@ossy/app/runtime/resolve-shell-slots'
@@ -224,7 +224,7 @@ export async function startServer (options = {}) {
   TaskService.startScheduler()
 
   if (process.env.DB_URL) {
-    ChangeStream.start(process.env.DB_URL)
+    ChangeStream.start(resolveMongoUrl(process.env.DB_URL))
   }
 
   const pageRouter = OssyRouter.of({
@@ -261,10 +261,11 @@ export async function startServer (options = {}) {
   if (fs.existsSync(publicDir)) app.use(express.static(publicDir))
   app.use(ProxyInternal())
 
-  // Actions endpoint — auto-exposes every registered `*.action.js` handler.
-  // Access rules are enforced here; business logic lives in the action's `run`.
-  app.post('/actions/:id', async (req, res) => {
-    const actionId = req.params.id
+  // Actions endpoint — POST /actions with body { action, payload }.
+  app.post('/actions', async (req, res) => {
+    const actionId = resolveActionId(req.body?.action)
+    if (!actionId) return res.status(400).json({ error: 'Missing action' })
+
     const action = ActionService.get(actionId)
     if (!action) return res.status(404).json({ error: 'Action not found' })
 
@@ -275,10 +276,11 @@ export async function startServer (options = {}) {
       return res.status(403).json({ error: 'Forbidden' })
     }
 
+    const payload = req.body?.payload ?? {}
     const actionLog = createLogger(actionId)
     try {
       const result = await ActionService.invoke(actionId, {
-        payload: req.body,
+        payload,
         sdk: req.sdk ?? null,
         log: actionLog,
         integrations: IntegrationService,
@@ -287,7 +289,8 @@ export async function startServer (options = {}) {
       res.json(result ?? { ok: true })
     } catch (err) {
       actionLog.error('Action failed', { id: actionId }, err)
-      res.status(500).json({ error: err && err.message ? err.message : 'Internal error' })
+      const status = err?.status ?? 500
+      res.status(status).json({ error: err?.message ?? 'Internal error' })
     }
   })
 

package/src/site-loader.js

@@ -54,7 +54,7 @@ async function collectFiles (sdk, location) {
 
   while (queue.length > 0) {
     const { location: loc, prefix } = queue.shift()
-    const resources = await sdk.makeRequest(ResourcesList)({
+    const resources = await sdk.invoke(ResourcesList, {
       search: new URLSearchParams({ location: loc }).toString(),
     })
 

package/src/tasks/change-stream.js

@@ -1,5 +1,6 @@
 import { TaskService } from './task-service.js'
 import { createLogger } from '@ossy/observability'
+import { resolveMongoUrl } from '@ossy/event-store'
 
 const log = createLogger('platform')
 
@@ -25,7 +26,7 @@ export class ChangeStream {
   static start(dbUrl) {
     ChangeStream._stopped = false
     ChangeStream._reconnectAttempts = 0
-    ChangeStream._dbUrl = dbUrl
+    ChangeStream._dbUrl = resolveMongoUrl(dbUrl)
     ChangeStream._open().catch((error) => {
       log.error('[ChangeStream] Change stream could not be opened', undefined, error)
       ChangeStream._scheduleReconnect()

package/src/tasks/task-service.js

@@ -13,6 +13,9 @@ export class TaskService {
   /** @type {Array<{ metadata: object, handler: function }>} */
   static _tasks = []
 
+  /** @type {Map<string, { metadata: object, handler: function }>} */
+  static _tasksById = new Map()
+
   /** @type {ReturnType<typeof setInterval> | null} */
   static _schedulerInterval = null
 
@@ -51,13 +54,41 @@ export class TaskService {
       return
     }
 
-    TaskService._tasks.push({ metadata, handler })
+    const entry = { metadata, handler }
+    TaskService._tasks.push(entry)
+    if (TaskService._tasksById.has(metadata.id)) {
+      _serviceLog.warn(`Task "${metadata.id}" already registered — overwriting`)
+    }
+    TaskService._tasksById.set(metadata.id, entry)
     _serviceLog.info(
       `Registered task "${metadata.id}" with ${metadata.triggers?.length ?? 0} trigger(s)` +
       (metadata.schedule ? ` and schedule "${metadata.schedule}"` : ''),
     )
   }
 
+  /**
+   * Look up a registered task by id.
+   *
+   * @param {string} id
+   * @returns {{ metadata: object, handler: function } | null}
+   */
+  static get(id) {
+    return TaskService._tasksById.get(id) ?? null
+  }
+
+  /**
+   * Synchronously invoke a task by id (HTTP / sdk.invoke path).
+   *
+   * @param {string} id
+   * @param {{ payload?: unknown, sdk?: unknown, log?: unknown, integrations?: unknown, req?: unknown }} context
+   * @returns {Promise<unknown>}
+   */
+  static async invoke(id, context = {}) {
+    const task = TaskService._tasksById.get(id)
+    if (!task) throw new Error(`[TaskService] Task not found: "${id}"`)
+    return task.handler(context)
+  }
+
   /**
    * Dispatches a single event (fullDocument from the changestream) to all
    * registered tasks whose triggers match.

package/src/test/e2e.util.js

@@ -3,6 +3,7 @@ import { MongoClient } from 'mongodb'
 const DB_URL = process.env.DB_URL ?? 'mongodb://localhost:27017/'
 const DB_NAME = process.env.DB_NAME ?? 'ossy-local'
 export const API_URL = process.env.OSSY_API_URL ?? process.env.API_URL ?? 'http://localhost:3001/api/v0'
+export const ACTIONS_URL = API_URL.replace(/\/api\/v0\/?$/, '')
 export const APP_URL = process.env.OSSY_APP_URL ?? process.env.BASE_URL ?? 'http://localhost:3002'
 
 /**
@@ -80,10 +81,10 @@ export async function signUpAndGetToken(firstName = 'Test', lastName = 'User') {
     await client.connect()
     const db = client.db(DB_NAME)
 
-    const res = await fetch(`${API_URL}/users/sign-up`, {
+    const res = await fetch(`${ACTIONS_URL}/actions`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ email, firstName, lastName }),
+      body: JSON.stringify({ action: 'authentication/sign-up', payload: { email, firstName, lastName } }),
     })
     if (!res.ok) throw new Error(`Sign-up failed with status ${res.status}`)
 

package/src/test/test.util.js

@@ -23,7 +23,13 @@ export function getApiTestBaseUrl() {
   return process.env.API_TEST_BASE_URL ?? 'http://localhost:3000/api/v0'
 }
 
+/** Server root for `POST /actions` (strips `/api/v0` suffix). */
+export function getActionsTestBaseUrl() {
+  return getApiTestBaseUrl().replace(/\/api\/v0\/?$/, '')
+}
+
 const baseUrl = /* lazy */ () => getApiTestBaseUrl()
+const actionsBaseUrl = /* lazy */ () => getActionsTestBaseUrl()
 
 export class TestUtil {
 
@@ -32,6 +38,44 @@ export class TestUtil {
     return JSON.stringify({ email, firstName, lastName })
   }
 
+  static InvokeAction({ actionId, headers = {}, body, payload }) {
+    const requestBody = body ?? JSON.stringify({ action: actionId, payload: payload ?? {} })
+    return fetch(`${actionsBaseUrl()}/actions`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...headers },
+      body: requestBody,
+    })
+  }
+
+  static AssertActionResponse(test) {
+    return TestUtil.InvokeAction(test).then(response => {
+      expect(response.status).toBe(test.expectedResponseStatus)
+      return response.json()
+        .then(data => expect(data).toEqual(test.expectedResponseBody))
+    })
+  }
+
+  static AssertActionAuthenticationNeeded({ actionId, headers = {}, body, payload }) {
+    describe('given no auth token is provided', () => {
+      it('must return 401 Unauthorized', async () => {
+        const response = await TestUtil.InvokeAction({ actionId, headers, body, payload })
+        expect(response.status).toEqual(401)
+        await expect(response.json()).resolves.toEqual({ error: 'Unauthorized' })
+      })
+    })
+  }
+
+  static AssertWorkspaceActionAuthenticationNeeded({ actionId, headers = {}, body, payload }) {
+    describe('given no auth token is provided', () => {
+      it('must return 403 Forbidden', async () => {
+        const response = await TestUtil.InvokeAction({ actionId, headers, body, payload })
+        expect(response.status).toEqual(403)
+        await expect(response.json()).resolves.toEqual({ error: 'Forbidden' })
+      })
+    })
+  }
+
+  /** @deprecated Prefer `InvokeAction` for platform actions. Kept for Tier-2 REST APIs (verify-sign-in, sign-off). */
   static AssertResponse(test) {
     return fetch(
       `${baseUrl()}${test.endpoint}`,
@@ -48,6 +92,7 @@ export class TestUtil {
     })
   }
 
+  /** @deprecated Prefer `InvokeAction`. Kept for Tier-2 REST APIs. */
   static AssertAuthenticationNeeded(request) {
     describe('given no auth token is provided', () => {
       it('must return 401 Unauthorized', async () => {
@@ -58,6 +103,7 @@ export class TestUtil {
     })
   }
 
+  /** @deprecated Prefer `InvokeAction`. Kept for Tier-2 REST APIs. */
   static MakeRequest(request) {
     return fetch(
       `${baseUrl()}${request.endpoint}`,
@@ -128,10 +174,10 @@ export class TestUtil {
   static GetVerificationToken() {
     const email = `${casual.email}`
 
-    return fetch(
-      `${baseUrl()}/users/sign-up`,
-      { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: TestUtil.signUpBody({ email }) }
-    )
+    return TestUtil.InvokeAction({
+      actionId: 'authentication/sign-up',
+      body: TestUtil.signUpBody({ email }),
+    })
     .then(() => EventStore.FindEvent({
       aggregateType: 'User',
       type: { $in: [ 'SignedUp' ] },
@@ -142,13 +188,11 @@ export class TestUtil {
 
   static async GetAuthenticatedTestUser(email = casual.email) {
 
-    await TestUtil.AssertResponse({
-        endpoint: '/users/sign-up',
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json'},
-        body: TestUtil.signUpBody({ email }),
-        expectedResponseStatus: 200,
-        expectedResponseBody: ''
+    await TestUtil.AssertActionResponse({
+      actionId: 'authentication/sign-up',
+      body: TestUtil.signUpBody({ email }),
+      expectedResponseStatus: 200,
+      expectedResponseBody: { ok: true }
     })
 
     const signedUpEvent = await TestUtil.GetEvent({

package/src/users.middleware.js

@@ -1,10 +1,10 @@
 import { TokenService } from './token.service.js'
 import { createLogger } from '@ossy/observability'
 import { Aggregate } from '@ossy/event-store'
-import { User } from '@ossy/users'
-import { Token } from '@ossy/tokens'
+import { User } from '@ossy/users/server'
+import { Token } from '@ossy/tokens/server'
 import { ConfigService } from './config.service.js'
-import { PoliciesQueries } from '@ossy/policies'
+import { PoliciesQueries } from '@ossy/policies/server'
 
 const log = createLogger('users')