@startup-api/cloudflare 0.0.1

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2026 Sergey Chernyshev and contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,114 @@
+# Startup API Cloudflare App
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+This application uses the Cloudflare Developer Platform, including Workers and DurableObjects, to implement foundational web application functionality. It acts as a transparent proxy for your application, allowing you to inject custom UI elements and intercept specific paths.
+
+## Features
+
+- **Transparent Proxying:** Forwards requests to your origin application
+- **HTML Injection:** Uses `HTMLRewriter` to inject scripts and custom elements (like `<power-strip>`) into your HTML pages
+- **Path Interception:** Intercepts requests to a configurable path to serve internal assets
+
+## Installation
+
+### Option 1: Cloudflare Workers GitHub Integration (Recommended)
+
+This is the easiest way to deploy and keep your worker up to date.
+
+1. **Fork this repository** to your account
+2. Go to your [Cloudflare Dashboard's Workers & pages > Create Application](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create)
+3. Click **Continue with GitHub**
+4. Select your forked `startup-api-cloudflare` repository
+5. Pick the name for your site's worker (e.g. you might have multiple)
+6. Deploy the Worker
+7. In the **Settings** tab of your Worker, go to **Variables** and add the required `ORIGIN_URL` (see [Configuration](#configuration-details) below)
+
+### Option 2: Manual Installation (CLI)
+
+Use this option if you want to deploy from your local machine.
+
+1. **Clone and Install**
+   ```bash
+   git clone https://github.com/StartupAPI/startup-api-cloudflare.git
+   cd startup-api-cloudflare
+   npm install
+   ```
+2. **Configure Environment Variables**
+
+   Update `wrangler.jsonc` or use dashboard **Settings** tab of your Worker, go to **Variables** and add the required `ORIGIN_URL` (see [Configuration](#configuration-details) below)
+
+3. **Deploy**
+   ```bash
+   npm run deploy
+   ```
+
+## Configuration Details
+
+### How to set environment variables
+
+- **Using Cloudflare Dashboard (Recommended):**
+  1. Go to **Workers & Pages**
+  2. Select your worker
+  3. Navigate to **Settings** > **Variables**
+  4. Click **Add variable** under **Environment Variables**
+  5. Add `ORIGIN_URL` and any optional variables
+  6. Click **Save and deploy**
+
+- **Using `wrangler.jsonc`:**
+  Add the variables to the `"vars"` object in your configuration file. See [Cloudflare documentation](https://developers.cloudflare.com/workers/wrangler/configuration/#environment-variables) for more details.
+
+| Variable               | Required | Default   | Description                                                                   |
+| :--------------------- | :------- | :-------- | :---------------------------------------------------------------------------- |
+| `ORIGIN_URL`           | **Yes**  | N/A       | The base URL of your origin application (e.g., `https://your-app-origin.com`) |
+| `USERS_PATH`           | No       | `/users/` | The path used to serve internal assets like `power-strip.js`                  |
+| `AUTH_ORIGIN`          | No       | N/A       | Optional base URL for OAuth redirects (overrides request origin)              |
+| `GOOGLE_CLIENT_ID`     | No       | N/A       | Google OAuth2 Client ID                                                       |
+| `GOOGLE_CLIENT_SECRET` | No       | N/A       | Google OAuth2 Client Secret                                                   |
+| `TWITCH_CLIENT_ID`     | No       | N/A       | Twitch OAuth2 Client ID                                                       |
+| `TWITCH_CLIENT_SECRET` | No       | N/A       | Twitch OAuth2 Client Secret                                                   |
+
+### Setting up OAuth
+
+#### Google
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select an existing one
+3. Navigate to **APIs & Services > Credentials**
+4. Click **Create Credentials > OAuth client ID**
+5. Select **Web application** as the application type
+6. Add your authorized redirect URI: `https://<your-worker-url>/users/auth/google/callback`
+7. Copy the **Client ID** and **Client Secret** and add them to your Worker's environment variables
+
+#### Twitch
+
+1. Go to the [Twitch Developer Console](https://dev.twitch.tv/console)
+2. Register a new application
+3. Add your authorized redirect URI: `https://<your-worker-url>/users/auth/twitch/callback`
+4. Select **Website** as the category
+5. Copy the **Client ID** and generate a **Client Secret** to add them to your Worker's environment variables
+
+### Example `wrangler.jsonc` snippet:
+
+```json
+{
+  "vars": {
+    "ORIGIN_URL": "https://your-app-origin.com"
+  }
+}
+```
+
+## How It Works
+
+1. **Request Interception:** The worker receives all incoming requests
+2. **Path Mapping:** If the request path starts with `USERS_PATH`, the worker serves assets directly from the `public/users/` directory
+3. **Proxying:** All other requests are proxied to the configured `ORIGIN_URL`
+4. **Injection:** For `text/html` responses, the worker injects a `<script>` tag and a `<power-strip>` custom element before serving the content to the user
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for details.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@startup-api/cloudflare",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/StartupAPI/startup-api-cloudflare.git"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./public/*": "./public/*",
+    "./wrangler.template.jsonc": "./wrangler.template.jsonc",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "public",
+    "worker-configuration.d.ts",
+    "wrangler.template.jsonc"
+  ],
+  "scripts": {
+    "deploy": "wrangler deploy",
+    "dev": "wrangler dev -c wrangler.local.jsonc",
+    "preview": "wrangler dev --env preview",
+    "test": "eslint . && vitest run",
+    "test:coverage": "vitest run --coverage --coverage.provider=istanbul",
+    "cf-typegen": "wrangler types",
+    "format": "npx prettier . --write",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.12.4",
+    "@eslint/js": "^10.0.1",
+    "@vitest/coverage-istanbul": "^3.2.4",
+    "@vitest/coverage-v8": "^3.2.4",
+    "eslint": "^10.0.1",
+    "globals": "^17.3.0",
+    "typescript": "^5.5.2",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "~3.2.0",
+    "wrangler": "^4.60.0"
+  },
+  "dependencies": {
+    "prettier": "^3.8.1",
+    "zod": "^3.25.76"
+  }
+}

package/public/index.html

@@ -0,0 +1,405 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Startup API Cloudflare App - Documentation</title>
+    <style>
+      :root {
+        --primary-color: #f6821f; /* Cloudflare Orange */
+        --bg-color: #f8f9fa;
+        --text-color: #333;
+        --card-bg: #fff;
+        --card-border: #eee;
+        --pre-bg: #f1f1f1;
+        --nav-bg: #2c2c2c;
+        --hero-bg: linear-gradient(135deg, #2c2c2c 0%, #4a4a4a 100%);
+        --container-width: 800px;
+      }
+
+      @media (prefers-color-scheme: dark) {
+        :root:not([data-theme='light']) {
+          --bg-color: #1a1a1a;
+          --text-color: #e0e0e0;
+          --card-bg: #2d2d2d;
+          --card-border: #444;
+          --pre-bg: #333;
+          --nav-bg: #111;
+        }
+      }
+
+      [data-theme='dark'] {
+        --bg-color: #1a1a1a;
+        --text-color: #e0e0e0;
+        --card-bg: #2d2d2d;
+        --card-border: #444;
+        --pre-bg: #333;
+        --nav-bg: #111;
+      }
+
+      [data-theme='light'] {
+        --bg-color: #f8f9fa;
+        --text-color: #333;
+        --card-bg: #fff;
+        --card-border: #eee;
+        --pre-bg: #f1f1f1;
+        --nav-bg: #2c2c2c;
+      }
+
+      body {
+        font-family:
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          'Segoe UI',
+          Roboto,
+          Oxygen,
+          Ubuntu,
+          Cantarell,
+          'Open Sans',
+          'Helvetica Neue',
+          sans-serif;
+        line-height: 1.6;
+        color: var(--text-color);
+        background-color: var(--bg-color);
+        margin: 0;
+        transition:
+          background-color 0.3s,
+          color 0.3s;
+      }
+
+      nav {
+        background-color: var(--nav-bg);
+        color: white;
+        padding: 1rem 0;
+        box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+      }
+
+      .nav-container {
+        max-width: var(--container-width);
+        margin: 0 auto;
+        display: flex;
+        justify-content: space-between;
+        align-items: center;
+        padding: 0 1rem;
+      }
+
+      .navbar-brand {
+        display: flex;
+        align-items: center;
+        font-weight: bold;
+        text-decoration: none;
+        color: white;
+        font-size: 1.25rem;
+      }
+
+      header.hero-section {
+        background: var(--hero-bg);
+        color: white;
+        padding: 4rem 1rem;
+        text-align: center;
+        margin-bottom: 2rem;
+      }
+
+      h1 {
+        margin: 0;
+        font-size: 2.5rem;
+      }
+
+      main {
+        max-width: var(--container-width);
+        margin: 0 auto;
+        padding: 0 1rem;
+      }
+
+      .card {
+        background-color: var(--card-bg);
+        border: 1px solid var(--card-border);
+        border-radius: 12px;
+        box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+        margin-bottom: 2rem;
+        overflow: hidden;
+      }
+
+      .card-header {
+        background-color: rgba(0, 0, 0, 0.03);
+        border-bottom: 1px solid var(--card-border);
+        font-weight: bold;
+        font-size: 1.2rem;
+        padding: 1rem 1.5rem;
+      }
+
+      .card-body {
+        padding: 1.5rem;
+      }
+
+      .variable-block {
+        margin-bottom: 1.5rem;
+      }
+
+      .variable-title {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        margin-bottom: 0.5rem;
+      }
+
+      .variable-name {
+        font-family: ui-monospace, SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace;
+        color: var(--primary-color);
+        font-weight: bold;
+        background: rgba(246, 130, 31, 0.1);
+        padding: 0.2rem 0.4rem;
+        border-radius: 4px;
+      }
+
+      .badge-required {
+        background-color: #dc3545;
+        color: white;
+        font-size: 0.75rem;
+        padding: 0.2rem 0.5rem;
+        border-radius: 4px;
+        font-weight: bold;
+      }
+
+      pre {
+        background-color: var(--pre-bg);
+        color: var(--text-color);
+        padding: 1rem;
+        border-radius: 8px;
+        overflow-x: auto;
+        font-family: ui-monospace, SFMono-Regular, Consolas, 'Liberation Mono', Menlo, monospace;
+        font-size: 0.9rem;
+      }
+
+      ol,
+      ul {
+        padding-left: 1.5rem;
+      }
+
+      li {
+        margin-bottom: 0.5rem;
+      }
+
+      footer {
+        text-align: center;
+        padding: 2rem 0;
+        color: #777;
+        border-top: 1px solid var(--card-border);
+        margin-top: 3rem;
+      }
+
+      .theme-toggle {
+        cursor: pointer;
+        background: transparent;
+        border: 1px solid rgba(255, 255, 255, 0.3);
+        color: white;
+        border-radius: 50%;
+        width: 40px;
+        height: 40px;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        transition: all 0.2s;
+        padding: 0;
+      }
+
+      .theme-toggle:hover {
+        background: rgba(255, 255, 255, 0.1);
+      }
+
+      .theme-toggle svg {
+        width: 20px;
+        height: 20px;
+        fill: currentColor;
+      }
+    </style>
+  </head>
+  <body>
+    <nav>
+      <div class="nav-container">
+        <a class="navbar-brand" href="">
+          <svg
+            viewBox="0 0 24 24"
+            style="width: 24px; height: 24px; fill: #ffcc00; margin-right: 10px; filter: drop-shadow(1px 1px 1px rgba(0, 0, 0, 0.5))"
+          >
+            <path d="M7 2v11h3v9l7-12h-4l4-8z" />
+          </svg>
+          Startup API
+        </a>
+        <button class="theme-toggle" id="themeToggle" title="Toggle Theme">
+          <svg id="sunIcon" viewBox="0 0 24 24" style="display: none">
+            <path
+              d="M12 7c-2.76 0-5 2.24-5 5s2.24 5 5 5 5-2.24 5-5-2.24-5-5-5zM2 13h2c.55 0 1-.45 1-1s-.45-1-1-1H2c-.55 0-1 .45-1 1s.45 1 1 1zm18 0h2c.55 0 1-.45 1-1s-.45-1-1-1h-2c-.55 0-1 .45-1 1s.45 1 1 1zM11 2v2c0 .55.45 1 1 1s1-.45 1-1V2c0-.55-.45-1-1-1s-1 .45-1 1zm0 18v2c0 .55.45 1 1 1s1-.45 1-1v-2c0-.55-.45-1-1-1s-1 .45-1 1zM5.99 4.58a.996.996 0 00-1.41 0 .996.996 0 000 1.41l1.06 1.06c.39.39 1.03.39 1.41 0s.39-1.03 0-1.41L5.99 4.58zm12.37 12.37a.996.996 0 00-1.41 0 .996.996 0 000 1.41l1.06 1.06c.39.39 1.03.39 1.41 0a.996.996 0 000-1.41l-1.06-1.06zm1.06-10.96a.996.996 0 000-1.41.996.996 0 00-1.41 0l-1.06 1.06c-.39.39-.39 1.03 0 1.41s1.03.39 1.41 0l1.06-1.06zM7.05 18.36a.996.996 0 000-1.41.996.996 0 00-1.41 0l-1.06 1.06c-.39.39-.39 1.03 0 1.41s1.03.39 1.41 0l1.06-1.06z"
+            />
+          </svg>
+          <svg id="moonIcon" viewBox="0 0 24 24">
+            <path
+              d="M12 3c-4.97 0-9 4.03-9 9s4.03 9 9 9 9-4.03 9-9c0-.46-.04-.92-.1-1.36-.98 1.37-2.58 2.26-4.4 2.26-2.98 0-5.4-2.42-5.4-5.4 0-1.81.89-3.42 2.26-4.4-.44-.06-.9-.1-1.36-.1z"
+            />
+          </svg>
+        </button>
+      </div>
+    </nav>
+
+    <script>
+      const themeToggle = document.getElementById('themeToggle');
+      const sunIcon = document.getElementById('sunIcon');
+      const moonIcon = document.getElementById('moonIcon');
+      const html = document.documentElement;
+
+      function updateIcons(theme) {
+        if (theme === 'dark') {
+          sunIcon.style.display = 'block';
+          moonIcon.style.display = 'none';
+        } else {
+          sunIcon.style.display = 'none';
+          moonIcon.style.display = 'block';
+        }
+      }
+
+      function setTheme(theme) {
+        if (theme) {
+          html.setAttribute('data-theme', theme);
+          updateIcons(theme);
+        } else {
+          html.removeAttribute('data-theme');
+          const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+          updateIcons(isDark ? 'dark' : 'light');
+        }
+      }
+
+      const savedTheme = localStorage.getItem('theme');
+      setTheme(savedTheme);
+
+      themeToggle.addEventListener('click', () => {
+        const currentTheme = html.getAttribute('data-theme');
+        let newTheme;
+
+        if (!currentTheme) {
+          const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+          newTheme = isDark ? 'light' : 'dark';
+        } else {
+          newTheme = currentTheme === 'dark' ? 'light' : 'dark';
+        }
+
+        setTheme(newTheme);
+        localStorage.setItem('theme', newTheme);
+      });
+
+      // Update icons if system theme changes and no manual override is set
+      window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
+        if (!html.getAttribute('data-theme')) {
+          updateIcons(e.matches ? 'dark' : 'light');
+        }
+      });
+    </script>
+
+    <header class="hero-section">
+      <div class="container">
+        <h1 class="display-4">Welcome to Startup API</h1>
+      </div>
+    </header>
+
+    <main class="container">
+      <div class="row">
+        <div class="col-lg-8 offset-lg-2">
+          <!-- Overview -->
+
+          <section class="card">
+            <div class="card-header">Overview</div>
+
+            <div class="card-body">
+              <p>
+                This application uses Cloudflare Developer Platform, including Workers and DurableObjects to implement functionality that
+                every web application needs on day zero.
+              </p>
+
+              <p>
+                The worker acts as a transparent proxy for your application. When configured, it fetches content from your site, injects a
+                <code>&lt;power-strip&gt;</code>, and serves it to the user.
+              </p>
+            </div>
+          </section>
+
+          <!-- Configuration -->
+          <section class="card">
+            <div class="card-header">Required Configuration</div>
+            <div class="card-body">
+              <p>
+                These variables <strong>must</strong> be set in your <code>wrangler.jsonc</code> or Cloudflare Dashboard for the worker to
+                function. Until these are configured, the worker serves this documentation page.
+              </p>
+
+              <div class="mb-4">
+                <h5>
+                  <span class="variable-name">ORIGIN_URL</span>
+                </h5>
+                <p>The base URL of the application you want to proxy, e.g. your app URL.</p>
+                <pre>ORIGIN_URL = "https://your-app-origin.com"</pre>
+              </div>
+
+              <div class="mb-4">
+                <h5>
+                  <span class="variable-name">SESSION_SECRET</span>
+                </h5>
+                <p>A long, random string used to encrypt session cookies. <strong>Keep this secret!</strong></p>
+                <pre>SESSION_SECRET = "your-long-random-secret-string"</pre>
+              </div>
+            </div>
+          </section>
+
+          <section class="card">
+            <div class="card-header">Optional Configuration</div>
+            <div class="card-body">
+              <div class="mb-4">
+                <h5>
+                  <span class="variable-name">USERS_PATH</span>
+                </h5>
+                <p>
+                  The URL path where the worker intercepts requests to serve Startup API UI (like
+                  <code>power-strip.js</code>).
+                </p>
+                <p><strong>Default:</strong> <code>/users/</code></p>
+                <pre>USERS_PATH = "/people/"</pre>
+              </div>
+            </div>
+          </section>
+
+          <!-- How it works -->
+          <section class="card">
+            <div class="card-header">How Injection Works</div>
+            <div class="card-body">
+              <ol>
+                <li>Worker receives a request.</li>
+                <li>
+                  If the path starts with
+                  <span class="variable-name">USERS_PATH</span>, it serves files from the <code>public/users/</code> directory.
+                </li>
+                <li>
+                  Otherwise, it proxies the request to
+                  <span class="variable-name">ORIGIN_URL</span>.
+                </li>
+                <li>
+                  If the response is <code>text/html</code>, it injects:
+                  <ul>
+                    <li>A <code>&lt;script&gt;</code> tag loading <code>power-strip.js</code>.</li>
+                    <li>A <code>&lt;power-strip&gt;</code> element styled to appear in the top-right corner.</li>
+                  </ul>
+                </li>
+              </ol>
+            </div>
+          </section>
+        </div>
+      </div>
+    </main>
+
+    <footer>
+      <p>&copy; 2026 Startup API. Licensed under Apache 2.0.</p>
+
+      <p>
+        <a href="https://github.com/StartupAPI/cloudflare" style="color: var(--primary-color); text-decoration: none">View on GitHub</a>
+      </p>
+    </footer>
+  </body>
+</html>