====== BCCCR API Documentation ======

== Platform Registration ==

=== POST /api/platforms/register ===

Submit a platform registration application for BCCCR review.

==== Request Body ====
<code json>
{
  "name": "<applicant_name>",
  "email": "<applicant_email>",
  "password": "<password>",
  "password_confirmation": "<password>",
  "platform_name": "<platform_name>",
  "platform_address": "<business_address>",
  "tin_number": "<tax_id>",
  "platform_phone": "<phone_number>",
  "platform_email": "<platform_contact_email>",
  "bank_account_number": "<account_number>",
  "bank_routing_number": "<routing_number>",
  "bank_name": "<bank_name>",
  "api_endpoint": "<optional_api_endpoint>"
}
</code>

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Platform registration submitted successfully. Your application will be reviewed by BCCCR administrators.",
  "data": {
    "platform_name": "<platform_name>",
    "status": "pending",
    "registration_date": "<timestamp>"
  }
}
</code>

==== Notes ====
  * Application status will be 'pending' until reviewed by BCCCR administrators
  * API key will be generated upon approval
  * All business information is required for compliance and settlement processing

=== GET /api/platforms/status/{email} ===

Check the status of a platform registration application.

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Registration status retrieved",
  "data": {
    "platform_name": "<platform_name>",
    "status": "<pending|active|inactive>",
    "registration_date": "<timestamp>",
    "approved_at": "<timestamp>",
    "admin_notes": "<notes>"
  }
}
</code>

== Admin Management ==

=== GET /api/admin/applications/pending ===

Get all pending platform applications (admin only).

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Pending applications retrieved",
  "data": [
    {
      "id": <application_id>,
      "name": "<applicant_name>",
      "email": "<email>",
      "platform_name": "<platform_name>",
      "platform_address": "<address>",
      "tin_number": "<tax_id>",
      "platform_phone": "<phone>",
      "platform_email": "<contact_email>",
      "bank_name": "<bank>",
      "created_at": "<timestamp>",
      "admin_notes": "<notes>"
    }
  ]
}
</code>

=== POST /api/admin/applications/{id}/approve ===

Approve a platform application (admin only).

==== Request Body ====
<code json>
{
  "notes": "<optional_admin_notes>"
}
</code>

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Platform application approved successfully",
  "data": {
    "platform_name": "<platform_name>",
    "status": "active",
    "approved_at": "<timestamp>",
    "api_key": "<generated_api_key>"
  }
}
</code>

=== POST /api/admin/applications/{id}/reject ===

Reject a platform application (admin only).

==== Request Body ====
<code json>
{
  "notes": "<rejection_reason>"
}
</code>

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Platform application rejected",
  "data": {
    "platform_name": "<platform_name>",
    "status": "inactive"
  }
}
</code>

== Contract Management ==

=== POST /api/contracts/register ===

Register up to 250 contract hashes for a single publication.

==== Request Body ====
<code json>
{
  "ipfs_hash": "<IPFS hash for the publication>",
  "metadata_cid": "<IPFS CID for the metadata>",
  "contract_hashes": [
    "<contract_hash_1>",
    "<contract_hash_2>"
    // ... up to 250
  ]
}
</code>
  * **ipfs_hash** (string, required): The IPFS hash for the publication (applies to all contracts in the batch)
  * **metadata_cid** (string, required): The IPFS CID for the metadata (applies to all contracts in the batch)
  * **contract_hashes** (array, required): Up to 250 unique contract hashes to register in one call

==== Validation Rules ====
  * All contract hashes must be unique within the request and not already registered in the system
  * All contracts in the batch will share the same IPFS hash and metadata CID

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Contracts registered successfully",
  "data": {
    "registered_count": <number>,
    "ipfs_hash": "<IPFS hash>",
    "metadata_cid": "<metadata CID>",
    "contract_hashes": [ ... ]
  }
}
</code>

==== Response (Validation Error) ====
<code json>
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contract_hashes": ["Contract hashes already exist: ..."]
  }
}
</code>

  * Returns HTTP 201 on success, HTTP 422 on validation error
  * Requires a valid API key in the ''X-API-Key'' header

