@applica-software-guru/persona-sdk 0.1.100 → 0.1.102

package/src/projects/types.ts

@@ -0,0 +1,52 @@
+export interface Project {
+  id?: string;
+  name?: string;
+  tag?: string;
+  apiKey?: string;
+}
+
+export interface ProjectCreateRequest {
+  name: string;
+  tag?: string;
+}
+
+export interface ProjectUpdateRequest {
+  projectId: string;
+  name?: string;
+  tag?: string;
+}
+
+export interface ProjectDuplicateRequest {
+  name: string;
+  tag?: string;
+}
+
+export interface ProjectSubscription {
+  id?: string;
+  projectId?: string;
+  owner?: string;
+  planType?: string;
+  status?: string;
+  startDate?: string;
+  planCredits?: number;
+  extraCredits?: number;
+  keepCreditsOnRenew?: boolean;
+  infiniteCredits?: boolean;
+  endDate?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  stripeCustomerId?: string;
+  stripeSubscriptionId?: string;
+}
+
+export interface ChangeProjectSubscriptionPlanRequest {
+  toPlanType: string;
+}
+
+export interface AddProjectSubscriptionCreditsRequest {
+  credits: number;
+}
+
+export interface SetProjectSubscriptionInfiniteCreditsRequest {
+  enabled: boolean;
+}

package/src/revisions/types.ts

@@ -0,0 +1,9 @@
+export interface Revision {
+  id?: string;
+  entityId?: string;
+  entityType?: string;
+  timestamp?: string;
+  data?: Record<string, unknown>;
+  userId?: string;
+  comment?: string;
+}

package/src/service-prices/service-prices-api.ts

@@ -0,0 +1,33 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { ServicePrice } from './types';
+
+export class ServicePricesApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async list(keyword?: string | null, page?: number, size?: number, extraParams?: Record<string, string>): Promise<Paginated<ServicePrice>> {
+    const { page: p, size: s } = this.normalizePageParams(page, size);
+    const params: Record<string, unknown> = { page: p, size: s, ...extraParams };
+    if (keyword) params.keyword = keyword;
+    return this.httpGet<Paginated<ServicePrice>>('/service-prices', params);
+  }
+
+  async get(id: string): Promise<ServicePrice> {
+    return this.httpGet<ServicePrice>('/service-prices/' + id);
+  }
+
+  async create(servicePrice: ServicePrice): Promise<ServicePrice> {
+    return this.httpPost<ServicePrice>('/service-prices', servicePrice);
+  }
+
+  async update(id: string, servicePrice: ServicePrice): Promise<ServicePrice> {
+    return this.httpPut<ServicePrice>('/service-prices/' + id, servicePrice);
+  }
+
+  async remove(id: string): Promise<void> {
+    await this.httpDelete('/service-prices/' + id);
+  }
+}

package/src/service-prices/types.ts

@@ -0,0 +1,8 @@
+export interface ServicePrice {
+  id?: string;
+  service?: string;
+  cost?: number;
+  unit?: string;
+  markupPercentage?: number;
+  fixedPrice?: number;
+}

package/src/sessions/sessions-api.ts

