@openwop/openwop 1.3.0 → 1.5.0

package/src/client.ts

@@ -12,6 +12,13 @@ import { streamEvents, type EventsStreamOptions } from './sse.js';
 import {
   WopError,
   type AuditVerifyResult,
+  type CreateTriggerSubscriptionResponse,
+  type LocalizedContentLanguageSettings,
+  type LocalizedContentPage,
+  type LocalizedContentPageResponse,
+  type LocalizedContentSection,
+  type PutContentSectionRequest,
+  type TriggerSubscriptionRegistration,
   type BulkCancelRunsRequest,
   type BulkCancelRunsResponse,
   type Capabilities,
@@ -57,6 +64,7 @@ import {
   type OrgChartResponsibilityView,
   type EvalSummary,
   type ToolDescriptor,
+  type CompactToolDescriptor,
   type AgentDeployment,
   type AgentDeploymentTransition,
   type CreateUserAgentRequest,
@@ -529,15 +537,40 @@ export class OpenwopClient {
       }
     },
 
+    /**
+     * RFC 0112 — list the `CompactToolDescriptor`s via `GET /v1/tools?view=compact`
+     * when the host advertises `capabilities.toolCatalog.compactView`. Unwraps the
+     * `{ tools: CompactToolDescriptor[] }` envelope. Returns `null` when the host
+     * doesn't advertise the catalog (the endpoint 404s).
+     */
+    listCompact: async (): Promise<readonly CompactToolDescriptor[] | null> => {
+      try {
+        const res = await this.#request<{ tools?: readonly CompactToolDescriptor[] }>({
+          method: 'GET',
+          path: '/v1/tools?view=compact',
+        });
+        return res.tools ?? [];
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
     /**
      * RFC 0078 §B — return one `ToolDescriptor` by its stable `toolId`. Returns
-     * `null` on 404 (no such tool, or the capability is unadvertised).
+     * `null` on 404 (no such tool, or the capability is unadvertised). Pass
+     * `{ view: 'compact' }` (RFC 0112) to receive the `CompactToolDescriptor`
+     * projection instead.
      */
-    get: async (toolId: string): Promise<ToolDescriptor | null> => {
+    get: async (
+      toolId: string,
+      opts: { readonly view?: 'standard' | 'compact' } = {},
+    ): Promise<ToolDescriptor | CompactToolDescriptor | null> => {
+      const query = opts.view === 'compact' ? '?view=compact' : '';
       try {
-        return await this.#request<ToolDescriptor>({
+        return await this.#request<ToolDescriptor | CompactToolDescriptor>({
           method: 'GET',
-          path: `/v1/tools/${encodeURIComponent(toolId)}`,
+          path: `/v1/tools/${encodeURIComponent(toolId)}${query}`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -837,6 +870,108 @@ export class OpenwopClient {
     },
   };
 
+  // ── RFC 0103 Localized content surface (gated on capabilities.content) ──
+  readonly content = {
+    /** `GET /v1/content/pages` — list page records. Returns `null` when the
+     *  host doesn't advertise `capabilities.content` (501). */
+    listPages: async (): Promise<readonly LocalizedContentPage[] | null> => {
+      try {
+        return await this.#request<readonly LocalizedContentPage[]>({
+          method: 'GET',
+          path: '/v1/content/pages',
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 501) return null;
+        throw err;
+      }
+    },
+
+    /** `GET /v1/content/pages/{slug}` — the negotiated locale's resolved page +
+     *  sections. `acceptLanguage` rides the `Accept-Language` header (the Stable
+     *  `i18n.md` negotiation; no `?locale=`). Returns `null` on `404`
+     *  (no such published page) or `501` (uncapable). */
+    getPage: async (
+      slug: string,
+      acceptLanguage?: string,
+    ): Promise<LocalizedContentPageResponse | null> => {
+      try {
+        return await this.#request<LocalizedContentPageResponse>({
+          method: 'GET',
+          path: `/v1/content/pages/${encodeURIComponent(slug)}`,
+          ...(acceptLanguage
+            ? { headers: { 'Accept-Language': acceptLanguage } }
+            : {}),
+        });
+      } catch (err) {
+        if (err instanceof WopError && (err.status === 404 || err.status === 501))
+          return null;
+        throw err;
+      }
+    },
+
+    /** `POST /v1/content/pages` — create a page record (admin). Throws the
+     *  typed `WopError` on `400`/`401`/`403`. */
+    createPage: (body: LocalizedContentPage): Promise<LocalizedContentPage> =>
+      this.#request<LocalizedContentPage>({
+        method: 'POST',
+        path: '/v1/content/pages',
+        body,
+      }),
+
+    /** `PUT /v1/content/pages/{pageId}/sections/{sectionId}` — upsert a
+     *  section's field overlay for a locale (admin). */
+    putSection: (
+      pageId: string,
+      sectionId: string,
+      body: PutContentSectionRequest,
+    ): Promise<LocalizedContentSection> =>
+      this.#request<LocalizedContentSection>({
+        method: 'PUT',
+        path: `/v1/content/pages/${encodeURIComponent(pageId)}/sections/${encodeURIComponent(sectionId)}`,
+        body,
+      }),
+
+    /** `GET /v1/content/settings` — language settings. Returns `null` when the
+     *  host doesn't advertise `capabilities.content` (501). */
+    getSettings: async (): Promise<LocalizedContentLanguageSettings | null> => {
+      try {
+        return await this.#request<LocalizedContentLanguageSettings>({
+          method: 'GET',
+          path: '/v1/content/settings',
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 501) return null;
+        throw err;
+      }
+    },
+
+    /** `PUT /v1/content/settings` — replace language settings (admin). */
+    putSettings: (
+      body: LocalizedContentLanguageSettings,
+    ): Promise<LocalizedContentLanguageSettings> =>
+      this.#request<LocalizedContentLanguageSettings>({
+        method: 'PUT',
+        path: '/v1/content/settings',
+        body,
+      }),
+  };
+
+  // ── RFC 0099 Trigger subscriptions (gated on capabilities.triggerBridge) ──
+  readonly triggerSubscriptions = {
+    /** `POST /v1/trigger-subscriptions` — register an external-event trigger.
+     *  The `binding.secret*` is returned ONCE at creation (SR-1); persist it.
+     *  Throws the typed `WopError` on `400`/`401`/`403`, or `501` when the host
+     *  doesn't advertise the trigger-bridge ingestion surface. */
+    create: (
+      body: TriggerSubscriptionRegistration,
+    ): Promise<CreateTriggerSubscriptionResponse> =>
+      this.#request<CreateTriggerSubscriptionResponse>({
+        method: 'POST',
+        path: '/v1/trigger-subscriptions',
+        body,
+      }),
+  };
+
   // ── Agent workspace files (RFC 0059; gated on capabilities.workspace) ──
   readonly workspace = {
     /**

package/src/event-helpers.ts

@@ -39,6 +39,14 @@ import type {
   OutputChunkPayload,
   RunEventDoc,
   TypedRunEvent,
+  VoiceSpeechStartPayload,
+  VoiceTranscriptPayload,
+  VoiceEndpointCandidatePayload,
+  VoiceTurnCommitPayload,
+  VoiceSynthesisChunkPayload,
+  VoiceBargeInPayload,
+  VoiceCancelledPayload,
+  ChannelPresencePayload,
 } from './types.js';
 
 // ─── Type guards ────────────────────────────────────────────────────────
@@ -160,6 +168,97 @@ export function isOutputChunk(
   return typeof (ev.payload as Record<string, unknown>).isLast === 'boolean';
 }
 
+function hasNumberField(payload: unknown, field: string): boolean {
+  return (
+    payload !== null &&
+    typeof payload === 'object' &&
+    typeof (payload as Record<string, unknown>)[field] === 'number'
+  );
+}
+
+/** `voice.speech_start` (RFC 0106). */
+export function isVoiceSpeechStart(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceSpeechStartPayload> {
+  return ev.type === 'voice.speech_start' && hasNumberField(ev.payload, 'atMs');
+}
+
+/** `voice.transcript` (RFC 0106). Narrows when `type` matches AND payload
+ *  carries the required `text` + `isFinal` + `atMs` + `contentTrust`. The
+ *  transcript is untrusted ingress (`voice-transcript-untrusted`). */
+export function isVoiceTranscript(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceTranscriptPayload> {
+  return (
+    ev.type === 'voice.transcript' &&
+    hasStringField(ev.payload, 'text') &&
+    typeof (ev.payload as Record<string, unknown>).isFinal === 'boolean' &&
+    hasNumberField(ev.payload, 'atMs') &&
+    (ev.payload as Record<string, unknown>).contentTrust === 'untrusted'
+  );
+}
+
+/** `voice.endpoint_candidate` (RFC 0106). */
+export function isVoiceEndpointCandidate(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceEndpointCandidatePayload> {
+  return (
+    ev.type === 'voice.endpoint_candidate' && hasNumberField(ev.payload, 'atMs')
+  );
+}
+
+/** `voice.turn_commit` (RFC 0106). Narrows when payload carries the required
+ *  `atMs` + `finalText` (the settled transcript). */
+export function isVoiceTurnCommit(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceTurnCommitPayload> {
+  return (
+    ev.type === 'voice.turn_commit' &&
+    hasNumberField(ev.payload, 'atMs') &&
+    hasStringField(ev.payload, 'finalText')
+  );
+}
+
+/** `voice.synthesis_chunk` (RFC 0106). Narrows when payload carries the
+ *  required `seq` (number) + `mimeType` (string). */
+export function isVoiceSynthesisChunk(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceSynthesisChunkPayload> {
+  return (
+    ev.type === 'voice.synthesis_chunk' &&
+    hasNumberField(ev.payload, 'seq') &&
+    hasStringField(ev.payload, 'mimeType')
+  );
+}
+
+/** `voice.barge_in` (RFC 0106). */
+export function isVoiceBargeIn(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceBargeInPayload> {
+  return ev.type === 'voice.barge_in' && hasNumberField(ev.payload, 'atMs');
+}
+
+/** `voice.cancelled` (RFC 0106). */
+export function isVoiceCancelled(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<VoiceCancelledPayload> {
+  return ev.type === 'voice.cancelled' && hasNumberField(ev.payload, 'atMs');
+}
+
+/** `channel.presence` (RFC 0110). EPHEMERAL — observable on the LIVE event
+ *  stream only; ABSENT on replay / `:fork` (the host never persists presence
+ *  to the replayable log). Narrows when payload carries `conversationId` +
+ *  a `present` array. */
+export function isChannelPresence(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<ChannelPresencePayload> {
+  return (
+    ev.type === 'channel.presence' &&
+    hasStringField(ev.payload, 'conversationId') &&
+    Array.isArray((ev.payload as Record<string, unknown>).present)
+  );
+}
+
 // ─── High-level subscription helper ─────────────────────────────────────
 
 /** Returned by {@link subscribeToAgentReasoning}. Call to cancel the

package/src/index.ts

@@ -61,6 +61,16 @@ export type {
   MemoryWrittenPayload,
   // RFC 0094 §D — streaming output chunk (`output.chunk` / `ai.message.chunk`)
   OutputChunkPayload,
+  // RFC 0106 — voice.* run-event payloads
+  VoiceSpeechStartPayload,
+  VoiceTranscriptPayload,
+  VoiceEndpointCandidatePayload,
+  VoiceTurnCommitPayload,
+  VoiceSynthesisChunkPayload,
+  VoiceBargeInPayload,
+  VoiceCancelledPayload,
+  // RFC 0110 — channel.presence run-event payload
+  ChannelPresencePayload,
   // RFC 0027 + RFC 0028 — Prompt library (spec/v1/prompts.md)
   GetPromptRequest,
   ListPromptsRequest,
@@ -116,6 +126,14 @@ export {
   isAgentDecided,
   isMemoryWritten,
   isOutputChunk,
+  isVoiceSpeechStart,
+  isVoiceTranscript,
+  isVoiceEndpointCandidate,
+  isVoiceTurnCommit,
+  isVoiceSynthesisChunk,
+  isVoiceBargeIn,
+  isVoiceCancelled,
+  isChannelPresence,
   subscribeToAgentReasoning,
 } from './event-helpers.js';
 export type {
@@ -183,6 +201,9 @@ export type {
 // AI Envelope types (DRAFT v1.x — spec/v1/ai-envelope.md). Inbound LLM-emission
 // envelope, distinct from RunEventDoc (outbound) and ErrorEnvelope (host HTTP).
 export type {
+  A2UISurfacePayload,
+  A2uiSurfaceDeltaFrame,
+  A2uiSurfacePatchOp,
   AIEnvelope,
   AIEnvelopeErrorPayload,
   ClarificationRequestPayload,
@@ -196,6 +217,17 @@ export type {
   SchemaRequestPayload,
   SchemaResponsePayload,
   ValidationDetail,
+  // RFC 0103 — localized content surface
+  LocalizedContentStatus,
+  LocalizedContentPage,
+  LocalizedContentSection,
+  LocalizedContentPageResponse,
+  LocalizedContentLanguageSettings,
+  PutContentSectionRequest,
+  // RFC 0099 — trigger subscription registration
+  TriggerSubscriptionRegistration,
+  TriggerSubscription,
+  CreateTriggerSubscriptionResponse,
 } from './types.js';
 
 // RFC 0030 §A `reasoning` field prompt-directive helper. Hosts that