Playbook Salesforce in 2026: Step-by-Step

// File: scripts/init-playbook.ts
// Description: Initializes 2026-ready Salesforce Playbook project with pinned dependencies
// Requires: Node.js v20.18.0+, Salesforce CLI v68.0.0+

import { execSync } from 'node:child_process';
import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
import { resolve } from 'node:path';
import { Config } from './types/playbook-config.js';
import { Logger } from './utils/logger.js';
import { VersionValidator } from './utils/version-validator.js';

// Pinned dependency versions for 2026 compliance
const PINNED_DEPS = {
  '@salesforce/cli': '68.0.0',
  '@salesforce/playbook-sdk': '3.2.0',
  '@salesforce/sfdx-plugin-playbook': '2.1.4',
  'typescript': '5.6.3',
  'eslint': '8.56.0',
  'jest': '29.7.0'
} as const;

// Supported Salesforce orgs for 2026 Playbook
const SUPPORTED_ORGS = ['developer', 'enterprise', 'performance'] as const;

/**
 * Main initialization function with full error handling
 */
async function initPlaybookProject(config: Config): Promise {
  const logger = new Logger('init-playbook');
  const validator = new VersionValidator();

  try {
    // Validate Node.js version
    const nodeVersion = process.version;
    if (!validator.isNodeVersionSupported(nodeVersion)) {
      throw new Error(`Unsupported Node.js version: ${nodeVersion}. Requires v20.18.0+`);
    }

    // Validate Salesforce CLI version
    const sfVersion = execSync('sf --version').toString().trim();
    if (!validator.isSfVersionSupported(sfVersion)) {
      throw new Error(`Unsupported Salesforce CLI version: ${sfVersion}. Requires v68.0.0+`);
    }

    // Create project directory structure
    const projectPath = resolve(process.cwd(), config.projectName);
    if (existsSync(projectPath)) {
      throw new Error(`Project directory ${projectPath} already exists. Delete or choose a different name.`);
    }

    mkdirSync(projectPath, { recursive: true });
    logger.info(`Created project directory: ${projectPath}`);

    // Write package.json with pinned dependencies
    const packageJson = {
      name: config.projectName,
      version: '0.0.1',
      description: `2026-ready Salesforce Playbook for ${config.industry}`,
      scripts: {
        'build': 'tsc',
        'test': 'jest',
        'deploy': 'sf playbook deploy --target-org ${SF_ORG}',
        'telemetry': 'node scripts/stream-telemetry.ts'
      },
      dependencies: PINNED_DEPS,
      engines: {
        node: '>=20.18.0',
        npm: '>=10.2.0'
      }
    };

    writeFileSync(
      resolve(projectPath, 'package.json'),
      JSON.stringify(packageJson, null, 2)
    );
    logger.info('Wrote package.json with pinned dependencies');

    // Initialize TypeScript config
    const tsConfig = {
      compilerOptions: {
        target: 'ES2022',
        module: 'Node16',
        moduleResolution: 'Node16',
        outDir: './dist',
        rootDir: './src',
        strict: true,
        esModuleInterop: true,
        skipLibCheck: true,
        forceConsistentCasingInFileNames: true
      },
      include: ['src/**/*'],
      exclude: ['node_modules', 'dist']
    };

    writeFileSync(
      resolve(projectPath, 'tsconfig.json'),
      JSON.stringify(tsConfig, null, 2)
    );
    logger.info('Wrote tsconfig.json');

    // Authenticate to Salesforce org
    if (config.authMethod === 'sfdx') {
      execSync(`sf org login ${config.orgType} --alias ${config.projectName}-org`, { stdio: 'inherit' });
    } else {
      throw new Error(`Unsupported auth method: ${config.authMethod}. Use 'sfdx' for 2026 Playbook.`);
    }

    logger.info('Project initialization complete. Run npm install to install dependencies.');
  } catch (error) {
    logger.error('Initialization failed:', error);
    // Cleanup partial project directory on failure
    if (existsSync(projectPath)) {
      execSync(`rm -rf ${projectPath}`);
      logger.info('Cleaned up partial project directory');
    }
    process.exit(1);
  }
}

