@ryusenkei/adapter-cloudflare 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RYUSENKEI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @ryusenkei/adapter-cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cloudflare Workers bindings as the rate limiter and mail sender that `@ryusenkei/form` uses. The binding types are structural, so this package does not depend on `@cloudflare/workers-types`.
+
+## Install
+
+```sh
+pnpm add @ryusenkei/adapter-cloudflare
+```
+
+## Usage
+
+```ts
+import { cloudflareMailer, cloudflareRateLimiter } from '@ryusenkei/adapter-cloudflare';
+
+const rateLimiter = cloudflareRateLimiter(env.FORM_LIMITER);
+const mailer = cloudflareMailer(env.EMAIL);
+```
+
+| Function | Returns | Binding |
+| --- | --- | --- |
+| `cloudflareRateLimiter` | `limit(key)` → `rate_limited` over the limit | Rate Limiting (`ratelimits` in wrangler config; limit and period are set there). Counts are per Cloudflare location, not a strict global limit |
+| `cloudflareMailer` | a `Mailer` from `@ryusenkei/mail` | Email Service (`send_email`). The sender domain must be onboarded to Email Sending |
+
+## Errors
+
+- A missing binding throws `ConfigError`, so a misconfigured deploy answers 503 `not_configured`.
+- A Rate Limiting binding failure throws `TransientError`.
+- The mailer runs `validateMail` first, then maps Email Service error codes:
+
+| Codes | Result |
+| --- | --- |
+| `E_RATE_LIMIT_EXCEEDED`, `E_DAILY_LIMIT_EXCEEDED`, `E_INTERNAL_SERVER_ERROR` | throws `TransientError` |
+| `E_SENDER_NOT_VERIFIED`, `E_SENDER_DOMAIN_NOT_AVAILABLE`, `E_ACCOUNT_SUSPENDED`, `E_RECIPIENT_NOT_ALLOWED` | throws `ConfigError` |
+| `E_RECIPIENT_SUPPRESSED`, `E_DELIVERY_FAILED` | `rejected` |
+| validation and header errors | `invalid_input` |
+| anything else | rethrown as is |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { cloudflareMailer, type SendEmailBinding } from './mail.ts';
+export { cloudflareRateLimiter, type RateLimitBinding, type RateLimiter } from './rate-limit.ts';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { cloudflareMailer } from "./mail.js";
+export { cloudflareRateLimiter } from "./rate-limit.js";

package/dist/mail.d.ts

@@ -0,0 +1,20 @@
+import { type MailAddress, type Mailer } from '@ryusenkei/mail';
+/** Email Service の `send_email` binding（使う部分だけの型） */
+export type SendEmailBinding = {
+    send(message: {
+        from: MailAddress;
+        to: MailAddress[];
+        replyTo?: MailAddress;
+        subject: string;
+        text: string;
+        html?: string;
+    }): Promise<{
+        messageId: string;
+    }>;
+};
+/**
+ * Email Service（Email Sending）の binding によるメール送信
+ * - 送信元のドメインは Email Sending に登録済みであること（未登録は `ConfigError`）
+ * - 知らないエラーコードはそのまま投げる（想定外の失敗として扱う）
+ */
+export declare function cloudflareMailer(binding: SendEmailBinding | undefined): Mailer;

package/dist/mail.js

