@rainfall-devkit/sdk 0.1.8 → 0.2.1

package/dist/errors-Chjq1Mev.d.mts

@@ -0,0 +1,332 @@
+import { R as RainfallConfig, d as RateLimitInfo, e as RequestOptions, T as ToolSchema, I as Integrations, M as Memory, c as Articles, W as Web, A as AI, D as Data, U as Utils } from './types-GnRAfH-h.mjs';
+
+/**
+ * Core HTTP client for Rainfall SDK
+ */
+
+declare class RainfallClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly defaultTimeout;
+    private readonly defaultRetries;
+    private readonly defaultRetryDelay;
+    private lastRateLimitInfo?;
+    private subscriberId?;
+    constructor(config: RainfallConfig);
+    /**
+     * Get the last rate limit info from the API
+     */
+    getRateLimitInfo(): RateLimitInfo | undefined;
+    /**
+     * Make an authenticated request to the Rainfall API
+     */
+    request<T = unknown>(path: string, options?: {
+        method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        body?: unknown;
+        headers?: Record<string, string>;
+    }, requestOptions?: RequestOptions): Promise<T>;
+    /**
+     * Execute a tool/node by ID
+     */
+    executeTool<T = unknown>(toolId: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * List all available tools
+     */
+    listTools(): Promise<Array<{
+        id: string;
+        name: string;
+        description: string;
+        category: string;
+    }>>;
+    /**
+     * Get tool schema/parameters
+     */
+    getToolSchema(toolId: string): Promise<ToolSchema>;
+    /**
+     * Get subscriber info
+     */
+    getMe(): Promise<{
+        id: string;
+        name: string;
+        email?: string;
+        plan?: string;
+        billingStatus?: string;
+        usage: {
+            callsThisMonth: number;
+            callsLimit: number;
+        };
+    }>;
+    /**
+     * Ensure we have a subscriber ID, fetching it if necessary
+     */
+    private ensureSubscriberId;
+    private sleep;
+}
+
+/**
+ * Integrations namespace for Rainfall SDK
+ * GitHub, Notion, Linear, Slack, Figma, Stripe
+ */
+
+declare class IntegrationsNamespace {
+    private client;
+    constructor(client: RainfallClient);
+    get github(): Integrations.GitHub;
+    get notion(): Integrations.Notion;
+    get linear(): Integrations.Linear;
+    get slack(): Integrations.Slack;
+    get figma(): Integrations.Figma;
+    get stripe(): Integrations.Stripe;
+}
+
+declare class Rainfall {
+    private readonly client;
+    private _integrations?;
+    private _memory?;
+    private _articles?;
+    private _web?;
+    private _ai?;
+    private _data?;
+    private _utils?;
+    constructor(config: RainfallConfig);
+    /**
+     * Integrations namespace - GitHub, Notion, Linear, Slack, Figma, Stripe
+     *
+     * @example
+     * ```typescript
+     * // GitHub
+     * await rainfall.integrations.github.issues.create({
+     *   owner: 'facebook',
+     *   repo: 'react',
+     *   title: 'Bug report'
+     * });
+     *
+     * // Slack
+     * await rainfall.integrations.slack.messages.send({
+     *   channelId: 'C123456',
+     *   text: 'Hello team!'
+     * });
+     *
+     * // Linear
+     * const issues = await rainfall.integrations.linear.issues.list();
+     * ```
+     */
+    get integrations(): IntegrationsNamespace;
+    /**
+     * Memory namespace - Semantic memory storage and retrieval
+     *
+     * @example
+     * ```typescript
+     * // Store a memory
+     * await rainfall.memory.create({
+     *   content: 'User prefers dark mode',
+     *   keywords: ['preference', 'ui']
+     * });
+     *
+     * // Recall similar memories
+     * const memories = await rainfall.memory.recall({
+     *   query: 'user preferences',
+     *   topK: 5
+     * });
+     * ```
+     */
+    get memory(): Memory.MemoryClient;
+    /**
+     * Articles namespace - News aggregation and article management
+     *
+     * @example
+     * ```typescript
+     * // Search news
+     * const articles = await rainfall.articles.search({
+     *   query: 'artificial intelligence'
+     * });
+     *
+     * // Create from URL
+     * const article = await rainfall.articles.createFromUrl({
+     *   url: 'https://example.com/article'
+     * });
+     *
+     * // Summarize
+     * const summary = await rainfall.articles.summarize({
+     *   text: article.content
+     * });
+     * ```
+     */
+    get articles(): Articles.ArticlesClient;
+    /**
+     * Web namespace - Web search, scraping, and content extraction
+     *
+     * @example
+     * ```typescript
+     * // Search with Exa
+     * const results = await rainfall.web.search.exa({
+     *   query: 'latest AI research'
+     * });
+     *
+     * // Fetch and convert
+     * const html = await rainfall.web.fetch({ url: 'https://example.com' });
+     * const markdown = await rainfall.web.htmlToMarkdown({ html });
+     *
+     * // Extract specific elements
+     * const links = await rainfall.web.extractHtml({
+     *   html,
+     *   selector: 'a[href]'
+     * });
+     * ```
+     */
+    get web(): Web.WebClient;
+    /**
+     * AI namespace - Embeddings, image generation, OCR, vision, chat
+     *
+     * @example
+     * ```typescript
+     * // Generate embeddings
+     * const embedding = await rainfall.ai.embeddings.document({
+     *   text: 'Hello world'
+     * });
+     *
+     * // Generate image
+     * const image = await rainfall.ai.image.generate({
+     *   prompt: 'A serene mountain landscape'
+     * });
+     *
+     * // OCR
+     * const text = await rainfall.ai.ocr({ imageBase64: '...' });
+     *
+     * // Chat
+     * const response = await rainfall.ai.chat({
+     *   messages: [{ role: 'user', content: 'Hello!' }]
+     * });
+     * ```
+     */
+    get ai(): AI.AIClient;
+    /**
+     * Data namespace - CSV processing, scripts, similarity search
+     *
+     * @example
+     * ```typescript
+     * // Query CSV with SQL
+     * const results = await rainfall.data.csv.query({
+     *   sql: 'SELECT * FROM data WHERE value > 100'
+     * });
+     *
+     * // Execute saved script
+     * const result = await rainfall.data.scripts.execute({
+     *   name: 'my-script',
+     *   params: { input: 'data' }
+     * });
+     * ```
+     */
+    get data(): Data.DataClient;
+    /**
+     * Utils namespace - Mermaid diagrams, document conversion, regex, JSON extraction
+     *
+     * @example
+     * ```typescript
+     * // Generate diagram
+     * const diagram = await rainfall.utils.mermaid({
+     *   diagram: 'graph TD; A-->B;'
+     * });
+     *
+     * // Convert document
+     * const pdf = await rainfall.utils.documentConvert({
+     *   document: markdownContent,
+     *   mimeType: 'text/markdown',
+     *   format: 'pdf'
+     * });
+     *
+     * // Extract JSON from text
+     * const json = await rainfall.utils.jsonExtract({
+     *   text: 'Here is some data: {"key": "value"}'
+     * });
+     * ```
+     */
+    get utils(): Utils.UtilsClient;
+    /**
+     * Get the underlying HTTP client for advanced usage
+     */
+    getClient(): RainfallClient;
+    /**
+     * List all available tools
+     */
+    listTools(): Promise<{
+        id: string;
+        name: string;
+        description: string;
+        category: string;
+    }[]>;
+    /**
+     * Get schema for a specific tool
+     */
+    getToolSchema(toolId: string): Promise<ToolSchema>;
+    /**
+     * Execute any tool by ID (low-level access)
+     */
+    executeTool<T = unknown>(toolId: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get current subscriber info and usage
+     */
+    getMe(): Promise<{
+        id: string;
+        name: string;
+        email?: string;
+        plan?: string;
+        billingStatus?: string;
+        usage: {
+            callsThisMonth: number;
+            callsLimit: number;
+        };
+    }>;
+    /**
+     * Get current rate limit info
+     */
+    getRateLimitInfo(): RateLimitInfo | undefined;
+}
+
+/**
+ * Error classes for Rainfall SDK
+ */
+declare class RainfallError extends Error {
+    readonly code: string;
+    readonly statusCode?: number | undefined;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined, details?: Record<string, unknown> | undefined);
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        statusCode: number | undefined;
+        details: Record<string, unknown> | undefined;
+    };
+}
+declare class AuthenticationError extends RainfallError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class RateLimitError extends RainfallError {
+    readonly retryAfter: number;
+    readonly limit: number;
+    readonly remaining: number;
+    readonly resetAt: Date;
+    constructor(message?: string, retryAfter?: number, limit?: number, remaining?: number, resetAt?: Date);
+}
+declare class ValidationError extends RainfallError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class NotFoundError extends RainfallError {
+    constructor(resource: string, identifier?: string);
+}
+declare class ServerError extends RainfallError {
+    constructor(message?: string, statusCode?: number);
+}
+declare class TimeoutError extends RainfallError {
+    constructor(timeoutMs: number);
+}
+declare class NetworkError extends RainfallError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+declare class ToolNotFoundError extends RainfallError {
+    constructor(toolId: string);
+}
+declare function parseErrorResponse(response: Response, data: unknown): RainfallError;
+
+export { AuthenticationError as A, NetworkError as N, Rainfall as R, ServerError as S, TimeoutError as T, ValidationError as V, NotFoundError as a, RainfallClient as b, RainfallError as c, RateLimitError as d, ToolNotFoundError as e, parseErrorResponse as p };

