@teever/ez-hook-effect 0.4.4 → 0.5.0

package/README.md

@@ -25,17 +25,14 @@ 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'
+import { Effect, pipe } from 'effect'
+import { makeDefaultLayer, sendWebhook, 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)
-)
+// Create service layer
+const AppLayer = makeDefaultLayer(WEBHOOK_URL)
 
 // Send a simple message
 const program = pipe(
@@ -47,7 +44,7 @@ const program = pipe(
 )
 
 // Run the program
-Effect.runPromise(Effect.provide(program, AppLayer))
+Effect.runPromise(program.pipe(Effect.provide(AppLayer)))
 ```
 
 ### Pipe-First API (Recommended)
@@ -105,7 +102,7 @@ const embedProgram = pipe(
 
 ## 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:
+Retries for rate limits (429) and transient errors (5xx) are handled automatically using configurable exponential backoff. `sendWebhook` fails the Effect on any non-204 response, so errors always surface to your error handling paths.
 
 ```typescript
 import { Effect, pipe } from 'effect'
@@ -144,6 +141,54 @@ Effect.catchTag('ValidationError', (error) =>
 )
 ```
 
+### Error Helpers
+
+```typescript
+import { Effect, pipe } from 'effect'
+import { Webhook, sendWebhook, formatWebhookError, webhookErrorToLogObject } from '@teever/ez-hook-effect'
+
+const program = pipe(
+  Webhook.make,
+  Webhook.setContent('Hello!'),
+  Webhook.build,
+  Effect.flatMap(sendWebhook),
+  Effect.catchAll((error) =>
+    Effect.logError(formatWebhookError(error)).pipe(
+      Effect.tap(() => Effect.log(JSON.stringify(webhookErrorToLogObject(error))))
+    )
+  )
+)
+```
+
+## Raw Response
+
+When you need status/body, use `sendWebhookRaw`:
+
+```typescript
+import { Effect, pipe } from 'effect'
+import { sendWebhookRaw, Webhook } from '@teever/ez-hook-effect'
+
+const program = pipe(
+  Webhook.make,
+  Webhook.setContent('Hello!'),
+  Webhook.build,
+  Effect.flatMap(sendWebhookRaw),
+  Effect.tap((res) => Effect.log(`Status: ${res.status}`))
+)
+```
+
+## Validate Only
+
+```typescript
+import { Effect, pipe } from 'effect'
+import { Webhook } from '@teever/ez-hook-effect'
+
+const program = pipe(
+  Webhook.validate({ content: 'Hello!' }),
+  Effect.tap(() => Effect.log('Valid payload'))
+)
+```
+
 ## Configuration Options
 
 ### Programmatic Configuration
@@ -160,6 +205,17 @@ const AppLayer = WebhookServiceLive.pipe(
 )
 ```
 
+### One-Liner Configuration
+
+```typescript
+import { makeDefaultLayer } from '@teever/ez-hook-effect'
+
+const AppLayer = makeDefaultLayer(WEBHOOK_URL, {
+  maxRetries: 5,
+  baseDelayMs: 1000,
+})
+```
+
 ### Environment Variables
 
 ```typescript
@@ -198,7 +254,7 @@ 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'
+import { getWebhook, modifyWebhook, deleteWebhook, validateWebhook, WebhookService, WebhookServiceLive, makeConfigLayer, HttpClientLive } from '@teever/ez-hook-effect'
 
 const AppLayer = WebhookServiceLive.pipe(
   Layer.provide(makeConfigLayer(WEBHOOK_URL)),
@@ -226,6 +282,28 @@ const program = Effect.gen(function* () {
 Effect.runPromise(Effect.provide(program, AppLayer))
 ```
 
+## Testing Utilities
+
+```typescript
+import { Effect, Layer, pipe } from 'effect'
+import { makeTestHttpClient, WebhookServiceLive, makeConfigLayer } from '@teever/ez-hook-effect'
+
+const TestHttpClient = makeTestHttpClient((_req) =>
+  Effect.succeed({
+    status: 204,
+    statusText: 'No Content',
+    headers: {},
+    body: null,
+    text: '',
+  })
+)
+
+const AppLayer = WebhookServiceLive.pipe(
+  Layer.provide(makeConfigLayer('https://discord.com/api/webhooks/123/abc')),
+  Layer.provide(TestHttpClient)
+)
+```
+
 ## Development
 
 ```bash