@pingroom/sdk 0.7.1 → 0.9.0

package/src/webhooks.ts

@@ -0,0 +1,373 @@
+/**
+ * Webhook helpers — usable standalone, no client/token required.
+ *
+ *  - verifyWebhookSignature: verify an OUTGOING webhook PingRoom sent you.
+ *    New deliveries carry both the legacy timestamp/body HMAC and a v2 HMAC
+ *    that also binds the delivery ID. Verify over the EXACT raw request body
+ *    bytes — re-serializing the parsed JSON will not match.
+ *
+ *  - sendIncomingWebhook: fire a room's INCOMING webhook (the URL carries its
+ *    own secret, so no agent token is needed) — the one-line CI/deploy ping.
+ *    Pass a top-level `live_status` to drive a Live Activity instead.
+ */
+
+import { PingRoomError, PingRoomTimeoutError } from './errors.js';
+import { defaultFetch } from './http.js';
+import { combineSignals } from './internal/async.js';
+import {
+  assertActionNumber,
+  assertMaxLength,
+  assertStructuredData,
+  MAX_PING_TITLE_LENGTH,
+  MAX_PUBLIC_PING_MESSAGE_LENGTH,
+  normalizeIdempotencyKey,
+} from './internal/guards.js';
+import { assertSecureUrl, redactUrlInMessage, refuseRedirect } from './internal/url.js';
+import { invalidSuccessResponse, isRecord } from './internal/validate.js';
+import type { LiveStatus } from './liveStatus.js';
+import type { AckMode, ActionState, FetchLike, JsonObject } from './types.js';
+import { VERSION } from './version.js';
+
+export const WEBHOOK_SIGNATURE_HEADER = 'X-PingRoom-Signature';
+export const WEBHOOK_SIGNATURE_V2_HEADER = 'X-PingRoom-Signature-V2';
+export const WEBHOOK_TIMESTAMP_HEADER = 'X-PingRoom-Timestamp';
+export const WEBHOOK_DELIVERY_HEADER = 'X-PingRoom-Delivery';
+export const WEBHOOK_EVENT_HEADER = 'X-PingRoom-Event';
+
+export interface VerifyWebhookSignatureOptions {
+  /**
+   * The raw request body — the exact bytes received, NOT a re-stringified
+   * object. A string, an ArrayBuffer or a typed array/Buffer. Anything else
+   * (an `{}` or `undefined` from a JSON/raw body parser that did not capture
+   * the body) throws a TypeError rather than failing verification.
+   */
+  payload: string | ArrayBuffer | ArrayBufferView;
+  /**
+   * Legacy X-PingRoom-Signature value (with or without the `sha256=` prefix).
+   * Tried only when `signatureV2` is absent and `requireV2` is not set.
+   */
+  signature?: string | null;
+  /** X-PingRoom-Signature-V2 value. When present, v2 MUST verify; v1 is not tried. */
+  signatureV2?: string | null;
+  /**
+   * Reject a delivery that carries no v2 signature instead of falling back to
+   * the legacy v1 HMAC. v1 does not sign `X-PingRoom-Delivery`, so a captured
+   * body replayed without its v2 header under a new delivery id still passes
+   * v1. Every current delivery carries v2: set this to `true`, and always set
+   * it when you dedupe on the delivery id. Default `false` for receivers that
+   * predate v2.
+   */
+  requireV2?: boolean;
+  /** The X-PingRoom-Timestamp header value (Unix seconds). */
+  timestamp: string | number | null | undefined;
+  /** X-PingRoom-Delivery value required by the v2 signed message. */
+  deliveryId?: string | null;
+  /** The webhook's signing_secret. */
+  secret: string;
+  /** Allowed timestamp skew in seconds. Defaults to 300 (five minutes). */
+  maxAgeSeconds?: number;
+}
+
+/**
+ * Constant-time verification of an outgoing-webhook signature. Returns a
+ * boolean and never throws on mismatch. Pass `requireV2: true` so a delivery
+ * without the v2 signature is refused rather than checked against v1.
+ *
+ * Throws a TypeError when `payload` is not a string, ArrayBuffer or typed
+ * array: a body parser that did not capture the raw bytes is a bug in the
+ * receiver, and must not look the same as a forged signature.
+ */
+export async function verifyWebhookSignature(opts: VerifyWebhookSignatureOptions): Promise<boolean> {
+  assertRawPayload(opts.payload);
+  const hasV2Signature = opts.signatureV2 !== null && opts.signatureV2 !== undefined;
+  if (opts.requireV2 === true && !hasV2Signature) {
+    return false;
+  }
+  const selectedSignature = hasV2Signature ? opts.signatureV2 : opts.signature;
+  if (!selectedSignature || !opts.secret) {
+    return false;
+  }
+  const timestamp = normalizeTimestamp(opts.timestamp);
+  if (timestamp === null) {
+    return false;
+  }
+  const maxAgeSeconds = opts.maxAgeSeconds ?? 300;
+  if (!Number.isFinite(maxAgeSeconds) || maxAgeSeconds < 0) {
+    return false;
+  }
+  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > maxAgeSeconds) {
+    return false;
+  }
+  const provided = normalizeSignature(selectedSignature).toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(provided)) {
+    return false;
+  }
+  let message: Uint8Array;
+  if (hasV2Signature) {
+    const deliveryId = normalizeDeliveryId(opts.deliveryId);
+    if (deliveryId === null) {
+      return false;
+    }
+    message = signedMessage(`v2\n${timestamp}\n${deliveryId}\n`, opts.payload);
+  } else {
+    message = signedMessage(`${timestamp}.`, opts.payload);
+  }
+  const expected = await hmacSha256Hex(opts.secret, message);
+  return timingSafeEqualHex(provided, expected);
+}
+
+export interface IncomingWebhookPayload {
+  /** Visible Ping body (≤ 120 characters in private rooms; ≤ 160 in public rooms). */
+  message?: string;
+  /** Visible Ping title (≤ 40 characters). */
+  title?: string;
+  /** Optional Quick Ping preset (1–16). Null bypasses the webhook's stored preset. */
+  action?: number | null;
+  /** Per-ping emoji override (≤ 16 chars, so ZWJ sequences and skin tones fit). */
+  emoji?: string;
+  /** Per-ping catalog icon override — a v3 room-icon id, validated server-side. */
+  icon?: string;
+  /** Per-ping color override: 6-digit hex, optional leading `#`. */
+  color?: string;
+  /** Per-ping sound override — a canonical sound id (see constants/sounds.json). */
+  sound?: string;
+  data?: JsonObject;
+  correlation_id?: string;
+  reply_to?: string;
+  /**
+   * Drive a Live Activity through this webhook. MUST be top-level — the server
+   * detects `live_status` on the request body, and strips it from `data` so a
+   * legacy-path caller cannot spoof completion alerts. Sending it nested under
+   * `data` silently produces an ordinary ping, not a stream.
+   *
+   * Requires `correlation_id`. Build it with the `liveStatus.*` helpers.
+   * See https://pingroom.io/liveactivities.md
+   */
+  live_status?: LiveStatus;
+  /**
+   * Override the selected quick action and require acknowledgement for this
+   * ping. Does NOT raise the delivery priority — that is {@link is_urgent}.
+   */
+  requires_ack?: boolean;
+  /** Confirmation rule for a regular ping (not live_status); defaults to any. */
+  ack_mode?: AckMode;
+  /**
+   * Deliver time-sensitive so the ping breaks through Focus / Do Not Disturb.
+   * Payload-only and independent of `requires_ack`: a webhook trigger has no
+   * stored urgency policy to inherit from the quick action it fires.
+   */
+  is_urgent?: boolean;
+  /** Optional acknowledgement deadline in seconds. Omit/null for no deadline. */
+  ack_timeout_seconds?: number | null;
+}
+
+export interface SendIncomingWebhookOptions {
+  /**
+   * Sent as the Idempotency-Key header; identical keys within ~1h replay the
+   * first result. Omitted or empty-string keys send no header. Other keys must
+   * be 1–255 printable ASCII characters (spaces allowed), else `invalid_request`
+   * before sending.
+   */
+  idempotencyKey?: string;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+  signal?: AbortSignal;
+  /** Allow plain-http webhook URLs to non-loopback hosts (off by default). */
+  allowInsecure?: boolean;
+}
+
+export interface IncomingWebhookResult {
+  success: boolean;
+  notification_id?: string;
+  message?: string;
+  action_state?: ActionState | null;
+  [key: string]: unknown;
+}
+
+/**
+ * Every field the incoming-webhook endpoint accepts, in the server's own order
+ * (`WebhookController::trigger`'s validate block, plus `live_status`, which it
+ * detects before that block and routes to the stream handler).
+ *
+ * The request body is built by walking this list rather than a hand-written run
+ * of `if`s. That run silently dropped whatever nobody remembered to add to it:
+ * first `live_status` (pre-0.3.1 — posted only `{correlation_id}`, fell into the
+ * legacy webhook branch, and returned `success: true` having created no activity
+ * at all), then `emoji`/`icon`/`color`/`sound`. Exported so a test can fail the
+ * moment this list and the server contract diverge again.
+ */
+export const INCOMING_WEBHOOK_FIELDS = [
+  'title',
+  'message',
+  'action',
+  'emoji',
+  'icon',
+  'color',
+  'sound',
+  'data',
+  'correlation_id',
+  'reply_to',
+  'is_urgent',
+  'requires_ack',
+  'ack_mode',
+  'ack_timeout_seconds',
+  // Top level, never folded into `data` — the server routes on this key and
+  // strips it from `data` so a legacy-path caller cannot spoof completion alerts.
+  'live_status',
+] as const satisfies readonly (keyof IncomingWebhookPayload)[];
+
+/** POST to a room's incoming-webhook URL (which embeds the secret in its path). */
+export async function sendIncomingWebhook(
+  webhookUrl: string,
+  payload: IncomingWebhookPayload,
+  options: SendIncomingWebhookOptions = {},
+): Promise<IncomingWebhookResult> {
+  const parsedUrl = assertSecureUrl(webhookUrl, options.allowInsecure ?? false);
+  // A webhook URL does not reveal room visibility, so validate the public
+  // ceiling here and let the server enforce 120 for private rooms.
+  assertMaxLength(payload.message, MAX_PUBLIC_PING_MESSAGE_LENGTH, 'message');
+  assertMaxLength(payload.title, MAX_PING_TITLE_LENGTH, 'title');
+  assertActionNumber(payload.action);
+  assertStructuredData(payload.data);
+
+  const body: Record<string, unknown> = {};
+  for (const field of INCOMING_WEBHOOK_FIELDS) {
+    const value = payload[field];
+    if (value !== undefined) body[field] = value;
+  }
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+    'User-Agent': `pingroom-sdk/${VERSION}`,
+  };
+  if (options.idempotencyKey) {
+    headers['Idempotency-Key'] = normalizeIdempotencyKey(options.idempotencyKey);
+  }
+
+  const fetchImpl = options.fetch ?? defaultFetch();
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new PingRoomTimeoutError()), options.timeoutMs ?? 30_000);
+  const signal = combineSignals(controller.signal, options.signal);
+
+  try {
+    // 'manual' plus an explicit refusal: Workers reject redirect: 'error', and
+    // a 307/308 must not replay this body to another origin.
+    const res = await fetchImpl(webhookUrl, { method: 'POST', headers, body: JSON.stringify(body), signal, redirect: 'manual' });
+    refuseRedirect(res);
+    const text = await res.text();
+    let json: unknown = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = text;
+      }
+    }
+    if (!res.ok || (isRecord(json) && json['success'] === false)) {
+      throw PingRoomError.fromResponse(res.status, json, res.headers);
+    }
+    // Every success the endpoint sends is a JSON object with `success: true`.
+    // Anything else is a misrouted URL or a proxy's page, not a delivered Ping.
+    if (!isRecord(json) || json['success'] !== true) {
+      throw invalidSuccessResponse(res.status, 'a JSON object with `success: true`', json);
+    }
+    return json as IncomingWebhookResult;
+  } catch (err) {
+    if (signal.aborted) {
+      throw signal.reason;
+    }
+    if (err instanceof PingRoomError) {
+      throw err;
+    }
+    const reason = redactUrlInMessage(err instanceof Error ? err.message : String(err), parsedUrl, webhookUrl);
+    throw new PingRoomError(`Webhook request failed: ${reason}`, {
+      code: 'network_error',
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// --- internals ------------------------------------------------------------
+
+function normalizeSignature(sig: string): string {
+  const s = sig.trim();
+  return s.startsWith('sha256=') ? s.slice('sha256='.length) : s;
+}
+
+function normalizeTimestamp(timestamp: string | number | null | undefined): string | null {
+  if (timestamp === null || timestamp === undefined) {
+    return null;
+  }
+  const normalized = typeof timestamp === 'string' ? timestamp.trim() : String(timestamp);
+  if (!/^\d+$/.test(normalized)) {
+    return null;
+  }
+  const seconds = Number(normalized);
+  return Number.isSafeInteger(seconds) ? normalized : null;
+}
+
+function normalizeDeliveryId(deliveryId: string | null | undefined): string | null {
+  return typeof deliveryId === 'string' && /^[\x21-\x7e]{1,255}$/.test(deliveryId)
+    ? deliveryId
+    : null;
+}
+
+// `Object.prototype.toString` rather than `instanceof ArrayBuffer`: a buffer
+// from another realm (a test sandbox, a worker) is still the raw body.
+function isArrayBuffer(value: unknown): value is ArrayBuffer {
+  return Object.prototype.toString.call(value) === '[object ArrayBuffer]';
+}
+
+function assertRawPayload(payload: unknown): void {
+  if (typeof payload === 'string' || isArrayBuffer(payload) || ArrayBuffer.isView(payload)) {
+    return;
+  }
+  const received = payload === null ? 'null' : Array.isArray(payload) ? 'an array' : typeof payload;
+  throw new TypeError(
+    `verifyWebhookSignature: \`payload\` must be the raw request body as a string, ArrayBuffer or Buffer/Uint8Array, got ${received}. `
+    + 'Capture the raw bytes before any JSON parsing (for Express: express.raw({ type: \'application/json\' }) on this route).',
+  );
+}
+
+function signedMessage(prefixText: string, payload: string | ArrayBuffer | ArrayBufferView): Uint8Array {
+  const enc = new TextEncoder();
+  const prefix = enc.encode(prefixText);
+  const body = typeof payload === 'string'
+    ? enc.encode(payload)
+    : ArrayBuffer.isView(payload)
+      // The view's own bytes: a Buffer is a window onto a larger pool, and a
+      // DataView or Int16Array must not be read element by element.
+      ? new Uint8Array(payload.buffer, payload.byteOffset, payload.byteLength)
+      : new Uint8Array(payload);
+  const message = new Uint8Array(prefix.byteLength + body.byteLength);
+  message.set(prefix, 0);
+  message.set(body, prefix.byteLength);
+  return message;
+}
+
+async function hmacSha256Hex(secret: string, message: Uint8Array): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey('raw', enc.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  const signature = await crypto.subtle.sign('HMAC', key, message as BufferSource);
+  const bytes = new Uint8Array(signature);
+  let hex = '';
+  for (const b of bytes) {
+    hex += b.toString(16).padStart(2, '0');
+  }
+  return hex;
+}
+
+/** Constant-time compare of two equal-length lowercase-hex strings. */
+function timingSafeEqualHex(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}

package/dist/liveActivity.d.ts

@@ -1,101 +0,0 @@
-/**
- * Live Activity template builders for the PingRoom agent SDK.
- *
- * IMPORTANT — these builders do NOT start an activity. The server starts,
- * updates, and ends Live Activities only from a **live-status stream**: a
- * `live_status` object sent either to a room's incoming webhook or to the agent
- * route (see https://pingroom.io/liveactivities.md). A `live_activity` block
- * placed in a `broadcast()` / `ping()` `data` object is carried as opaque
- * structured data — clients only honor the server-built, top-level
- * `live_activity` push block.
- *
- * These builders produce that `{ attributes, content_state }` block in the
- * frozen native shape (mobile/modules/live-activity/src/LiveActivity.types.ts,
- * LIVE_ACTIVITY_TEMPLATES.md). Use them when you need the native contract —
- * e.g. constructing expected payloads in tests or tooling that speaks the
- * push-layer shape.
- *
- * To actually drive a Live Activity, use `liveStatus.*` + `pr.live.push()`
- * (agent credential, `pingroom:live:write`) or `sendIncomingWebhook()`.
- */
-export type LiveActivityTemplate = 'status' | 'steps' | 'progress' | 'metrics' | 'countdown' | 'question' | 'matchup';
-export type LiveActivityStatus = 'open' | 'done' | 'failed' | 'acked' | 'answered' | 'expired' | 'cancelled';
-export interface LiveActivityMetric {
-    label: string;
-    value: string;
-}
-export interface LiveActivityOption {
-    value: string;
-    label: string;
-}
-export interface LiveActivitySide {
-    label: string;
-    value: string;
-    iconSvg?: string;
-}
-/** Identity fields common to every template (immutable for the activity's life). */
-export interface LiveActivityIdentity {
-    roomCode: string;
-    roomName: string;
-    /** Hex accent — the palette room color, or brand red `#e33122`. */
-    roomColor: string;
-    roomIconSvg?: string;
-    /** Reuse across updates to target the same activity; also links agent replies. */
-    correlationId?: string;
-    agentId?: string;
-    kind?: string;
-}
-/** Content fields shared across templates. */
-interface CommonState {
-    title: string;
-    message?: string;
-    status?: LiveActivityStatus;
-    /** Semantic accent hex for this state only (e.g. deadline red). */
-    accentOverride?: string;
-}
-/** The `data` fragment carrying a Live Activity. Spread into a ping's `data`. */
-export interface LiveActivityData {
-    live_activity: {
-        attributes: Record<string, unknown>;
-        content_state: Record<string, unknown>;
-    };
-}
-export declare const liveActivity: {
-    /** Single hero line + status dot; optional live ETA (`etaAt`, epoch seconds). */
-    status(input: LiveActivityIdentity & CommonState & {
-        progress?: number;
-        etaAt?: number;
-    }): LiveActivityData;
-    /** Checkpoint rail — the understand → plan → doc pattern. */
-    steps(input: LiveActivityIdentity & CommonState & {
-        steps: string[];
-        currentStep: number;
-    }): LiveActivityData;
-    /** Determinate progress bar (0..1), optional `etaAt` countdown. */
-    progress(input: LiveActivityIdentity & CommonState & {
-        progress: number;
-        etaAt?: number;
-    }): LiveActivityData;
-    /** Up to 3 live counters. */
-    metrics(input: LiveActivityIdentity & CommonState & {
-        metrics: LiveActivityMetric[];
-    }): LiveActivityData;
-    /** Big timer counting down to `deadlineAt` (epoch seconds). */
-    countdown(input: LiveActivityIdentity & CommonState & {
-        deadlineAt: number;
-    }): LiveActivityData;
-    /** Lock-screen ask: prompt + up to 4 options; `deadlineAt` shows time-left. */
-    question(input: LiveActivityIdentity & CommonState & {
-        prompt: string;
-        options: LiveActivityOption[];
-        deadlineAt?: number;
-    }): LiveActivityData;
-    /** Head-to-head: left · center · right. */
-    matchup(input: LiveActivityIdentity & CommonState & {
-        left: LiveActivitySide;
-        right: LiveActivitySide;
-        center?: string;
-    }): LiveActivityData;
-};
-export {};
-//# sourceMappingURL=liveActivity.d.ts.map

package/dist/liveActivity.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"liveActivity.d.ts","sourceRoot":"","sources":["../src/liveActivity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,QAAQ,GACR,OAAO,GACP,UAAU,GACV,SAAS,GACT,WAAW,GACX,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,MAAM,GACN,QAAQ,GACR,OAAO,GACP,UAAU,GACV,SAAS,GACT,WAAW,CAAC;AAEhB,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8CAA8C;AAC9C,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE;QACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH;AAgCD,eAAO,MAAM,YAAY;IACvB,iFAAiF;kBACnE,oBAAoB,GAAG,WAAW,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAKxF,6DAA6D;iBAChD,oBAAoB,GAAG,WAAW,GAAG;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;IAK1F,mEAAmE;oBACnD,oBAAoB,GAAG,WAAW,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAKzF,6BAA6B;mBACd,oBAAoB,GAAG,WAAW,GAAG;QAAE,OAAO,EAAE,kBAAkB,EAAE,CAAA;KAAE;IAKrF,+DAA+D;qBAC9C,oBAAoB,GAAG,WAAW,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE;IAK5E,+EAA+E;oBAEtE,oBAAoB,GACzB,WAAW,GAAG;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,kBAAkB,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAMxF,2CAA2C;mBAElC,oBAAoB,GACzB,WAAW,GAAG;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;CAKvF,CAAC"}

package/dist/liveActivity.js

@@ -1,83 +0,0 @@
-/**
- * Live Activity template builders for the PingRoom agent SDK.
- *
- * IMPORTANT — these builders do NOT start an activity. The server starts,
- * updates, and ends Live Activities only from a **live-status stream**: a
- * `live_status` object sent either to a room's incoming webhook or to the agent
- * route (see https://pingroom.io/liveactivities.md). A `live_activity` block
- * placed in a `broadcast()` / `ping()` `data` object is carried as opaque
- * structured data — clients only honor the server-built, top-level
- * `live_activity` push block.
- *
- * These builders produce that `{ attributes, content_state }` block in the
- * frozen native shape (mobile/modules/live-activity/src/LiveActivity.types.ts,
- * LIVE_ACTIVITY_TEMPLATES.md). Use them when you need the native contract —
- * e.g. constructing expected payloads in tests or tooling that speaks the
- * push-layer shape.
- *
- * To actually drive a Live Activity, use `liveStatus.*` + `pr.live.push()`
- * (agent credential, `pingroom:live:write`) or `sendIncomingWebhook()`.
- */
-function build(template, id, state) {
-    const { title, message, status, accentOverride, ...rest } = state;
-    return {
-        live_activity: {
-            attributes: {
-                kind: id.kind ?? 'agent',
-                template,
-                roomCode: id.roomCode,
-                roomName: id.roomName,
-                roomColor: id.roomColor,
-                ...(id.roomIconSvg ? { roomIconSvg: id.roomIconSvg } : {}),
-                ...(id.correlationId ? { correlationId: id.correlationId } : {}),
-                ...(id.agentId ? { agentId: id.agentId } : {}),
-            },
-            content_state: {
-                status: status ?? 'open',
-                title,
-                message: message ?? '',
-                ...(accentOverride ? { accentOverride } : {}),
-                ...rest,
-                updatedAt: Math.floor(Date.now() / 1000),
-            },
-        },
-    };
-}
-export const liveActivity = {
-    /** Single hero line + status dot; optional live ETA (`etaAt`, epoch seconds). */
-    status(input) {
-        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
-        return build('status', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
-    },
-    /** Checkpoint rail — the understand → plan → doc pattern. */
-    steps(input) {
-        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
-        return build('steps', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
-    },
-    /** Determinate progress bar (0..1), optional `etaAt` countdown. */
-    progress(input) {
-        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
-        return build('progress', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
-    },
-    /** Up to 3 live counters. */
-    metrics(input) {
-        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
-        return build('metrics', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
-    },
-    /** Big timer counting down to `deadlineAt` (epoch seconds). */
-    countdown(input) {
-        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
-        return build('countdown', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
-    },
-    /** Lock-screen ask: prompt + up to 4 options; `deadlineAt` shows time-left. */
-    question(input) {
-        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
-        return build('question', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
-    },
-    /** Head-to-head: left · center · right. */
-    matchup(input) {
-        const { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind, ...state } = input;
-        return build('matchup', { roomCode, roomName, roomColor, roomIconSvg, correlationId, agentId, kind }, state);
-    },
-};
-//# sourceMappingURL=liveActivity.js.map

package/dist/liveActivity.js.map

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