package/dist/index.d.mts

@@ -1,4 +1,251 @@
-export { A as AI, a as ApiError, b as ApiResponse, c as Articles, d as AuthenticationError, D as Data, I as Integrations, M as Memory, N as NetworkError, e as NotFoundError, R as Rainfall, f as RainfallClient, g as RainfallConfig, h as RainfallError, i as RateLimitError, j as RateLimitInfo, k as RequestOptions, S as ServerError, T as TimeoutError, l as ToolNotFoundError, m as ToolSchema, U as Utils, V as ValidationError, W as Web } from './errors-COkXMRZk.mjs';
+import { l as RainfallClient } from './sdk-4OvXPr8E.mjs';
+export { A as AI, b as ApiError, c as ApiResponse, d as Articles, D as Data, I as Integrations, M as Memory, a as Rainfall, R as RainfallConfig, e as RateLimitInfo, f as RequestOptions, T as ToolSchema, U as Utils, W as Web } from './sdk-4OvXPr8E.mjs';
+export { A as AuthenticationError, N as NetworkError, a as NotFoundError, R as RainfallError, b as RateLimitError, S as ServerError, T as TimeoutError, c as ToolNotFoundError, V as ValidationError } from './errors-BMPseAnM.mjs';
+export { C as ContextOptions, c as CronTriggerConfig, E as EdgeNodeRegistration, F as FileWatcherConfig, L as ListenerEvent, d as ListenerRegistry, M as MemoryEntry, N as NetworkedExecutorOptions, e as NodeCapabilities, Q as QueuedJob, a as RainfallDaemonContext, b as RainfallListenerRegistry, R as RainfallNetworkedExecutor, S as SessionContext, T as ToolExecutionRecord, f as createCronWorkflow, g as createFileWatcherWorkflow } from './listeners-MNAnpZj-.mjs';
+import 'ws';
+import '@modelcontextprotocol/sdk/client/index.js';
+import '@modelcontextprotocol/sdk/client/stdio.js';
+import '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+/**
+ * Edge Node Security Module
+ *
+ * Provides:
+ * - JWT token generation/validation for edge node authentication
+ * - ACL enforcement for job routing (same-subscriber only)
+ * - Libsodium-based encryption for job parameters
+ * - Key pair generation for edge nodes
+ */
+interface EdgeNodeJWT {
+    sub: string;
+    iss: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    scope: string[];
+}
+interface JWTPayload {
+    edgeNodeId: string;
+    subscriberId: string;
+    scopes: string[];
+    expiresAt: number;
+}
+interface ACLCheck {
+    edgeNodeId: string;
+    subscriberId: string;
+    jobSubscriberId: string;
+    action: 'claim' | 'submit' | 'queue' | 'heartbeat';
+}
+interface ACLResult {
+    allowed: boolean;
+    reason?: string;
+}
+interface EncryptedPayload {
+    ciphertext: string;
+    nonce: string;
+    ephemeralPublicKey: string;
+}
+interface KeyPair {
+    publicKey: string;
+    privateKey: string;
+}
+/**
+ * Edge Node Security Manager
+ */
+declare class EdgeNodeSecurity {
+    private sodiumReady;
+    private backendSecret?;
+    private keyPair?;
+    constructor(options?: {
+        backendSecret?: string;
+        keyPair?: KeyPair;
+    });
+    /**
+     * Initialize libsodium
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate a JWT token for an edge node
+     * Note: In production, this is done by the backend. This is for testing.
+     */
+    generateJWT(edgeNodeId: string, subscriberId: string, expiresInDays?: number): string;
+    /**
+     * Validate a JWT token
+     */
+    validateJWT(token: string): JWTPayload;
+    /**
+     * Extract bearer token from Authorization header
+     */
+    extractBearerToken(authHeader: string | undefined): string | null;
+    /**
+     * Check if an edge node is allowed to perform an action on a job
+     * Rule: Edge nodes can only access jobs for their own subscriber
+     */
+    checkACL(check: ACLCheck): ACLResult;
+    /**
+     * Middleware-style ACL check for job operations
+     */
+    requireSameSubscriber(edgeNodeSubscriberId: string, jobSubscriberId: string, operation: string): void;
+    /**
+     * Generate a new Ed25519 key pair for an edge node
+     */
+    generateKeyPair(): Promise<KeyPair>;
+    /**
+     * Encrypt job parameters for a target edge node using its public key
+     */
+    encryptForEdgeNode(plaintext: string, targetPublicKeyBase64: string): Promise<EncryptedPayload>;
+    /**
+     * Decrypt job parameters received from the backend
+     */
+    decryptFromBackend(encrypted: EncryptedPayload): Promise<string>;
+    /**
+     * Encrypt job parameters for local storage (using secretbox)
+     */
+    encryptLocal(plaintext: string, key: string): Promise<{
+        ciphertext: string;
+        nonce: string;
+    }>;
+    /**
+     * Decrypt locally stored job parameters
+     */
+    decryptLocal(encrypted: {
+        ciphertext: string;
+        nonce: string;
+    }, key: string): Promise<string>;
+    private generateTokenId;
+    private base64UrlEncode;
+    private base64UrlDecode;
+    private hmacSha256;
+    private timingSafeEqual;
+    private bytesToBase64;
+    private base64ToBytes;
+    private deriveKey;
+}
+/**
+ * Create security manager from environment or config
+ */
+declare function createEdgeNodeSecurity(options?: {
+    backendSecret?: string;
+    keyPair?: KeyPair;
+}): Promise<EdgeNodeSecurity>;
+
+/**
+ * Secure Edge Node Client
+ *
+ * Handles secure communication with the Rainfall backend:
+ * - JWT authentication on all requests
+ * - ACL validation
+ * - Job parameter encryption/decryption
+ */
+
+interface SecureEdgeConfig {
+    /** Rainfall client instance */
+    client: RainfallClient;
+    /** Edge node ID from backend registration */
+    edgeNodeId: string;
+    /** JWT secret from backend */
+    edgeNodeSecret: string;
+    /** Path to key directory (contains edge-node.pub and edge-node.key) */
+    keysPath: string;
+    /** Backend secret for JWT validation (optional, for testing) */
+    backendSecret?: string;
+}
+interface SecureJob {
+    id: string;
+    subscriberId: string;
+    type: string;
+    params?: string;
+    encrypted?: boolean;
+}
+interface JobResult {
+    jobId: string;
+    success: boolean;
+    output?: string;
+    error?: string;
+}
+/**
+ * Secure Edge Node Client
+ *
+ * Wraps the Rainfall Client with security features for edge node operation.
+ */
+declare class SecureEdgeClient {
+    private client;
+    private security;
+    private edgeNodeId;
+    private edgeNodeSecret;
+    private keysPath;
+    private jwtPayload?;
+    private keyPair?;
+    constructor(config: SecureEdgeConfig);
+    /**
+     * Initialize the secure client
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load key pair from disk
+     */
+    private loadKeyPair;
+    /**
+     * Get public key for sharing with backend
+     */
+    getPublicKey(): string;
+    /**
+     * Send heartbeat with authentication
+     */
+    heartbeat(): Promise<{
+        status: string;
+        timestamp: number;
+    }>;
+    /**
+     * Claim a job from the queue
+     */
+    claimJob(): Promise<SecureJob | null>;
+    /**
+     * Submit job result
+     */
+    submitJobResult(result: JobResult): Promise<void>;
+    /**
+     * Queue a job for processing
+     */
+    queueJob(type: string, params: Record<string, unknown>, targetPublicKey?: string): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Decrypt job params received from backend
+     */
+    private decryptJobParams;
+    /**
+     * Encrypt job result for sending to backend
+     */
+    private encryptJobResult;
+    /**
+     * Encrypt job params for a specific target edge node
+     */
+    private encryptJobParamsForTarget;
+    /**
+     * Check if client is authenticated
+     */
+    private requireAuth;
+    /**
+     * Get current authentication status
+     */
+    getAuthStatus(): {
+        authenticated: boolean;
+        edgeNodeId?: string;
+        subscriberId?: string;
+        expiresAt?: number;
+        scopes?: string[];
+    };
+}
+/**
+ * Factory function to create secure edge client from config
+ */
+declare function createSecureEdgeClient(client: RainfallClient, options: {
+    edgeNodeId: string;
+    edgeNodeSecret: string;
+    keysPath: string;
+    backendSecret?: string;
+}): Promise<SecureEdgeClient>;
 
 /**
  * Rainfall SDK - Official SDK for Rainfall API
@@ -26,4 +273,4 @@ export { A as AI, a as ApiError, b as ApiResponse, c as Articles, d as Authentic
 
 declare const VERSION = "0.1.0";
 
-export { VERSION };
+export { type ACLCheck, type ACLResult, type EdgeNodeJWT, EdgeNodeSecurity, type EncryptedPayload, type JWTPayload, type JobResult, type KeyPair, RainfallClient, SecureEdgeClient, type SecureEdgeConfig, type SecureJob, VERSION, createEdgeNodeSecurity, createSecureEdgeClient };