me3-protocol 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+# me3 Protocol (me.json)
+
+The **me3 Protocol** (`me.json`) is a minimal standard for portable personal websites.
+
+It treats your online identity as a **"Digital Business Card"**—a single JSON file that makes you discoverable by both humans and AI agents, without locking you into a specific platform.
+
+## 1. The Specification
+
+### File Location & Discovery
+To be compliant, your `me.json` file must be hosted at one of the following locations (in order of priority):
+
+1.  **Primary**: `https://yourdomain.com/me.json`
+2.  **Fallback**: `https://yourdomain.com/.well-known/me`
+
+### Transport & Security
+*   **HTTPS Only**: The file must be served over a secure connection.
+*   **CORS (Cross-Origin Resource Sharing)**: You **MUST** serve the file with the following header:
+    ```http
+    Access-Control-Allow-Origin: *
+    ```
+    **Why?** This ensures that AI agents running in browsers (e.g., Chrome extensions, web-based assistants) can read your identity file even if they are running on a different domain. Without this, your digital business card is invisible to the tools that help people find you.
+
+### Content Type
+The file should be served with `application/json` content type.
+
+## 2. The Schema
+
+Your `me.json` defines who you are and where to find you. It is strictly typed to ensure compatibility across all readers.
+
+### Core Structure (`Me3Profile`)
+
+| Field | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `version` | `string` | **Yes** | Protocol version (currently "0.1"). |
+| `name` | `string` | **Yes** | Your display name. |
+| `handle` | `string` | No | Your preferred username/handle. |
+| `bio` | `string` | No | Short bio (max 500 chars). |
+| `avatar` | `string` | No | URL to your profile picture. |
+| `banner` | `string` | No | URL to a header/banner image. |
+| `links` | `object` | No | Social links (website, github, twitter, etc.). |
+| `buttons` | `array` | No | Primary actions (e.g., "Book Call", "Subscribe"). |
+| `pages` | `array` | No | Custom content pages. |
+
+### Example
+
+```json
+{
+  "version": "0.1",
+  "name": "Jane Doe",
+  "handle": "janedoe",
+  "bio": "Building the open web. Creative Director at Studio X.",
+  "avatar": "https://example.com/jane.jpg",
+  "links": {
+    "website": "https://janedoe.com",
+    "twitter": "janedoe",
+    "github": "janedoe"
+  },
+  "buttons": [
+    {
+      "text": "Hire Me",
+      "url": "https://cal.com/janedoe",
+      "style": "primary"
+    }
+  ]
+}
+```
+
+## 3. What it is NOT
+
+*   **NOT Authentication**: `me.json` is public data. It does not handle logins, passwords, or private keys.
+*   **NOT a Social Network**: There is no "feed", no "likes", and no central server. You own your data.
+*   **NOT a Platform**: You can host this file on GitHub Pages, Vercel, WordPress, or your own server.
+
+## 4. Usage
+
+### For Developers
+You can use this package to validate `me.json` files in your applications.
+
+```bash
+npm install me3-protocol
+```
+
+```typescript
+import { validateProfile, parseMe3Json } from 'me3-protocol'
+
+// Validate an object
+const result = validateProfile(myProfileData)
+
+// Parse and validate a string
+const result = parseMe3Json(jsonString)
+
+if (!result.valid) {
+  console.error(result.errors)
+}
+```
+
+### JSON Schema
+A standard JSON Schema is available in [schema.json](./schema.json) for non-TypeScript implementations.

package/examples/full.json

@@ -0,0 +1,20 @@
+{
+  "version": "0.1",
+  "name": "Kieran Butler",
+  "handle": "kieran",
+  "bio": "Intuitive. Coach. Coder. Creative. Building Soulink.",
+  "avatar": "https://api.dicebear.com/7.x/avataaars/svg?seed=kieran",
+  "banner": "https://images.unsplash.com/photo-1519681393784-d120267933ba?w=1200&h=400&fit=crop",
+  "links": {
+    "website": "https://kieranbutler.com",
+    "github": "kieranbutler",
+    "soulink": "kieran"
+  },
+  "buttons": [
+    { "text": "Book a Discovery Call", "url": "https://cal.com/kieran", "style": "primary", "icon": "📅" },
+    { "text": "Buy me a coffee", "url": "https://buymeacoffee.com/kieran", "style": "secondary", "icon": "☕" }
+  ],
+  "pages": [
+    { "slug": "about", "title": "About", "file": "about.md", "visible": true }
+  ]
+}

