@gravito/echo 3.1.1 → 3.1.2

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

@@ -1,119 +0,0 @@
-/**
- * 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

@@ -1,33 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-/**
- * 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

@@ -1,39 +0,0 @@
-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

@@ -1,78 +0,0 @@
-/**
- * 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

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

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

@@ -1,94 +0,0 @@
-/**
- * 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

@@ -1,115 +0,0 @@
-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/index.d.ts

@@ -1,64 +0,0 @@
-/**
- * @fileoverview \@gravito/echo - Enterprise Webhook Orchestration
- *
- * Echo provides a secure, reliable, and observable layer for handling webhooks
- * in Gravito applications. It standardizes incoming webhook reception with
- * signature verification and dynamic key rotation, while ensuring reliable
- * outgoing delivery via exponential backoff and circuit breaking.
- *
- * @example Receiving webhooks from Stripe
- * ```typescript
- * import { OrbitEcho, WebhookReceiver } from '@gravito/echo'
- *
- * const core = new PlanetCore()
- * core.install(new OrbitEcho({
- *   providers: {
- *     stripe: { name: 'stripe', secret: process.env.STRIPE_SECRET! }
- *   }
- * }))
- *
- * const receiver = core.container.make<WebhookReceiver>('echo.receiver')
- * receiver.on('stripe', 'payment_intent.succeeded', async (event) => {
- *   // Securely process validated payment
- * })
- * ```
- *
- * @example Dispatching reliable outgoing webhooks
- * ```typescript
- * import { WebhookDispatcher } from '@gravito/echo'
- *
- * const dispatcher = new WebhookDispatcher({ secret: 'app-secret' })
- * await dispatcher.dispatch({
- *   url: 'https://consumer.com/hook',
- *   event: 'order.created',
- *   data: { id: 123 }
- * })
- * ```
- *
- * @module @gravito/echo
- */
-export type { DeadLetterEvent, DeadLetterQueue } from './dlq/DeadLetterQueue';
-export { MemoryDeadLetterQueue } from './dlq/MemoryDeadLetterQueue';
-export { createRequestBufferMiddleware, RequestBufferMiddleware } from './middleware';
-export { OrbitEcho } from './OrbitEcho';
-export type { EchoLogEvent, EchoLogger } from './observability/logging';
-export { ConsoleEchoLogger } from './observability/logging';
-export type { MetricsProvider, WebhookMetricLabels } from './observability/metrics';
-export { EchoMetrics, NoopMetricsProvider, PrometheusMetricsProvider, } from './observability/metrics';
-export type { Span, SpanOptions, Tracer } from './observability/tracing';
-export { NoopSpan, NoopTracer, SpanStatusCode } from './observability/tracing';
-export { BaseProvider, type ProviderOptions } from './providers/base/BaseProvider';
-export { GenericProvider } from './providers/GenericProvider';
-export { GitHubProvider } from './providers/GitHubProvider';
-export { LinearProvider } from './providers/LinearProvider';
-export { PaddleProvider } from './providers/PaddleProvider';
-export { ShopifyProvider } from './providers/ShopifyProvider';
-export { SlackProvider } from './providers/SlackProvider';
-export { StripeProvider } from './providers/StripeProvider';
-export { TwilioProvider } from './providers/TwilioProvider';
-export { computeHmacSha1, computeHmacSha256, parseStripeSignature, timingSafeEqual, validateTimestamp, } from './receive/SignatureValidator';
-export { WebhookReceiver } from './receive/WebhookReceiver';
-export { WebhookReplayService } from './replay/WebhookReplayService';
-export { CircuitBreaker } from './resilience';
-export { KeyRotationManager } from './rotation';
-export type { BufferedRequest, CircuitBreakerConfig, CircuitBreakerMetrics, CircuitBreakerState, EchoConfig, EchoObservabilityConfig, KeyRotationConfig, ProviderKeyEntry, ReplayOptions, ReplayResult, RequestBufferConfig, RetryConfig, WebhookDeliveryResult, WebhookDispatcherConfig, WebhookEvent, WebhookHandler, WebhookPayload, WebhookProvider, WebhookProviderConfig, WebhookProviderConfigWithRotation, WebhookVerificationResult, } from './types';

package/dist/echo/src/providers/GenericProvider.d.ts

@@ -1,53 +0,0 @@
-/**
- * Generic webhook provider.
- * @module @gravito/echo/providers
- */
-import type { WebhookVerificationResult } from '../types';
-import { BaseProvider, type ProviderOptions } from './base/BaseProvider';
-/**
- * Configuration options for the generic provider.
- */
-export interface GenericProviderOptions extends ProviderOptions {
-    /**
-     * Custom header name for the signature.
-     * @defaultValue 'x-webhook-signature'
-     */
-    signatureHeader?: string;
-    /**
-     * Custom header name for the timestamp.
-     * @defaultValue 'x-webhook-timestamp'
-     */
-    timestampHeader?: string;
-}
-/**
- * Generic webhook provider using HMAC-SHA256 for signature verification.
- *
- * Expected headers:
- * - X-Webhook-Signature: HMAC-SHA256 hex signature.
- * - X-Webhook-Timestamp: Unix timestamp (optional, used for replay protection).
- *
- * @example
- * ```typescript
- * const provider = new GenericProvider({
- *   signatureHeader: 'X-Custom-Sig',
- *   tolerance: 600
- * });
- * const result = await provider.verify(body, headers, secret);
- * ```
- */
-export declare class GenericProvider extends BaseProvider {
-    readonly name = "generic";
-    private signatureHeader;
-    private timestampHeader;
-    constructor(options?: GenericProviderOptions);
-    /**
-     * Verifies the webhook using HMAC-SHA256.
-     *
-     * @param payload - Raw request body.
-     * @param headers - Request headers.
-     * @param secret - Secret key for HMAC computation.
-     * @returns Verification result.
-     * @throws Error if signature computation fails.
-     */
-    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
-}

package/dist/echo/src/providers/GitHubProvider.d.ts

@@ -1,35 +0,0 @@
-/**
- * GitHub webhook provider.
- * @module @gravito/echo/providers
- */
-import type { WebhookVerificationResult } from '../types';
-import { BaseProvider } from './base/BaseProvider';
-/**
- * GitHub webhook provider.
- *
- * Verifies GitHub webhook signatures using the `X-Hub-Signature-256` header.
- * @see {@link https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries | GitHub Webhook Validation}
- *
- * @example
- * ```typescript
- * const provider = new GitHubProvider();
- * const result = await provider.verify(body, headers, process.env.GITHUB_WEBHOOK_SECRET);
- * ```
- */
-export declare class GitHubProvider extends BaseProvider {
-    readonly name = "github";
-    /**
-     * Verifies the GitHub webhook signature.
-     *
-     * @param payload - Raw request body.
-     * @param headers - Request headers.
-     * @param secret - GitHub webhook secret.
-     * @returns Verification result.
-     * @throws Error if signature computation fails.
-     */
-    verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string): Promise<WebhookVerificationResult>;
-    /**
-     * Extracts the action from the GitHub payload if available.
-     */
-    parseEventType(payload: unknown): string | undefined;
-}