@ossy/platform 1.31.2 → 1.31.3

package/README.md

@@ -0,0 +1,95 @@
+# @ossy/platform
+
+Ossy application server runtime — Express-based server that loads the build manifest produced by `@ossy/app` and serves pages, APIs, tasks, and integrations.
+
+---
+
+## `*.integration.js` — third-party integration primitive
+
+An integration file declares a named third-party client (e.g. a database, email provider, or payment SDK) that the platform connects to once at startup and makes available to every task.
+
+### File naming
+
+Name the file `<slug>.integration.js` (or `.mjs` / `.cjs`) and place it anywhere inside `src/`. The build pipeline discovers it automatically using the `*.integration.js` pattern, just like `*.task.js` and `*.page.jsx`.
+
+### Required exports
+
+| Export | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique slug used to retrieve the client — e.g. `'email'`, `'stripe'`. |
+| `credentials` | `string[]` | Names of environment variables that must be present. If any are missing the integration is skipped at startup with a warning. |
+| `connect` | `async ({ env }) => client` | Called once at startup with the full `process.env`. Returns the client object stored by `id`. If it throws, the integration is skipped (non-fatal). |
+
+### Minimal example
+
+```js
+// src/stripe.integration.js
+import Stripe from 'stripe'
+
+export const id = 'stripe'
+
+export const credentials = ['STRIPE_SECRET_KEY']
+
+export async function connect ({ env }) {
+  return new Stripe(env.STRIPE_SECRET_KEY)
+}
+```
+
+### Consuming integrations inside a task
+
+The platform injects `integrations` into every task's `run()` call alongside `sdk`:
+
+```js
+// src/send-invoice.task.js
+export const metadata = {
+  id: 'send-invoice',
+  triggers: [{ aggregateType: 'Invoice', event: 'InvoiceCreated' }],
+}
+
+export async function run ({ event, sdk, integrations }) {
+  const stripe = integrations.get('stripe')   // null if credentials are missing
+  if (!stripe) return
+
+  await stripe.invoices.send(event.payload.stripeInvoiceId)
+}
+```
+
+`integrations.get(id)` returns `null` when the integration was not loaded (missing credentials, failed `connect()`, or not declared anywhere).
+
+### Manifest output
+
+After `app build` the manifest contains an `integrations` array:
+
+```json
+{
+  "integrations": [
+    {
+      "id": "stripe",
+      "entry": "/static/stripe.integration-7f2a.js",
+      "credentials": ["STRIPE_SECRET_KEY"]
+    }
+  ]
+}
+```
+
+### Built-in integrations
+
+`@ossy/platform` ships with the following integration that is auto-discovered for every app using the package:
+
+| id | Credentials | Client |
+|---|---|---|
+| `email` | `SES_REGION`, `SES_ACCESS_KEY_ID`, `SES_SECRET_ACCESS_KEY` | `SESClient` from `@aws-sdk/client-ses` |
+
+If the SES env vars are not set the `email` integration is silently skipped and `integrations.get('email')` returns `null`.
+
+### `IntegrationService` API
+
+```js
+import { IntegrationService } from '@ossy/platform/integrations'
+
+// Load a list of already-imported integration modules (done automatically by the server).
+await IntegrationService.load(modules, process.env)
+
+// Retrieve a connected client by id.
+const client = IntegrationService.get('email')  // SESClient | null
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "1.31.2",
+  "version": "1.31.3",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -19,7 +19,8 @@
     "./site-loader": "./src/site-loader.js",
     "./tasks": "./src/index.js",
     "./resources": "./src/resources/index.js",
-    "./definition": "./src/Definition.js"
+    "./definition": "./src/Definition.js",
+    "./integrations": "./src/integration.service.js"
   },
   "scripts": {
     "start": "PORT=3003 node -e \"import('./src/server.js').then(m => m.startServer())\""
@@ -28,8 +29,10 @@
   "author": "Ossy <yourfriends@ossy.se> (https://ossy.se)",
   "license": "MIT",
   "dependencies": {
-    "@ossy/router": "^1.32.2",
-    "@ossy/sdk": "^1.32.2",
+    "@aws-sdk/client-ses": "^3.0.0",
+    "@ossy/event-store": "^1.0.1",
+    "@ossy/router": "^1.32.3",
+    "@ossy/sdk": "^1.32.3",
     "cookie-parser": "^1.4.7",
     "dotenv": ">=16.0.0 <18.0.0",
     "express": ">=5.0.0 <6.0.0",
@@ -40,5 +43,5 @@
     "src",
     "Dockerfile"
   ],
-  "gitHead": "5c17e379298f7027f1dbdcf064a4aff69d1497d5"
+  "gitHead": "b8cbdc545a659e96af8948aa08a89316a2c2d193"
 }

package/src/email.integration.js

@@ -0,0 +1,26 @@
+import { SESClient } from '@aws-sdk/client-ses'
+
+export const id = 'email'
+
+export const credentials = [
+  'SES_REGION',
+  'SES_ACCESS_KEY_ID',
+  'SES_SECRET_ACCESS_KEY',
+]
+
+/**
+ * Returns an AWS SES client configured from env vars.
+ * Tasks receive this via `integrations.get('email')`.
+ *
+ * @param {{ env: NodeJS.ProcessEnv }} opts
+ * @returns {SESClient}
+ */
+export async function connect ({ env }) {
+  return new SESClient({
+    region: env.SES_REGION,
+    credentials: {
+      accessKeyId: env.SES_ACCESS_KEY_ID,
+      secretAccessKey: env.SES_SECRET_ACCESS_KEY,
+    },
+  })
+}

package/src/index.js

@@ -4,3 +4,4 @@ export { ChangeStream } from './tasks/change-stream.js'
 export { registerResourceTemplate, getSystemResourceTemplates } from './resources/resource-template.registry.js'
 export { normalizeAndValidateDocumentContent, validateResourceTemplatesForImport, ALLOWED_FIELD_TYPES } from './resources/resource-template.validation.js'
 export { Definition } from './Definition.js'
+export { IntegrationService } from './integration.service.js'

package/src/integration.service.js

@@ -0,0 +1,60 @@
+/** @type {Record<string, unknown>} */
+const _clients = {}
+
+/**
+ * Manages third-party integration clients declared via `*.integration.js` files.
+ *
+ * Integrations are loaded once at server startup. If a required env var is
+ * missing, or if `connect()` throws, the integration is skipped with a warning
+ * so the server can still boot without every optional credential being present.
+ */
+export const IntegrationService = {
+  /**
+   * Connect all integration modules, storing each resulting client by id.
+   * Pass the array of already-imported integration modules (each exporting
+   * `id`, `credentials`, and `connect`).
+   *
+   * @param {Array<{ id: string, credentials: string[], connect: (opts: { env: NodeJS.ProcessEnv }) => Promise<unknown> | unknown }>} modules
+   * @param {NodeJS.ProcessEnv} env  Usually `process.env`.
+   */
+  async load (modules, env) {
+    for (const mod of modules) {
+      const { id, credentials = [], connect } = mod
+
+      if (typeof id !== 'string' || id.trim() === '') {
+        console.warn('[IntegrationService] Skipping integration with missing or invalid "id"')
+        continue
+      }
+
+      const missing = credentials.filter((key) => !env[key])
+      if (missing.length > 0) {
+        console.warn(
+          `[IntegrationService] Skipping integration "${id}" — missing env var(s): ${missing.join(', ')}`,
+        )
+        continue
+      }
+
+      try {
+        _clients[id] = await connect({ env })
+        console.log(`[IntegrationService] Connected integration "${id}"`)
+      } catch (err) {
+        console.warn(
+          `[IntegrationService] Integration "${id}" connect() failed — skipping:`,
+          err && err.message ? err.message : err,
+        )
+      }
+    }
+  },
+
+  /**
+   * Retrieve a connected client by integration id.
+   * Returns `null` when the integration was not loaded (missing credentials,
+   * connect failure, or not declared in the manifest).
+   *
+   * @param {string} id
+   * @returns {unknown | null}
+   */
+  get (id) {
+    return _clients[id] ?? null
+  },
+}

package/src/server.js

@@ -7,9 +7,11 @@ 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 { TaskService } from './tasks/task-service.js'
 import { ChangeStream } from './tasks/change-stream.js'
 import { registerResourceTemplate } from './resources/resource-template.registry.js'
+import { IntegrationService } from './integration.service.js'
 
 const DEFAULT_PORT = 3000
 const MANIFEST_FILE = 'manifest.json'
@@ -49,6 +51,8 @@ export function loadManifest (buildDir) {
   const components = Array.isArray(manifest.components) ? manifest.components : []
   const resourceTemplates = Array.isArray(manifest.resourceTemplates) ? manifest.resourceTemplates : []
   const aggregates = Array.isArray(manifest.aggregates) ? manifest.aggregates : []
+  const integrations = Array.isArray(manifest.integrations) ? manifest.integrations : []
+  const startups = Array.isArray(manifest.startups) ? manifest.startups : []
   for (const e of entries) {
     if ((e.type === 'page' || e.type === 'api') && !validRoutable(e)) {
       console.warn(`[@ossy/platform][server] Skipping ${e.type} "${e.id}" — manifest entry has no path.`)
@@ -62,6 +66,8 @@ export function loadManifest (buildDir) {
     components,
     resourceTemplates,
     aggregates,
+    integrations,
+    startups,
     config: manifest.config || {},
   }
 }
@@ -108,19 +114,22 @@ export async function startServer (options = {}) {
     registerResourceTemplate(template)
   }
 
-  // Aggregate registration — mirrors task and resource-template registration above.
-  // AggregateRebuild lives in the co-located api package. The relative path resolves
-  // correctly both in the monorepo layout (ossy/packages/platform/src/ → api/) and
-  // when the published package is installed inside api/node_modules/@ossy/platform/src/.
-  // A try/catch ensures the server starts cleanly even when the api source is absent.
-  let AggregateRebuild = null
-  try {
-    const rebuildMod = await import(new URL('../../../../api/src/aggregate/aggregate.rebuild.js', import.meta.url).href)
-    AggregateRebuild = rebuildMod.AggregateRebuild
-  } catch {
-    // AggregateRebuild not reachable from this installation — aggregate registration skipped.
+  // Integration loading — import each bundled integration module, check its
+  // declared credentials, and call connect({ env }) to obtain a client.
+  // Missing credentials or a failing connect() are non-fatal: the integration
+  // is skipped with a warning so the server still starts.
+  const integrationModules = []
+  for (const intEntry of manifest.integrations ?? []) {
+    try {
+      integrationModules.push(await import(resolveEntryUrl(intEntry.entry, buildDir)))
+    } catch (err) {
+      console.warn(`[@ossy/platform][server] Failed to import integration "${intEntry.id}":`, err.message)
+    }
   }
+  await IntegrationService.load(integrationModules, process.env)
 
+  // Aggregate registration — mirrors task and resource-template registration above.
+  // AggregateRebuild is provided by @ossy/event-store.
   if (AggregateRebuild) {
     for (const agg of manifest.aggregates ?? []) {
       try {
@@ -130,6 +139,21 @@ export async function startServer (options = {}) {
         console.error(`[@ossy/platform][server] Failed to load aggregate "${agg.id}":`, err.message)
       }
     }
+
+    AggregateRebuild.BuildAndSaveAll().catch((error) => {
+      console.error('[@ossy/platform][server] BuildAndSaveAll failed — is MongoDB reachable?', error)
+    })
+  }
+
+  for (const startup of manifest.startups ?? []) {
+    try {
+      const mod = await import(resolveEntryUrl(startup.entry, buildDir))
+      if (typeof mod.run === 'function') {
+        await mod.run({ env: process.env })
+      }
+    } catch (err) {
+      console.error(`[@ossy/platform][server] Failed to run startup "${startup.id}":`, err.message)
+    }
   }
 
   // Register the SDK so all tasks receive it as `sdk`.

package/src/tasks/task-service.js

@@ -1,5 +1,6 @@
 import { matchesGlob } from './glob.js'
 import { matchesCron } from './cron.js'
+import { IntegrationService } from '../integration.service.js'
 
 const SCHEDULER_INTERVAL_MS = 60_000
 
@@ -74,7 +75,7 @@ export class TaskService {
       console.log(`[TaskService] Dispatching task "${metadata.id}"`)
 
       Promise.resolve()
-        .then(() => handler({ event, sdk: effectiveSdk }))
+        .then(() => handler({ event, sdk: effectiveSdk, integrations: IntegrationService }))
         .catch(error =>
           console.error(`[TaskService] Task "${metadata.id}" failed`, error),
         )
@@ -104,7 +105,7 @@ export class TaskService {
         console.log(`[TaskService] Schedule fired for task "${metadata.id}"`)
 
         Promise.resolve()
-          .then(() => handler({ event: { type: 'scheduled', taskId: metadata.id }, sdk: TaskService._sdk }))
+          .then(() => handler({ event: { type: 'scheduled', taskId: metadata.id }, sdk: TaskService._sdk, integrations: IntegrationService }))
           .catch(error =>
             console.error(`[TaskService] Scheduled task "${metadata.id}" failed`, error),
           )