package/examples/simple.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.1",
+  "name": "Jane Doe",
+  "handle": "janedoe",
+  "bio": "Minimalist example.",
+  "links": {
+    "twitter": "janedoe"
+  }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "me3-protocol",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc",
+    "generate-schema": "ts-json-schema-generator --path 'src/index.ts' --type 'Me3Profile' --out 'schema.json' --no-type-check",
+    "prepublishOnly": "npm run build && npm run generate-schema"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soulink8/me3.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/soulink8/me3/issues"
+  },
+  "homepage": "https://github.com/soulink8/me3#readme",
+  "devDependencies": {
+    "ts-json-schema-generator": "^2.4.0",
+    "typescript": "^5.9.3"
+  }
+}

package/schema.json

@@ -0,0 +1,161 @@
+{
+  "$ref": "#/definitions/Me3Profile",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "Me3Button": {
+      "additionalProperties": false,
+      "properties": {
+        "icon": {
+          "description": "Optional icon (emoji or icon identifier)",
+          "type": "string"
+        },
+        "style": {
+          "description": "Button style",
+          "enum": [
+            "primary",
+            "secondary",
+            "outline"
+          ],
+          "type": "string"
+        },
+        "text": {
+          "description": "Button text (max 30 chars)",
+          "type": "string"
+        },
+        "url": {
+          "description": "URL to open when clicked",
+          "type": "string"
+        }
+      },
+      "required": [
+        "text",
+        "url"
+      ],
+      "type": "object"
+    },
+    "Me3Links": {
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "not": {}
+          }
+        ]
+      },
+      "properties": {
+        "email": {
+          "type": "string"
+        },
+        "github": {
+          "type": "string"
+        },
+        "instagram": {
+          "type": "string"
+        },
+        "linkedin": {
+          "type": "string"
+        },
+        "tiktok": {
+          "type": "string"
+        },
+        "twitter": {
+          "type": "string"
+        },
+        "website": {
+          "type": "string"
+        },
+        "youtube": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "Me3Page": {
+      "additionalProperties": false,
+      "description": "me3 Protocol v0.1\n\nA protocol for portable personal websites. Your site lives in a single me.json file that you can take anywhere.",
+      "properties": {
+        "file": {
+          "description": "Path to markdown file (relative to me.json)",
+          "type": "string"
+        },
+        "slug": {
+          "description": "URL-friendly identifier",
+          "type": "string"
+        },
+        "title": {
+          "description": "Display name for navigation",
+          "type": "string"
+        },
+        "visible": {
+          "description": "Whether to show in navigation",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "slug",
+        "title",
+        "file",
+        "visible"
+      ],
+      "type": "object"
+    },
+    "Me3Profile": {
+      "additionalProperties": false,
+      "properties": {
+        "avatar": {
+          "description": "Avatar URL (absolute or relative)",
+          "type": "string"
+        },
+        "banner": {
+          "description": "Banner/header image URL",
+          "type": "string"
+        },
+        "bio": {
+          "description": "Short bio",
+          "type": "string"
+        },
+        "buttons": {
+          "description": "Call-to-action buttons (max 3)",
+          "items": {
+            "$ref": "#/definitions/Me3Button"
+          },
+          "type": "array"
+        },
+        "handle": {
+          "description": "Username/handle",
+          "type": "string"
+        },
+        "links": {
+          "$ref": "#/definitions/Me3Links",
+          "description": "Social and external links"
+        },
+        "name": {
+          "description": "Display name (required)",
+          "type": "string"
+        },
+        "pages": {
+          "description": "Custom pages (markdown)",
+          "items": {
+            "$ref": "#/definitions/Me3Page"
+          },
+          "type": "array"
+        },
+        "theme": {
+          "description": "Theme identifier (for future use)",
+          "type": "string"
+        },
+        "version": {
+          "description": "Protocol version",
+          "type": "string"
+        }
+      },
+      "required": [
+        "version",
+        "name"
+      ],
+      "type": "object"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,246 @@
+/**
+ * me3 Protocol v0.1
+ * 
+ * A protocol for portable personal websites.
+ * Your site lives in a single me.json file that you can take anywhere.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Me3Page {
+  /** URL-friendly identifier */
+  slug: string
+  /** Display name for navigation */
+  title: string
+  /** Path to markdown file (relative to me.json) */
+  file: string
+  /** Whether to show in navigation */
+  visible: boolean
+}
+
+export interface Me3Links {
+  website?: string
+  github?: string
+  twitter?: string
+  linkedin?: string
+  instagram?: string
+  youtube?: string
+  tiktok?: string
+  email?: string
+  [key: string]: string | undefined
+}
+
+export interface Me3Button {
+  /** Button text (max 30 chars) */
+  text: string
+  /** URL to open when clicked */
+  url: string
+  /** Button style */
+  style?: 'primary' | 'secondary' | 'outline'
+  /** Optional icon (emoji or icon identifier) */
+  icon?: string
+}
+
+export interface Me3Profile {
+  /** Protocol version */
+  version: string
+  /** Display name (required) */
+  name: string
+  /** Username/handle */
+  handle?: string
+  /** Short bio */
+  bio?: string
+  /** Avatar URL (absolute or relative) */
+  avatar?: string
+  /** Banner/header image URL */
+  banner?: string
+  /** Social and external links */
+  links?: Me3Links
+  /** Call-to-action buttons (max 3) */
+  buttons?: Me3Button[]
+  /** Custom pages (markdown) */
+  pages?: Me3Page[]
+  /** Theme identifier (for future use) */
+  theme?: string
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+export interface ValidationError {
+  field: string
+  message: string
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: ValidationError[]
+  profile?: Me3Profile
+}
+
+const CURRENT_VERSION = '0.1'
+const MAX_NAME_LENGTH = 100
+const MAX_BIO_LENGTH = 500
+const MAX_HANDLE_LENGTH = 30
+const HANDLE_REGEX = /^[a-z0-9_-]+$/i
+const MAX_BUTTONS = 3
+const MAX_BUTTON_TEXT_LENGTH = 30
+const VALID_BUTTON_STYLES = ['primary', 'secondary', 'outline']
+const URL_REGEX = /^https?:\/\/.+/i
+
+/**
+ * Validate a me3 profile object
+ */
+export function validateProfile(data: unknown): ValidationResult {
+  const errors: ValidationError[] = []
+
+  if (!data || typeof data !== 'object') {
+    return {
+      valid: false,
+      errors: [{ field: 'root', message: 'Profile must be an object' }],
+    }
+  }
+
+  const profile = data as Record<string, unknown>
+
+  // Version (required)
+  if (!profile.version || typeof profile.version !== 'string') {
+    errors.push({ field: 'version', message: 'Version is required' })
+  } else if (profile.version !== CURRENT_VERSION) {
+    errors.push({ field: 'version', message: `Unsupported version. Expected ${CURRENT_VERSION}` })
+  }
+
+  // Name (required)
+  if (!profile.name || typeof profile.name !== 'string') {
+    errors.push({ field: 'name', message: 'Name is required' })
+  } else if (profile.name.length > MAX_NAME_LENGTH) {
+    errors.push({ field: 'name', message: `Name must be ${MAX_NAME_LENGTH} characters or less` })
+  }
+
+  // Handle (optional)
+  if (profile.handle !== undefined) {
+    if (typeof profile.handle !== 'string') {
+      errors.push({ field: 'handle', message: 'Handle must be a string' })
+    } else if (profile.handle.length > MAX_HANDLE_LENGTH) {
+      errors.push({ field: 'handle', message: `Handle must be ${MAX_HANDLE_LENGTH} characters or less` })
+    } else if (!HANDLE_REGEX.test(profile.handle)) {
+      errors.push({ field: 'handle', message: 'Handle can only contain letters, numbers, underscores, and hyphens' })
+    }
+  }
+
+  // Bio (optional)
+  if (profile.bio !== undefined) {
+    if (typeof profile.bio !== 'string') {
+      errors.push({ field: 'bio', message: 'Bio must be a string' })
+    } else if (profile.bio.length > MAX_BIO_LENGTH) {
+      errors.push({ field: 'bio', message: `Bio must be ${MAX_BIO_LENGTH} characters or less` })
+    }
+  }
+
+  // Avatar (optional)
+  if (profile.avatar !== undefined && typeof profile.avatar !== 'string') {
+    errors.push({ field: 'avatar', message: 'Avatar must be a string URL' })
+  }
+
+  // Banner (optional)
+  if (profile.banner !== undefined && typeof profile.banner !== 'string') {
+    errors.push({ field: 'banner', message: 'Banner must be a string URL' })
+  }
+
+  // Links (optional)
+  if (profile.links !== undefined) {
+    if (typeof profile.links !== 'object' || profile.links === null) {
+      errors.push({ field: 'links', message: 'Links must be an object' })
+    }
+  }
+
+  // Buttons (optional)
+  if (profile.buttons !== undefined) {
+    if (!Array.isArray(profile.buttons)) {
+      errors.push({ field: 'buttons', message: 'Buttons must be an array' })
+    } else {
+      if (profile.buttons.length > MAX_BUTTONS) {
+        errors.push({ field: 'buttons', message: `Maximum ${MAX_BUTTONS} buttons allowed` })
+      }
+      profile.buttons.forEach((button, index) => {
+        if (!button || typeof button !== 'object') {
+          errors.push({ field: `buttons[${index}]`, message: 'Button must be an object' })
+          return
+        }
+        if (!button.text || typeof button.text !== 'string') {
+          errors.push({ field: `buttons[${index}].text`, message: 'Button text is required' })
+        } else if (button.text.length > MAX_BUTTON_TEXT_LENGTH) {
+          errors.push({ field: `buttons[${index}].text`, message: `Button text must be ${MAX_BUTTON_TEXT_LENGTH} characters or less` })
+        }
+        if (!button.url || typeof button.url !== 'string') {
+          errors.push({ field: `buttons[${index}].url`, message: 'Button URL is required' })
+        } else if (!URL_REGEX.test(button.url)) {
+          errors.push({ field: `buttons[${index}].url`, message: 'Button URL must be a valid URL starting with http:// or https://' })
+        }
+        if (button.style !== undefined && !VALID_BUTTON_STYLES.includes(button.style)) {
+          errors.push({ field: `buttons[${index}].style`, message: `Button style must be one of: ${VALID_BUTTON_STYLES.join(', ')}` })
+        }
+        if (button.icon !== undefined && typeof button.icon !== 'string') {
+          errors.push({ field: `buttons[${index}].icon`, message: 'Button icon must be a string' })
+        }
+      })
+    }
+  }
+
+  // Pages (optional)
+  if (profile.pages !== undefined) {
+    if (!Array.isArray(profile.pages)) {
+      errors.push({ field: 'pages', message: 'Pages must be an array' })
+    } else {
+      profile.pages.forEach((page, index) => {
+        if (!page || typeof page !== 'object') {
+          errors.push({ field: `pages[${index}]`, message: 'Page must be an object' })
+          return
+        }
+        if (!page.slug || typeof page.slug !== 'string') {
+          errors.push({ field: `pages[${index}].slug`, message: 'Page slug is required' })
+        }
+        if (!page.title || typeof page.title !== 'string') {
+          errors.push({ field: `pages[${index}].title`, message: 'Page title is required' })
+        }
+        if (!page.file || typeof page.file !== 'string') {
+          errors.push({ field: `pages[${index}].file`, message: 'Page file is required' })
+        }
+        if (typeof page.visible !== 'boolean') {
+          errors.push({ field: `pages[${index}].visible`, message: 'Page visible must be a boolean' })
+        }
+      })
+    }
+  }
+
+  if (errors.length > 0) {
+    return { valid: false, errors }
+  }
+
+  return {
+    valid: true,
+    errors: [],
+    profile: profile as unknown as Me3Profile,
+  }
+}
+
+/**
+ * Parse and validate a me.json string
+ */
+export function parseMe3Json(jsonString: string): ValidationResult {
+  try {
+    const data = JSON.parse(jsonString)
+    return validateProfile(data)
+  } catch (e) {
+    return {
+      valid: false,
+      errors: [{ field: 'root', message: 'Invalid JSON' }],
+    }
+  }
+}
+
+export const ME3_VERSION = CURRENT_VERSION
+export const ME3_FILENAME = 'me.json'

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}