@gravito/echo 3.0.0 → 3.1.0

package/dist/core/src/reliability/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reliability and retry exports.
+ * @packageDocumentation
+ */
+export { DeadLetterQueueManager, type DLQManagerFilter, type DLQRecord, type DLQStats, } from './DeadLetterQueueManager';
+export { getDefaultRetryPolicy, getPresetRetryPolicy, RetryEngine, type RetryPolicy, } from './RetryPolicy';

package/dist/core/src/router/ControllerDispatcher.d.ts

@@ -0,0 +1,12 @@
+import type { GravitoHandler } from '../http/types';
+import type { PlanetCore } from '../PlanetCore';
+import type { ControllerClass } from '../Router';
+export declare class ControllerDispatcher {
+    private core;
+    private controllers;
+    constructor(core: PlanetCore);
+    /**
+     * Resolve Controller Instance and Method
+     */
+    resolve(CtrlClass: ControllerClass, methodName: string): GravitoHandler;
+}

package/dist/core/src/router/RequestValidator.d.ts

@@ -0,0 +1,20 @@
+import type { GravitoMiddleware } from '../http/types';
+import { type FormRequestClass } from '../Router';
+/**
+ * Handles validation of incoming requests using FormRequest classes.
+ * Provides mechanisms to detect and convert FormRequest classes into Gravito middleware.
+ */
+export declare class RequestValidator {
+    /**
+     * Check if a value is a FormRequest class.
+     * Optimized with Symbol check, prototype check, and caching.
+     * @internal
+     */
+    static isFormRequestClass(value: unknown): value is FormRequestClass;
+    /**
+     * Convert a FormRequest class to middleware.
+     * Uses instance caching to avoid re-instantiation on every request.
+     * @internal
+     */
+    static formRequestToMiddleware(RequestClass: FormRequestClass): GravitoMiddleware;
+}

package/dist/core/src/runtime.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Detected Javascript Runtime Environment
+ * @public
+ */
+export type RuntimeKind = 'bun' | 'node' | 'deno' | 'unknown';
+/**
+ * Options for spawning subprocesses
+ * @public
+ */
+export interface RuntimeSpawnOptions {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    stdin?: 'pipe' | 'inherit' | 'ignore';
+    stdout?: 'pipe' | 'inherit' | 'ignore';
+    stderr?: 'pipe' | 'inherit' | 'ignore';
+}
+/**
+ * Abstract subprocess interface
+ * @public
+ */
+export interface RuntimeProcess {
+    exited: Promise<number>;
+    stdout?: ReadableStream<Uint8Array> | null;
+    stderr?: ReadableStream<Uint8Array> | null;
+    kill?: (signal?: string | number) => void;
+}
+/**
+ * File statistics abstraction
+ * @public
+ */
+export interface RuntimeFileStat {
+    size: number;
+}
+/**
+ * HTTP Server configuration
+ * @public
+ */
+export interface RuntimeServeConfig {
+    port?: number;
+    fetch: (req: Request, server?: unknown) => Response | Promise<Response>;
+    websocket?: unknown;
+}
+/**
+ * HTTP Server interface
+ * @public
+ */
+export interface RuntimeServer {
+    stop?: () => void;
+}
+/**
+ * Abstraction layer for filesystem and process operations across runtimes.
+ * @public
+ */
+export interface RuntimeAdapter {
+    kind: RuntimeKind;
+    spawn(command: string[], options?: RuntimeSpawnOptions): RuntimeProcess;
+    writeFile(path: string, data: Blob | Buffer | string | ArrayBuffer | Uint8Array): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    readFileAsBlob(path: string): Promise<Blob>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<RuntimeFileStat>;
+    deleteFile(path: string): Promise<void>;
+    serve(config: RuntimeServeConfig): RuntimeServer;
+}
+/**
+ * Abstraction layer for password hashing
+ * @public
+ */
+export interface RuntimePasswordAdapter {
+    hash(value: string, options: {
+        algorithm: 'bcrypt';
+        cost?: number;
+    } | {
+        algorithm: 'argon2id';
+        memoryCost?: number;
+        timeCost?: number;
+        parallelism?: number;
+    }): Promise<string>;
+    verify(value: string, hashed: string): Promise<boolean>;
+}
+/**
+ * SQLite Statement abstraction
+ * @public
+ */
+export interface RuntimeSqliteStatement {
+    run(params?: Record<string, unknown>): void;
+    get(params?: Record<string, unknown>): unknown;
+    all(params?: Record<string, unknown>): unknown[];
+}
+/**
+ * SQLite Database abstraction
+ * @public
+ */
+export interface RuntimeSqliteDatabase {
+    run(sql: string): void;
+    prepare(sql: string): RuntimeSqliteStatement;
+    query(sql: string): RuntimeSqliteStatement;
+    close(): void;
+}
+/**
+ * Get environment variables from the current runtime.
+ * @public
+ */
+export declare const getRuntimeEnv: () => Record<string, string | undefined>;
+/**
+ * Get the runtime abstraction adapter (Bun/Node/Deno).
+ * @public
+ */
+export declare const getRuntimeAdapter: () => RuntimeAdapter;
+/**
+ * Get the password hashing adapter using native optimized implementations if available.
+ * @public
+ */
+export declare const getPasswordAdapter: () => RuntimePasswordAdapter;
+/**
+ * Create a SQLite database connection using runtime-native drivers.
+ * @public
+ */
+export declare const createSqliteDatabase: (path: string) => Promise<RuntimeSqliteDatabase>;

