plugins.ts

/**
 * Example script demonstrating the plugin framework.
 *
 * This example shows how to:
 * 1. Define a plugin with custom fields via `definePlugin({ schemas })`
 * 2. Access the typed `common` schema for validation
 * 3. Read typed custom field values directly
 *
 * Run with: pnpm example:plugins
 */

import { z } from "zod";
import { CustomFieldType } from "../src/constants";
import { definePlugin } from "../src/extensions";

// ############################################################################
// Step 1: Define independent plugins
// ############################################################################

// Plugin for backward compatibility with a legacy grants system
const LegacyIdValueSchema = z.object({
  system: z.string(),
  id: z.number().int(),
});

const legacyPlugin = definePlugin({
  schemas: {
    Opportunity: {
      customFields: {
        legacyId: {
          fieldType: CustomFieldType.object,
          value: LegacyIdValueSchema,
          description: "Maps to the opportunity_id in the legacy system",
        },
      },
    },
  },
} as const);

// Plugin for grant categorization
const classificationPlugin = definePlugin({
  schemas: {
    Opportunity: {
      customFields: {
        category: {
          fieldType: CustomFieldType.string,
          description: "Grant category",
        },
        priority: {
          fieldType: CustomFieldType.integer,
          description: "Processing priority (1 = highest)",
        },
      },
    },
  },
} as const);

// ############################################################################
// Step 2: Use standalone plugins
// ############################################################################

// Sample data shared by all examples
const baseData = {
  id: "573525f2-8e15-4405-83fb-e6523511d893",
  title: "STEM Education Grant Program",
  description: "A grant program focused on STEM education in underserved communities",
  status: { value: "open" },
  createdAt: "2025-01-01T00:00:00Z",
  lastModifiedAt: "2025-01-15T00:00:00Z",
};

function demonstrateStandalonePlugins() {
  console.log("--- Standalone plugins ---\n");

  // Legacy plugin schema validates and types its own fields
  const legacyOpp = legacyPlugin.schemas.Opportunity.commonSchema.parse({
    ...baseData,
    customFields: {
      legacyId: {
        name: "legacyId",
        fieldType: CustomFieldType.object,
        value: { system: "grants-v1", id: 42 },
      },
    },
  });

  // Direct typed access — no helper needed
  const legacyId = legacyOpp.customFields?.legacyId?.value;
  console.log(`  legacyId.system: ${legacyId?.system}`);
  console.log(`  legacyId.id:     ${legacyId?.id} (typed as number)\n`);

  // Classification plugin schema validates its fields
  const classOpp = classificationPlugin.schemas.Opportunity.commonSchema.parse({
    ...baseData,
    customFields: {
      category: {
        name: "category",
        fieldType: CustomFieldType.string,
        value: "STEM Education",
      },
      priority: {
        name: "priority",
        fieldType: CustomFieldType.integer,
        value: 1,
      },
    },
  });

  console.log(`  category: ${classOpp.customFields?.category?.value} (typed as string)`);
  console.log(`  priority: ${classOpp.customFields?.priority?.value} (typed as number)`);
}

// ############################################################################
// Step 3: Demonstrate validation
// ############################################################################

function demonstrateValidation() {
  console.log("\n--- Validation ---\n");

  const combinedPlugin = definePlugin({
    schemas: {
      Opportunity: {
        customFields: {
          priority: {
            fieldType: CustomFieldType.integer,
            description: "Processing priority (1 = highest)",
          },
        },
      },
    },
  } as const);

  const oppData = {
    ...baseData,
    customFields: {
      priority: {
        name: "priority",
        fieldType: CustomFieldType.integer,
        value: "not-a-number",
      },
    },
  };

  console.log("Invalid custom field data:");
  console.log(JSON.stringify(oppData, null, 2));
  console.log();

  const result = combinedPlugin.schemas.Opportunity.commonSchema.safeParse(oppData);

  if (!result.success) {
    const issue = result.error.issues[0];
    console.log("Validation failed (as expected):");
    console.log(`  Path:    ${issue.path.join(".")}`);
    console.log(`  Message: ${issue.message}`);
  }
}

// ############################################################################
// Run
// ############################################################################

function main() {
  console.log("=== Plugins Example ===\n");
  demonstrateStandalonePlugins();
  demonstrateValidation();
  console.log("\n=== Example Complete ===");
}

main();