@@ -0,0 +1,90 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import {
+  Session,
+  GenerationRequest,
+  GenerationResponse,
+  Message,
+  CommittedUsage,
+  AgentStateInfo,
+  SteerAccepted,
+} from './types';
+
+export class SessionsApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async list(
+    keyword?: string | null,
+    status?: string | null,
+    agentId?: string | null,
+    userId?: string | null,
+    page?: number,
+    size?: number,
+  ): Promise<Paginated<Session>> {
+    const { page: p, size: s } = this.normalizePageParams(page, size);
+    const params: Record<string, unknown> = { page: p, size: s };
+    if (keyword) params.keyword = keyword;
+    if (status) params.status = status;
+    if (agentId) params.agentId = agentId;
+    if (userId) params.userId = userId;
+    return this.httpGet<Paginated<Session>>('/sessions', params);
+  }
+
+  async get(sessionId: string): Promise<Session> {
+    return this.httpGet<Session>('/sessions/' + sessionId);
+  }
+
+  async getUsage(sessionId: string): Promise<CommittedUsage[]> {
+    return this.httpGet<CommittedUsage[]>('/sessions/' + sessionId + '/usage');
+  }
+
+  async generateMessage(code: string, request: GenerationRequest): Promise<GenerationResponse> {
+    return this.httpPost<GenerationResponse>('/sessions/' + code + '/messages', request);
+  }
+
+  async findMessages(code: string, page?: number, size?: number): Promise<Paginated<Message>> {
+    const { page: p, size: s } = this.normalizePageParams(page, size);
+    const params: Record<string, unknown> = { page: p, size: s };
+    return this.httpGet<Paginated<Message>>('/sessions/' + code + '/messages', params);
+  }
+
+  async remove(code: string): Promise<void> {
+    await this.httpDelete('/sessions/' + code);
+  }
+
+  async rename(sessionId: string, name: string): Promise<Session> {
+    return this.httpPut<Session>('/sessions/' + sessionId + '/name', { name });
+  }
+
+  // ─── Agent Execution Lifecycle ────────────────────────────────
+
+  /**
+   * Get the current state of the agent execution for a session.
+   */
+  async getAgentState(code: string): Promise<AgentStateInfo> {
+    return this.httpGet<AgentStateInfo>('/sessions/' + encodeURIComponent(code) + '/agent-state');
+  }
+
+  /**
+   * Cancel a running agent execution for a session.
+   */
+  async cancelExecution(code: string): Promise<{ status: string; sessionId: string }> {
+    return this.httpPost<{ status: string; sessionId: string }>(
+      '/sessions/' + encodeURIComponent(code) + '/cancel',
+      {},
+    );
+  }
+
+  /**
+   * Steer a running agent execution by injecting an instruction.
+   */
+  async steerExecution(code: string, text: string): Promise<SteerAccepted> {
+    return this.httpPost<SteerAccepted>(
+      '/sessions/' + encodeURIComponent(code) + '/steer',
+      { text },
+    );
+  }
+}

package/src/sessions/types.ts

@@ -0,0 +1,150 @@
+export interface Image {
+  content?: string;
+  contentType?: string;
+}
+
+export interface SessionFile {
+  name?: string;
+  url?: string;
+  base64?: string;
+  contentType?: string;
+}
+
+export interface FunctionCall {
+  name?: string;
+  args?: Record<string, unknown>;
+  id?: string;
+}
+
+export type ToolResultItem = string | SessionFile | Image | Record<string, unknown>;
+
+export interface FunctionResponse {
+  name?: string;
+  result?: ToolResultItem | ToolResultItem[] | null;
+  functionCallId?: string;
+}
+
+export interface SourceChunk {
+  start?: number;
+  end?: number;
+}
+
+export interface Source {
+  type?: string;
+  url?: string;
+  documentId?: string;
+  pageId?: string;
+  pageNumber?: number;
+  chunks?: SourceChunk[];
+  mostRelevant?: boolean;
+}
+
+export type CollaborationMode = 'delegate_and_return' | 'persistent_transfer' | 'consult_then_respond';
+
+export interface TransferAction {
+  request?: string;
+  thought?: string;
+  agent?: string;
+  functionCallMessage?: Message;
+  functionResponseMessage?: Message;
+  collaborationMode?: CollaborationMode;
+}
+
+export interface Message {
+  id?: string;
+  sessionId?: string;
+  text?: string;
+  image?: Image;
+  file?: SessionFile;
+  role?: string;
+  timestamp?: number;
+  createdAt?: string;
+  functionCalls?: FunctionCall[];
+  functionResponse?: FunctionResponse;
+  finishReason?: string;
+  sources?: Source[];
+  task?: Record<string, unknown>;
+  sender?: string;
+  thought?: boolean;
+}
+
+export interface AgentResponse {
+  messages?: Message[];
+  transfer?: TransferAction;
+}
+
+export interface AgentContext {}
+
+export interface UsageCost {
+  service?: string;
+  value?: number;
+  cost?: number;
+  price?: number;
+  credits?: number;
+  unit?: string;
+}
+
+export interface CommittedUsage {
+  id?: string;
+  committedAt?: string;
+  projectId?: string;
+  sessionId?: string;
+  creditsUsed?: number;
+  totalCost?: number;
+  totalPrice?: number;
+  userId?: string;
+  details?: UsageCost[];
+}
+
+export interface Session {
+  id?: string;
+  code?: string;
+  name?: string;
+  projectId?: string;
+  agentId?: string;
+  currentAgentId?: string;
+  userId?: string;
+  status?: string;
+  visibility?: string;
+  type?: string;
+  createdAt?: string;
+  finishedAt?: string;
+  parentSessionId?: string;
+  protocol?: string;
+  extras?: Record<string, unknown>;
+  isNew?: boolean;
+}
+
+export interface GenerationRequest {
+  agentId?: string;
+  userMessage?: unknown;
+  initialContext?: AgentContext;
+  responseSchema?: Record<string, unknown>;
+  parentSessionId?: string;
+  userId?: string;
+}
+
+export interface GenerationResponse {
+  json?: unknown;
+  response?: AgentResponse;
+  sessionId?: string;
+}
+
+// ─── Agent Execution Lifecycle types ────────────────────────────
+
+export interface AgentStateInfo {
+  state: string;
+  sessionId?: string;
+  agentId?: string;
+  currentTurn?: number;
+  pendingSteers?: number;
+  eventCount?: number;
+  message?: string;
+}
+
+export interface SteerAccepted {
+  steerId: string;
+  text: string;
+  acceptedAt: string;
+  willProcessAfterTurn: number | null;
+}

