.do
API ReferenceTypes

Service Type Definitions

Complete type definitions for Service, ServiceCategory, ServiceCapability, and ServiceRequirements

This document provides complete TypeScript type definitions for all service-related types in the services-as-software platform.

Core Service Types

Service

The main Service type that represents a discrete unit of work.

// @errors: 7006
interface Service extends Thing {
  $type: 'Service'
  $id: string
  name: string
  description: string
  provider: Organization | Person
  workflow: BusinessWorkflow
  pricing: PricingSpecification
  category?: ServiceCategory
  tags?: string[]
  status: ServiceStatus
  version?: string
  capabilities?: ServiceCapability[]
  requirements?: ServiceRequirements
  metadata?: ServiceMetadata
}

const service: Service = {
  $type: 'Service',
  //^?
  $id: 'service-1',
  name: 'AI SDR',
  description: 'Automated outreach',
  provider: {} as Organization,
  workflow: {} as BusinessWorkflow,
  pricing: {} as PricingSpecification,
  status: 'active',
}

ServiceStatus

Status enum for service availability.

type ServiceStatus =
  | 'draft' // Service is being developed, not available
  | 'active' // Service is live and available
  | 'inactive' // Service is temporarily unavailable
  | 'archived' // Service is permanently retired

Usage Example:

// @errors: 7006
// Create service in draft status
const service = await $.Service.define({
  name: 'My Service',
  status: 'draft',
  //        ^?
  // ... other properties
})

// Publish service
await $.Service[service.$id].update({ status: 'active' })
//                                            ^?

// Temporarily disable
await $.Service[service.$id].update({ status: 'inactive' })

// Retire service
await $.Service[service.$id].update({ status: 'archived' })

ServiceCategory

Predefined service categories for organization and discovery.

type ServiceCategory =
  // AI Services
  | 'ai-content-generation'
  | 'ai-analysis'
  | 'ai-decision-support'
  | 'ai-creative'
  | 'ai-research'
  | 'ai-code-generation'

  // Automation Services
  | 'automation-workflow'
  | 'automation-data-pipeline'
  | 'automation-business-process'
  | 'automation-integration'
  | 'automation-testing'
  | 'automation-deployment'

  // Data Services
  | 'data-transformation'
  | 'data-enrichment'
  | 'data-validation'
  | 'data-analytics'
  | 'data-visualization'
  | 'data-migration'

  // Integration Services
  | 'integration-api'
  | 'integration-sync'
  | 'integration-events'
  | 'integration-protocols'
  | 'integration-etl'

  // Business Services
  | 'business-customer-service'
  | 'business-sales'
  | 'business-marketing'
  | 'business-financial'
  | 'business-hr'
  | 'business-operations'

  // Development Services
  | 'development-frontend'
  | 'development-backend'
  | 'development-mobile'
  | 'development-infrastructure'
  | 'development-database'

  // Content Services
  | 'content-writing'
  | 'content-editing'
  | 'content-translation'
  | 'content-localization'
  | 'content-seo'

  // Design Services
  | 'design-ui-ux'
  | 'design-graphic'
  | 'design-brand'
  | 'design-3d'
  | 'design-video'

  // Analytics Services
  | 'analytics-business-intelligence'
  | 'analytics-reporting'
  | 'analytics-predictive'
  | 'analytics-prescriptive'

  // Custom
  | 'custom'

Usage Example:

// @errors: 7006
// Create service with category
const service = await $.Service.define({
  name: 'AI Blog Writer',
  category: 'ai-content-generation',
  //          ^?
  // ... other properties
})

// Find services by category
const aiServices = await $.Service.find({
  category: 'ai-content-generation',
  //          ^^^^^^^^^^^^^^^^^^^^^^
})

// Find multiple categories
const contentServices = await $.Service.find({
  category: {
    $in: ['content-writing', 'content-editing', 'content-seo'],
  },
})

ServiceCapability

Specific capabilities that a service provides.

