@everruns/channelkit 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mykhailo Chalyi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# Channelkit for Node.js
 
-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.
+Rust-backed Slack and WhatsApp adapters for application-owned agents.
+A library with no server, database, background worker, or install-time downloads.
+
+```sh
+npm install @everruns/channelkit@alpha
+```
+
+```js
+const {Slack} = require('@everruns/channelkit');
+const slack = new Slack({
+  installation: 'support', teamId: process.env.SLACK_TEAM_ID,
+  token: process.env.SLACK_BOT_TOKEN, signingSecret: process.env.SLACK_SIGNING_SECRET,
+});
+async function main() {
+  const receipt = await slack.post(slack.conversation(process.env.SLACK_TEST_CHANNEL),
+                                   'Hello from Rust-backed Node!');
+  console.log(receipt.status); // accepted, not delivery confirmation
+}
+main().catch(console.error);
+```
+
+## Signed webhooks and replies
+
+```js
+// Your host supplies the ORIGINAL body Buffer, never JSON reserialization.
+const ingress = slack.receive(rawBody, headers);
+for (const event of ingress.events) {
+  const message = event.kind.Message;
+  if (message?.mentioned) await slack.reply(message, 'I received your message');
+}
+// Your host returns ingress.response.status, content_type, body.
+// Persist/deduplicate accepted events before acknowledging when durability is needed.
+```
+
+`receive` synchronously verifies signatures and normalizes the Rust event model.
+It never sends an HTTP response or starts agent work. Outbound methods return
+Promises and run on Rust's async runtime without blocking Node's event loop.
+The host owns HTTP acceptance, event storage, authorization, agents, and recovery.
+TypeScript declarations are included; ESM supports named imports too.
+
+`new WhatsApp({installation, phoneNumberId, token, appSecret, verifyToken})`
+verifies Meta signatures and GET challenges:
+`receive(Buffer.alloc(0), {}, {method: 'GET', query})`.
+`reply(message, text)` uses the verified message timestamp for WhatsApp's reply
+window. `post` leaves window enforcement to Meta and maps a window rejection to
+`ReplyWindowClosed`. For outbound conversations, use
+`sendTemplate(target, 'approved_template', 'en_US')` for an approved template
+and an opted-in recipient. The library never creates templates or recipients.
+
+## API and errors
+
+Adapters expose `conversation`, `receive`, `post`, `reply`, `react`, `edit`,
+`delete`, `history`, and `typing`; WhatsApp adds `sendTemplate`.
+Unsupported provider operations fail explicitly. Rust-validated helpers:
+`text`, `markdown`, `card(title, body, [{id: 'approve', label: 'Approve'}])`,
+`conversation`, and Unicode-aware `splitText`.
+
+`ChannelkitError` exposes `code`, `details`, `retryAfterMs`, and `confirmed`.
+Never blindly repeat `DeliveryUnknown`. `PartialDelivery` preserves confirmed
+message references and `details.source`. No automatic retries occur. A cancelled task or host timeout is also not proof
+that a send was rejected; retain pending work and reconcile before recovery. Errors
+redact raw provider bodies and credentials; keep tokens in your secret manager.
+
+`providerCapabilities` describes the underlying Rust adapter. This initial
+binding does not expose coordinator/durability hooks, streaming, media,
+Slack-specific extensions, or other providers. Those remain Rust APIs.
+
+Node 20+: macOS 11+ arm64/x64, Windows x64, Linux x64 glibc 2.35+.
+Native N-API binaries are bundled. Unsupported platforms fail explicitly;
+there is no network installer, WASM fallback, or musl support claim.
+
+## Sources of inspiration
+
+[Chat SDK](https://chat-sdk.dev/), [BerriAI agentchat](https://github.com/BerriAI/agentchat),
+[Bashkit](https://github.com/everruns/bashkit), and [Everruns](https://github.com/everruns/everruns).
+Native bindings use [napi-rs](https://napi.rs/).
+
+[Project](https://github.com/everruns/channelkit) · [MIT license](LICENSE)