@ryusenkei/adapter-cloudflare 0.0.0-stage → 0.1.0

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,44 @@
-# 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.
+Implementations of the runtime ports with Cloudflare Workers bindings. The binding types are structural, so this package does not depend on `@cloudflare/workers-types`. Pass the bindings from `env` in your `services.ts`.
+
+## Install
+
+```sh
+pnpm add @ryusenkei/adapter-cloudflare
+```
+
+## Usage
+
+```ts
+import { cloudflareMailer, cloudflareRateLimiter, r2BlobStore } from '@ryusenkei/adapter-cloudflare';
+
+export const servicesFromEnv = (env: Env) => ({
+  rateLimiter: cloudflareRateLimiter(env.INQUIRY_RATE_LIMITER),
+  mailer: cloudflareMailer(env.EMAIL),
+  blob: r2BlobStore(env.UPLOADS),
+});
+```
+
+| Function | Port | Binding |
+| --- | --- | --- |
+| `cloudflareRateLimiter` | [`RateLimiter`](../rate-limit) | Rate Limiting (`ratelimits` in wrangler config; limit and period are set there). Counts are per Cloudflare location, not a strict global limit |
+| `cloudflareMailer` | [`Mailer`](../mail) | Email Service (`send_email`). The sender domain must be onboarded to Email Sending |
+| `r2BlobStore` | [`BlobStore`](../blob) | R2 bucket. `list` follows the cursor past 1,000 keys |
+
+Error handling:
+
+- A missing binding throws `ConfigError`, so a misconfigured deploy returns 503 `not_configured` through `failureResponse`
+- Rate Limiting and R2 failures throw `TransientError`
+- Email Service error codes:
+  - `E_RATE_LIMIT_EXCEEDED`, `E_DAILY_LIMIT_EXCEEDED`, and `E_INTERNAL_SERVER_ERROR` throw `TransientError`
+  - Unverified or unavailable sender domains, a suspended account, and recipients not allowed by the binding throw `ConfigError`
+  - Suppressed recipients and delivery failures return `rejected`
+  - Validation and header errors return `invalid_input`
+  - Unknown codes are rethrown as is
+
+D1 (`db`) is not here yet.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { cloudflareMailer, type SendEmailBinding } from './mail.ts';
+export { r2BlobStore, type R2BucketBinding } from './r2.ts';
+export { cloudflareRateLimiter, type RateLimitBinding } from './rate-limit.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { cloudflareMailer } from "./mail.js";
+export { r2BlobStore } from "./r2.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/r2.d.ts

@@ -0,0 +1,33 @@
+import type { BlobBody, BlobStore } from '@ryusenkei/blob';
+type R2Object = {
+    size: number;
+    httpMetadata?: {
+        contentType?: string;
+    };
+    body: ReadableStream<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+};
+/** R2 の bucket の binding（使う部分だけの型） */
+export type R2BucketBinding = {
+    put(key: string, value: BlobBody, options?: {
+        httpMetadata?: {
+            contentType?: string;
+        };
+    }): Promise<unknown>;
+    get(key: string): Promise<R2Object | null>;
+    delete(key: string): Promise<void>;
+    list(options?: {
+        prefix?: string;
+        cursor?: string;
+    }): Promise<{
+        objects: {
+            key: string;
+        }[];
+        truncated: boolean;
+        cursor?: string;
+    }>;
+};
+/** R2 の bucket によるファイルの保存 */
+export declare function r2BlobStore(bucket: R2BucketBinding | undefined): BlobStore;
+export {};

package/dist/r2.js

@@ -0,0 +1,41 @@
+import { ConfigError, err, ok, TransientError } from '@ryusenkei/core';
+/** R2 の bucket によるファイルの保存 */
+export function r2BlobStore(bucket) {
+    // R2 の失敗は再試行で回復しうるものとして扱う（binding の操作の例外は理由を区別できない）
+    const transient = async (op, run) => {
+        if (!bucket)
+            throw new ConfigError('R2 の binding が未設定');
+        try {
+            return await run(bucket);
+        }
+        catch (e) {
+            throw new TransientError(`R2 の ${op} の失敗`, { cause: e });
+        }
+    };
+    return {
+        async put(key, body, options = {}) {
+            await transient('put', (b) => b.put(key, body, options.contentType ? { httpMetadata: { contentType: options.contentType } } : {}));
+        },
+        async get(key) {
+            const object = await transient('get', (b) => b.get(key));
+            if (!object)
+                return err('not_found');
+            const blob = { size: object.size, contentType: object.httpMetadata?.contentType, body: object.body, arrayBuffer: () => object.arrayBuffer(), text: () => object.text() };
+            return ok(blob);
+        },
+        async delete(key) {
+            await transient('delete', (b) => b.delete(key));
+        },
+        // 1回の応答は最大1,000件なので、cursor で続きを取得
+        async list(prefix) {
+            const keys = [];
+            let cursor;
+            do {
+                const page = await transient('list', (b) => b.list({ ...(prefix ? { prefix } : {}), ...(cursor ? { cursor } : {}) }));
+                keys.push(...page.objects.map((o) => o.key));
+                cursor = page.truncated ? page.cursor : undefined;
+            } while (cursor);
+            return keys.sort();
+        },
+    };
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,15 @@
+import type { RateLimiter } from '@ryusenkei/rate-limit';
+/** 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,41 @@
 {
   "name": "@ryusenkei/adapter-cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "差し込み口の Cloudflare Workers の binding による実装（回数の制限、メール送信、R2）",
+  "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"
+  },
+  "dependencies": {
+    "@ryusenkei/core": "^0.1.0",
+    "@ryusenkei/rate-limit": "^0.1.0",
+    "@ryusenkei/mail": "^0.1.0",
+    "@ryusenkei/blob": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
 }