@aiassist-secure/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Interchained LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# @aiassist-secure/core
+
+[![npm version](https://img.shields.io/npm/v/@aiassist-secure/core.svg)](https://www.npmjs.com/package/@aiassist-secure/core)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+**Framework-agnostic TypeScript SDK for AiAssist Secure** - The enterprise AI orchestration platform with shadow mode, human-in-the-loop, and real-time typing indicators.
+
+Works in **Node.js 18+** and **modern browsers**.
+
+---
+
+## Features
+
+- **OpenAI-Compatible API** - Drop-in replacement syntax
+- **Shadow Mode** - AI drafts require human approval before sending
+- **Human-in-the-Loop** - Seamless AI-to-human handoff detection
+- **Typing Preview** - Real-time "AI is typing..." indicators
+- **Streaming** - Server-sent events for token-by-token output
+- **Managed Workspaces** - Persistent conversation threads with context
+- **Full TypeScript** - Complete type definitions included
+
+---
+
+## Installation
+
+```bash
+npm install @aiassist-secure/core
+# or
+yarn add @aiassist-secure/core
+# or
+pnpm add @aiassist-secure/core
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { AiAssistClient } from '@aiassist-secure/core';
+
+const client = new AiAssistClient({ apiKey: 'aai_your_key' });
+
+// Simple chat completion (OpenAI-compatible)
+const response = await client.chat.completions.create({
+  messages: [{ role: 'user', content: 'Hello!' }]
+});
+
+console.log(response.choices[0].message.content);
+```
+
+---
+
+## Streaming Responses
+
+Get real-time token-by-token output:
+
+```typescript
+const stream = await client.chat.completions.create({
+  messages: [{ role: 'user', content: 'Write a haiku about coding' }],
+  stream: true
+});
+
+for await (const chunk of stream) {
+  const content = chunk.choices[0]?.delta?.content;
+  if (content) {
+    process.stdout.write(content); // Print each token as it arrives
+  }
+}
+```
+
+---
+
+## Managed Workspaces
+
+Create persistent conversation threads with full context:
+
+```typescript
+// Create a workspace with system prompt and context
+const { workspace, messages } = await client.workspaces.create({
+  clientId: 'user_123',
+  initial_message: 'Hello!',
+  system_prompt: 'You are a helpful customer support agent for Acme Inc.',
+  context: {
+    user_plan: 'enterprise',
+    previous_tickets: 3
+  }
+});
+
+console.log('Workspace ID:', workspace.id);
+console.log('AI Response:', messages[0].content);
+
+// Continue the conversation
+const response = await client.workspaces.sendMessage(
+  workspace.id,
+  'I need help with my billing'
+);
+
+console.log('Mode:', response.mode); // 'ai' | 'shadow' | 'takeover'
+console.log('Response:', response.responses[0].content);
+
+// Get full conversation history
+const history = await client.workspaces.getMessages(workspace.id);
+```
+
+---
+
+## Shadow Mode (Enterprise)
+
+In shadow mode, AI drafts require manager approval before being sent to the client. Perfect for training, compliance, and quality assurance:
+
+```typescript
+const response = await client.workspaces.sendMessage(workspace.id, 'Process my refund');
+
+if (response.pending_approval) {
+  console.log('AI drafted a response - awaiting manager approval');
+  console.log('Draft:', response.responses[0].content);
+  
+  // The message won't be visible to the end-user until approved
+  // Your manager dashboard can approve/reject/edit the draft
+}
+
+// Check workspace mode
+console.log('Current mode:', response.mode);
+// 'ai'      - Fully autonomous
+// 'shadow'  - AI drafts, human approves  
+// 'takeover' - Human control only
+```
+
+---
+
+## Human-in-the-Loop Detection
+
+Detect when a human agent takes over the conversation:
+
+```typescript
+const response = await client.workspaces.sendMessage(workspace.id, 'I want to speak to a human');
+
+switch (response.mode) {
+  case 'ai':
+    console.log('AI is handling this conversation');
+    break;
+  case 'shadow':
+    console.log('AI is drafting, but a human will review');
+    break;
+  case 'takeover':
+    console.log('A human agent has taken control');
+    // Update your UI to show "Speaking with Support Agent"
+    break;
+}
+```
+
+---
+
+## Typing Preview
+
+Show real-time "AI is typing..." indicators in your UI:
+
+```typescript
+// Poll for typing status (useful for chat UIs)
+const status = await client.workspaces.getTypingStatus(workspace.id);
+
+if (status.is_typing) {
+  showTypingIndicator();
+  console.log('AI is composing a response...');
+} else {
+  hideTypingIndicator();
+}
+```
+
+---
+
+## End Conversation
+
+Gracefully close conversations with optional feedback:
+
+```typescript
+// End the conversation
+await client.workspaces.endConversation(workspace.id);
+
+// Or end with a reason/feedback
+await client.workspaces.endConversation(workspace.id, {
+  reason: 'resolved',
+  feedback: 'Issue was resolved successfully'
+});
+```
+
+---
+
+## Configuration Options
+
+```typescript
+const client = new AiAssistClient({
+  apiKey: 'aai_your_key',           // Required: Your API key
+  baseURL: 'https://api.aiassist.net', // Custom endpoint
+  timeout: 30000,                    // Request timeout (ms)
+  maxRetries: 3,                     // Retry failed requests
+  defaultHeaders: {                  // Custom headers
+    'X-Custom-Header': 'value'
+  }
+});
+```
+
+---
+
+## Error Handling
+
+Typed errors for precise error handling:
+
+```typescript
+import {
+  AiAssistClient,
+  AuthenticationError,
+  RateLimitError,
+  APIError
+} from '@aiassist-secure/core';
+
+try {
+  const response = await client.chat.completions.create({
+    messages: [{ role: 'user', content: 'Hello' }]
+  });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key - check your credentials');
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
+    // Implement exponential backoff
+  } else if (error instanceof APIError) {
+    console.error(`API error ${error.status}: ${error.message}`);
+  }
+}
+```
+
+---
+
+## List Available Models
+
+```typescript
+const models = await client.models.list();
+
+console.log('Available models:');
+models.forEach(model => {
+  console.log(`- ${model.id}: ${model.context_length} tokens`);
+});
+
+// Example output:
+// - llama-3.3-70b-versatile: 128000 tokens
+// - llama-3.1-8b-instant: 131072 tokens
+// - mixtral-8x7b-32768: 32768 tokens
+```
+
+---
+
+## TypeScript Types
+
+Full type definitions included:
+
+```typescript
+import type {
+  // Core types
+  Message,
+  ChatCompletion,
+  ChatCompletionChunk,
+  ChatCompletionCreateParams,
+  
+  // Workspace types
+  Workspace,
+  WorkspaceMessage,
+  WorkspaceCreateParams,
+  WorkspaceCreateResponse,
+  SendMessageResponse,
+  WorkspaceMode,        // 'ai' | 'shadow' | 'takeover'
+  WorkspaceStatus,      // 'active' | 'ended'
+  
+  // Client types
+  AiAssistClientOptions,
+} from '@aiassist-secure/core';
+```
+
+---
+
+## Browser Usage
+
+Works directly in modern browsers via ESM:
+
+```html
+<script type="module">
+  import { AiAssistClient } from 'https://esm.sh/@aiassist-secure/core';
+  
+  const client = new AiAssistClient({ 
+    apiKey: 'aai_pub_your_domain_scoped_key' 
+  });
+  
+  const response = await client.chat.completions.create({
+    messages: [{ role: 'user', content: 'Hello from the browser!' }]
+  });
+  
+  document.getElementById('output').textContent = 
+    response.choices[0].message.content;
+</script>
+```
+
+**Note:** Use domain-scoped public keys (`aai_pub_*`) for browser environments.
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [@aiassist-secure/react](https://www.npmjs.com/package/@aiassist-secure/react) | React components with built-in UI |
+| [@aiassist-secure/vanilla](https://www.npmjs.com/package/@aiassist-secure/vanilla) | Drop-in widget for any website |
+
+---
+
+## Links
+
+- [Documentation](https://aiassist.net/developer-docs/typescript)
+- [API Reference](https://aiassist.net/api-reference)
+- [GitHub](https://github.com/aiassistsecure/aiassist-js)
+- [Discord Community](https://discord.gg/aiassist)
+
+---
+
+## License
+
+MIT License - [Interchained LLC](https://interchained.com)

package/dist/index.d.mts

@@ -0,0 +1,223 @@
+/**
+ * AiAssist SDK Types
+ */
+interface Message {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+    name?: string;
+}
+interface ChatCompletionChoice {
+    index: number;
+    message: Message;
+    finish_reason: 'stop' | 'length' | 'content_filter' | null;
+}
+interface Usage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatCompletion {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: Usage;
+}
+interface ChatCompletionChunkDelta {
+    role?: 'assistant';
+    content?: string;
+}
+interface ChatCompletionChunkChoice {
+    index: number;
+    delta: ChatCompletionChunkDelta;
+    finish_reason: 'stop' | 'length' | 'content_filter' | null;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: ChatCompletionChunkChoice[];
+}
+interface ChatCompletionCreateParams {
+    messages: Message[];
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    stream?: boolean;
+    provider?: string;
+}
+type WorkspaceMode = 'ai' | 'shadow' | 'takeover';
+type WorkspaceStatus = 'active' | 'archived' | 'deleted';
+type MessageRole = 'user' | 'ai' | 'human' | 'system';
+interface Workspace {
+    id: string;
+    mode: WorkspaceMode;
+    status: WorkspaceStatus;
+    metadata?: Record<string, unknown>;
+    created_at?: string;
+    updated_at?: string;
+}
+interface WorkspaceMessage {
+    id: string;
+    role: MessageRole;
+    content: string;
+    created_at?: string;
+    workspace_id?: string;
+}
+interface WorkspaceCreateParams {
+    initial_message?: string;
+    client_id?: string;
+    system_prompt?: string;
+    context?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+interface WorkspaceCreateResponse {
+    workspace: Workspace;
+    messages: WorkspaceMessage[];
+}
+interface SendMessageResponse {
+    user_message: WorkspaceMessage;
+    responses: WorkspaceMessage[];
+    mode: WorkspaceMode;
+    pending_approval?: boolean;
+}
+interface WorkspaceByClientResponse {
+    workspace: Workspace | null;
+    messages: WorkspaceMessage[];
+    exists: boolean;
+}
+interface Model {
+    id: string;
+    object: 'model';
+    owned_by: string;
+    created?: number;
+}
+interface ModelList {
+    object: 'list';
+    data: Model[];
+}
+interface LeadInfo {
+    leadId: string;
+    email: string;
+}
+interface AiAssistClientOptions {
+    apiKey: string;
+    baseURL?: string;
+    timeout?: number;
+    maxRetries?: number;
+    defaultHeaders?: Record<string, string>;
+}
+declare class AiAssistError extends Error {
+    status?: number;
+    code?: string;
+    constructor(message: string, status?: number, code?: string);
+}
+declare class AuthenticationError extends AiAssistError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends AiAssistError {
+    retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+declare class APIError extends AiAssistError {
+    constructor(message: string, status?: number, code?: string);
+}
+
+/**
+ * AiAssist API Client
+ *
+ * Framework-agnostic TypeScript client for the AiAssist API.
+ * Works in Node.js and browsers.
+ *
+ * Full feature parity with React and Vanilla SDKs including:
+ * - Shadow mode support (pending_approval)
+ * - Human-in-the-loop mode detection
+ * - Typing preview
+ * - Conversation management
+ */
+
+declare class AiAssistClient {
+    private apiKey;
+    private baseURL;
+    private timeout;
+    private maxRetries;
+    private defaultHeaders;
+    chat: ChatAPI;
+    models: ModelsAPI;
+    workspaces: WorkspacesAPI;
+    constructor(options: AiAssistClientOptions);
+    private getHeaders;
+    request<T>(method: string, path: string, options?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    requestSilent(method: string, path: string, options?: {
+        body?: unknown;
+    }): Promise<void>;
+    stream(method: string, path: string, body: unknown): AsyncGenerator<ChatCompletionChunk, void, unknown>;
+    private sleep;
+}
+declare class ChatAPI {
+    completions: ChatCompletionsAPI;
+    constructor(client: AiAssistClient);
+}
+declare class ChatCompletionsAPI {
+    private client;
+    constructor(client: AiAssistClient);
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }): Promise<ChatCompletion>;
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }): Promise<AsyncGenerator<ChatCompletionChunk, void, unknown>>;
+    create(params: ChatCompletionCreateParams): Promise<ChatCompletion | AsyncGenerator<ChatCompletionChunk, void, unknown>>;
+}
+declare class ModelsAPI {
+    private client;
+    constructor(client: AiAssistClient);
+    list(): Promise<Model[]>;
+}
+declare class WorkspacesAPI {
+    private client;
+    constructor(client: AiAssistClient);
+    /**
+     * Create a new workspace with optional system prompt and context.
+     *
+     * @param params - Workspace creation options
+     * @returns Workspace and initial messages
+     */
+    create(params?: WorkspaceCreateParams): Promise<WorkspaceCreateResponse>;
+    /**
+     * Get workspace by ID.
+     */
+    get(workspaceId: string): Promise<Workspace>;
+    /**
+     * Get workspace by client ID.
+     * Returns null if not found.
+     */
+    getByClientId(clientId: string): Promise<WorkspaceByClientResponse>;
+    /**
+     * Send a message to a workspace.
+     * Returns user message, AI/human responses, mode, and shadow mode approval status.
+     */
+    sendMessage(workspaceId: string, content: string): Promise<SendMessageResponse>;
+    /**
+     * Get all messages in a workspace.
+     */
+    getMessages(workspaceId: string): Promise<WorkspaceMessage[]>;
+    /**
+     * Send typing preview to workspace (for real-time typing indicators).
+     * Fails silently - non-critical operation.
+     */
+    sendTypingPreview(workspaceId: string, text: string): Promise<void>;
+    /**
+     * End a conversation/workspace.
+     * Fails silently - non-critical operation.
+     */
+    endConversation(workspaceId: string): Promise<void>;
+}
+
+export { APIError, AiAssistClient, type AiAssistClientOptions, AiAssistError, AuthenticationError, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionChunkChoice, type ChatCompletionChunkDelta, type ChatCompletionCreateParams, type LeadInfo, type Message, type MessageRole, type Model, type ModelList, RateLimitError, type SendMessageResponse, type Usage, type Workspace, type WorkspaceByClientResponse, type WorkspaceCreateParams, type WorkspaceCreateResponse, type WorkspaceMessage, type WorkspaceMode, type WorkspaceStatus };