me3-protocol 2.2.0 → 2.3.0

package/README.md

@@ -1,115 +1,126 @@
 # me3 Protocol (me.json)
 
-The **me3 Protocol** (`me.json`) is a minimal standard for portable personal websites.
+**The place machines check before acting on a person.**
 
-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.
+`me.json` is a minimal protocol that lets you declare what actions AI agents and services can take on your behalf—and how.
 
-## Why it exists (brief)
+## The Problem
 
-People increasingly ask AI to _find_ a person (to hire, collaborate with, or learn from). Scraping arbitrary personal sites is a failure mode for agents: it’s brittle, slow, and ambiguous. `me.json` is a small, predictable identity endpoint that makes discovery and summarization reliable.
+Machines are already making decisions about people:
 
-## 1. The Specification
+- "Should I book a meeting with this person?"
+- "Can I subscribe them to updates?"
+- "How should I introduce them?"
 
-### File Location & Discovery
+Without an authoritative source, they guess. They scrape. They get it wrong.
 
-To be compliant, your `me.json` file must be hosted at one of the following locations (in order of priority):
+Schema.org describes _pages_. `me.json` declares _people_—their identity, their preferences, and their **intents**.
 
-1.  **Primary**: `https://yourdomain.com/me.json`
-2.  **Fallback**: `https://yourdomain.com/.well-known/me`
+## The Solution: Intents
 
-### Transport & Security
+The core of `me.json` is the `intents` object—machine-readable declarations of what visitors and agents can do:
 
-- **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.
+```json
+{
+  "version": "0.1",
+  "name": "Jane Doe",
+  "bio": "Creative Director at Studio X",
+  "intents": {
+    "subscribe": {
+      "enabled": true,
+      "title": "Design Weekly",
+      "description": "Curated design links every Sunday",
+      "frequency": "weekly"
+    },
+    "book": {
+      "enabled": true,
+      "title": "30-min Consultation",
+      "description": "Let's discuss your project",
+      "duration": 30,
+      "url": "https://cal.com/janedoe"
+    }
+  }
+}
+```
 
-### Content Type
+**Without `me.json`**: An AI asked "Can I book a call with Jane?" has to guess, scrape her site, or fail.
 
-The file should be served with `application/json` content type.
+**With `me.json`**: The AI reads `intents.book`, confirms it's enabled, and knows exactly where to send the user.
 
-## 2. The Schema
+That's the protocol's value: **authority before action**.
 
-Your `me.json` defines who you are and where to find you. It is strictly typed to ensure compatibility across all readers.
+## Supported Intents
 
-### Core Structure (`Me3Profile`)
+| Intent      | Purpose                      | Key Fields                                           |
+| :---------- | :--------------------------- | :--------------------------------------------------- |
+| `subscribe` | Newsletter/updates signup    | `enabled`, `title`, `description`, `frequency`       |
+| `book`      | Meeting/consultation booking | `enabled`, `title`, `description`, `url`, `duration` |
 
-| 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.                     |
-| `location` | `string` | No       | Freeform location string (e.g. "Remote").         |
-| `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.                             |
-| `footer`   | `object` | No       | Custom footer config (or `false` to hide).        |
+More intents (like `contact` for routing preferences) are planned.
 
-### Examples
+---
 
-Minimal:
+## Full Schema
 
-```json
-{
-  "version": "0.1",
-  "name": "Jane Doe",
-  "handle": "janedoe",
-  "bio": "Building the open web. Creative Director at Studio X.",
-  "location": "Berlin, Germany",
-  "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"
-    }
-  ]
-}
-```
+Beyond intents, `me.json` includes identity and presentation fields:
+
+| Field      | Type     | Required | Description                                          |
+| :--------- | :------- | :------- | :--------------------------------------------------- |
+| `version`  | `string` | **Yes**  | Protocol version (currently `"0.1"`).                |
+| `name`     | `string` | **Yes**  | Display name.                                        |
+| `handle`   | `string` | No       | Preferred username/handle.                           |
+| `bio`      | `string` | No       | Short bio (max 500 chars).                           |
+| `avatar`   | `string` | No       | Profile picture URL.                                 |
+| `banner`   | `string` | No       | Header/banner image URL.                             |
+| `location` | `string` | No       | Freeform location (e.g., "Berlin" or "Remote").      |
+| `links`    | `object` | No       | Social links (`website`, `github`, `twitter`, etc.). |
+| `buttons`  | `array`  | No       | Call-to-action buttons for human visitors.           |
+| `pages`    | `array`  | No       | Custom content pages (markdown).                     |
+| `intents`  | `object` | No       | Machine-actionable declarations (see above).         |
+| `footer`   | `object` | No       | Footer config (or `false` to hide).                  |
+
+See [`examples/full.json`](./examples/full.json) for a complete example.
+
+---
+
+## Hosting & Discovery
+
+Your `me.json` must be publicly accessible at:
 
-More complete examples live in [`examples/`](./examples/), including [`examples/simple.json`](./examples/simple.json) and [`examples/full.json`](./examples/full.json).
+1. **Primary**: `https://yourdomain.com/me.json`
+2. **Fallback**: `https://yourdomain.com/.well-known/me`
 