// Example config for B2B Commerce Playbook
const exampleConfig: Config = {
  projectName: 'b2b-commerce-playbook-2026',
  industry: 'B2B Commerce',
  orgType: 'enterprise',
  authMethod: 'sfdx',
  dataResidency: 'eu' // Options: us, eu, cn (2026 compliance)
};

// Run initialization if script is called directly
if (require.main === module) {
  initPlaybookProject(exampleConfig);
}

// File: src/sdk/playbook-wrapper.ts
// Description: 2026-compliant wrapper for @salesforce/playbook-sdk with data residency enforcement
// Requires: @salesforce/playbook-sdk v3.2.0+

import { PlaybookClient, PlaybookConfig, ResidencyRegion } from '@salesforce/playbook-sdk';
import { Logger } from '../utils/logger.js';
import { AuditLogger } from './audit-logger.js';
import { TelemetryClient } from './telemetry-client.js';
import { RateLimiter } from '../utils/rate-limiter.js';
import { ConfigurationError, DeploymentError, ResidencyError } from '../types/errors.js';

// 2026 data residency regions (per Salesforce 2026 Data Policy)
const RESIDENCY_REGIONS: Record = {
  'us': ResidencyRegion.US,
  'eu': ResidencyRegion.EU,
  'cn': ResidencyRegion.CN,
  'aus': ResidencyRegion.AUS // Added in SDK v3.2.0
};

// Default playbook configuration for 2026 compliance
const DEFAULT_PLAYBOOK_CONFIG: Partial = {
  enableAuditLogs: true,
  enableTelemetry: true,
  faultTolerance: 0.9999, // 99.99% uptime requirement
  maxRetries: 3,
  timeoutMs: 30000
};

/**
 * Wrapper class for Salesforce Playbook SDK with 2026 compliance features
 */
export class PlaybookWrapper {
  private client: PlaybookClient;
  private logger: Logger;
  private auditLogger: AuditLogger;
  private telemetry: TelemetryClient;
  private rateLimiter: RateLimiter;
  private residencyRegion: ResidencyRegion;

  /**
   * Initialize PlaybookWrapper with configuration
   * @param config - Playbook configuration object
   * @param residency - Data residency region (us/eu/cn/aus)
   */
  constructor(config: PlaybookConfig, residency: string) {
    this.logger = new Logger('playbook-wrapper');
    this.auditLogger = new AuditLogger();
    this.telemetry = new TelemetryClient();
    this.rateLimiter = new RateLimiter({ maxRequests: 100, perMs: 60000 }); // 100 req/min

    // Validate residency region
    if (!RESIDENCY_REGIONS[residency]) {
      throw new ResidencyError(`Unsupported residency region: ${residency}. Valid: ${Object.keys(RESIDENCY_REGIONS).join(', ')}`);
    }
    this.residencyRegion = RESIDENCY_REGIONS[residency];

    // Merge default config with user config
    const mergedConfig: PlaybookConfig = {
      ...DEFAULT_PLAYBOOK_CONFIG,
      ...config,
      residencyRegion: this.residencyRegion
    };

    try {
      this.client = new PlaybookClient(mergedConfig);
      this.logger.info(`Initialized PlaybookClient for region: ${residency}`);
    } catch (error) {
      this.logger.error('Failed to initialize PlaybookClient:', error);
      throw new ConfigurationError(`Playbook client initialization failed: ${error.message}`);
    }
  }

