docs(testing): add PlanAction JWT hydration implementation guide

Add comprehensive implementation guide for creating PlanAction claims via hydratePlan() function pattern, following established hydrateGive() and hydrateOffer() patterns. Changes: - Add hydrate-plan-implementation-guide.md with complete implementation details, usage examples, and testing recommendations - Link implementation guide from getting-valid-plan-ids.md Method 6 - Link implementation guide from localhost-testing-guide.md Option B The guide provides: - Complete hydratePlan() function implementation - PlanActionClaim interface structure - Helper functions (createAndSubmitPlan, editAndSubmitPlan) - Usage examples and edge cases - Testing recommendations and security considerations This complements plan creation documentation by showing how to programmatically construct valid PlanAction JWTs for POST /api/v2/claim.
4 days ago · ed5dcfbbd1
3 changed files with 572 additions and 0 deletions
--- a/docs/getting-valid-plan-ids.md
+++ b/docs/getting-valid-plan-ids.md
@ -78,6 +78,12 @@ Plans are created by importing JWT claims containing a `PlanAction`:
 - JWT must be signed with a valid DID key
 - Response includes `handleId` and `planId` if creation succeeds
 **Implementation Guide**: See [`docs/hydrate-plan-implementation-guide.md`](./hydrate-plan-implementation-guide.md) for complete implementation details, including:
 - `hydratePlan()` function pattern
 - PlanActionClaim interface structure
 - Helper functions for create/edit operations
 - Usage examples and testing recommendations
 **Note**: This method requires generating signed JWTs with DID keys, which is complex. **Method 1 (TimeSafari App UI) is recommended** for creating test plans.
 ## Plan Handle ID Format
