@raidiant/notifai 0.1.0

package/dist/send.d.ts

@@ -0,0 +1,86 @@
+import { type LifecycleT, type NotificationDraftT, type Platform, type SubmissionReceipt } from '@raidiant/notifai-protocol';
+import type { CliConfig } from './config.js';
+export interface SendFlags {
+    title: string;
+    body: string;
+    subtitle?: string;
+    /** Long-form markdown for the app's detail view; never on the banner. */
+    detail?: string;
+    event?: string;
+    /** What this notification is: update (default), done, or question. */
+    kind?: string;
+    project?: string;
+    session?: string;
+    device?: string[];
+    all?: boolean;
+    ttl?: number;
+    collapseKey?: string;
+    sound?: string;
+    badge?: number;
+    threadId?: string;
+    level?: string;
+    relevance?: number;
+    targetContentId?: string;
+    data?: string[];
+    image?: string;
+    /** Enable the inline reply action for this Notification Request. */
+    reply?: boolean;
+    /** How long the server accepts a reply after submission. */
+    replyWindow?: number;
+    /**
+     * Answer labels; turns the reply into a closed question. One value splits on
+     * commas; repeating the flag passes each label through verbatim.
+     */
+    replyChoice?: string | string[];
+    /** Platform whose optional notification fields these flags configure. */
+    platform?: string;
+    /**
+     * Lifecycle position of this send; not a user-facing flag. Hooks set it so
+     * questions and their retirements ride the wire as what they are.
+     */
+    lifecycle?: LifecycleT;
+}
+export type DraftBuild = {
+    ok: true;
+    draft: NotificationDraftT;
+    platform: Platform;
+} | {
+    ok: false;
+    error: string;
+};
+/** Merge flags over resolved config into a Notification Request draft. */
+export declare function buildDraft(config: CliConfig, flags: SendFlags): DraftBuild;
+/** Human one-screen receipt summary; agents use --json instead. */
+export declare function formatReceipt(receipt: SubmissionReceipt): string;
+/** Stable exit codes: 0 ok/pending, 1 rejected everywhere. */
+export declare function receiptExitCode(receipt: SubmissionReceipt): number;
+/**
+ * `"Staging,Production"` -> `[{id:'staging',label:'Staging'}, ...]`.
+ *
+ * A single occurrence splits on commas, which keeps the common one-liner
+ * short. Repeating the flag is the escape hatch, and the only way to write a
+ * label that itself contains a comma: passing `"Yes, ship it,No"` as one value
+ * silently yields three choices, and nothing downstream can detect that the
+ * agent meant two.
+ */
+export declare function parseChoices(value: string | string[] | undefined): {
+    id: string;
+    label: string;
+}[] | null | 'invalid';
+/** Message shared by every surface that accepts choice labels. */
+export declare const CHOICE_USAGE: string;
+/**
+ * Catches the split that looked like it worked.
+ *
+ * `--choice "macOS parity,Long-form detail,Nothing, I'll review"` produced four
+ * buttons rather than three, because the third label contained a comma. Nothing
+ * downstream can detect it — the labels are all well-formed — and the CLI
+ * cheerfully echoed the wrong list back, so the user saw buttons the agent
+ * never intended.
+ *
+ * The tell is a comma followed by a space. A delimiter list is written
+ * "Yes,No"; prose is written "Nothing, I'll review". That is a heuristic and it
+ * will occasionally be wrong, which is exactly why this warns and names the
+ * escape hatch rather than rejecting: the split may well have been intended.
+ */
+export declare function ambiguousChoiceSplit(value: string | string[] | undefined): string | null;

package/dist/send.js

