@boxxy/notifier-atc 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+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,35 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/notifier-atc</h1>
 
-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.
+  <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>
+
+  <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,6 +1,39 @@
 {
   "name": "@boxxy/notifier-atc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "adapters/notifier-atc"
+  },
+  "files": [
+    "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.3"
+  },
+  "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;
+}