@siftline/actions 0.0.2 → 0.1.1

package/README.md

@@ -1,17 +1,27 @@
 # @siftline/actions
 
-Siftline adapters for the places labels land: issue trackers, inboxes and queues.
+Siftline adapters that carry a Decision to a webhook or to Slack.
 
-This package is a walking skeleton. It exports a placeholder constant built from
-`@siftline/core`'s own placeholder, which is enough to prove the build, type, test, pack
-and publish path and that the dependency on the engine resolves. The adapters land next.
+```sh
+npm install @siftline/actions
+```
 
 ```ts
-import { PLACEHOLDER } from "@siftline/actions";
+import { perform, webhook } from "@siftline/actions";
+
+const request = await webhook.build(decision, { url, secret }, recipe);
+const { status, body, truncated } = await perform(request, fetch);
 ```
 
+`build` is pure and `perform` sends once, so a preview is `build` without `perform`. The
+webhook body is the Decision line, signed with HMAC-SHA256 when a `secret` is set;
+`slackIncomingWebhook` posts one message.
+
+The guide and the full reference live at
+[docs.siftline.dev](https://docs.siftline.dev/docs/packages/actions).
+
 ESM only. Node 22.14 or newer.
 
 ## Licence
 
-MIT — see [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).

package/dist/index.d.mts

@@ -1,9 +1,86 @@
-//#region src/index.d.ts
+import { ZodType } from "zod";
+import { Decision, Recipe, SiftlineError } from "@siftline/core";
+//#region src/adapter.d.ts
+/** Cloud's `action.kind` strings. */
+type ActionKind = "webhook" | "slack_incoming_webhook";
+/** Everything needed to send an Action, and nothing that depends on a clock or randomness. */
+interface ActionRequest {
+  method: "POST";
+  url: string;
+  headers: {
+    [name: string]: string;
+  };
+  body: string;
+  idempotencyKey: string;
+}
+interface Adapter<C> {
+  kind: ActionKind;
+  configSchema: ZodType<C>;
+  build: (decision: Decision, config: C, recipe: Recipe) => Promise<ActionRequest>;
+}
+//#endregion
+//#region src/webhook.d.ts
+interface WebhookConfig {
+  url: string;
+  secret?: string;
+  headers?: {
+    [name: string]: string;
+  };
+}
+/** POSTs the Decision line itself, with no envelope, so a receiver runs `parseDecision`. */
+export declare const webhook: Adapter<WebhookConfig>;
+//#endregion
+//#region src/slack.d.ts
+interface SlackIncomingWebhookConfig {
+  url: string;
+}
 /**
- * Walking-skeleton export. It exists so the build, type, test, pack and publish path
- * can be proven before any adapter is written, and it will be deleted when the first
- * adapter lands. The engine's own placeholder is folded in so the caret dependency on
- * `@siftline/core` is exercised at runtime, not merely declared.
+ * Posts one mrkdwn message, no blocks. Slack itself has no idempotency, so a redelivery
+ * past cloud's guard posts twice.
  */
-export declare const PLACEHOLDER = "siftline-actions-walking-skeleton(siftline-core-walking-skeleton)";
-//#endregion
+export declare const slackIncomingWebhook: Adapter<SlackIncomingWebhookConfig>;
+//#endregion
+//#region src/adapters.d.ts
+/** Every Adapter, keyed by cloud's `action.kind`. */
+export declare const adapters: {
+  webhook: Adapter<WebhookConfig>;
+  slack_incoming_webhook: Adapter<SlackIncomingWebhookConfig>;
+};
+//#endregion
+//#region src/errors.d.ts
+/** A Decision that cannot become a request. Never retryable: nothing about it will change. */
+export declare class ActionBuildError extends SiftlineError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/** A request that was sent and did not land. `status` is null when `fetch` itself threw. */
+export declare class ActionFailedError extends SiftlineError {
+  readonly status: number | null;
+  constructor(message: string, status: number | null, retryable: boolean, options?: ErrorOptions);
+}
+//#endregion
+//#region src/perform.d.ts
+interface ActionResponse {
+  status: number;
+  body: string;
+  truncated: boolean;
+}
+interface ActionFetchInit {
+  method: "POST";
+  headers: {
+    [name: string]: string;
+  };
+  body: string;
+  signal?: AbortSignal;
+}
+/** Narrower than the global `fetch`, which is assignable to it, so a stub needs no cast. */
+type ActionFetch = (url: string, init: ActionFetchInit) => Promise<Response>;
+/** Sends the request once. No retries, no timeout of its own: both belong to the caller. */
+export declare function perform(request: ActionRequest, fetchImpl: ActionFetch, options?: {
+  signal?: AbortSignal;
+}): Promise<ActionResponse>;
+//#endregion
+//#region src/version.d.ts
+/** The published version of `@siftline/actions`, baked in at build time. */
+export declare const VERSION: string;
+//#endregion
+export type { ActionFetch, ActionFetchInit, ActionKind, ActionRequest, ActionResponse, Adapter, SlackIncomingWebhookConfig, WebhookConfig };

package/dist/index.mjs

@@ -1,11 +1,162 @@
-import { PLACEHOLDER as PLACEHOLDER$1 } from "@siftline/core";
-//#region src/index.ts
+import { z } from "zod";
+import { SiftlineError, serializeDecision } from "@siftline/core";
+//#region src/errors.ts
+/** A Decision that cannot become a request. Never retryable: nothing about it will change. */
+var ActionBuildError = class extends SiftlineError {
+	constructor(message, options) {
+		super(message, "action_build", false, options);
+	}
+};
+/** A request that was sent and did not land. `status` is null when `fetch` itself threw. */
+var ActionFailedError = class extends SiftlineError {
+	status;
+	constructor(message, status, retryable, options) {
+		super(message, "action_failed", retryable, options);
+		this.status = status;
+	}
+};
+//#endregion
+//#region src/version.ts
+/** The published version of `@siftline/actions`, baked in at build time. */
+const VERSION = "0.1.1";
+//#endregion
+//#region src/adapter.ts
+/** The key the receiver deduplicates on, and the `Idempotency-Key` header. */
+function idempotencyKeyFor(decision) {
+	if (decision.action === null) throw new ActionBuildError(`Decision ${decision.id} selected no Action`);
+	return `${decision.id}:${decision.action}`;
+}
+/** The three headers every adapter sends. An adapter adds its own on top. */
+function baseHeaders(idempotencyKey) {
+	return {
+		"Content-Type": "application/json",
+		"Idempotency-Key": idempotencyKey,
+		"User-Agent": `siftline-actions/${VERSION}`
+	};
+}
+const encoder = new TextEncoder();
+async function hmacSha256Hex(secret, body) {
+	const key = await crypto.subtle.importKey("raw", encoder.encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
+	return Array.from(new Uint8Array(signature), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+//#region src/slack.ts
+const slackIncomingWebhookConfigSchema = z.object({ url: z.url() }).strict();
+function describeLevel(index, criteria) {
+	const description = criteria[index];
+	if (description === void 0) return String(index);
+	return `${index} · ${description === null || description instanceof Object ? JSON.stringify(description) : description}`;
+}
+function renderAnswer(question, answer) {
+	if (question.type === "noul") return answer ? "yes" : "no";
+	if (question.type === "score") return describeLevel(Number(answer), question.criteria);
+	return String(answer);
+}
+function renderText(decision, recipe) {
+	const lines = [`*${recipe.name}* · ${decision.recordId}`];
+	for (const [name, question] of Object.entries(recipe.questions)) {
+		const answer = decision.answers[name];
+		const evidence = decision.questions[name];
+		if (answer === void 0 || evidence === void 0) continue;
+		const percent = Math.round(evidence.confidence * 100);
+		lines.push(`${name}: ${renderAnswer(question, answer)} (${percent}%)`);
+	}
+	if (decision.rule !== null) lines.push(`rule ${decision.rule}`);
+	return lines.join("\n");
+}
+async function build$1(decision, config, recipe) {
+	const idempotencyKey = idempotencyKeyFor(decision);
+	return {
+		method: "POST",
+		url: config.url,
+		headers: baseHeaders(idempotencyKey),
+		body: JSON.stringify({ text: renderText(decision, recipe) }),
+		idempotencyKey
+	};
+}
 /**
-* Walking-skeleton export. It exists so the build, type, test, pack and publish path
-* can be proven before any adapter is written, and it will be deleted when the first
-* adapter lands. The engine's own placeholder is folded in so the caret dependency on
-* `@siftline/core` is exercised at runtime, not merely declared.
+* Posts one mrkdwn message, no blocks. Slack itself has no idempotency, so a redelivery
+* past cloud's guard posts twice.
 */
-const PLACEHOLDER = `siftline-actions-walking-skeleton(${PLACEHOLDER$1})`;
+const slackIncomingWebhook = {
+	kind: "slack_incoming_webhook",
+	configSchema: slackIncomingWebhookConfigSchema,
+	build: build$1
+};
+//#endregion
+//#region src/webhook.ts
+const webhookConfigSchema = z.object({
+	url: z.url(),
+	secret: z.string().min(1).optional(),
+	headers: z.record(z.string().min(1), z.string()).optional()
+}).strict();
+async function build(decision, config, _recipe) {
+	const idempotencyKey = idempotencyKeyFor(decision);
+	const body = serializeDecision(decision);
+	const headers = baseHeaders(idempotencyKey);
+	for (const [name, value] of Object.entries(config.headers ?? {})) headers[name] = value;
+	if (config.secret !== void 0) headers["X-Siftline-Signature"] = `sha256=${await hmacSha256Hex(config.secret, body)}`;
+	return {
+		method: "POST",
+		url: config.url,
+		headers,
+		body,
+		idempotencyKey
+	};
+}
+/** POSTs the Decision line itself, with no envelope, so a receiver runs `parseDecision`. */
+const webhook = {
+	kind: "webhook",
+	configSchema: webhookConfigSchema,
+	build
+};
+//#endregion
+//#region src/adapters.ts
+/** Every Adapter, keyed by cloud's `action.kind`. */
+const adapters = {
+	webhook,
+	slack_incoming_webhook: slackIncomingWebhook
+};
+//#endregion
+//#region src/perform.ts
+const BODY_LIMIT = 4096;
+const decoder = new TextDecoder();
+function truncate(bytes) {
+	let end = BODY_LIMIT;
+	while (end > 0 && ((bytes[end] ?? 0) & 192) === 128) end -= 1;
+	return decoder.decode(bytes.subarray(0, end));
+}
+function retryableStatus(status) {
+	return status === 408 || status === 429 || status >= 500;
+}
+/** Sends the request once. No retries, no timeout of its own: both belong to the caller. */
+async function perform(request, fetchImpl, options = {}) {
+	let response;
+	try {
+		response = await fetchImpl(request.url, {
+			method: request.method,
+			headers: request.headers,
+			body: request.body,
+			signal: options.signal
+		});
+	} catch (cause) {
+		const reason = cause instanceof Error ? cause.message : String(cause);
+		throw new ActionFailedError(`POST ${request.url} failed: ${reason}`, null, true, { cause });
+	}
+	const bytes = new Uint8Array(await response.arrayBuffer());
+	const truncated = bytes.byteLength > BODY_LIMIT;
+	const body = truncated ? truncate(bytes) : decoder.decode(bytes);
+	const result = {
+		status: response.status,
+		body,
+		truncated
+	};
+	if (!response.ok) throw new ActionFailedError(`POST ${request.url} returned ${response.status}`, response.status, retryableStatus(response.status), { cause: result });
+	return result;
+}
 //#endregion
-export { PLACEHOLDER };
+export { ActionBuildError, ActionFailedError, VERSION, adapters, perform, slackIncomingWebhook, webhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@siftline/actions",
-  "version": "0.0.2",
+  "version": "0.1.1",
   "description": "Siftline adapters for the places labels land: issue trackers, inboxes and queues.",
   "keywords": [
     "actions",
@@ -42,7 +42,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@siftline/core": "^0.0.3"
+    "@siftline/core": "^0.1.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@arethetypeswrong/core": "0.18.5",
@@ -54,5 +55,6 @@
   },
   "engines": {
     "node": ">=22.14"
-  }
+  },
+  "//zod": "Direct, though core already depends on it: `Adapter<C>.configSchema` is a `ZodType<C>`, so zod is in this package's public types and must resolve from here. The spec's \"actions adds none beyond core\" is owed a correction."
 }