@@ -0,0 +1,202 @@
+import { CLI_SOUNDS, INTERRUPTION_LEVELS, NOTIFICATION_SCHEMA_VERSION, NOTIFICATION_KINDS, PLATFORMS, } from '@raidiant/notifai-protocol';
+/** Merge flags over resolved config into a Notification Request draft. */
+export function buildDraft(config, flags) {
+    if (!flags.title || !flags.body)
+        return { ok: false, error: 'Both --title and --body are required.' };
+    const platform = resolvePlatform(flags.platform);
+    if (!platform) {
+        return { ok: false, error: `Unknown platform "${flags.platform}" — use ${PLATFORMS.join(' or ')}.` };
+    }
+    const deviceIds = flags.all ? null : (flags.device?.length ? flags.device : config.devices.value);
+    const targets = deviceIds && deviceIds.length > 0 ? { mode: 'selected', device_ids: deviceIds } : { mode: 'all' };
+    const sound = flags.sound ?? config.sound.value;
+    if (sound !== null && sound !== undefined && !CLI_SOUNDS.includes(sound)) {
+        return {
+            ok: false,
+            error: `Unknown sound "${sound}" — supported: ${CLI_SOUNDS.map((value) => `"${value}"`).join(', ')}.`,
+        };
+    }
+    const level = flags.level ?? config.interruption_level.value;
+    if (level !== null &&
+        level !== undefined &&
+        !INTERRUPTION_LEVELS.includes(level)) {
+        return { ok: false, error: `Unknown interruption level "${level}".` };
+    }
+    const options = {};
+    if (sound === 'none')
+        options.sound = null;
+    else if (sound !== null && sound !== undefined) {
+        options.sound = sound;
+    }
+    if (flags.badge !== undefined)
+        options.badge = flags.badge;
+    if (flags.threadId !== undefined)
+        options.thread_id = flags.threadId;
+    if (level !== null && level !== undefined) {
+        options.interruption_level = level;
+    }
+    if (flags.relevance !== undefined)
+        options.relevance_score = flags.relevance;
+    if (flags.targetContentId !== undefined)
+        options.target_content_id = flags.targetContentId;
+    if (flags.data?.length) {
+        const data = {};
+        for (const pair of flags.data) {
+            const eq = pair.indexOf('=');
+            if (eq <= 0)
+                return { ok: false, error: `--data expects key=value, got "${pair}".` };
+            data[pair.slice(0, eq)] = pair.slice(eq + 1);
+        }
+        options.custom_data = data;
+    }
+    if (flags.kind !== undefined &&
+        !NOTIFICATION_KINDS.includes(flags.kind)) {
+        return {
+            ok: false,
+            error: `Unknown kind "${flags.kind}" — supported: ${NOTIFICATION_KINDS.map((kind) => `"${kind}"`).join(', ')}.`,
+        };
+    }
+    const ttl = flags.ttl ?? config.ttl_seconds.value;
+    const collapse = flags.collapseKey ?? config.collapse_key.value;
+    const project = flags.project ?? config.project.value;
+    // Harnesses can export NOTIFAI_SESSION once instead of passing the flag
+    // on every send.
+    const session = flags.session ?? process.env['NOTIFAI_SESSION'];
+    // Ids are derived from labels so an agent writing a one-liner does not have
+    // to invent them, but they stay the stable thing it branches on afterwards.
+    const choices = parseChoices(flags.replyChoice);
+    if (choices === 'invalid') {
+        return {
+            ok: false,
+            error: CHOICE_USAGE,
+        };
+    }
+    const draft = {
+        schema_version: NOTIFICATION_SCHEMA_VERSION,
+        ...(flags.event !== undefined ? { event: flags.event } : {}),
+        ...(flags.kind !== undefined
+            ? { kind: flags.kind }
+            : {}),
+        ...(flags.lifecycle !== undefined ? { lifecycle: flags.lifecycle } : {}),
+        ...(project !== null && project !== undefined ? { project } : {}),
+        ...(session !== undefined && session !== '' ? { session } : {}),
+        presentation: {
+            title: flags.title,
+            body: flags.body,
+            ...(flags.subtitle !== undefined ? { subtitle: flags.subtitle } : {}),
+            ...(flags.detail !== undefined && flags.detail.trim() !== ''
+                ? { detail: flags.detail }
+                : {}),
+            ...(flags.image !== undefined ? { image: { media_id: flags.image } } : {}),
+        },
+        targets,
+        delivery: { ttl_seconds: ttl, collapse_key: collapse },
+        ...(flags.reply
+            ? {
+                reply: {
+                    expires_in_seconds: flags.replyWindow ?? 86400,
+                    ...(choices !== null ? { kind: 'choice', choices } : {}),
+                },
+            }
+            : {}),
+        ...(Object.keys(options).length > 0
+            ? platform === 'ios'
+                ? { platform: { ios: options } }
+                : { platform: { macos: options } }
+            : {}),
+    };
+    return { ok: true, draft, platform };
+}
+function resolvePlatform(value) {
+    if (value === undefined)
+        return 'ios';
+    return PLATFORMS.includes(value) ? value : null;
+}
+/** Human one-screen receipt summary; agents use --json instead. */
+export function formatReceipt(receipt) {
+    const lines = [];
+    const overall = receipt.overall === 'provider_accepted_all'
+        ? 'accepted by the push provider for every device'
+        : receipt.overall === 'provider_accepted_partial'
+            ? 'accepted for some devices'
+            : receipt.overall === 'provider_rejected_all'
+                ? 'rejected for every device'
+                : 'still in flight';
+    lines.push(`request ${receipt.request_id}${receipt.replayed ? ' (replayed)' : ''}: ${overall}`);
+    for (const d of receipt.deliveries) {
+        const detail = d.provider_reason ? ` (${d.provider_reason})` : '';
+        lines.push(`  ${d.device_name}: ${d.state}${detail}`);
+    }
+    for (const w of receipt.warnings)
+        lines.push(`  warning ${w.path}: ${w.message}`);
+    return lines.join('\n');
+}
+/** Stable exit codes: 0 ok/pending, 1 rejected everywhere. */
+export function receiptExitCode(receipt) {
+    return receipt.overall === 'provider_rejected_all' ? 1 : 0;
+}
+/**
+ * `"Staging,Production"` -> `[{id:'staging',label:'Staging'}, ...]`.
+ *
+ * A single occurrence splits on commas, which keeps the common one-liner
+ * short. Repeating the flag is the escape hatch, and the only way to write a
+ * label that itself contains a comma: passing `"Yes, ship it,No"` as one value
+ * silently yields three choices, and nothing downstream can detect that the
+ * agent meant two.
+ */
+export function parseChoices(value) {
+    if (value === undefined)
+        return null;
+    const raw = Array.isArray(value) ? value : [value];
+    if (raw.length === 0)
+        return null;
+    const labels = (raw.length === 1 ? (raw[0] ?? '').split(',') : raw)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (labels.length < 2 || labels.length > 6)
+        return 'invalid';
+    const choices = labels.map((label) => ({ id: slugify(label), label }));
+    if (choices.some((choice) => choice.id === ''))
+        return 'invalid';
+    if (new Set(choices.map((choice) => choice.id)).size !== choices.length)
+        return 'invalid';
+    return choices;
+}
+/** Message shared by every surface that accepts choice labels. */
+export const CHOICE_USAGE = 'Choices must be 2-6 non-empty labels, unique once slugified. One value splits on ' +
+    'commas ("Staging,Production"); repeat the flag when a label contains a comma.';
+/**
+ * Catches the split that looked like it worked.
+ *
+ * `--choice "macOS parity,Long-form detail,Nothing, I'll review"` produced four
+ * buttons rather than three, because the third label contained a comma. Nothing
+ * downstream can detect it — the labels are all well-formed — and the CLI
+ * cheerfully echoed the wrong list back, so the user saw buttons the agent
+ * never intended.
+ *
+ * The tell is a comma followed by a space. A delimiter list is written
+ * "Yes,No"; prose is written "Nothing, I'll review". That is a heuristic and it
+ * will occasionally be wrong, which is exactly why this warns and names the
+ * escape hatch rather than rejecting: the split may well have been intended.
+ */
+export function ambiguousChoiceSplit(value) {
+    if (value === undefined || Array.isArray(value))
+        return null;
+    if (!/,\s/.test(value))
+        return null;
+    const parts = value
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    return (`Heads up: "${value}" was split on commas into ${parts.length} answers ` +
+        `(${parts.join(' / ')}). If one of those labels was meant to contain a comma, ` +
+        'pass --choice once per answer instead.');
+}
+function slugify(label) {
+    return label
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32);
+}
+//# sourceMappingURL=send.js.map

