anear-js-api 1.8.0 → 2.1.1

package/README.md

@@ -115,6 +115,31 @@ ANEARAPP_API_VERSION=v1
 ANEARAPP_API_URL=http://api.lvh.me:3001/developer  # Optional, for local development
 ```
 
+### Local Dev Quickstart (no Docker)
+
+To keep development behavior close to today:
+
+1. Keep runtime asset publishing enabled (default):
+
+```bash
+unset ANEARAPP_SKIP_RUNTIME_ASSET_SYNC
+```
+
+2. Start your app process normally:
+
+```bash
+npm install
+node index.js
+```
+
+3. If your ANAPI environment is not Rails `development`, set:
+
+```bash
+export ANEARAPP_SINGLE_LATEST_VERSION=true
+```
+
+This preserves a single mutable `latest` app version for iterative development.
+
 ### Developer API Authentication
 
 `anear-js-api` communicates with the **ANAPI Developer API** (`/developer/v1/*` endpoints) using JWT authentication:
@@ -263,6 +288,29 @@ The JSAPI automatically handles asset management:
 2. **Image Upload**: All images in `assets/images/` are uploaded to CloudFront
 3. **Template Preloading**: All PUG templates are preloaded and cached
 
+### CI-Managed Assets Mode
+
+For containerized deployments, you can publish assets during CI and skip runtime asset sync:
+
+```bash
+ANEARAPP_SKIP_RUNTIME_ASSET_SYNC=true
+```
+
+When this variable is enabled, `AnearCoreServiceMachine` skips image/font/CSS upload states and proceeds directly to template compilation and event lifecycle listening.
+
+CI helpers are available under:
+
+- `anear-js-api/lib/ci/publishAssets.js`
+- `anear-js-api/lib/ci/registerAppVersion.js`
+
+### Versioned Lifecycle Channels
+
+ACSM subscribes to versioned lifecycle channels derived from ANAPI app metadata:
+
+`anear:<appId>:v:<appVersion>:e`
+
+ANAPI must return `latest_app_version` in developer app payloads for startup channel resolution.
+
 ### Asset Structure
 
 ```

package/lib/api/AnearApi.js

@@ -80,6 +80,24 @@ class AnearApi extends ApiService {
     return attrs
   }
 
+  async createAppVersion(appId, attrs) {
+    logger.debug(`API: POST app_versions for app ${appId}`)
+    const json = await this.post("app_versions", attrs, { app: appId })
+    return json.data
+  }
+
+  async updateAppVersion(appVersionId, attrs) {
+    logger.debug(`API: PUT app_versions/${appVersionId}`)
+    const json = await this.put("app_versions", appVersionId, attrs)
+    return json.data
+  }
+
+  async getLatestAppVersion(appId) {
+    logger.debug(`API: GET apps/${appId}/latest_app_version`)
+    const json = await this.get(`apps/${appId}/latest_app_version`)
+    return json.data
+  }
+
   async saveAppEventContext(eventId, appmContext) {
     logger.debug(`API: POST developer events/${eventId}/app_event_context`)
     const path = `events/${eventId}/app_event_context`

package/lib/ci/publishAssets.js

@@ -0,0 +1,35 @@
+"use strict"
+
+const C = require('../utils/Constants')
+const ImageAssetsUploader = require('../utils/ImageAssetsUploader')
+const FontAssetsUploader = require('../utils/FontAssetsUploader')
+const CssUploader = require('../utils/CssUploader')
+
+async function publishAssetsFromCi(appId = process.env.ANEARAPP_APP_ID) {
+  if (!appId) {
+    throw new Error('ANEARAPP_APP_ID must be set to publish assets from CI')
+  }
+
+  const imageAssetsUploader = new ImageAssetsUploader(C.ImagesDirPath, appId)
+  const imageAssetsUrl = await imageAssetsUploader.uploadAssets()
+
+  const fontAssetsUploader = new FontAssetsUploader(C.FontsDirPath, appId)
+  const fontAssetsUrl = await fontAssetsUploader.uploadAssets()
+
+  const cssUploader = new CssUploader(
+    C.CssDirPath,
+    imageAssetsUrl,
+    fontAssetsUrl,
+    appId
+  )
+  const cssUrl = await cssUploader.uploadCss()
+
+  return {
+    appId,
+    imageAssetsUrl,
+    fontAssetsUrl,
+    cssUrl
+  }
+}
+
+module.exports = { publishAssetsFromCi }

package/lib/ci/registerAppVersion.js

@@ -0,0 +1,49 @@
+"use strict"
+
+const AnearApi = require('../api/AnearApi')
+
+async function registerAppVersionFromCi({
+  appId = process.env.ANEARAPP_APP_ID,
+  version = process.env.APP_VERSION,
+  gitSha = process.env.GITHUB_SHA,
+  imageUri = process.env.IMAGE_URI,
+  assetManifestHash = process.env.ASSET_MANIFEST_HASH,
+  imageAssetsUrl = process.env.IMAGE_ASSETS_URL,
+  fontAssetsUrl = process.env.FONT_ASSETS_URL,
+  cssUrl = process.env.CSS_URL,
+  status = 'building'
+} = {}) {
+  if (!appId || !version) {
+    throw new Error('ANEARAPP_APP_ID and APP_VERSION are required to register an app version')
+  }
+
+  const data = await AnearApi.createAppVersion(appId, {
+    version,
+    status,
+    git_sha: gitSha,
+    image_uri: imageUri,
+    asset_manifest_hash: assetManifestHash,
+    image_assets_url: imageAssetsUrl,
+    font_assets_url: fontAssetsUrl,
+    css_url: cssUrl
+  })
+
+  return data
+}
+
+async function markAppVersionStatus(appVersionId, status, extraAttrs = {}) {
+  if (!appVersionId || !status) {
+    throw new Error('appVersionId and status are required to update app version status')
+  }
+
+  const data = await AnearApi.updateAppVersion(appVersionId, {
+    status,
+    ...extraAttrs
+  })
+  return data
+}
+
+module.exports = {
+  registerAppVersionFromCi,
+  markAppVersionStatus
+}

package/lib/state_machines/AnearCoreServiceMachine.js

@@ -58,8 +58,11 @@ const ImageAssetsUploader = require('../utils/ImageAssetsUploader')
 const FontAssetsUploader = require('../utils/FontAssetsUploader')
 const C = require('../utils/Constants')
 
-const CreateEventChannelNameTemplate = appId => `anear:${appId}:e`
+const CreateVersionedEventChannelNameTemplate = (appId, appVersion) => `anear:${appId}:v:${normalizeVersionToken(appVersion)}:e`
 const DefaultTemplatesRootDir = "./views"
+const SkipRuntimeAssetSync = process.env.ANEARAPP_SKIP_RUNTIME_ASSET_SYNC === 'true'
+const FallbackImageAssetsUrl = process.env.ANEARAPP_IMAGE_ASSETS_URL || null
+const FallbackFontAssetsUrl = process.env.ANEARAPP_FONT_ASSETS_URL || null
 
 // Process-wide signal handling.
 // We install exactly once per process to avoid duplicate handlers in reconnect/restart scenarios.
@@ -152,7 +155,33 @@ const AnearCoreServiceMachineConfig = appId => ({
             actions: ({ context }) => logger.warn(`[ACSM] Realtime connected, but shutdown already requested for app ${context.appId}; not subscribing to CREATE/LOAD commands`)
           }
         ],
-        ATTACHED: 'uploadNewImageAssets'
+        ATTACHED: 'syncAssetsOrSkip'
+      }
+    },
+    syncAssetsOrSkip: {
+      always: [
+        {
+          guard: 'runtimeAssetSyncDisabled',
+          actions: () => logger.info('[ACSM] Runtime asset sync disabled; assuming CI has already published assets'),
+          target: 'resolveVersionAssetUrls'
+        },
+        {
+          target: 'uploadNewImageAssets'
+        }
+      ]
+    },
+    resolveVersionAssetUrls: {
+      invoke: {
+        src: 'fetchLatestAppVersionAssets',
+        input: ({ context }) => ({ appId: context.appId }),
+        onDone: {
+          actions: assign({
+            imageAssetsUrl: ({ event }) => event.output.imageAssetsUrl,
+            fontAssetsUrl: ({ event }) => event.output.fontAssetsUrl
+          }),
+          target: 'loadAndCompilePugTemplates'
+        },
+        onError: '#failure'
       }
     },
     uploadNewImageAssets: {
@@ -242,6 +271,19 @@ const AnearCoreServiceMachineFunctions = {
     // v5 pattern: async "services" become Promise Actors via `fromPromise`.
     // The invoked actor receives `input` from the invoking state's `invoke.input`.
     fetchAppData: fromPromise(({ input }) => AnearApi.getApp(input.appId)),
+    fetchLatestAppVersionAssets: fromPromise(async ({ input }) => {
+      const latestVersion = await AnearApi.getLatestAppVersion(input.appId)
+      const attrs = latestVersion?.attributes || {}
+      const imageAssetsUrl = attrs['image-assets-url'] || FallbackImageAssetsUrl
+      const fontAssetsUrl = attrs['font-assets-url'] || FallbackFontAssetsUrl
+
+      if (!imageAssetsUrl) {
+        throw new Error('[ACSM] Missing image-assets-url for latest app version; set app_version image_assets_url in ANAPI or ANEARAPP_IMAGE_ASSETS_URL env var')
+      }
+
+      logger.info(`[ACSM] Using pre-published version assets image_base=${imageAssetsUrl}`)
+      return { imageAssetsUrl, fontAssetsUrl }
+    }),
     uploadNewImageAssets: fromPromise(({ input }) => {
       const uploader = new ImageAssetsUploader(C.ImagesDirPath, input.appId)
       return uploader.uploadAssets()
@@ -298,7 +340,13 @@ const AnearCoreServiceMachineFunctions = {
     createEventsCreationChannel: assign(
       {
         newEventCreationChannel: ({ context, self }) => {
-          const channelName = CreateEventChannelNameTemplate(context.appId)
+          const attrs = context.appData?.data?.attributes || {}
+          const appVersion = attrs['latest-app-version']
+          if (!appVersion) {
+            throw new Error('[ACSM] Missing latest-app-version in app data; cannot subscribe to lifecycle channel')
+          }
+          const channelName = CreateVersionedEventChannelNameTemplate(context.appId, appVersion)
+          logger.info(`[ACSM] Subscribing to versioned lifecycle channel ${channelName}`)
           return RealtimeMessaging.getChannel(channelName, self)
         }
       }
@@ -314,7 +362,7 @@ const AnearCoreServiceMachineFunctions = {
         self,
         'LOAD_EVENT'
       )
-      logger.info(`[ACSM] Subscribed to CREATE_EVENT and LOAD_EVENT on events channel (pid=${process.pid})`)
+      logger.info(`[ACSM] Subscribed to CREATE_EVENT and LOAD_EVENT on versioned lifecycle channel (pid=${process.pid})`)
     },
     logIgnoredLifecycleCommand: ({ event, context }) => {
       logger.warn(`[ACSM] Ignoring ${event.type} because shutdown has been requested (appId=${context.appId} pid=${process.pid})`)
@@ -436,10 +484,15 @@ const AnearCoreServiceMachineFunctions = {
   },
   guards: {
     noImageAssetFilesFound: ({ event }) => event.output === null,
-    acceptLifecycleCommands: ({ context }) => !context.shutdownRequested
+    acceptLifecycleCommands: ({ context }) => !context.shutdownRequested,
+    runtimeAssetSyncDisabled: () => SkipRuntimeAssetSync
   }
 }
 
+function normalizeVersionToken(value) {
+  return String(value).replace(/[^A-Za-z0-9_.-]/g, '_')
+}
+
 const AnearCoreServiceMachine = (appEventMachineFactory, appParticipantMachineFactory = null) => {
   const appId = process.env.ANEARAPP_APP_ID
   const machineConfig = AnearCoreServiceMachineConfig(appId)

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "anear-js-api",
-  "version": "1.8.0",
+  "version": "2.1.1",
   "description": "Javascript Developer API for Anear Apps",
   "main": "lib/index.js",
   "scripts": {
-    "test": "jest"
+    "test": "jest",
+    "audit:prod": "npm audit --omit=dev",
+    "audit:prod:fix": "npm audit fix --omit=dev",
+    "audit:full": "npm audit",
+    "audit:full:fix": "npm audit fix"
   },
   "repository": {
     "type": "git",