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