package/dist/send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send.js","sourceRoot":"","sources":["../src/send.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@raidiant/notifai",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Send native phone notifications from agents and local programs",
+  "bin": {
+    "notifai": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^14.0.0",
+    "smol-toml": "^1.4.0",
+    "@raidiant/notifai-protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "Apache-2.0",
+  "author": "Rafael Vidaurre",
+  "homepage": "https://github.com/RafaelVidaurre/notifai#readme",
+  "bugs": {
+    "url": "https://github.com/RafaelVidaurre/notifai/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RafaelVidaurre/notifai.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "notifications",
+    "cli",
+    "agents",
+    "apns",
+    "push",
+    "ai",
+    "claude",
+    "codex"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,83 @@
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { afterEach, describe, expect, it } from 'vitest'
+import { NetworkError, createClient } from './client.js'
+
+/**
+ * These run against a real socket rather than a stubbed fetch, because the
+ * failure being fixed is a property of the transport: a server that accepts the
+ * connection and then says nothing. A mock that resolves or rejects cannot
+ * reproduce it.
+ */
+let server: Server | undefined
+
+afterEach(async () => {
+  if (server) {
+    const closing = server
+    server = undefined
+    await new Promise<void>((resolve) => closing.close(() => resolve()))
+  }
+})
+
+/** Starts a server with the given behaviour and returns its base URL. */
+async function serving(handler: Parameters<typeof createServer>[1]): Promise<string> {
+  server = createServer(handler)
+  await new Promise<void>((resolve) => server?.listen(0, '127.0.0.1', resolve))
+  const { port } = server.address() as AddressInfo
+  return `http://127.0.0.1:${port}`
+}
+
+describe('a server that never answers', () => {
+  it('gives up instead of hanging until the harness kills the hook', async () => {
+    // Accepts the request, holds the socket open, writes nothing — ever.
+    const held: unknown[] = []
+    const baseUrl = await serving((_request, response) => {
+      held.push(response)
+    })
+    const client = createClient(baseUrl, null, { timeoutMs: 300 })
+
+    const started = Date.now()
+    await expect(client.listDevices()).rejects.toBeInstanceOf(NetworkError)
+    // The point is that it returns at all; the bound is loose so a busy CI box
+    // does not make this flaky.
+    expect(Date.now() - started).toBeLessThan(5_000)
+    expect(held).toHaveLength(1)
+  })
+
+  it('says the server went quiet rather than reporting a bare abort', async () => {
+    const baseUrl = await serving(() => {})
+    const client = createClient(baseUrl, null, { timeoutMs: 300 })
+
+    await expect(client.listDevices()).rejects.toThrow(/did not respond within/)
+  })
+
+  it('allows for the long poll it asked the server to hold', async () => {
+    // The deadline is per request, so a 25s long poll must not be cut off by
+    // the ordinary budget — otherwise waiting for a reply could never work.
+    let seen: string | undefined
+    const baseUrl = await serving((request, response) => {
+      seen = request.url
+      response.setHeader('content-type', 'application/json')
+      response.end(JSON.stringify({ request_id: 'req_1', reply_expires_at: null, replies: [] }))
+    })
+    const client = createClient(baseUrl, null, { timeoutMs: 300 })
+
+    const result = await client.replies('req_1', { waitSeconds: 25, afterSeq: 0 })
+
+    expect(seen).toContain('wait_seconds=25')
+    expect(result.replies).toEqual([])
+  })
+
+  it('treats a truncated body as a transport failure, not a crash', async () => {
+    // A body that stops mid-JSON used to escape as a raw parse error outside
+    // the retry path, so nothing backed off and retried it.
+    const baseUrl = await serving((_request, response) => {
+      response.setHeader('content-type', 'application/json')
+      response.write('{"devices": [')
+      response.destroy()
+    })
+    const client = createClient(baseUrl, null, { timeoutMs: 500 })
+
+    await expect(client.listDevices()).rejects.toBeInstanceOf(NetworkError)
+  })
+})

package/src/client.ts

@@ -0,0 +1,183 @@
+import type {
+  ApiErrorBody,
+  BeginPairingResponse,
+  CapabilityDocument,
+  CreateMediaUploadRequestT,
+  CreateMediaUploadResponse,
+  EvidenceSnapshot,
+  ListDevicesResponse,
+  ListRepliesResponse,
+  Platform,
+  PollPairingResponse,
+  SubmissionReceipt,
+  SubmitNotificationRequestT,
+} from '@raidiant/notifai-protocol'
+
+export class ApiCallError extends Error {
+  constructor(
+    public status: number,
+    public code: string,
+    message: string,
+    public nextAction: string | null = null,
+    public details: unknown = null,
+  ) {
+    super(message)
+  }
+}
+
+export class NetworkError extends Error {}
+
+/**
+ * A deadline that fired reads as an abort, which says nothing useful on its
+ * own. Naming the timeout is what lets someone tell a hung server apart from a
+ * refused connection.
+ */
+function networkFailure(err: unknown, root: string, limitMs: number): NetworkError {
+  const name = err instanceof Error ? err.name : ''
+  if (name === 'TimeoutError' || name === 'AbortError') {
+    return new NetworkError(`${root} did not respond within ${Math.round(limitMs / 1000)}s`)
+  }
+  return new NetworkError(`Could not reach ${root}: ${String(err)}`)
+}
+
+export interface ApiClient {
+  beginPairing(body: {
+    machine_name: string
+    credential_hash: string
+    poll_verifier_hash: string
+  }): Promise<BeginPairingResponse>
+  pollPairing(pairingId: string, pollVerifier: string): Promise<PollPairingResponse>
+  listDevices(): Promise<ListDevicesResponse>
+  capabilities(platform?: Platform): Promise<CapabilityDocument>
+  submit(body: SubmitNotificationRequestT, waitSeconds: number): Promise<SubmissionReceipt>
+  evidence(requestId: string): Promise<EvidenceSnapshot>
+  replies(
+    requestId: string,
+    options: { waitSeconds: number; afterSeq: number },
+  ): Promise<ListRepliesResponse>
+  /** Retire a question so a late device answer is rejected rather than lost. */
+  closeReplies(requestId: string): Promise<void>
+  createMediaUpload(body: CreateMediaUploadRequestT): Promise<CreateMediaUploadResponse>
+  uploadMedia(grant: CreateMediaUploadResponse, bytes: Uint8Array): Promise<void>
+  health(): Promise<boolean>
+}
+
+export interface ClientOptions {
+  /**
+   * Ceiling for a single request, on top of any long poll the server has been
+   * asked to hold. Callers running inside a harness hook shrink this so their
+   * whole network path stays inside the budget the harness allows them.
+   */
+  timeoutMs?: number
+}
+
+/** Generous enough for a slow link, short enough that nothing hangs for ever. */
+const DEFAULT_TIMEOUT_MS = 20_000
+
+export function createClient(
+  baseUrl: string,
+  bearer: string | null,
+  options: ClientOptions = {},
+): ApiClient {
+  const root = baseUrl.replace(/\/$/, '')
+  const budgetMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  async function call<T>(
+    method: string,
+    apiPath: string,
+    body?: unknown,
+    /** Seconds the server was asked to hold the connection open. */
+    serverWaitSeconds = 0,
+  ): Promise<T> {
+    // Without this, a server that accepts the connection and then never answers
+    // hangs until the harness kills the whole hook — and the reply-poll deadline
+    // cannot interrupt an individual fetch. The signal covers the
+    // body read too, not just the response headers.
+    const limitMs = budgetMs + serverWaitSeconds * 1000
+    const signal = AbortSignal.timeout(limitMs)
+    let response: Response
+    try {
+      response = await fetch(`${root}${apiPath}`, {
+        method,
+        headers: {
+          ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+          ...(bearer ? { authorization: bearer } : {}),
+        },
+        signal,
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      })
+    } catch (err) {
+      throw networkFailure(err, root, limitMs)
+    }
+    if (!response.ok) {
+      let parsed: ApiErrorBody | null = null
+      try {
+        parsed = (await response.json()) as ApiErrorBody
+      } catch {
+        // non-JSON body
+      }
+      throw new ApiCallError(
+        response.status,
+        parsed?.error.code ?? 'internal_error',
+        parsed?.error.message ?? `Request failed with status ${response.status}`,
+        parsed?.error.next_action ?? null,
+        parsed?.error.details ?? null,
+      )
+    }
+    if (response.status === 204) return undefined as T
+    try {
+      return (await response.json()) as T
+    } catch (err) {
+      // A truncated or abandoned body is a transport failure, not a protocol
+      // one: it must be retryable like any other, not surface as a raw abort.
+      throw networkFailure(err, root, limitMs)
+    }
+  }
+
+  return {
+    beginPairing: (body) => call('POST', '/api/v1/pairings', body),
+    pollPairing: (pairingId, pollVerifier) =>
+      call('POST', `/api/v1/pairings/${pairingId}/poll`, { poll_verifier: pollVerifier }),
+    listDevices: () => call('GET', '/api/v1/devices'),
+    capabilities: (platform = 'ios') => call('GET', `/api/v1/capabilities/${platform}`),
+    submit: (body, waitSeconds) =>
+      call('POST', `/api/v1/notifications?wait_seconds=${waitSeconds}`, body, waitSeconds),
+    evidence: (requestId) => call('GET', `/api/v1/notifications/${requestId}`),
+    replies: (requestId, { waitSeconds, afterSeq }) =>
+      call(
+        'GET',
+        `/api/v1/notifications/${encodeURIComponent(requestId)}/replies?wait_seconds=${waitSeconds}&after_seq=${afterSeq}`,
+        undefined,
+        waitSeconds,
+      ),
+    closeReplies: (requestId) =>
+      call('POST', `/api/v1/notifications/${encodeURIComponent(requestId)}/replies/close`),
+    createMediaUpload: (body) => call('POST', '/api/v1/media', body),
+    uploadMedia: async (grant, bytes) => {
+      let response: Response
+      try {
+        response = await fetch(grant.upload_url, {
+          method: 'PUT',
+          headers: grant.upload_headers,
+          body: bytes,
+          // Media can be large, so this gets its own allowance rather than the
+          // per-request budget — but still a finite one.
+          signal: AbortSignal.timeout(Math.max(budgetMs, 60_000)),
+        })
+      } catch (err) {
+        throw new NetworkError(`Upload failed: ${String(err)}`)
+      }
+      if (!response.ok) {
+        throw new NetworkError(`Upload rejected with status ${response.status}`)
+      }
+    },
+    health: async () => {
+      try {
+        await call('GET', '/healthz')
+        return true
+      } catch {
+        return false
+      }
+    },
+  }
+}