package/dist/core/src/security/Encrypter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Options for the Encrypter class.
+ * @public
+ */
+export interface EncrypterOptions {
+    key: string;
+    cipher?: string;
+}
+/**
+ * Service for OpenSSL encryption/decryption.
+ * Compatible with Laravel's encryption format.
+ * @public
+ */
+export declare class Encrypter {
+    private algorithm;
+    private key;
+    constructor(options: EncrypterOptions);
+    /**
+     * Encrypt a value
+     */
+    encrypt(value: unknown, serialize?: boolean): string;
+    /**
+     * Decrypt a value
+     */
+    decrypt(payload: string, deserialize?: boolean): unknown;
+    private hash;
+    private validPayload;
+    private validMac;
+    /**
+     * Generate a new key
+     */
+    static generateKey(cipher?: string): string;
+}

package/dist/core/src/security/Hasher.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hashing interface
+ */
+export interface Hasher {
+    /**
+     * Hash the given value
+     */
+    make(value: string, options?: Record<string, unknown>): Promise<string>;
+    /**
+     * Check the given plain value against a hash
+     */
+    check(value: string, hashedValue: string): Promise<boolean>;
+    /**
+     * Check if the given hash has been hashed using the given options
+     */
+    needsRehash(hashedValue: string, options?: Record<string, unknown>): boolean;
+}
+/**
+ * Bun Hasher
+ * Uses Bun's native password hashing (bcrypt by default)
+ */
+export declare class BunHasher implements Hasher {
+    make(value: string, options?: {
+        algorithm?: 'bcrypt' | 'argon2id';
+        cost?: number;
+    }): Promise<string>;
+    check(value: string, hashedValue: string): Promise<boolean>;
+    needsRehash(_hashedValue: string, _options?: Record<string, unknown>): boolean;
+}

package/dist/core/src/testing/HttpTester.d.ts