-## 3. What it is NOT
+### Requirements
 
-- **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.
-- **NOT Reputation / Ranking**: No scoring, ranking, endorsements, verification, or algorithmic ordering.
+- **HTTPS only**
+- **CORS enabled**: Serve with `Access-Control-Allow-Origin: *` so browser-based agents can read it
+- **Content-Type**: `application/json`
 
-## 4. Guardrails & versioning
+---
 
-- **Current version**: `0.1` (see `version` field). Validators in this repo currently require `version === "0.1"`.
-- **Backwards compatibility**: `0.1` is intended to stay stable. Changes should be additive and conservative.
-- **Extensions**: top-level fields are intentionally strict. If you need custom keys, prefer placing them under `links` (e.g. `"links": { "mastodon": "...", "custom": "..." }`) until the protocol defines a first-class place for extensions.
+## What me.json is NOT
 
-## 5. Usage
+- **NOT authentication** — This is public data. No logins, no private keys.
+- **NOT a social network** — No feeds, no likes, no central server.
+- **NOT a platform** — Host it anywhere: GitHub Pages, Vercel, your own server.
+- **NOT reputation** — No scores, rankings, or verification.
 
-### For Developers
+---
 
-You can use this package to validate `me.json` files in your applications.
+## Usage
+
+### Install
 
 ```bash
 npm install me3-protocol
 ```
 
