@openclaw/crabline 0.1.8 → 0.1.10

package/README.md

@@ -86,10 +86,18 @@ Provider ids are local profile names. Fixtures reference them through
 `provider`. Built-in adapters infer their platform from `adapter`; `platform` is
 required only for `adapter: script`.
 
-Built-in provider credentials are optional metadata only. `doctor` checks
-explicit `env` declarations, script command availability, and config shape; it
-does not require live Slack, Discord, Telegram, WhatsApp, Matrix, iMessage, or
-other platform secrets for local mocks.
+Most built-in provider credentials are optional mock metadata. The WhatsApp
+webhook requires `appSecret` and `verifyToken` because every verification or
+delivery request is authenticated. `doctor` checks explicit `env` declarations,
+script command availability, and config shape without requiring live platform
+credentials.
+
+When configured, Discord `publicKey`, Feishu `encryptKey`, Google Chat endpoint
+or Pub/Sub identity settings, Microsoft Teams `appId`, Slack `signingSecret`,
+Telegram `secretToken`, and Zalo `webhookSecret` enforce provider-native
+webhook authentication. Feishu `verificationToken` remains an additional or
+loopback-only callback check. Microsoft Teams also requires `appId` for
+non-loopback or explicitly public webhook endpoints.
 
 ## Built-In Mock Channels
 
@@ -116,8 +124,13 @@ The built-in providers are:
 - `whatsapp`
 - `zalo`
 
-The `script` adapter can bridge any other OpenClaw channel by running local
-commands for `probe`, `send`, `waitForInbound`, or `watch`.
+The `script` adapter can bridge any OpenClaw channel represented by the
+configured `platform` enum by running local commands for `probe`, `send`,
+`waitForInbound`, or `watch`.
+
+Treat manifests that configure `adapter: script` as executable, trusted code:
+Crabline runs their declared commands with the configured environment. Load
+them only from sources you trust and review changes before use.
 
 ## Local Provider Servers
 
@@ -125,6 +138,11 @@ commands for `probe`, `send`, `waitForInbound`, or `watch`.
 preferred Smoke CI path because OpenClaw still uses its normal channel adapter,
 but the provider endpoint is local and deterministic.
 
