effect-cf 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # effect-cf
 
+## 0.16.0
+
+### Minor Changes
+
+- [#51](https://github.com/danieljvdm/effect-cf/pull/51) [`9a6abd2`](https://github.com/danieljvdm/effect-cf/commit/9a6abd27366c71867a420f872459b3d5fc1b2143) Thanks [@owensbla](https://github.com/owensbla)! - Add Effect-native Cloudflare Analytics Engine helpers. `AnalyticsEngine.Tag(...)` now provides validated dataset writes, configurable invalid-write policy, and batch write helpers. `AnalyticsEngine.QueryTag(...)` / `makeQueryClient(...)` provide SQL API querying backed by Effect `HttpClient`, config and redacted API token support, typed result envelopes, and row decoding through Effect schemas.
+
+## 0.15.0
+
+### Minor Changes
+
+- [#47](https://github.com/danieljvdm/effect-cf/pull/47) [`debc5e1`](https://github.com/danieljvdm/effect-cf/commit/debc5e12cee68c85c5ea99096e2660aa0ec90b6f) Thanks [@owensbla](https://github.com/owensbla)! - Add an Effect-native Cloudflare Send Email binding wrapper. `Email.Tag(...)` now provides a typed client for `send_email` bindings with `send(...)`, `unsafeRaw`, binding validation, and `EmailOperationError` failure mapping.
+
 ## 0.14.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # effect-cf
 
-Effect-native Cloudflare primitives for Workers, Durable Objects, bindings, KV, D1, Queues, Workflows, and Durable Object storage.
+Effect-native Cloudflare primitives for Workers, Durable Objects, bindings, KV, D1, Queues, Email, Analytics Engine, Workflows, and Durable Object storage.
 
 ## Install
 
@@ -35,6 +35,8 @@ Runtime creation belongs at Cloudflare entrypoints, not inside binding helpers.
 - `R2` - typed R2 bucket binding helper with Effect-wrapped object and multipart operations
 - `Hyperdrive` - typed Hyperdrive binding helper for connection strings and optional Postgres SQL integration
 - `Images` - typed Cloudflare Images binding helper with transformation APIs and optional hosted image operations
+- `Email` - typed Cloudflare Send Email binding helper for `send_email` bindings
+- `AnalyticsEngine` - typed Cloudflare Analytics Engine write bindings and SQL API query helpers
 - `Queue` - typed Queue producer/consumer tags plus client and error types
 - `Workflow` - typed Workflow entrypoints, steps, starter clients, and instance types
 - `Rpc` - Cloudflare RPC type helpers and scoped disposal utilities
@@ -206,6 +208,113 @@ export const resizeAvatar = (image: Images.ImageInputValue) =>
   });
 ```
 
+## Email Example
+
+Email tags expose Cloudflare Send Email bindings as Effect-wrapped `send(...)` operations.
+
+```ts
+import { Effect } from "effect";
+import { Email } from "effect-cf";
+
+class TransactionalEmail extends Email.Tag<TransactionalEmail>()("TransactionalEmail") {}
+
+export const TransactionalEmailLayer = TransactionalEmail.layer({ binding: "EMAIL" });
+
+export const sendWelcomeEmail = (to: string) =>
+  Effect.gen(function* () {
+    const email = yield* TransactionalEmail;
+
+    return yield* email.send({
+      from: { name: "Example", email: "team@example.com" },
+      to,
+      subject: "Welcome to Example",
+      text: "Welcome to Example",
+      html: "<p>Welcome to Example</p>",
+    });
+  });
+```
+
+## Analytics Engine Example
+
+Analytics Engine tags expose Cloudflare dataset bindings as Effect-wrapped `writeDataPoint(...)` operations. Writes use Cloudflare's native non-blocking runtime API and are validated against Workers Analytics Engine limits before reaching the binding.
+
+```ts
+import { Effect } from "effect";
+import { AnalyticsEngine } from "effect-cf";
+
+class RequestAnalytics extends AnalyticsEngine.Tag<RequestAnalytics>()("RequestAnalytics") {}
+
+export const RequestAnalyticsLayer = RequestAnalytics.layer({
+  binding: "REQUEST_ANALYTICS",
+  write: {
+    onInvalid: "error",
+    batchSize: 100,
+  },
+});
+
+export const recordPageView = (request: Request) =>
+  Effect.gen(function* () {
+    const analytics = yield* RequestAnalytics;
+    const url = new URL(request.url);
+
+    yield* analytics.writeDataPoint({
+      indexes: [url.hostname],
+      blobs: [url.pathname, request.headers.get("cf-connecting-country") ?? "unknown"],
+      doubles: [1],
+    });
+
+    yield* analytics.writeBatch(
+      [
+        {
+          indexes: [url.hostname],
+          blobs: [url.pathname, "page-view"],
+          doubles: [1],
+        },
+      ],
+      { onInvalid: "drop" },
+    );
+  });
+```
+
+Define the dataset binding in the consuming Worker's `wrangler.jsonc` with `analytics_engine_datasets`, then provide `RequestAnalytics.layer({ binding: "REQUEST_ANALYTICS" })` from the Worker layer. Invalid writes fail with `AnalyticsEngineWriteValidationError` by default. Use `write: { onInvalid: "drop" }` on the layer or `{ onInvalid: "drop" }` per call when dropping invalid points is preferable.
+
+Analytics Engine query tags wrap Cloudflare's HTTP SQL API. Configuration can stay in Effect `Config`, including a redacted API token, the outbound transport is an Effect `HttpClient` dependency, and rows can be decoded with Effect schemas at the query boundary. Use `fetchLayerConfig(...)` as shorthand when the platform fetch-backed client is enough.
+
+```ts
+import { Effect, Layer, Schema as S } from "effect";
+import { FetchHttpClient } from "effect/unstable/http";
+import { AnalyticsEngine, WorkerConfig } from "effect-cf";
+
+class AnalyticsQuery extends AnalyticsEngine.QueryTag<AnalyticsQuery>()("AnalyticsQuery") {}
+
+export const AnalyticsQueryLayer = AnalyticsQuery.layerConfig(
+  AnalyticsEngine.queryConfig({
+    accountId: WorkerConfig.string("CLOUDFLARE_ACCOUNT_ID"),
+    apiToken: WorkerConfig.redacted("CLOUDFLARE_API_TOKEN"),
+  }),
+).pipe(Layer.provide(FetchHttpClient.layer));
+
+const PageView = S.Struct({
+  path: S.String,
+  views: S.Number,
+});
+
+export const topPages = Effect.gen(function* () {
+  const analytics = yield* AnalyticsQuery;
+
+  return yield* analytics.queryRows(
+    PageView,
+    `
+      SELECT blob1 AS path, SUM(_sample_interval) AS views
+      FROM request_metrics
+      GROUP BY path
+      ORDER BY views DESC
+      LIMIT 10
+    `,
+  );
+});
+```
+
 ## Workflow Example
 
 Workflow definitions type the payload and result. Runtime handlers can access `Workflow.WorkflowEvent`, use durable `Workflow.step(...)`, and use normal binding services inside steps.