npm - enigmatic - Versions diffs - 0.34.0 → 0.36.0 - Mend

enigmatic 0.34.0 → 0.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/README.md +62 -96
package/bin/enigmatic.js +3 -0
package/client/public/AGENTS.md +314 -0
package/client/public/api.html +202 -0
package/client/public/client.js +106 -0
package/client/public/index.html +414 -0
package/clientserver.png +0 -0
package/package.json +7 -9
package/server/bun-server.js +132 -0
package/__tests__/e2.test.js +0 -340
package/__tests__/jest.config.js +0 -7
package/__tests__/jest.setup.js +0 -9
package/beemap.js +0 -47
package/bun-server.js +0 -122
package/public/client.js +0 -118
package/public/index.html +0 -48
package/public/index2.html +0 -10
/package/{public → client/public}/custom.js +0 -0

package/README.md CHANGED Viewed

@@ -1,9 +1,15 @@
 # Enigmatic
-![Tests](https://img.shields.io/badge/tests-26%20passing-brightgreen) ![Size](https://img.shields.io/badge/size-3.4%20KB-blue) ![Version](https://img.shields.io/npm/v/enigmatic)
+![Version](https://img.shields.io/npm/v/enigmatic)
 A lightweight client-side JavaScript library for DOM manipulation, reactive state management, and API interactions, with an optional Bun server for backend functionality.
+## Architecture
+![Client-Server Architecture](clientserver.png)
+The diagram above shows the interaction between the client (browser), Bun server, and external services (Auth0 and Cloudflare R2/S3).
 ## Quick Start
 ### Using client.js via CDN
@@ -14,66 +20,54 @@ Include `client.js` in any HTML file using the unpkg CDN:
 <!DOCTYPE html>
 <html>
 <head>
-  <script src="https://unpkg.com/enigmatic@0.34.0/public/client.js"></script>
+  <script src="https://unpkg.com/enigmatic"></script>
+  <script src="https://unpkg.com/enigmatic/client/public/custom.js"></script>
   <script>
-    // Configure your API URL
     window.api_url = 'https://your-server.com';
-    // Define custom elements
-    window.custom = {
-      "hello-world": (data) => `Hello ${data || 'World'}`
-    };
+    window.state.message = 'Hello World';
   </script>
 </head>
 <body>
   <hello-world data="message"></hello-world>
-  <script>
-    window.state.message = "Hello World";
-  </script>
 </body>
 </html>
 ```
-**Note:** Replace `0.34.0` with the latest version number from [npm](https://www.npmjs.com/package/enigmatic).
+**Note:** Use `enigmatic@0.35.0` (or latest) in the URL to pin a version.
 ### Using the Bun Server
-The Bun server provides a complete backend implementation with:
-- Key-value storage (using BeeMap)
-- File storage (using Cloudflare R2/S3)
-- Authentication (using Auth0)
-- Static file serving
+The Bun server provides a complete backend with:
+- **Key-value storage** – Per-user KV persisted as append-only JSONL (`server/kv/{user}.jsonl`) with `update`/`delete` actions and timestamps
+- **File storage** – Per-user files via Cloudflare R2 (or S3-compatible API)
+- **Authentication** – Auth0 OAuth2 login/logout
+- **Static files** – Served from `client/public/`
 #### Installation
-1. Install Bun (if not already installed):
+1. Install [Bun](https://bun.sh):
    ```bash
    curl -fsSL https://bun.sh/install | bash
    ```
-2. Install dependencies:
+2. Install dependencies (if any):
    ```bash
    bun install
    ```
-3. Generate HTTPS certificates (for local development):
-   ```bash
-   cd server
-   ./generate-certs.sh
-   cd ..
-   ```
+3. TLS certificates: place `cert.pem` and `key.pem` in `server/certs/` for HTTPS (required for Auth0 in production).
 #### Environment Variables
-Create a `.env` file in the project root with the following variables:
+Create a `.env` file in the project root (or set env vars):
 ```bash
-# Auth0 Configuration
+# Auth0
 AUTH0_DOMAIN=your-tenant.auth0.com
 AUTH0_CLIENT_ID=your-client-id
 AUTH0_CLIENT_SECRET=your-client-secret
-# Cloudflare R2 Configuration (optional, for file storage)
+# Cloudflare R2 (optional, for file storage)
 CLOUDFLARE_ACCESS_KEY_ID=your-access-key-id
 CLOUDFLARE_SECRET_ACCESS_KEY=your-secret-access-key
 CLOUDFLARE_BUCKET_NAME=your-bucket-name
@@ -82,37 +76,33 @@ CLOUDFLARE_PUBLIC_URL=https://your-account-id.r2.cloudflarestorage.com
 #### Running the Server
-Start the server with hot reload:
 ```bash
 npm start
 # or
-bun --hot ./bun-server.js
+npx enigmatic
+# or with hot reload
+npm run hot
 ```
-The server will start on `https://localhost:3000` (HTTPS is required for Auth0 cookies).
-#### Server Features
-- **Static File Serving**: Automatically serves any files from the `public/` folder
-- **Key-Value Storage**: Per-user KV storage using BeeMap (persisted to JSONL files)
-- **File Storage**: Per-user file storage using Cloudflare R2 (or compatible S3)
-- **Authentication**: OAuth2 flow with Auth0
-- **CORS**: Enabled for all origins (configurable)
+Server runs at **https://localhost:3000** (HTTPS is required for Auth0 cookies).
 #### Server Endpoints
-- `GET /` or `GET /index.html` - Serves `public/index.html`
-- `GET /{path}` - Serves static files from `public/` folder
-- `GET /login` - Initiates Auth0 login flow
-- `GET /callback` - Auth0 callback handler
-- `GET /logout` - Logs out user
-- `GET /{key}` - Retrieves KV value (requires auth)
-- `POST /{key}` - Stores KV value (requires auth)
-- `DELETE /{key}` - Deletes KV value (requires auth)
-- `PUT /{key}` - Uploads file to R2 (requires auth)
-- `PURGE /{key}` - Deletes file from R2 (requires auth)
-- `PROPFIND /` - Lists files in R2 (requires auth)
-- `PATCH /{key}` - Downloads file from R2 (requires auth)
+| Method   | Path       | Description |
+|----------|------------|-------------|
+| GET      | `/`        | Serves `client/public/index.html` |
+| GET      | `/index.html`, `/*.js`, etc. | Static files from `client/public/` |
+| GET      | `/login`   | Redirects to Auth0 login |
+| GET      | `/callback`| Auth0 OAuth callback |
+| GET      | `/logout`  | Logs out and clears session |
+| GET      | `/me`      | Current user or 401 (no auth) |
+| GET      | `/{key}`   | KV get (auth required) |
+| POST     | `/{key}`   | KV set (auth required) |
+| DELETE   | `/{key}`   | KV delete (auth required) |
+| PUT      | `/{key}`   | Upload file to R2 (auth required) |
+| PURGE    | `/{key}`   | Delete file from R2 (auth required) |
+| PROPFIND | `/`        | List R2 files (auth required) |
+| PATCH    | `/{key}`   | Download file from R2 (auth required) |
 ## Overview
@@ -137,7 +127,7 @@ const elements = window.$$('.my-class');
 ### API Base URL
 ```javascript
-window.api_url = "https://localhost:3000"
+window.api_url = "https://localhost:3001"
 ```
 Configures the base URL for all API requests. Modify this to point to your server.
@@ -283,6 +273,16 @@ window.logout();
 **Behavior:** Sets `window.location.href` to `{api_url}/logout`
+#### `window.me()`
+Returns the current user if authenticated, or `null` if not (e.g. 401).
+```javascript
+const user = await window.me();
+// user is { sub, email, ... } or null
+```
+**Endpoint:** `GET {api_url}/me` (with credentials)
 ## Custom Elements System
 Custom elements are defined in `window.custom` object and automatically initialized when the DOM loads or when elements are added dynamically.
@@ -397,42 +397,18 @@ window.get('key').catch(err => console.error(err));
 <!DOCTYPE html>
 <html>
 <head>
-  <script src="https://unpkg.com/enigmatic@0.34.0/public/client.js"></script>
+  <script src="https://unpkg.com/enigmatic"></script>
+  <script src="https://unpkg.com/enigmatic/client/public/custom.js"></script>
   <script>
-    // Configure API URL
-    window.api_url = 'https://localhost:3000';
-    // Define custom elements
-    window.custom = {
-      "hello-world": (data) => `Hello ${data || 'World'}`
-    };
+    window.api_url = window.api_url || window.location.origin;
+    window.state.message = 'World';
   </script>
 </head>
 <body>
-  <!-- Custom element with reactive state -->
   <hello-world data="message"></hello-world>
+  <file-widget></file-widget>
   <script>
-    // Set reactive state (triggers updates to elements with data="message")
-    window.state.message = "Hello World";
-    // Use API functions
-    (async () => {
-      await window.set('test', 'value');
-      const value = await window.get('test');
-      console.log(value);
-      // Upload file
-      const fileInput = document.querySelector('input[type="file"]');
-      fileInput.onchange = async (e) => {
-        const file = e.target.files[0];
-        await window.put(file.name, file);
-      };
-      // List files
-      const files = await window.list();
-      console.log(files);
-    })();
+    window.me().then(u => console.log(u ? 'Logged in as ' + u.email : 'Not logged in'));
   </script>
 </body>
 </html>
@@ -448,7 +424,7 @@ window.get('key').catch(err => console.error(err));
   - `URL.createObjectURL`
   - `MutationObserver` API
-**Note:** Custom element definitions can be loaded before or after `client.js` - the Proxy system will handle initialization either way.
+**Note:** Load `client.js` first, then your custom element definitions (e.g. `custom.js`); the Proxy initializes elements when definitions are assigned.
 ## Notes
@@ -464,19 +440,9 @@ window.get('key').catch(err => console.error(err));
 ## Development
-### Running Tests
-```bash
-npm test
-```
-### Building
-The library is ready to use as-is. For production, you can use the minified version:
-```html
-<script src="https://unpkg.com/enigmatic@0.34.0/public/client.min.js"></script>
-```
+- **Start server:** `npm start` or `npx enigmatic`
+- **Hot reload:** `npm run hot`
+- **Client:** Load `client.js` from unpkg or from `client/public/client.js` when serving locally. Load `custom.js` (or your definitions) after `client.js`; set `window.api_url` before making API calls.
 ## License

package/bin/enigmatic.js ADDED Viewed

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import config from "../server/bun-server.js";
+Bun.serve(config);

package/client/public/AGENTS.md ADDED Viewed

@@ -0,0 +1,314 @@
+# Custom Web Components Instructions for LLMs
+## Overview
+When users request web components to be created, you MUST use the `window.custom` system. You can see examples at https://unpkg.com/enigmatic/client/public/custom.js or in the repo at `client/public/custom.js`. This system allows you to define custom HTML elements that automatically render and can be reactive to state changes.
+## System Architecture
+The custom component system works by:
+1. Defining components in `window.custom` object
+2. Using custom HTML tags in the DOM (e.g., `<my-component></my-component>`)
+3. Components automatically initialize when the DOM loads or when elements are added
+4. Components can be reactive to `window.state` changes via `data` attributes
+## Component Definition Format
+### Format 1: Function-Based Component (Simple)
+**Use this format for simple components that just render HTML:**
+```javascript
+window.custom = {
+  "mycomponent": (data) => {
+    // data is the value from window.state if element has data="key" attribute
+    // If no data attribute, data will be undefined
+    return `<div>Your HTML here: ${data || 'default'}</div>`;
+  }
+};
+```
+**Example from custom.js:**
+```javascript
+window.custom = {
+  "hello-world": (data) => `Hello ${data}`,
+};
+```
+**HTML Usage:**
+```html
+<hello-world></hello-world>
+<!-- or with reactive state -->
+<hello-world data="message"></hello-world>
+<script>
+  window.state.message = "World"; // Component updates automatically
+</script>
+```
+### Format 2: Object-Based Component (Advanced)
+**Use this format when you need methods, properties, or more complex logic:**
+```javascript
+window.custom = {
+  "component-name": {
+    // Optional helper methods
+    prop: (data) => `Processed: ${data}`,
+    // Required: render method that returns HTML string
+    render: function(data) {
+      // Use 'this' to access other methods/properties
+      return `<div>${this.prop(data)}</div>`;
+    }
+  }
+};
+```
+**Example from custom.js:**
+```javascript
+window.custom = {
+  "hello-world-2": {
+    prop: (data) => `${data} World`,
+    render: function(data) {
+      return this.prop(data);
+    }
+  }
+};
+```
+**HTML Usage:**
+```html
+<hello-world-2 data="greeting"></hello-world-2>
+<script>
+  window.state.greeting = "Hello"; // Component updates automatically
+</script>
+```
+### Format 3: Async Component
+**Use this format when you need to fetch data or perform async operations:**
+```javascript
+window.custom = {
+  "async-component": async () => {
+    try {
+      const data = await window.get('some-key');
+      // Or use other API functions: window.list(), window.set(), etc.
+      return `<div>${JSON.stringify(data)}</div>`;
+    } catch (err) {
+      return `<div>Error: ${err.message}</div>`;
+    }
+  }
+};
+```
+**Example from custom.js:**
+```javascript
+window.custom = {
+  "file-widget": async () => {
+    try {
+      const list = await window.list();
+      // Render file list with styles and interactive elements
+      return `<div>...</div>`;
+    } catch (err) {
+      return `<div>Error occurred</div>`;
+    }
+  }
+};
+```
+## Key Rules and Patterns
+### 1. Component Names
+- Use kebab-case (e.g., `"my-component"`, `"file-widget"`)
+- Must match the HTML tag name exactly (case-insensitive)
+- Example: `window.custom["my-component"]` → `<my-component></my-component>`
+### 2. Return Value
+- Components MUST return a string containing HTML
+- Can include inline `<style>` tags for component-specific styles
+- Can include inline event handlers using `onclick`, `onchange`, etc.
+### 3. Reactive State Integration
+- Components automatically receive state values when element has `data="key"` attribute
+- When `window.state.key = value` is set, all elements with `data="key"` are re-rendered
+- Access state value as the first parameter: `(data) => ...` or `render: function(data) { ... }`
+### 4. Async Operations
+- Use `async` functions when you need to fetch data
+- Use `window.get()`, `window.set()`, `window.list()`, `window.put()`, `window.delete()`, `window.purge()`, `window.me()`, `window.download()`, etc. for API calls (all use `window.api_url`)
+- Always wrap async operations in try-catch for error handling
+### 5. Styling
+- Include styles inline using `<style>` tags within the returned HTML
+- Use scoped class names (e.g., `.w-c`, `.w-i`) to avoid conflicts
+- Keep styles minimal and component-specific
+### 6. Event Handlers
+- Use inline event handlers: `onclick="..."`, `onchange="..."`
+- Can call `window` API functions directly: `onclick="window.download('file.txt')"`
+- For async operations, wrap in IIFE: `onclick="(async()=>{await window.purge('file');location.reload()})()"`
+## Complete Examples
+### Example 1: Simple Counter Component
+```javascript
+window.custom = {
+  "counter": (data) => {
+    const count = data || 0;
+    return `
+      <div style="padding: 20px; text-align: center;">
+        <h2>Count: ${count}</h2>
+        <button onclick="window.state.count = (window.state.count || 0) + 1">+</button>
+        <button onclick="window.state.count = (window.state.count || 0) - 1">-</button>
+      </div>
+    `;
+  }
+};
+```
+**HTML:**
+```html
+<counter data="count"></counter>
+<script>
+  window.state.count = 0;
+</script>
+```
+### Example 2: Data Display Component
+```javascript
+window.custom = {
+  "data-display": async () => {
+    try {
+      const data = await window.get('user-data');
+      return `
+        <div style="padding: 15px; border: 1px solid #ddd; border-radius: 5px;">
+          <h3>User Data</h3>
+          <pre>${JSON.stringify(data, null, 2)}</pre>
+        </div>
+      `;
+    } catch (err) {
+      return `<div style="color: red;">Error loading data: ${err.message}</div>`;
+    }
+  }
+};
+```
+**HTML:**
+```html
+<data-display></data-display>
+```
+### Example 3: Form Component with Object Methods
+```javascript
+window.custom = {
+  "contact-form": {
+    validate: (email) => email && email.includes('@'),
+    render: function(data) {
+      const email = data?.email || '';
+      const isValid = this.validate(email);
+      return `
+        <style>
+          .form-container { padding: 20px; max-width: 400px; }
+          .form-input { width: 100%; padding: 8px; margin: 5px 0; }
+          .form-submit { background: #007bff; color: white; padding: 10px 20px; border: none; cursor: pointer; }
+        </style>
+        <div class="form-container">
+          <input type="email" class="form-input"
+                 placeholder="Email"
+                 value="${email}"
+                 onchange="window.state.formData = {...(window.state.formData || {}), email: this.value}">
+          <button class="form-submit"
+                  onclick="alert('Form submitted!')"
+                  ${!isValid ? 'disabled' : ''}>
+            Submit
+          </button>
+        </div>
+      `;
+    }
+  }
+};
+```
+**HTML:**
+```html
+<contact-form data="formData"></contact-form>
+<script>
+  window.state.formData = { email: '' };
+</script>
+```
+## When to Use Each Format
+- **Function format**: Simple components, static content, or when you only need the data parameter
+- **Object format**: When you need helper methods, want to organize code better, or need `this` context
+- **Async format**: When you need to fetch data from APIs, perform async operations, or load external resources
+## Important Notes
+1. **Always return HTML strings** - Components must return valid HTML strings
+2. **Handle errors** - Wrap async operations in try-catch blocks
+3. **Use kebab-case** - Component names must be in kebab-case to match HTML tag names
+4. **State reactivity** - Use `data="key"` attribute to make components reactive to `window.state[key]`
+5. **Auto-initialization** - Components automatically initialize when:
+   - DOM loads
+   - Component is added to `window.custom`
+   - New matching elements are added to the DOM
+## Common Patterns
+### Pattern: Loading State
+```javascript
+window.custom = {
+  "loading-component": async () => {
+    try {
+      const data = await window.get('data');
+      return data ? `<div>${data}</div>` : '<div>No data</div>';
+    } catch (err) {
+      return `<div>Error: ${err.message}</div>`;
+    }
+  }
+};
+```
+### Pattern: Error Handling
+```javascript
+window.custom = {
+  "safe-component": async () => {
+    try {
+      const result = await window.list();
+      return `<div>Success: ${result.length} items</div>`;
+    } catch (err) {
+      return `<div style="color: red;">Error: ${err.message}</div>`;
+    }
+  }
+};
+```
+### Pattern: Conditional Rendering
+```javascript
+window.custom = {
+  "conditional": (data) => {
+    if (!data) return '<div>No data</div>';
+    if (data.error) return `<div>Error: ${data.error}</div>`;
+    return `<div>Data: ${data.value}</div>`;
+  }
+};
+```
+## Summary
+When creating web components:
+1. Define them in `window.custom` object
+2. Use kebab-case names matching HTML tag names
+3. Return HTML strings (can include styles and event handlers)
+4. Use function format for simple components
+5. Use object format with `render` method for complex components
+6. Use async functions when fetching data
+7. Make components reactive by using `data="key"` attributes
+8. Always handle errors in async components