@teever/ez-hook-effect 0.4.4

package/README.md

@@ -0,0 +1,265 @@
+# @teever/ez-hook-effect
+
+A Discord webhook library built with [Effect](https://effect.website/) - type-safe, composable, and resilient.
+
+## Features
+
+- **Type-safe** - Runtime validation with Effect schemas
+- **Composable** - Functional programming patterns with Effect
+- **Error Handling** - Comprehensive error tracking with structured validation issues
+- **Retry Logic** - Built-in exponential backoff with jitter
+- **Dependency Injection** - Layer-based architecture
+- **Validated** - All Discord webhook constraints enforced
+- **One Dependency** - Only requires Effect
+- **Environment Support** - Configure via environment variables
+- **CRUD Operations** - Send, get, modify, delete, and validate webhooks
+
+## Installation
+
+```bash
+bunx jsr add @teever/ez-hook-effect
+# or
+npx jsr add @teever/ez-hook-effect
+```
+
+## Quick Start
+
+```typescript
+import { Effect, Layer, pipe } from 'effect'
+import { sendWebhook, makeConfigLayer, HttpClientLive, WebhookServiceLive, Webhook } from '@teever/ez-hook-effect'
+
+// Configure your webhook
+const WEBHOOK_URL = 'https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN'
+
+// Create service layers
+const AppLayer = WebhookServiceLive.pipe(
+  Layer.provide(makeConfigLayer(WEBHOOK_URL)),
+  Layer.provide(HttpClientLive)
+)
+
+// Send a simple message
+const program = pipe(
+  Webhook.make,
+  Webhook.setContent('Hello from Effect!'),
+  Webhook.setUsername('My Bot'),
+  Webhook.build,
+  Effect.flatMap(sendWebhook)
+)
+
+// Run the program
+Effect.runPromise(Effect.provide(program, AppLayer))
+```
+
+### Pipe-First API (Recommended)
+
+Prefer composing with `pipe` for ergonomic, Effect-style data assembly. This library uses a single, pipe-first API (no OO builders).
+
+```ts
+import { Effect, pipe } from 'effect'
+import { Webhook, Embed, sendWebhook } from '@teever/ez-hook-effect'
+
+const program = pipe(
+  Embed.make,
+  Embed.setTitle('System Status'),
+  Embed.setDescription('All systems operational'),
+  Embed.setColor(0x00ff00),
+  Embed.addField('CPU', '45%', true),
+  Embed.setTimestamp(),
+  Embed.build,
+  Effect.flatMap((embed) =>
+    pipe(
+      Webhook.make,
+      Webhook.setContent('📊 Status Update'),
+      Webhook.setUsername('Ez-Hook Bot'),
+      Webhook.addEmbed(embed),
+      Webhook.build
+    )
+  ),
+  Effect.flatMap(sendWebhook)
+)
+```
+
+## Building Rich Embeds
+
+```typescript
+const embedProgram = pipe(
+  Embed.make,
+  Embed.setTitle('Server Status'),
+  Embed.setDescription('All systems operational'),
+  Embed.setColor(0x00FF00),
+  Embed.addField('CPU', '45%', true),
+  Embed.addField('Memory', '2.1GB', true),
+  Embed.addField('Uptime', '15 days', true),
+  Embed.build,
+  Effect.flatMap((embed) =>
+    pipe(
+      Webhook.make,
+      Webhook.setContent('Daily Report'),
+      Webhook.addEmbed(embed),
+      Webhook.build
+    )
+  ),
+  Effect.flatMap(sendWebhook)
+)
+```
+
+## Error Handling
+
+Retries for rate limits (429) and transient errors (5xx) are handled automatically using configurable exponential backoff. You only need to handle errors that persist after retries are exhausted:
+
+```typescript
+import { Effect, pipe } from 'effect'
+import { Webhook, sendWebhook, ValidationError, HttpError, NetworkError, RateLimitError, WebhookError } from '@teever/ez-hook-effect'
+
+const program = pipe(
+  Webhook.make,
+  Webhook.setContent('Hello!'),
+  Webhook.build,
+  Effect.flatMap(sendWebhook),
+  Effect.catchTag('ValidationError', (error) =>
+    Effect.logError(`Validation failed: ${error.message}`)
+  ),
+  Effect.catchTag('RateLimitError', (error) =>
+    Effect.logError(`Rate limited: retry after ${error.retryAfter}ms`)
+  ),
+  Effect.catchTag('HttpError', (error) =>
+    Effect.logError(`Request failed: ${error.message}`)
+  ),
+  Effect.catchTag('NetworkError', (error) =>
+    Effect.logError(`Network error: ${error.message}`)
+  ),
+  Effect.catchTag('WebhookError', (error) =>
+    Effect.logError(`Webhook error: ${error.message}`)
+  )
+)
+```
+
+### Structured Validation Errors
+
+Validation errors include detailed issue information:
+
+```typescript
+Effect.catchTag('ValidationError', (error) =>
+  Effect.logError(`Validation failed:\n${error.format()}`)
+)
+```
+
+## Configuration Options
+
+### Programmatic Configuration
+
+```typescript
+const AppLayer = WebhookServiceLive.pipe(
+  Layer.provide(makeConfigLayer(WEBHOOK_URL, {
+    maxRetries: 5,        // Maximum retry attempts
+    baseDelayMs: 1000,    // Base delay for exponential backoff
+    maxDelayMs: 60000,    // Maximum delay between retries
+    enableJitter: true    // Add randomness to retry delays
+  })),
+  Layer.provide(HttpClientLive)
+)
+```
+
+### Environment Variables
+
+```typescript
+import { ConfigFromEnv, HttpClientLive, WebhookServiceLive } from '@teever/ez-hook-effect'
+
+// Reads from DISCORD_WEBHOOK_URL, WEBHOOK_MAX_RETRIES, etc.
+const AppLayer = WebhookServiceLive.pipe(
+  Layer.provide(ConfigFromEnv),
+  Layer.provide(HttpClientLive)
+)
+
+# Available environment variables:
+# DISCORD_WEBHOOK_URL     - Webhook URL (required)
+# WEBHOOK_MAX_RETRIES     - Maximum retry attempts (default: 3)
+# WEBHOOK_BASE_DELAY_MS   - Base delay in ms (default: 1000)
+# WEBHOOK_MAX_DELAY_MS    - Maximum delay in ms (default: 60000)
+# WEBHOOK_ENABLE_JITTER   - Enable jitter (default: true)
+```
+
+### Parse Webhook URL
+
+Extract webhook ID and token from a URL:
+
+```typescript
+import { parseWebhookUrl } from '@teever/ez-hook-effect'
+
+const result = await Effect.runPromise(
+  parseWebhookUrl('https://discord.com/api/webhooks/123456789/token')
+)
+// result: { id: '123456789', token: 'token' }
+```
+
+## Webhook Operations
+
+Beyond sending messages, the library supports full webhook CRUD:
+
+```typescript
+import { Effect, Layer, pipe } from 'effect'
+import { getWebhook, modifyWebhook, deleteWebhook, validateWebhook, WebhookServiceLive, makeConfigLayer, HttpClientLive } from '@teever/ez-hook-effect'
+
+const AppLayer = WebhookServiceLive.pipe(
+  Layer.provide(makeConfigLayer(WEBHOOK_URL)),
+  Layer.provide(HttpClientLive)
+)
+
+const program = Effect.gen(function* () {
+  const service = yield* WebhookService
+
+  // Check if webhook is valid and accessible
+  const isValid = yield* service.validateWebhook()
+
+  // Get webhook information
+  const info = yield* service.getWebhook()
+
+  // Modify webhook settings
+  const modified = yield* service.modifyWebhook({
+    name: 'New Name',
+  })
+
+  // Delete the webhook
+  const deleted = yield* service.deleteWebhook()
+})
+
+Effect.runPromise(Effect.provide(program, AppLayer))
+```
+
+## Development
+
+```bash
+bun run lint          # Biome lint + format
+bun run typecheck     # TypeScript type checking
+```
+
+## Testing
+
+The library includes comprehensive tests for all features:
+
+```bash
+bun test              # Run all tests
+bun test:watch        # Watch mode
+bun test:coverage     # Coverage report
+```
+
+## Building
+
+```bash
+bun run build         # Build the library
+bun run build:standalone  # Create standalone executable
+```
+
+## Examples
+
+Check out the `examples/` directory:
+
+- `01-basic-webhook.ts` - Send a simple message
+- `02-rich-embeds.ts` - Build embeds with fields, colors, metadata
+- `03-error-handling.ts` - Validation errors and recovery patterns
+- `04-multiple-embeds.ts` - Add several embeds to one webhook
+- `05-service-layer.ts` - Dependency injection with layers and CRUD operations
+
+## License
+
+MIT

package/dist/errors/WebhookError.d.ts

@@ -0,0 +1,156 @@
+import { type ParseResult } from "effect";
+declare const WebhookError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WebhookError";
+} & Readonly<A>;
+/**
+ * Base error class for all webhook-related errors
+ */
+export declare class WebhookError extends WebhookError_base<{
+    message: string;
+    cause?: unknown;
+}> {
+}
+/**
+ * Structured validation issue with path and constraint details
+ */
+export interface ValidationIssue {
+    /** JSONPath-style path to the invalid field, e.g. "$.embeds[0].fields[2].name" */
+    readonly path: string;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Constraint name, e.g. "MaxLength", "MinItems", "Required" */
+    readonly constraint?: string;
+    /** Expected value or constraint description */
+    readonly expected?: string;
+    /** Actual value (truncated for large values) */
+    readonly actual?: unknown;
+}
+/**
+ * Convert Effect Schema ParseError to ValidationIssue array
+ */
+export declare const parseErrorToIssues: (error: ParseResult.ParseError) => ValidationIssue[];
+/**
+ * Create a single ValidationIssue from simple field validation
+ */
+export declare const makeIssue: (field: string, message: string, options?: {
+    constraint?: string;
+    expected?: string;
+    actual?: unknown;
+}) => ValidationIssue;
+declare const ValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ValidationError";
+} & Readonly<A>;
+/**
+ * Validation errors for webhook data with structured issues
+ */
+export declare class ValidationError extends ValidationError_base<{
+    /** Human-readable summary message */
+    message: string;
+    /** Structured validation issues */
+    issues: ReadonlyArray<ValidationIssue>;
+    /** Legacy: primary field that failed (for backward compatibility) */
+    field?: string;
+    /** Legacy: value that failed validation (for backward compatibility) */
+    value?: unknown;
+}> {
+    /**
+     * Format issues as a human-readable string
+     */
+    format(options?: {
+        maxIssues?: number;
+    }): string;
+    /**
+     * Create ValidationError from Effect Schema ParseError
+     */
+    static fromParseError(parseError: ParseResult.ParseError, context?: {
+        field?: string;
+        value?: unknown;
+    }): ValidationError;
+    /**
+     * Create ValidationError from a single issue
+     */
+    static fromIssue(field: string, message: string, options?: {
+        constraint?: string;
+        expected?: string;
+        actual?: unknown;
+    }): ValidationError;
+}
+declare const NetworkError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NetworkError";
+} & Readonly<A>;
+/**
+ * Network-related errors
+ */
+export declare class NetworkError extends NetworkError_base<{
+    message: string;
+    statusCode?: number;
+    response?: unknown;
+}> {
+}
+declare const RateLimitError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RateLimitError";
+} & Readonly<A>;
+/**
+ * Rate limit errors
+ */
+export declare class RateLimitError extends RateLimitError_base<{
+    message: string;
+    retryAfter: number;
+    limit?: number;
+    remaining?: number;
+    reset?: Date;
+}> {
+}
+declare const ConfigError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ConfigError";
+} & Readonly<A>;
+/**
+ * Configuration errors
+ */
+export declare class ConfigError extends ConfigError_base<{
+    message: string;
+    parameter: string;
+}> {
+}
+declare const FileError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "FileError";
+} & Readonly<A>;
+/**
+ * File-related errors
+ */
+export declare class FileError extends FileError_base<{
+    message: string;
+    filename?: string;
+    size?: number;
+    maxSize?: number;
+}> {
+}
+/**
+ * HTTP response error details
+ */
+export interface HttpErrorResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+declare const HttpError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
+    readonly _tag: "HttpError";
+} & Readonly<A>;
+/**
+ * HTTP errors with detailed response information
+ */
+export declare class HttpError extends HttpError_base<{
+    message: string;
+    request: {
+        method: string;
+        url: string;
+    };
+    response?: HttpErrorResponse;
+}> {
+}
+/**
+ * All possible webhook errors
+ */
+export type WebhookErrors = WebhookError | ValidationError | NetworkError | RateLimitError | ConfigError | FileError | HttpError;
+export {};