type ServiceCapability =
  // AI Capabilities
  | 'text-generation'
  | 'text-analysis'
  | 'text-classification'
  | 'text-summarization'
  | 'text-translation'
  | 'text-extraction'
  | 'image-generation'
  | 'image-analysis'
  | 'image-classification'
  | 'image-enhancement'
  | 'video-generation'
  | 'video-analysis'
  | 'audio-generation'
  | 'audio-transcription'
  | 'code-generation'
  | 'code-analysis'
  | 'code-review'
  | 'code-testing'

  // Communication Capabilities
  | 'email-sending'
  | 'email-parsing'
  | 'sms-sending'
  | 'voice-calling'
  | 'chat-messaging'
  | 'social-media-posting'
  | 'notification-push'

  // Data Capabilities
  | 'data-ingestion'
  | 'data-transformation'
  | 'data-validation'
  | 'data-enrichment'
  | 'data-deduplication'
  | 'data-export'
  | 'data-backup'
  | 'data-sync'

  // Integration Capabilities
  | 'api-integration'
  | 'webhook-handling'
  | 'event-streaming'
  | 'file-transfer'
  | 'database-access'
  | 'oauth-authentication'

  // Automation Capabilities
  | 'workflow-orchestration'
  | 'task-scheduling'
  | 'conditional-logic'
  | 'error-handling'
  | 'retry-logic'
  | 'parallel-processing'

  // Business Capabilities
  | 'lead-generation'
  | 'lead-qualification'
  | 'lead-nurturing'
  | 'customer-onboarding'
  | 'customer-support'
  | 'order-processing'
  | 'invoice-generation'
  | 'payment-processing'
  | 'contract-management'

  // Analytics Capabilities
  | 'data-visualization'
  | 'report-generation'
  | 'dashboard-creation'
  | 'predictive-modeling'
  | 'trend-analysis'
  | 'anomaly-detection'

  // Development Capabilities
  | 'deployment'
  | 'monitoring'
  | 'logging'
  | 'alerting'
  | 'load-balancing'
  | 'auto-scaling'

Usage Example:

// @errors: 7006
// Define service with capabilities
const service = await $.Service.define({
  name: 'AI SDR Outreach',
  category: 'business-sales',
  capabilities: [
    //^^^^^^^^^^^^^
    'lead-generation',
    'text-generation',
    'email-sending',
    'workflow-orchestration',
  ],
  // ... other properties
})

// Find services with specific capability
const emailServices = await $.Service.find({
  capabilities: { $contains: 'email-sending' },
  //                            ^^^^^^^^^^^^^^^
})

