Partner API Integration Guide

<?php

class PulsePartnerAPI
{
    private string $apiKey;
    private string $apiSecret;
    private string $baseUrl = 'https://pulse.cares.center/api/v1/partner';

    public function __construct(string $apiKey, string $apiSecret)
    {
        $this->apiKey = $apiKey;
        $this->apiSecret = $apiSecret;
    }

    /**
     * Create registration and get URL in one call
     */
    public function createPartnerRegistration(
        string $organizationName,
        string $email,
        ?string $displayName = null,
        ?string $projectName = null,
        ?string $externalUserId = null,
        ?string $callbackUrl = null
    ): array {
        // Step 1: Create request
        $createData = [
            'organization_name' => $organizationName,
            'email' => $email,
        ];
        if ($displayName) $createData['display_name'] = $displayName;
        if ($projectName) $createData['project_name'] = $projectName;
        if ($callbackUrl) $createData['callback_url'] = $callbackUrl;

        $createResult = $this->request('POST', '/request', $createData);

        if (!$createResult['success']) {
            return $createResult;
        }

        $token = $createResult['data']['request_token'];

        // Step 2: Confirm and get URL
        $confirmData = $externalUserId ? ['external_user_id' => $externalUserId] : [];
        $confirmResult = $this->request('POST', "/request/{$token}/confirm", $confirmData);

        if (!$confirmResult['success']) {
            return $confirmResult;
        }

        return [
            'success' => true,
            'data' => [
                'request_token' => $token,
                'registration_url' => $confirmResult['data']['registration_url'],
                'expires_at' => $createResult['data']['expires_at'],
            ]
        ];
    }

    private function request(string $method, string $endpoint, array $data = []): array
    {
        $url = $this->baseUrl . $endpoint;
        $timestamp = time();
        $body = $method !== 'GET' ? json_encode($data) : '';
        $signature = hash_hmac('sha256', $timestamp . '.' . $body, $this->apiSecret);

        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST => $method,
            CURLOPT_HTTPHEADER => [
                'X-Partner-Key: ' . $this->apiKey,
                'X-Partner-Signature: ' . $signature,
                'X-Partner-Timestamp: ' . $timestamp,
                'Content-Type: application/json',
            ],
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POSTFIELDS => $body ?: null,
        ]);

        $response = curl_exec($ch);
        curl_close($ch);
        return json_decode($response, true);
    }
}

// Usage
$pulse = new PulsePartnerAPI('pak_your_key', 'pas_your_secret');

$result = $pulse->createPartnerRegistration(
    organizationName: 'ACME Corporation',
    email: 'john@acme.com',
    displayName: 'John Doe',
    projectName: 'CARES Initiative 2026',
    externalUserId: 'user_12345'
);

if ($result['success']) {
    echo "Send this URL to user: " . $result['data']['registration_url'];
}

import hmac
import hashlib
import time
import json
import requests
from typing import Optional, Dict, Any

class PulsePartnerAPI:
    def __init__(self, api_key: str, api_secret: str):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = 'https://pulse.cares.center/api/v1/partner'

    def create_partner_registration(
        self,
        organization_name: str,
        email: str,
        display_name: Optional[str] = None,
        project_name: Optional[str] = None,
        external_user_id: Optional[str] = None,
        callback_url: Optional[str] = None
    ) -> Dict[str, Any]:
        # Step 1: Create request
        create_data = {'organization_name': organization_name, 'email': email}
        if display_name: create_data['display_name'] = display_name
        if project_name: create_data['project_name'] = project_name
        if callback_url: create_data['callback_url'] = callback_url

        create_result = self._request('POST', '/request', create_data)
        if not create_result.get('success'):
            return create_result

        token = create_result['data']['request_token']

        # Step 2: Confirm
        confirm_data = {'external_user_id': external_user_id} if external_user_id else {}
        confirm_result = self._request('POST', f'/request/{token}/confirm', confirm_data)

        if not confirm_result.get('success'):
            return confirm_result

        return {
            'success': True,
            'data': {
                'request_token': token,
                'registration_url': confirm_result['data']['registration_url'],
                'expires_at': create_result['data']['expires_at'],
            }
        }

    def _request(self, method: str, endpoint: str, data: Optional[Dict] = None) -> Dict:
        url = self.base_url + endpoint
        timestamp = int(time.time())
        body = json.dumps(data) if data and method != 'GET' else ''
        signature = hmac.new(
            self.api_secret.encode(),
            f"{timestamp}.{body}".encode(),
            hashlib.sha256
        ).hexdigest()

        response = requests.request(
            method=method, url=url,
            headers={
                'X-Partner-Key': self.api_key,
                'X-Partner-Signature': signature,
                'X-Partner-Timestamp': str(timestamp),
                'Content-Type': 'application/json',
            },
            data=body if body else None
        )
        return response.json()

# Usage
pulse = PulsePartnerAPI('pak_your_key', 'pas_your_secret')
result = pulse.create_partner_registration(
    organization_name='ACME Corporation',
    email='john@acme.com',
    display_name='John Doe',
    external_user_id='user_12345'
)

if result['success']:
    print(f"Send this URL to user: {result['data']['registration_url']}")