package/dist/errors/index.d.ts

@@ -0,0 +1 @@
+export * from "./WebhookError";

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ez-hook-effect - Discord webhook library built with Effect
+ *
+ * Type-safe, composable, and resilient Discord webhook client.
+ *
+ * @example
+ * ```ts
+ * import { Webhook, Embed, sendWebhook, WebhookServiceLive, makeConfigLayer, HttpClientLive } from "ez-hook-effect";
+ * import { Effect, Layer, pipe } from "effect";
+ *
+ * const webhook = pipe(
+ *   Webhook.make,
+ *   Webhook.setContent("Hello from Effect!"),
+ *   Webhook.build
+ * );
+ *
+ * const layer = WebhookServiceLive.pipe(
+ *   Layer.provide(makeConfigLayer("https://discord.com/api/webhooks/...")),
+ *   Layer.provide(HttpClientLive)
+ * );
+ *
+ * Effect.gen(function* () {
+ *   const msg = yield* webhook;
+ *   yield* sendWebhook(msg);
+ * }).pipe(Effect.provide(layer), Effect.runPromise);
+ * ```
+ *
+ * @packageDocumentation
+ */
+/** Error types for handling webhook failures */
+export { ConfigError, FileError, HttpError, type HttpErrorResponse, makeIssue, NetworkError, parseErrorToIssues, RateLimitError, ValidationError, type ValidationIssue, WebhookError, type WebhookErrors, } from "./errors";
+/**
+ * Configuration service and layers.
+ * Use makeConfigLayer for programmatic config or ConfigFromEnv for environment variables.
+ */
+export { Config, ConfigFromEnv, makeConfig, makeConfigLayer, parseWebhookUrl, type WebhookConfig, } from "./layers/Config";
+/**
+ * HTTP client service and layers.
+ * Provides fetch-based HTTP client with retry and rate limit support.
+ */
+export { createRetrySchedule, defaultRetryConfig, FetchHttpClient, HttpClient, HttpClientLive, type HttpRequest, type HttpResponse, makeHttpClientLayer, parseRateLimitHeaders, type RateLimitInfo, type RetryConfig, } from "./layers/HttpClient";
+/**
+ * Embed builder namespace.
+ * Pipe-first API for building Discord embed objects.
+ *
+ * @example
+ * ```ts
+ * import { Embed } from "ez-hook-effect";
+ * import { pipe } from "effect";
+ *
+ * const embed = pipe(
+ *   Embed.make,
+ *   Embed.setTitle("Hello"),
+ *   Embed.setDescription("World"),
+ *   Embed.setColor("#5865F2"),
+ *   Embed.build
+ * );
+ * ```
+ */
+export * as Embed from "./pipes/Embed";
+/**
+ * Webhook builder namespace.
+ * Pipe-first API for building Discord webhook payloads.
+ *
+ * @example
+ * ```ts
+ * import { Webhook } from "ez-hook-effect";
+ * import { pipe } from "effect";
+ *
+ * const webhook = pipe(
+ *   Webhook.make,
+ *   Webhook.setUsername("Bot"),
+ *   Webhook.setContent("Hello!"),
+ *   Webhook.build
+ * );
+ * ```
+ */
+export * as Webhook from "./pipes/Webhook";
+/** Schema types for Discord webhook payloads */
+export * from "./schemas";
+/**
+ * Webhook service and module-level accessors.
+ * Use these with Effect.flatMap or Effect.gen for sending webhooks.
+ */
+export { deleteWebhook, getWebhook, makeWebhookService, modifyWebhook, sendWebhook, validateWebhook, WebhookService, WebhookServiceLive, } from "./services/WebhookService";