@ductape/sdk 0.0.4 → 0.0.6

package/README.md

@@ -1,58 +1,92 @@
-# Ductape  
+# @ductape/sdk
 
-### **Simplifying Product Development with Seamless Interoperability**  
+SDK for building Ductape-powered products. Use a single access key to work with databases, message brokers, storage, sessions, workflows, and more.
 
-Ductape streamlines software development with **composable** and **portable** components that unify services, enable interoperability, and ensure consistency—all from your codebase.  
+## Install
 
-## 🚀 Why Ductape?  
-
-- **Composable & Reusable** – Reduce redundancy, accelerate feature development, and integrate databases, message brokers, storage, and third-party services.  
-- **Safe Testing** – Validate features in isolated environments for **reliable deployments** and **early issue detection**.  
-- **Built-in Monitoring** – Track performance, log issues, and analyze usage patterns in real time.  
-
-## 🔧 Core Features  
-
-- **Modular Components** – Seamless integration with databases, messaging, storage, and web services.  
-- **Effortless Scaling** – Dynamic resource allocation with minimal backend maintenance.  
-- **Streamlined Management** – Define, monitor, and optimize services directly in your codebase.  
-
-## 🛠 Getting Started  
-
-### 1️ Install SDK  
 ```sh
 npm install @ductape/sdk
-```  
-
-### 2️ Define Apps & Actions  
-- **Apps:** Third-party services (e.g., payment gateways, AI agents).  
-- **Actions:** Tasks like "Send Email" or "Create Payment."  
-
-### 3️ Configure App Resources  
-- **Webhooks** for real-time updates.  
-- **Events** to trigger workflows.  
-- **Authentication** via API keys or OAuth.  
-
-### 4️ Create Products & Add Apps  
-Group apps, resources, and features into a **product** for seamless interoperability.  
-
-### 5️ Define Product Resources  
-- **Storage** (AWS S3, AZURE, GCP) **Databases** (SQL & NOSQL), **Message Brokers** (RabbitMQ, AWS SQS, Redis, Kafka, Google PubSub).  
-- **Third-Party API Integrations, Notifications, Background Jobs.**  
-- **Features & Workflows** to automate actions.  
-
-### 6️ Use in Code  
-```js
-import Ductape from "@ductape/sdk";
-
-const { processor } = new Ductape(credentials);
-
-await processor.storage.save({ env: "prd", product: "myApp", event: "bucket-name", input: { blob, fileName: "text.txt" } });
-
-await processor.messageBroker.publish({ env: "prd", product: "myApp", event: "queue:topic", input: { message: { orderId: 12345 } } });
-```  
-
-## 📖 Documentation  
-Find detailed usage at [docs.ductape.app](https://docs.ductape.app).  
-
-## 📄 License  
-Ductape is **MIT-licensed**. Made with ❤️ by **Ductape Technologies**.
+```
+
+## Quick start
+
+Initialize the client with your **access key** (and optional `env_type`). Then use the namespaced APIs: `messaging`, `storage`, `sessions`, `databases`, etc.
+
+```ts
+import Ductape from '@ductape/sdk';
+
+const ductape = new Ductape({
+  accessKey: 'your-access-key',
+});
+
+// Message brokers: produce and consume
+await ductape.messaging.produce({
+  product: 'my-product',
+  env: 'prd',
+  event: 'order-events:order-created',
+  message: { orderId: '123', amount: 99.99 },
+});
+
+await ductape.messaging.consume({
+  product: 'my-product',
+  env: 'prd',
+  event: 'order-events:order-created',
+  callback: async (msg) => console.log(msg),
+});
+
+// Storage: upload, download, list files
+const uploadResult = await ductape.storage.upload({
+  product: 'my-product',
+  env: 'prd',
+  storage: 'main-storage',
+  fileName: 'reports/file.pdf',
+  buffer: fileBuffer,
+  mimeType: 'application/pdf',
+});
+
+// Sessions: start, verify, refresh
+const session = await ductape.sessions.start({
+  product: 'my-product',
+  env: 'prd',
+  tag: 'user-session',
+  data: { userId: 'u1', email: 'user@example.com' },
+});
+// session.token, session.refreshToken, session.sessionId
+```
+
+## What you can do
+
+- **Messaging** - `ductape.messaging.produce()`, `consume()`, `list()`, `fetch()`, `topics.create()`, etc. (Kafka, RabbitMQ, Redis, SQS, Pub/Sub, NATS)
+- **Storage** - `ductape.storage.upload()`, `download()`, `remove()`, `listFiles()`, `getSignedUrl()`, `stats()` (AWS S3, GCP, Azure)
+- **Sessions** - `ductape.sessions.start()`, `verify()`, `refresh()`, `revoke()`, `listActive()` (JWT-based)
+- **Databases** - relational, graph, vector (via `ductape.databases`, `ductape.graph`, `ductape.vector`)
+- **Warehouse** - unified query across relational, graph, and vector (via `ductape.warehouse`)
+- **Caching** - multi-tier cache with product-scoped tags (`ductape.cache`)
+- **Agents** - LLM agents with tools, memory, and multi-agent flows (`ductape.agents`)
+- **Resilience** - quotas, fallbacks, health checks (`ductape.quota`, `ductape.fallback`, `ductape.healthcheck`)
+- **Workflows** - define and run workflows with steps that call actions, storage, messaging, etc.
+- **Jobs** - schedule and run background jobs
+- **Notifications** - email, SMS, push (multiple providers), callbacks
+- **Secrets** - store and resolve secrets per environment
+
+## Environment
+
+The SDK is intended for **Node.js** (server). Browser use is not supported for broker, storage, and similar operations.
+
+## Documentation
+
+Full docs: [docs.ductape.app](https://docs.ductape.app)
+
+- [Message Brokers](https://docs.ductape.app/message-brokers/overview)
+- [Storage](https://docs.ductape.app/storage/overview)
+- [Sessions](https://docs.ductape.app/sessions/overview)
+- [Databases](https://docs.ductape.app/databases/relational/getting-started)
+- [Warehouse](https://docs.ductape.app/databases/warehouse/getting-started)
+- [Caching](https://docs.ductape.app/caching/overview)
+- [Agents](https://docs.ductape.app/agents/overview)
+- [Resilience](https://docs.ductape.app/resilience/overview)
+- [Workflows](https://docs.ductape.app/workflows/overview)
+
+## License
+
+MIT © Ductape Technologies

package/dist/agents/agent-context.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Agent Context
+ *
+ * Provides context to agent tool handlers, including access to
+ * Ductape components (actions, database, graph, etc.) and state management.
+ */
+import { IAgentToolContext, IAgentActionContext, IAgentDatabaseContext, IAgentGraphContext, IAgentNotificationContext, IAgentStorageContext, IAgentMessagingContext, IAgentPublishContext, IAgentFeatureContext, IAgentResilienceContext, IAgentResilienceConfig, IAgentLogger, IConversationMessage, IToolCallResult, IMemoryResult, IAgentState } from './types';
+import { IAgentServiceConfig } from './types';
+/**
+ * Memory adapter interface
+ * Allows pluggable memory implementations (in-memory, vector store, etc.)
+ */
+export interface IMemoryAdapter {
+    /** Store content with metadata */
+    store(content: string, metadata?: Record<string, unknown>): Promise<void>;
+    /** Retrieve similar content */
+    retrieve(query: string, topK?: number): Promise<IMemoryResult[]>;
+    /** Clear memory */
+    clear(): Promise<void>;
+}
+/**
+ * In-memory adapter (fallback when vector store not available)
+ */
+export declare class InMemoryAdapter implements IMemoryAdapter {
+    private memories;
+    store(content: string, metadata?: Record<string, unknown>): Promise<void>;
+    retrieve(query: string, topK?: number): Promise<IMemoryResult[]>;
+    clear(): Promise<void>;
+}
+/**
+ * Service references for context
+ */
+export interface IAgentContextServices {
+    config: IAgentServiceConfig;
+    processorService?: any;
+    productBuilder?: any;
+    databaseService?: any;
+    graphService?: any;
+    storageService?: any;
+    brokersService?: any;
+    resilienceService?: any;
+    /** Agent resilience configuration */
+    resilienceConfig?: IAgentResilienceConfig;
+}
+/**
+ * Agent Context Implementation
+ *
+ * Provides the execution context for agent tool handlers,
+ * wrapping Ductape services and managing state.
+ */
+export declare class AgentContext implements IAgentToolContext {
+    private _state;
+    private _customState;
+    private _services;
+    private _memoryAdapter;
+    private _session?;
+    readonly action: IAgentActionContext;
+    readonly database: IAgentDatabaseContext;
+    readonly graph: IAgentGraphContext;
+    readonly notification: IAgentNotificationContext;
+    readonly storage: IAgentStorageContext;
+    readonly messaging: IAgentMessagingContext;
+    readonly publish: IAgentPublishContext;
+    readonly feature: IAgentFeatureContext;
+    readonly resilience: IAgentResilienceContext;
+    readonly log: IAgentLogger;
+    constructor(state: IAgentState, services: IAgentContextServices, memoryAdapter?: IMemoryAdapter, session?: string);
+    get input(): Record<string, unknown>;
+    get execution_id(): string;
+    get agent_tag(): string;
+    get env(): string;
+    get product(): string;
+    get iteration(): number;
+    get session(): string | undefined;
+    getConversationHistory(): IConversationMessage[];
+    getToolCallHistory(): IToolCallResult[];
+    setState(key: string, value: unknown): void;
+    getState<T>(key: string): T | undefined;
+    remember(content: string, metadata?: Record<string, unknown>): Promise<void>;
+    recall(query: string, topK?: number): Promise<IMemoryResult[]>;
+    private createActionContext;
+    private createDatabaseContext;
+    private createGraphContext;
+    private createNotificationContext;
+    private createStorageContext;
+    private createMessagingContext;
+    private createPublishContext;
+    private createFeatureContext;
+    private createResilienceContext;
+    private createLogger;
+    /**
+     * Update internal state (called by AgentExecutor)
+     */
+    updateState(updates: Partial<IAgentState>): void;
+    /**
+     * Get current state snapshot
+     */
+    getStateSnapshot(): IAgentState;
+}
+export default AgentContext;