@openserv-labs/client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenServ Labs
+
+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,646 @@
+# OpenServ Platform Client
+
+[![npm version](https://badge.fury.io/js/@openserv-labs%2Fclient.svg)](https://www.npmjs.com/package/@openserv-labs/client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+
+A TypeScript client for interacting with the OpenServ Platform API. Manage agents, workflows, tasks, and triggers programmatically.
+
+> **Note**: This is the platform client for API operations. If you want to build AI agents, see [@openserv-labs/sdk](https://github.com/openserv-labs/sdk).
+
+## Installation
+
+```bash
+npm install @openserv-labs/client
+```
+
+## Quick Start
+
+```typescript
+import { PlatformClient } from '@openserv-labs/client'
+
+const client = new PlatformClient({
+  apiKey: process.env.OPENSERV_USER_API_KEY
+})
+
+// List all agents
+const agents = await client.agents.list()
+
+// Create a workflow
+const workflow = await client.workflows.create({
+  name: 'My Workflow',
+  goal: 'Process data automatically',
+  agentIds: [123, 456]
+})
+```
+
+## Authentication
+
+### API Key Authentication
+
+```typescript
+const client = new PlatformClient({
+  apiKey: 'your-api-key'
+})
+```
+
+Or set the `OPENSERV_USER_API_KEY` environment variable:
+
+```typescript
+const client = new PlatformClient() // Uses OPENSERV_USER_API_KEY env var
+```
+
+### Wallet Authentication (SIWE)
+
+Authenticate using an Ethereum wallet (EIP-4361):
+
+```typescript
+const client = new PlatformClient()
+const apiKey = await client.authenticate(process.env.WALLET_PRIVATE_KEY)
+```
+
+## API Reference
+
+### Agents
+
+```typescript
+// List all agents
+const agents = await client.agents.list()
+
+// Get agent by ID
+const agent = await client.agents.get({ id: 123 })
+
+// Search your own agents by name/description
+const myAgents = await client.agents.searchOwned({ query: 'my-agent' })
+
+// Search all marketplace agents (semantic search)
+const marketplaceResults = await client.agents.listMarketplace({ search: 'data processing' })
+
+// Create an agent
+// endpoint_url is optional when using @openserv-labs/sdk v2.0.0+ (auto-set by run())
+const agent = await client.agents.create({
+  name: 'My Agent',
+  capabilities_description: 'Agent capabilities description',
+  endpoint_url: 'https://my-agent.example.com' // Optional for dev, required for production
+})
+
+// Update an agent
+await client.agents.update({
+  id: 123,
+  name: 'Updated Name',
+  capabilities_description: 'Updated description',
+  endpoint_url: 'https://new-endpoint.example.com' // Only if changing the endpoint
+})
+
+// Delete an agent
+await client.agents.delete({ id: 123 })
+
+// Get agent API key
+const apiKey = await client.agents.getApiKey({ id: 123 })
+
+// Generate and save auth token for agent security
+const { authToken, authTokenHash } = await client.agents.generateAuthToken()
+await client.agents.saveAuthToken({ id: 123, authTokenHash })
+
+// List marketplace agents (public agents from other developers)
+const marketplace = await client.agents.listMarketplace({
+  search: 'data processing', // Optional search query
+  page: 1,
+  pageSize: 20,
+  showPrivateAgents: true // Include your own private agents
+})
+
+console.log(`Found ${marketplace.total} agents`)
+for (const agent of marketplace.items) {
+  console.log(`${agent.name} by ${agent.author_name}`)
+}
+```
+
+### Workflows
+
+```typescript
+// Create a workflow
+const workflow = await client.workflows.create({
+  name: 'Data Pipeline',
+  goal: 'Process and analyze data',
+  agentIds: [123, 456]
+})
+
+// Get a workflow
+const workflow = await client.workflows.get({ id: 789 })
+
+// List all workflows
+const workflows = await client.workflows.list()
+
+// Update a workflow
+await client.workflows.update({
+  id: 789,
+  name: 'Updated Pipeline',
+  goal: 'New goal'
+})
+
+// Delete a workflow
+await client.workflows.delete({ id: 789 })
+
+// Set workflow to running state
+await client.workflows.setRunning({ id: 789 })
+
+// Sync workflow configuration
+await client.workflows.sync({
+  id: 789,
+  triggers: [{ name: 'webhook', type: 'webhook' }],
+  tasks: [{ name: 'process', agentId: 123, description: 'Process data' }],
+  edges: [{ from: 'trigger:webhook', to: 'task:process' }]
+})
+```
+
+### Tasks
+
+```typescript
+// Create a task
+const task = await client.tasks.create({
+  workflowId: 789,
+  agentId: 123,
+  description: 'Process the data',
+  body: 'Additional task details',
+  dependencies: [456] // Optional task dependencies
+})
+
+// Get a task
+const task = await client.tasks.get({ workflowId: 789, id: 1 })
+
+// List tasks in a workflow
+const tasks = await client.tasks.list({ workflowId: 789 })
+
+// Update a task
+await client.tasks.update({
+  workflowId: 789,
+  id: 1,
+  description: 'Updated description',
+  status: 'in-progress'
+})
+
+// Delete a task
+await client.tasks.delete({ workflowId: 789, id: 1 })
+```
+
+### Triggers
+
+```typescript
+import { triggers, triggerConfigToProps } from '@openserv-labs/client'
+
+// Create a webhook trigger
+const trigger = await client.triggers.create({
+  workflowId: 789,
+  name: 'My Webhook',
+  type: 'webhook',
+  props: triggerConfigToProps(
+    triggers.webhook({
+      waitForCompletion: true,
+      timeout: 300
+    })
+  )
+})
+
+// Create a cron trigger
+const cronTrigger = await client.triggers.create({
+  workflowId: 789,
+  name: 'Daily Job',
+  type: 'cron',
+  props: triggerConfigToProps(
+    triggers.cron({
+      schedule: '0 9 * * *',
+      timezone: 'America/New_York'
+    })
+  )
+})
+
+// Create an x402 (paid) trigger
+const paidTrigger = await client.triggers.create({
+  workflowId: 789,
+  name: 'Paid API',
+  type: 'x402',
+  props: triggerConfigToProps(
+    triggers.x402({
+      price: '0.01',
+      input: {
+        query: { type: 'string', description: 'Search query' }
+      }
+    })
+  )
+})
+
+// Get a trigger
+const trigger = await client.triggers.get({ workflowId: 789, id: 'trigger-id' })
+
+// List triggers
+const allTriggers = await client.triggers.list({ workflowId: 789 })
+
+// Update a trigger
+await client.triggers.update({
+  workflowId: 789,
+  id: 'trigger-id',
+  name: 'Updated Name',
+  props: { timeout: 600 }
+})
+
+// Activate a trigger
+await client.triggers.activate({ workflowId: 789, id: 'trigger-id' })
+
+// Fire a trigger manually
+await client.triggers.fire({
+  workflowId: 789,
+  id: 'trigger-id',
+  payload: { data: 'test' }
+})
+
+// Delete a trigger
+await client.triggers.delete({ workflowId: 789, id: 'trigger-id' })
+```
+
+### Payments (x402)
+
+Pay for and execute x402-protected workflows programmatically.
+
+> **Note**: Set `WALLET_PRIVATE_KEY` in your environment. The client uses it automatically for x402 payments using the [x402 protocol](https://www.x402.org/).
+
+```typescript
+// Pay and execute an x402 workflow - just set WALLET_PRIVATE_KEY env var
+const client = new PlatformClient()
+const result = await client.payments.payWorkflow({
+  triggerUrl: 'https://api.openserv.ai/webhooks/x402/trigger/...',
+  input: { prompt: 'Generate a summary' }
+})
+
+console.log(`Response: ${JSON.stringify(result.response)}`)
+```
+
+The `payWorkflow` method handles the entire x402 payment flow automatically:
+
+1. Creates a payment-enabled fetch wrapper using your wallet
+2. Makes a request to the trigger URL
+3. Automatically handles the 402 Payment Required response
+4. Signs and submits the USDC payment on Base
+5. Retries the request with payment proof
+6. Returns the workflow response
+
+#### Discover x402 services
+
+```typescript
+// List available paid services on the platform
+const services = await client.payments.discoverServices()
+
+for (const service of services) {
+  console.log(`${service.name}: $${service.x402Pricing}`)
+  console.log(`URL: ${service.webhookUrl}`)
+  console.log(`By: ${service.ownerDisplayName}`)
+}
+```
+
+#### Get trigger preflight info
+
+```typescript
+// Get pricing and input schema before paying
+const preflight = await client.payments.getTriggerPreflight({
+  token: 'abc123def456' // Extract from webhook URL
+})
+
+console.log(`Price: ${preflight.x402Pricing}`)
+console.log(`Pay to: ${preflight.x402WalletAddress}`)
+console.log(`Input schema: ${JSON.stringify(preflight.jsonSchema)}`)
+```
+
+### Integrations
+
+Manage integration connections for triggers and external services.
+
+```typescript
+// List all integration connections for your account
+const connections = await client.integrations.listConnections()
+
+for (const conn of connections) {
+  console.log(`${conn.integrationDisplayName} (${conn.integrationType})`)
+  console.log(`  ID: ${conn.id}`)
+  console.log(`  Integration: ${conn.integrationName}`)
+}
+
+// Create a custom integration connection
+await client.integrations.connect({
+  identifier: 'webhook-trigger',
+  props: {} // Optional properties
+})
+
+// Get or create a connection (useful for trigger setup)
+const connectionId = await client.integrations.getOrCreateConnection('webhook-trigger')
+```
+
+### Web3 / USDC Top-up
+
+Add credits to your account by paying with USDC.
+
+> **Note**: Set `WALLET_PRIVATE_KEY` in your environment. The client uses it automatically for payments and SIWE authentication.
+
+```typescript
+// Simple one-liner - just set WALLET_PRIVATE_KEY env var
+const client = new PlatformClient()
+const result = await client.web3.topUp({ amountUsd: 10 })
+
+console.log(`Transaction: ${result.txHash}`)
+console.log(`Added ${result.creditsAdded} credits`)
+console.log(`USDC spent: ${result.usdcAmount}`)
+console.log(`Network: ${result.network}`)
+```
+
+The `topUp` method handles the entire flow:
+
+1. Fetches USDC configuration from the platform
+2. Checks your USDC balance
+3. Sends USDC to the platform's receiver address
+4. Waits for transaction confirmation
+5. Signs a verification message
+6. Verifies and adds credits to your account
+
+#### Lower-level methods
+
+For more control, use the individual methods:
+
+```typescript
+// Get USDC top-up configuration
+const config = await client.web3.getUsdcTopupConfig()
+console.log(`Send USDC to ${config.receiverAddress} on ${config.network}`)
+console.log(`Chain ID: ${config.chainId}`)
+console.log(`USDC Contract: ${config.usdcContractAddress}`)
+console.log(`Rate: 1 USDC = ${config.rateUsdcToCredits} credits`)
+
+// After sending USDC manually, verify the transaction
+const result = await client.web3.verifyUsdcTransaction({
+  txHash: '0xabc123...',
+  payerAddress: '0xYourWallet...', // Required for non-wallet-authenticated users
+  signature: '0x...' // Sign "Verify USDC top-up: {txHash}"
+})
+console.log(`Added ${result.creditsAdded} credits`)
+```
+
+## Workflow Object
+
+When you retrieve a workflow, you get a `Workflow` object with helper methods:
+
+```typescript
+const workflow = await client.workflows.get({ id: 789 })
+
+// Access workflow properties
+console.log(workflow.id, workflow.name, workflow.goal)
+console.log(workflow.status) // 'draft', 'running', etc.
+console.log(workflow.triggers) // Array of triggers
+console.log(workflow.tasks) // Array of tasks
+console.log(workflow.edges) // Graph edges
+console.log(workflow.agents) // Assigned agents
+
+// Sync configuration declaratively
+await workflow.sync({
+  triggers: [{ name: 'api', type: 'webhook' }],
+  tasks: [{ name: 'work', agentId: 123, description: 'Do work' }],
+  edges: [{ from: 'trigger:api', to: 'task:work' }]
+})
+
+// Start the workflow
+await workflow.setRunning()
+```
+
+## Provision API
+
+The `provision()` function provides a simple way to deploy agents and workflows in one call. It's designed to work seamlessly with [@openserv-labs/sdk](https://github.com/openserv-labs/sdk) for building AI agents.
+
+### About `endpointUrl`
+
+The `endpointUrl` parameter is **optional** when using `@openserv-labs/sdk` v2.0.0+. Here's why:
+
+- **Development**: When you call `run(agent)` from the SDK, it automatically registers your agent with the OpenServ agents proxy (`https://agents-proxy.openserv.ai`), which tunnels requests to your local machine. No `endpointUrl` needed.
+- **Production**: If you're deploying your agent to a publicly accessible URL (e.g., your own server, cloud function, or container), provide the `endpointUrl` so the platform knows where to reach your agent.
+
+### Development Example (No endpointUrl)
+
+When developing locally with the SDK, you can omit `endpointUrl`:
+
+```typescript
+import { provision, triggers } from '@openserv-labs/client'
+import { Agent, run } from '@openserv-labs/sdk'
+
+// Step 1: Provision the agent and workflow (no endpointUrl needed for dev)
+const result = await provision({
+  agent: {
+    name: 'my-agent',
+    description: 'Handles API requests'
+  },
+  workflow: {
+    name: 'api-workflow',
+    trigger: triggers.webhook({
+      input: { query: { type: 'string' } },
+      waitForCompletion: true
+    }),
+    task: {
+      description: 'Process incoming API requests and return results'
+    }
+  }
+})
+
+console.log(result.agentId) // Created agent ID
+console.log(result.apiKey) // Agent API key
+console.log(result.apiEndpoint) // Webhook URL to call
+
+// Step 2: Create and run the agent (SDK auto-updates endpoint to agents-proxy)
+const agent = new Agent({
+  systemPrompt: 'You are a helpful assistant.'
+})
+
+run(agent) // Automatically connects to agents-proxy.openserv.ai
+```
+
+### Production Example (With endpointUrl)
+
+When deploying to production with a publicly accessible URL:
+
+```typescript
+import { provision, triggers } from '@openserv-labs/client'
+
+const result = await provision({
+  agent: {
+    name: 'my-agent',
+    description: 'Handles API requests',
+    endpointUrl: 'https://my-agent.example.com' // Your production URL
+  },
+  workflow: {
+    name: 'api-workflow',
+    trigger: triggers.webhook({
+      input: { query: { type: 'string' } },
+      waitForCompletion: true
+    }),
+    task: {
+      description: 'Process incoming API requests and return results'
+    }
+  }
+})
+
+console.log(result.apiEndpoint) // Webhook URL to call
+```
+
+### More Examples
+
+```typescript
+import { provision, triggers, isProvisioned, getProvisionedInfo, clearProvisionedState } from '@openserv-labs/client'
+
+// Provision with x402 (paid) trigger
+const paidResult = await provision({
+  agent: {
+    name: 'paid-agent',
+    description: 'Premium AI service',
+    endpointUrl: 'https://paid-agent.example.com' // Required for production
+  },
+  workflow: {
+    name: 'paid-workflow',
+    trigger: triggers.x402({
+      price: '0.01',
+      input: { prompt: { type: 'string' } }
+    }),
+    task: {
+      description: 'Process paid requests and deliver premium results'
+    }
+  }
+})
+
+console.log(paidResult.paywallUrl) // Public paywall URL for payments
+
+// Check if already provisioned (uses .openserv.json state file)
+if (isProvisioned('my-agent', 'api-workflow')) {
+  const info = getProvisionedInfo('my-agent', 'api-workflow')
+  console.log('Already provisioned:', info)
+}
+
+// Clear provisioned state (does not delete from platform)
+clearProvisionedState()
+```
+
+### Provision with Cron Trigger
+
+```typescript
+const cronResult = await provision({
+  agent: {
+    name: 'scheduled-agent',
+    description: 'Runs scheduled tasks',
+    endpointUrl: 'https://scheduled-agent.example.com' // Required for production
+  },
+  workflow: {
+    name: 'daily-job',
+    trigger: triggers.cron({
+      schedule: '0 9 * * *', // Daily at 9 AM
+      timezone: 'America/New_York'
+    }),
+    task: {
+      description: 'Execute daily data processing and send reports'
+    }
+  }
+})
+```
+
+## Trigger Factory Functions
+
+Use the `triggers` factory for type-safe trigger configuration:
+
+```typescript
+import { triggers, triggerConfigToProps } from '@openserv-labs/client'
+
+// Webhook trigger
+triggers.webhook({
+  input: { message: { type: 'string' } },
+  waitForCompletion: true,
+  timeout: 180
+})
+
+// Cron trigger
+triggers.cron({
+  schedule: '0 */6 * * *', // Every 6 hours
+  timezone: 'UTC'
+})
+
+// x402 (paid) trigger
+triggers.x402({
+  price: '0.05',
+  input: { prompt: { type: 'string', description: 'User prompt' } },
+  timeout: 300,
+  walletAddress: '0x...'
+})
+
+// Manual trigger
+triggers.manual()
+```
+
+## Environment Variables
+
+| Variable                | Description                           | Required                     |
+| ----------------------- | ------------------------------------- | ---------------------------- |
+| `OPENSERV_USER_API_KEY` | Your OpenServ user API key            | For most API operations      |
+| `OPENSERV_API_URL`      | Custom API URL (for testing)          | No                           |
+| `WALLET_PRIVATE_KEY`    | Wallet private key for blockchain ops | For top-up and x402 payments |
+
+**Authentication options:**
+
+- Use `OPENSERV_USER_API_KEY` for API key authentication
+- Use `WALLET_PRIVATE_KEY` for wallet-based (SIWE) authentication
+
+**For Web3 operations:** Just set `WALLET_PRIVATE_KEY` - the client automatically uses it for blockchain transactions and handles SIWE authentication. No need to pass it explicitly in API calls.
+
+## Types
+
+All types are exported for TypeScript users:
+
+```typescript
+import type {
+  // Domain types
+  Agent,
+  Workflow,
+  WorkflowConfig,
+  WorkflowData,
+  Task,
+  Trigger,
+  TriggerDefinition,
+  TaskDefinition,
+  EdgeDefinition,
+  Edge,
+  // Marketplace types
+  MarketplaceAgent,
+  MarketplaceAgentsResponse,
+  Category,
+  // Integration types
+  IntegrationConnection,
+  // Trigger config types
+  TriggerConfig,
+  WebhookTriggerConfig,
+  X402TriggerConfig,
+  CronTriggerConfig,
+  ManualTriggerConfig,
+  InputSchema,
+  InputSchemaProperty,
+  // API response types
+  PaginatedResponse,
+  IdResponse,
+  ApiKeyResponse,
+  NonceResponse,
+  VerifyResponse,
+  // Web3 types
+  UsdcTopupConfig,
+  UsdcTopupResult,
+  UsdcVerifyRequest,
+  UsdcVerifyResponse,
+  // x402 Payment types
+  X402PaymentRequest,
+  X402PaymentResult,
+  // Provision types
+  ProvisionConfig,
+  ProvisionResult,
+  Logger
+} from '@openserv-labs/client'
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.