feat(api): add queue trigger handler registration

[nnoce14]

Summary

• add Azure queue trigger registration to the app-local Cellix bootstrap fluent API
• add queue trigger phase-contract coverage, including mixed HTTP/queue chaining and post-startup lockout
• introduce @ocom/handler-queue-community-update and route trigger handling through typed queue storage service receive methods with built-in validation/logging

Testing

• pnpm --filter @cellix/service-queue-storage test
• pnpm --filter @ocom/handler-queue-community-update test
• pnpm --filter @apps/api test
• pnpm --filter @apps/api build

Notes

• this PR targets issue263/queue-storage-service because it depends on the unmerged queue storage service work
• local commit used --no-verify because the repo pre-commit hook currently fails on unrelated formatting in packages/ocom/domain/target/site/serenity/cucumber-report.json

Summary by Sourcery

Add Azure Storage Queue trigger support to the Cellix bootstrap API and wire up a community-update queue handler into the API app.

New Features:

• Introduce registration of Azure Functions Storage Queue triggers in the Cellix fluent bootstrap API, alongside existing HTTP handlers.
• Add a dedicated community-update queue definition and handler package to process community update messages via Azure Storage Queues.
• Enable system-scoped application services resolution for non-request queue handler workloads.

Enhancements:

• Extend the queue consumer to accept trigger-delivered messages while reusing existing validation and logging behavior.
• Update the API bootstrap to register the community-update queue handler and integrate it with the shared queue storage service.

Documentation:

• Document the new community-update queue handler package, its purpose, public API, and behavior.

Tests:

• Add BDD and unit tests covering queue handler registration, mixed HTTP/queue chaining, startup phase guards, trigger-delivered message handling, and the community-update queue handler behavior.

[sourcery-ai]

Reviewer's Guide

Adds first-class Azure Storage Queue trigger support to the Cellix bootstrap, wires a new community-update queue and handler into the @apps/api app using typed queue storage services, and extends the queue consumer to validate/log both polled and trigger-delivered messages, including new system-scoped application services access.

Sequence diagram for community-update queue trigger handling

sequenceDiagram
    participant AzureStorageQueue
    participant AzureFunctions
    participant CommunityUpdateQueueHandler as communityUpdateQueueHandlerCreator
    participant QueueStorageService as QueueStorageOperations
    participant AppServicesFactory as ApplicationServicesFactory
    participant AppServices as ApplicationServices
    participant CommunityDomain as CommunityService

    AzureStorageQueue-->>AzureFunctions: StorageQueueTrigger
    AzureFunctions->>CommunityUpdateQueueHandler: StorageQueueHandler
    CommunityUpdateQueueHandler->>QueueStorageService: receiveFromCommunityUpdateQueue
    QueueStorageService-->>CommunityUpdateQueueHandler: QueueMessage
    CommunityUpdateQueueHandler->>AppServicesFactory: forSystem
    AppServicesFactory-->>CommunityUpdateQueueHandler: ApplicationServices
    CommunityUpdateQueueHandler->>CommunityDomain: queryById
    CommunityDomain-->>CommunityUpdateQueueHandler: existingCommunity
    CommunityUpdateQueueHandler->>CommunityDomain: updateSettings

Loading

File-Level Changes