// Find services with multiple capabilities
const aiEmailServices = await $.Service.find({
  capabilities: {
    $all: ['text-generation', 'email-sending'],
    //         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  },
})

ServiceRequirements

Requirements and prerequisites for using a service.

// @errors: 7006
interface ServiceRequirements {
  // Required input parameters
  input: InputRequirement[]
  //       ^^^^^^^^^^^^^^^^^^
  // Required permissions
  permissions: Permission[]

  // Required third-party integrations
  integrations: Integration[]

  // Minimum service tier or plan
  minTier?: ServiceTier

  // Geographic restrictions
  regions?: string[]

  // Industry restrictions
  industries?: string[]

  // Compliance requirements
  compliance?: ComplianceRequirement[]
}

interface InputRequirement {
  name: string
  type: InputType
  description: string
  required: boolean
  //^^^^^^^^
  default?: any
  validation?: ValidationRule
  examples?: any[]
}

type InputType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'file' | 'url' | 'email' | 'date' | 'datetime'

interface ValidationRule {
  pattern?: string
  min?: number
  max?: number
  enum?: any[]
  format?: string
}

interface Permission {
  scope: string
  description: string
  required: boolean
}

interface Integration {
  name: string
  description: string
  required: boolean
  oauth?: boolean
  apiKey?: boolean
  webhook?: boolean
}

type ServiceTier = 'free' | 'starter' | 'professional' | 'enterprise'
//                  ^^^^^^

interface ComplianceRequirement {
  standard: string
  description: string
  required: boolean
}

Usage Example:

// Define service with detailed requirements
const service = await $.Service.define({
  name: 'Email Campaign Service',
  requirements: {
    input: [
      {
        name: 'leads',
        type: 'array',
        description: 'List of leads to contact',
        required: true,
        validation: {
          min: 1,
          max: 1000,
        },
        examples: [
          [
            { name: 'John Doe', email: '[email protected]' },
            { name: 'Jane Smith', email: '[email protected]' },
          ],
        ],
      },
      {
        name: 'template',
        type: 'string',
        description: 'Email template ID',
        required: true,
        validation: {
          pattern: '^template-[a-z0-9]+',
        },
      },
      {
        name: 'schedule',
        type: 'datetime',
        description: 'When to send emails',
        required: false,
        default: null,
      },
    ],
    permissions: [
      {
        scope: 'email:send',
        description: 'Permission to send emails on your behalf',
        required: true,
      },
      {
        scope: 'contacts:read',
        description: 'Permission to read contact information',
        required: true,
      },
    ],
    integrations: [
      {
        name: 'Email Provider',
        description: 'SMTP or email service integration',
        required: true,
        oauth: true,
        apiKey: true,
      },
      {
        name: 'CRM',
        description: 'CRM integration for contact sync',
        required: false,
        oauth: true,
      },
    ],
    minTier: 'professional',
    regions: ['US', 'CA', 'EU'],
    compliance: [
      {
        standard: 'GDPR',
        description: 'Must comply with GDPR for EU customers',
        required: true,
      },
      {
        standard: 'CAN-SPAM',
        description: 'Must comply with CAN-SPAM Act',
        required: true,
      },
    ],
  },
  // ... other properties
})

ServiceMetadata

Additional metadata about a service.

interface ServiceMetadata {
  // Timestamps
  createdAt: string
  updatedAt: string
  publishedAt?: string
  deprecatedAt?: string

  // Authorship
  createdBy: string
  maintainers?: string[]

  // Statistics
  totalOrders?: number
  totalExecutions?: number
  averageExecutionTime?: number
  averageRating?: number
  successRate?: number

  // Performance
  sla?: ServiceLevelAgreement
  uptime?: number

  // Documentation
  documentationUrl?: string
  changelogUrl?: string
  supportUrl?: string

  // Versioning
  deprecatedVersions?: string[]
  latestVersion?: string

  // Custom metadata
  custom?: Record<string, any>
}

interface ServiceLevelAgreement {
  availability: number // e.g., 99.9
  responseTime: number // milliseconds
  resolution: number // milliseconds
  support: SupportLevel
}

type SupportLevel = 'community' | 'standard' | 'priority' | 'enterprise'

Usage Example:

// Access service metadata
const service = await $.Service.get('service-id')

console.log('Service Stats:')
console.log(`- Created: ${service.metadata.createdAt}`)
console.log(`- Total Orders: ${service.metadata.totalOrders}`)
console.log(`- Success Rate: ${(service.metadata.successRate * 100).toFixed(1)}%`)
console.log(`- Average Execution: ${service.metadata.averageExecutionTime}ms`)
console.log(`- SLA Uptime: ${service.metadata.sla.availability}%`)

Service Configuration Types

ServiceConfig

Configuration object for creating a service.

interface ServiceConfig {
  name: string
  description: string
  provider: Organization | Person | string
  workflow: BusinessWorkflow | string
  pricing: PricingSpecification
  category?: ServiceCategory
  tags?: string[]
  status?: ServiceStatus
  version?: string
  capabilities?: ServiceCapability[]
  requirements?: ServiceRequirements
}

ServiceFilter

Filter object for querying services.

interface ServiceFilter {
  status?: ServiceStatus | ServiceStatus[]
  category?: ServiceCategory | ServiceCategory[]
  provider?: string
  tags?: string | string[]
  capabilities?: string | string[]
  'pricing.model'?: string
  'pricing.currency'?: string
  'metadata.successRate'?: { $gte?: number; $lte?: number }
}

Usage Example:

// Complex service query
const services = await $.Service.find({
  status: 'active',
  category: ['ai-content-generation', 'content-writing'],
  capabilities: { $contains: 'text-generation' },
  'pricing.model': 'per-unit',
  'pricing.currency': 'USD',
  'metadata.successRate': { $gte: 0.9 },
})

ServiceQuery

Advanced query object with operators.

interface ServiceQuery {
  // Field filters
  [field: string]: any | QueryOperator

  // Relationship filters
  provider?: string | QueryOperator
  workflow?: string | QueryOperator

  // Array filters
  tags?: ArrayQueryOperator
  capabilities?: ArrayQueryOperator

  // Numeric filters
  'metadata.totalOrders'?: NumericQueryOperator
  'metadata.successRate'?: NumericQueryOperator
  'metadata.averageRating'?: NumericQueryOperator
}

interface QueryOperator {
  $eq?: any
  $ne?: any
  $gt?: any
  $gte?: any
  $lt?: any
  $lte?: any
  $in?: any[]
  $nin?: any[]
  $exists?: boolean
}

interface ArrayQueryOperator extends QueryOperator {
  $contains?: any
  $all?: any[]
  $size?: number
}

interface NumericQueryOperator {
  $eq?: number
  $ne?: number
  $gt?: number
  $gte?: number
  $lt?: number
  $lte?: number
  $between?: [number, number]
}

Usage Example:

// Advanced queries
const highPerformingServices = await $.Service.find({
  'metadata.successRate': { $gte: 0.95 },
  'metadata.averageRating': { $gte: 4.5 },
  'metadata.totalOrders': { $gte: 100 },
})

const recentServices = await $.Service.find({
  'metadata.publishedAt': {
    $gte: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString(),
  },
})

Service Response Types

ServiceListResponse

Response type for service list queries.

interface ServiceListResponse {
  services: Service[]
  total: number
  page: number
  pageSize: number
  hasMore: boolean
}

ServiceSearchResult

Search result with relevance scoring.

interface ServiceSearchResult {
  service: Service
  score: number
  highlights: SearchHighlight[]
}

interface SearchHighlight {
  field: string
  value: string
  matched: string[]
}

Usage Example:

// Search with results
const results = await $.Service.search('ai content generation')

results.forEach((result) => {
  console.log(`${result.service.name} (score: ${result.score})`)
  result.highlights.forEach((highlight) => {
    console.log(`  - ${highlight.field}: ${highlight.value}`)
  })
})

Complete Type Examples

Example 1: AI Content Service Definition

const aiContentService: Service = {
  $type: 'Service',
  $id: 'https://services.do/ai-content-service',
  name: 'AI Blog Post Writer',
  description: 'Generate high-quality blog posts with AI and human review',
  provider: 'content-ai-co',
  workflow: 'blog-writing-workflow',
  pricing: {
    model: 'per-unit',
    amount: 50,
    currency: 'USD',
  },
  category: 'ai-content-generation',
  tags: ['ai', 'content', 'blog', 'writing', 'seo'],
  status: 'active',
  version: '2.1.0',
  capabilities: ['text-generation', 'text-analysis', 'code-generation', 'data-transformation'],
  requirements: {
    input: [
      {
        name: 'topic',
        type: 'string',
        description: 'Blog post topic',
        required: true,
      },
      {
        name: 'keywords',
        type: 'array',
        description: 'SEO keywords to target',
        required: true,
        validation: {
          min: 1,
          max: 10,
        },
      },
      {
        name: 'word_count',
        type: 'number',
        description: 'Target word count',
        required: false,
        default: 1000,
        validation: {
          min: 500,
          max: 5000,
        },
      },
    ],
    permissions: [],
    integrations: [],
  },
  metadata: {
    createdAt: '2025-01-15T00:00:00Z',
    updatedAt: '2025-10-26T00:00:00Z',
    publishedAt: '2025-02-01T00:00:00Z',
    createdBy: 'user-123',
    totalOrders: 1547,
    totalExecutions: 1523,
    averageExecutionTime: 120000,
    averageRating: 4.7,
    successRate: 0.985,
    sla: {
      availability: 99.9,
      responseTime: 5000,
      resolution: 86400000,
      support: 'standard',
    },
    documentationUrl: 'https://docs.services.do/ai-content-service',
  },
}

Example 2: SDR Outreach Service Definition

const sdrOutreachService: Service = {
  $type: 'Service',
  $id: 'https://services.do/sdr-outreach-service',
  name: 'AI-Powered SDR Outreach',
  description: 'Automated outreach to qualified leads with personalized messaging',
  provider: 'sales-automation-co',
  workflow: 'sdr-workflow',
  pricing: {
    model: 'per-lead',
    amount: 5,
    currency: 'USD',
  },
  category: 'business-sales',
  tags: ['sdr', 'outreach', 'sales', 'b2b', 'ai'],
  status: 'active',
  version: '1.3.0',
  capabilities: ['lead-generation', 'text-generation', 'email-sending', 'workflow-orchestration', 'data-enrichment'],
  requirements: {
    input: [
      {
        name: 'leads',
        type: 'array',
        description: 'List of leads to contact',
        required: true,
        validation: {
          min: 1,
          max: 1000,
        },
      },
      {
        name: 'company_info',
        type: 'object',
        description: 'Your company information',
        required: true,
      },
    ],
    permissions: [
      {
        scope: 'email:send',
        description: 'Send emails on your behalf',
        required: true,
      },
    ],
    integrations: [
      {
        name: 'Email Provider',
        description: 'SMTP or email service',
        required: true,
        oauth: true,
        apiKey: true,
      },
      {
        name: 'CRM',
        description: 'CRM integration (optional)',
        required: false,
        oauth: true,
      },
    ],
    regions: ['US', 'CA', 'EU', 'UK'],
    compliance: [
      {
        standard: 'CAN-SPAM',
        description: 'Compliance with email regulations',
        required: true,
      },
    ],
  },
  metadata: {
    createdAt: '2025-05-10T00:00:00Z',
    updatedAt: '2025-10-20T00:00:00Z',
    publishedAt: '2025-06-01T00:00:00Z',
    createdBy: 'user-456',
    totalOrders: 3254,
    totalExecutions: 3189,
    averageExecutionTime: 45000,
    averageRating: 4.8,
    successRate: 0.98,
    sla: {
      availability: 99.95,
      responseTime: 3000,
      resolution: 43200000,
      support: 'priority',
    },
  },
}

Utility Types

ServiceWithRelations

Service with all relations populated.

interface ServiceWithRelations extends Service {
  provider: Organization | Person
  workflow: BusinessWorkflow
  offerings: ServiceOffering[]
  orders: ServiceOrder[]
  executions: ServiceExecution[]
}

PartialService

Partial service type for updates.

type PartialService = Partial<Omit<Service, '$type' | '$id'>>

ServiceDTO

Data transfer object for API responses.

interface ServiceDTO {
  id: string
  name: string
  description: string
  category: ServiceCategory
  pricing: PricingSpecification
  rating: number
  orderCount: number
  status: ServiceStatus
}

Type Guards

Utility functions for type checking.

function isService(value: any): value is Service {
  return value && typeof value === 'object' && value.$type === 'Service' && typeof value.name === 'string' && typeof value.description === 'string'
}

function isActiveService(service: Service): boolean {
  return service.status === 'active'
}

function hasCapability(service: Service, capability: ServiceCapability): boolean {
  return service.capabilities?.includes(capability) ?? false
}

See Also

Pricing Type Definitions

Complete type definitions for PricingModel, BillingPeriod, PricingSpecification, and pricing calculations

Complete Content Generation Service

Production-ready blog post generation service with research, writing, SEO optimization, and quality assurance

On this page

Core Service TypesServiceServiceStatusServiceCategoryServiceCapabilityServiceRequirementsServiceMetadataService Configuration TypesServiceConfigServiceFilterServiceQueryService Response TypesServiceListResponseServiceSearchResultComplete Type ExamplesExample 1: AI Content Service DefinitionExample 2: SDR Outreach Service DefinitionUtility TypesServiceWithRelationsPartialServiceServiceDTOType GuardsSee Also