@applica-software-guru/persona-sdk 0.1.113 → 0.1.114

package/src/workflows/channels-api.ts

@@ -0,0 +1,61 @@
+import { HttpApi } from '../http-api';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { ChannelIdentity, ChannelLink, ChannelProvider, NotificationChannel } from './types';
+
+/**
+ * Notification channels: where the project's human tasks are announced and
+ * can be answered outside the inbox (a Telegram group, one message per
+ * task). Linking goes through one-shot deep links returned by the service.
+ * Identity endpoints require a user (IAM bearer) session. Lives on the
+ * workflows service.
+ */
+export class ChannelsApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  /** The providers enabled on the server (e.g. the Telegram bot). */
+  async providers(): Promise<ChannelProvider[]> {
+    return this.httpGet<ChannelProvider[]>('/channels/providers');
+  }
+
+  /** The project's channels, with their setup status. */
+  async list(): Promise<NotificationChannel[]> {
+    return this.httpGet<NotificationChannel[]>('/channels');
+  }
+
+  /** One-shot deep link that links a group to the project. */
+  async createLink(provider = 'telegram'): Promise<ChannelLink> {
+    return this.httpPost<ChannelLink>('/channels/' + provider + '/link-token');
+  }
+
+  async update(
+    channelId: string,
+    changes: { includePayload?: boolean; locale?: string }
+  ): Promise<NotificationChannel> {
+    return this.httpPatch<NotificationChannel>('/channels/' + channelId, changes);
+  }
+
+  /** Re-checks the channel setup (the bot can still post in the group). */
+  async verify(channelId: string): Promise<NotificationChannel> {
+    return this.httpPost<NotificationChannel>('/channels/' + channelId + '/verify');
+  }
+
+  async unlink(channelId: string): Promise<void> {
+    await this.httpDelete('/channels/' + channelId);
+  }
+
+  /** The caller's linked accounts. */
+  async myIdentities(): Promise<ChannelIdentity[]> {
+    return this.httpGet<ChannelIdentity[]>('/channels/identities/me');
+  }
+
+  /** One-shot deep link that links the caller's account. */
+  async createIdentityLink(provider = 'telegram'): Promise<ChannelLink> {
+    return this.httpPost<ChannelLink>('/channels/identities/' + provider + '/link-token');
+  }
+
+  async unlinkIdentity(provider = 'telegram'): Promise<void> {
+    await this.httpDelete('/channels/identities/me/' + provider);
+  }
+}

package/src/workflows/types.ts

@@ -152,6 +152,8 @@ export interface HumanTask {
   origin?: 'node' | 'agent_escalation';
   question?: string;
   payload?: Record<string, unknown>;
+  /** Closed set of answers (buttons); absent = free-text answer. */
+  options?: string[];
   assignee?: string;
   role?: string;
   status: string;
@@ -163,6 +165,49 @@ export interface HumanTask {
   sessionCode?: string;
 }
 
+export type ChannelStatus = 'active' | 'incomplete' | 'disconnected';
+
+/** A place where a project's human tasks are announced (e.g. a Telegram group). */
+export interface NotificationChannel {
+  id: string;
+  projectId: string;
+  provider: string;
+  chatId: string;
+  title?: string;
+  status: ChannelStatus;
+  /** Why the channel is not active (e.g. `removed`, `cannot_post`). */
+  statusDetail?: string;
+  includePayload: boolean;
+  locale: string;
+  linkedBy?: string;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/** An external account linked to the current user. */
+export interface ChannelIdentity {
+  id: string;
+  provider: string;
+  externalUserId: string;
+  externalUsername?: string;
+  iamUserId: string;
+  iamUserEmail?: string;
+  createdAt?: string;
+}
+
+export interface ChannelProvider {
+  provider: string;
+  botUsername?: string;
+  ready: boolean;
+}
+
+/** One-shot deep link completing a group or account link. */
+export interface ChannelLink {
+  token: string;
+  url: string;
+  expiresAt: string;
+}
+
 export interface Workflow {
   id?: string;
   projectId?: string;

package/src/workflows/workflows-api.ts

@@ -5,6 +5,7 @@ import { Revision } from '../revisions/types';
 import { Workflow } from './types';
 import { WorkflowExecutionsApi } from './workflow-executions-api';
 import { HumanTasksApi } from './human-tasks-api';
+import { ChannelsApi } from './channels-api';
 
 export class WorkflowsApi extends HttpApi {
   constructor(baseUrl: string, auth: string | AuthenticationProvider) {
@@ -43,6 +44,10 @@ export class WorkflowsApi extends HttpApi {
     return new HumanTasksApi(this.getBaseUrl(), this.getAuthProvider());
   }
 
+  channels(): ChannelsApi {
+    return new ChannelsApi(this.getBaseUrl(), this.getAuthProvider());
+  }
+
   async listRevisions(workflowId: string): Promise<Revision[]> {
     return this.httpGet<Revision[]>('/workflows/' + workflowId + '/revisions');
   }

package/tests/channels-api.test.mjs

@@ -0,0 +1,55 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { ChannelsApi } from '../dist/bundle.es.js';
+
+function jsonResponse(body) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+function recordFetch(context, body) {
+  const originalFetch = globalThis.fetch;
+  context.after(() => {
+    globalThis.fetch = originalFetch;
+  });
+  const calls = [];
+  globalThis.fetch = async (url, init) => {
+    calls.push({ url: String(url), method: init.method, body: init.body ? JSON.parse(init.body) : undefined });
+    return jsonResponse(body);
+  };
+  return calls;
+}
+
+test('createLink asks the workflows service for a group deep link', async (context) => {
+  const link = { token: 't', url: 'https://t.me/bot?startgroup=t', expiresAt: '2026-10-28T10:00:00' };
+  const calls = recordFetch(context, link);
+
+  const api = new ChannelsApi('https://workflows.test', 'api-key');
+  const result = await api.createLink();
+
+  assert.equal(calls[0].method, 'POST');
+  assert.equal(calls[0].url, 'https://workflows.test/channels/telegram/link-token');
+  assert.equal(result.url, link.url);
+});
+
+test('identity links and settings use the expected endpoints', async (context) => {
+  const calls = recordFetch(context, {});
+  const api = new ChannelsApi('https://workflows.test', 'api-key');
+
+  await api.createIdentityLink();
+  await api.update('wf-chan_1', { includePayload: false });
+  await api.verify('wf-chan_1');
+
+  assert.deepEqual(
+    calls.map((call) => `${call.method} ${call.url}`),
+    [
+      'POST https://workflows.test/channels/identities/telegram/link-token',
+      'PATCH https://workflows.test/channels/wf-chan_1',
+      'POST https://workflows.test/channels/wf-chan_1/verify',
+    ]
+  );
+  assert.deepEqual(calls[1].body, { includePayload: false });
+});