@cratis/chronicle 0.1.0 → 0.2.0

package/webhooks/WebhookDefinitionBuilder.ts

@@ -0,0 +1,144 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type {
+    BasicAuthorization,
+    BearerTokenAuthorization,
+    OAuthAuthorization,
+    OneOfBasicAuthorizationBearerTokenAuthorizationOAuthAuthorization,
+    WebhookDefinition
+} from '@cratis/chronicle.contracts';
+import { Constructor } from '@cratis/fundamentals';
+import { IEventTypes } from '../events/IEventTypes';
+import { getEventTypeFor } from '../events/eventTypeDecorator';
+import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
+import { WebhookId } from './WebhookId';
+import { WebhookTargetUrl } from './WebhookTargetUrl';
+
+/**
+ * Implements {@link IWebhookDefinitionBuilder}.
+ */
+export class WebhookDefinitionBuilder implements IWebhookDefinitionBuilder {
+    private readonly _eventTypes = new Set<Constructor>();
+    private readonly _headers = new Map<string, string>();
+    private _eventSequenceId = EventSequenceId.eventLog.value;
+    private _authorization: OneOfBasicAuthorizationBearerTokenAuthorizationOAuthAuthorization | undefined;
+    private _isReplayable = true;
+    private _isActive = true;
+
+    /**
+     * Creates a new builder.
+     * @param _registeredEventTypes - Registered event types.
+     */
+    constructor(private readonly _registeredEventTypes: IEventTypes) {}
+
+    /** @inheritdoc */
+    onEventSequence(eventSequenceId: EventSequenceId): IWebhookDefinitionBuilder {
+        this._eventSequenceId = eventSequenceId.value;
+        return this;
+    }
+
+    /** @inheritdoc */
+    withBasicAuth(username: string, password: string): IWebhookDefinitionBuilder {
+        const value: BasicAuthorization = {
+            Username: username,
+            Password: password
+        };
+        this._authorization = {
+            Value0: value,
+            Value1: undefined,
+            Value2: undefined
+        };
+        return this;
+    }
+
+    /** @inheritdoc */
+    withBearerToken(token: string): IWebhookDefinitionBuilder {
+        const value: BearerTokenAuthorization = { Token: token };
+        this._authorization = {
+            Value0: undefined,
+            Value1: value,
+            Value2: undefined
+        };
+        return this;
+    }
+
+    /** @inheritdoc */
+    withOAuth(authority: string, clientId: string, clientSecret: string): IWebhookDefinitionBuilder {
+        const value: OAuthAuthorization = {
+            Authority: authority,
+            ClientId: clientId,
+            ClientSecret: clientSecret
+        };
+        this._authorization = {
+            Value0: undefined,
+            Value1: undefined,
+            Value2: value
+        };
+        return this;
+    }
+
+    /** @inheritdoc */
+    withHeader(key: string, value: string): IWebhookDefinitionBuilder {
+        this._headers.set(key, value);
+        return this;
+    }
+
+    /** @inheritdoc */
+    withEventType(eventType: Constructor): IWebhookDefinitionBuilder {
+        this._eventTypes.add(eventType);
+        return this;
+    }
+
+    /** @inheritdoc */
+    notReplayable(): IWebhookDefinitionBuilder {
+        this._isReplayable = false;
+        return this;
+    }
+
+    /** @inheritdoc */
+    notActive(): IWebhookDefinitionBuilder {
+        this._isActive = false;
+        return this;
+    }
+
+    /**
+     * Builds a webhook definition.
+     * When no event types are explicitly configured, all registered event types are used.
+     * @param id - Webhook identifier.
+     * @param targetUrl - Webhook target URL.
+     * @returns A contract webhook definition.
+     */
+    build(id: WebhookId, targetUrl: WebhookTargetUrl): WebhookDefinition {
+        if (!targetUrl.value) {
+            throw new Error(`Webhook '${id.value}' has an empty target URL.`);
+        }
+
+        const selectedEventTypes = this._eventTypes.size > 0 ? [...this._eventTypes] : this._registeredEventTypes.all;
+        const eventTypes = selectedEventTypes.map(type => {
+            const metadata = getEventTypeFor(type);
+            if (metadata.id.value === '00000000-0000-0000-0000-000000000000') {
+                throw new Error(`Event type '${type.name}' has an invalid or uninitialized event type id.`);
+            }
+            return {
+                Id: metadata.id.value,
+                Generation: metadata.generation.value,
+                Tombstone: false
+            };
+        });
+
+        return {
+            EventSequenceId: this._eventSequenceId,
+            Identifier: id.value,
+            EventTypes: eventTypes,
+            Target: {
+                Url: targetUrl.value,
+                Authorization: this._authorization,
+                Headers: Object.fromEntries(this._headers)
+            },
+            IsReplayable: this._isReplayable,
+            IsActive: this._isActive
+        };
+    }
+}

