Skip to content

🚀 v2.0.1 - Complete IPN Implementation & List Operations Enhancement

Choose a tag to compare

View all tags
@PaulGossen PaulGossen released this 09 Nov 08:41
· 50 commits to main since this release
v2.0.1
9b67d17

📋 Overview

This patch release completes the implementation of IPN (Instant Payment Notification) endpoints and enhances List operations with comprehensive search capabilities. All Request classes now fully match the OpenAPI specification with type-safe DTOs and Enums.

⚠️ BREAKING CHANGES

Note: These breaking changes were introduced in v2.0.0 and are documented here for reference. If you're upgrading from v2.0.0 to v2.0.1, there are no additional breaking changes.

IPN Request Classes

IpnSetupRequest

v2.0.0 (Previous): Only 2 parameters (incomplete implementation)

$request = new IpnSetupRequest(
    url: 'https://yoursite.com/webhook',
    ipnPassword: 'secret123'
);

v2.0.1 (Current): Complete with 9 parameters

$request = new IpnSetupRequest(
    ipnUrl: 'https://yoursite.com/webhook',
    name: 'My Platform',
    productIds: 'all',
    domainId: 'my-platform',
    categories: [IpnTransactionCategory::ORDERS, IpnTransactionCategory::AFFILIATIONS],
    transactions: [IpnTransactionType::PAYMENT, IpnTransactionType::REFUND],
    timing: IpnTiming::DELAYED,
    shaPassphrase: 'random',
    newsletterSendPolicy: IpnNewsletterSendPolicy::SEND_IF_OPTIN
);
  • ✅ Changed from 2 parameters to 9 comprehensive parameters
  • ✅ Added type-safe Enums for categories, transactions, timing, and newsletter policy
  • ✅ Renamed url → ipnUrl, removed ipnPassword

IpnInfoRequest

v2.0.0 (Previous): HTTP POST, no parameters

$response = $api->ipn()->info(); // Incomplete

v2.0.1 (Current): HTTP GET with optional filter

$request = new IpnInfoRequest(domainId: 'my-platform'); // HTTP GET
$response = $api->ipn()->info($request);
  • ✅ Changed from HTTP POST to HTTP GET
  • ✅ Added optional domainId parameter for filtering

IpnDeleteRequest

v2.0.0 (Previous): HTTP POST, no parameters

$request = new IpnDeleteRequest(); // Incomplete
$response = $api->ipn()->delete($request);

v2.0.1 (Current): HTTP DELETE with required domainId

$response = $api->ipn()->delete('my-platform'); // HTTP DELETE, required domainId
  • ✅ Changed from HTTP POST to HTTP DELETE
  • ✅ Now requires domainId parameter (string)
  • ✅ IpnResource::delete() signature changed from delete(?IpnDeleteRequest) to delete(string $domainId)

List Request Classes

ListPurchasesRequest

v2.0.0 (Previous): Basic 4 parameters

$request = new ListPurchasesRequest(
    productId: 123,
    buyerEmail: 'buyer@example.com',
    fromDate: '2025-01-01',
    toDate: '2025-12-31'
);

v2.0.1 (Current): Enhanced with 8 comprehensive parameters

$search = new PurchaseSearchData(
    productId: 123,
    email: 'buyer@example.com',
    role: 'buyer'
);

$request = new ListPurchasesRequest(
    from: '2025-01-01',
    to: '2025-12-31',
    search: $search,
    sortBy: PurchaseSortBy::DATE,
    sortOrder: SortOrder::DESC,
    loadTransactions: true,
    pageNo: 1,
    pageSize: 500
);
  • ✅ Replaced 4 basic parameters with 8 comprehensive parameters
  • ✅ Introduced PurchaseSearchData DTO with 13 search criteria
  • ✅ Added type-safe PurchaseSortBy and SortOrder Enums
  • ✅ Added pagination support (pageNo, pageSize)
  • ✅ Added loadTransactions flag for detailed data

ListProductsRequest

v2.0.0 (Previous): Parameters not matching OpenAPI spec

$request = new ListProductsRequest(
    productType: 'digital',
    onlyPublished: true
);

v2.0.1 (Current): Corrected to match OpenAPI spec

$request = new ListProductsRequest(
    sortBy: ProductSortBy::NAME
);
  • ✅ Simplified to single sortBy parameter with ProductSortBy Enum
  • ✅ Removed productType and onlyPublished (not in OpenAPI spec)

ListTransactionsRequest

v2.0.0 (Previous): Generic arrays, no type safety

$request = new ListTransactionsRequest(
    search: ['product_id' => 123], // Generic array
    sort: ['date' => 'desc'] // Generic array
);

v2.0.1 (Current): Type-safe with DTOs and Enums

$search = new TransactionSearchData(
    productId: 123,
    email: 'buyer@example.com'
);

$request = new ListTransactionsRequest(
    from: '2025-01-01',
    to: '2025-12-31',
    search: $search,
    sortBy: TransactionSortBy::DATE,
    sortOrder: SortOrder::DESC
);
  • ✅ Replaced generic arrays with TransactionSearchData DTO
  • ✅ Added type-safe TransactionSortBy and SortOrder Enums