package/src/triggers/trigger-executions-api.ts

@@ -0,0 +1,28 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { TriggerExecutionResult } from './types';
+
+export class TriggerExecutionsApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async list(triggerId: string, page?: number, size?: number): Promise<Paginated<TriggerExecutionResult>> {
+    const { page: p, size: s } = this.normalizePageParams(page, size);
+    const params: Record<string, unknown> = { page: p, size: s };
+    return this.httpGet<Paginated<TriggerExecutionResult>>('/triggers/' + triggerId + '/executions', params);
+  }
+
+  async execute(triggerId: string, execution: TriggerExecutionResult): Promise<TriggerExecutionResult> {
+    return this.httpPost<TriggerExecutionResult>('/triggers/' + triggerId + '/executions', execution);
+  }
+
+  async get(executionId: string): Promise<TriggerExecutionResult> {
+    return this.httpGet<TriggerExecutionResult>('/triggers/executions/' + executionId);
+  }
+
+  async remove(executionId: string): Promise<void> {
+    await this.httpDelete('/triggers/executions/' + executionId);
+  }
+}

package/src/triggers/triggers-api.ts

@@ -0,0 +1,38 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { Trigger } from './types';
+import { TriggerExecutionsApi } from './trigger-executions-api';
+
+export class TriggersApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async list(keyword?: string | null, page?: number, size?: number, extraParams?: Record<string, string>): Promise<Paginated<Trigger>> {
+    const { page: p, size: s } = this.normalizePageParams(page, size);
+    const params: Record<string, unknown> = { page: p, size: s, ...extraParams };
+    if (keyword) params.keyword = keyword;
+    return this.httpGet<Paginated<Trigger>>('/triggers', params);
+  }
+
+  async create(trigger: Trigger): Promise<Trigger> {
+    return this.httpPost<Trigger>('/triggers', trigger);
+  }
+
+  async update(triggerId: string, trigger: Trigger): Promise<Trigger> {
+    return this.httpPut<Trigger>('/triggers/' + triggerId, trigger);
+  }
+
+  async remove(triggerId: string): Promise<void> {
+    await this.httpDelete('/triggers/' + triggerId);
+  }
+
+  async get(triggerId: string): Promise<Trigger> {
+    return this.httpGet<Trigger>('/triggers/' + triggerId);
+  }
+
+  executions(): TriggerExecutionsApi {
+    return new TriggerExecutionsApi(this.getBaseUrl(), this.getAuthProvider());
+  }
+}

package/src/triggers/types.ts