@@ -0,0 +1,41 @@
+import { ConfigError, err, ok, TransientError } from '@ryusenkei/core';
+import { validateMail } from '@ryusenkei/mail';
+// binding のエラーの `code` の分類（Email Service の Workers API の一覧）
+const TRANSIENT = ['E_RATE_LIMIT_EXCEEDED', 'E_DAILY_LIMIT_EXCEEDED', 'E_INTERNAL_SERVER_ERROR'];
+const CONFIG = ['E_SENDER_NOT_VERIFIED', 'E_SENDER_DOMAIN_NOT_AVAILABLE', 'E_ACCOUNT_SUSPENDED', 'E_RECIPIENT_NOT_ALLOWED'];
+const REJECTED = ['E_RECIPIENT_SUPPRESSED', 'E_DELIVERY_FAILED'];
+const INVALID = /^E_(VALIDATION_ERROR|FIELD_MISSING|TOO_MANY_RECIPIENTS|TOO_MANY_ATTACHMENTS|CONTENT_TOO_LARGE|HEADERS?_.+)$/;
+/**
+ * Email Service（Email Sending）の binding によるメール送信
+ * - 送信元のドメインは Email Sending に登録済みであること（未登録は `ConfigError`）
+ * - 知らないエラーコードはそのまま投げる（想定外の失敗として扱う）
+ */
+export function cloudflareMailer(binding) {
+    return {
+        async send(mail) {
+            if (!binding)
+                throw new ConfigError('send_email の binding が未設定');
+            const valid = validateMail(mail);
+            if (!valid.ok)
+                return valid;
+            try {
+                const { messageId } = await binding.send({ from: mail.from, to: mail.to, ...(mail.replyTo ? { replyTo: mail.replyTo } : {}), subject: mail.subject, text: mail.text, ...(mail.html ? { html: mail.html } : {}) });
+                return ok({ id: messageId });
+            }
+            catch (e) {
+                const code = e.code;
+                if (typeof code !== 'string')
+                    throw e;
+                if (TRANSIENT.includes(code))
+                    throw new TransientError(`メール送信の一時的な失敗: ${code}`, { cause: e });
+                if (CONFIG.includes(code))
+                    throw new ConfigError(`メール送信の設定の誤り: ${code}`, { cause: e });
+                if (REJECTED.includes(code))
+                    return err('rejected');
+                if (INVALID.test(code))
+                    return err('invalid_input');
+                throw e;
+            }
+        },
+    };
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,19 @@
+import { type Result } from '@ryusenkei/core';
+/** キー（IP アドレスなど）ごとの回数の制限（`@ryusenkei/form/server` の `rateLimiter` に渡せる） */
+export type RateLimiter = Readonly<{
+    limit(key: string): Promise<Result<void, 'rate_limited'>>;
+}>;
+/** Workers の Rate Limiting の binding（使う部分だけの型。`@cloudflare/workers-types` に依存しない） */
+export type RateLimitBinding = {
+    limit(options: {
+        key: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+};
+/**
+ * Workers の Rate Limiting の binding による回数の制限
+ * - 上限と期間は wrangler の設定（`ratelimits`）で決める
+ * - 数え方は Cloudflare の拠点ごとで、厳密な全体の上限ではない
+ */
+export declare function cloudflareRateLimiter(binding: RateLimitBinding | undefined): RateLimiter;

package/dist/rate-limit.js

@@ -0,0 +1,22 @@
+import { ConfigError, err, ok, TransientError } from '@ryusenkei/core';
+/**
+ * Workers の Rate Limiting の binding による回数の制限
+ * - 上限と期間は wrangler の設定（`ratelimits`）で決める
+ * - 数え方は Cloudflare の拠点ごとで、厳密な全体の上限ではない
+ */
+export function cloudflareRateLimiter(binding) {
+    return {
+        async limit(key) {
+            if (!binding)
+                throw new ConfigError('Rate Limiting の binding が未設定');
+            let result;
+            try {
+                result = await binding.limit({ key });
+            }
+            catch (e) {
+                throw new TransientError('Rate Limiting の binding の失敗', { cause: e });
+            }
+            return result.success ? ok() : err('rate_limited');
+        },
+    };
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@ryusenkei/adapter-cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "Cloudflare Workers の binding による実装（回数の制限、メール送信）",
+  "license": "MIT",
+  "author": "RYUSENKEI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryusenkei-inc/toolkit.git",
+    "directory": "packages/runtime/adapter-cloudflare"
+  },
+  "homepage": "https://github.com/ryusenkei-inc/toolkit/tree/main/packages/runtime/adapter-cloudflare",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@ryusenkei/core": "^0.2.0",
+    "@ryusenkei/mail": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
 }