@riff-tech/code-checkout

code-checkout 🚀

A robust, developer-friendly platform for seamless license management, analytics tracking, and checkout integration in JavaScript/TypeScript projects.

✨ Features

• 🔒 Secure License Validation with offline-first caching
• 📊 Analytics Tracking for user actions and commands
• 🛒 Checkout Integration with customizable success/cancel flows
• 💻 Cross-Platform Support for all JavaScript and TypeScript projects
• 🔋 Battery-Included with TypeScript types and comprehensive documentation

🚀 Quick Start

Installation

npm install @riff-tech/code-checkout

📖 Usage Guide

Analytics Tracking

Track user actions and commands with ease:

import { logAnalyticsEvent } from "@riff-tech/code-checkout";

// Track a user action
await logAnalyticsEvent({
  softwareId: "your-software-id", // The unique identifier for your software, e.g. com.mypublisher.mysoftware
  commandId: "user.login", // The unique identifier for your command to track its usage
  licenseKey: "USER_LICENSE_KEY", // Optional as it will be cached automatically
});

License Validation

Implement secure license validation with built-in offline caching:

import { validateLicense } from "@riff-tech/code-checkout";

// Validate a license
const result = await validateLicense({
  licenseKey: "USER_LICENSE_KEY", // Optional as it will be cached automatically
  softwareId: "your-software-id",
  forceOnlineValidation: false, // Optional, defaults to false. If `true` the license will skip the cache and validate against the server
  cacheDurationInHours: 24, // Optional, defaults to 24. Grace period for offline usage
});

if (result.isValid) {
  // License is valid
  console.log("License is valid");
} else {
  // License is invalid
  console.log("License is invalid:", result.reason);
}

Checkout URL Generation

Create customized checkout experiences for your users:

Parameter	Type	Required	Description
softwareId	string	Yes	Unique identifier for your software using code-checkout
successUrl	string	No	URL to redirect to after successful checkout. Default is a code-checkout activation page. Query parameters for key, name, and redirectUri are automatically appended
cancelUrl	string	No	URL to redirect to if checkout is cancelled. Defaults to code-checkout homepage
testMode	boolean	No	When true, creates a test checkout session with no charges. Defaults to false
licenseKey	string	No	Custom license key to activate after checkout. If omitted, one will be generated
name	string	No	Display name for your software. If provided, appended as query param to successUrl
redirectUri	string	No	URI to redirect back to your application. If provided, appended as query param to successUrl

import { generateCheckoutUrl } from "@riff-tech/code-checkout";

const appDisplayName = "Example App";
const appUri = "vscode://"; // Optional, but this enables a button that can redirect back to your app
const successUrl = "https://mysite.com"; // Optional, but can be used to show your website after purchase

const licenseKeyToActivate = generateLicenseKey(); // Optionally generate a license key and pass it to `generateCheckoutUrl` for activation after checkout success

// Generate a checkout URL and get the licenseKey that will be activated
const { licenseKey, url } = generateCheckoutUrl({
  softwareId: "your-software-id",
  successUrl: `https://codecheckout.dev/activate?key={licenseKey}`, // Optional. Default is a page where the license and app name are shown. The query params are automatically attached to the default or custom `successUrl`
  cancelUrl: "https://riff-tech.com/codecheckout", // Optional. Default is shown.
  name: appDisplayName, // Optional. If provided, it will be attached as a query param to the `successUrl`
  redirectUri: successUrl, // Optional. If provided, it will be attached as a query param to the `successUrl`
  testMode: false, // Optional. Creates a test checkout session where no charges are incurred
});

console.log("checkoutUrl: ", url);
// http://riff-tech.com/activate?key=YOUR-LICENSE-KEY-HERE&name=Your%20Software%20Name&redirectUri=https://your-app.com

// Redirect the user to the checkout URL
https: window.location.href = url;

📚 API Reference

Analytics Tracking

logAnalyticsEvent({
  softwareId: string;
  commandId: string;
  licenseKey?: string;
  machineId?: string;
  sessionId?: string;
  timestamp?: string;
  metadata?: Record<string, unknown>; // Additional data you want to track
}): Promise<{ success: boolean }>;

License Validation

validateLicense({
  softwareId: string;
  licenseKey?: string;
  machineId?: string;
  sessionId?: string;
  environment?: object;
  forceOnlineValidation?: boolean;
  cacheDurationInHours?: number;
}): Promise<{ isValid: boolean, reason?: string }>;

Checkout URL Generation

generateCheckoutUrl({
  softwareId: string;
  successUrl?: string;
  cancelUrl?: string;
  testMode?: boolean;
  name?: string;
  redirectUri: string;
}): { licenseKey: string; url: string };

🎯 Examples

Explore our comprehensive examples in the /examples directory:

• 🔨 Basic Usage Example: Simple TypeScript program demonstrating core functionality
• 🌐 Browser Example: Modern implementation using Vite
• 🖥️ Node.js Server Example: Server-side implementation with Express

Each example comes with detailed documentation and step-by-step setup instructions.

🤝 Contributing

We welcome contributions! Feel free to submit issues and pull requests.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• GitHub Repository
• Documentation
• Issue Tracker