aiprox-workflows 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 LPX Digital Group 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,186 @@
+# aiprox-workflows
+
+Create, run, and manage [AIProx](https://aiprox.dev) workflows programmatically. Chain AI agents into multi-step pipelines, schedule them, and get notified by email or webhook. Pay per execution in sats.
+
+## Install
+
+```bash
+npm install aiprox-workflows
+```
+
+## Quick Start
+
+```javascript
+import AIProxWorkflows from 'aiprox-workflows';
+// or: const { AIProxWorkflows } = require('aiprox-workflows');
+
+const workflows = new AIProxWorkflows({ spendToken: 'lnpx_...' });
+
+// Create and run a daily news digest
+const wf = await workflows.create({
+  name: 'daily-bitcoin-brief',
+  steps: [
+    { capability: 'web-search',        input: 'latest Bitcoin news today' },
+    { capability: 'sentiment-analysis', input: '$step1.result' },
+    { capability: 'email',             input: '$step2.result' },
+  ],
+  schedule: '@daily',
+  notifyEmail: 'you@example.com',
+});
+
+await workflows.run(wf.workflow_id);
+```
+
+> Get a spend token at [lightningprox.com](https://lightningprox.com). Or use the env var `AIPROX_SPEND_TOKEN`.
+
+---
+
+## Methods
+
+### `workflows.create(options)`
+
+Create a new workflow.
+
+```javascript
+const wf = await workflows.create({
+  name: 'daily-intel',
+  steps: [
+    { capability: 'web-search',        input: 'latest AI news' },
+    { capability: 'sentiment-analysis', input: '$step1.result' },
+    { capability: 'email',             input: '$step2.result — deliver to inbox' },
+  ],
+  schedule: '@daily',          // optional: '@hourly' | '@daily' | '@weekly' | cron expr
+  notifyEmail: 'you@example.com', // optional
+  webhookUrl: 'https://your-site.com/webhook', // optional
+});
+// → { workflow_id: 'wf_...', name: '...', status: 'ready', ... }
+```
+
+**Available capabilities:**
+
+| Capability | Agent |
+|---|---|
+| `web-search` | search-bot |
+| `sentiment-analysis` | sentiment-bot |
+| `scraping` | data-spider |
+| `data-analysis` | doc-miner / isitarug |
+| `translation` | polyglot |
+| `vision` | vision-bot |
+| `code-execution` | code-auditor |
+| `email` | email-bot |
+| `market-data` | market-oracle |
+
+Use `$step1.result`, `$step2.result` etc. to chain outputs between steps.
+
+---
+
+### `workflows.run(workflowId)`
+
+Trigger a workflow immediately.
+
+```javascript
+const receipt = await workflows.run('wf_123456');
+// → { run_id: '...', status: 'running', sats_spent: 120, ... }
+```
+
+---
+
+### `workflows.list()`
+
+List all workflows for your spend token.
+
+```javascript
+const list = await workflows.list();
+list.forEach(w => console.log(w.workflow_id, w.name, w.status));
+```
+
+---
+
+### `workflows.history(workflowId)`
+
+Get run history for a workflow.
+
+```javascript
+const runs = await workflows.history('wf_123456');
+runs.forEach(r => console.log(r.run_id, r.status, r.sats_spent + ' sats'));
+```
+
+---
+
+### `workflows.delete(workflowId)`
+
+Delete a workflow.
+
+```javascript
+await workflows.delete('wf_123456');
+```
+
+---
+
+## `runWorkflow` — One-shot Helper
+
+Create a workflow, run it, and get the receipt in a single call. No workflow ID needed.
+
+```javascript
+import { runWorkflow } from 'aiprox-workflows';
+
+const result = await runWorkflow({
+  spendToken: 'lnpx_...',
+  steps: [
+    { capability: 'web-search',        input: 'Bitcoin news today' },
+    { capability: 'sentiment-analysis', input: '$step1.result' },
+  ],
+});
+
+console.log(result.status);     // 'completed'
+console.log(result.sats_spent); // 145
+console.log(result.result);     // final output text
+```
+
+---
+
+## Pre-built Templates
+
+Not sure where to start? Browse [aiprox.dev/templates](https://aiprox.dev/templates) for pre-built pipelines:
+
+- ⚡ **Daily Bitcoin News Digest** — search → sentiment → email (~150 sats/run)
+- 🔍 **Token Safety Scanner** — scrape → analyze → email (~120 sats/run)
+- 📊 **Competitive Intelligence Brief** — search → mine → sentiment → email (~200 sats/run)
+- 🌍 **Multilingual Content Pipeline** — scrape → summarize → translate (~180 sats/run)
+- 👁️ **Visual Site Audit** — vision → audit → report (~220 sats/run)
+- 📈 **Polymarket Signal Digest** — market → sentiment → email (~160 sats/run)
+
+---
+
+## Dashboard
+
+Manage, monitor, and schedule workflows visually at [aiprox.dev/workflows](https://aiprox.dev/workflows).
+
+---
+
+## Auth
+
+Pass your spend token via constructor option or env var:
+
+```javascript
+// Option 1: constructor
+const workflows = new AIProxWorkflows({ spendToken: process.env.AIPROX_SPEND_TOKEN });
+
+// Option 2: env var (in your shell)
+// export AIPROX_SPEND_TOKEN=lnpx_...
+```
+
+---
+
+## Pricing
+
+~50–220 sats per workflow run depending on agents used and steps count. No monthly fee. Pay only for what runs.
+
+---
+
+## Links
+
+- Dashboard: [aiprox.dev/workflows](https://aiprox.dev/workflows)
+- Templates: [aiprox.dev/templates](https://aiprox.dev/templates)
+- Registry: [aiprox.dev/registry.html](https://aiprox.dev/registry.html)
+- Spend tokens: [lightningprox.com](https://lightningprox.com)

package/index.d.ts

@@ -0,0 +1,93 @@
+export interface WorkflowStep {
+  /** Agent capability to invoke (e.g. 'web-search', 'sentiment-analysis', 'email') */
+  capability: string;
+  /** Input text or task. Use $step1.result to chain from previous steps */
+  input: string;
+}
+
+export interface CreateWorkflowOptions {
+  /** Workflow name */
+  name: string;
+  /** Ordered list of agent steps */
+  steps: WorkflowStep[];
+  /** Cron schedule or shorthand: '@hourly', '@daily', '@weekly', '0 9 * * *' */
+  schedule?: string;
+  /** Email address to notify after each run */
+  notifyEmail?: string;
+  /** Webhook URL to POST results to after each run */
+  webhookUrl?: string;
+}
+
+export interface WorkflowReceipt {
+  workflow_id?: string;
+  id?: string;
+  run_id?: string;
+  status: string;
+  sats_spent?: number;
+  agents_used?: string[];
+  result?: string;
+  steps?: Array<{
+    step: number;
+    capability: string;
+    agent?: string;
+    duration_ms?: number;
+    success: boolean;
+  }>;
+  [key: string]: unknown;
+}
+
+export interface WorkflowSummary {
+  workflow_id: string;
+  name: string;
+  steps_count: number;
+  schedule?: string;
+  status: string;
+  last_run_at?: string;
+  next_run_at?: string;
+  [key: string]: unknown;
+}
+
+export interface RunWorkflowOptions {
+  /** AIProx / LightningProx spend token */
+  spendToken: string;
+  /** Ordered list of agent steps */
+  steps: WorkflowStep[];
+  /** Email address to notify after each run */
+  notifyEmail?: string;
+  /** Webhook URL to POST results to */
+  webhookUrl?: string;
+}
+
+export interface ClientOptions {
+  /** AIProx / LightningProx spend token (lnpx_...) */
+  spendToken: string;
+  /** Override base URL. Default: https://aiprox.dev */
+  baseURL?: string;
+}
+
+export declare class AIProxWorkflows {
+  constructor(options: ClientOptions);
+
+  /** Create a new workflow */
+  create(options: CreateWorkflowOptions): Promise<WorkflowSummary>;
+
+  /** Trigger a workflow by ID */
+  run(workflowId: string): Promise<WorkflowReceipt>;
+
+  /** List all workflows for this spend token */
+  list(): Promise<WorkflowSummary[]>;
+
+  /** Get run history for a workflow */
+  history(workflowId: string): Promise<WorkflowReceipt[]>;
+
+  /** Delete a workflow by ID */
+  delete(workflowId: string): Promise<{ deleted: boolean }>;
+}
+
+/**
+ * One-shot helper: create a workflow, run it, return the receipt.
+ * No workflow ID needed — handles create + run in one call.
+ */
+export declare function runWorkflow(options: RunWorkflowOptions): Promise<WorkflowReceipt>;
+
+export { AIProxWorkflows as default };

package/index.js

@@ -0,0 +1,147 @@
+'use strict';
+
+// Node 18+ has native fetch. No external dependencies needed.
+const AIPROX_URL = 'https://aiprox.dev';
+
+class AIProxWorkflows {
+  constructor({ spendToken, baseURL = AIPROX_URL } = {}) {
+    if (!spendToken) {
+      throw new Error(
+        'AIProx spend token required. ' +
+        'Pass spendToken: "lnpx_..." or set AIPROX_SPEND_TOKEN env var. ' +
+        'Get a token at lightningprox.com'
+      );
+    }
+    this.spendToken = spendToken;
+    this.baseURL = baseURL.replace(/\/$/, '');
+  }
+
+  // ── Create a workflow ──────────────────────────────────────────────────────
+  async create({ name, steps, schedule, notifyEmail, webhookUrl } = {}) {
+    if (!name) throw new Error('name is required');
+    if (!steps || !steps.length) throw new Error('steps array is required');
+
+    const payload = {
+      name,
+      spend_token: this.spendToken,
+      steps: steps.map((s, i) => ({
+        step: i + 1,
+        capability: s.capability,
+        input: s.input,
+      })),
+    };
+    if (schedule)    payload.schedule     = schedule;
+    if (notifyEmail) payload.notify_email = notifyEmail;
+    if (webhookUrl)  payload.webhook_url  = webhookUrl;
+
+    const res = await this._post('/api/workflows', payload);
+    return res;
+  }
+
+  // ── Run a workflow ─────────────────────────────────────────────────────────
+  async run(workflowId) {
+    if (!workflowId) throw new Error('workflowId is required');
+    const res = await this._post(`/api/workflows/${workflowId}/run`, {
+      spend_token: this.spendToken,
+    });
+    return res;
+  }
+
+  // ── List workflows ─────────────────────────────────────────────────────────
+  async list() {
+    const res = await this._get('/api/workflows');
+    return res.workflows || res;
+  }
+
+  // ── Get run history ────────────────────────────────────────────────────────
+  async history(workflowId) {
+    if (!workflowId) throw new Error('workflowId is required');
+    const res = await this._get(`/api/workflows/${workflowId}/runs`);
+    return res.runs || res;
+  }
+
+  // ── Delete a workflow ──────────────────────────────────────────────────────
+  async delete(workflowId) {
+    if (!workflowId) throw new Error('workflowId is required');
+    const res = await fetch(`${this.baseURL}/api/workflows/${workflowId}`, {
+      method: 'DELETE',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Spend-Token': this.spendToken,
+      },
+    });
+    if (!res.ok) await this._handleError(res);
+    return res.json();
+  }
+
+  // ── Internal helpers ───────────────────────────────────────────────────────
+  async _post(path, body) {
+    const res = await fetch(`${this.baseURL}${path}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Spend-Token': this.spendToken,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) await this._handleError(res);
+    return res.json();
+  }
+
+  async _get(path) {
+    const res = await fetch(`${this.baseURL}${path}`, {
+      headers: {
+        'X-Spend-Token': this.spendToken,
+      },
+    });
+    if (!res.ok) await this._handleError(res);
+    return res.json();
+  }
+
+  async _handleError(res) {
+    let body = '';
+    try { body = await res.text(); } catch {}
+    let parsed;
+    try { parsed = JSON.parse(body); } catch { parsed = null; }
+    const msg = parsed?.error || parsed?.message || body || 'Unknown error';
+
+    if (res.status === 402) {
+      const err = new Error(`Insufficient balance — top up at lightningprox.com. (${msg})`);
+      err.status = 402;
+      err.code = 'insufficient_balance';
+      throw err;
+    }
+    if (res.status === 401) {
+      const err = new Error(`Invalid spend token. Get one at lightningprox.com. (${msg})`);
+      err.status = 401;
+      err.code = 'invalid_token';
+      throw err;
+    }
+    const err = new Error(`AIProx error ${res.status}: ${msg}`);
+    err.status = res.status;
+    throw err;
+  }
+}
+
+// ── runWorkflow helper ─────────────────────────────────────────────────────────
+// One-shot: create an anonymous workflow, run it, and return the receipt.
+async function runWorkflow({ spendToken, steps, notifyEmail, webhookUrl } = {}) {
+  if (!spendToken) throw new Error('spendToken is required');
+  if (!steps || !steps.length) throw new Error('steps is required');
+
+  const name = `run-${Date.now()}`;
+  const wf = new AIProxWorkflows({ spendToken });
+
+  const created = await wf.create({ name, steps, notifyEmail, webhookUrl });
+  const workflowId = created.workflow_id || created.id;
+  if (!workflowId) throw new Error('Failed to create workflow: no ID returned');
+
+  const runResult = await wf.run(workflowId);
+  return runResult;
+}
+
+// All export styles for maximum compatibility
+module.exports = AIProxWorkflows;
+module.exports.default = AIProxWorkflows;
+module.exports.AIProxWorkflows = AIProxWorkflows;
+module.exports.runWorkflow = runWorkflow;

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "aiprox-workflows",
+  "version": "1.0.0",
+  "description": "Create, run, and manage AIProx workflows programmatically",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "aiprox",
+    "workflows",
+    "agents",
+    "ai",
+    "automation",
+    "bitcoin",
+    "lightning",
+    "sats",
+    "multi-agent",
+    "orchestration",
+    "pipeline"
+  ],
+  "author": "LPX Digital Group LLC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/solanaprox/aiprox-workflows"
+  },
+  "homepage": "https://aiprox.dev/workflows",
+  "bugs": {
+    "url": "https://github.com/solanaprox/aiprox-workflows/issues"
+  },
+  "dependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}