+### Validate
+
 ```typescript
 import { validateProfile, parseMe3Json } from "me3-protocol";
 
-// Validate an object
-const result = validateProfile(myProfileData);
-
-// Parse and validate a string
-const result = parseMe3Json(jsonString);
+const result = validateProfile(profileData);
 
 if (!result.valid) {
   console.error(result.errors);
@@ -118,4 +129,12 @@ if (!result.valid) {
 
 ### JSON Schema
 
-A standard JSON Schema is available in [schema.json](./schema.json) for non-TypeScript implementations.
+A standard JSON Schema is available at [`schema.json`](./schema.json).
+
+---
+
+## Versioning
+
+- **Current version**: `0.1`
+- **Stability**: Additive changes only. Breaking changes require a version bump.
+- **Extensions**: Custom fields should go under `links` until the protocol defines extension points.

package/dist/index.d.ts

@@ -61,6 +61,24 @@ export interface Me3IntentSubscribe {
     /** How often subscribers will hear from you */
     frequency?: "daily" | "weekly" | "monthly" | "irregular";
 }
+/**
+ * Availability windows for booking.
+ * Defines when the person is available for meetings.
+ */
+export interface Me3BookingAvailability {
+    /** Timezone for the availability windows (e.g., "America/New_York") */
+    timezone: string;
+    /** Weekly availability windows by day */
+    windows: {
+        monday?: string[];
+        tuesday?: string[];
+        wednesday?: string[];
+        thursday?: string[];
+        friday?: string[];
+        saturday?: string[];
+        sunday?: string[];
+    };
+}
 /**
  * Booking/scheduling intent.
  * Declares that the person accepts meeting bookings.
@@ -74,10 +92,12 @@ export interface Me3IntentBook {
     description?: string;
     /** Meeting duration in minutes */
     duration?: number;
-    /** Booking provider (e.g., "cal.com", "calendly") */
+    /** Booking provider (e.g., "cal.com", "calendly") - for external providers */
     provider?: string;
-    /** Direct booking URL */
-    url: string;
+    /** Direct booking URL - for external booking systems */
+    url?: string;
+    /** Availability windows - for native me3 booking */
+    availability?: Me3BookingAvailability;
 }
 /**
  * Intents object - declares what actions visitors/agents can take.

package/dist/index.js

@@ -396,16 +396,93 @@ function validateProfile(data) {
                             message: "Book provider must be a string",
                         });
                     }
-                    if (!book.url || typeof book.url !== "string") {
-                        errors.push({
-                            field: "intents.book.url",
-                            message: "Book URL is required",
-                        });
+                    // URL is optional if availability is set (native me3 booking)
+                    if (book.url !== undefined) {
+                        if (typeof book.url !== "string") {
+                            errors.push({
+                                field: "intents.book.url",
+                                message: "Book URL must be a string",
+                            });
+                        }
+                        else if (!URL_REGEX.test(book.url)) {
+                            errors.push({
+                                field: "intents.book.url",
+                                message: "Book URL must be a valid URL starting with http:// or https://",
+                            });
+                        }
+                    }
+                    // Validate availability if present
+                    if (book.availability !== undefined) {
+                        if (typeof book.availability !== "object" ||
+                            book.availability === null) {
+                            errors.push({
+                                field: "intents.book.availability",
+                                message: "Book availability must be an object",
+                            });
+                        }
+                        else {
+                            const availability = book.availability;
+                            if (!availability.timezone ||
+                                typeof availability.timezone !== "string") {
+                                errors.push({
+                                    field: "intents.book.availability.timezone",
+                                    message: "Availability timezone is required",
+                                });
+                            }
+                            if (availability.windows !== undefined) {
+                                if (typeof availability.windows !== "object" ||
+                                    availability.windows === null) {
+                                    errors.push({
+                                        field: "intents.book.availability.windows",
+                                        message: "Availability windows must be an object",
+                                    });
+                                }
+                                else {
+                                    const windows = availability.windows;
+                                    const validDays = [
+                                        "monday",
+                                        "tuesday",
+                                        "wednesday",
+                                        "thursday",
+                                        "friday",
+                                        "saturday",
+                                        "sunday",
+                                    ];
+                                    const timeWindowRegex = /^\d{2}:\d{2}-\d{2}:\d{2}$/;
+                                    for (const [day, value] of Object.entries(windows)) {
+                                        if (!validDays.includes(day)) {
+                                            errors.push({
+                                                field: `intents.book.availability.windows.${day}`,
+                                                message: `Invalid day: ${day}`,
+                                            });
+                                            continue;
+                                        }
+                                        if (!Array.isArray(value)) {
+                                            errors.push({
+                                                field: `intents.book.availability.windows.${day}`,
+                                                message: `Windows for ${day} must be an array`,
+                                            });
+                                            continue;
+                                        }
+                                        for (const window of value) {
+                                            if (typeof window !== "string" ||
+                                                !timeWindowRegex.test(window)) {
+                                                errors.push({
+                                                    field: `intents.book.availability.windows.${day}`,
+                                                    message: `Invalid time window format. Use HH:MM-HH:MM`,
+                                                });
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
                     }
-                    else if (!URL_REGEX.test(book.url)) {
+                    // Either URL or availability must be set for booking to work
+                    if (!book.url && !book.availability) {
                         errors.push({
-                            field: "intents.book.url",
-                            message: "Book URL must be a valid URL starting with http:// or https://",
+                            field: "intents.book",
+                            message: "Book intent requires either a URL (for external booking) or availability (for native booking)",
                         });
                     }
                 }

package/examples/full.json

@@ -40,8 +40,16 @@
       "title": "30-min Consultation",
       "description": "Let's discuss your project",
       "duration": 30,
-      "provider": "cal.com",
-      "url": "https://cal.com/example"
+      "availability": {
+        "timezone": "America/New_York",
+        "windows": {
+          "monday": ["09:00-12:00", "14:00-17:00"],
+          "tuesday": ["09:00-17:00"],
+          "wednesday": ["09:00-17:00"],
+          "thursday": ["09:00-17:00"],
+          "friday": ["09:00-12:00"]
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "me3-protocol",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/schema.json

@@ -2,6 +2,70 @@
   "$ref": "#/definitions/Me3Profile",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "definitions": {
+    "Me3BookingAvailability": {
+      "additionalProperties": false,
+      "description": "Availability windows for booking. Defines when the person is available for meetings.",
+      "properties": {
+        "timezone": {
+          "description": "Timezone for the availability windows (e.g., \"America/New_York\")",
+          "type": "string"
+        },
+        "windows": {
+          "additionalProperties": false,
+          "description": "Weekly availability windows by day",
+          "properties": {
+            "friday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "monday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "saturday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "sunday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "thursday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "tuesday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "wednesday": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "type": "object"
+        }
+      },
+      "required": [
+        "timezone",
+        "windows"
+      ],
+      "type": "object"
+    },
     "Me3Button": {
       "additionalProperties": false,
       "properties": {
@@ -69,6 +133,10 @@
       "additionalProperties": false,
       "description": "Booking/scheduling intent. Declares that the person accepts meeting bookings.",
       "properties": {
+        "availability": {
+          "$ref": "#/definitions/Me3BookingAvailability",
+          "description": "Availability windows - for native me3 booking"
+        },
         "description": {
           "description": "What the meeting is about",
           "type": "string"
@@ -82,7 +150,7 @@
           "type": "boolean"
         },
         "provider": {
-          "description": "Booking provider (e.g., \"cal.com\", \"calendly\")",
+          "description": "Booking provider (e.g., \"cal.com\", \"calendly\") - for external providers",
           "type": "string"
         },
         "title": {
@@ -90,13 +158,12 @@
           "type": "string"
         },
         "url": {
-          "description": "Direct booking URL",
+          "description": "Direct booking URL - for external booking systems",
           "type": "string"
         }
       },
       "required": [
-        "enabled",
-        "url"
+        "enabled"
       ],
       "type": "object"
     },