services-as-software 0.1.0 → 2.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> services-as-software@2.0.1 build /Users/nathanclevenger/projects/primitives.org.ai/packages/services-as-software
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# services-as-software
+
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-database@2.0.1
+  - ai-functions@2.0.1
+  - digital-workers@2.0.1

package/README.md

@@ -1,302 +1,312 @@
 # services-as-software
 
-Define services with objectives, key results, and various pricing models for the agentic services architecture.
+Primitives for building AI-powered services that operate as software. Services are a superset of digital-workers with a payment/business overlay, capable of crossing company/business boundaries.
 
 ## Installation
 
 ```bash
-npm install services-as-software
-# or
-yarn add services-as-software
-# or
 pnpm add services-as-software
 ```
 
-## Overview
+## Quick Start
 
-The `services-as-software` package enables defining services with clear objectives, measurable key results, and support for multiple pricing models. It allows Functions, Workflows, and Agents to be offered as Services with appropriate pricing and business models.
-
-## Usage
+```typescript
+import { Service, POST, GET } from 'services-as-software'
 
-### Basic Service Definition
+// Define a service
+const translationService = Service({
+  name: 'translation-service',
+  version: '1.0.0',
+  description: 'AI-powered translation service',
 
-```typescript
-import { Service } from 'services-as-software'
-
-const myService = Service({
-  name: 'Content Generation Service',
-  description: 'AI-powered content generation for marketing teams',
-  objective: {
-    description: 'Provide high-quality content generation that increases marketing efficiency',
-    keyResults: [],
-  },
-  keyResults: [
-    {
-      description: 'Reduce content creation time',
-      target: 50,
-      currentValue: 0,
-      unit: 'percent',
-    },
-    {
-      description: 'Maintain content quality score',
-      target: 8,
-      currentValue: 0,
-      unit: 'rating',
-    },
-  ],
+  // Pricing configuration
   pricing: {
-    model: 'cost-based',
-    costBase: 10,
-    fixedCosts: 5,
-    variableCosts: 2,
+    model: 'per-use',
+    pricePerUnit: 0.01,
+    currency: 'USD',
   },
-  implementation: {
-    type: 'function',
-    id: 'content-generator-123',
-  },
-})
 
-// Register the service
-const registeredService = await myService.register()
-
-// Calculate price
-const price = myService.calculatePrice({ quantity: 5 })
-
-// Track progress towards key results
-myService.trackProgress({
-  'Reduce content creation time': 30,
-  'Maintain content quality score': 9,
+  // Service endpoints
+  endpoints: [
+    POST({
+      name: 'translate',
+      path: '/translate',
+      handler: async (input) => {
+        return {
+          translatedText: `Translated: ${input.text}`,
+          confidence: 0.95,
+        }
+      },
+    }),
+  ],
 })
 
-// Check if objective is achieved
-const achieved = myService.isObjectiveAchieved()
+// Use the service
+const result = await translationService.call('translate', {
+  text: 'Hello, world!',
+  to: 'es',
+})
 ```
 
-### Pricing Models
+## Core Primitives
 
-The package supports four pricing models:
+### Service Creation
 
-#### 1. Cost-based Pricing
+- **`Service(definition)`** - Define a service with endpoints, pricing, and business logic
+- **`Endpoint(config)`** - Create a service endpoint
+- **`POST()`, `GET()`, `PUT()`, `DELETE()`, `PATCH()`** - HTTP method helpers
 
-```typescript
-const service = Service({
-  // ...other properties
-  pricing: {
-    model: 'cost-based',
-    costBase: 100,
-    fixedCosts: 50,
-    variableCosts: 10,
-  },
-})
-
-// Calculate price for 5 units
-const price = service.calculatePrice({ quantity: 5 }) // 200 (100 + 50 + 10*5)
-```
+### Client & Providers
 
-#### 2. Margin-based Pricing
+- **`Client(config)`** - Connect to a remote service
+- **`Provider(config)`** - Manage multiple services
+- **`providers.aws()`, `providers.gcp()`, `providers.azure()`** - Pre-configured cloud providers
 
-```typescript
-const service = Service({
-  // ...other properties
-  pricing: {
-    model: 'margin-based',
-    costBase: 100,
-    marginPercentage: 20,
-  },
-})
+### Service Operations
 