  /**
   * Deploy a playbook flow with full error handling and audit logging
   * @param flowPath - Path to playbook flow definition YAML
   * @param targetOrg - Salesforce target org alias
   */
  async deployFlow(flowPath: string, targetOrg: string): Promise {
    const deploymentId = crypto.randomUUID();
    this.auditLogger.log({
      action: 'DEPLOY_FLOW_START',
      deploymentId,
      flowPath,
      targetOrg,
      timestamp: new Date().toISOString()
    });

    try {
      // Apply rate limiting
      await this.rateLimiter.acquire();

      // Validate flow before deployment
      const flowValidation = await this.client.validateFlow(flowPath);
      if (!flowValidation.isValid) {
        throw new DeploymentError(`Flow validation failed: ${flowValidation.errors.join(', ')}`);
      }

      // Deploy flow with 99.99% fault tolerance
      const deploymentResult = await this.client.deployFlow({
        flowPath,
        targetOrg,
        enableRollback: true,
        rollbackOnFailure: true
      });

      if (!deploymentResult.success) {
        throw new DeploymentError(`Deployment failed: ${deploymentResult.error}`);
      }

      // Log success to audit and telemetry
      this.auditLogger.log({
        action: 'DEPLOY_FLOW_SUCCESS',
        deploymentId,
        flowPath,
        targetOrg,
        timestamp: new Date().toISOString()
      });
      this.telemetry.trackEvent('playbook_flow_deployed', {
        flowPath,
        targetOrg,
        deploymentTimeMs: deploymentResult.durationMs
      });

      this.logger.info(`Successfully deployed flow ${flowPath} to ${targetOrg} (ID: ${deploymentId})`);
    } catch (error) {
      // Log failure to audit and telemetry
      this.auditLogger.log({
        action: 'DEPLOY_FLOW_FAILURE',
        deploymentId,
        flowPath,
        targetOrg,
        error: error.message,
        timestamp: new Date().toISOString()
      });
      this.telemetry.trackEvent('playbook_flow_deploy_failed', {
        flowPath,
        targetOrg,
        error: error.message
      });
      this.logger.error(`Deployment failed for ${flowPath}:`, error);
      throw error; // Re-throw for upstream handling
    }
  }

  /**
   * Get playbook execution metrics for 2026 compliance reporting
   */
  async getComplianceMetrics(): Promise> {
    const metrics = await this.client.getMetrics();
    return {
      'deployment_success_rate': metrics.deploymentSuccessRate,
      'p99_latency_ms': metrics.p99LatencyMs,
      'fault_tolerance': metrics.faultTolerance,
      'data_residency_compliance': metrics.residencyCompliance ? 1 : 0
    };
  }
}

// File: scripts/stream-telemetry.ts
// Description: Streams real-time Playbook telemetry to Datadog and Prometheus
// Requires: @datadog/datadog-api-client v12.0.0+, prom-client v15.1.0+

import { createWriteStream } from 'node:fs';
import { createServer } from 'node:http';
import { DatadogApiClient, MetricsApi } from '@datadog/datadog-api-client';
import { register, Counter, Histogram, Gauge } from 'prom-client';
import { PlaybookWrapper } from '../src/sdk/playbook-wrapper.js';
import { Logger } from '../src/utils/logger.js';
import { ConfigLoader } from '../src/utils/config-loader.js';

// Telemetry metrics definitions
const playbookDeployments = new Counter({
  name: 'salesforce_playbook_deployments_total',
  help: 'Total number of Playbook deployments',
  labelNames: ['org_type', 'region', 'status']
});

const playbookLatency = new Histogram({
  name: 'salesforce_playbook_deployment_latency_ms',
  help: 'Playbook deployment latency in milliseconds',
  labelNames: ['org_type', 'region'],
  buckets: [100, 500, 1000, 2000, 5000]
});

const playbookCompliance = new Gauge({
  name: 'salesforce_playbook_compliance_status',
  help: '1 if compliant with 2026 data residency, 0 otherwise',
  labelNames: ['region']
});

/**
 * Main telemetry streaming function
 */
