@redplanethq/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,44 @@
+Sol License
+
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (c) 2025 — Poozle Inc.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+Additional Terms:
+
+As additional permission under GNU AGPL version 3 section 7, you
+may combine or link a "work that uses the Library" with a publicly
+distributed version of this library to produce a combined library or
+application, then distribute that combined work under the terms of
+your choice, with no requirement to comply with the obligations
+normally placed on you by section 4 of the GNU AGPL version 3
+(or the corresponding section of a later version of the GNU AGPL
+version 3 license).
+
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License (defined below), subject to the following condition:
+
+Without limiting other conditions in the License, the grant of rights under the License will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the rights granted to you under the License to provide the Software to third parties, for a fee or other consideration (including without limitation fees for hosting or consulting/support services related to the Software), as part of a product or service whose value derives, entirely or substantially, from the functionality of the Software. Any license notice or attribution required by the License must also include this Commons Clause License Condition notice.
+
+Software: All files in this repository.
+
+License: GNU Affero General Public License v3.0
+
+Licensor: Poozle Inc.

package/README.md

@@ -0,0 +1,203 @@
+# Echo SDK
+
+The Echo SDK provides tools and utilities for building integrations with the Echo platform.
+
+## Integration System
+
+The Echo integration system uses a CLI-based approach where each integration is a command-line tool that responds to specific events. This makes integrations portable, testable, and easy to debug.
+
+### Integration Event Types
+
+Each integration CLI handles 5 core event types:
+
+#### 1. `spec`
+Returns the integration's metadata and configuration.
+
+**Usage:**
+```bash
+my-integration spec
+```
+
+**Returns:** Integration specification including name, description, auth config, etc.
+
+#### 2. `setup`
+Processes authentication data and returns tokens/credentials to be saved.
+
+**Usage:**
+```bash
+my-integration setup --event-body '{"code":"oauth_code","state":"state"}' --integration-definition '{}'
+```
+
+**Returns:** Configuration data (tokens, credentials) to be stored for the account.
+
+#### 3. `identify`
+Extracts accountId from webhook data to route webhooks to the correct account.
+
+**Usage:**
+```bash
+my-integration identify --webhook-data '{"team_id":"T123","event":{}}'
+```
+
+**Returns:** Account identifier for webhook routing.
+
+#### 4. `process`
+Handles webhook events and returns activity data.
+
+**Usage:**
+```bash
+my-integration process --event-data '{"type":"reaction_added","reaction":"=M"}' --config '{"access_token":"token"}'
+```
+
+**Returns:** Activity messages representing user actions.
+
+#### 5. `sync`
+Performs scheduled data synchronization for integrations that don't support webhooks.
+
+**Usage:**
+```bash
+my-integration sync --config '{"access_token":"token","last_sync":"2023-01-01T00:00:00Z"}'
+```
+
+**Returns:** Activity messages and updated state for next sync.
+
+### Message Types
+
+All integration responses are wrapped in a `Message` object with a `type` field:
+
+- **`spec`** - Integration metadata and configuration
+- **`activity`** - User actions/events from the integration
+- **`state`** - Sync state for polling integrations
+- **`identifier`** - Account identification for webhook routing
+
+### Building an Integration
+
+1. **Install the SDK:**
+```bash
+npm install @echo/core-sdk
+```
+
+2. **Create your integration class:**
+```typescript
+import { IntegrationCLI } from '@echo/core-sdk';
+
+class MyIntegration extends IntegrationCLI {
+  constructor() {
+    super('my-integration', '1.0.0');
+  }
+
+  protected async handleEvent(eventPayload: IntegrationEventPayload): Promise<any> {
+    switch (eventPayload.event) {
+      case 'SETUP':
+        return this.handleSetup(eventPayload);
+      case 'PROCESS':
+        return this.handleProcess(eventPayload);
+      case 'IDENTIFY':
+        return this.handleIdentify(eventPayload);
+      case 'SYNC':
+        return this.handleSync(eventPayload);
+      default:
+        throw new Error(`Unknown event type: ${eventPayload.event}`);
+    }
+  }
+
+  protected async getSpec(): Promise<Spec> {
+    return {
+      name: 'My Integration',
+      key: 'my-integration',
+      description: 'Integration with My Service',
+      icon: 'https://example.com/icon.png',
+      auth: {
+        OAuth2: {
+          token_url: 'https://api.example.com/oauth/token',
+          authorization_url: 'https://api.example.com/oauth/authorize',
+          scopes: ['read', 'write']
+        }
+      }
+    };
+  }
+
+  private async handleSetup(eventPayload: IntegrationEventPayload): Promise<any> {
+    // Process OAuth response and return tokens to save
+    const { code } = eventPayload.eventBody;
+    // Exchange code for tokens...
+    return {
+      access_token: 'token',
+      refresh_token: 'refresh_token',
+      expires_at: Date.now() + 3600000
+    };
+  }
+
+  private async handleProcess(eventPayload: IntegrationEventPayload): Promise<any> {
+    // Handle webhook events
+    const { eventData } = eventPayload.eventBody;
+    // Process event and return activity...
+    return {
+      type: 'message',
+      user: 'user123',
+      content: 'Hello world',
+      timestamp: new Date()
+    };
+  }
+
+  private async handleIdentify(eventPayload: IntegrationEventPayload): Promise<any> {
+    // Extract account ID from webhook
+    const { team_id } = eventPayload.eventBody;
+    return { id: team_id };
+  }
+
+  private async handleSync(eventPayload: IntegrationEventPayload): Promise<any> {
+    // Perform scheduled sync
+    const { config } = eventPayload;
+    // Fetch data since last sync...
+    return {
+      activities: [/* activity data */],
+      state: { last_sync: new Date().toISOString() }
+    };
+  }
+}
+
+// CLI entry point
+const integration = new MyIntegration();
+integration.parse();
+```
+
+3. **Build and package your integration:**
+```bash
+npm run build
+npm pack
+```
+
+### Integration Development
+
+The `IntegrationCLI` base class provides:
+
+- **Automatic CLI setup** with all required commands
+- **JSON input/output handling** for all event types
+- **Error handling** with proper exit codes
+- **Consistent message formatting** for all responses
+
+### Testing
+
+Test your integration by running commands directly:
+
+```bash
+# Test spec
+node dist/index.js spec
+
+# Test setup
+node dist/index.js setup --event-body '{"code":"test"}' --integration-definition '{}'
+
+# Test webhook processing
+node dist/index.js process --event-data '{"type":"test"}' --config '{"token":"test"}'
+```
+
+### Best Practices
+
+1. **Always validate input data** before processing
+2. **Handle errors gracefully** with meaningful error messages
+3. **Use consistent data structures** for activities
+4. **Include proper timestamps** in all activity data
+5. **Store minimal state** for sync operations
+6. **Test all event types** thoroughly
+
+For more examples, see the integrations in the `integrations/` directory.