@@ -0,0 +1,39 @@
+import type { PlanetCore } from '../PlanetCore';
+import { TestResponse } from './TestResponse';
+/**
+ * HttpTester provides a way to simulate HTTP requests against a PlanetCore instance
+ * and returns a TestResponse for assertions.
+ */
+export declare class HttpTester {
+    private core;
+    private cookies;
+    constructor(core: PlanetCore);
+    /**
+     * Make a GET request
+     */
+    get(uri: string, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a POST request
+     */
+    post(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a PUT request
+     */
+    put(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a PATCH request
+     */
+    patch(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Make a DELETE request
+     */
+    delete(uri: string, data?: any, headers?: Record<string, string>): Promise<TestResponse>;
+    /**
+     * Core call method
+     */
+    private call;
+}
+/**
+ * Helper to create an HttpTester for a PlanetCore instance
+ */
+export declare function createHttpTester(core: PlanetCore): HttpTester;

package/dist/core/src/testing/TestResponse.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TestResponse wraps a standard Fetch Response and provides fluent assertion methods
+ * inspired by Laravel's TestResponse.
+ */
+export declare class TestResponse {
+    readonly response: Response;
+    private _jsonData;
+    private _textData;
+    constructor(response: Response);
+    /**
+     * Assert the response status code
+     */
+    assertStatus(status: number): this;
+    /**
+     * Assert that the response has a 200 status code
+     */
+    assertOk(): this;
+    /**
+     * Assert that the response has a 201 status code
+     */
+    assertCreated(): this;
+    /**
+     * Assert that the response has a 404 status code
+     */
+    assertNotFound(): this;
+    /**
+     * Assert that the response has a 403 status code
+     */
+    assertForbidden(): this;
+    /**
+     * Assert that the response has a 401 status code
+     */
+    assertUnauthorized(): this;
+    /**
+     * Assert the response is a redirect
+     */
+    assertRedirect(uri?: string): this;
+    /**
+     * Assert that the response contains the given JSON data.
+     */
+    assertJson(data: any): Promise<this>;
+    /**
+     * Assert that the response contains exactly the given JSON data.
+     */
+    assertExactJson(data: any): Promise<this>;
+    /**
+     * Assert the structure of the JSON response.
+     */
+    assertJsonStructure(structure: any): Promise<this>;
+    /**
+     * Assert that the response contains the given string.
+     */
+    assertSee(value: string): Promise<this>;
+    /**
+     * Assert that the response does not contain the given string.
+     */
+    assertDontSee(value: string): Promise<this>;
+    /**
+     * Assert a header exists and matches value
+     */
+    assertHeader(header: string, value: string): this;
+    /**
+     * Assert a header does not exist
+     */
+    assertHeaderMissing(header: string): this;
+    /**
+     * Get the JSON content
+     */
+    getJson(): Promise<any>;
+    /**
+     * Get the text content
+     */
+    getText(): Promise<string>;
+    /**
+     * Alias for getText for standard expectations if needed
+     */
+    get body(): Promise<string>;
+}

package/dist/core/src/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './HttpTester';
+export * from './TestResponse';

package/dist/core/src/types/events.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Event system type definitions.
+ */
+/**
+ * Listener interface.
+ *
+ * All event listeners must implement this interface.
+ */
+export interface Listener<TEvent extends Event = Event> {
+    /**
+     * Handle an event.
+     * @param event - Event instance
+     */
+    handle(event: TEvent): Promise<void> | void;
+}
+/**
+ * Marker interface for listeners that should be queued.
+ *
+ * Listeners implementing this interface can be dispatched asynchronously via a queue.
+ */
+export interface ShouldQueue {
+    /**
+     * Queue name (optional).
+     */
+    queue?: string;
+    /**
+     * Connection name (optional).
+     */
+    connection?: string;
+    /**
+     * Delay before execution (seconds).
+     */
+    delay?: number;
+}
+/**
+ * Marker interface for events that should be broadcast.
+ *
+ * Events implementing this interface can be automatically broadcast to clients.
+ */
+export interface ShouldBroadcast {
+    /**
+     * Define the broadcast channel.
+     * @returns Channel name or channel object
+     */
+    broadcastOn(): string | Channel;
+    /**
+     * Define broadcast payload (optional).
+     * If omitted, public event properties will be used.
+     * @returns Broadcast payload
+     */
+    broadcastWith?(): Record<string, unknown>;
+    /**
+     * Define the broadcast event name (optional).
+     * If omitted, the event class name will be used.
+     * @returns Event name
+     */
+    broadcastAs?(): string;
+}
+/**
+ * Channel interface.
+ */
+export interface Channel {
+    /**
+     * Channel name.
+     */
+    name: string;
+    /**
+     * Channel type.
+     */
+    type: 'public' | 'private' | 'presence';
+}
+/**
+ * Base event class.
+ *
+ * All events should extend this class.
+ */
+export declare abstract class Event {
+    /**
+     * Whether this event should be broadcast.
+     */
+    shouldBroadcast(): boolean;
+    /**
+     * Get broadcast channel.
+     */
+    getBroadcastChannel(): string | Channel | null;
+    /**
+     * Get broadcast payload.
+     */
+    getBroadcastData(): Record<string, unknown>;
+    /**
+     * Get broadcast event name.
+     */
+    getBroadcastEventName(): string;
+}

package/dist/echo/src/OrbitEcho.d.ts

@@ -0,0 +1,115 @@
+import type { GravitoOrbit, PlanetCore } from '@gravito/core';
+import { WebhookReceiver } from './receive/WebhookReceiver';
+import { KeyRotationManager } from './rotation/KeyRotationManager';
+import { WebhookDispatcher } from './send/WebhookDispatcher';
+import type { EchoConfig, ProviderKeyEntry } from './types';
+/**
+ * OrbitEcho is the official webhook orchestration module for the Gravito ecosystem.
+ *
+ * It serves as a comprehensive hub for managing the entire webhook lifecycle,
+ * including secure reception, signature verification across multiple providers,
+ * persistent storage for auditing, and reliable outgoing dispatch with
+ * exponential backoff and circuit breaking.
+ *
+ * @example Basic integration with PlanetCore
+ * ```typescript
+ * import { PlanetCore } from '@gravito/core';
+ * import { OrbitEcho } from '@gravito/echo';
+ *
+ * const core = new PlanetCore();
+ * const echo = new OrbitEcho({
+ *   providers: {
+ *     stripe: { name: 'stripe', secret: process.env.STRIPE_SECRET }
+ *   },
+ *   dispatcher: {
+ *     secret: process.env.APP_WEBHOOK_SECRET
+ *   }
+ * });
+ *
+ * core.install(echo);
+ * ```
+ *
+ * @public
+ */
+export declare class OrbitEcho implements GravitoOrbit {
+    private receiver;
+    private dispatcher?;
+    private echoConfig;
+    private keyRotationManager?;
+    /**
+     * Constructs a new OrbitEcho instance with the specified configuration.
+     *
+     * This constructor initializes the core receiver component, sets up key rotation
+     * orchestration if enabled, registers defined providers, and connects the
+     * observability stack (metrics, tracing, logging).
+     *
+     * @param config - The global configuration defining providers, dispatchers, and infrastructure.
+     */
+    constructor(config?: EchoConfig);
+    /**
+     * Integrates the Echo module into the Gravito application lifecycle.
+     *
+     * This method performs the following setup tasks:
+     * 1. Installs request buffering middleware (if enabled) to preserve raw bodies.
+     * 2. Binds Echo components to the service container (`echo`, `echo.receiver`).
+     * 3. Injects the Echo instance into the request context for easy access in handlers.
+     *
+     * @param core - The PlanetCore instance managing the application.
+     * @throws {Error} If the core adapter is missing or improperly configured.
+     */
+    install(core: PlanetCore): void;
+    /**
+     * Retrieves the underlying receiver instance for manual webhook processing.
+     *
+     * Use this when you need fine-grained control over how incoming webhooks
+     * are routed or verified outside of the standard middleware flow.
+     *
+     * @returns The active WebhookReceiver instance.
+     */
+    getReceiver(): WebhookReceiver;
+    /**
+     * Retrieves the dispatcher instance for sending outgoing webhooks.
+     *
+     * @returns The configured WebhookDispatcher, or undefined if dispatch is disabled.
+     */
+    getDispatcher(): WebhookDispatcher | undefined;
+    /**
+     * Accesses the active configuration used by this OrbitEcho instance.
+     *
+     * @returns The immutable EchoConfig object.
+     */
+    getConfig(): EchoConfig;
+    /**
+     * Retrieves the key rotation manager responsible for secret lifecycle.
+     *
+     * @returns The manager instance, or undefined if key rotation is disabled.
+     */
+    getKeyRotationManager(): KeyRotationManager | undefined;
+    /**
+     * Initiates a zero-downtime primary key rotation for a specific provider.
+     *
+     * This method promotes a new key to primary status while maintaining valid old keys
+     * for a grace period, ensuring that webhooks signed with either key are accepted
+     * during the transition.
+     *
+     * @param providerName - The identifier of the provider to update.
+     * @param newKey - Metadata and value for the replacement key.
+     * @throws {Error} If key rotation is not enabled in the global configuration.
+     *
+     * @example
+     * ```typescript
+     * await echo.rotateProviderKey('stripe', {
+     *   key: 'whsec_new_secret',
+     *   version: 'v2',
+     *   activeFrom: new Date()
+     * });
+     * ```
+     */
+    rotateProviderKey(providerName: string, newKey: Omit<ProviderKeyEntry, 'isPrimary'>): Promise<void>;
+}
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** Webhook receiver and dispatcher */
+        echo?: OrbitEcho;
+    }
+}

package/dist/echo/src/dlq/DeadLetterQueue.d.ts

@@ -0,0 +1,94 @@
+import type { IncomingWebhookRecord, OutgoingWebhookRecord } from '../storage/WebhookStore';
+/**
+ * Interface for a Dead Letter Queue (DLQ) implementation.
+ *
+ * A DLQ serves as a safety net for webhook events that have permanently failed
+ * all processing or delivery attempts. It enables manual inspection, diagnostic
+ * analysis, and eventual re-processing of high-value events that would otherwise
+ * be lost due to transient or permanent failures.
+ *
+ * @example Inspected failed events
+ * ```typescript
+ * const dlq: DeadLetterQueue = new MyPersistentDlq();
+ *
+ * // Retrieve recent failures for manual triage
+ * const failedEvents = await dlq.peek(10);
+ * for (const event of failedEvents) {
+ *   console.log(`Event ${event.id} failed after ${event.retryCount} attempts: ${event.failureReason}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface DeadLetterQueue {
+    /**
+     * Appends a permanently failed event to the queue for later inspection.
+     *
+     * @param event - The dead letter event metadata and original record.
+     * @returns A promise resolving to a unique identifier for the event within the queue.
+     * @throws {Error} If the underlying storage fails to persist the event.
+     */
+    enqueue(event: DeadLetterEvent): Promise<string>;
+    /**
+     * Retrieves a snapshot of failed events from the queue without removing them.
+     *
+     * @param limit - Maximum number of events to retrieve (ordered by failure time).
+     * @returns A collection of dead letter events.
+     */
+    peek(limit?: number): Promise<DeadLetterEvent[]>;
+    /**
+     * Permanently removes an event from the queue after successful manual resolution.
+     *
+     * @param id - The unique identifier assigned during the `enqueue` process.
+     * @throws {Error} If the event ID is invalid or not found in the queue.
+     */
+    dequeue(id: string): Promise<void>;
+    /**
+     * Calculates the total number of events currently residing in the queue.
+     *
+     * @returns The total count of dead letter events.
+     */
+    size(): Promise<number>;
+    /**
+     * Removes all events from the queue, resetting it to an empty state.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Metadata and payload for a failed webhook event stored in the Dead Letter Queue.
+ *
+ * This structure captures the complete context of a failure, including the original
+ * data and the diagnostic reason for the final failure.
+ *
+ * @public
+ */
+export interface DeadLetterEvent {
+    /**
+     * A unique identifier for the entry within the DLQ storage.
+     */
+    id?: string;
+    /**
+     * Indicates whether the failure occurred during reception or dispatch.
+     */
+    type: 'incoming' | 'outgoing';
+    /**
+     * The complete original record of the webhook at the moment of failure.
+     */
+    originalEvent: IncomingWebhookRecord | OutgoingWebhookRecord;
+    /**
+     * A descriptive diagnostic message explaining why the event was sent to the DLQ.
+     */
+    failureReason: string;
+    /**
+     * The exact timestamp when the event reached its maximum retry limit or terminal error.
+     */
+    failedAt: Date;
+    /**
+     * The total number of automated attempts made before giving up on the event.
+     */
+    retryCount: number;
+    /**
+     * The timestamp of the final attempted processing or delivery action.
+     */
+    lastRetryAt?: Date;
+}

package/dist/echo/src/dlq/MemoryDeadLetterQueue.d.ts

@@ -0,0 +1,36 @@
+import type { DeadLetterEvent, DeadLetterQueue } from './DeadLetterQueue';
+/**
+ * An in-memory implementation of {@link DeadLetterQueue}.
+ * Suitable for development, testing, or small-scale applications where persistence is not required.
+ *
+ * @example
+ * ```typescript
+ * const dlq = new MemoryDeadLetterQueue();
+ * await dlq.enqueue(failedEvent);
+ * const size = await dlq.size();
+ * ```
+ */
+export declare class MemoryDeadLetterQueue implements DeadLetterQueue {
+    private queue;
+    /**
+     * Stores the event in an internal Map.
+     * Generates a UUID if the event does not have an ID.
+     */
+    enqueue(event: DeadLetterEvent): Promise<string>;
+    /**
+     * Returns events sorted by failure timestamp.
+     */
+    peek(limit?: number): Promise<DeadLetterEvent[]>;
+    /**
+     * Removes the event from the internal Map.
+     */
+    dequeue(id: string): Promise<void>;
+    /**
+     * Returns the number of items in the internal Map.
+     */
+    size(): Promise<number>;
+    /**
+     * Clears the internal Map.
+     */
+    clear(): Promise<void>;
+}

package/dist/echo/src/dlq/index.d.ts

@@ -0,0 +1,2 @@
+export * from './DeadLetterQueue';
+export * from './MemoryDeadLetterQueue';