package/webhooks/WebhookId.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the unique identifier of a webhook.
+ */
+export class WebhookId {
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}

package/webhooks/WebhookTargetUrl.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents the target URL for a webhook.
+ */
+export class WebhookTargetUrl {
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}

package/webhooks/Webhooks.ts

@@ -0,0 +1,125 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ObserverOwner, type WebhookDefinition } from '@cratis/chronicle.contracts';
+import { Constructor } from '@cratis/fundamentals';
+import { IClientArtifactsProvider } from '../artifacts';
+import { ChronicleConnection } from '../connection';
+import { EventSequenceId } from '../eventSequences/EventSequenceId';
+import { IEventTypes } from '../events/IEventTypes';
+import { IWebhook } from './IWebhook';
+import { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
+import { IWebhooks } from './IWebhooks';
+import { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder';
+import { WebhookId } from './WebhookId';
+import { WebhookTargetUrl } from './WebhookTargetUrl';
+import { getWebhookMetadata } from './webhook';
+
+/**
+ * Implements {@link IWebhooks}.
+ */
+export class Webhooks implements IWebhooks {
+    private readonly _discovered = new Map<string, WebhookDefinition>();
+
+    /**
+     * Creates a new {@link Webhooks} instance.
+     * @param _eventStore - Event store name.
+     * @param _connection - Chronicle connection.
+     * @param _eventTypes - Event types manager.
+     * @param _clientArtifacts - Client artifacts provider.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _connection: ChronicleConnection,
+        private readonly _eventTypes: IEventTypes,
+        private readonly _clientArtifacts: IClientArtifactsProvider
+    ) {}
+
+    /** @inheritdoc */
+    async discover(): Promise<void> {
+        this._discovered.clear();
+        for (const type of this._clientArtifacts.webhooks) {
+            const metadata = getWebhookMetadata(type);
+            if (!metadata) {
+                continue;
+            }
+
+            const definition = this.buildDefinition(type, metadata.id, metadata.targetUrl, undefined, metadata.eventSequenceId);
+            this._discovered.set(metadata.id.value, definition);
+        }
+    }
+
+    /** @inheritdoc */
+    async registerDiscovered(): Promise<void> {
+        if (this._discovered.size === 0) {
+            await this.discover();
+        }
+
+        if (this._discovered.size === 0) {
+            return;
+        }
+
+        await this._connection.webhooks.add({
+            EventStore: this._eventStore,
+            Owner: ObserverOwner.Client,
+            Webhooks: [...this._discovered.values()]
+        });
+    }
+
+    /** @inheritdoc */
+    async register(
+        webhookId: WebhookId | string,
+        targetUrl: WebhookTargetUrl | string,
+        configure: (builder: IWebhookDefinitionBuilder) => void
+    ): Promise<void> {
+        const definition = this.buildDefinition(
+            undefined,
+            typeof webhookId === 'string' ? new WebhookId(webhookId) : webhookId,
+            typeof targetUrl === 'string' ? new WebhookTargetUrl(targetUrl) : targetUrl,
+            configure
+        );
+
+        await this._connection.webhooks.add({
+            EventStore: this._eventStore,
+            Owner: ObserverOwner.Client,
+            Webhooks: [definition]
+        });
+    }
+
+    /** @inheritdoc */
+    async getWebhooks(): Promise<WebhookDefinition[]> {
+        const response = await this._connection.webhooks.getWebhooks({ EventStore: this._eventStore });
+        return response.items ?? [];
+    }
+
+    /** @inheritdoc */
+    async remove(webhookId: WebhookId | string): Promise<void> {
+        const id = typeof webhookId === 'string' ? webhookId : webhookId.value;
+        await this._connection.webhooks.remove({
+            EventStore: this._eventStore,
+            Webhooks: [id]
+        });
+    }
+
+    private buildDefinition(
+        type: Constructor | undefined,
+        id: WebhookId,
+        targetUrl: WebhookTargetUrl,
+        configure: ((builder: IWebhookDefinitionBuilder) => void) | undefined,
+        eventSequenceId?: string
+    ): WebhookDefinition {
+        const builder = new WebhookDefinitionBuilder(this._eventTypes);
+        configure?.(builder);
+
+        if (type) {
+            const instance = new (type as new () => IWebhook)();
+            instance.define(builder);
+        }
+
+        if (eventSequenceId) {
+            builder.onEventSequence(new EventSequenceId(eventSequenceId));
+        }
+
+        return builder.build(id, targetUrl);
+    }
+}

package/webhooks/index.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { WebhookId } from './WebhookId';
+export { WebhookTargetUrl } from './WebhookTargetUrl';
+export { webhook, getWebhookMetadata, isWebhook } from './webhook';
+export type { WebhookMetadata } from './webhook';
+export type { IWebhook } from './IWebhook';
+export type { IWebhookDefinitionBuilder } from './IWebhookDefinitionBuilder';
+export type { IWebhooks } from './IWebhooks';
+export { WebhookDefinitionBuilder } from './WebhookDefinitionBuilder';
+export { Webhooks } from './Webhooks';

package/webhooks/webhook.ts

@@ -0,0 +1,83 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import 'reflect-metadata';
+import { Constructor } from '@cratis/fundamentals';
+import { DecoratorType, TypeDiscoverer } from '../types';
+import { WebhookId } from './WebhookId';
+import { WebhookTargetUrl } from './WebhookTargetUrl';
+
+/** Metadata key used to store webhook information on a class. */
+const WEBHOOK_METADATA_KEY = 'chronicle:webhook';
+
+/**
+ * Metadata stored on a webhook class.
+ */
+export interface WebhookMetadata {
+    /** The webhook identifier. */
+    readonly id: WebhookId;
+
+    /** The webhook target URL. */
+    readonly targetUrl: WebhookTargetUrl;
+
+    /** Optional explicit event sequence id. */
+    readonly eventSequenceId: string | undefined;
+}
+
+/**
+ * TypeScript decorator that marks a class as a discoverable webhook.
+ * Overloads:
+ * - `@webhook(targetUrl)` -> class name is used as identifier.
+ * - `@webhook(id, targetUrl)` -> explicit identifier.
+ * - `@webhook(id, targetUrl, eventSequenceId)` -> explicit identifier and event sequence.
+ * @param idOrTargetUrl - The webhook identifier or target URL.
+ * @param targetUrlOrUndefined - The webhook target URL when id is provided.
+ * @param eventSequenceId - Optional event sequence identifier.
+ * @returns A class decorator.
+ */
+export function webhook(targetUrl: string): ClassDecorator;
+export function webhook(id: string, targetUrl: string): ClassDecorator;
+export function webhook(id: string, targetUrl: string, eventSequenceId: string): ClassDecorator;
+export function webhook(idOrTargetUrl: string, targetUrlOrUndefined?: string, eventSequenceId?: string): ClassDecorator {
+    return (target: object) => {
+        const hasExplicitId = targetUrlOrUndefined !== undefined;
+        const explicitId = hasExplicitId ? idOrTargetUrl : undefined;
+        const resolvedTargetUrl = hasExplicitId ? targetUrlOrUndefined : idOrTargetUrl;
+
+        if (!resolvedTargetUrl) {
+            throw new Error('A webhook targetUrl must be a non-empty string for @webhook.');
+        }
+
+        const constructor = target as Function;
+        const webhookId = new WebhookId(explicitId ?? constructor.name);
+        const metadata: WebhookMetadata = {
+            id: webhookId,
+            targetUrl: new WebhookTargetUrl(resolvedTargetUrl),
+            eventSequenceId
+        };
+        Reflect.defineMetadata(WEBHOOK_METADATA_KEY, metadata, target);
+        TypeDiscoverer.default.register(
+            DecoratorType.Webhook,
+            constructor as Constructor,
+            webhookId.value
+        );
+    };
+}
+
+/**
+ * Gets webhook metadata from a webhook class.
+ * @param target - The class constructor.
+ * @returns The metadata, if any.
+ */
+export function getWebhookMetadata(target: Function): WebhookMetadata | undefined {
+    return Reflect.getMetadata(WEBHOOK_METADATA_KEY, target);
+}
+
+/**
+ * Checks whether a class has webhook metadata.
+ * @param target - The class constructor.
+ * @returns True when decorated as webhook.
+ */
+export function isWebhook(target: Function): boolean {
+    return Reflect.hasMetadata(WEBHOOK_METADATA_KEY, target);
+}

package/EventSequences/AppendOptions.ts

@@ -1,15 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { Guid } from '@cratis/fundamentals';
-
-/**
- * Options for appending an event to an event sequence.
- */
-export interface AppendOptions {
-    /** Optional correlation identifier for tracking the append operation. */
-    correlationId?: string | Guid;
-
-    /** Optional explicit sequence number to use for the event. */
-    eventSourceId?: string;
-}

package/EventSequences/EventLog.ts

@@ -1,21 +0,0 @@
-// Copyright (c) Cratis. All rights reserved.
-// Licensed under the MIT license. See LICENSE file in the project root for full license information.
-
-import { ChronicleConnection } from '../connection';
-import { EventSequence } from './EventSequence';
-import { EventSequenceId } from './EventSequenceId';
-import { IEventLog } from './IEventLog';
-
-/**
- * Implements {@link IEventLog} by extending the base {@link EventSequence}.
- * The event log is the default event sequence used for all domain events.
- */
-export class EventLog extends EventSequence implements IEventLog {
-    constructor(
-        eventStoreName: string,
-        namespace: string,
-        connection: ChronicleConnection
-    ) {
-        super(EventSequenceId.eventLog, eventStoreName, namespace, connection);
-    }
-}