package/dist/index.d.mts

@@ -0,0 +1,246 @@
+import { Command } from 'commander';
+
+declare enum LLMModelEnum {
+    GPT35TURBO = "GPT35TURBO",
+    GPT4TURBO = "GPT4TURBO",
+    GPT4O = "GPT4O",
+    GPT41 = "GPT41",
+    GPT41MINI = "GPT41MINI",
+    GPT41NANO = "GPT41NANO",
+    LLAMA3 = "LLAMA3",
+    CLAUDEOPUS = "CLAUDEOPUS",
+    CLAUDESONNET = "CLAUDESONNET",
+    CLAUDEHAIKU = "CLAUDEHAIKU",
+    GEMINI25FLASH = "GEMINI25FLASH",
+    GEMINI25PRO = "GEMINI25PRO",
+    GEMINI20FLASH = "GEMINI20FLASH",
+    GEMINI20FLASHLITE = "GEMINI20FLASHLITE"
+}
+declare enum LLMMappings {
+    GPT35TURBO = "gpt-3.5-turbo",
+    GPT4TURBO = "gpt-4-turbo",
+    GPT4O = "gpt-4o",
+    GPT41 = "gpt-4.1-2025-04-14",
+    GPT41MINI = "gpt-4.1-mini-2025-04-14",
+    GPT41NANO = "gpt-4.1-nano-2025-04-14",
+    LLAMA3 = "llama3",
+    CLAUDEOPUS = "claude-3-opus-20240229",
+    CLAUDESONNET = "claude-3-7-sonnet-20250219",
+    CLAUDEHAIKU = "claude-3-5-haiku-20241022",
+    GEMINI25FLASH = "gemini-2.5-flash-preview-04-17",
+    GEMINI25PRO = "gemini-2.5-pro-preview-03-25",
+    GEMINI20FLASH = "gemini-2.0-flash",
+    GEMINI20FLASHLITE = "gemini-2.0-flash-lite"
+}
+declare const OpenAIModels: LLMModelEnum[];
+declare const ClaudeModels: LLMModelEnum[];
+declare const GeminiModels: LLMModelEnum[];
+declare const LLMModelType: {
+    GPT35TURBO: string;
+    GPT4TURBO: string;
+    GPT4O: string;
+    GPT41: string;
+    GPT41MINI: string;
+    GPT41NANO: string;
+    LLAMA3: string;
+    CLAUDEOPUS: string;
+    CLAUDESONNET: string;
+    CLAUDEHAIKU: string;
+    GEMINI25FLASH: string;
+    GEMINI25PRO: string;
+    GEMINI20FLASH: string;
+    GEMINI20FLASHLITE: string;
+};
+type LLMModelType = (typeof LLMModelType)[keyof typeof LLMModelType];
+
+declare enum EpisodeType {
+    Conversation = "CONVERSATION",
+    Text = "TEXT"
+}
+/**
+ * Interface for episodic node in the reified knowledge graph
+ * Episodes are containers for statements and represent source information
+ */
+interface EpisodicNode {
+    uuid: string;
+    content: string;
+    originalContent: string;
+    contentEmbedding?: number[];
+    metadata: Record<string, any>;
+    source: string;
+    createdAt: Date;
+    validAt: Date;
+    labels: string[];
+    userId: string;
+    space?: string;
+    sessionId?: string;
+}
+/**
+ * Interface for entity node in the reified knowledge graph
+ * Entities represent subjects, objects, or predicates in statements
+ */
+interface EntityNode {
+    uuid: string;
+    name: string;
+    type: string;
+    attributes: Record<string, any>;
+    nameEmbedding: number[];
+    createdAt: Date;
+    userId: string;
+    space?: string;
+}
+/**
+ * Interface for statement node in the reified knowledge graph
+ * Statements are first-class objects representing facts with temporal properties
+ */
+interface StatementNode {
+    uuid: string;
+    fact: string;
+    factEmbedding: number[];
+    createdAt: Date;
+    validAt: Date;
+    invalidAt: Date | null;
+    attributes: Record<string, any>;
+    userId: string;
+    space?: string;
+}
+/**
+ * Interface for a triple in the reified knowledge graph
+ * A triple connects a subject, predicate, object via a statement node
+ * and maintains provenance information
+ */
+interface Triple {
+    statement: StatementNode;
+    subject: EntityNode;
+    predicate: EntityNode;
+    object: EntityNode;
+    provenance: EpisodicNode;
+}
+type AddEpisodeParams = {
+    episodeBody: string;
+    referenceTime: Date;
+    metadata: Record<string, any>;
+    source: string;
+    userId: string;
+    spaceId?: string;
+    sessionId?: string;
+};
+type AddEpisodeResult = {
+    episodeUuid: string;
+    nodesCreated: number;
+    statementsCreated: number;
+    processingTimeMs: number;
+};
+
+declare enum ActionStatusEnum {
+    ACCEPT = "ACCEPT",
+    DECLINE = "DECLINE",
+    QUESTION = "QUESTION",
+    TOOL_REQUEST = "TOOL_REQUEST",
+    SUCCESS = "SUCCESS",
+    FAILED = "FAILED"
+}
+declare const ActionStatus: {
+    ACCEPT: string;
+    DECLINE: string;
+    QUESTION: string;
+    TOOL_REQUEST: string;
+    SUCCESS: string;
+    FAILED: string;
+};
+type ActionStatus = (typeof ActionStatus)[keyof typeof ActionStatus];
+
+declare class OAuth2Params {
+    authorization_url: string;
+    authorization_params?: Record<string, string>;
+    default_scopes?: string[];
+    scope_separator?: string;
+    scope_identifier?: string;
+    token_url: string;
+    token_params?: Record<string, string>;
+    redirect_uri_metadata?: string[];
+    token_response_metadata?: string[];
+    token_expiration_buffer?: number;
+    scopes?: string[];
+}
+type AuthType = "OAuth2" | "APIKey";
+declare class APIKeyParams {
+    "header_name": string;
+    "format": string;
+}
+
+declare enum IntegrationEventType {
+    /**
+     * Processes authentication data and returns tokens/credentials to be saved
+     */
+    SETUP = "setup",
+    /**
+     * Processing incoming data from the integration
+     */
+    PROCESS = "process",
+    /**
+     * Identifying which account a webhook belongs to
+     */
+    IDENTIFY = "identify",
+    /**
+     * Scheduled synchronization of data
+     */
+    SYNC = "sync",
+    /**
+     * For returning integration metadata/config
+     */
+    SPEC = "spec"
+}
+interface IntegrationEventPayload {
+    event: IntegrationEventType;
+    [x: string]: any;
+}
+declare class Spec {
+    name: string;
+    key: string;
+    description: string;
+    icon: string;
+    mcp?: {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+    auth?: Record<string, OAuth2Params | APIKeyParams>;
+}
+interface Config {
+    access_token: string;
+    [key: string]: any;
+}
+interface Identifier {
+    id: string;
+    type?: string;
+}
+type MessageType = "spec" | "activity" | "state" | "identifier";
+interface Message {
+    type: MessageType;
+    data: any;
+}
+
+declare enum UserTypeEnum {
+    Agent = "Agent",
+    User = "User",
+    System = "System"
+}
+
+declare abstract class IntegrationCLI {
+    protected program: Command;
+    protected integrationName: string;
+    protected version: string;
+    constructor(integrationName: string, version?: string);
+    private setupProgram;
+    private setupAccountCommands;
+    private setupDataCommands;
+    private setupSpecCommand;
+    private setupSyncCommand;
+    protected abstract handleEvent(eventPayload: IntegrationEventPayload): Promise<Message[]>;
+    protected abstract getSpec(): Promise<Spec>;
+    parse(): void;
+    getProgram(): Command;
+}
+
+export { APIKeyParams, ActionStatus, ActionStatusEnum, type AddEpisodeParams, type AddEpisodeResult, type AuthType, ClaudeModels, type Config, type EntityNode, EpisodeType, type EpisodicNode, GeminiModels, type Identifier, IntegrationCLI, type IntegrationEventPayload, IntegrationEventType, LLMMappings, LLMModelEnum, LLMModelType, type Message, type MessageType, OAuth2Params, OpenAIModels, Spec, type StatementNode, type Triple, UserTypeEnum };