==== Example cURL ====
<code bash>
curl -X POST http://localhost:8000/api/contracts/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"ipfs_hash":"QmTest123","metadata_cid":"QmMeta456","contract_hashes":["hash1","hash2"]}'
</code>

=== POST /api/contracts/validate ===

Validate a contract hash and return legitimacy and usage information.

==== Request Body ====
<code json>
{
  "contract_hash": "<contract_hash>"
}
</code>
  * **contract_hash** (string, required): The contract hash to validate

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Contract found",
  "data": {
    "contract_hash": "<contract_hash>",
    "status": "active",
    "ipfs_hash": "<IPFS hash>",
    "metadata_cid": "<metadata CID>",
    "originating_platform_id": <platform_id>,
    "originating_platform_name": "<platform name>",
    "registered_at": "<timestamp>"
  }
}
</code>

==== Response (Not Found or Inactive) ====
<code json>
{
  "success": false,
  "message": "Contract not found",
  "data": null
}
</code>

  * Returns HTTP 200 on success, HTTP 404 if not found or not active
  * Requires a valid API key in the ''X-API-Key'' header

==== Example cURL ====
<code bash>
curl -X POST http://localhost:8000/api/contracts/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"contract_hash":"hash1"}'
</code>

=== PUT /api/contracts/{hash}/revoke ===

Revoke a contract. Only the publishing platform can revoke its own contracts.

==== Request Body ====
<code json>
{
  "reason": "<reason for revocation>"
}
</code>
  * **reason** (string, optional): Reason for revocation (max 500 chars)

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Contract revoked successfully",
  "data": {
    "contract_hash": "<contract_hash>",
    "status": "revoked",
    "revoked_at": "<timestamp>",
    "reason": "<reason>"
  }
}
</code>

==== Response (Not Allowed or Already Revoked) ====
<code json>
{
  "success": false,
  "message": "Only the publishing platform can revoke this contract",
  "data": null
}
</code>
<code json>
{
  "success": false,
  "message": "Contract is already revoked",
  "data": null
}
</code>

  * Returns HTTP 200 on success, HTTP 403 if not authorized, HTTP 400 if already revoked, HTTP 404 if not found
  * Requires a valid API key in the ''X-API-Key'' header

==== Example cURL ====
<code bash>
curl -X PUT http://localhost:8000/api/contracts/hash1/revoke \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"reason":"No longer valid"}'
</code> 

== Sales Reporting ==

=== POST /api/sales ===

Report a cross-platform sale to track royalty obligations between platforms.

==== Request Body ====
<code json>
{
  "contract_hash": "0x1234567890abcdef...",
  "buyer_wallet_address": "0xabcdef1234567890...",
  "sale_amount": 29.99,
  "royalty_amount": 2.99,
  "transaction_hash": "0x9876543210fedcba...",
  "metadata": {
    "payment_method": "credit_card",
    "currency": "USD",
    "platform_fee": 1.50
  },
  "sold_at": "2024-01-15T10:30:00Z"
}
</code>

==== Required Fields ====
  * **contract_hash** (string): The contract hash of the content being sold
  * **sale_amount** (numeric): Total sale amount in USD (minimum $0.01)
  * **royalty_amount** (numeric): Royalty amount owed to author in USD

==== Optional Fields ====
  * **buyer_wallet_address** (string): Buyer's wallet address (max 42 characters)
  * **transaction_hash** (string): Blockchain transaction hash
  * **metadata** (object): Additional transaction metadata
  * **sold_at** (datetime): When the sale occurred (defaults to current time)

==== Validation Rules ====
  * Contract hash must be registered and active in the system
  * Sale amount must be at least $0.01
  * Royalty amount cannot exceed sale amount
  * Royalty amount cannot be negative

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Sale reported successfully",
  "data": {
    "transaction_id": 123,
    "royalty_id": 456,
    "contract_hash": "0x1234567890abcdef...",
    "sale_amount": 29.99,
    "royalty_amount": 2.99,
    "sold_at": "2024-01-15T10:30:00Z"
  }
}
</code>

