@sockethub/platform-whatsapp 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,88 @@
-# Temporary Holding Version
+# `@sockethub/platform-whatsapp`
 
-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 the WhatsApp Business Cloud 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-whatsapp` and include it in your config's `platforms` list
+alongside the other platforms you use. Node.js >= 20.19 and Redis >= 6 are required.
+
+Create a Meta developer app with the WhatsApp use case and register a business
+phone number. Use a system-user or temporary access token with
+`whatsapp_business_messaging`. The actor ID is the **phone number ID** shown in
+the app's WhatsApp API setup (not the phone number itself); the target ID is the
+recipient's phone number in international format, for example `+15551234567`.
+
+This implementation sends as a WhatsApp Business number through Meta's Cloud
+API, not as a personal WhatsApp account. Obtain tokens outside Sockethub.
+
+## 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.WHATSAPP_PHONE_NUMBER_ID, type: 'person' };
+
+sc.socket.emit('credentials', {
+  '@context': sc.contextFor('whatsapp'),
+  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('whatsapp'),
+    type: 'send',
+    actor,
+    target: { id: '+15551234567', 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
+    // the WhatsApp message ID (wamid). This confirms API acceptance, not
+    // delivery or reading.
+    console.log(result.object?.id);
+  });
+});
+```
+
+## Limits and failures
+
+- Text only, up to 4096 characters per message. Link previews are off.
+- Free-form text is only accepted within 24 hours of the recipient's last
+  message to your number. Sockethub does not track incoming messages or
+  calculate eligibility; Meta enforces its policies. Template messages, which
+  are required to start a conversation, are not supported.
+- Meta error code `131047` returns the stable marker
+  `meta:messaging-window-closed` followed by the original diagnostic details,
+  matching the Messenger and Instagram platforms.
+- Meta failures return the HTTP status, error code, 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, templates, media, interactive
+  messages, or webhook hosting.
+
+API contract references:
+
+- [Send messages](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages)
+- [Error codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes)

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import type { ActivityStream, CredentialsObject, PlatformCallback, PlatformInterface, PlatformSession, StatelessPlatformConfig } from "@sockethub/schemas";
+export interface WhatsAppCredentials extends CredentialsObject {
+    object: {
+        type: "credentials";
+        token: string;
+        apiVersion: string;
+    };
+}
+export default class WhatsApp 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;
+                        };
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                object: {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        content: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                        };
+                    };
+                };
+            };
+        };
+        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;
+                        };
+                        type: {
+                            const: string;
+                        };
+                    };
+                };
+                object: {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                        id: {
+                            type: string;
+                            minLength: number;
+                        };
+                        content: {
+                            type: string;
+                        };
+                    };
+                };
+            };
+        };
+    };
+    isInitialized(): boolean;
+    cleanup(done: PlatformCallback): void;
+    send(job: ActivityStream, credentials: WhatsAppCredentials, done: PlatformCallback): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,212 @@
+// package.json
+var package_default = {
+  name: "@sockethub/platform-whatsapp",
+  description: "Outgoing text messages through the WhatsApp Business Cloud 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 actor = {
+  type: "object",
+  required: ["id", "type"],
+  additionalProperties: false,
+  properties: {
+    id: { type: "string", pattern: "^[0-9]+$", maxLength: 128 },
+    type: { const: "person" }
+  }
+};
+var target = {
+  type: "object",
+  required: ["id", "type"],
+  additionalProperties: false,
+  properties: {
+    id: { type: "string", pattern: "^\\+?[1-9][0-9]{6,14}$" },
+    type: { const: "person" }
+  }
+};
+var PlatformWhatsAppSchema = {
+  name: "whatsapp",
+  version: package_default.version,
+  contextUrl: "https://sockethub.org/ns/context/platform/whatsapp/v1.jsonld",
+  contextVersion: "1",
+  schemaVersion: "1",
+  messages: {
+    required: ["type", "actor", "target", "object"],
+    properties: {
+      type: { enum: ["send"] },
+      actor,
+      target,
+      object: {
+        type: "object",
+        required: ["type", "content"],
+        additionalProperties: false,
+        properties: {
+          type: { const: "message" },
+          content: { type: "string", minLength: 1, maxLength: 4096 }
+        }
+      }
+    }
+  },
+  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,
+      target,
+      object: {
+        type: "object",
+        required: ["type", "id", "content"],
+        properties: {
+          type: { const: "message" },
+          id: { type: "string", minLength: 1 },
+          content: { type: "string" }
+        }
+      }
+    }
+  }
+};
+
+// src/index.ts
+class WhatsApp {
+  log;
+  config = {
+    persist: false,
+    requireCredentials: ["send"]
+  };
+  constructor(session) {
+    this.log = session.log;
+  }
+  get schema() {
+    return PlatformWhatsAppSchema;
+  }
+  isInitialized() {
+    return true;
+  }
+  cleanup(done) {
+    done();
+  }
+  async send(job, credentials, done) {
+    const { token, apiVersion } = credentials.object;
+    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({
+          messaging_product: "whatsapp",
+          recipient_type: "individual",
+          to: job.target.id,
+          type: "text",
+          text: { body: job.object.content, preview_url: false }
+        }),
+        signal: AbortSignal.timeout(15000)
+      });
+      const data = await response.json();
+      if (!data || typeof data !== "object") {
+        throw new Error("whatsapp: 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 ("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 === 131047;
+        const reason = windowClosed ? "meta:messaging-window-closed" : "whatsapp: send rejected";
+        throw new Error(`${reason} (${detail})`);
+      }
+      const id = "messages" in data && Array.isArray(data.messages) && data.messages[0] && typeof data.messages[0] === "object" && "id" in data.messages[0] ? data.messages[0].id : undefined;
+      if (typeof id !== "string" || !id) {
+        throw new Error("whatsapp: API response missing message id");
+      }
+      result = { ...job, object: { ...job.object, id } };
+    } catch (error) {
+      const failure = error instanceof Error && (error.message.startsWith("whatsapp:") || error.message.startsWith("meta:messaging-window-closed")) ? new Error(error.message.split(token).join("[redacted]")) : new Error("whatsapp: send failed (network error, timeout, or invalid JSON); delivery is unknown");
+      this.log.warn(`send failed for actor ${job.actor.id} on whatsapp`);
+      done(failure);
+      return;
+    }
+    done(null, result);
+  }
+}
+export {
+  WhatsApp as default
+};
+
+//# debugId=645C91CA9AEA149964756E2164756E21

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\n// actor: WhatsApp Business phone number ID (Meta-assigned, numeric).\nconst actor = {\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\n// target: recipient phone number in international format (E.164 digits).\nconst target = {\n    type: \"object\",\n    required: [\"id\", \"type\"],\n    additionalProperties: false,\n    properties: {\n        id: { type: \"string\", pattern: \"^\\\\+?[1-9][0-9]{6,14}$\" },\n        type: { const: \"person\" },\n    },\n};\n\nexport const PlatformWhatsAppSchema = {\n    name: \"whatsapp\",\n    version: packageJson.version,\n    contextUrl: \"https://sockethub.org/ns/context/platform/whatsapp/v1.jsonld\",\n    contextVersion: \"1\",\n    schemaVersion: \"1\",\n    messages: {\n        required: [\"type\", \"actor\", \"target\", \"object\"],\n        properties: {\n            type: { enum: [\"send\"] },\n            actor,\n            target,\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: 4096 },\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,\n            target,\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                },\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 { PlatformWhatsAppSchema } from \"./schema.js\";\n\nexport interface WhatsAppCredentials extends CredentialsObject {\n    object: { type: \"credentials\"; token: string; apiVersion: string };\n}\n\nexport default class WhatsApp 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 PlatformWhatsAppSchema;\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: WhatsAppCredentials,\n        done: PlatformCallback,\n    ): Promise<void> {\n        const { token, apiVersion } = credentials.object;\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                        messaging_product: \"whatsapp\",\n                        recipient_type: \"individual\",\n                        to: job.target.id,\n                        type: \"text\",\n                        text: { body: job.object.content, preview_url: false },\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(\"whatsapp: 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                        \"message\" in error &&\n                        typeof error.message === \"string\"\n                    ) {\n                        detail += `: ${error.message.split(token).join(\"[redacted]\")}`;\n                    }\n                }\n                // 131047: more than 24 hours since the recipient last messaged.\n                const windowClosed =\n                    error &&\n                    typeof error === \"object\" &&\n                    \"code\" in error &&\n                    error.code === 131047;\n                const reason = windowClosed\n                    ? \"meta:messaging-window-closed\"\n                    : \"whatsapp: send rejected\";\n                throw new Error(`${reason} (${detail})`);\n            }\n            const id =\n                \"messages\" in data &&\n                Array.isArray(data.messages) &&\n                data.messages[0] &&\n                typeof data.messages[0] === \"object\" &&\n                \"id\" in data.messages[0]\n                    ? data.messages[0].id\n                    : undefined;\n            if (typeof id !== \"string\" || !id) {\n                throw new Error(\"whatsapp: API response missing message id\");\n            }\n            result = { ...job, object: { ...job.object, id } };\n        } catch (error) {\n            // Network errors may contain request details; never expose tokens.\n            const failure =\n                error instanceof Error &&\n                (error.message.startsWith(\"whatsapp:\") ||\n                    error.message.startsWith(\"meta:messaging-window-closed\"))\n                    ? new Error(error.message.split(token).join(\"[redacted]\"))\n                    : new Error(\n                          \"whatsapp: send failed (network error, timeout, or invalid JSON); delivery is unknown\",\n                      );\n            this.log.warn(`send failed for actor ${job.actor.id} on whatsapp`);\n            done(failure);\n            return;\n        }\n        done(null, result);\n    }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "645C91CA9AEA149964756E2164756E21",
+  "names": []
+}

package/dist/schema.d.ts

@@ -0,0 +1,144 @@
+export declare const PlatformWhatsAppSchema: {
+    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;
+                    };
+                    type: {
+                        const: string;
+                    };
+                };
+            };
+            object: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    content: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                    };
+                };
+            };
+        };
+    };
+    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;
+                    };
+                    type: {
+                        const: string;
+                    };
+                };
+            };
+            object: {
+                type: string;
+                required: string[];
+                properties: {
+                    type: {
+                        const: string;
+                    };
+                    id: {
+                        type: string;
+                        minLength: number;
+                    };
+                    content: {
+                        type: string;
+                    };
+                };
+            };
+        };
+    };
+};

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@sockethub/platform-whatsapp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Outgoing text messages through the WhatsApp Business Cloud 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"
+}