@vly/integrations

First-order integrations for AI, email, and payments with automatic usage billing through Vly deployment tokens.

Installation

npm install @vly/integrations axios
# or
yarn add @vly/integrations axios
# or
pnpm add @vly/integrations axios

Note: axios is a peer dependency and must be installed separately.

Usage

import { createVlyIntegrations } from '@vly/integrations';

const vly = createVlyIntegrations({
  deploymentToken: process.env.VLY_DEPLOYMENT_TOKEN,
  apiEndpoint: 'https://api.vly.io/v1', // optional
  debug: false // optional
});

// AI Completions
const completion = await vly.ai.completion({
  model: 'gpt-3.5-turbo',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' }
  ],
  temperature: 0.7,
  maxTokens: 150
});

// Send Email
const emailResult = await vly.email.send({
  to: 'user@example.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our service!</h1>',
  text: 'Welcome to our service!'
});

// Create Payment Intent
const paymentIntent = await vly.payments.createPaymentIntent({
  amount: 2000, // $20.00 in cents
  currency: 'usd',
  description: 'Premium subscription',
  customer: {
    email: 'customer@example.com'
  }
});

API Reference

AI Integration

// Create completion
vly.ai.completion(request: AICompletionRequest): Promise<ApiResponse<AICompletionResponse>>

// Stream completion
vly.ai.streamCompletion(
  request: AICompletionRequest,
  onChunk: (chunk: string) => void
): Promise<ApiResponse<AICompletionResponse>>

// Generate embeddings
vly.ai.embeddings(input: string | string[]): Promise<ApiResponse<{embeddings: number[][]}>>

Email Integration

// Send single email
vly.email.send(email: EmailRequest): Promise<ApiResponse<EmailResponse>>

// Send batch emails
vly.email.sendBatch(emails: EmailRequest[]): Promise<ApiResponse<EmailResponse[]>>

// Get email status
vly.email.getStatus(emailId: string): Promise<ApiResponse<EmailResponse>>

// Domain management
vly.email.verifyDomain(domain: string): Promise<ApiResponse>
vly.email.listDomains(): Promise<ApiResponse>

Payments Integration

// Payment Intents
vly.payments.createPaymentIntent(intent: PaymentIntent): Promise<ApiResponse<PaymentIntentResponse>>
vly.payments.confirmPaymentIntent(intentId: string, paymentMethodId: string): Promise<ApiResponse>
vly.payments.getPaymentIntent(intentId: string): Promise<ApiResponse>
vly.payments.cancelPaymentIntent(intentId: string): Promise<ApiResponse>

// Subscriptions
vly.payments.createSubscription(subscription: Subscription): Promise<ApiResponse<SubscriptionResponse>>
vly.payments.updateSubscription(id: string, updates: Partial<Subscription>): Promise<ApiResponse>
vly.payments.cancelSubscription(id: string, immediately?: boolean): Promise<ApiResponse>
vly.payments.getSubscription(id: string): Promise<ApiResponse>
vly.payments.listSubscriptions(customerId?: string): Promise<ApiResponse>

// Checkout & Portal
vly.payments.createCheckoutSession(session: CheckoutSession): Promise<ApiResponse>
vly.payments.createCustomerPortal(session: CustomerPortalSession): Promise<ApiResponse>

// Customer Management
vly.payments.createCustomer(customer: Customer): Promise<ApiResponse>
vly.payments.getCustomer(customerId: string): Promise<ApiResponse>
vly.payments.updateCustomer(customerId: string, updates: CustomerUpdate): Promise<ApiResponse>

// Payment Methods
vly.payments.listPaymentMethods(customerId: string): Promise<ApiResponse>
vly.payments.attachPaymentMethod(methodId: string, customerId: string): Promise<ApiResponse>
vly.payments.detachPaymentMethod(methodId: string): Promise<ApiResponse>

Error Handling

All methods return an ApiResponse object with the following structure:

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  usage?: {
    credits: number;
    operation: string;
  };
}

Example error handling:

const result = await vly.ai.completion({ ... });

if (result.success) {
  console.log('Response:', result.data);
  console.log('Credits used:', result.usage?.credits);
} else {
  console.error('Error:', result.error);
}

Configuration

Environment Variables

VLY_DEPLOYMENT_TOKEN=your_deployment_token_here
VLY_API_ENDPOINT=https://api.vly.io/v1  # optional
VLY_DEBUG=true  # optional, enables debug logging

Debug Mode

Enable debug mode to see detailed logs:

const vly = createVlyIntegrations({
  deploymentToken: process.env.VLY_DEPLOYMENT_TOKEN,
  debug: true
});

Billing

All API calls are automatically billed to your deployment based on usage. The billing happens transparently through your deployment token, and usage information is included in the API responses.

License

MIT