brrr.now 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 uqe
+
+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

@@ -0,0 +1,93 @@
+# brrr.now
+
+Minimal TypeScript client for the [brrr.now](https://brrr.now/docs/) notification service.
+
+## Installation
+
+```bash
+bun add brrr.now
+```
+
+```bash
+npm install brrr.now
+```
+
+## Usage
+
+```typescript
+import { sendNotification } from "brrr.now";
+
+await sendNotification({
+	webhook: process.env.BRRR_WEBHOOK!,
+	title: "Coffee Machine Offline",
+	message: "The coffee machine is currently unreachable.",
+	sound: "upbeat_bells",
+	openUrl: "https://status.example.com/coffee-machine",
+});
+```
+
+`webhook` can be either:
+
+- the full webhook URL from the brrr.now app
+- only the secret part, for example `br_usr_a1b2c3`
+
+## API
+
+```typescript
+import type {
+	NotificationInterruptionLevel,
+	NotificationSound,
+	SendNotificationParams,
+} from "brrr.now";
+import { isBrrrNowError, sendNotification } from "brrr.now";
+```
+
+`sendNotification(params)` sends a `POST` request with a JSON payload and returns the native `Response`.
+
+### `SendNotificationParams`
+
+- `title`
+- `subtitle`
+- `message`
+- `sound`: `NotificationSound`
+- `openUrl`
+- `imageUrl`
+- `expirationDate`: `string | Date`
+- `filterCriteria`
+- `interruptionLevel`: `NotificationInterruptionLevel`
+
+### Error handling
+
+On non-`2xx` responses, `sendNotification` throws an `Error` object with extra fields:
+
+- `name: "BrrrNowError"`
+- `status`
+- `statusText`
+- `body`
+
+Use `isBrrrNowError` to narrow the error type:
+
+```typescript
+import { isBrrrNowError, sendNotification } from "brrr.now";
+
+try {
+	await sendNotification({
+		webhook: process.env.BRRR_WEBHOOK!,
+		message: "Hello world!",
+	});
+} catch (error) {
+	if (isBrrrNowError(error)) {
+		console.error(error.status, error.body);
+	}
+}
+```
+
+The supported sound values follow the official brrr.now documentation.
+
+## Contributing
+
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+type NotificationSound = "default" | "system" | "brrr" | "bell_ringing" | "bubble_ding" | "bubbly_success_ding" | "cat_meow" | "calm1" | "calm2" | "cha_ching" | "dog_barking" | "door_bell" | "duck_quack" | "short_triple_blink" | "upbeat_bells" | "warm_soft_error";
+type NotificationInterruptionLevel = "passive" | "active" | "time-sensitive";
+interface SendNotificationParams {
+	webhook: string;
+	title?: string;
+	subtitle?: string;
+	message?: string;
+	sound?: NotificationSound;
+	openUrl?: string;
+	imageUrl?: string;
+	expirationDate?: string | Date;
+	filterCriteria?: string;
+	interruptionLevel?: NotificationInterruptionLevel;
+}
+type BrrrNowError = Error & {
+	name: "BrrrNowError";
+	status: number;
+	statusText: string;
+	body: string;
+};
+declare const sendNotification: (params: SendNotificationParams) => Promise<Response>;
+declare const isBrrrNowError: (error: unknown) => error is BrrrNowError;
+export { sendNotification, isBrrrNowError, SendNotificationParams, NotificationSound, NotificationInterruptionLevel, BrrrNowError };

package/dist/index.js

@@ -0,0 +1,60 @@
+// src/index.ts
+var API_BASE_URL = "https://api.brrr.now/v1/";
+var sendNotification = async (params) => {
+  const response = await fetch(resolveWebhookUrl(params.webhook), {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(createPayload(params))
+  });
+  if (!response.ok) {
+    throw createBrrrNowError(response, await response.text());
+  }
+  return response;
+};
+var isBrrrNowError = (error) => {
+  return error instanceof Error && error.name === "BrrrNowError" && typeof error.status === "number" && typeof error.statusText === "string" && typeof error.body === "string";
+};
+var createPayload = (params) => {
+  return {
+    title: params.title,
+    subtitle: params.subtitle,
+    message: params.message,
+    sound: params.sound,
+    open_url: params.openUrl,
+    image_url: params.imageUrl,
+    expiration_date: serializeExpirationDate(params.expirationDate),
+    "filter-criteria": params.filterCriteria,
+    "interruption-level": params.interruptionLevel
+  };
+};
+var createBrrrNowError = (response, body) => {
+  const error = new Error(`brrr.now request failed with ${response.status} ${response.statusText}${body ? `: ${body}` : ""}`);
+  return Object.assign(error, {
+    name: "BrrrNowError",
+    status: response.status,
+    statusText: response.statusText,
+    body
+  });
+};
+var resolveWebhookUrl = (webhook) => {
+  const trimmedWebhook = webhook.trim();
+  if (!trimmedWebhook) {
+    throw new TypeError("webhook must not be empty");
+  }
+  if (trimmedWebhook.startsWith("https://") || trimmedWebhook.startsWith("http://")) {
+    return trimmedWebhook;
+  }
+  return new URL(trimmedWebhook, API_BASE_URL).toString();
+};
+var serializeExpirationDate = (expirationDate) => {
+  if (expirationDate instanceof Date) {
+    return expirationDate.toISOString();
+  }
+  return expirationDate;
+};
+export {
+  sendNotification,
+  isBrrrNowError
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+	"name": "brrr.now",
+	"version": "0.1.0",
+	"description": "Tiny TypeScript client for sending push notifications with brrr.now webhooks",
+	"homepage": "https://github.com/uqe/brrr.now#readme",
+	"bugs": {
+		"url": "https://github.com/uqe/brrr.now/issues"
+	},
+	"license": "MIT",
+	"keywords": [
+		"brrr.now",
+		"brrr",
+		"notification",
+		"push-notification",
+		"push-notifications",
+		"webhook",
+		"typescript"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/uqe/brrr.now.git"
+	},
+	"files": [
+		"dist"
+	],
+	"sideEffects": false,
+	"type": "module",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			}
+		},
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"build": "bunup",
+		"dev": "bunup --watch",
+		"format": "oxfmt",
+		"lint": "oxlint",
+		"prepare": "bun simple-git-hooks",
+		"release": "bumpp --commit --push --tag",
+		"test": "bun test",
+		"test:coverage": "bun test --coverage",
+		"test:watch": "bun test --watch",
+		"type-check": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.11",
+		"bumpp": "^11.0.1",
+		"bunup": "^0.16.31",
+		"oxfmt": "^0.42.0",
+		"oxlint": "^1.57.0",
+		"simple-git-hooks": "^2.13.1",
+		"typescript": "^6.0.2"
+	},
+	"peerDependencies": {
+		"typescript": ">=4.5.0"
+	},
+	"peerDependenciesMeta": {
+		"typescript": {
+			"optional": true
+		}
+	},
+	"simple-git-hooks": {
+		"pre-commit": "bun run lint && bun run type-check"
+	}
+}