+Library callers can pass `onEvent` to `startCrablineServer`, an individual
+provider server, or `startOpenClawCrablineAdapter`. Crabline awaits the callback
+after appending each API/admin event to `recorderPath`, so callers can react in
+process while retaining the JSONL artifact as durable evidence.
+
 Mattermost:
 
 ```bash
@@ -238,7 +256,7 @@ provided. The inbound endpoint rejects requests without the matching admin
 header (or `Authorization: Bearer <token>`).
 
 Implemented Telegram Bot API endpoints include `getMe`, `sendMessage`,
-`sendPhoto`, `sendDocument`, `sendVideo`, `sendAnimation`, `editMessageText`,
+`sendPhoto`, `sendDocument`, `sendVideo`, `sendAudio`, `sendAnimation`, `editMessageText`,
 `deleteMessage`, `setMessageReaction`, `createForumTopic`, `editForumTopic`,
 `pinChatMessage`, `unpinChatMessage`, `getUpdates`, `deleteWebhook`,
 `setWebhook`, `setMyCommands`, `deleteMyCommands`, `sendChatAction`, and
@@ -252,31 +270,36 @@ crabline --json serve whatsapp --ready-file .crabline/whatsapp-server.json
 
 The JSON manifest contains:
 
-- `endpoints.apiRoot`: Crabline WhatsApp local provider API root
+- `endpoints.apiRoot`: versioned WhatsApp Graph API root
+- `endpoints.phoneNumberUrl`: provider-native phone-number resource
 - `endpoints.baileysWebSocketUrl`: Baileys-compatible WebSocket URL for
   `waWebSocketUrl`, including the local provider access token query parameter
 - `accessToken`: bearer token for local provider requests
 - `adminToken`: send this as the `X-Crabline-Admin-Token` header when posting
   test user messages
-- `selfJid`: local authenticated WhatsApp user JID
-- `env.CRABLINE_WHATSAPP_ACCESS_TOKEN`: same value as `accessToken`
-- `env.CRABLINE_WHATSAPP_API_ROOT`: same value as `endpoints.apiRoot`
-- `env.CRABLINE_WHATSAPP_BAILEYS_WEB_SOCKET_URL`: same value as
-  `endpoints.baileysWebSocketUrl`
-- `env.CRABLINE_WHATSAPP_RECORDER_PATH`: recorder file for HTTP traffic and
-  Baileys WebSocket stanzas
-- `env.CRABLINE_WHATSAPP_SELF_JID`: local authenticated WhatsApp user JID
+- `selfJid`: canonical local authenticated WhatsApp user JID; legacy `@c.us`
+  input is normalized to `@s.whatsapp.net`
+- `env.CLOUD_API_ACCESS_TOKEN`: same value as `accessToken`
+- `env.CLOUD_API_VERSION`: Graph API version used by the local server
+- `env.WA_BASE_URL`: local Graph API origin
+- `env.WA_PHONE_NUMBER_ID`: local sender phone-number resource ID
 - `endpoints.adminInboundUrl`: authenticated POST endpoint for test user
   messages using the WhatsApp Business webhook payload shape
-- `endpoints.messagesUrl`: local text send endpoint for Graph-style callers
-- `endpoints.presenceUrl`: local presence endpoint for Graph-style callers
+- `endpoints.messagesUrl`: provider-native Cloud API message and status endpoint
+- `endpoints.statusUrl`: alias for the same provider-native status endpoint
 - `recorderPath`: JSONL file of local provider API/admin traffic and Baileys
   WebSocket stanzas
 
 Pass `endpoints.baileysWebSocketUrl` to Baileys as `waWebSocketUrl` when a
-runtime needs to connect through the local provider. The local server completes
+runtime needs to connect through the local provider. Cloud API-compatible
+clients can send text messages through
+`POST /v25.0/<phone-number-id>/messages` with a bearer token. The local server completes
 the Baileys Noise handshake, serves bootstrap/device/prekey queries, and records
-encrypted outbound WebSocket stanzas. The WebSocket endpoint rejects clients
+encrypted outbound WebSocket stanzas. Direct `msg` and `pkmsg` text sends are
+also recorded as normalized accepted-send evidence for the OpenClaw bridge.
+Group outbound uses sender-key `skmsg` encryption and is outside this supported
+subset, so OpenClaw Crabline outbound targets are direct users only. Group
+inbound injection remains supported. The WebSocket endpoint rejects clients
 that do not present the access token embedded in the manifest URL. The admin
 token is generated randomly unless `--admin-token <token>` is provided.
 
@@ -306,7 +329,8 @@ single-update long polling through `getUpdates`, `sendMessage`, `sendPhoto`,
 `sendChatAction`, and webhook registration, inspection, and deletion. These Bot
 API methods accept GET query parameters or POST requests. Admin
 ingress injects a native Zalo update into the active polling or webhook
-transport. OpenClaw-specific endpoint, config, and target mapping remain in the
+transport. Webhook delivery posts the native `{ event_name, message }` update
+directly. OpenClaw-specific endpoint, config, and target mapping remain in the
 isolated bridge.
 
 The admin ingress accepts JSON like:
@@ -335,6 +359,7 @@ Thread targets use the platform's native thread identifier:
 
 ```yaml
 target:
+  id: "C1234567890"
   channelId: "C1234567890"
   threadId: "1700000000.000100"
 ```
@@ -345,7 +370,7 @@ Examples:
 - Slack threads: `1700000000.000100`
 - Telegram chats: `-1001234567890` or `@channelusername`
 - Telegram topics: `42`
-- WhatsApp users: `15551234567@s.whatsapp.net`
+- WhatsApp Cloud API users: digits-only `wa_id` values such as `15551234567`
 - WhatsApp groups: `120363001234567890@g.us`
 - Discord channels and threads: Discord snowflake ids such as
   `123456789012345678`
@@ -393,6 +418,11 @@ and `agent` modes, the local mock also records a deterministic assistant reply:
 live service latency, external credentials, webhooks exposed to the internet, or
 provider SDK state.
 
+Recorder files remain JSONL. Individual events use one object per line; an
+accepted multi-message webhook is committed as one versioned batch object so
+readers never observe a partial batch. Crabline's recorder APIs flatten those
+batch objects back into their individual events.
+
 ## More Setup Detail
 
 See [Channel Setup](docs/channel-setup.md) for the provider matrix, webhook

package/assets/crabline-banner.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 420" role="img" aria-labelledby="title desc">
+  <title id="title">Crabline deterministic channel QA</title>
+  <desc id="desc">A coral crab crossing a cyan test waveform over a dark navy background.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" x2="1" y1="0" y2="1"><stop stop-color="#07192c"/><stop offset="1" stop-color="#102f43"/></linearGradient>
+    <linearGradient id="wave" x1="0" x2="1"><stop stop-color="#00e5cc"/><stop offset="1" stop-color="#ffb347"/></linearGradient>
+  </defs>
+  <rect width="1200" height="420" rx="28" fill="url(#bg)"/>
+  <path d="M40 300h140l35-100 45 155 48-120 44 65h160l38-88 46 118 46-75 38 45h300" fill="none" stroke="url(#wave)" stroke-linecap="round" stroke-linejoin="round" stroke-width="10" opacity=".85"/>
+  <g transform="translate(120 88)" fill="none" stroke="#ff6f4d" stroke-linecap="round" stroke-linejoin="round" stroke-width="12">
+    <path d="M85 102c-42-32-71-36-102-16m102 30c-46 0-76 15-104 48m230-62c42-32 71-36 102-16m-102 30c46 0 76 15 104 48"/>
+    <path d="M78 150c-32 30-44 61-35 92m192-92c32 30 44 61 35 92"/>
+    <ellipse cx="160" cy="122" rx="88" ry="68" fill="#ff6f4d"/>
+    <circle cx="126" cy="95" r="9" fill="#07192c" stroke="none"/><circle cx="194" cy="95" r="9" fill="#07192c" stroke="none"/>
+    <path d="M131 134c18 15 40 15 58 0"/>
+  </g>
+  <text x="470" y="145" fill="#fff" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="64" font-weight="700">crabline</text>
+  <text x="474" y="205" fill="#9ddbd5" font-family="ui-sans-serif, system-ui, sans-serif" font-size="26">deterministic messaging-channel QA</text>
+  <text x="474" y="255" fill="#ffcf86" font-family="ui-sans-serif, system-ui, sans-serif" font-size="22">local mocks · provider APIs · reproducible evidence</text>
+</svg>

package/dist/src/bin/crabline.js.map

@@ -1 +1 @@
-{"version":3,"file":"crabline.js","sourceRoot":"","sources":["../../../src/bin/crabline.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC5C,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"crabline.js","sourceRoot":"","sources":["../../../src/bin/crabline.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AAC5C,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;AAC9B,CAAC","sourcesContent":["#!/usr/bin/env node\n\nimport { runCli } from \"../cli/program.js\";\n\nconst exitCode = await runCli(process.argv);\nif (exitCode !== 0) {\n  process.exitCode = exitCode;\n}\n"]}

package/dist/src/cli/program.d.ts

@@ -1,5 +1,29 @@
 import { Command } from "commander";
+import { createRegistry } from "../providers/registry.js";
+import { type StartCrablineServerParams, type StartedCrablineServer } from "../servers/index.js";
 type SetExitCode = (code: number) => void;
-export declare function createProgram(setExitCode?: SetExitCode): Command;
+export type ReadyFileIdentity = {
+    birthtimeNs: bigint;
+    ctimeNs: bigint;
+    dev: bigint;
+    ino: bigint;
+    size: bigint;
+};
+type ProgramDependencies = {
+    acquireReadyFileLease?: (filePath: string) => Promise<() => Promise<void>>;
+    createRegistry?: typeof createRegistry;
+    publishReadyFile?: (filePath: string, contents: string) => Promise<ReadyFileIdentity>;
+    removeReadyFile?: (filePath: string, expectedContents: string, expectedIdentity: ReadyFileIdentity) => Promise<void>;
+    startServer?: (params: StartCrablineServerParams) => Promise<StartedCrablineServer>;
+};
+export declare function createProgram(setExitCode?: SetExitCode, dependencies?: ProgramDependencies): Command;
+type ShutdownSignal = "SIGINT" | "SIGTERM";
+type SignalTarget = {
+    on(event: ShutdownSignal, listener: () => void): unknown;
+    removeListener(event: ShutdownSignal, listener: () => void): unknown;
+};
+export declare function publishReadyFile(filePath: string, contents: string): Promise<ReadyFileIdentity>;
+export declare function removeReadyFile(filePath: string, expectedContents: string, expectedIdentity: ReadyFileIdentity): Promise<void>;
+export declare function waitForShutdown(close: () => Promise<void>, signalTarget?: SignalTarget): Promise<void>;
 export declare function runCli(argv: string[]): Promise<number>;
 export {};