@@ -0,0 +1,50 @@
+export type TriggerSourceType = 'webhook' | 'schedule' | 'gmail' | 'imap';
+
+export interface GmailTriggerSourceConfiguration {
+  event?: string;
+  query?: string;
+  credentialsId?: string;
+  userEmail?: string;
+  watchExpiration?: number;
+  lastHistoryId?: number;
+}
+
+export interface ImapTriggerSourceConfiguration {
+  event?: string;
+  credentialsId?: string;
+  mailbox?: string;
+  searchCriteria?: string;
+  processAttachments?: boolean;
+  allowedMimeTypes?: string[];
+}
+
+export type TriggerSourceConfiguration = GmailTriggerSourceConfiguration | ImapTriggerSourceConfiguration | Record<string, unknown>;
+
+export interface TriggerSource {
+  type?: TriggerSourceType;
+  configuration?: TriggerSourceConfiguration;
+}
+
+export interface TriggerDestination {
+  type?: string;
+  configuration?: Record<string, unknown>;
+}
+
+export interface Trigger {
+  id?: string;
+  projectId?: string;
+  name?: string;
+  source?: TriggerSource;
+  destination?: TriggerDestination;
+  enabled?: boolean;
+  createdAt?: string;
+  processedAt?: string;
+}
+
+export interface TriggerExecutionResult {
+  id?: string;
+  triggerId?: string;
+  success?: boolean;
+  message?: string;
+  processedAt?: string;
+}

package/src/values/values-api.ts

@@ -0,0 +1,84 @@
+import { HttpApi } from '../http-api';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+
+export class ValuesApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async get(category: string): Promise<Record<string, unknown>[]> {
+    return this.httpGet<Record<string, unknown>[]>('/values/' + category);
+  }
+
+  async getLanguageCodes(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/language-codes');
+  }
+
+  async getModelNames(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/model-names');
+  }
+
+  async getModelProviders(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/model-providers');
+  }
+
+  async getKnowledgeTypes(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/knowledge-types');
+  }
+
+  async getCollaborationModes(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/collaboration-modes');
+  }
+
+  async getTranscriberNames(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/transcriber-names');
+  }
+
+  async getSynthesizerNames(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/synthesizer-names');
+  }
+
+  async getSynthesizerVoices(synthesizerName: string): Promise<string[]> {
+    return this.httpGet<string[]>('/values/synthesizers/' + synthesizerName + '/voices');
+  }
+
+  async getStmTypes(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/stm-types');
+  }
+
+  async getDocumentExtractors(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/document-extractors');
+  }
+
+  async getEmbeddingModels(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/embedding-models');
+  }
+
+  async getQualityOptions(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/quality');
+  }
+
+  async getChunkSizeOptions(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/chunk-size');
+  }
+
+  async getFeatureTypes(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/feature-types');
+  }
+
+  async getRoles(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/roles');
+  }
+
+  async getServiceUnits(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/service-units');
+  }
+
+  async getTriggerSourceTypes(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/trigger-source-types');
+  }
+
+  async getTriggerDestinationTypes(): Promise<string[]> {
+    return this.httpGet<string[]>('/values/trigger-destination-types');
+  }
+}

package/src/workflows/human-tasks-api.ts

@@ -0,0 +1,44 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { HumanTask } from './types';
+
+/**
+ * Human-in-the-loop tasks. A task is created when a workflow step
+ * suspends waiting for a human (a declared `human` node or an agent
+ * escalation); responding to it resumes the run. Lives on the workflows
+ * service.
+ */
+export class HumanTasksApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  /** The project's human-task inbox. */
+  async list(
+    filters: {
+      status?: string;
+      assignee?: string;
+      workflowId?: string;
+      executionId?: string;
+      page?: number;
+      size?: number;
+    } = {},
+  ): Promise<Paginated<HumanTask>> {
+    const { page, size } = this.normalizePageParams(filters.page, filters.size ?? 50);
+    const params: Record<string, unknown> = { page, size };
+    if (filters.status ?? 'pending') params.status = filters.status ?? 'pending';
+    if (filters.assignee) params.assignee = filters.assignee;
+    if (filters.workflowId) params.workflowId = filters.workflowId;
+    if (filters.executionId) params.executionId = filters.executionId;
+    return this.httpGet<Paginated<HumanTask>>('/human-tasks', params);
+  }
+
+  /** Answer a pending human task, resuming the suspended workflow execution. */
+  async respond(humanTaskId: string, response: unknown, respondedBy?: string): Promise<HumanTask> {
+    return this.httpPost<HumanTask>('/human-tasks/' + humanTaskId + '/respond', {
+      response,
+      respondedBy,
+    });
+  }
+}