@assembly-js/app-foundation 0.0.11 → 0.0.12

package/bin/validate-manifest.mjs

@@ -310,7 +310,8 @@ const MAX_ACTION_DESC_LENGTH = 40;
 const MAX_PATH_LENGTH = 512;
 
 const RESOURCE_NAME_RE = /^[a-z][a-zA-Z0-9]{1,63}$/;
-const EVENT_NAME_RE = /^[a-zA-Z0-9]+\.[a-zA-Z0-9]+$/;
+const EVENT_NAME_RE = /^(~app-[a-z0-9]+\.)?[a-zA-Z0-9]+\.[a-zA-Z0-9]+$/;
+const APP_EVENT_MARKER_RE = /^~app-[a-z0-9]+\./;
 const API_PATH_RE = /^(\/[a-z0-9\-_]+)+(\/:id)?$/;
 
 const ALLOWED_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
@@ -530,22 +531,33 @@ function camelCaseAlnum(s) {
   return out;
 }
 
+// Mirrors marketplace_application.PeelAppEventMarker: splits a possibly-namespaced
+// event name into its "~<appId>." marker (empty when absent) and the bare
+// {resourceName}.{verb} remainder.
+function peelAppEventMarker(eventName) {
+  const m = APP_EVENT_MARKER_RE.exec(eventName);
+  const marker = m ? m[0] : '';
+  return { marker, bare: eventName.slice(marker.length) };
+}
+
 // Mirrors normalizeAppApiEventName in app_api_resources.go: the publish gate
 // coerces an authored eventName toward the canonical {resourceName}.{verb}
 // form instead of rejecting it ("intake.review_status_changed" →
 // "intake.reviewStatusChanged"; a bare verb gains the record's resourceName;
-// an empty verb becomes "triggered"). Returns the input unchanged when
-// nothing salvageable remains, so the format error still fires.
+// an empty verb becomes "triggered"). Any leading "~<appId>." marker is peeled
+// off, normalized around, and re-attached verbatim. Returns the input unchanged
+// when nothing salvageable remains, so the format error still fires.
 function normalizeEventName(resourceName, eventName) {
+  const { marker, bare } = peelAppEventMarker(eventName);
   let prefix = resourceName;
-  let verb = eventName;
-  const dot = eventName.indexOf('.');
+  let verb = bare;
+  const dot = bare.indexOf('.');
   if (dot >= 0) {
-    prefix = camelCaseAlnum(eventName.slice(0, dot)) || resourceName;
-    verb = eventName.slice(dot + 1);
+    prefix = camelCaseAlnum(bare.slice(0, dot)) || resourceName;
+    verb = bare.slice(dot + 1);
   }
   verb = camelCaseAlnum(verb) || 'triggered';
-  const normalized = prefix + '.' + verb;
+  const normalized = marker + prefix + '.' + verb;
   return EVENT_NAME_RE.test(normalized) ? normalized : eventName;
 }
 
@@ -1025,16 +1037,21 @@ if (existsSync(API_RESOURCES)) {
             if (!EVENT_NAME_RE.test(eventName)) {
               apiErrors.push(webhookWhere + ': eventName "' + eventName + '" must be {resourceName}.{verb}.');
             } else {
-              const prefix = eventName.slice(0, eventName.indexOf('.'));
+              // A namespaced app event carries a "~<appId>." marker that is opaque
+              // to the resourceName and native-collision checks; validate the bare
+              // {resourceName}.{verb} remainder.
+              const bare = peelAppEventMarker(eventName).bare;
+              const prefix = bare.slice(0, bare.indexOf('.'));
               if (!resourceNames.has(prefix)) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" must be prefixed by one of the manifest\'s resourceNames.');
               }
-              const lowerEventName = eventName.toLowerCase();
-              if (NATIVE_EVENTS_LOWER.has(lowerEventName)) {
+              const lowerBare = bare.toLowerCase();
+              if (NATIVE_EVENTS_LOWER.has(lowerBare)) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" is a native platform event name.');
               } else if (NATIVE_NAMESPACES_LOWER.has(prefix.toLowerCase())) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" uses the native "' + prefix + '" event namespace; pick a distinct resourceName.');
               }
+              const lowerEventName = eventName.toLowerCase();
               if (seenEventNames.has(lowerEventName)) {
                 apiErrors.push(webhookWhere + ': eventName "' + eventName + '" is already declared by ' + seenEventNames.get(lowerEventName) + ' (event names are matched case-insensitively).');
               } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-automations/SKILL.md

