@sockethub/platform-messenger 0.0.0-stage → 1.0.0-beta.3

package/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# `@sockethub/platform-messenger`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Outgoing text messages through Meta's Messenger API. This is a stateless,
+authenticated platform: set credentials, then send. No connect action or webhook
+endpoint is needed. Incoming messages and recipient discovery are external.
+
+## Setup
+
+The Sockethub CLI bundles this platform. For a custom server installation, install
+`@sockethub/platform-messenger` and include it in your config's `platforms` list
+alongside the other platforms you use. Node.js >= 20.19 and Redis >= 6 are required.
+
+Use a Page access token with `pages_messaging`. The actor ID is your
+Facebook Page ID; the target ID is the recipient's Page-scoped ID (PSID),
+obtained through your external incoming-message integration. A username, phone
+number, or ID scoped to a different app/account is not a substitute.
+
+This implementation sends as a Facebook Page, not a personal Facebook profile.
+
+Create a Meta developer app, add the messaging use case, connect your account,
+and use app-role/tester accounts for a private development-mode proof of concept.
+Public use and Human Agent access depend on Meta permissions and review; owning
+the account does not remove those requirements. Obtain tokens outside Sockethub.
+
+## Examples app
+
+Run `bun run dev` and open `/examples/messenger` on the Sockethub server.
+Enter your account ID, access token, Graph API version, and scoped recipient ID
+to send a text reply. Human Agent tagging is optional and off by default.
+
+## Usage
+
+This server-side JavaScript example uses runtime environment variables. In a
+browser, obtain credentials through your application's secure runtime flow.
+Choose a supported Graph API version enabled for your Meta app explicitly.
+
+```javascript
+import SockethubClient from '@sockethub/client';
+
+const sc = await SockethubClient.connect('http://localhost:10550');
+await sc.ready();
+const actor = { id: process.env.META_ACCOUNT_ID, type: 'person' };
+
+sc.socket.emit('credentials', {
+  '@context': sc.contextFor('messenger'),
+  type: 'credentials',
+  actor,
+  object: {
+    type: 'credentials',
+    token: process.env.META_ACCESS_TOKEN,
+    apiVersion: process.env.META_API_VERSION
+  }
+}, (ack) => {
+  if (ack?.error) {
+    console.error(ack.error);
+    return;
+  }
+  sc.socket.emit('message', {
+    '@context': sc.contextFor('messenger'),
+    type: 'send',
+    actor,
+    target: { id: process.env.META_RECIPIENT_ID, type: 'person' },
+    object: { type: 'message', content: 'Hello from Sockethub!' }
+  }, (result) => {
+    if (result?.error) {
+      console.error(result.error);
+      return;
+    }
+    // A successful send returns the original activity with object.id set to
+    // Meta's message ID. This confirms API acceptance, not delivery or reading.
+    console.log(result.object?.id);
+  });
+});
+
+// On explicit logout or when switching users, clear the client-side replay
+// state and disconnect. Credentials already stored for this server session
+// stay usable until the socket disconnects; a new connection starts a fresh
+// session that cannot reach them.
+// sc.clearCredentials();
+// sc.socket.disconnect();
+```
+
+## Limits and failures
+
+- Text only, up to 2000 characters per message.
+- Standard replies use Meta's normal messaging window. Sockethub does not track
+  incoming messages or calculate eligibility; Meta enforces its policies.
+- Set `object.humanAgent: true` only for an eligible manual support reply when
+  your Meta app has Human Agent access. This explicitly adds `HUMAN_AGENT`;
+  Messenger also sets `messaging_type: MESSAGE_TAG`.
+  It does not grant access, verify human authorship, or restart the window.
+- Meta error code `10` with subcode `2018278` or `2534022` returns the stable
+  marker `meta:messaging-window-closed` followed by the original diagnostic details.
+  Clients can recognise this marker in the acknowledgement's `error` string;
+  permission failures are not classified as window failures.
+- Meta failures return the HTTP status, error code/subcode, and error message.
+  Requests time out after 15 seconds. There are no platform-level retries:
+  after a network timeout, delivery is unknown, so retrying may duplicate a send.
+- No inbound messages, delivery/read receipts, OAuth onboarding, attachments,
+  conversation history, or webhook hosting.
+
+See [Meta's Messenger API collection](https://www.postman.com/meta/messenger-platform-api/documentation/iyp204x/messenger-platform-api)
+for access requirements and the underlying API.
+
+API contract references:
+
+- [Meta error codes](https://developers.facebook.com/docs/messenger-platform/error-codes/)

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import type { ActivityStream, CredentialsObject, PlatformCallback, PlatformInterface, PlatformSession, StatelessPlatformConfig } from "@sockethub/schemas";
+export interface MessengerCredentials extends CredentialsObject {
+    object: {
+        type: "credentials";
+        token: string;
+        apiVersion: string;
+    };
+}
+export default class Messenger implements PlatformInterface {
+    private readonly log;
+    config: StatelessPlatformConfig;
+    constructor(session: PlatformSession);
+    get schema(): {
+        name: string;
+        version: string;
+        contextUrl: string;
+        contextVersion: string;
+        schemaVersion: string;
+        messages: {
+            required: string[];
+            properties: {
+                type: {
+                    enum: string[];
+                };
+                actor: {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        id: {
+                            type: string;
+                            pattern: string;
+                            maxLength: number;
+                        };
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                target: {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        id: {
+                            type: string;
+                            pattern: string;
+                            maxLength: number;
+                        };
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                object: {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        content: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                        };
+                        humanAgent: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+        credentials: {
+            required: string[];
+            properties: {
+                object: {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        token: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                            pattern: string;
+                        };
+                        apiVersion: {
+                            type: string;
+                            pattern: string;
+                        };
+                    };
+                };
+            };
+        };
+        responses: {
+            type: string;
+            required: string[];
+            properties: {
+                "@context": {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                };
+                type: {
+                    const: string;
+                };
+                actor: {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        id: {
+                            type: string;
+                            pattern: string;
+                            maxLength: number;
+                        };
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                target: {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        id: {
+                            type: string;
+                            pattern: string;
+                            maxLength: number;
+                        };
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                object: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        id: {
+                            type: string;
+                            minLength: number;
+                        };
+                        content: {
+                            type: string;
+                        };
+                        humanAgent: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    isInitialized(): boolean;
+    cleanup(done: PlatformCallback): void;
+    send(job: ActivityStream, credentials: MessengerCredentials, done: PlatformCallback): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,210 @@
+// package.json
+var package_default = {
+  name: "@sockethub/platform-messenger",
+  description: "Outgoing text messages through the Meta Messenger API",
+  version: "1.0.0-beta.3",
+  type: "module",
+  private: false,
+  license: "LGPL-3.0+",
+  publishConfig: {
+    access: "public"
+  },
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js",
+      default: "./dist/index.js"
+    }
+  },
+  files: [
+    "dist/"
+  ],
+  engines: {
+    node: ">=20.19"
+  },
+  scripts: {
+    build: "bun build src/index.ts --outdir dist --target node --format esm --sourcemap=external",
+    clean: "rm -rf dist",
+    "clean:deps": "rm -rf node_modules",
+    test: "bun test src/"
+  },
+  dependencies: {
+    "@sockethub/schemas": "^3.0.0-beta.3"
+  },
+  devDependencies: {
+    "@types/bun": "latest"
+  },
+  peerDependencies: {
+    "@sockethub/server": "^5.0.0-beta.3"
+  },
+  peerDependenciesMeta: {
+    "@sockethub/server": {
+      optional: true
+    }
+  },
+  gitHead: "bc04522d60d1e2fa1b3098b339897de62c3b0549"
+};
+
+// src/schema.ts
+var identity = {
+  type: "object",
+  required: ["id", "type"],
+  additionalProperties: false,
+  properties: {
+    id: { type: "string", pattern: "^[0-9]+$", maxLength: 128 },
+    type: { const: "person" }
+  }
+};
+var PlatformMessengerSchema = {
+  name: "messenger",
+  version: package_default.version,
+  contextUrl: "https://sockethub.org/ns/context/platform/messenger/v1.jsonld",
+  contextVersion: "1",
+  schemaVersion: "1",
+  messages: {
+    required: ["type", "actor", "target", "object"],
+    properties: {
+      type: { enum: ["send"] },
+      actor: identity,
+      target: identity,
+      object: {
+        type: "object",
+        required: ["type", "content"],
+        additionalProperties: false,
+        properties: {
+          type: { const: "message" },
+          content: { type: "string", minLength: 1, maxLength: 2000 },
+          humanAgent: { type: "boolean" }
+        }
+      }
+    }
+  },
+  credentials: {
+    required: ["object"],
+    properties: {
+      object: {
+        type: "object",
+        required: ["type", "token", "apiVersion"],
+        additionalProperties: false,
+        properties: {
+          type: { const: "credentials" },
+          token: {
+            type: "string",
+            minLength: 1,
+            maxLength: 8192,
+            pattern: "^[^\\r\\n]+$"
+          },
+          apiVersion: {
+            type: "string",
+            pattern: "^v[0-9]{1,3}\\.[0-9]{1,2}$"
+          }
+        }
+      }
+    }
+  },
+  responses: {
+    type: "object",
+    required: ["@context", "type", "actor", "target", "object"],
+    properties: {
+      "@context": { type: "array", items: { type: "string" } },
+      type: { const: "send" },
+      actor: identity,
+      target: identity,
+      object: {
+        type: "object",
+        required: ["type", "id", "content"],
+        properties: {
+          type: { const: "message" },
+          id: { type: "string", minLength: 1 },
+          content: { type: "string" },
+          humanAgent: { type: "boolean" }
+        }
+      }
+    }
+  }
+};
+
+// src/index.ts
+class Messenger {
+  log;
+  config = {
+    persist: false,
+    requireCredentials: ["send"]
+  };
+  constructor(session) {
+    this.log = session.log;
+  }
+  get schema() {
+    return PlatformMessengerSchema;
+  }
+  isInitialized() {
+    return true;
+  }
+  cleanup(done) {
+    done();
+  }
+  async send(job, credentials, done) {
+    const { token, apiVersion } = credentials.object;
+    const humanAgent = job.object.humanAgent === true;
+    let result;
+    try {
+      const response = await fetch(`https://graph.facebook.com/${apiVersion}/${encodeURIComponent(job.actor.id)}/messages`, {
+        method: "POST",
+        redirect: "error",
+        headers: {
+          authorization: `Bearer ${token}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify({
+          recipient: { id: job.target.id },
+          message: { text: job.object.content },
+          messaging_type: humanAgent ? "MESSAGE_TAG" : "RESPONSE",
+          ...humanAgent ? { tag: "HUMAN_AGENT" } : {}
+        }),
+        signal: AbortSignal.timeout(15000)
+      });
+      const data = await response.json();
+      if (!data || typeof data !== "object") {
+        throw new Error("messenger: invalid API response");
+      }
+      if ("error" in data || !response.ok) {
+        const error = "error" in data ? data.error : undefined;
+        let detail = `HTTP ${response.status}`;
+        if (error && typeof error === "object") {
+          if ("code" in error && typeof error.code === "number") {
+            detail += `, code ${error.code}`;
+          }
+          if ("error_subcode" in error && typeof error.error_subcode === "number") {
+            detail += `, subcode ${error.error_subcode}`;
+          }
+          if ("message" in error && typeof error.message === "string") {
+            detail += `: ${error.message.split(token).join("[redacted]")}`;
+          }
+        }
+        const windowClosed = error && typeof error === "object" && "code" in error && error.code === 10 && "error_subcode" in error && (error.error_subcode === 2018278 || error.error_subcode === 2534022);
+        const reason = windowClosed ? "meta:messaging-window-closed" : "messenger: send rejected";
+        throw new Error(`${reason} (${detail})`);
+      }
+      if (!("message_id" in data) || typeof data.message_id !== "string" || !data.message_id) {
+        throw new Error("messenger: API response missing message_id");
+      }
+      result = {
+        ...job,
+        object: { ...job.object, id: data.message_id }
+      };
+    } catch (error) {
+      const failure = error instanceof Error && (error.message.startsWith("messenger:") || error.message.startsWith("meta:messaging-window-closed")) ? new Error(error.message.split(token).join("[redacted]")) : new Error("messenger: send failed (network error, timeout, or invalid JSON); delivery is unknown");
+      this.log.warn(`send failed for actor ${job.actor.id} on messenger`);
+      done(failure);
+      return;
+    }
+    done(null, result);
+  }
+}
+export {
+  Messenger as default
+};
+
+//# debugId=26BEBDC5E9854B7964756E2164756E21

package/dist/index.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/schema.ts", "../src/index.ts"],
+  "sourcesContent": [
+    "import packageJson from \"../package.json\" with { type: \"json\" };\n\nconst identity = {\n    type: \"object\",\n    required: [\"id\", \"type\"],\n    additionalProperties: false,\n    properties: {\n        id: { type: \"string\", pattern: \"^[0-9]+$\", maxLength: 128 },\n        type: { const: \"person\" },\n    },\n};\n\nexport const PlatformMessengerSchema = {\n    name: \"messenger\",\n    version: packageJson.version,\n    contextUrl: \"https://sockethub.org/ns/context/platform/messenger/v1.jsonld\",\n    contextVersion: \"1\",\n    schemaVersion: \"1\",\n    messages: {\n        required: [\"type\", \"actor\", \"target\", \"object\"],\n        properties: {\n            type: { enum: [\"send\"] },\n            actor: identity,\n            target: identity,\n            object: {\n                type: \"object\",\n                required: [\"type\", \"content\"],\n                additionalProperties: false,\n                properties: {\n                    type: { const: \"message\" },\n                    content: { type: \"string\", minLength: 1, maxLength: 2000 },\n                    humanAgent: { type: \"boolean\" },\n                },\n            },\n        },\n    },\n    credentials: {\n        required: [\"object\"],\n        properties: {\n            object: {\n                type: \"object\",\n                required: [\"type\", \"token\", \"apiVersion\"],\n                additionalProperties: false,\n                properties: {\n                    type: { const: \"credentials\" },\n                    token: {\n                        type: \"string\",\n                        minLength: 1,\n                        maxLength: 8192,\n                        pattern: \"^[^\\\\r\\\\n]+$\",\n                    },\n                    apiVersion: {\n                        type: \"string\",\n                        pattern: \"^v[0-9]{1,3}\\\\.[0-9]{1,2}$\",\n                    },\n                },\n            },\n        },\n    },\n    responses: {\n        type: \"object\",\n        required: [\"@context\", \"type\", \"actor\", \"target\", \"object\"],\n        properties: {\n            \"@context\": { type: \"array\", items: { type: \"string\" } },\n            type: { const: \"send\" },\n            actor: identity,\n            target: identity,\n            object: {\n                type: \"object\",\n                required: [\"type\", \"id\", \"content\"],\n                properties: {\n                    type: { const: \"message\" },\n                    id: { type: \"string\", minLength: 1 },\n                    content: { type: \"string\" },\n                    humanAgent: { type: \"boolean\" },\n                },\n            },\n        },\n    },\n};\n",
+    "import type {\n    ActivityStream,\n    CredentialsObject,\n    Logger,\n    PlatformCallback,\n    PlatformInterface,\n    PlatformSession,\n    StatelessPlatformConfig,\n} from \"@sockethub/schemas\";\nimport { PlatformMessengerSchema } from \"./schema.js\";\n\nexport interface MessengerCredentials extends CredentialsObject {\n    object: { type: \"credentials\"; token: string; apiVersion: string };\n}\n\nexport default class Messenger implements PlatformInterface {\n    private readonly log: Logger;\n    config: StatelessPlatformConfig = {\n        persist: false,\n        requireCredentials: [\"send\"],\n    };\n\n    constructor(session: PlatformSession) {\n        this.log = session.log;\n    }\n\n    get schema() {\n        return PlatformMessengerSchema;\n    }\n\n    isInitialized(): boolean {\n        return true;\n    }\n\n    cleanup(done: PlatformCallback): void {\n        done();\n    }\n\n    async send(\n        job: ActivityStream,\n        credentials: MessengerCredentials,\n        done: PlatformCallback,\n    ): Promise<void> {\n        const { token, apiVersion } = credentials.object;\n        const humanAgent = job.object.humanAgent === true;\n        let result: ActivityStream;\n        try {\n            const response = await fetch(\n                `https://graph.facebook.com/${apiVersion}/${encodeURIComponent(job.actor.id)}/messages`,\n                {\n                    method: \"POST\",\n                    redirect: \"error\",\n                    headers: {\n                        authorization: `Bearer ${token}`,\n                        \"content-type\": \"application/json\",\n                    },\n                    body: JSON.stringify({\n                        recipient: { id: job.target.id },\n                        message: { text: job.object.content },\n                        messaging_type: humanAgent ? \"MESSAGE_TAG\" : \"RESPONSE\",\n                        ...(humanAgent ? { tag: \"HUMAN_AGENT\" } : {}),\n                    }),\n                    signal: AbortSignal.timeout(15_000),\n                },\n            );\n            const data: unknown = await response.json();\n            if (!data || typeof data !== \"object\") {\n                throw new Error(\"messenger: invalid API response\");\n            }\n            if (\"error\" in data || !response.ok) {\n                const error = \"error\" in data ? data.error : undefined;\n                let detail = `HTTP ${response.status}`;\n                if (error && typeof error === \"object\") {\n                    if (\"code\" in error && typeof error.code === \"number\") {\n                        detail += `, code ${error.code}`;\n                    }\n                    if (\n                        \"error_subcode\" in error &&\n                        typeof error.error_subcode === \"number\"\n                    ) {\n                        detail += `, subcode ${error.error_subcode}`;\n                    }\n                    if (\n                        \"message\" in error &&\n                        typeof error.message === \"string\"\n                    ) {\n                        detail += `: ${error.message.split(token).join(\"[redacted]\")}`;\n                    }\n                }\n                const windowClosed =\n                    error &&\n                    typeof error === \"object\" &&\n                    \"code\" in error &&\n                    error.code === 10 &&\n                    \"error_subcode\" in error &&\n                    (error.error_subcode === 2018278 ||\n                        error.error_subcode === 2534022);\n                const reason = windowClosed\n                    ? \"meta:messaging-window-closed\"\n                    : \"messenger: send rejected\";\n                throw new Error(`${reason} (${detail})`);\n            }\n            if (\n                !(\"message_id\" in data) ||\n                typeof data.message_id !== \"string\" ||\n                !data.message_id\n            ) {\n                throw new Error(\"messenger: API response missing message_id\");\n            }\n            result = {\n                ...job,\n                object: { ...job.object, id: data.message_id },\n            };\n        } catch (error) {\n            // Network errors may contain request details; never expose tokens.\n            const failure =\n                error instanceof Error &&\n                (error.message.startsWith(\"messenger:\") ||\n                    error.message.startsWith(\"meta:messaging-window-closed\"))\n                    ? new Error(error.message.split(token).join(\"[redacted]\"))\n                    : new Error(\n                          \"messenger: send failed (network error, timeout, or invalid JSON); delivery is unknown\",\n                      );\n            this.log.warn(`send failed for actor ${job.actor.id} on messenger`);\n            done(failure);\n            return;\n        }\n        done(null, result);\n    }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "26BEBDC5E9854B7964756E2164756E21",
+  "names": []
+}

package/dist/schema.d.ts

@@ -0,0 +1,152 @@
+export declare const PlatformMessengerSchema: {
+    name: string;
+    version: string;
+    contextUrl: string;
+    contextVersion: string;
+    schemaVersion: string;
+    messages: {
+        required: string[];
+        properties: {
+            type: {
+                enum: string[];
+            };
+            actor: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    id: {
+                        type: string;
+                        pattern: string;
+                        maxLength: number;
+                    };
+                    type: {
+                        const: string;
+                    };
+                };
+            };
+            target: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    id: {
+                        type: string;
+                        pattern: string;
+                        maxLength: number;
+                    };
+                    type: {
+                        const: string;
+                    };
+                };
+            };
+            object: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    content: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                    };
+                    humanAgent: {
+                        type: string;
+                    };
+                };
+            };
+        };
+    };
+    credentials: {
+        required: string[];
+        properties: {
+            object: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    token: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                        pattern: string;
+                    };
+                    apiVersion: {
+                        type: string;
+                        pattern: string;
+                    };
+                };
+            };
+        };
+    };
+    responses: {
+        type: string;
+        required: string[];
+        properties: {
+            "@context": {
+                type: string;
+                items: {
+                    type: string;
+                };
+            };
+            type: {
+                const: string;
+            };
+            actor: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    id: {
+                        type: string;
+                        pattern: string;
+                        maxLength: number;
+                    };
+                    type: {
+                        const: string;
+                    };
+                };
+            };
+            target: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    id: {
+                        type: string;
+                        pattern: string;
+                        maxLength: number;
+                    };
+                    type: {
+                        const: string;
+                    };
+                };
+            };
+            object: {
+                type: string;
+                required: string[];
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    id: {
+                        type: string;
+                        minLength: number;
+                    };
+                    content: {
+                        type: string;
+                    };
+                    humanAgent: {
+                        type: string;
+                    };
+                };
+            };
+        };
+    };
+};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@sockethub/platform-messenger",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Outgoing text messages through the Meta Messenger API",
+  "version": "1.0.0-beta.3",
+  "type": "module",
+  "private": false,
+  "license": "LGPL-3.0+",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --sourcemap=external",
+    "clean": "rm -rf dist",
+    "clean:deps": "rm -rf node_modules",
+    "test": "bun test src/"
+  },
+  "dependencies": {
+    "@sockethub/schemas": "^3.0.0-beta.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "@sockethub/server": "^5.0.0-beta.3"
+  },
+  "peerDependenciesMeta": {
+    "@sockethub/server": {
+      "optional": true
+    }
+  },
+  "gitHead": "603d4edd90e1f0f0b70c4ab759be5f70b24020ea"
+}