-// Calculate price for 2 units
-const price = service.calculatePrice({ quantity: 2 }) // 240 (100*2 + 20% margin)
-```
+- **`ask()`** - Ask a question helper
+- **`deliver()`** - Deliver results helper
+- **`do()`** - Execute a task helper
+- **`every()`** - Scheduled recurring tasks helper
+- **`generate()`** - Generate content helper
+- **`is()`** - Type checking/validation helper
+- **`notify()`** - Send notifications helper
+- **`on()`** - Event handlers helper
+- **`order()`** - Place an order helper
+- **`queue()`** - Queue management helper
+- **`quote()`** - Request a quote helper
+- **`subscribe()`** - Subscription management helper
 
-#### 3. Activity-based Pricing
+### Business Metrics
 
-```typescript
-const service = Service({
-  // ...other properties
-  pricing: {
-    model: 'activity-based',
-    activities: [
-      { name: 'research', rate: 50 },
-      { name: 'writing', rate: 100 },
-      { name: 'editing', rate: 30 },
-    ],
-  },
-})
+- **`entitlements()`** - Access entitlements helper
+- **`kpis()`** - Key performance indicators helper
+- **`okrs()`** - Objectives and key results helper
+- **`Plan()`** - Create subscription plans
+- **`KPI()`** - Define KPIs
+- **`OKR()`** - Define OKRs
 
-// Calculate price based on activities performed
-const price = service.calculatePrice({
-  activities: {
-    research: 2,
-    writing: 1,
-    editing: 3,
-  },
-}) // 290 (50*2 + 100*1 + 30*3)
-```
+## Examples
 
-#### 4. Outcome-based Pricing
+### Creating a Service
 
 ```typescript
+import { Service, Endpoint, POST } from 'services-as-software'
+
 const service = Service({
-  // ...other properties
-  pricing: {
-    model: 'outcome-based',
-    outcomes: [
-      { metric: 'conversion-rate', targetValue: 5, price: 500 },
-      { metric: 'engagement', targetValue: 10000, price: 300 },
-    ],
-  },
-})
+  name: 'my-service',
+  version: '1.0.0',
 