✨ New Features

🎯 5 New Enums for Type Safety

  1. SortOrder - Universal sort direction

    • ASC, DESC

  2. PurchaseSortBy - Purchase list sorting

    • DATE, EARNING, AMOUNT

  3. ProductSortBy - Product list sorting

    • NAME, GROUP

  4. TransactionSortBy - Transaction list sorting

    • DATE, EARNING, AMOUNT

  5. OrderType - Live vs Test orders

    • LIVE, TEST

All Enums implement StringBackedEnum interface with StringBackedEnumTrait for consistency.

📦 2 New DTOs for Structured Search

  1. PurchaseSearchData - 13 search criteria

    • role, productId, firstName, lastName, email
    • hasAffiliate, affiliateName, orderType, payMethod
    • billingType, transactionType, currency, purchaseId

  2. TransactionSearchData - 12 search criteria

    • Same as PurchaseSearchData minus orderType

Both extend AbstractDataTransferObject with toArray() method.

📚 Documentation Updates

Updated documentation for all IPN endpoints:

  • ✅ ipnSetup.md - Complete rewrite with all 9 parameters and Enum examples
  • ✅ ipnInfo.md - Updated with domainId parameter and HTTP GET method
  • ✅ ipnDelete.md - Updated with required domainId parameter and HTTP DELETE method

All docs now include:

  • Modern named arguments syntax
  • Type-safe Enum usage examples
  • Breaking changes warnings
  • Error handling examples

🧪 Quality Assurance

  • ✅ 1137/1137 Unit Tests Passing (2271 assertions)
  • ✅ PHPStan Level 9: 0 errors (653 files analyzed)
  • ✅ PHP CS Fixer: 0 violations (PSR-12 compliant)
  • ✅ 6 Test Files Completely Rewritten with comprehensive coverage

🔧 Migration Guide

For users upgrading from v2.0.0 → v2.0.1

Good news! If you're already on v2.0.0, you only need to update your IPN and List operations code to use the new comprehensive parameters. The breaking changes were already introduced in v2.0.0.

Step 1: Update IPN Setup

// v2.0.0 (Incomplete)
$api->ipn()->setup(
    url: 'https://example.com/webhook',
    ipnPassword: 'secret'
);

// v2.0.1 (Complete)
use GoSuccess\Digistore24\Api\Enum\IpnTiming;
use GoSuccess\Digistore24\Api\Enum\IpnTransactionType;

$api->ipn()->setup(new IpnSetupRequest(
    ipnUrl: 'https://example.com/webhook',
    name: 'My Platform',
    productIds: 'all',
    timing: IpnTiming::BEFORE_THANKYOU,
    transactions: [IpnTransactionType::PAYMENT, IpnTransactionType::REFUND]
));

Step 2: Update IPN Delete

// v2.0.0 (Incomplete)
$api->ipn()->delete(new IpnDeleteRequest());

// v2.0.1 (Complete)
$api->ipn()->delete('my-platform'); // Direct string parameter

Step 3: Update List Purchases

// v2.0.0 (Basic)
$api->purchase()->list(
    productId: 123,
    buyerEmail: 'test@example.com'
);

// v2.0.1 (Enhanced)
use GoSuccess\Digistore24\Api\DTO\PurchaseSearchData;
use GoSuccess\Digistore24\Api\Enum\PurchaseSortBy;
use GoSuccess\Digistore24\Api\Enum\SortOrder;

$search = new PurchaseSearchData(
    productId: 123,
    email: 'test@example.com'
);

$api->purchase()->list(new ListPurchasesRequest(
    search: $search,
    sortBy: PurchaseSortBy::DATE,
    sortOrder: SortOrder::DESC
));

📦 Files Changed

24 files changed: 824 insertions(+), 214 deletions(-)

New Files (7)

  • src/DTO/PurchaseSearchData.php
  • src/DTO/TransactionSearchData.php
  • src/Enum/OrderType.php
  • src/Enum/ProductSortBy.php
  • src/Enum/PurchaseSortBy.php
  • src/Enum/SortOrder.php
  • src/Enum/TransactionSortBy.php

Modified Files (17)

  • Request Classes: IpnSetupRequest, IpnInfoRequest, IpnDeleteRequest, ListPurchasesRequest, ListProductsRequest, ListTransactionsRequest
  • Resource: IpnResource
  • Tests: 6 test files completely rewritten
  • Documentation: ipnSetup.md, ipnInfo.md, ipnDelete.md

💡 Notes

  • This release prioritizes type safety over backward compatibility
  • All changes validated against OpenAPI specification
  • OpenAPI spec contained errors (e.g., IpnNewsletterSendPolicy values) - corrected based on actual API behavior
  • Default values preserved for optional parameters (e.g., last 24 hours for date ranges)
  • Parameter naming changed from snake_case to camelCase for PHP conventions

Full Changelog: v2.0.0...v2.0.1

Assets 2
Loading