me3-protocol 2.0.0 → 2.2.0

package/README.md

@@ -6,7 +6,7 @@ It treats your online identity as a **"Digital Business Card"**—a single JSON
 
 ## Why it exists (brief)
 
-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.
+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.
 
 ## 1. The Specification
 
@@ -36,18 +36,19 @@ Your `me.json` defines who you are and where to find you. It is strictly typed t
 
 ### 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.                     |
-| `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.                             |
+| 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).        |
 
 ### Examples
 

package/dist/index.d.ts

@@ -35,6 +35,60 @@ export interface Me3Button {
     /** Optional icon (emoji or icon identifier) */
     icon?: string;
 }
+export interface Me3FooterLink {
+    /** Link text */
+    text: string;
+    /** URL to open when clicked */
+    url: string;
+}
+export interface Me3Footer {
+    /** Custom footer text (e.g. "Built by Jane") */
+    text?: string;
+    /** Optional custom footer link */
+    link?: Me3FooterLink;
+}
+/**
+ * Newsletter subscription intent.
+ * When enabled, the site accepts email subscriptions via POST /api/subscribe
+ */
+export interface Me3IntentSubscribe {
+    /** Whether newsletter signups are enabled */
+    enabled: boolean;
+    /** Newsletter title (e.g., "AI Weekly") - for agents to present context */
+    title?: string;
+    /** What subscribers will receive - for agents to explain the value */
+    description?: string;
+    /** How often subscribers will hear from you */
+    frequency?: "daily" | "weekly" | "monthly" | "irregular";
+}
+/**
+ * Booking/scheduling intent.
+ * Declares that the person accepts meeting bookings.
+ */
+export interface Me3IntentBook {
+    /** Whether booking is enabled */
+    enabled: boolean;
+    /** Meeting title (e.g., "30-min Consultation") */
+    title?: string;
+    /** What the meeting is about */
+    description?: string;
+    /** Meeting duration in minutes */
+    duration?: number;
+    /** Booking provider (e.g., "cal.com", "calendly") */
+    provider?: string;
+    /** Direct booking URL */
+    url: string;
+}
+/**
+ * Intents object - declares what actions visitors/agents can take.
+ * This is the machine-readable API contract for interacting with a person.
+ */
+export interface Me3Intents {
+    /** Newsletter subscription */
+    subscribe?: Me3IntentSubscribe;
+    /** Meeting booking */
+    book?: Me3IntentBook;
+}
 export interface Me3Profile {
     /** Protocol version */
     version: string;
@@ -56,6 +110,17 @@ export interface Me3Profile {
     buttons?: Me3Button[];
     /** Custom pages (markdown) */
     pages?: Me3Page[];
+    /**
+     * Custom footer configuration.
+     * - `undefined`: default footer behavior (renderer-defined)
+     * - `false`: hide footer (renderer may restrict this to Pro tiers)
+     */
+    footer?: Me3Footer | false;
+    /**
+     * Intents - machine-readable actions that visitors/agents can take.
+     * This is the API contract for interacting with the person.
+     */
+    intents?: Me3Intents;
 }
 export interface ValidationError {
     field: string;

package/dist/index.js

@@ -19,6 +19,11 @@ const MAX_BUTTONS = 3;
 const MAX_BUTTON_TEXT_LENGTH = 30;
 const VALID_BUTTON_STYLES = ["primary", "secondary", "outline"];
 const URL_REGEX = /^https?:\/\/.+/i;
+const MAX_FOOTER_TEXT_LENGTH = 200;
+const MAX_FOOTER_LINK_TEXT_LENGTH = 60;
+const MAX_INTENT_TITLE_LENGTH = 100;
+const MAX_INTENT_DESCRIPTION_LENGTH = 300;
+const VALID_FREQUENCIES = ["daily", "weekly", "monthly", "irregular"];
 /**
  * Validate a me3 profile object
  */
@@ -167,6 +172,70 @@ function validateProfile(data) {
             });
         }
     }
+    // Footer (optional)
+    if (profile.footer !== undefined) {
+        if (profile.footer === false) {
+            // ok (renderer may enforce tier restrictions)
+        }
+        else if (typeof profile.footer !== "object" || profile.footer === null) {
+            errors.push({
+                field: "footer",
+                message: "Footer must be an object or false",
+            });
+        }
+        else {
+            const footer = profile.footer;
+            if (footer.text !== undefined) {
+                if (typeof footer.text !== "string") {
+                    errors.push({
+                        field: "footer.text",
+                        message: "Footer text must be a string",
+                    });
+                }
+                else if (footer.text.length > MAX_FOOTER_TEXT_LENGTH) {
+                    errors.push({
+                        field: "footer.text",
+                        message: `Footer text must be ${MAX_FOOTER_TEXT_LENGTH} characters or less`,
+                    });
+                }
+            }
+            if (footer.link !== undefined) {
+                if (typeof footer.link !== "object" || footer.link === null) {
+                    errors.push({
+                        field: "footer.link",
+                        message: "Footer link must be an object",
+                    });
+                }
+                else {
+                    const link = footer.link;
+                    if (!link.text || typeof link.text !== "string") {
+                        errors.push({
+                            field: "footer.link.text",
+                            message: "Footer link text is required",
+                        });
+                    }
+                    else if (link.text.length > MAX_FOOTER_LINK_TEXT_LENGTH) {
+                        errors.push({
+                            field: "footer.link.text",
+                            message: `Footer link text must be ${MAX_FOOTER_LINK_TEXT_LENGTH} characters or less`,
+                        });
+                    }
+                    if (!link.url || typeof link.url !== "string") {
+                        errors.push({
+                            field: "footer.link.url",
+                            message: "Footer link URL is required",
+                        });
+                    }
+                    else if (!URL_REGEX.test(link.url)) {
+                        errors.push({
+                            field: "footer.link.url",
+                            message: "Footer link URL must be a valid URL starting with http:// or https://",
+                        });
+                    }
+                }
+            }
+        }
+    }
     // Pages (optional)
     if (profile.pages !== undefined) {
         if (!Array.isArray(profile.pages)) {
@@ -208,6 +277,141 @@ function validateProfile(data) {
             });
         }
     }
+    // Intents (optional)
+    if (profile.intents !== undefined) {
+        if (typeof profile.intents !== "object" || profile.intents === null) {
+            errors.push({ field: "intents", message: "Intents must be an object" });
+        }
+        else {
+            const intents = profile.intents;
+            // Validate subscribe intent
+            if (intents.subscribe !== undefined) {
+                if (typeof intents.subscribe !== "object" ||
+                    intents.subscribe === null) {
+                    errors.push({
+                        field: "intents.subscribe",
+                        message: "Subscribe intent must be an object",
+                    });
+                }
+                else {
+                    const subscribe = intents.subscribe;
+                    if (typeof subscribe.enabled !== "boolean") {
+                        errors.push({
+                            field: "intents.subscribe.enabled",
+                            message: "Subscribe enabled must be a boolean",
+                        });
+                    }
+                    if (subscribe.title !== undefined) {
+                        if (typeof subscribe.title !== "string") {
+                            errors.push({
+                                field: "intents.subscribe.title",
+                                message: "Subscribe title must be a string",
+                            });
+                        }
+                        else if (subscribe.title.length > MAX_INTENT_TITLE_LENGTH) {
+                            errors.push({
+                                field: "intents.subscribe.title",
+                                message: `Subscribe title must be ${MAX_INTENT_TITLE_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (subscribe.description !== undefined) {
+                        if (typeof subscribe.description !== "string") {
+                            errors.push({
+                                field: "intents.subscribe.description",
+                                message: "Subscribe description must be a string",
+                            });
+                        }
+                        else if (subscribe.description.length > MAX_INTENT_DESCRIPTION_LENGTH) {
+                            errors.push({
+                                field: "intents.subscribe.description",
+                                message: `Subscribe description must be ${MAX_INTENT_DESCRIPTION_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (subscribe.frequency !== undefined &&
+                        !VALID_FREQUENCIES.includes(subscribe.frequency)) {
+                        errors.push({
+                            field: "intents.subscribe.frequency",
+                            message: `Subscribe frequency must be one of: ${VALID_FREQUENCIES.join(", ")}`,
+                        });
+                    }
+                }
+            }
+            // Validate book intent
+            if (intents.book !== undefined) {
+                if (typeof intents.book !== "object" || intents.book === null) {
+                    errors.push({
+                        field: "intents.book",
+                        message: "Book intent must be an object",
+                    });
+                }
+                else {
+                    const book = intents.book;
+                    if (typeof book.enabled !== "boolean") {
+                        errors.push({
+                            field: "intents.book.enabled",
+                            message: "Book enabled must be a boolean",
+                        });
+                    }
+                    if (book.title !== undefined) {
+                        if (typeof book.title !== "string") {
+                            errors.push({
+                                field: "intents.book.title",
+                                message: "Book title must be a string",
+                            });
+                        }
+                        else if (book.title.length > MAX_INTENT_TITLE_LENGTH) {
+                            errors.push({
+                                field: "intents.book.title",
+                                message: `Book title must be ${MAX_INTENT_TITLE_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (book.description !== undefined) {
+                        if (typeof book.description !== "string") {
+                            errors.push({
+                                field: "intents.book.description",
+                                message: "Book description must be a string",
+                            });
+                        }
+                        else if (book.description.length > MAX_INTENT_DESCRIPTION_LENGTH) {
+                            errors.push({
+                                field: "intents.book.description",
+                                message: `Book description must be ${MAX_INTENT_DESCRIPTION_LENGTH} characters or less`,
+                            });
+                        }
+                    }
+                    if (book.duration !== undefined &&
+                        typeof book.duration !== "number") {
+                        errors.push({
+                            field: "intents.book.duration",
+                            message: "Book duration must be a number (minutes)",
+                        });
+                    }
+                    if (book.provider !== undefined &&
+                        typeof book.provider !== "string") {
+                        errors.push({
+                            field: "intents.book.provider",
+                            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",
+                        });
+                    }
+                    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://",
+                        });
+                    }
+                }
+            }
+        }
+    }
     if (errors.length > 0) {
         return { valid: false, errors };
     }

