Integration Packages

Integration packages provide abstractions and implementations for connecting with external services.

integrations-core

Core abstractions and base classes for all integration implementations.

Key Features

• Sync pattern for CRUD operations
• Integration mapping for linking vendor data
• Structured exception hierarchy
• File-based logging with vendor context

Architecture

abstract class Integrator {
    abstract function syncAll(): array;
    abstract function sync(IntegrationMapping $mapping): array;
}

abstract class Sync {
    abstract function execute(): void;
}

Exception Hierarchy

IntegrationExceptionInterface
├── ConnectException
├── UnauthorizedException
├── ForbiddenException
├── NotFoundException
├── UnexpectedValueException
├── TimeoutException
├── ServiceUnavailableException
├── TooManyRequestException
├── FileOutdatedException
├── FileDeliveryException
└── FileNotFoundException

Result Structure

// Sync result format
[
    $advisor_id => [
        $household_id => [
            'accounts' => [$account_id => [$position_ids]],
            'insurances' => [$insurance_id => []],
            'persons' => [$person_id],
        ]
    ]
]

Dependencies

• core-models, laravel-sentry
• illuminate-http-problem-response

---

integrations-file-based

File-based integrations for custodians and vendors.

Supported Vendors

Vendor	File Type	Data Types
Allianz	Custom	Life insurance, investments
Jackson	Custom	Life insurance, investments
Apex	CSV	Investment accounts
Altruist	CSV	Portfolio data
Betterment	CSV	Investment accounts
InteractiveBrokers	Fixed-width	Accounts, positions
FirstClearing	Fixed-width (NSCC)	Accounts, securities
Fidelity	CSV	Investment accounts
Schwab	CSV	Investment accounts
Pershing	CSV	Investment accounts
RBC	CSV	Investment accounts
RaymondJames	CSV	Investment accounts
Flourish	CSV	Bank accounts

File Parsing Patterns

// CSV-based
interface CsvFileTypeInterface extends FileTypeInterface {
    public function getHeaders(): array;
    public function getFieldMappings(): array;
}

// Fixed-width (NSCC)
class NsccFileType {
    public function getColumnDefinitions(): array;
}

Integration Flow

1. Advisor uploads file via REST API
2. File stored in S3/SFTP
3. Background job parses file
4. Holdings/accounts stored in database
5. Data available for mapping to households

---

laravel-stripe

Stripe payment processing and subscription management.

Key Features

• Customer and subscription management
• Payment method handling
• Tax calculation
• Coupon/discount processing
• Webhook event handling

Facades

use RightCapital\LaravelStripe\Stripe;
use RightCapital\LaravelStripe\StripeConnect;

Usage

// Customer management
Stripe::createCustomer('user@example.com', [
    'name' => 'John Doe',
    'metadata' => ['user_id' => 123],
]);

// Subscription management
Stripe::createSubscription($customer_id, $price_id);
Stripe::cancelSubscription($subscription_id);

// Coupon handling
$coupon = Stripe::getCoupon('DISCOUNT20');

// Tax calculation
Stripe::applyTaxToLocation('94105');

// Webhook processing
$event = Stripe::constructWebhookEvent($payload, $signature);

Configuration

config/services.php

'stripe' => [
    'secret' => env('STRIPE_SECRET'),
    'webhook' => [
        'secret' => env('STRIPE_WEBHOOK_SECRET'),
    ],
    'max_network_retries' => 3,
],

Exception Classes

• CouponNotFound
• CustomerNotFound
• SubscriptionNotFound
• PaymentMethodNotFound
• InvalidTaxLocation

---

laravel-salesforce

Salesforce CRM integration for enterprise features.

SObject Types

SObject	Purpose
AccountSobject	CRM Accounts
ContactSobject	Contacts
LeadSobject	Sales leads
OpportunitySobject	Opportunities
UserSobject	Salesforce users
TaskSobject	Task activities
EventSobject	Event activities
CampaignMemberSobject	Campaign memberships
AdvisorInvitationSobject	Custom: advisor invitations

Usage

use RightCapital\LaravelSalesforce\Salesforce;

// Create account
Salesforce::account()->create(['Name' => 'Acme Corp']);

// Find by ID
$contact = Salesforce::contact()->find($salesforce_id);

