business-as-code 2.3.0 → 2.4.0

package/dist/roles.d.ts

@@ -0,0 +1,334 @@
+/**
+ * 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

package/dist/roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"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"}

package/dist/roles.js

@@ -0,0 +1,282 @@
+/**
+ * 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
+ */
+/**
+ * Convert a digital-workers WorkerRef to an AssigneeRef
+ */
+export function workerRefToAssignee(workerRef) {
+    const result = {
+        type: 'worker',
+        id: workerRef.id,
+    };
+    if (workerRef.name !== undefined) {
+        result.name = workerRef.name;
+    }
+    return result;
+}
+/**
+ * Convert an AssigneeRef to a digital-workers WorkerRef (if type is 'worker')
+ */
+export function assigneeToWorkerRef(assignee) {
+    if (assignee.type !== 'worker')
+        return null;
+    const result = {
+        id: assignee.id,
+    };
+    if (assignee.name !== undefined) {
+        result.name = assignee.name;
+    }
+    return result;
+}
+// =============================================================================
+// Standard Business Roles
+// =============================================================================
+/**
+ * Standard business roles with typical permissions
+ */
+export const StandardBusinessRoles = {
+    // Executive
+    ceo: {
+        type: 'ceo',
+        name: 'Chief Executive Officer',
+        level: 10,
+        permissions: { '*': ['manage'] },
+        canApprove: ['*'],
+        workerType: 'human',
+    },
+    cto: {
+        type: 'cto',
+        name: 'Chief Technology Officer',
+        level: 10,
+        department: 'Technology',
+        permissions: {
+            technology: ['manage'],
+            repository: ['manage'],
+            infrastructure: ['manage'],
+        },
+        canApprove: ['technical-decision', 'architecture', 'technology-budget'],
+        workerType: 'human',
+    },
+    cfo: {
+        type: 'cfo',
+        name: 'Chief Financial Officer',
+        level: 10,
+        department: 'Finance',
+        permissions: {
+            finance: ['manage'],
+            budget: ['manage'],
+            expense: ['manage'],
+        },
+        canApprove: ['expense', 'budget', 'financial-decision'],
+        workerType: 'human',
+    },
+    // Management
+    director: {
+        type: 'director',
+        level: 8,
+        permissions: {
+            team: ['manage'],
+            project: ['manage'],
+            budget: ['read', 'edit'],
+        },
+        canApprove: ['hiring', 'budget-under-50k', 'project'],
+        workerType: 'human',
+    },
+    manager: {
+        type: 'manager',
+        level: 6,
+        permissions: {
+            team: ['read', 'edit'],
+            project: ['read', 'edit', 'manage'],
+        },
+        canApprove: ['expense-under-5k', 'time-off', 'code-review'],
+        workerType: 'human',
+    },
+    lead: {
+        type: 'lead',
+        level: 5,
+        permissions: {
+            team: ['read'],
+            project: ['read', 'edit'],
+            repository: ['read', 'edit', 'act:merge'],
+        },
+        canDelegate: ['code-review', 'testing'],
+        workerType: 'hybrid',
+    },
+    // Individual Contributors
+    engineer: {
+        type: 'engineer',
+        level: 3,
+        department: 'Engineering',
+        permissions: {
+            repository: ['read', 'edit'],
+            project: ['read'],
+        },
+        canHandle: ['coding', 'code-review', 'bug-fix', 'testing'],
+        workerType: 'hybrid',
+    },
+    analyst: {
+        type: 'analyst',
+        level: 3,
+        permissions: {
+            data: ['read'],
+            report: ['read', 'edit'],
+        },
+        canHandle: ['data-analysis', 'reporting', 'research'],
+        workerType: 'hybrid',
+    },
+    // Operations
+    agent: {
+        type: 'agent',
+        level: 2,
+        permissions: {
+            ticket: ['read', 'edit', 'act:respond', 'act:escalate'],
+            customer: ['read'],
+        },
+        canHandle: ['customer-inquiry', 'support-ticket', 'basic-troubleshooting'],
+        workerType: 'ai', // AI-first
+    },
+    assistant: {
+        type: 'assistant',
+        level: 1,
+        permissions: {
+            calendar: ['read', 'edit'],
+            email: ['read', 'act:draft'],
+            task: ['read', 'edit'],
+        },
+        canHandle: ['scheduling', 'email-draft', 'task-management', 'research'],
+        workerType: 'ai', // AI-first
+    },
+};
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Create a business role from a standard template
+ */
+export function createBusinessRole(id, template, overrides) {
+    const standard = StandardBusinessRoles[template];
+    if (!standard) {
+        throw new Error(`Unknown role template: ${template}`);
+    }
+    return {
+        id,
+        name: standard['name'] || template,
+        type: standard['type'] || template,
+        ...standard,
+        ...overrides,
+    };
+}
+/**
+ * Check if a role has permission for an action on a resource type
+ */
+export function hasPermission(role, resourceType, action) {
+    if (!role.permissions)
+        return false;
+    // Check wildcard permissions
+    const wildcardPerms = role.permissions['*'];
+    if (wildcardPerms) {
+        if (wildcardPerms.includes('manage') || wildcardPerms.includes('*'))
+            return true;
+        if (wildcardPerms.includes(action))
+            return true;
+    }
+    // Check resource-specific permissions
+    const resourcePerms = role.permissions[resourceType];
+    if (!resourcePerms)
+        return false;
+    // Check for exact match
+    if (resourcePerms.includes(action))
+        return true;
+    // Check for 'manage' which includes all actions
+    if (resourcePerms.includes('manage') || resourcePerms.includes('*'))
+        return true;
+    // Check for act:* pattern
+    if (action.startsWith('act:')) {
+        if (resourcePerms.includes('act:*'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Check if a role can handle a task type
+ */
+export function canHandleTask(role, taskType) {
+    if (!role['canHandle'])
+        return false;
+    return role['canHandle'].includes(taskType) || role['canHandle'].includes('*');
+}
+/**
+ * Check if a role can approve a request type
+ */
+export function canApproveRequest(role, requestType) {
+    if (!role['canApprove'])
+        return false;
+    return role['canApprove'].includes(requestType) || role['canApprove'].includes('*');
+}
+/**
+ * Check if a role can delegate a task type
+ */
+export function canDelegateTask(role, taskType) {
+    if (!role['canDelegate'])
+        return false;
+    return role['canDelegate'].includes(taskType) || role['canDelegate'].includes('*');
+}
+/**
+ * Find the best role for a task based on routing rules
+ */
+export function findRoleForTask(taskType, rules, context) {
+    const matchingRules = rules.filter((rule) => rule.taskType === taskType);
+    if (matchingRules.length === 0)
+        return undefined;
+    // If there's an amount and escalation rules, check those
+    if (context?.amount) {
+        for (const rule of matchingRules) {
+            if (rule.escalateAbove && context.amount > rule.escalateAbove) {
+                // Find the escalated rule
+                const escalatedRule = rules.find((r) => r.taskType === taskType && r.requiredRole === rule.escalateTo);
+                if (escalatedRule)
+                    return escalatedRule;
+            }
+        }
+    }
+    // Return the first matching rule
+    return matchingRules[0];
+}
+/**
+ * Create a task assignment
+ */
+export function createTaskAssignment(taskId, taskType, assignee, options) {
+    return {
+        id: `assign_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
+        taskId,
+        taskType,
+        assignee,
+        status: 'assigned',
+        assignedAt: new Date(),
+        priority: 'normal',
+        ...options,
+    };
+}
+/**
+ * Transition task assignment status
+ */
+export function transitionTaskStatus(assignment, newStatus, options) {
+    const now = new Date();
+    return {
+        ...assignment,
+        status: newStatus,
+        ...(newStatus === 'in_progress' && !assignment.startedAt ? { startedAt: now } : {}),
+        ...(newStatus === 'completed' || newStatus === 'failed' ? { completedAt: now } : {}),
+        ...(options?.result ? { result: options.result } : {}),
+        ...(options?.notes ? { notes: options.notes } : {}),
+    };
+}
+//# sourceMappingURL=roles.js.map

package/dist/roles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles.js","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"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"}