@aws-blocks/core 0.1.0

package/src/telemetry/trackCommand.ts

@@ -0,0 +1,110 @@
+import type { CommandName, CommandState, TrackCommandOptions } from './types.js';
+import { isTelemetryEnabled } from './consent.js';
+import { buildAndSendEvent } from './client.js';
+
+/**
+ * Classify a caught error into a telemetry-safe error code.
+ * Only inspects the error message for known patterns — never transmits raw messages.
+ */
+export function classifyError(error: unknown): { code: string; phase: string } {
+  if (!(error instanceof Error)) return { code: 'UNKNOWN', phase: 'unknown' };
+  const msg = error.message.toLowerCase();
+
+  if (msg.includes('eaddrinuse') || (msg.includes('port') && msg.includes('in use'))) {
+    return { code: 'PORT_IN_USE', phase: 'startup' };
+  }
+  if (msg.includes('access denied') || msg.includes('not authorized') || msg.includes('forbidden')) {
+    return { code: 'PERMISSION_DENIED', phase: 'auth' };
+  }
+  if (msg.includes('credentials') || msg.includes('no credentials') || msg.includes('security token')) {
+    return { code: 'CREDENTIALS_FAILED', phase: 'auth' };
+  }
+  if (msg.includes('cdk synth') || msg.includes('synthesis')) {
+    return { code: 'CDK_SYNTH_FAILED', phase: 'synth' };
+  }
+  if (msg.includes('cdk deploy') || msg.includes('deployment failed')) {
+    return { code: 'CDK_DEPLOY_FAILED', phase: 'deploy' };
+  }
+  if (msg.includes('cdk destroy') || msg.includes('destroy failed')) {
+    return { code: 'CDK_DESTROY_FAILED', phase: 'destroy' };
+  }
+  if (msg.includes('npm install') || msg.includes('npm err')) {
+    return { code: 'NPM_INSTALL_FAILED', phase: 'install' };
+  }
+  if (msg.includes('codegen') || msg.includes('generate client')) {
+    return { code: 'CODEGEN_FAILED', phase: 'codegen' };
+  }
+  if (msg.includes('vite') || msg.includes('next build') || msg.includes('frontend build')) {
+    return { code: 'FRONTEND_BUILD_FAILED', phase: 'build' };
+  }
+  if (msg.includes('template') && msg.includes('copy')) {
+    return { code: 'TEMPLATE_COPY_FAILED', phase: 'init' };
+  }
+  if (msg.includes('argument') || msg.includes('parse')) {
+    return { code: 'ARG_PARSE_FAILED', phase: 'init' };
+  }
+
+  return { code: 'UNKNOWN', phase: 'unknown' };
+}
+
+/**
+ * Wrap a CLI command function with telemetry tracking.
+ *
+ * Measures wall-clock duration, classifies errors, and sends a single telemetry event
+ * after the command completes (success or failure). The telemetry send is fire-and-forget
+ * and bounded by a 5s timeout — it will never delay the command or affect its exit code.
+ *
+ * If telemetry is disabled (via env var or config), the function is executed directly
+ * with zero overhead.
+ *
+ * @param commandName - The command being tracked
+ * @param fn - The async function to execute
+ * @param options - Optional metadata (template, framework, etc.)
+ *
+ * @example
+ * ```ts
+ * await trackCommand('sandbox', async () => {
+ *   await startSandbox({ backendPath: '...' });
+ * });
+ * ```
+ */
+export async function trackCommand(
+  commandName: CommandName,
+  fn: () => Promise<void>,
+  options?: TrackCommandOptions,
+): Promise<void> {
+  if (!isTelemetryEnabled()) {
+    return fn();
+  }
+
+  const startTime = Date.now();
+  let state: CommandState = 'SUCCESS';
+  let errorInfo: { code: string; phase: string } | undefined;
+
+  try {
+    await fn();
+  } catch (error: unknown) {
+    state = 'FAIL';
+    errorInfo = classifyError(error);
+    throw error;
+  } finally {
+    const duration = Date.now() - startTime;
+    buildAndSendEvent({
+      command: commandName,
+      state,
+      duration,
+      ...(errorInfo && { error: errorInfo }),
+      ...(options && {
+        product: {
+          ...(options.cdkVersion && { cdkVersion: options.cdkVersion }),
+          ...(options.framework && { framework: options.framework }),
+          ...(options.template && { template: options.template }),
+          ...(options.templateVersion && { templateVersion: options.templateVersion }),
+        },
+      }),
+      ...(options?.blocksCount !== undefined && {
+        counters: { blocksCount: options.blocksCount },
+      }),
+    });
+  }
+}