@@ -63,7 +63,7 @@ The entire file is one top-level key. Unknown keys anywhere are publish errors,
       ],
       "apis": [
         {
-          "name": "Create time entry",
+          "name": "~app-43574726.Create time entry",
           "description": "Log a time entry",
           "method": "POST",
           "path": "/time-entries",
@@ -84,7 +84,7 @@ The entire file is one top-level key. Unknown keys anywhere are publish errors,
       ],
       "webhooks": [
         {
-          "eventName": "timeEntry.created",
+          "eventName": "~app-43574726.timeEntry.created",
           "eventDescription": "Fires when a time entry is logged",
           "trigger": {
             "name": "Time entry logged",
@@ -94,7 +94,7 @@ The entire file is one top-level key. Unknown keys anywhere are publish errors,
           }
         },
         {
-          "eventName": "timeEntry.approved",
+          "eventName": "~app-43574726.timeEntry.approved",
           "eventDescription": "Fires when a time entry is approved",
           "trigger": {
             "name": "Time entry approved",
@@ -223,7 +223,7 @@ const userAgent = req.headers.get('user-agent') ?? '';
 
 after(async () => {
   try {
-    const res = await assembly.fetch('/v1/webhooks/timeEntry.created', {
+    const res = await assembly.fetch('/v1/webhooks/~app-43574726.timeEntry.created', {
       method: 'POST',
       headers: {
         'X-Assembly-Actor-Id': actorId,
@@ -242,7 +242,7 @@ after(async () => {
 });
 ```
 
-- **`assembly.fetch` is how an event is emitted** — it adds the app's auth and the JSON content type for you. The path is `/v1/webhooks/<eventName>` using the exact `eventName` from this file; the platform validates the name and payload against this manifest's registration, then runs matching automations.
+- **`assembly.fetch` is how an event is emitted** — it adds the app's auth and the JSON content type for you. The path is `/v1/webhooks/<eventName>` using the **exact** `eventName` from this file, `~<appId>.` prefix and all (the `~` is URL-safe, so the path needs no encoding); the platform validates the name and payload against this manifest's registration, then runs matching automations.
 - **Check `res.ok`.** `assembly.fetch` resolves on a 4xx instead of throwing, so an unregistered event name or an invalid payload is a silent no-op unless you read the status — the easiest way there is to ship a trigger that never fires.
 - **Emit inside `after()`, and never leave the call un-awaited.** `after()` runs the emit once the response is sent, so it never delays or breaks the user's action — log the failure there and continue. Dropping the `await` to keep the handler fast looks equivalent and is not: a floating promise is frozen when the handler returns, so the event arrives minutes late or never, and which one you get is luck.
 - **Capture the request values in the handler, not inside the callback.** `after()` runs past the response, so read `actorId` / IP / user-agent before it and close over them.
@@ -471,14 +471,15 @@ export const GET = automationActionRoute(async (_input, { workspaceId }) => {
 
 ## Rules the publish gate enforces
 
-- **Event names are `{resourceName}.{verb}`** — `timeEntry.created`, never a bare `created` and never a native platform event name (`task.completed`, `client.created`, …). Unique within the app, case-insensitively. Both segments are single alphanumeric camelCase tokens — no underscores, hyphens, or extra dots: `intake.reviewStatusChanged`, never `intake.review_status_changed`. The publish gate auto-normalizes non-conforming names to camelCase, so the event name your runtime code emits must be the canonical form — write camelCase everywhere.
+- **Namespace every event name and exposed action with your app id.** Prefix each `eventName`, and the `name` of every api you set `exposeToAutomations: true` on, with `~$ASSEMBLY_APP_ID.` — read the id from the `ASSEMBLY_APP_ID` environment variable (`echo $ASSEMBLY_APP_ID`, it looks like `app-43574726`) and write the literal value in. This is what keeps your triggers and actions from colliding with another app installed in the same workspace, and the prefix is stripped before the user ever sees it. Prefix only **new** events/actions — never re-prefix or rename one you already shipped (see the renaming rule below).
+- **Event names are `~<appId>.{resourceName}.{verb}`** — e.g. `~app-43574726.timeEntry.created`. The `{resourceName}.{verb}` remainder is still exactly two single alphanumeric camelCase tokens: no bare `created`, no native platform event name (`task.completed`, `client.created`, …), and no underscores, hyphens, or extra dots inside the remainder — `~app-43574726.intake.reviewStatusChanged`, never `intake.review_status_changed`. The publish gate normalizes only the remainder to camelCase and carries the `~<appId>.` prefix through untouched, so the event name your runtime code emits must be byte-identical to what you declare — write it the same in both places.
 - **One action = one record + method.** `exposeToAutomations: true` requires an `input` with at least one field where `automationSettings.isEnabled` is true. `(method, path)` pairs must be unique across the whole file.
 - **The zero-value rule**: the platform treats a zero value (`0`, `""`, `false`) on a required field as missing. Declare booleans and legitimately-zeroable numbers `optional: true`; a required `bool` field is rejected outright.
 - **`dynamicOptions`** on action fields (`{ "requestUrl": "/projects", "nameField": "name" }`) points a dropdown at a **GET api registered by any record in this manifest** — cross-resource references are normal (a `feedbackItem` input listing categories points at the `category` record's GET api). The `requestUrl` must equal that api's `path`; `/:id` forms don't qualify. The endpoint must return `{ "data": [ { "id": "...", "name": "..." } ] }` — `nameField` may be nested/composite (`name.first|name.last`). The referenced api must live in a record whose `baseUrl` actually serves it and whose `schema[]` the response satisfies — see "Serving dynamic options". Use `dropdownSource` instead when the choice is an Assembly client/company/internal user.
 - Paths are lowercase `[a-z0-9-_]` segments with an optional trailing `/:id`, and must not contain `tasks`, `task-templates`, or `comments` — those route to the platform's Tasks app.
 - **`apis[].description` max 40 characters** (all apis). It becomes the action's label — see above.
 - **`trigger.icon`, when set, must be one of the names in the icon list above.** Unknown names fail the publish; an omitted icon renders a generic default.
-- **Renaming breaks saved automations.** An action's identity derives from the api's `name` and a trigger's from `eventName`; renaming either orphans every automation a workspace built on it. Pick names as if they're permanent.
+- **Renaming breaks saved automations.** An action's identity derives from the api's `name` and a trigger's from `eventName` — including the `~<appId>.` prefix, which is part of that identity. Renaming either, or adding/removing the prefix on one you already shipped, orphans every automation a workspace built on it. Pick names as if they're permanent.
 
 ## Telling the user