@opentag/slack 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# @opentag/slack
+
+Slack adapter helpers for OpenTag.
+
+Use this package to normalize Slack `app_mention` events into `OpenTagEvent` objects and to encode or parse Slack callback thread keys.
+
+## Install
+
+```bash
+pnpm add @opentag/slack
+```
+
+## Exports
+
+- `normalizeSlackAppMention`: converts a Slack app mention into an `OpenTagEvent`.
+- `slackThreadKey`: encodes team, channel, and thread timestamp for callback routing.
+- `parseSlackThreadKey`: decodes a Slack thread key for `chat.postMessage`.
+- `SlackChannelBinding`: channel-to-repository binding contract.
+
+## Example
+
+```ts
+import { normalizeSlackAppMention } from "@opentag/slack";
+
+const event = normalizeSlackAppMention({
+  teamId: "T123",
+  channelId: "C123",
+  userId: "U456",
+  text: "<@U_APP> investigate this deploy failure",
+  ts: "1710000000.000100",
+  eventId: "Ev123",
+  eventTime: 1710000000,
+  botUserId: "U_APP",
+  binding: {
+    teamId: "T123",
+    channelId: "C123",
+    owner: "acme",
+    repo: "demo"
+  }
+});
+
+if (event) {
+  // Send event to @opentag/client or your own OpenTag-compatible control plane.
+}
+```
+
+## Stability
+
+Thread key format is public because callback sinks depend on it. Change it only with a migration path.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./normalize.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,113 @@
+// src/normalize.ts
+import { commandFromRawText } from "@opentag/core";
+function stripSlackAppMention(text, botUserId) {
+  const patterns = botUserId ? [new RegExp(`^<@${botUserId}>\\s*`, "i"), /^<@[^>]+>\s*/] : [/^<@[^>]+>\s*/];
+  for (const pattern of patterns) {
+    const stripped = text.replace(pattern, "").trim();
+    if (stripped !== text.trim()) {
+      return stripped.length > 0 ? stripped : null;
+    }
+  }
+  return null;
+}
+function encodeSlackThreadKey(input) {
+  return `${input.teamId}|${input.channelId}|${input.threadTs}`;
+}
+function parseSlackThreadKey(threadKey) {
+  const [teamId, channelId, threadTs] = threadKey.split("|");
+  if (!teamId || !channelId || !threadTs) {
+    throw new Error(`Invalid Slack thread key: ${threadKey}`);
+  }
+  return { teamId, channelId, threadTs };
+}
+function permissionsForIntent(intent) {
+  const permissions = [
+    {
+      scope: "chat:postMessage",
+      reason: "reply in the originating Slack thread"
+    },
+    {
+      scope: "runner:local",
+      reason: "execute the run on a paired local daemon"
+    }
+  ];
+  if (intent === "fix" || intent === "run") {
+    permissions.push(
+      {
+        scope: "repo:read",
+        reason: "inspect the repository in the paired local checkout"
+      },
+      {
+        scope: "repo:write",
+        reason: "commit code changes on an isolated run branch"
+      },
+      {
+        scope: "pr:create",
+        reason: "open a pull request for completed code changes"
+      }
+    );
+  }
+  return permissions;
+}
+function normalizeSlackAppMention(input) {
+  const rawText = stripSlackAppMention(input.text, input.botUserId);
+  if (!rawText) return null;
+  const command = commandFromRawText(rawText);
+  const replyThreadTs = input.threadTs ?? input.ts;
+  return {
+    id: `evt_slack_app_mention_${input.eventId}`,
+    source: "slack",
+    sourceEventId: input.eventId,
+    receivedAt: new Date(input.eventTime * 1e3).toISOString(),
+    actor: {
+      provider: "slack",
+      providerUserId: input.userId,
+      handle: input.userId,
+      organizationId: input.teamId
+    },
+    target: {
+      mention: input.botUserId ? `<@${input.botUserId}>` : "<@app>",
+      agentId: "opentag"
+    },
+    command,
+    context: [
+      {
+        kind: "url",
+        uri: `slack://team/${input.teamId}/channel/${input.channelId}/message/${input.ts}`,
+        visibility: "organization",
+        title: "Slack message"
+      },
+      {
+        kind: "text",
+        uri: input.text,
+        visibility: "organization",
+        title: "Slack message text"
+      }
+    ],
+    permissions: permissionsForIntent(command.intent),
+    callback: {
+      provider: "slack",
+      uri: input.callbackUri ?? "https://slack.com/api/chat.postMessage",
+      threadKey: encodeSlackThreadKey({
+        teamId: input.teamId,
+        channelId: input.channelId,
+        threadTs: replyThreadTs
+      })
+    },
+    metadata: {
+      teamId: input.teamId,
+      channelId: input.channelId,
+      messageTs: input.ts,
+      repoProvider: "github",
+      owner: input.binding.owner,
+      repo: input.binding.repo
+    }
+  };
+}
+export {
+  encodeSlackThreadKey,
+  normalizeSlackAppMention,
+  parseSlackThreadKey,
+  stripSlackAppMention
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/normalize.ts"],"sourcesContent":["import { commandFromRawText, type OpenTagEvent, type PermissionGrant } from \"@opentag/core\";\n\nexport type SlackChannelBinding = {\n  teamId: string;\n  channelId: string;\n  owner: string;\n  repo: string;\n};\n\nexport type SlackAppMentionInput = {\n  teamId: string;\n  channelId: string;\n  userId: string;\n  text: string;\n  ts: string;\n  threadTs?: string;\n  eventId: string;\n  eventTime: number;\n  botUserId?: string;\n  callbackUri?: string;\n  binding: SlackChannelBinding;\n};\n\nexport function stripSlackAppMention(text: string, botUserId?: string): string | null {\n  const patterns = botUserId\n    ? [new RegExp(`^<@${botUserId}>\\\\s*`, \"i\"), /^<@[^>]+>\\s*/]\n    : [/^<@[^>]+>\\s*/];\n\n  for (const pattern of patterns) {\n    const stripped = text.replace(pattern, \"\").trim();\n    if (stripped !== text.trim()) {\n      return stripped.length > 0 ? stripped : null;\n    }\n  }\n\n  return null;\n}\n\nexport function encodeSlackThreadKey(input: { teamId: string; channelId: string; threadTs: string }): string {\n  return `${input.teamId}|${input.channelId}|${input.threadTs}`;\n}\n\nexport function parseSlackThreadKey(threadKey: string): { teamId: string; channelId: string; threadTs: string } {\n  const [teamId, channelId, threadTs] = threadKey.split(\"|\");\n  if (!teamId || !channelId || !threadTs) {\n    throw new Error(`Invalid Slack thread key: ${threadKey}`);\n  }\n  return { teamId, channelId, threadTs };\n}\n\nfunction permissionsForIntent(intent: ReturnType<typeof commandFromRawText>[\"intent\"]): PermissionGrant[] {\n  const permissions: PermissionGrant[] = [\n    {\n      scope: \"chat:postMessage\",\n      reason: \"reply in the originating Slack thread\"\n    },\n    {\n      scope: \"runner:local\",\n      reason: \"execute the run on a paired local daemon\"\n    }\n  ];\n\n  if (intent === \"fix\" || intent === \"run\") {\n    permissions.push(\n      {\n        scope: \"repo:read\",\n        reason: \"inspect the repository in the paired local checkout\"\n      },\n      {\n        scope: \"repo:write\",\n        reason: \"commit code changes on an isolated run branch\"\n      },\n      {\n        scope: \"pr:create\",\n        reason: \"open a pull request for completed code changes\"\n      }\n    );\n  }\n\n  return permissions;\n}\n\nexport function normalizeSlackAppMention(input: SlackAppMentionInput): OpenTagEvent | null {\n  const rawText = stripSlackAppMention(input.text, input.botUserId);\n  if (!rawText) return null;\n\n  const command = commandFromRawText(rawText);\n  const replyThreadTs = input.threadTs ?? input.ts;\n\n  return {\n    id: `evt_slack_app_mention_${input.eventId}`,\n    source: \"slack\",\n    sourceEventId: input.eventId,\n    receivedAt: new Date(input.eventTime * 1000).toISOString(),\n    actor: {\n      provider: \"slack\",\n      providerUserId: input.userId,\n      handle: input.userId,\n      organizationId: input.teamId\n    },\n    target: {\n      mention: input.botUserId ? `<@${input.botUserId}>` : \"<@app>\",\n      agentId: \"opentag\"\n    },\n    command,\n    context: [\n      {\n        kind: \"url\",\n        uri: `slack://team/${input.teamId}/channel/${input.channelId}/message/${input.ts}`,\n        visibility: \"organization\",\n        title: \"Slack message\"\n      },\n      {\n        kind: \"text\",\n        uri: input.text,\n        visibility: \"organization\",\n        title: \"Slack message text\"\n      }\n    ],\n    permissions: permissionsForIntent(command.intent),\n    callback: {\n      provider: \"slack\",\n      uri: input.callbackUri ?? \"https://slack.com/api/chat.postMessage\",\n      threadKey: encodeSlackThreadKey({\n        teamId: input.teamId,\n        channelId: input.channelId,\n        threadTs: replyThreadTs\n      })\n    },\n    metadata: {\n      teamId: input.teamId,\n      channelId: input.channelId,\n      messageTs: input.ts,\n      repoProvider: \"github\",\n      owner: input.binding.owner,\n      repo: input.binding.repo\n    }\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/normalize.d.ts

@@ -0,0 +1,33 @@
+import { type OpenTagEvent } from "@opentag/core";
+export type SlackChannelBinding = {
+    teamId: string;
+    channelId: string;
+    owner: string;
+    repo: string;
+};
+export type SlackAppMentionInput = {
+    teamId: string;
+    channelId: string;
+    userId: string;
+    text: string;
+    ts: string;
+    threadTs?: string;
+    eventId: string;
+    eventTime: number;
+    botUserId?: string;
+    callbackUri?: string;
+    binding: SlackChannelBinding;
+};
+export declare function stripSlackAppMention(text: string, botUserId?: string): string | null;
+export declare function encodeSlackThreadKey(input: {
+    teamId: string;
+    channelId: string;
+    threadTs: string;
+}): string;
+export declare function parseSlackThreadKey(threadKey: string): {
+    teamId: string;
+    channelId: string;
+    threadTs: string;
+};
+export declare function normalizeSlackAppMention(input: SlackAppMentionInput): OpenTagEvent | null;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,YAAY,EAAwB,MAAM,eAAe,CAAC;AAE5F,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAapF;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE3G;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAM9G;AAkCD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,oBAAoB,GAAG,YAAY,GAAG,IAAI,CAwDzF"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@opentag/slack",
+  "version": "0.1.0",
+  "description": "Slack app mention normalization and callback helpers for OpenTag.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "opentag",
+    "slack",
+    "events",
+    "agents",
+    "webhooks"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@opentag/core": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup && tsc -b tsconfig.json --emitDeclarationOnly --force",
+    "lint": "tsc --noEmit"
+  }
+}