@boxxy/notifier-atc 0.0.1 → 0.1.4

package/README.md

@@ -1,7 +1,35 @@
-# @boxxy/notifier-atc
+<div align="center">
+  <h1>@boxxy/notifier-atc</h1>
 
-This version, 0.0.1, is a placeholder. It holds no code. It reserves the name on npm so that the
-boxxy release can publish every real version from CI with provenance.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/notifier-atc"><img src="https://img.shields.io/npm/v/@boxxy/notifier-atc" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
 
-Install a version above 0.0.1. The source lives in [`adapters/notifier-atc`](https://github.com/zgeoff/boxxy/tree/main/adapters/notifier-atc)
-of the [boxxy repo](https://github.com/zgeoff/boxxy).
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+boxxy's `Notifier` port on atc: a hold notice arrives as one atc message in one named session.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/notifier-atc) with Bun:
+
+```bash
+bun add @boxxy/notifier-atc
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `createAtcNotifier({ client, session })` returns a `Notifier`. The message names the item and the
+  reason, and says the owner next runs `boxxy item note` and `boxxy item retry`.
+- The client is one call, `sendMessage`. The app builds it from its atc connection.
+- A send that fails, or that atc refuses, returns the failed outcome and never throws.
+
+## Documentation
+
+[Notices in v1](../../docs/design/boxxy/v1.md#notices) describes when a notice is written and sent.

package/dist/create-atc-notifier.d.ts

@@ -0,0 +1,3 @@
+import type { Notifier } from '@boxxy/model';
+import type { AtcNotifierOptions } from './types.ts';
+export declare function createAtcNotifier(options: AtcNotifierOptions): Notifier;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createAtcNotifier } from './create-atc-notifier.ts';
+export type { AtcMessageClient, AtcNotifierOptions, AtcSendRequest } from './types.ts';

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+export interface AtcSendRequest {
+    readonly session: string;
+    readonly text: string;
+    readonly idempotencyKey: string;
+}
+export interface AtcMessageClient {
+    sendMessage: (request: AtcSendRequest) => Promise<unknown>;
+}
+export interface AtcNotifierOptions {
+    readonly client: AtcMessageClient;
+    readonly session: string;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@boxxy/notifier-atc",
-  "version": "0.0.1",
-  "description": "Placeholder that reserves the name; the first real version comes from the boxxy release",
+  "version": "0.1.4",
+  "description": "boxxy's hold notice sent as an atc message to one named session",
   "homepage": "https://github.com/zgeoff/boxxy/tree/main/adapters/notifier-atc#readme",
   "bugs": "https://github.com/zgeoff/boxxy/issues",
   "license": "MIT",
@@ -11,10 +11,29 @@
     "directory": "adapters/notifier-atc"
   },
   "files": [
-    "README.md",
-    "LICENSE"
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
   ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@boxxy/model": "0.1.4"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
   }
 }

package/src/create-atc-notifier.ts

@@ -0,0 +1,47 @@
+import type { HoldNotice, Notifier } from '@boxxy/model';
+import type { AtcNotifierOptions } from './types.ts';
+
+export function createAtcNotifier(options: AtcNotifierOptions): Notifier {
+  return {
+    async tellHold(notice) {
+      try {
+        await options.client.sendMessage({
+          session: options.session,
+          text: formatHoldMessage(notice),
+          idempotencyKey: buildIdempotencyKey(notice),
+        });
+      } catch (error) {
+        return { kind: 'failed', reason: toFailureReason(error) };
+      }
+
+      return { kind: 'sent' };
+    },
+  };
+}
+
+function formatHoldMessage(notice: HoldNotice): string {
+  return [
+    `boxxy put ${notice.item} on hold: ${notice.reason}.`,
+    `Add a note with \`boxxy item note ${notice.item}\`, then run \`boxxy item retry ${notice.item}\`.`,
+  ].join('\n');
+}
+
+// The port's notice has no id or try count; the item, the reason and the time name the notice,
+// so a later try of the same notice repeats the key.
+function buildIdempotencyKey(notice: HoldNotice): string {
+  return `boxxy-hold:${notice.item}:${notice.reason}:${notice.at}`;
+}
+
+// Only a string `code` is kept: an error message may carry text that must not reach the log.
+function toFailureReason(error: unknown): string {
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    typeof error.code === 'string'
+  ) {
+    return error.code;
+  }
+
+  return 'atc send failed';
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { createAtcNotifier } from './create-atc-notifier.ts';
+export type { AtcMessageClient, AtcNotifierOptions, AtcSendRequest } from './types.ts';

package/src/types.ts

@@ -0,0 +1,17 @@
+export interface AtcSendRequest {
+  // the name or the id of the session that gets the message
+  readonly session: string;
+  readonly text: string;
+  readonly idempotencyKey: string;
+}
+
+// The one call the adapter needs. It resolves when atc takes the message and rejects when atc
+// refuses it or cannot be reached; a rejection may carry a string `code`, such as `no_such_session`.
+export interface AtcMessageClient {
+  sendMessage: (request: AtcSendRequest) => Promise<unknown>;
+}
+
+export interface AtcNotifierOptions {
+  readonly client: AtcMessageClient;
+  readonly session: string;
+}