// Find by external ID
$opp = Salesforce::opportunity()->findByExternalId('ext-123', 'External_ID__c');

// Query
$results = Salesforce::account()->query(
    "SELECT Id, Name FROM Account WHERE Name LIKE '%Pattern%'"
);

// Update
Salesforce::task()->update($id, ['Status' => 'Completed']);

// Delete
Salesforce::lead()->delete($id);

Configuration

config/services.php

'salesforce' => [
    'credentials' => [
        'client_id' => env('SALESFORCE_CLIENT_ID'),
        'client_secret' => env('SALESFORCE_CLIENT_SECRET'),
        'username' => env('SALESFORCE_USERNAME'),
        'password' => env('SALESFORCE_PASSWORD'),
        'instance_url' => env('SALESFORCE_INSTANCE_URL'),
    ],
],

Custom SObjects

class CustomSobject extends AbstractCustomSobject {
    protected string $sobject_name = 'CustomObject__c';

    public function customMethod(): array { }
}

// Register
Client::registerSobjectMap('customObject', CustomSobject::class);
Salesforce::customObject()->create([...]);

---

laravel-azure-ad

Azure Active Directory authentication and authorization.

Key Features

• JWT token validation
• Claims extraction
• Role-based access control
• Driver pattern (production/local)

Service Provider

AzureAdServiceProvider registers the Azure AD manager.

Authentication Flow

1. Browser → Azure AD login
2. User authenticates (MFA)
3. Redirect back with auth code
4. Server exchanges for tokens
5. JWT validated and claims extracted
6. User object created

Usage

use RightCapital\LaravelAzureAd\AzureAd;

$service = AzureAd::driver('azure_ad');
$service->setAccessToken($token_string);

if ($service->check()) {
    $user = $service->getUser();
    $claims = $service->getClaims();
    $roles = $service->getClaim('roles', []);
}

Configuration

config/services.php

'azure_ad' => [
    'driver' => env('AZURE_AD_DRIVER', 'azure_ad'),
    'tenant_id' => env('AZURE_AD_TENANT_ID'),
    'client_id' => env('AZURE_AD_CLIENT_ID'),
    'client_secret' => env('AZURE_AD_CLIENT_SECRET'),
    'redirect_uri' => env('AZURE_AD_REDIRECT_URI'),
    'scopes' => ['openid', 'profile', 'email'],
],

Exceptions

• InvalidTokenException
• TokenExpiredException
• InvalidSignatureException
• WrongAppIdTokenException

---

saml

SAML 2.0 Single Sign-On implementation.

Key Features

• SP (Service Provider) configuration
• AuthN request generation
• Response assertion parsing
• Multi-certificate support for key rotation

SAML Flow

1. SP initiates AuthN Request
2. Request signed with SP certificate
3. User redirected to IdP
4. IdP authenticates user
5. IdP returns signed Response
6. SP validates signature
7. SP extracts user attributes
8. Session created

Key Classes

// Enhanced key descriptor with multi-certificate support
class KeyDescriptor {
    // Supports key rotation: add new cert before revoking old
}

// XML signature creation
class SignatureWrite {
    // Creates XML-DSig signatures for SAML documents
}

Endpoints

Endpoint	Purpose
/saml/metadata	SP metadata XML
/saml/login	Initiate login
/saml/acs	Assertion Consumer Service
/saml/logout	Initiate logout

Security Features

• Signed requests prevent tampering
• Encrypted assertions protect data
• Certificate validation prevents MITM
• Timestamp validation prevents replay

Dependencies

• litesaml/lightsaml v4.5+

---

Dependency Graph

integrations-core
    ↓
integrations-file-based
    ├── Uses: integrations-core
    └── Uses: laravel-apm, laravel-aop

laravel-stripe (standalone)

laravel-salesforce
    └── Uses: omniphx/forrest

laravel-azure-ad
    └── Uses: lcobucci/jwt

saml
    └── Uses: litesaml/lightsaml

Summary

Package	Integration Type	External Service
integrations-core	Base abstractions	N/A
integrations-file-based	File processing	15+ custodians
laravel-stripe	Payment	Stripe
laravel-salesforce	CRM	Salesforce
laravel-azure-ad	Authentication	Azure AD
saml	SSO	Any SAML 2.0 IdP