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

package/src/billing/billing-client.ts

@@ -0,0 +1,182 @@
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { ApiException } from '../exceptions';
+import {
+  Customer,
+  Subscription,
+  Invoice,
+  CreateCustomerRequest,
+  UpdateCustomerRequest,
+  CreateSubscriptionRequest,
+  UpgradeSubscriptionRequest,
+  DowngradeSubscriptionRequest,
+  MentorizeSubscriptionRequest,
+  UsageStats,
+  UsagePage,
+} from './types';
+
+export class BillingClient {
+  private readonly baseUrl: string;
+  private readonly authProvider: AuthenticationProvider | string | null;
+
+  constructor(baseUrl?: string, auth?: string | AuthenticationProvider | null) {
+    this.baseUrl = (baseUrl || 'https://persona.applica.guru/billing').replace(/\/$/, '');
+    this.authProvider = auth ?? null;
+  }
+
+  private buildHeaders(): Headers {
+    const headers = new Headers();
+    headers.set('Content-Type', 'application/json');
+    if (this.authProvider) {
+      if (typeof this.authProvider === 'string') {
+        headers.set('x-persona-apikey', this.authProvider);
+      } else {
+        this.authProvider.applyHeaders(headers);
+      }
+    }
+    return headers;
+  }
+
+  private async request<T>(path: string, method: string, body?: unknown): Promise<T> {
+    const response = await fetch(this.baseUrl + path, {
+      method,
+      headers: this.buildHeaders(),
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw new ApiException(response.status, text);
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : (undefined as T);
+  }
+
+  async createCustomer(request: CreateCustomerRequest): Promise<Customer> {
+    return this.request<Customer>('/customers', 'POST', request);
+  }
+
+  async updateCustomer(owner: string, request: UpdateCustomerRequest): Promise<Customer> {
+    return this.request<Customer>('/customers/' + owner, 'PUT', request);
+  }
+
+  async getCustomer(owner: string): Promise<Customer> {
+    return this.request<Customer>('/customers/' + owner, 'GET');
+  }
+
+  async saveCustomer(customer: Customer): Promise<Customer> {
+    return this.request<Customer>('/customers', 'POST', customer);
+  }
+
+  async deleteCustomer(owner: string): Promise<void> {
+    await this.request<void>('/customers/' + owner, 'DELETE');
+  }
+
+  async createSubscription(request: CreateSubscriptionRequest): Promise<Subscription> {
+    return this.request<Subscription>('/customers/' + request.owner + '/subscription', 'POST', request);
+  }
+
+  async getSubscription(owner: string): Promise<Subscription> {
+    return this.request<Subscription>('/customers/' + owner + '/subscription', 'GET');
+  }
+
+  async getProjectSubscription(projectId: string): Promise<Subscription> {
+    return this.request<Subscription>('/projects/' + projectId + '/subscription', 'GET');
+  }
+
+  async changeProjectSubscriptionPlan(projectId: string, request: { toPlanType: string }): Promise<Subscription> {
+    return this.request<Subscription>('/projects/' + projectId + '/subscription/actions/change-plan', 'POST', request);
+  }
+
+  async addProjectSubscriptionCredits(projectId: string, request: { credits: number }): Promise<Subscription> {
+    return this.request<Subscription>('/projects/' + projectId + '/subscription/actions/add-credits', 'POST', request);
+  }
+
+  async beginUpgrade(owner: string, request: UpgradeSubscriptionRequest): Promise<Subscription> {
+    return this.request<Subscription>('/customers/' + owner + '/subscription/actions/upgrade', 'POST', request);
+  }
+
+  async downgrade(owner: string, request: DowngradeSubscriptionRequest): Promise<Subscription> {
+    return this.request<Subscription>('/customers/' + owner + '/subscription/actions/downgrade', 'POST', request);
+  }
+
+  async mentorize(owner: string, request: MentorizeSubscriptionRequest): Promise<Subscription> {
+    return this.request<Subscription>('/customers/' + owner + '/subscription/actions/mentorize', 'POST', request);
+  }
+
+  async addCredits(owner: string, credits: number): Promise<Subscription> {
+    return this.request<Subscription>('/customers/' + owner + '/subscription/credits', 'POST', { credits });
+  }
+
+  async useCredits(
+    owner: string,
+    credits: number,
+    services: string[],
+    referenceId?: string,
+    totalCost?: number,
+    totalPrice?: number,
+  ): Promise<Subscription> {
+    const body: Record<string, unknown> = { credits, services };
+    if (referenceId) body.referenceId = referenceId;
+    if (totalCost !== undefined) body.totalCost = totalCost;
+    if (totalPrice !== undefined) body.totalPrice = totalPrice;
+    return this.request<Subscription>('/customers/' + owner + '/subscription/credits', 'DELETE', body);
+  }
+
+  async getCredits(owner: string): Promise<number> {
+    try {
+      const result = await this.request<{ credits?: number }>('/customers/' + owner + '/subscription/credits', 'GET');
+      return result.credits ?? 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  async isValid(owner: string): Promise<boolean> {
+    try {
+      const result = await this.request<{ valid?: boolean }>('/customers/' + owner + '/subscription/valid', 'GET');
+      return result.valid ?? false;
+    } catch {
+      return false;
+    }
+  }
+
+  async listInvoices(owner: string, dateFrom?: string, dateTo?: string): Promise<Invoice[]> {
+    const params: string[] = [];
+    if (dateFrom) params.push('date_from=' + dateFrom);
+    if (dateTo) params.push('date_to=' + dateTo);
+    const query = params.length > 0 ? '?' + params.join('&') : '';
+    return this.request<Invoice[]>('/customers/' + owner + '/invoices' + query, 'GET');
+  }
+
+  async cancelSubscription(owner: string): Promise<Subscription> {
+    return this.request<Subscription>('/customers/' + owner + '/subscription/actions/cancel', 'POST', {});
+  }
+
+  async getUsageStats(projectId: string, dateFrom?: string, dateTo?: string, models?: string[]): Promise<UsageStats> {
+    const params: string[] = [];
+    if (dateFrom) params.push('date_from=' + encodeURIComponent(dateFrom));
+    if (dateTo) params.push('date_to=' + encodeURIComponent(dateTo));
+    if (models?.length) models.forEach(m => params.push('model=' + encodeURIComponent(m)));
+    const query = params.length > 0 ? '?' + params.join('&') : '';
+    return this.request<UsageStats>('/projects/' + projectId + '/subscription/usage-stats' + query, 'GET');
+  }
+
+  async listUsages(
+    projectId: string,
+    dateFrom?: string,
+    dateTo?: string,
+    models?: string[],
+    sessionId?: string,
+    page?: number,
+    size?: number,
+  ): Promise<UsagePage> {
+    const params: string[] = [];
+    if (dateFrom) params.push('date_from=' + encodeURIComponent(dateFrom));
+    if (dateTo) params.push('date_to=' + encodeURIComponent(dateTo));
+    if (models?.length) models.forEach(m => params.push('model=' + encodeURIComponent(m)));
+    if (sessionId) params.push('session_id=' + encodeURIComponent(sessionId));
+    if (page !== undefined) params.push('page=' + encodeURIComponent(String(page)));
+    if (size !== undefined) params.push('size=' + encodeURIComponent(String(size)));
+    const query = params.length > 0 ? '?' + params.join('&') : '';
+    return this.request<UsagePage>('/projects/' + projectId + '/subscription/usages' + query, 'GET');
+  }
+}

package/src/billing/types.ts

@@ -0,0 +1,166 @@
+export interface Customer {
+  id?: string;
+  owner?: string;
+  name?: string;
+  email?: string;
+  phone?: string;
+  address?: string;
+  stripeCustomerId?: string;
+}
+
+export interface Subscription {
+  id?: string;
+  projectId?: string;
+  owner?: string;
+  planType?: string;
+  status?: string;
+  startDate?: string;
+  planCredits?: number;
+  extraCredits?: number;
+  keepCreditsOnRenew?: boolean;
+  endDate?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  stripeCustomerId?: string;
+  stripeSubscriptionId?: string;
+}
+
+export interface Invoice {
+  id?: string;
+  subscriptionId?: string;
+  status?: string;
+  amountDue?: number;
+  amountPaid?: number;
+  currency?: string;
+  customerEmail?: string;
+  customerName?: string;
+  hostedInvoiceUrl?: string;
+  invoicePdf?: string;
+  dueDate?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  lines?: LineItem[];
+}
+
+export interface LineItem {
+  description?: string;
+  amount?: number;
+  currency?: string;
+  quantity?: number;
+  periodStart?: string;
+  periodEnd?: string;
+}
+
+export interface Usage {
+  id?: string;
+  subscriptionId?: string;
+  creditsUsed?: number;
+  services?: string[];
+  totalCost?: number;
+  totalPrice?: number;
+  referenceId?: string;
+  sessionId?: string;
+  userId?: string;
+  details?: UsageDetail[];
+  createdAt?: string;
+}
+
+export interface UsageDetail {
+  service?: string;
+  value?: number;
+  cost?: number;
+  price?: number;
+  credits?: number;
+  unit?: string;
+  [key: string]: unknown;
+}
+
+export interface UsagePage {
+  content: Usage[];
+  totalElements: number;
+  totalPages: number;
+  page: number;
+  size: number;
+}
+
+export interface Payment {
+  id?: string;
+  subscriptionId?: string;
+  status?: string;
+  product?: string;
+  quantity?: number;
+  createdAt?: string;
+  updatedAt?: string;
+  checkoutUrl?: string;
+  stripeCheckoutSessionId?: string;
+  stripeCustomerId?: string;
+  stripeSubscriptionId?: string;
+}
+
+export interface CreateCustomerRequest {
+  owner?: string;
+  name?: string;
+  email?: string;
+  phone?: string;
+}
+
+export interface UpdateCustomerRequest {
+  name?: string;
+  email?: string;
+  phone?: string;
+}
+
+export interface CreateSubscriptionRequest {
+  owner: string;
+}
+
+export interface UpgradeSubscriptionRequest {
+  toPlanType: string;
+}
+
+export interface DowngradeSubscriptionRequest {
+  toPlanType: string;
+}
+
+export interface MentorizeSubscriptionRequest {
+  endDate?: string;
+}
+
+export interface UsageDailyEntry {
+  date: string;
+  credits: number;
+  count: number;
+  totalCost?: number;
+  totalPrice?: number;
+}
+
+export interface UsageModelEntry {
+  model: string;
+  credits: number;
+  count: number;
+  totalCost?: number;
+  totalPrice?: number;
+}
+
+export interface UsageTotals {
+  creditsUsed: number;
+  usageCount: number;
+  previousCreditsUsed: number;
+  totalCost?: number;
+  totalPrice?: number;
+  previousTotalCost?: number;
+  previousTotalPrice?: number;
+}
+
+export interface UsageStats {
+  subscription: Subscription;
+  totals: UsageTotals;
+  daily: UsageDailyEntry[];
+  byModel: UsageModelEntry[];
+  availableModels: string[];
+  hasCostData?: boolean;
+  costDataMode?: 'actual' | 'estimated_price' | 'mixed' | 'none';
+  hasEstimatedPriceData?: boolean;
+  hasActualCostData?: boolean;
+  costDataWarningCode?: string | null;
+}

package/src/credentials/credentials-api.ts

@@ -0,0 +1,40 @@
+import { HttpApi } from '../http-api';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import {
+  Credentials,
+  AuthorizeRequest,
+  AuthorizeResponse,
+  OAuth2CallbackResponse,
+} from './types';
+
+export class CredentialsApi extends HttpApi {
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    super(baseUrl, auth);
+  }
+
+  async authorize(provider: string, request: AuthorizeRequest): Promise<AuthorizeResponse> {
+    return this.httpPost<AuthorizeResponse>('/credentials/' + provider + '/authorize', request);
+  }
+
+  async handleOAuth2Callback(provider: string, code: string, state: string, scope?: string): Promise<OAuth2CallbackResponse> {
+    const params: Record<string, unknown> = { code, state };
+    if (scope) params.scope = scope;
+    return this.httpGet<OAuth2CallbackResponse>('/credentials/' + provider + '/oauth2/callback', params);
+  }
+
+  async list(): Promise<Credentials[]> {
+    return this.httpGet<Credentials[]>('/credentials');
+  }
+
+  async getByProvider(provider: string): Promise<Credentials[]> {
+    return this.httpGet<Credentials[]>('/credentials/' + provider);
+  }
+
+  async getById(credentialsId: string): Promise<Credentials> {
+    return this.httpGet<Credentials>('/credentials/all/' + credentialsId);
+  }
+
+  async remove(credentialsId: string): Promise<void> {
+    await this.httpDelete('/credentials/all/' + credentialsId);
+  }
+}

package/src/credentials/types.ts

@@ -0,0 +1,67 @@
+export interface Credentials {
+  id?: string;
+  name?: string;
+  projectId?: string;
+  provider?: string;
+  obtainedAt?: string;
+  validUntil?: string;
+  data?: unknown;
+  clientId?: string;
+  clientSecret?: string;
+  apiKey?: string;
+  apiSecret?: string;
+  token?: string;
+  successUrl?: string;
+  active?: boolean;
+  server?: string;
+  port?: number;
+  useSsl?: boolean;
+  username?: string;
+  password?: string;
+}
+
+export interface AuthorizeRequest {
+  name?: string;
+  provider?: string;
+  clientId?: string;
+  clientSecret?: string;
+  scope?: string;
+  apiKey?: string;
+  apiSecret?: string;
+  token?: string;
+  successUrl?: string;
+  server?: string;
+  port?: number;
+  useSsl?: boolean;
+  username?: string;
+  password?: string;
+}
+
+export interface OAuth2State {
+  id?: string;
+  credentialsName?: string;
+  projectId?: string;
+  provider?: string;
+  status?: string;
+  code?: string;
+  scope?: string;
+  clientId?: string;
+  clientSecret?: string;
+  apiKey?: string;
+  apiSecret?: string;
+  token?: string;
+  successUrl?: string;
+}
+
+export interface AuthorizeResponse {
+  credentials?: Credentials;
+  state?: OAuth2State;
+  redirectUrl?: string;
+}
+
+export interface OAuth2CallbackResponse {
+  id?: string;
+  successUrl?: string;
+  success?: boolean;
+  error?: string;
+}

package/src/exceptions.ts

@@ -0,0 +1,10 @@
+export class ApiException extends Error {
+  public readonly statusCode: number;
+  public readonly body: string;
+
+  constructor(statusCode: number, body: string) {
+    super(`API Error: ${statusCode} - ${body}`);
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}

package/src/features/feature-templates-api.ts

@@ -0,0 +1,43 @@
+import { HttpApi } from '../http-api';
+import { Paginated } from '../paginated';
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { FeatureTemplate, McpToolsResponse } from './types';
+import { McpServerConfiguration } from '../agents/types';
+
+export class FeatureTemplatesApi 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<FeatureTemplate>> {
+    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<FeatureTemplate>>('/features/templates', params);
+  }
+
+  async get(templateId: string): Promise<FeatureTemplate> {
+    return this.httpGet<FeatureTemplate>('/features/templates/' + templateId);
+  }
+
+  async create(template: FeatureTemplate): Promise<FeatureTemplate> {
+    return this.httpPost<FeatureTemplate>('/features/templates', template);
+  }
+
+  async update(templateId: string, template: FeatureTemplate): Promise<FeatureTemplate> {
+    return this.httpPut<FeatureTemplate>('/features/templates/' + templateId, template);
+  }
+
+  async patch(templateId: string, template: FeatureTemplate): Promise<FeatureTemplate> {
+    return this.httpPatch<FeatureTemplate>('/features/templates/' + templateId, template);
+  }
+
+  async remove(templateId: string): Promise<void> {
+    await this.httpDelete('/features/templates/' + templateId);
+  }
+
+  async getMcpAvailableTools(configuration: McpServerConfiguration, credentialsId?: string): Promise<McpToolsResponse> {
+    const params = credentialsId ? { credentialsId } : undefined;
+    return this.httpPost<McpToolsResponse>('/features/templates/mcp/available-tools', configuration, params);
+  }
+}

package/src/features/features-api.ts

@@ -0,0 +1,16 @@
+import { AuthenticationProvider } from '../auth/authentication-provider';
+import { FeatureTemplatesApi } from './feature-templates-api';
+
+export class FeaturesApi {
+  private readonly baseUrl: string;
+  private readonly auth: string | AuthenticationProvider;
+
+  constructor(baseUrl: string, auth: string | AuthenticationProvider) {
+    this.baseUrl = baseUrl;
+    this.auth = auth;
+  }
+
+  templates(): FeatureTemplatesApi {
+    return new FeatureTemplatesApi(this.baseUrl, this.auth);
+  }
+}

package/src/features/types.ts

@@ -0,0 +1,25 @@
+import { FeatureConfiguration, McpServerConfiguration } from '../agents/types';
+import { ToolDefinition } from '../agents/types';
+
+export type FeatureType = 'mcp' | 'flag' | 'skill';
+
+export interface FeatureCredentialsConfiguration {
+  requireCredentials?: boolean;
+  credentialsType?: string;
+}
+
+export interface FeatureTemplate {
+  id?: string;
+  projectId?: string;
+  type?: FeatureType;
+  name?: string;
+  description?: string;
+  logoUrl?: string;
+  configuration?: FeatureConfiguration;
+  credentialsConfiguration?: FeatureCredentialsConfiguration;
+}
+
+export interface McpToolsResponse {
+  tools?: ToolDefinition[];
+  error?: string;
+}

package/src/http-api.ts

@@ -0,0 +1,102 @@
+import { ApiException } from './exceptions';
+import { AuthenticationProvider } from './auth/authentication-provider';
+import { ApiKeyAuthenticationProvider } from './auth/api-key-auth';
+
+export abstract class HttpApi {
+  private readonly baseUrl: string;
+  private readonly authProvider: AuthenticationProvider;
+
+  constructor(baseUrl: string, apiKey: string | AuthenticationProvider) {
+    this.baseUrl = baseUrl;
+    this.authProvider = typeof apiKey === 'string' ? new ApiKeyAuthenticationProvider(apiKey) : apiKey;
+  }
+
+  protected getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  protected getAuthProvider(): AuthenticationProvider {
+    return this.authProvider;
+  }
+
+  protected normalizePageParams(page?: number, size?: number): { page: number; size: number } {
+    return {
+      page: page === undefined || page < 1 ? 1 : page,
+      size: size === undefined || size < 1 ? 20 : size,
+    };
+  }
+
+  private buildHeaders(): Headers {
+    const headers = new Headers();
+    headers.set('Content-Type', 'application/json');
+    this.authProvider.applyHeaders(headers);
+    return headers;
+  }
+
+  private buildUrl(path: string, params?: Record<string, unknown>): string {
+    const url = new URL(this.baseUrl + path);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== null && value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      });
+    }
+    return url.toString();
+  }
+
+  private async handleResponse<T>(response: Response): Promise<T> {
+    if (!response.ok) {
+      const body = await response.text();
+      throw new ApiException(response.status, body);
+    }
+    const text = await response.text();
+    return text ? JSON.parse(text) : (undefined as T);
+  }
+
+  protected async httpGet<T>(path: string, params?: Record<string, unknown>): Promise<T> {
+    const response = await fetch(this.buildUrl(path, params), {
+      method: 'GET',
+      headers: this.buildHeaders(),
+    });
+    return this.handleResponse<T>(response);
+  }
+
+  protected async httpPost<T>(path: string, body?: unknown, params?: Record<string, unknown>): Promise<T> {
+    const response = await fetch(this.buildUrl(path, params), {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    return this.handleResponse<T>(response);
+  }
+
+  protected async httpPut<T>(path: string, body: unknown): Promise<T> {
+    const response = await fetch(this.baseUrl + path, {
+      method: 'PUT',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    });
+    return this.handleResponse<T>(response);
+  }
+
+  protected async httpPatch<T>(path: string, body: unknown): Promise<T> {
+    const response = await fetch(this.baseUrl + path, {
+      method: 'PATCH',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+    });
+    return this.handleResponse<T>(response);
+  }
+
+  protected async httpDelete(path: string): Promise<void> {
+    const response = await fetch(this.baseUrl + path, {
+      method: 'DELETE',
+      headers: this.buildHeaders(),
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new ApiException(response.status, body);
+    }
+  }
+}