-// Calculate price based on achieved outcomes
-const price = service.calculatePrice({
-  outcomes: {
-    'conversion-rate': 6.5,
-    engagement: 8000,
+  // Pricing
+  pricing: {
+    model: 'subscription',
+    basePrice: 49.99,
+    currency: 'USD',
+    interval: 'monthly',
   },
-}) // 500 (only conversion-rate target was met)
-```
 
-### Offering Functions as Services
+  // Endpoints
+  endpoints: [
+    POST({
+      name: 'process',
+      handler: async (input, context) => {
+        // Your logic here
+        return { processed: true }
+      },
+    }),
+  ],
 
-```typescript
-import { Service } from 'services-as-software'
+  // Subscription plans
+  plans: [
+    {
+      id: 'pro',
+      name: 'Pro Plan',
+      pricing: { model: 'subscription', basePrice: 49.99, currency: 'USD', interval: 'monthly' },
+      entitlements: ['api-access', 'priority-support'],
+      features: ['Unlimited API calls', '24/7 support'],
+    },
+  ],
 
-const functionAsService = Service({
-  name: 'Text Summarization',
-  objective: {
-    description: 'Provide accurate text summarization',
-    keyResults: [],
-  },
-  keyResults: [
+  // KPIs
+  kpis: [
     {
-      description: 'Summarization accuracy',
-      target: 90,
-      unit: 'percent',
+      id: 'daily-requests',
+      name: 'Daily Requests',
+      calculate: async () => 1000,
+      target: 1500,
     },
   ],
-  pricing: {
-    model: 'cost-based',
-    costBase: 5,
-    variableCosts: 0.01,
-  },
-  implementation: {
-    type: 'function',
-    id: 'text-summarizer-function',
-  },
 })
 ```
 
-### Offering Workflows as Services
+### Using a Client
 
 ```typescript
-import { Service } from 'services-as-software'
+import { Client } from 'services-as-software'
 
-const workflowAsService = Service({
-  name: 'Content Production Pipeline',
-  objective: {
-    description: 'End-to-end content production',
-    keyResults: [],
-  },
-  keyResults: [
-    {
-      description: 'Average production time',
-      target: 24,
-      unit: 'hours',
-    },
-  ],
-  pricing: {
-    model: 'activity-based',
-    activities: [
-      { name: 'research', rate: 100 },
-      { name: 'writing', rate: 200 },
-      { name: 'editing', rate: 50 },
-      { name: 'publishing', rate: 30 },
-    ],
-  },
-  implementation: {
-    type: 'workflow',
-    id: 'content-production-workflow',
+const client = Client({
+  url: 'https://api.example.com/service',
+  auth: {
+    type: 'api-key',
+    credentials: { apiKey: 'your-key' },
   },
 })
+
+const result = await client.do('translate', { text: 'Hello', to: 'es' })
 ```
 
-### Offering Agents as Services
+### Using Providers
 
 ```typescript
-import { Service } from 'services-as-software'
+import { providers } from 'services-as-software'
 
-const agentAsService = Service({
-  name: 'Customer Support Agent',
-  objective: {
-    description: 'Provide excellent customer support',
-    keyResults: [],
-  },
-  keyResults: [
-    {
-      description: 'Customer satisfaction score',
-      target: 4.5,
-      unit: 'rating',
-    },
-    {
-      description: 'First response time',
-      target: 5,
-      unit: 'minutes',
-    },
-  ],
-  pricing: {
-    model: 'outcome-based',
-    outcomes: [
-      { metric: 'resolution-rate', targetValue: 95, price: 1000 },
-      { metric: 'satisfaction-score', targetValue: 4.8, price: 500 },
-    ],
-  },
-  implementation: {
-    type: 'agent',
-    id: 'customer-support-agent',
-  },
+const aws = providers.aws({
+  accessKeyId: 'key',
+  secretAccessKey: 'secret',
+  region: 'us-east-1',
 })
+
+const translate = aws.service('translate')
+const result = await translate.do('translate', { text: 'Hello', to: 'es' })
 ```
 
-## API Reference
+## Features
+
+- **Type-safe** - Full TypeScript support with comprehensive types
+- **Pricing Models** - Support for free, fixed, per-use, subscription, tiered, and custom pricing
+- **Authentication** - Built-in support for API keys, OAuth, JWT, and Basic auth
+- **Rate Limiting** - Endpoint-level rate limiting configuration
+- **Usage Tracking** - Track service usage for billing and analytics
+- **Subscription Management** - Built-in subscription and entitlement support
+- **Business Metrics** - KPIs and OKRs for monitoring service health
+- **Event System** - Register event handlers for service events
+- **Scheduled Tasks** - Cron-based recurring task support
+- **Multi-Provider** - Connect to AWS, GCP, Azure, and custom providers
+
+## Entity Definitions (Nouns)
+
+This package provides comprehensive entity definitions for AI-delivered productized services, following the Noun pattern from `ai-database`. Each entity includes properties, relationships, actions, and events.
+
+### Entity Categories
+
+| Category | Entities |
+|----------|----------|
+| **Services** | ProductizedService, ServiceOffering, ServicePlan, ServiceInstance, ServiceExecution |
+| **Delivery** | AgentDelivery, AutonomyLevel, EscalationRule, ConfidenceThreshold, HumanHandoff, QualityGate |
+| **Billing** | ServiceQuote, ServiceOrder, ServiceSubscription, Usage, Invoice, Payment |
+| **Operations** | SLA, SLO, ServiceIncident, SupportTicket, ServiceFeedback, ServiceMetric |
+| **Customers** | ServiceCustomer, ServiceEntitlement, CustomerUsage, CustomerSegment |
+| **Orchestration** | ServiceWorkflow, WorkflowStep, ServiceTask, ServiceQueue, ServiceWorker |
 
-### Service Function
+### Using Entity Definitions
 
 ```typescript
-function Service(definition: ServiceDefinition): ServiceObject
+import {
+  ProductizedService,
+  AgentDelivery,
+  EscalationRule,
+  ServiceEntities,
+  DeliveryEntities,
+} from 'services-as-software'
+
+// Access individual entities
+console.log(ProductizedService.singular)  // 'productized-service'
+console.log(ProductizedService.actions)   // ['create', 'update', 'publish', 'execute', ...]
+
+// Access entity collections
+const allServices = ServiceEntities
+const allDelivery = DeliveryEntities
 ```
 
-Creates a service with the given definition.
+### AI Delivery Entities
 
-### ServiceDefinition
+The delivery entities capture the key semantics of AI-delivered services:
 
 ```typescript
-interface ServiceDefinition {
-  name: string
-  description?: string
-  objective: Objective
-  keyResults: KeyResult[]
-  pricing: ServicePricing
-  implementation: ImplementationDetails
-  metadata?: Record<string, any>
+const AgentDelivery: Noun = {
+  singular: 'agent-delivery',
+  plural: 'agent-deliveries',
+  description: 'AI agent configuration for autonomous service delivery',
+
+  properties: {
+    name: { type: 'string', description: 'Agent name' },
+    model: { type: 'string', description: 'AI model identifier' },
+    autonomyLevel: {
+      type: 'string',
+      examples: ['full', 'supervised', 'assisted', 'advisory']
+    },
+    confidenceThreshold: {
+      type: 'number',
+      description: 'Min confidence for autonomous action (0-1)'
+    },
+    escalationTriggers: {
+      type: 'string',
+      array: true,
+      description: 'Conditions that trigger escalation'
+    },
+    // ... more properties
+  },
+
+  relationships: {
+    service: { type: 'ProductizedService', description: 'Parent service' },
+    escalationRules: { type: 'EscalationRule[]', description: 'Escalation rules' },
+    qualityGates: { type: 'QualityGate[]', description: 'Quality gates' },
+  },
+
+  actions: ['create', 'update', 'activate', 'pause', 'train', 'evaluate', 'escalate'],
+  events: ['created', 'updated', 'activated', 'paused', 'trained', 'evaluated', 'escalated'],
 }
 ```
 
-### Pricing Models
+### Productized Service Entity
 
 ```typescript
-type PricingModel = 'cost-based' | 'margin-based' | 'activity-based' | 'outcome-based'
+const ProductizedService: Noun = {
+  singular: 'productized-service',
+  plural: 'productized-services',
+  description: 'A service packaged and delivered as software',
+
+  properties: {
+    name: { type: 'string', description: 'Service name' },
+    deliveryModel: {
+      type: 'string',
+      examples: ['autonomous', 'assisted', 'supervised', 'manual']
+    },
+    autonomyLevel: { type: 'number', description: 'AI autonomy level (1-5)' },
+    confidenceThreshold: {
+      type: 'number',
+      description: 'Min confidence for auto-completion'
+    },
+    escalationPolicy: {
+      type: 'string',
+      examples: ['immediate', 'queue', 'scheduled', 'manual']
+    },
+    // ... more properties
+  },
 
-type ServicePricing = CostBasedPricing | MarginBasedPricing | ActivityBasedPricing | OutcomeBasedPricing
+  relationships: {
+    plans: { type: 'ServicePlan[]', description: 'Pricing plans' },
+    agent: { type: 'AgentDelivery', description: 'AI agent for delivery' },
+    sla: { type: 'SLA', description: 'Service level agreement' },
+    workflows: { type: 'ServiceWorkflow[]', description: 'Service workflows' },
+  },
+
+  actions: ['create', 'update', 'publish', 'execute', 'escalate', 'complete'],
+  events: ['created', 'updated', 'published', 'executed', 'escalated', 'completed'],
+}
 ```
 
-## Integration with Existing Services
+## Architecture
 
-The `services-as-software` package is designed to work with the existing services ecosystem:
+Services-as-software provides a complete framework for building and consuming services:
 
-- Integrates with the `services.do` SDK for service registration
-- Extends the business model concepts from `Business-as-Code`
-- Compatible with Functions, Workflows, and Agents collections
+```
+Service Definition → Service Instance → Client Access
+     ↓                    ↓                  ↓
+  Endpoints          Event Handlers      HTTP/RPC
+  Pricing            Scheduled Tasks     Authentication
+  Plans              KPIs/OKRs           Rate Limiting
+```
 
 ## License
 

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Service client for connecting to remote services
+ */
+import type { ServiceClient, ClientConfig } from './types.js';
+/**
+ * Create a client to connect to a remote service
+ *
+ * @example
+ * ```ts
+ * const client = Client({
+ *   url: 'https://api.example.com/translation',
+ *   auth: {
+ *     type: 'api-key',
+ *     credentials: { apiKey: process.env.API_KEY },
+ *   },
+ * })
+ *
+ * const result = await client.do('translate', {
+ *   text: 'Hello world',
+ *   to: 'es',
+ * })
+ * ```
+ */
+export declare function Client(config: ClientConfig): ServiceClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EAOb,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,CAiG1D"}

package/dist/client.js

@@ -0,0 +1,103 @@
+/**
+ * Service client for connecting to remote services
+ */
+/**
+ * Create a client to connect to a remote service
+ *
+ * @example
+ * ```ts
+ * const client = Client({
+ *   url: 'https://api.example.com/translation',
+ *   auth: {
+ *     type: 'api-key',
+ *     credentials: { apiKey: process.env.API_KEY },
+ *   },
+ * })
+ *
+ * const result = await client.do('translate', {
+ *   text: 'Hello world',
+ *   to: 'es',
+ * })
+ * ```
+ */
+export function Client(config) {
+    const baseUrl = config.url || '';
+    const headers = {
+        'Content-Type': 'application/json',
+        ...config.headers,
+    };
+    // Add auth headers
+    if (config.auth) {
+        switch (config.auth.type) {
+            case 'api-key':
+                headers['Authorization'] = `Bearer ${config.auth.credentials.apiKey || config.auth.credentials.token}`;
+                break;
+            case 'basic':
+                const basicAuth = Buffer.from(`${config.auth.credentials.username}:${config.auth.credentials.password}`).toString('base64');
+                headers['Authorization'] = `Basic ${basicAuth}`;
+                break;
+            case 'jwt':
+                headers['Authorization'] = `Bearer ${config.auth.credentials.token}`;
+                break;
+            // OAuth would require more complex flow
+        }
+    }
+    /**
+     * Make an HTTP request to the service
+     */
+    async function request(endpoint, body) {
+        const url = `${baseUrl}/${endpoint.replace(/^\//, '')}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: config.timeout ? AbortSignal.timeout(config.timeout) : undefined,
+        });
+        if (!response.ok) {
+            throw new Error(`Service request failed: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+    return {
+        async ask(question, context) {
+            const result = await request('ask', { question, context });
+            return result.answer;
+        },
+        async deliver(orderId, results) {
+            await request('deliver', { orderId, results });
+        },
+        async do(action, input) {
+            return request('do', { action, input });
+        },
+        async generate(prompt, options) {
+            return request('generate', { prompt, options });
+        },
+        async is(value, type) {
+            const result = await request('is', { value, type });
+            return result.result;
+        },
+        async notify(notification) {
+            await request('notify', notification);
+        },
+        async order(product, quantity) {
+            return request('order', { product, quantity });
+        },
+        async quote(product, quantity) {
+            return request('quote', { product, quantity });
+        },
+        async subscribe(planId) {
+            return request('subscribe', { planId });
+        },
+        async entitlements() {
+            const result = await request('entitlements', {});
+            return result.entitlements;
+        },
+        async kpis() {
+            return request('kpis', {});
+        },
+        async okrs() {
+            return request('okrs', {});
+        },
+    };
+}
+//# sourceMappingURL=client.js.map