Skip to main content

OpenAPI Schema Additions for DPPS

File to Edit: valkyrai/src/main/resources/openapi/api.hbs.yaml

Instructions​

  1. Locate the Product schema in the components/schemas section
  2. Add the following properties to enhance digital product support:
# ADD TO Product schema (under components/schemas/Product/properties)

contentDataId:
  type: string
  format: uuid
  description: Reference to uploaded FileRecord or ContentData asset
  example: "550e8400-e29b-41d4-a716-446655440008"

deliveryMode:
  type: string
  enum:
    - DIGITAL_DOWNLOAD
    - STREAMING
    - LICENSE_KEY
    - PHYSICAL
  default: DIGITAL_DOWNLOAD
  description: How the product is delivered to the customer

maxDownloads:
  type: integer
  description: Maximum number of downloads allowed per purchase (-1 = unlimited)
  example: 5
  default: -1

expiresAfterDays:
  type: integer
  description: Days after purchase before entitlement expires (-1 = perpetual)
  example: 365
  default: -1

After Adding​

  1. Regenerate ThorAPI models:

    cd thorapi
    mvn clean install

  2. Rebuild ValkyrAI:

    cd ../valkyrai
    mvn clean install

  3. Verify Generated Files:

    • valkyrai/generated/spring/src/main/java/com/valkyrlabs/model/Product.java
    • Should now include:
      • private UUID contentDataId;
      • private DeliveryModeEnum deliveryMode;
      • private Integer maxDownloads;
      • private Integer expiresAfterDays;

  4. Frontend TypeScript Types:

    • web/typescript/backend/model/product.ts
    • Should auto-update with new fields

Optional: Add DownloadUrlResponse Schema​

If you want to formalize the download URL response structure, add this schema:

# ADD TO components/schemas

DownloadUrlResponse:
  type: object
  required:
    - url
    - expiresInMinutes
  properties:
    url:
      type: string
      format: uri
      description: Time-limited signed URL for downloading the asset
      example: "https://s3.amazonaws.com/valkyr-assets/abc123?signature=..."
    expiresInMinutes:
      type: integer
      description: Minutes until the URL expires
      example: 15
    downloadToken:
      type: string
      format: uuid
      description: One-time token for tracking this download

Then add a corresponding endpoint:

# ADD TO paths section

/v1/download/{downloadAccessId}:
  parameters:
    - name: downloadAccessId
      in: path
      required: true
      description: Unique identifier for the DownloadAccess entitlement
      schema:
        type: string
        format: uuid
    - name: validityMinutes
      in: query
      required: false
      description: Minutes until the signed URL expires (default 15)
      schema:
        type: integer
        default: 15
        minimum: 1
        maximum: 60
  get:
    tags: [Download]
    summary: Generate signed download URL
    description: >
      Creates a time-limited signed URL for downloading a digital asset.
      Requires active DownloadAccess entitlement and ACL READ permission.
      Enforces max download limits and expiry dates.
    operationId: getDownloadUrl
    x-thorapi-nonCrud: true
    responses:
      "200":
        description: Signed URL generated successfully
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DownloadUrlResponse"
      "403":
        description: Permission denied or entitlement inactive
      "404":
        description: DownloadAccess not found
      "429":
        description: Download limit exceeded

Notes​

  • No new entities needed: DownloadAccess already serves as the entitlement record
  • No funnel entity needed: ProductFunnelWizard already exists
  • All other schemas: Already present in current OpenAPI spec

Validation​

After regeneration, verify these services exist:

# Check generated files
ls valkyrai/generated/spring/src/main/java/com/valkyrlabs/model/Product.java
ls web/typescript/backend/model/product.ts

# Verify new fields in Product model
grep "contentDataId" valkyrai/generated/spring/src/main/java/com/valkyrlabs/model/Product.java
grep "deliveryMode" valkyrai/generated/spring/src/main/java/com/valkyrlabs/model/Product.java

Complete Rebuild Command Sequence​

# 1. Edit OpenAPI spec (add Product enhancements)
code valkyrai/src/main/resources/openapi/api.hbs.yaml

# 2. Regenerate ThorAPI
cd thorapi
mvn clean install

# 3. Rebuild ValkyrAI with new models
cd ../valkyrai
mvn clean install -DskipTests

# 4. Rebuild frontend types
cd ../web/typescript/backend
npm run generate  # if you have a codegen script

# 5. Verify changes
git diff valkyrai/generated/spring/src/main/java/com/valkyrlabs/model/Product.java

Ready to Proceed​

Once ThorAPI models are regenerated with these enhancements, you can proceed with implementing the backend services in DPPS_IMPLEMENTATION_PLAN.md Phase 2.

Next Step: Day 1, Step 3 — Implement DppsOrchestrationService.java