package/examples/full.json

@@ -1,31 +1,47 @@
 {
   "version": "0.1",
-  "name": "Kieran Butler",
-  "handle": "kieran",
-  "location": "Austin, TX",
-  "bio": "Intuitive. Coach. Coder. Creative. Building Soulink.",
-  "avatar": "https://api.dicebear.com/7.x/avataaars/svg?seed=kieran",
+  "name": "Example Name",
+  "handle": "example",
+  "location": "City, Country",
+  "bio": "Short example bio describing what this person does.",
+  "avatar": "https://api.dicebear.com/7.x/avataaars/svg?seed=example",
   "banner": "https://images.unsplash.com/photo-1519681393784-d120267933ba?w=1200&h=400&fit=crop",
   "links": {
-    "website": "https://kieranbutler.com",
-    "github": "kieranbutler",
-    "soulink": "kieran"
+    "website": "https://example.com",
+    "github": "example",
+    "soulink": "example"
   },
   "buttons": [
     {
-      "text": "Book a Discovery Call",
-      "url": "https://cal.com/kieran",
+      "text": "Primary Call To Action",
+      "url": "https://cal.com/example",
       "style": "primary",
       "icon": "📅"
     },
     {
-      "text": "Buy me a coffee",
-      "url": "https://buymeacoffee.com/kieran",
+      "text": "Secondary Action",
+      "url": "https://buymeacoffee.com/example",
       "style": "secondary",
       "icon": "☕"
     }
   ],
   "pages": [
     { "slug": "about", "title": "About", "file": "about.md", "visible": true }
-  ]
+  ],
+  "intents": {
+    "subscribe": {
+      "enabled": true,
+      "title": "Weekly Insights",
+      "description": "Curated thoughts on design, tech, and creativity every Sunday",
+      "frequency": "weekly"
+    },
+    "book": {
+      "enabled": true,
+      "title": "30-min Consultation",
+      "description": "Let's discuss your project",
+      "duration": 30,
+      "provider": "cal.com",
+      "url": "https://cal.com/example"
+    }
+  }
 }