package/src/telemetry/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Command names tracked by the Blocks CLI telemetry system.
+ */
+export type CommandName =
+  | 'create-blocks-app'
+  | 'dev'
+  | 'sandbox'
+  | 'sandbox:destroy'
+  | 'deploy'
+  | 'destroy'
+  | 'cleanup'
+  | 'console'
+  | 'vendorize';
+
+/**
+ * Terminal state of a command execution.
+ */
+export type CommandState = 'SUCCESS' | 'FAIL' | 'ABORTED';
+
+/**
+ * The telemetry event payload sent to the endpoint.
+ *
+ * Matches the server schema exactly (additionalProperties: false).
+ * All fields are anonymized — no PII, no customer content, no account IDs.
+ */
+export interface BlocksTelemetryEvent {
+  telemetryVersion: string;
+  identifiers: {
+    installationId: string;
+    projectId: string;
+    eventId: string;
+    timestamp: string;
+  };
+  event: {
+    command: CommandName;
+    state: CommandState;
+    duration: number;
+    error?: {
+      code: string;
+      phase: string;
+    };
+  };
+  environment: {
+    os: 'linux' | 'darwin' | 'win32';
+    nodeVersion: string;
+    ci: boolean;
+    packageManager?: string;
+    agent?: string;
+  };
+  product?: {
+    blocksVersion: string;
+    cdkVersion?: string;
+    framework?: 'nextjs' | 'spa' | 'static';
+    template?: { name: string; version?: string };
+    buildingBlocks?: Array<{ name: string; version: string }>;
+  };
+  counters?: {
+    blocksCount: number;
+    customBuildingBlocks?: number;
+  };
+}
+
+/**
+ * Options for the `trackCommand` utility.
+ */
+export interface TrackCommandOptions {
+  template?: string;
+  templateVersion?: string;
+  framework?: 'nextjs' | 'spa' | 'static';
+  cdkVersion?: string;
+  blocksCount?: number;
+}
+
+/**
+ * Options accepted by `buildAndSendEvent()`.
+ *
+ * Callers provide minimal metadata; the function resolves identifiers,
+ * environment, and consent internally.
+ */
+export interface BuildAndSendEventOptions {
+  command: CommandName;
+  state: CommandState;
+  duration: number;
+  error?: { code: string; phase: string };
+  product?: {
+    cdkVersion?: string;
+    framework?: 'nextjs' | 'spa' | 'static';
+    template?: string;
+    templateVersion?: string;
+  };
+  counters?: { blocksCount: number; customBuildingBlocks?: number };
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Construct } from 'constructs';
+
+/**
+ * Infrastructure layer function signature.
+ * Exported from `infra.ts` in a Building Block.
+ */
+export type MaterializeFn<TOptions = any> = (
+  scope: Construct,
+  name: string,
+  options: TOptions
+) => void | Record<string, any>;
+
+/**
+ * Building Block metadata discovered by Blocks.
+ */
+export interface BuildingBlockMetadata {
+  name: string;
+  runtimePath?: string;    // index.ts
+  infraPath?: string;       // infra.ts
+  mockPath?: string;        // mock.ts
+  clientHookPath?: string;  // client-hook.ts
+}
+
+/**
+ * Client-side protocol extension hook.
+ */
+export interface ClientSideAPIHook {
+  onResponse?(response: Response): Promise<void>;
+  onRequest?(request: Request): Promise<void>;
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+// Auto-generated by scripts/generate-version.mjs — do not edit manually
+export const CORE_VERSION = '0.1.0';