--- a/docs/hydrate-plan-implementation-guide.md
+++ b/docs/hydrate-plan-implementation-guide.md
@ -0,0 +1,564 @@
 # Directive: hydratePlan Implementation Guide
 **Author**: Matthew Raymer
 **Date**: 2025-10-29 12:38:40 UTC
 **Status**: 🎯 **ACTIVE** - Implementation directive for PlanActionClaim hydration
 ## Overview
 This directive provides a complete implementation guide for creating a
 `hydratePlan()` function that follows the same pattern as `hydrateGive()` and
 `hydrateOffer()`. This function constructs and hydrates `PlanActionClaim`
 entities (projects) for submission to the endorser server.
 ## Pattern Reference
 The `hydratePlan()` function should follow the established pattern from:
 - **`hydrateGive()`** (`src/libs/endorserServer.ts:831-920`)
 - **`hydrateOffer()`** (`src/libs/endorserServer.ts:1018-1072`)
 ### Key Pattern Elements
 1. **Function Signature**: Accepts optional original claim and parameters
 2. **Clone or Create**: Clone existing claim or create new base structure
 3. **Edit Detection**: Handle `lastClaimId` for edit operations
 4. **Field Hydration**: Set optional fields only when provided
 5. **Cleanup**: Use `undefined` to remove fields (not empty strings)
 6. **Return**: Return properly typed claim object
 ## PlanActionClaim Interface
 ```typescript
 export interface PlanActionClaim extends ClaimObject {
  "@context": "https://schema.org";
  "@type": "PlanAction";
  name: string;                              // REQUIRED
  agent?: { identifier: string };            // Optional: creator DID
  description?: string;                      // Optional: project description
  endTime?: string;                          // Optional: ISO 8601 date string
  identifier?: string;                       // Auto-set by server on first create
  image?: string;                            // Optional: image URL
  lastClaimId?: string;                      // Required for edits
  location?: {                               // Optional: geographic location
    geo: {
      "@type": "GeoCoordinates";
      latitude: number;
      longitude: number;
    };
  };
  startTime?: string;                        // Optional: ISO 8601 date string
  url?: string;                              // Optional: project URL
 }
 ```
 ## Implementation
 ### Function Signature
 ```typescript
 /**
 * Construct PlanAction VC for submission to server
 *
 * Creates or updates a PlanAction claim (project) with all optional fields
 * properly handled. Follows the same pattern as hydrateGive() and
 * hydrateOffer().
 *
 * @param vcClaimOrig - Optional existing claim to clone and modify
 * @param name - Required project name
 * @param agentDid - Optional DID of the project creator
 * @param description - Optional project description
 * @param startTime - Optional ISO 8601 start date/time string
 * @param endTime - Optional ISO 8601 end date/time string
 * @param imageUrl - Optional image URL for the project
 * @param url - Optional project URL
 * @param latitude - Optional location latitude
 * @param longitude - Optional location longitude
 * @param lastClaimId - Required when editing an existing project
 *
 * @returns Properly hydrated PlanActionClaim ready for submission
 *
 * @example
 * // Create new project
 * const claim = hydratePlan(
 *   undefined,
 *   "Community Garden Project",
 *   "did:ethr:0x123...",
 *   "Building a community garden",
 *   "2025-06-01T00:00:00Z",
 *   "2025-08-31T23:59:59Z"
 * );
 *
 * @example
 * // Edit existing project
 * const updated = hydratePlan(
 *   existingClaim,
 *   "Updated Project Name",
 *   "did:ethr:0x123...",
 *   "New description",
 *   undefined,
 *   undefined,
 *   undefined,
 *   undefined,
 *   undefined,
 *   undefined,
 *   "01ABC123..." // lastClaimId
 * );
 */
 export function hydratePlan(
  vcClaimOrig?: PlanActionClaim,
  name?: string,
  agentDid?: string,
  description?: string,
  startTime?: string,
  endTime?: string,
  imageUrl?: string,
  url?: string,
  latitude?: number,
  longitude?: number,
  lastClaimId?: string,
 ): PlanActionClaim {
  // Clone existing claim or create base structure
  const vcClaim: PlanActionClaim = vcClaimOrig
    ? R.clone(vcClaimOrig)
    : {
        "@context": SCHEMA_ORG_CONTEXT,
        "@type": "PlanAction",
      };
  // Handle edit operation (lastClaimId indicates edit)
  if (lastClaimId) {
    vcClaim.lastClaimId = lastClaimId;
    // Remove identifier on edit - server assigns new one
    delete vcClaim.identifier;
  }
  // Set required name field (must be provided for new claims)
  if (name) {
    vcClaim.name = name;
  }
  // Handle agent (creator DID)
  if (agentDid) {
    vcClaim.agent = { identifier: agentDid };
  } else {
    // Remove agent if not provided (allows clearing)
    delete vcClaim.agent;
  }
  // Handle description
  vcClaim.description = description || undefined;
  // Handle start time (ISO 8601 format required)
  if (startTime) {
    // Validate it's a proper ISO 8601 string
    try {
      const date = new Date(startTime);
      if (isNaN(date.getTime())) {
        throw new Error("Invalid startTime format");
      }
      vcClaim.startTime = startTime;
    } catch {
      // Invalid date - remove the field
      delete vcClaim.startTime;
    }
  } else {
    delete vcClaim.startTime;
  }
  // Handle end time (ISO 8601 format required)
  if (endTime) {
    try {
      const date = new Date(endTime);
      if (isNaN(date.getTime())) {
        throw new Error("Invalid endTime format");
      }
      vcClaim.endTime = endTime;
    } catch {
      delete vcClaim.endTime;
    }
  } else {
    delete vcClaim.endTime;
  }
  // Handle image URL
  vcClaim.image = imageUrl || undefined;
  // Handle project URL
  vcClaim.url = url || undefined;
  // Handle location (both latitude and longitude required)
  if (latitude !== undefined && longitude !== undefined) {
    // Validate coordinates are numbers
    if (
      typeof latitude === "number" &&
      typeof longitude === "number" &&
      !isNaN(latitude) &&
      !isNaN(longitude)
    ) {
      vcClaim.location = {
        geo: {
          "@type": "GeoCoordinates",
          latitude,
          longitude,
        },
      };
    } else {
      // Invalid coordinates - remove location
      delete vcClaim.location;
    }
  } else {
    // Remove location if either coordinate missing
    delete vcClaim.location;
  }
  return vcClaim;
 }
 ```
 ## Helper Functions (Recommended)
 Following the pattern from `createAndSubmitGive()` and
 `createAndSubmitOffer()`, create wrapper functions:
 ### Create and Submit
 ```typescript
 /**
 * Create and submit a new PlanAction claim
 *
 * @param axios - Axios instance for HTTP requests
 * @param apiServer - Endorser API server URL
 * @param issuerDid - DID to sign the claim (must match agentDid or
 *                    be authorized)
 * @param name - Required project name
 * @param agentDid - Optional creator DID
 * @param description - Optional project description
 * @param startTime - Optional ISO 8601 start time
 * @param endTime - Optional ISO 8601 end time
 * @param imageUrl - Optional image URL
 * @param url - Optional project URL
 * @param latitude - Optional location latitude
 * @param longitude - Optional location longitude
 *
 * @returns Promise with submission result (handleId, claimId, etc.)
 */
 export async function createAndSubmitPlan(
  axios: Axios,
  apiServer: string,
  issuerDid: string,
  name: string,
  agentDid?: string,
  description?: string,
  startTime?: string,
  endTime?: string,
  imageUrl?: string,
  url?: string,
  latitude?: number,
  longitude?: number,
 ): Promise<CreateAndSubmitClaimResult> {
  const vcClaim = hydratePlan(
    undefined,
    name,
    agentDid,
    description,
    startTime,
    endTime,
    imageUrl,
    url,
    latitude,
    longitude,
    undefined, // No lastClaimId for new claims
  );
  return createAndSubmitClaim(
    vcClaim as GenericVerifiableCredential,
    issuerDid,
    apiServer,
    axios,
  );
 }
 ```
 ### Edit and Submit
 ```typescript
 /**
 * Edit and submit an existing PlanAction claim
 *
 * @param axios - Axios instance for HTTP requests
 * @param apiServer - Endorser API server URL
 * @param fullClaim - Existing claim wrapper with ID
 * @param issuerDid - DID to sign the claim
 * @param name - Updated project name (if changed)
 * @param agentDid - Updated creator DID (if changed)
 * @param description - Updated description (if changed)
 * @param startTime - Updated start time (if changed)
 * @param endTime - Updated end time (if changed)
 * @param imageUrl - Updated image URL (if changed)
 * @param url - Updated project URL (if changed)
 * @param latitude - Updated location latitude (if changed)
 * @param longitude - Updated location longitude (if changed)
 *
 * @returns Promise with submission result
 */
 export async function editAndSubmitPlan(
  axios: Axios,
  apiServer: string,
  fullClaim: GenericCredWrapper<PlanActionClaim>,
  issuerDid: string,
  name?: string,
  agentDid?: string,
  description?: string,
  startTime?: string,
  endTime?: string,
  imageUrl?: string,
  url?: string,
  latitude?: number,
  longitude?: number,
 ): Promise<CreateAndSubmitClaimResult> {
  const vcClaim = hydratePlan(
    fullClaim.claim,
    name,
    agentDid,
    description,
    startTime,
    endTime,
    imageUrl,
    url,
    latitude,
    longitude,
    fullClaim.id, // Use existing claim ID for edit
  );
  return createAndSubmitClaim(
    vcClaim as GenericVerifiableCredential,
    issuerDid,
    apiServer,
    axios,
  );
 }
 ```
 ## Required Dependencies
 Ensure these imports are available:
 ```typescript
 import * as R from "ramda"; // For R.clone()
 import { Axios } from "axios";
 import { PlanActionClaim } from "../interfaces/claims";
 import { 
  GenericCredWrapper,
  GenericVerifiableCredential,
  CreateAndSubmitClaimResult 
 } from "../interfaces/common";
 // Constants
 export const SCHEMA_ORG_CONTEXT = "https://schema.org";
 ```
 ## Usage Examples
 ### Example 1: Create Simple Project
 ```typescript
 const claim = hydratePlan(
  undefined,              // New claim
  "My Project",          // Required name
  "did:ethr:0x123...",   // Creator DID
  "Project description"  // Description
 );
 // Result:
 // {
 //   "@context": "https://schema.org",
 //   "@type": "PlanAction",
 //   "name": "My Project",
 //   "agent": { "identifier": "did:ethr:0x123..." },
 //   "description": "Project description"
 // }
 ```
 ### Example 2: Create Project with Dates and Location
 ```typescript
 const claim = hydratePlan(
  undefined,
  "Community Event",
  "did:ethr:0x456...",
  "Annual community gathering",
  "2025-07-01T10:00:00Z",  // Start time
  "2025-07-03T18:00:00Z",  // End time
  "https://example.com/img.jpg",  // Image
  "https://example.com/event",     // URL
  40.7128,  // Latitude
  -74.0060  // Longitude
 );
 ```
 ### Example 3: Edit Existing Project
 ```typescript
 const existingClaim: PlanActionClaim = {
  "@context": "https://schema.org",
  "@type": "PlanAction",
  "name": "Old Name",
  "identifier": "01ABC123...",
  // ... other fields
 };
 const updated = hydratePlan(
  existingClaim,         // Original claim to clone
  "New Name",            // Updated name
  "did:ethr:0x123...",   // Keep same agent
  "Updated description", // Updated description
  undefined,             // Keep existing startTime
  undefined,             // Keep existing endTime
  undefined,             // Keep existing image
  undefined,             // Keep existing url
  undefined,             // Keep existing location
  undefined,             // Keep existing location
  "01ABC123..."          // Required: lastClaimId
 );
 // Result will have:
 // - lastClaimId: "01ABC123..."
 // - identifier: undefined (removed for edit)
 // - Updated name and description
 // - All other fields preserved from original
 ```
 ### Example 4: Remove Location from Existing Project
 ```typescript
 const updated = hydratePlan(
  existingClaim,
  existingClaim.name,     // Keep name
  existingClaim.agent?.identifier,
  existingClaim.description,
  existingClaim.startTime,
  existingClaim.endTime,
  existingClaim.image,
  existingClaim.url,
  undefined,  // latitude undefined = remove location
  undefined,  // longitude undefined = remove location
  "01ABC123..."
 );
 ```
 ## Important Notes
 ### Date/Time Handling
 - **Format**: All date/time strings must be ISO 8601 format
 - **Validation**: Function validates date strings but caller should ensure
  proper format
 - **Timezone**: Include timezone information (Z for UTC, or +/- offset)
 - **Example**: `"2025-06-01T10:00:00Z"` or `"2025-06-01T10:00:00-05:00"`
 ### Location Handling
 - **Both Required**: Both `latitude` and `longitude` must be provided
  together, or both omitted
 - **Validation**: Coordinates must be valid numbers (not NaN)
 - **Removal**: Setting either to `undefined` removes the entire location
  object
 - **Range**: Latitude: -90 to 90, Longitude: -180 to 180 (validation
  recommended)
 ### Edit Operations
 - **lastClaimId Required**: Must provide `lastClaimId` when editing
 - **identifier Removed**: Server assigns new identifier on edit
 - **Field Preservation**: Only explicitly changed fields are modified;
  others preserved from original
 - **Undefined vs Missing**: Use `undefined` to explicitly remove optional
  fields
 ### Field Cleanup
 - **Use undefined**: Set fields to `undefined` rather than empty strings
 - **Delete for Edit**: For edits, explicitly delete fields that should be
  removed
 - **Optional Field Pattern**: Check existence before setting to preserve
  optional nature
 ## Testing Recommendations
 ### Unit Tests
 Test the following scenarios:
 1. **New Claim Creation**
   - Minimum required fields (name only)
   - All optional fields provided
   - Validate structure matches interface
 2. **Edit Operations**
   - Clone existing claim correctly
   - lastClaimId sets identifier removal
   - Partial field updates preserve other fields
 3. **Field Validation**
   - Invalid date strings removed
   - Location requires both coordinates
   - Undefined fields properly handled
 4. **Edge Cases**
   - Empty string handling (should become undefined)
   - NaN coordinate values
   - Missing required fields on new claims
 ### Integration Tests
 Test with actual server submission:
 ```typescript
 // Test createAndSubmitPlan
 const result = await createAndSubmitPlan(
  axiosInstance,
  "https://test-api.endorser.ch",
  testDid,
  "Test Project",
  testDid,
  "Test description"
 );
 expect(result.success).toBe(true);
 expect(result.handleId).toBeDefined();
 ```
 ## Security Considerations
 1. **DID Validation**: Validate agentDid matches issuerDid or is authorized
 2. **Date Validation**: Ensure date strings don't contain injection attempts
 3. **URL Validation**: Validate image and URL fields are proper URLs
 4. **Coordinate Validation**: Ensure lat/lng are within valid ranges
 ## References
 - **hydrateGive()**: `src/libs/endorserServer.ts:831-920`
 - **hydrateOffer()**: `src/libs/endorserServer.ts:1018-1072`
 - **PlanActionClaim Interface**: `src/interfaces/claims.ts:76-91`
 - **Pattern Example**: `src/views/NewEditProjectView.vue:536-597`
 ## Implementation Checklist
 - [ ] Implement `hydratePlan()` function with all parameters
 - [ ] Add date/time validation logic
 - [ ] Add location coordinate validation
 - [ ] Implement `createAndSubmitPlan()` wrapper
 - [ ] Implement `editAndSubmitPlan()` wrapper
 - [ ] Add comprehensive JSDoc comments
 - [ ] Write unit tests for all scenarios
 - [ ] Write integration tests with server
 - [ ] Update any existing code to use new function
 - [ ] Document breaking changes if refactoring existing code
 ---
 **Status**: Active implementation directive
 **Priority**: Medium
 **Estimated Effort**: 2-4 hours for complete implementation including tests
 **Dependencies**: Requires ramda, axios, and existing claim interfaces
 **Stakeholders**: Development team implementing claim hydration utilities
--- a/docs/localhost-testing-guide.md
+++ b/docs/localhost-testing-guide.md
@ -70,6 +70,8 @@ If you have your own localhost API server, you must create plans first. Plans ar
 **Note**: Creating PlanAction JWTs requires DID signing and proper claim structure, which is complex. For quick testing, **Option A (test API server) is recommended**.
 **Implementation Reference**: If you need to programmatically create PlanAction JWTs, see [`docs/hydrate-plan-implementation-guide.md`](./hydrate-plan-implementation-guide.md) for the complete implementation pattern, including `hydratePlan()` function and helper utilities.
 Then verify your setup:
 ```bash