package/package.json

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

package/schema.json

@@ -33,6 +33,120 @@
       ],
       "type": "object"
     },
+    "Me3Footer": {
+      "additionalProperties": false,
+      "properties": {
+        "link": {
+          "$ref": "#/definitions/Me3FooterLink",
+          "description": "Optional custom footer link"
+        },
+        "text": {
+          "description": "Custom footer text (e.g. \"Built by Jane\")",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "Me3FooterLink": {
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "description": "Link text",
+          "type": "string"
+        },
+        "url": {
+          "description": "URL to open when clicked",
+          "type": "string"
+        }
+      },
+      "required": [
+        "text",
+        "url"
+      ],
+      "type": "object"
+    },
+    "Me3IntentBook": {
+      "additionalProperties": false,
+      "description": "Booking/scheduling intent. Declares that the person accepts meeting bookings.",
+      "properties": {
+        "description": {
+          "description": "What the meeting is about",
+          "type": "string"
+        },
+        "duration": {
+          "description": "Meeting duration in minutes",
+          "type": "number"
+        },
+        "enabled": {
+          "description": "Whether booking is enabled",
+          "type": "boolean"
+        },
+        "provider": {
+          "description": "Booking provider (e.g., \"cal.com\", \"calendly\")",
+          "type": "string"
+        },
+        "title": {
+          "description": "Meeting title (e.g., \"30-min Consultation\")",
+          "type": "string"
+        },
+        "url": {
+          "description": "Direct booking URL",
+          "type": "string"
+        }
+      },
+      "required": [
+        "enabled",
+        "url"
+      ],
+      "type": "object"
+    },
+    "Me3IntentSubscribe": {
+      "additionalProperties": false,
+      "description": "Newsletter subscription intent. When enabled, the site accepts email subscriptions via POST /api/subscribe",
+      "properties": {
+        "description": {
+          "description": "What subscribers will receive - for agents to explain the value",
+          "type": "string"
+        },
+        "enabled": {
+          "description": "Whether newsletter signups are enabled",
+          "type": "boolean"
+        },
+        "frequency": {
+          "description": "How often subscribers will hear from you",
+          "enum": [
+            "daily",
+            "weekly",
+            "monthly",
+            "irregular"
+          ],
+          "type": "string"
+        },
+        "title": {
+          "description": "Newsletter title (e.g., \"AI Weekly\") - for agents to present context",
+          "type": "string"
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "type": "object"
+    },
+    "Me3Intents": {
+      "additionalProperties": false,
+      "description": "Intents object - declares what actions visitors/agents can take. This is the machine-readable API contract for interacting with a person.",
+      "properties": {
+        "book": {
+          "$ref": "#/definitions/Me3IntentBook",
+          "description": "Meeting booking"
+        },
+        "subscribe": {
+          "$ref": "#/definitions/Me3IntentSubscribe",
+          "description": "Newsletter subscription"
+        }
+      },
+      "type": "object"
+    },
     "Me3Links": {
       "additionalProperties": {
         "anyOf": [
@@ -123,10 +237,26 @@
           },
           "type": "array"
         },
+        "footer": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Me3Footer"
+            },
+            {
+              "const": false,
+              "type": "boolean"
+            }
+          ],
+          "description": "Custom footer configuration.\n- `undefined`: default footer behavior (renderer-defined)\n- `false`: hide footer (renderer may restrict this to Pro tiers)"
+        },
         "handle": {
           "description": "Username/handle",
           "type": "string"
         },
+        "intents": {
+          "$ref": "#/definitions/Me3Intents",
+          "description": "Intents - machine-readable actions that visitors/agents can take. This is the API contract for interacting with the person."
+        },
         "links": {
           "$ref": "#/definitions/Me3Links",
           "description": "Social and external links"