==== Response (Validation Error) ====
<code json>
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contract_hash": ["Contract hash is not registered."],
    "royalty_amount": ["Royalty amount cannot exceed sale amount."]
  }
}
</code>

==== Business Logic ====
  * Creates a transaction record linking the sale to the contract and platforms
  * Creates a royalty record where the selling platform owes the originating platform
  * Both records are created in a database transaction to ensure consistency
  * Logs the sale for audit and settlement processing

  * Returns HTTP 201 on success, HTTP 422 on validation error
  * Requires a valid API key in the ''X-API-Key'' header

==== Example cURL ====
<code bash>
curl -X POST http://localhost:8000/api/sales \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"contract_hash":"0x1234567890abcdef","sale_amount":29.99,"royalty_amount":2.99}'
</code>

== Content Mirroring ==

=== POST /api/mirrors ===

Report content mirroring with IPFS locations to create a decentralized backup system.

==== Request Body ====
<code json>
{
  "contract_hash": "0x1234567890abcdef...",
  "mirrored_ipfs_hash": "QmMirroredContent123",
  "mirror_location": "ipfs-node-1",
  "access_count": 0,
  "mirrored_at": "2024-01-15T10:30:00Z"
}
</code>

==== Required Fields ====
  * **contract_hash** (string): The contract hash of the content being mirrored
  * **mirrored_ipfs_hash** (string): The IPFS hash where the content is mirrored (max 64 characters)

==== Optional Fields ====
  * **mirror_location** (string): IPFS node location/identifier
  * **access_count** (integer): Number of times this mirror was accessed
  * **mirrored_at** (datetime): When the mirror was created (defaults to current time)

==== Validation Rules ====
  * Contract hash must be registered and active in the system
  * Mirrored IPFS hash cannot exceed 64 characters
  * Access count cannot be negative

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Content mirror created successfully",
  "data": {
    "mirror_id": 123,
    "contract_hash": "0x1234567890abcdef...",
    "ipfs_hash": "QmOriginalContent",
    "mirrored_ipfs_hash": "QmMirroredContent123",
    "mirror_location": "ipfs-node-1",
    "access_count": 0,
    "mirrored_at": "2024-01-15T10:30:00Z",
    "action": "created"
  }
}
</code>

==== Business Logic ====
  * Creates or updates a mirror record for the platform and IPFS hash
  * If a mirror already exists for the same platform and IPFS hash, it updates the existing record
  * Logs the mirror for audit and content discovery
  * Enables decentralized backup through normal usage patterns

  * Returns HTTP 201 on success, HTTP 422 on validation error
  * Requires a valid API key in the ''X-API-Key'' header

==== Example cURL ====
<code bash>
curl -X POST http://localhost:8000/api/mirrors \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your-api-key>" \
  -d '{"contract_hash":"0x1234567890abcdef","mirrored_ipfs_hash":"QmMirroredContent123"}'
</code>

=== GET /api/mirrors/{ipfsHash} ===

Retrieve all mirrors for a specific IPFS hash to find available content locations.

==== Response (Success) ====
<code json>
{
  "success": true,
  "message": "Mirrors retrieved successfully",
  "data": {
    "ipfs_hash": "QmOriginalContent",
    "mirrors": [
      {
        "mirror_id": 123,
        "mirrored_ipfs_hash": "QmMirroredContent123",
        "mirror_location": "ipfs-node-1",
        "platform_name": "Platform A",
        "access_count": 5,
        "last_accessed_at": "2024-01-15T10:30:00Z",
        "mirrored_at": "2024-01-10T09:00:00Z"
      }
    ],
    "total_mirrors": 1
  }
}
</code>

  * Returns HTTP 200 on success, HTTP 500 on server error
  * Requires a valid API key in the ''X-API-Key'' header

==== Example cURL ====
<code bash>
curl -X GET http://localhost:8000/api/mirrors/QmOriginalContent \
  -H "X-API-Key: <your-api-key>"
</code>