async function streamTelemetry(): Promise {
  const logger = new Logger('stream-telemetry');
  const config = ConfigLoader.load();

  // Initialize Datadog client
  const datadogClient = new DatadogApiClient();
  datadogClient.configure({
    apiKey: config.datadogApiKey,
    appKey: config.datadogAppKey,
    site: 'datadoghq.eu' // Match residency region
  });
  const metricsApi = new MetricsApi(datadogClient);

  // Initialize Playbook wrapper
  const playbook = new PlaybookWrapper(
    { targetOrg: config.targetOrg },
    config.dataResidency
  );

  // Start Prometheus metrics server
  const metricsServer = createServer(async (req, res) => {
    if (req.url === '/metrics') {
      res.setHeader('Content-Type', register.contentType);
      res.end(await register.metrics());
    } else {
      res.statusCode = 404;
      res.end('Not found');
    }
  });

  metricsServer.listen(9090, () => {
    logger.info('Prometheus metrics server listening on port 9090');
  });

  // Stream telemetry every 30 seconds
  setInterval(async () => {
    try {
      // Get compliance metrics from Playbook wrapper
      const metrics = await playbook.getComplianceMetrics();

      // Update Prometheus metrics
      playbookCompliance.set(
        { region: config.dataResidency },
        metrics.data_residency_compliance
      );

      // Send to Datadog
      await metricsApi.submitMetrics({
        body: {
          series: [
            {
              metric: 'salesforce.playbook.deployment_success_rate',
              points: [{ timestamp: Math.floor(Date.now() / 1000), value: metrics.deployment_success_rate }],
              tags: [`region:${config.dataResidency}`, `org:${config.targetOrg}`]
            },
            {
              metric: 'salesforce.playbook.p99_latency',
              points: [{ timestamp: Math.floor(Date.now() / 1000), value: metrics.p99_latency_ms }],
              tags: [`region:${config.dataResidency}`, `org:${config.targetOrg}`]
            }
          ]
        }
      });

      logger.info(`Streamed telemetry for region ${config.dataResidency}`);
    } catch (error) {
      logger.error('Failed to stream telemetry:', error);
      // Retry once on failure
      setTimeout(async () => {
        try {
          await streamTelemetry();
        } catch (retryError) {
          logger.error('Telemetry retry failed:', retryError);
        }
      }, 5000);
    }
  }, 30000);

  // Log stream start
  logger.info(`Started telemetry streaming for Playbook ${config.projectName}`);
}

// Handle process termination
process.on('SIGTERM', () => {
  logger.info('Received SIGTERM, stopping telemetry stream');
  process.exit(0);
});

// Run if script is called directly
if (require.main === module) {
  streamTelemetry().catch((error) => {
    logger.error('Telemetry stream failed to start:', error);
    process.exit(1);
  });
}

const { execSync } = require('node:child_process');
const sfVersion = execSync('sf --version').toString().trim();
if (!sfVersion.includes('68.0.0')) {
  throw new Error(`Unsupported SF CLI version: ${sfVersion}`);
}

const { PlaybookClient } = require('@salesforce/playbook-sdk');
const client = new PlaybookClient({ residencyRegion: 'eu' });
const compliance = await client.checkResidencyCompliance();
if (!compliance.isCompliant) {
  throw new Error(`Residency violation: ${compliance.violations.join(', ')}`);
}

const { RateLimiter } = require('./utils/rate-limiter.js');
const limiter = new RateLimiter({ maxRequests: 100, perMs: 60000 });
await limiter.acquire(); // Blocks until a token is available
await playbookClient.deployFlow(flowPath, targetOrg);

2026-playbook-guide/
├── src/
│   ├── sdk/
│   │   ├── playbook-wrapper.ts
│   │   ├── audit-logger.ts
│   │   └── telemetry-client.ts
│   ├── utils/
│   │   ├── logger.ts
│   │   ├── version-validator.ts
│   │   └── rate-limiter.ts
│   └── types/
│       ├── playbook-config.ts
│       └── errors.ts
├── scripts/
│   ├── init-playbook.ts
│   ├── stream-telemetry.ts
│   └── migrate-legacy-playbook.ts
├── .github/
│   └── workflows/
│       └── deploy-playbook.yml
├── package.json
├── tsconfig.json
└── README.md