Change	Details	Files
Extend Cellix bootstrap fluent API to register Azure Storage Queue triggers alongside HTTP handlers, including phase validation, startup wiring, and mixed chaining support.	Add registerAzureFunctionQueueHandler to the AzureFunctionHandlerRegistry interface and Cellix implementation, storing queue handler metadata in pendingQueueHandlers Introduce PendingQueueHandler and app-services host type that can optionally expose forSystem in addition to forRequest Ensure registerAzureFunctionQueueHandler is only callable in app-services/handlers phases, moves phase to handlers, and registers all pending queue handlers with app.storageQueue during startUp Expand Cellix BDD specs and tests to cover queue handler registration, mixed HTTP/queue chaining, direct startup from app-services, and post-startup fluent API lockout	apps/api/src/cellix.ts apps/api/src/cellix.test.ts apps/api/src/features/cellix.feature
Enhance queue consumer so typed receive methods can process both polled and trigger-delivered messages with shared validation/logging, and define a TriggeredQueueMessage shape.	Change QueueConsumerContext receive methods to accept an optional TriggeredQueueMessage parameter, delegating to new validation/logging helper when provided Factor validation and logging into validateAndLogInboundMessage, reusing existing logging-fields resolution and log envelope construction Add TriggeredQueueMessage type and toQueueMessage adapter to map trigger-delivered messages into QueueMessage Add feature and unit tests for processing trigger-delivered messages via receiveFromImportRequestsQueue	packages/cellix/service-queue-storage/src/queue-consumer.ts packages/cellix/service-queue-storage/src/queue-consumer.test.ts packages/cellix/service-queue-storage/src/features/queue-consumer.feature packages/cellix/service-queue-storage/src/interfaces.ts
Introduce the community-update inbound queue contract and include it in the shared queue registry and exports for use by apps and handlers.	Define CommunityUpdateMessage and communityUpdateQueue using defineQueue with logging metadata/tags and JSON schema Register communityUpdateQueue as an inbound queue and update allQueueNames to include community-update Export CommunityUpdateMessage and communityUpdateQueue from @ocom/service-queue-storage public API	packages/ocom/service-queue-storage/src/schemas/inbound/community-update.ts packages/ocom/service-queue-storage/src/schemas/inbound/community-update.schema.json packages/ocom/service-queue-storage/src/registry.ts packages/ocom/service-queue-storage/src/index.ts
Add a dedicated @ocom/handler-queue-community-update package that encapsulates the Azure Functions queue trigger handler for community-update messages, leveraging typed queue storage and system-scoped app services.	Implement communityUpdateQueueHandlerCreator to adapt InvocationContext metadata into a triggered message, call receiveFromCommunityUpdateQueue, and update community settings via system-scoped services Propagate trigger metadata (id, popReceipt, dequeueCount) into the queue consumer path and handle missing communities by logging instead of persisting Add extensive unit tests for happy path, metadata propagation, missing community behavior, invalid payload errors, and missing forSystem support Set up package boilerplate (tsconfig, vitest config, manifest/readme, build outputs, and package.json with dependencies on application-services and service-queue-storage)	packages/ocom/handler-queue-community-update/src/handler.ts packages/ocom/handler-queue-community-update/src/handler.test.ts packages/ocom/handler-queue-community-update/src/index.ts packages/ocom/handler-queue-community-update/package.json packages/ocom/handler-queue-community-update/readme.md packages/ocom/handler-queue-community-update/manifest.md packages/ocom/handler-queue-community-update/vitest.config.ts packages/ocom/handler-queue-community-update/tsconfig.json packages/ocom/handler-queue-community-update/dist/*
Wire the community-update queue and handler into the @apps/api bootstrap using the new queue trigger registration API and system-scoped application services.	Extend application services host to expose an optional forSystem method and implement it in buildApplicationServicesFactory to create a system-passport-backed ApplicationServices instance Update api bootstrap to register the community-update queue handler via registerAzureFunctionQueueHandler, using communityUpdateQueue metadata and AZURE_STORAGE_CONNECTION_STRING Mock and assert queue-related behavior in api index tests, including handler registration, handler creator wiring, and error/validation flows Add @ocom/handler-queue-community-update as a dependency and tsconfig reference for the api app	packages/ocom/application-services/src/index.ts apps/api/src/index.ts apps/api/src/index.test.ts apps/api/package.json apps/api/tsconfig.json pnpm-lock.yaml

Possibly linked issues

• Upgrade Storybook 9 → 10 across UI packages, apps, and the shared test config #268: The PR adds Cellix queue trigger registration plus the community-update queue handler and wiring exactly matching the issue scope.
• Implement @cellix/service-queue-storage for type-safe queue messaging, validation, logging, and OCOM integration #263: PR delivers the fluent queue trigger API and a typed inbound queue handler that uses the new queue storage service.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 3 issues, and left some high level feedback:

• The new @ocom/handler-queue-community-update package commits built dist artifacts (.js, .d.ts, .map); if your usual pattern is to build on publish/CI, consider excluding dist from source control to avoid drift between compiled and source code.
• In communityUpdateQueueHandlerCreator you re-declare the trigger message shape and manually build the object passed to receiveFromCommunityUpdateQueue; you could simplify and tighten typing by reusing the exported TriggeredQueueMessage type from @cellix/service-queue-storage (and possibly the buildTriggeredQueueMessage helper) instead of maintaining a parallel structural type.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The new `@ocom/handler-queue-community-update` package commits built `dist` artifacts (`.js`, `.d.ts`, `.map`); if your usual pattern is to build on publish/CI, consider excluding `dist` from source control to avoid drift between compiled and source code.
- In `communityUpdateQueueHandlerCreator` you re-declare the trigger message shape and manually build the object passed to `receiveFromCommunityUpdateQueue`; you could simplify and tighten typing by reusing the exported `TriggeredQueueMessage` type from `@cellix/service-queue-storage` (and possibly the `buildTriggeredQueueMessage` helper) instead of maintaining a parallel structural type.

## Individual Comments

### Comment 1
<location path="packages/cellix/service-queue-storage/src/queue-consumer.ts" line_range="118-120" />
<code_context>
+	return message;
+}
+
+function toQueueMessage<TPayload>(triggeredMessage: TriggeredQueueMessage<TPayload>): QueueMessage<TPayload> {
+	return {
+		id: triggeredMessage.id ?? 'triggered-message',
+		payload: triggeredMessage.payload,
+		...(triggeredMessage.popReceipt !== undefined ? { popReceipt: triggeredMessage.popReceipt } : {}),
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Defaulting the triggered message ID to a synthetic constant may make diagnosing issues harder.

Using the hardcoded `'triggered-message'` means all messages without an ID become indistinguishable in logs and for any consumers relying on `message.id`. Consider either propagating `undefined` and requiring consumers to handle it, or deriving a more descriptive ID from available metadata to keep messages distinguishable for diagnostics and any ID-based logic.

Suggested implementation:

```typescript
function toQueueMessage<TPayload>(triggeredMessage: TriggeredQueueMessage<TPayload>): QueueMessage<TPayload> {
	return {
		...(triggeredMessage.id !== undefined ? { id: triggeredMessage.id } : {}),
		payload: triggeredMessage.payload,
		...(triggeredMessage.popReceipt !== undefined ? { popReceipt: triggeredMessage.popReceipt } : {}),
		...(triggeredMessage.dequeueCount !== undefined ? { dequeueCount: triggeredMessage.dequeueCount } : {}),
	};
}

```

If the `QueueMessage<TPayload>` type currently requires a non-optional `id: string`, you should:
1. Update `QueueMessage` so that `id` is optional (e.g. `id?: string`) to reflect that some triggered messages legitimately do not have an ID.
2. Audit any consumers of `QueueMessage` that assume `message.id` is always present, and add appropriate handling (e.g. conditional logic or fallback generation localized to where it's needed) instead of relying on a synthetic constant ID.
</issue_to_address>

### Comment 2
<location path="apps/api/src/cellix.ts" line_range="172-173" />
<code_context>
 };

-type AppHost<AppServices> = RequestScopedHost<AppServices, unknown>;
+type AppHost<AppServices> = RequestScopedHost<AppServices, unknown> & {
+	forSystem?(): Promise<AppServices>;
+};

</code_context>
<issue_to_address>
**suggestion (bug_risk):** Making `forSystem` optional on `AppHost` but required by some handlers may hide configuration mistakes until runtime.

Queue handlers such as `communityUpdateQueueHandlerCreator` require a system-scoped host and will throw if `forSystem` is missing. By typing `forSystem` as optional on `AppHost`, misconfigured application-service factories will only fail at runtime. Consider either introducing a separate type (e.g. `SystemCapableAppHost`) or requiring `forSystem` on the host used to wire queue handlers, so the type system enforces this contract instead of relying on runtime checks.

Suggested implementation:

```typescript
		options: Omit<StorageQueueFunctionOptions<TMessage>, 'handler'>,
		handlerCreator: (applicationServicesHost: SystemCapableAppHost<AppServices>, infrastructureRegistry: InitializedServiceRegistry) => StorageQueueHandler<TMessage>,
	): AzureFunctionHandlerRegistry<ContextType, AppServices>;

```

1. If there are other queue (or system-scoped) handler creator signatures in this file that currently accept `AppHost<AppServices>` but require `forSystem`, update them to accept `SystemCapableAppHost<AppServices>` instead.
2. If any handlers in other files rely on a system-scoped host and currently type their parameter as `AppHost<AppServices>`, consider updating those to `SystemCapableAppHost<AppServices>` so the requirement is enforced at compile time.
</issue_to_address>

### Comment 3
<location path="packages/ocom/handler-queue-community-update/src/handler.ts" line_range="42-51" />
<code_context>
+	};
+};
+
+function buildTriggeredQueueMessage(message: CommunityUpdateMessage, invocationContext: InvocationContext) {
+	const triggeredMessage: {
+		payload: CommunityUpdateMessage;
+		id?: string;
+		popReceipt?: string;
+		dequeueCount?: number;
+	} = {
+		payload: message,
+	};
+
+	const id = pickString(invocationContext, ['id', 'messageId']);
+	if (id !== undefined) {
+		triggeredMessage.id = id;
+	}
+
+	const popReceipt = pickString(invocationContext, ['popReceipt']);
+	if (popReceipt !== undefined) {
+		triggeredMessage.popReceipt = popReceipt;
+	}
+
+	const dequeueCount = pickNumber(invocationContext, ['dequeueCount']);
+	if (dequeueCount !== undefined) {
+		triggeredMessage.dequeueCount = dequeueCount;
+	}
+
+	return triggeredMessage;
+}
+
</code_context>
<issue_to_address>
**suggestion:** `buildTriggeredQueueMessage` manually re-specifies the trigger message shape instead of reusing the shared `TriggeredQueueMessage` type.

This helper reconstructs the `{ payload, id?, popReceipt?, dequeueCount? }` shape even though `TriggeredQueueMessage<T>` exists in `queue-storage`. Returning `TriggeredQueueMessage<CommunityUpdateMessage>` (and typing `triggeredMessage` as such) would remove duplication and keep this code aligned with the shared contract as it evolves.

Suggested implementation:

```typescript
function buildTriggeredQueueMessage(
	message: CommunityUpdateMessage,
	invocationContext: InvocationContext,
): TriggeredQueueMessage<CommunityUpdateMessage> {
	const triggeredMessage: TriggeredQueueMessage<CommunityUpdateMessage> = {
		payload: message,
	};

```

1. Ensure `TriggeredQueueMessage` is imported at the top of `packages/ocom/handler-queue-community-update/src/handler.ts`, for example:

   `import { TriggeredQueueMessage } from 'queue-storage';`

   or from whatever the correct local package path is in this repo (e.g. `@tribe/queue-storage` or similar), matching existing usage elsewhere.
2. No changes are needed at the callsite: `buildTriggeredQueueMessage(message, invocationContext)` already matches the updated signature.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion (bug_risk): Defaulting the triggered message ID to a synthetic constant may make diagnosing issues harder.

Using the hardcoded 'triggered-message' means all messages without an ID become indistinguishable in logs and for any consumers relying on message.id. Consider either propagating undefined and requiring consumers to handle it, or deriving a more descriptive ID from available metadata to keep messages distinguishable for diagnostics and any ID-based logic.

Suggested implementation:

function toQueueMessage<TPayload>(triggeredMessage: TriggeredQueueMessage<TPayload>): QueueMessage<TPayload> {
	return {
		...(triggeredMessage.id !== undefined ? { id: triggeredMessage.id } : {}),
		payload: triggeredMessage.payload,
		...(triggeredMessage.popReceipt !== undefined ? { popReceipt: triggeredMessage.popReceipt } : {}),
		...(triggeredMessage.dequeueCount !== undefined ? { dequeueCount: triggeredMessage.dequeueCount } : {}),
	};
}

If the QueueMessage<TPayload> type currently requires a non-optional id: string, you should:

1. Update QueueMessage so that id is optional (e.g. id?: string) to reflect that some triggered messages legitimately do not have an ID.
2. Audit any consumers of QueueMessage that assume message.id is always present, and add appropriate handling (e.g. conditional logic or fallback generation localized to where it's needed) instead of relying on a synthetic constant ID.

[sourcery-ai]

suggestion (bug_risk): Making forSystem optional on AppHost but required by some handlers may hide configuration mistakes until runtime.

Queue handlers such as communityUpdateQueueHandlerCreator require a system-scoped host and will throw if forSystem is missing. By typing forSystem as optional on AppHost, misconfigured application-service factories will only fail at runtime. Consider either introducing a separate type (e.g. SystemCapableAppHost) or requiring forSystem on the host used to wire queue handlers, so the type system enforces this contract instead of relying on runtime checks.

Suggested implementation:

		options: Omit<StorageQueueFunctionOptions<TMessage>, 'handler'>,
		handlerCreator: (applicationServicesHost: SystemCapableAppHost<AppServices>, infrastructureRegistry: InitializedServiceRegistry) => StorageQueueHandler<TMessage>,
	): AzureFunctionHandlerRegistry<ContextType, AppServices>;

1. If there are other queue (or system-scoped) handler creator signatures in this file that currently accept AppHost<AppServices> but require forSystem, update them to accept SystemCapableAppHost<AppServices> instead.
2. If any handlers in other files rely on a system-scoped host and currently type their parameter as AppHost<AppServices>, consider updating those to SystemCapableAppHost<AppServices> so the requirement is enforced at compile time.

[sourcery-ai]

suggestion: buildTriggeredQueueMessage manually re-specifies the trigger message shape instead of reusing the shared TriggeredQueueMessage type.

This helper reconstructs the { payload, id?, popReceipt?, dequeueCount? } shape even though TriggeredQueueMessage<T> exists in queue-storage. Returning TriggeredQueueMessage<CommunityUpdateMessage> (and typing triggeredMessage as such) would remove duplication and keep this code aligned with the shared contract as it evolves.

Suggested implementation:

function buildTriggeredQueueMessage(
	message: CommunityUpdateMessage,
	invocationContext: InvocationContext,
): TriggeredQueueMessage<CommunityUpdateMessage> {
	const triggeredMessage: TriggeredQueueMessage<CommunityUpdateMessage> = {
		payload: message,
	};

1. Ensure TriggeredQueueMessage is imported at the top of packages/ocom/handler-queue-community-update/src/handler.ts, for example:

   import { TriggeredQueueMessage } from 'queue-storage';

   or from whatever the correct local package path is in this repo (e.g. @tribe/queue-storage or similar), matching existing usage elsewhere.

2. No changes are needed at the callsite: buildTriggeredQueueMessage(message, invocationContext) already matches the updated signature.