business-as-code
Version:
Primitives for expressing business logic and processes as code
334 lines • 10.2 kB
TypeScript
/**
* Business Roles - Bridges digital-workers and ai-database authorization
*
* Connects:
* - WorkerRole (business role: CEO, Engineer, Manager)
* - Authorization Role (FGA/RBAC: permissions, access control)
* - Task Assignment (who handles what in workflows/processes)
*
* @packageDocumentation
*/
import type { Role as OrgRole, RoleType as OrgRoleType, RoleWorkerType } from 'org.ai';
import type { WorkerRef } from 'digital-workers';
export type { Worker, WorkerRef } from 'digital-workers';
export type { OrgRole, OrgRoleType, RoleWorkerType };
/**
* Business role type - the function of a worker in the organization
*/
export type BusinessRoleType = 'ceo' | 'cto' | 'cfo' | 'coo' | 'cmo' | 'cpo' | 'director' | 'manager' | 'lead' | 'supervisor' | 'engineer' | 'designer' | 'analyst' | 'specialist' | 'coordinator' | 'operator' | 'agent' | 'assistant' | string;
/**
* Business Role - extends org.ai Role with authorization and task capabilities
*
* Composes with org.ai Role to provide additional business-specific properties
* like authorization permissions, task capabilities, and compensation.
*
* @example
* ```ts
* const engineeringManager: BusinessRole = {
* id: 'role_eng_manager',
* name: 'Engineering Manager',
* type: 'manager',
* department: 'Engineering',
* description: 'Leads engineering team and makes technical decisions',
*
* // From org.ai Role
* skills: ['TypeScript', 'Architecture', 'Team Leadership'],
*
* // Business responsibilities
* responsibilities: [
* 'Lead engineering team',
* 'Make architecture decisions',
* 'Conduct code reviews',
* ],
*
* // Authorization permissions (from FGA)
* permissions: {
* repository: ['read', 'edit', 'act:merge', 'act:deploy'],
* project: ['read', 'edit', 'manage'],
* team: ['read', 'edit'],
* },
*
* // Task capabilities
* canHandle: ['code-review', 'architecture-decision', 'deployment-approval'],
* canDelegate: ['code-review', 'testing'],
* canApprove: ['pull-request', 'deployment', 'budget-under-5k'],
*
* // Worker type preference
* workerType: 'human',
* }
* ```
*/
export interface BusinessRole extends Omit<OrgRole, 'permissions'> {
/** Role type classification (overrides OrgRole.type with business-specific types) */
type: BusinessRoleType;
/**
* Authorization permissions by resource type
*
* Maps resource types to allowed actions:
* - 'read', 'edit', 'delete', 'manage' (standard)
* - 'act:*' or 'act:verb' (domain-specific verbs)
*
* Note: This differs from OrgRole.permissions which is string[]
*
* @example
* ```ts
* permissions: {
* document: ['read', 'edit'],
* invoice: ['read', 'act:send', 'act:void'],
* project: ['read', 'edit', 'manage'],
* }
* ```
*/
permissions?: Record<string, string[]>;
/** Compensation band */
compensationBand?: string;
}
/**
* Task status
*/
export type TaskStatus = 'pending' | 'assigned' | 'in_progress' | 'blocked' | 'completed' | 'failed' | 'cancelled';
/**
* Task priority
*/
export type TaskPriority = 'low' | 'normal' | 'high' | 'urgent' | 'critical';
/**
* Task assignment - links a worker to a task
*
* @example
* ```ts
* const assignment: TaskAssignment = {
* id: 'assign_123',
* taskId: 'task_review_pr_456',
* taskType: 'code-review',
*
* // Who is assigned
* assignee: { type: 'worker', id: 'worker_alice' },
* role: 'role_eng_manager',
*
* // From what process/workflow
* processId: 'process_code_review',
* stepId: 'step_1_review',
*
* // Status and timing
* status: 'in_progress',
* priority: 'high',
* assignedAt: new Date(),
* dueAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
*
* // Context
* context: {
* pullRequestId: 'pr_789',
* repository: 'acme/webapp',
* },
* }
* ```
*/
export interface TaskAssignment {
/** Unique assignment ID */
id: string;
/** Task identifier */
taskId: string;
/** Task type (for routing) */
taskType: string;
/** Task description */
description?: string;
/** Who is assigned */
assignee: AssigneeRef;
/** Required role for this task */
role?: string;
/** Source process ID */
processId?: string;
/** Source workflow ID */
workflowId?: string;
/** Step ID within process/workflow */
stepId?: string;
/** Current status */
status: TaskStatus;
/** Priority */
priority?: TaskPriority;
/** When assigned */
assignedAt: Date;
/** Who assigned it */
assignedBy?: AssigneeRef;
/** Due date */
dueAt?: Date;
/** Started at */
startedAt?: Date;
/** Completed at */
completedAt?: Date;
/** Task context/data */
context?: Record<string, unknown>;
/** Task result */
result?: unknown;
/** Notes */
notes?: string;
/** Metadata */
metadata?: Record<string, unknown>;
}
/**
* Reference to an assignee (worker, team, or role)
*
* Compatible with digital-workers WorkerRef for worker assignments.
*/
export interface AssigneeRef {
/** Type of assignee */
type: 'worker' | 'team' | 'role';
/** Assignee ID */
id: string;
/** Display name */
name?: string;
}
/**
* Convert a digital-workers WorkerRef to an AssigneeRef
*/
export declare function workerRefToAssignee(workerRef: WorkerRef): AssigneeRef;
/**
* Convert an AssigneeRef to a digital-workers WorkerRef (if type is 'worker')
*/
export declare function assigneeToWorkerRef(assignee: AssigneeRef): WorkerRef | null;
/**
* Task routing rule - determines who handles what tasks
*
* @example
* ```ts
* const routingRules: TaskRoutingRule[] = [
* {
* taskType: 'code-review',
* requiredRole: 'engineer',
* requiredLevel: 2,
* requiredSkills: ['TypeScript'],
* preferWorkerType: 'human',
* },
* {
* taskType: 'expense-approval',
* requiredRole: 'manager',
* amountThreshold: 1000,
* escalateAbove: 5000, // Escalate to director above $5k
* escalateTo: 'director',
* },
* {
* taskType: 'customer-inquiry',
* requiredRole: 'agent',
* preferWorkerType: 'ai',
* fallbackTo: 'human', // Escalate to human if AI can't handle
* },
* ]
* ```
*/
export interface TaskRoutingRule {
/** Task type this rule applies to */
taskType: string;
/** Required role type */
requiredRole?: BusinessRoleType;
/** Minimum level required */
requiredLevel?: number;
/** Required skills */
requiredSkills?: string[];
/** Required permissions */
requiredPermissions?: string[];
/** Preferred worker type */
preferWorkerType?: 'ai' | 'human' | 'hybrid';
/** Amount threshold (for approval tasks) */
amountThreshold?: number;
/** Amount above which to escalate */
escalateAbove?: number;
/** Role to escalate to */
escalateTo?: BusinessRoleType | string;
/** Fallback worker type if preferred unavailable */
fallbackTo?: 'ai' | 'human';
/** Priority for this task type */
defaultPriority?: TaskPriority;
/** SLA in minutes */
slaMinutes?: number;
/** Additional conditions */
conditions?: Record<string, unknown>;
}
/**
* Workflow role - defines a role within the context of a workflow
*
* @example
* ```ts
* const workflowRoles: WorkflowRole[] = [
* {
* name: 'Requester',
* description: 'Person who initiates the request',
* canInitiate: true,
* canView: ['all'],
* },
* {
* name: 'Approver',
* description: 'Person who approves or rejects',
* tasks: ['review', 'approve', 'reject'],
* canView: ['details', 'history'],
* requiredBusinessRole: 'manager',
* },
* {
* name: 'Processor',
* description: 'Person who processes after approval',
* tasks: ['process', 'complete'],
* requiredBusinessRole: 'operator',
* },
* ]
* ```
*/
export interface WorkflowRole {
/** Role name within workflow */
name: string;
/** Description */
description?: string;
/** Can initiate this workflow */
canInitiate?: boolean;
/** Tasks this role handles */
tasks?: string[];
/** What this role can view */
canView?: string[];
/** Required business role */
requiredBusinessRole?: BusinessRoleType | string;
/** Required permissions */
requiredPermissions?: string[];
/** Minimum level */
minLevel?: number;
}
/**
* Standard business roles with typical permissions
*/
export declare const StandardBusinessRoles: Record<string, Partial<BusinessRole>>;
/**
* Create a business role from a standard template
*/
export declare function createBusinessRole(id: string, template: keyof typeof StandardBusinessRoles, overrides?: Partial<BusinessRole>): BusinessRole;
/**
* Check if a role has permission for an action on a resource type
*/
export declare function hasPermission(role: BusinessRole, resourceType: string, action: string): boolean;
/**
* Check if a role can handle a task type
*/
export declare function canHandleTask(role: BusinessRole, taskType: string): boolean;
/**
* Check if a role can approve a request type
*/
export declare function canApproveRequest(role: BusinessRole, requestType: string): boolean;
/**
* Check if a role can delegate a task type
*/
export declare function canDelegateTask(role: BusinessRole, taskType: string): boolean;
/**
* Find the best role for a task based on routing rules
*/
export declare function findRoleForTask(taskType: string, rules: TaskRoutingRule[], context?: {
amount?: number;
skills?: string[];
}): TaskRoutingRule | undefined;
/**
* Create a task assignment
*/
export declare function createTaskAssignment(taskId: string, taskType: string, assignee: AssigneeRef, options?: Partial<Omit<TaskAssignment, 'id' | 'taskId' | 'taskType' | 'assignee' | 'status' | 'assignedAt'>>): TaskAssignment;
/**
* Transition task assignment status
*/
export declare function transitionTaskStatus(assignment: TaskAssignment, newStatus: TaskStatus, options?: {
result?: unknown;
notes?: string;
}): TaskAssignment;
//# sourceMappingURL=roles.d.ts.map