me3-protocol 2.1.0 → 2.2.0

package/dist/index.d.ts

@@ -47,6 +47,48 @@ export interface Me3Footer {
     /** 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;
@@ -74,6 +116,11 @@ export interface Me3Profile {
      * - `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

@@ -21,6 +21,9 @@ 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
  */
@@ -184,7 +187,10 @@ function validateProfile(data) {
             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" });
+                    errors.push({
+                        field: "footer.text",
+                        message: "Footer text must be a string",
+                    });
                 }
                 else if (footer.text.length > MAX_FOOTER_TEXT_LENGTH) {
                     errors.push({
@@ -195,12 +201,18 @@ function validateProfile(data) {
             }
             if (footer.link !== undefined) {
                 if (typeof footer.link !== "object" || footer.link === null) {
-                    errors.push({ field: "footer.link", message: "Footer link must be an object" });
+                    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" });
+                        errors.push({
+                            field: "footer.link.text",
+                            message: "Footer link text is required",
+                        });
                     }
                     else if (link.text.length > MAX_FOOTER_LINK_TEXT_LENGTH) {
                         errors.push({
@@ -209,7 +221,10 @@ function validateProfile(data) {
                         });
                     }
                     if (!link.url || typeof link.url !== "string") {
-                        errors.push({ field: "footer.link.url", message: "Footer link URL is required" });
+                        errors.push({
+                            field: "footer.link.url",
+                            message: "Footer link URL is required",
+                        });
                     }
                     else if (!URL_REGEX.test(link.url)) {
                         errors.push({
@@ -262,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

@@ -27,5 +27,21 @@
   ],
   "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.1.0",
+  "version": "2.2.0",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/schema.json

@@ -65,6 +65,88 @@
       ],
       "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": [
@@ -171,6 +253,10 @@
           "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"