@signo/sdk 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @signo/sdk
+
+Send [Signo](https://signo.digitospace.com) notifications from your Node backend.
+
+## Install
+
+```sh
+npm i @signo/sdk
+```
+
+## Usage
+
+```ts
+import { Signo } from '@signo/sdk';
+
+const signo = new Signo();
+
+await signo.send('a7bx9k', {
+  title: 'New sale 🎉',
+  body: 'Order #1043 · $89.00',
+});
+```
+
+Or the zero-config default client:
+
+```ts
+import signo from '@signo/sdk';
+
+await signo.notify('a7bx9k', { title: 'Deploy finished', body: 'prod · a1b2c3' });
+```
+
+Sending is public - a topic's namespace is its address, so no API key is needed. Pass the namespace with or without the `signo.` prefix.
+
+## Rich notifications
+
+```ts
+await signo.send('a7bx9k', {
+  title: 'New sale 🎉',
+  body: 'Order #1043 · $89.00',
+  subtitle: 'Acme Store',
+  image: 'https://cdn.acme.com/p/1043.jpg',
+  badge: 1,
+  interruptionLevel: 'time-sensitive',
+  payload: { orderId: '1043', total: 89.0 },
+});
+```
+
+Every field is optional except `title`:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `title` | `string` | Required |
+| `body` | `string` | |
+| `subtitle` | `string` | iOS secondary line |
+| `image` | `string` | Android inline; iOS needs a Notification Service Extension |
+| `badge` | `number` | iOS app-icon count |
+| `sound` | `'default' \| null` | `null` = silent |
+| `priority` | `'default' \| 'normal' \| 'high'` | Defaults to `high` |
+| `interruptionLevel` | `'active' \| 'critical' \| 'passive' \| 'time-sensitive'` | iOS |
+| `ttl` / `expiration` | `number` | Drop stale pushes |
+| `categoryId` | `string` | Interactive actions |
+| `mutableContent` | `boolean` | |
+| `payload` | `object` | Arbitrary JSON delivered to the app |
+
+## Result & errors
+
+```ts
+const { eventId, delivered } = await signo.send('a7bx9k', { title: 'Hi' });
+```
+
+A failed request throws a `SignoError` with a `.status`:
+
+```ts
+import { Signo, SignoError } from '@signo/sdk';
+
+try {
+  await signo.send('nope', { title: 'Hi' });
+} catch (err) {
+  if (err instanceof SignoError) console.error(err.status, err.message);
+}
+```
+
+## Options
+
+```ts
+new Signo({
+  apiUrl: 'https://signo.digitospace.com', // override the API base URL
+  fetch: myFetch,                          // custom fetch (defaults to global fetch)
+});
+```
+
+Requires Node 18+ (global `fetch`).

package/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Signo server SDK - send notifications to your Signo topics from any Node backend.
+ *
+ * ```ts
+ * import { Signo } from '@signo/sdk';
+ * const signo = new Signo();
+ * await signo.send('a7bx9k', { title: 'New sale 🎉', body: 'Order #1043 · $89.00' });
+ * ```
+ */
+export type Priority = 'default' | 'normal' | 'high';
+export type InterruptionLevel = 'active' | 'critical' | 'passive' | 'time-sensitive';
+/** A notification to deliver. Mirrors the fields the Signo events API accepts. */
+export interface NotifyOptions {
+    /** Title line (required). */
+    title: string;
+    /** Body text under the title. */
+    body?: string;
+    /** iOS secondary line, shown under the title. */
+    subtitle?: string;
+    /** Image URL. Android renders it inline; iOS needs a Notification Service Extension. */
+    image?: string;
+    /** App-icon badge count (iOS). Use 0 to clear it. */
+    badge?: number;
+    /** 'default' plays the device sound; null delivers silently. Defaults to 'default'. */
+    sound?: 'default' | null;
+    /** Delivery priority. Defaults to 'high' server-side. */
+    priority?: Priority;
+    /** iOS interruption level; 'time-sensitive' can break through Focus / DND. */
+    interruptionLevel?: InterruptionLevel;
+    /** Seconds the push may be retried for before it's dropped. */
+    ttl?: number;
+    /** Unix timestamp (seconds) after which the push expires. `ttl` takes precedence. */
+    expiration?: number;
+    /** Interactive category id (must be registered in the app for actions to appear). */
+    categoryId?: string;
+    /** Let the app modify the notification before display (required for iOS rich media). */
+    mutableContent?: boolean;
+    /** Arbitrary JSON delivered to the app alongside the notification. */
+    payload?: Record<string, unknown>;
+}
+/** Result of a successful send. */
+export interface SendResult {
+    /** The stored event's id. */
+    eventId: string;
+    /** How many devices the push was accepted for. */
+    delivered: number;
+}
+export interface SignoOptions {
+    /** API base URL. Defaults to the hosted Signo service. */
+    apiUrl?: string;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+/** Thrown when the Signo API rejects a request. */
+export declare class SignoError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** A Signo client. Sending is public - a topic's namespace is its address. */
+export declare class Signo {
+    #private;
+    constructor(options?: SignoOptions);
+    /** Send a notification to a topic, identified by its namespace. */
+    send(namespace: string, message: NotifyOptions): Promise<SendResult>;
+    /** Alias for {@link Signo.send}. */
+    notify(namespace: string, message: NotifyOptions): Promise<SendResult>;
+}
+/** Zero-config client for the hosted Signo service. */
+export declare const signo: Signo;
+export default signo;

package/dist/index.js

@@ -0,0 +1,67 @@
+/**
+ * Signo server SDK - send notifications to your Signo topics from any Node backend.
+ *
+ * ```ts
+ * import { Signo } from '@signo/sdk';
+ * const signo = new Signo();
+ * await signo.send('a7bx9k', { title: 'New sale 🎉', body: 'Order #1043 · $89.00' });
+ * ```
+ */
+const DEFAULT_API_URL = 'https://signo.digitospace.com';
+/** Thrown when the Signo API rejects a request. */
+export class SignoError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'SignoError';
+        this.status = status;
+    }
+}
+/** Accept a namespace with or without its `signo.` prefix. */
+function address(namespace) {
+    return /^signo\./i.test(namespace) ? namespace : `signo.${namespace}`;
+}
+/** A Signo client. Sending is public - a topic's namespace is its address. */
+export class Signo {
+    #apiUrl;
+    #fetch;
+    constructor(options = {}) {
+        this.#apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/+$/, '');
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!fetchImpl) {
+            throw new Error('No global fetch found - use Node >=18 or pass options.fetch.');
+        }
+        this.#fetch = fetchImpl;
+    }
+    /** Send a notification to a topic, identified by its namespace. */
+    async send(namespace, message) {
+        if (!namespace)
+            throw new Error('A topic namespace is required.');
+        if (!message?.title)
+            throw new Error('A notification title is required.');
+        const res = await this.#fetch(`${this.#apiUrl}/api/events`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ namespace: address(namespace), ...message }),
+        });
+        let data = null;
+        try {
+            data = await res.json();
+        }
+        catch {
+            // Non-JSON body (e.g. a gateway error page); fall through to the status check.
+        }
+        if (res.status !== 202) {
+            const error = data?.error;
+            throw new SignoError(error ?? `Signo request failed (HTTP ${res.status}).`, res.status);
+        }
+        return data;
+    }
+    /** Alias for {@link Signo.send}. */
+    notify(namespace, message) {
+        return this.send(namespace, message);
+    }
+}
+/** Zero-config client for the hosted Signo service. */
+export const signo = new Signo();
+export default signo;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@signo/sdk",
+  "version": "0.1.0",
+  "description": "Send Signo notifications from your Node backend.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "signo",
+    "notifications",
+    "push"
+  ],
+  "license": "MIT",
+  "homepage": "https://signo.digitospace.com",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}