Fresh Squeezy

https://github.com/yosefhayim/fresh-squeezy
Admin
Fresh Squeezy is a comprehensive billing layer for Lemon Squeezy that simplifies checkout, webhook...
Tokens:62,481
Snippets:290
Trust Score:4
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Run Fresh Squeezy Setup Wizard

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/llms.txt

Executes the Fresh Squeezy setup wizard using npx. This command auto-discovers stores and products, generates configuration files (.billing/billing-config.ts and .billing/example.ts), and caches previous answers in .billing/wizard-cache.json.

```bash
npx fresh-squeezy wizard
```

--------------------------------

### Install fresh-squeezy via npm

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/README.md

The standard command to install the fresh-squeezy package into your Node.js project.

```bash
npm install fresh-squeezy
```

--------------------------------

### Subscription JSON Example with URLs

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/scripts/ls-changelog/changelog/guides-developer-guide-managing-subscriptions.md

This JSON example shows the structure of a subscription object, specifically highlighting the 'urls' attribute. It includes URLs for updating payment methods and accessing the customer portal, which are crucial for managing subscription billing.

```json
{
  "type": "subscriptions",
  "id": "1",
  "attributes": {
    ...
    "urls": {
      "update_payment_method": "https://my-store.lemonsqueezy.com/subscription/1/payment-details?expires=1674045831&signature=31cf3c83983a03a6cf92e4ec3b469fc044eace0a13183dcb1d7bc0da3bad6f31",
      "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1674045831&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5"
    }
    ...
  }
}
```

--------------------------------

### Run Setup Wizard

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/README.md

Executes the CLI wizard to auto-discover stores and products, generating the necessary configuration files for the project.

```bash
npx fresh-squeezy-billing wizard
```

--------------------------------

### Utilize Fresh Squeezy CLI Commands

Source: https://context7.com/yosefhayim/fresh-squeezy/llms.txt

Provides command-line tools for setting up and validating Fresh Squeezy configurations. Includes an interactive setup wizard for store discovery and configuration file generation, a validation tool, and a help command.

```bash
# Interactive setup wizard - auto-discovers stores, generates config files
npx fresh-squeezy-billing wizard

# Validate your configuration
npx fresh-squeezy-billing validate

# Show help
npx fresh-squeezy-billing help
```

--------------------------------

### Customer Object JSON Example

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/scripts/ls-changelog/changelog/api-customers.md

This JSON object represents a customer within the Fresh Squeezy system. It includes all relevant customer attributes, such as identification, contact information, subscription status, revenue figures, and timestamps. This example serves as a reference for the expected data structure when interacting with customer data.

```json
{
  "type": "customers",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "name": "John Doe",
    "email": "[email protected]",
    "status": "subscribed",
    "city": null,
    "region": null,
    "country": "US",
    "total_revenue_currency": 84332,
    "mrr": 1999,
    "status_formatted": "Subscribed",
    "country_formatted": "United States",
    "total_revenue_currency_formatted": "$843.32",
    "mrr_formatted": "$19.99",
    "urls": {
      "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=82ae290ceac8edd4190c82825dd73a8743346d894a8ddbc4898b97eb96d105a5"
    },
    "created_at": "2022-12-01T13:01:07.000000Z",
    "updated_at": "2022-12-09T09:05:21.000000Z",
    "test_mode": false
  }
}
```

--------------------------------

### fresh-squeezy Management API Methods

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/README.md

Provides examples of management-related API calls for fresh-squeezy, allowing for operations such as listing webhooks, retrieving subscription details, managing orders, customers, license keys, products, and discounts.

```javascript
// Management (all return typed data)
billing.listWebhooks()
billing.getSubscription(id) / listSubscriptions(filter?)
billing.listOrders(filter?) / getOrder(id) / issueOrderRefund(id, amount)
billing.getCustomer(id) / createCustomer(storeId, name, email)
billing.validateLicense(key) / activateLicense(key, instanceName)
billing.listProducts(storeId?) / listVariants(productId?)
billing.createDiscount(storeId, { name, code, amount })
```

--------------------------------

### JSON Example for Creating a Customer

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-customers-create-customer.md

This JSON object demonstrates the structure required to create a new customer. It includes fields for customer details such as name, email, and address, as well as store-specific information and relationship links.

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://api.lemonsqueezy.com/v1/customers/1"
  },
  "data": {
    "type": "customers",
    "id": "1",
    "attributes": {
      "store_id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "status": "subscribed",
      "city": "New York",
      "region": "NY",
      "country": "US",
      "total_revenue_currency": 0,
      "mrr": 0,
      "status_formatted": "Subscribed",
      "country_formatted": "United States",
      "total_revenue_currency_formatted": "0.00",
      "mrr_formatted": "$0.00",
      "urls": {
        "customer_portal": null
      },
      "created_at": "2022-12-01T13:01:07.000000Z",
      "updated_at": "2022-12-09T09:05:21.000000Z",
      "test_mode": false
    },
    "relationships": {
      "store": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/customers/1/store",
          "self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/store"
        }
      },
      "orders": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/customers/1/orders",
          "self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/orders"
        }
      },
      "subscriptions": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/customers/1/subscriptions",
          "self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/subscriptions"
        }
      },
      "license-keys": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/customers/1/license-keys",
          "self": "https://api.lemonsqueezy.com/v1/customers/1/relationships/license-keys"
        }
      }
    },
    "links": {
      "self": "https://api.lemonsqueezy.com/v1/customers/1"
    }
  }
}
```

--------------------------------

### Representing a Price Object in JSON

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-prices-the-price-object.md

This JSON example demonstrates the structure of a Price object, including nested tier configurations for graduated pricing and subscription-specific attributes.

```json
{
  "type": "prices",
  "id": "1",
  "attributes": {
    "variant_id": 1,
    "category": "subscription",
    "scheme": "graduated",
    "usage_aggregation": null,
    "unit_price": 999,
    "unit_price_decimal": null,
    "setup_fee_enabled": false,
    "setup_fee": null,
    "package_size": 1,
    "tiers": [
      {
        "last_unit": 2,
        "unit_price": 10000,
        "unit_price_decimal": null,
        "fixed_fee": 1000
      },
      {
        "last_unit": "inf",
        "unit_price": 1000,
        "unit_price_decimal": null,
        "fixed_fee": 1000
      }
    ],
    "renewal_interval_unit": "year",
    "renewal_interval_quantity": 1,
    "trial_interval_unit": "day",
    "trial_interval_quantity": 30,
    "min_price": null,
    "suggested_price": null,
    "tax_code": "eservice",
    "created_at": "2023-05-24T14:15:06.000000Z",
    "updated_at": "2023-06-24T14:44:38.000000Z"
  }
}
```

--------------------------------

### JSON Order Data Structure Example

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-orders.md

This snippet demonstrates the structure of a JSON object representing an order in the Fresh Squeezy system. It includes details about the order, customer, items, and associated URLs. This format is crucial for data exchange and API interactions.

```json
{
  "type": "orders",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "customer_id": 1,
    "identifier": "104e18a2-d755-4d4b-80c4-a6c1dcbe1c10",
    "order_number": 1,
    "user_name": "John Doe",
    "user_email": "[email protected]",
    "currency": "USD",
    "currency_rate": "1.0000",
    "subtotal": 999,
    "setup_fee": 999,
    "discount_total": 0,
    "tax": 200,
    "total": 1199,
    "subtotal_usd": 999,
    "setup_fee_usd": 999,
    "discount_total_usd": 0,
    "tax_usd": 200,
    "total_usd": 1199,
    "tax_name": "VAT",
    "tax_rate": "20.00",
    "tax_inclusive": false,
    "status": "paid",
    "status_formatted": "Paid",
    "refunded": false,
    "refunded_at": null,
    "subtotal_formatted": "$9.99",
    "setup_fee_formatted": "$9.99",
    "discount_total_formatted": "$0.00",
    "tax_formatted": "$2.00",
    "total_formatted": "$11.99",
    "first_order_item": {
      "id": 1,
      "order_id": 1,
      "product_id": 1,
      "variant_id": 1,
      "product_name": "Test Limited License for 2 years",
      "variant_name": "Default",
      "price": 1199,
      "created_at": "2021-08-17T09:45:53.000000Z",
      "updated_at": "2021-08-17T09:45:53.000000Z",
      "test_mode": false
    },
    "urls": {
      "receipt": "https://app.lemonsqueezy.com/my-orders/104e18a2-d755-4d4b-80c4-a6c1dcbe1c10?signature=8847fff02e1bfb0c7c43ff1cdf1b1657a8eed2029413692663b86859208c9f42"
    },
    "created_at": "2021-08-17T09:45:53.000000Z",
    "updated_at": "2021-08-17T09:45:53.000000Z",
    "test_mode": false
  }
}
```

--------------------------------

### Initialize Billing and Handle Webhooks

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/README.md

Demonstrates how to initialize the billing client with API keys and callbacks, create a checkout URL, and verify/handle incoming webhooks in an Express application.

```typescript
import { createBilling } from "fresh-squeezy";

const billing = await createBilling({
  apiKey: process.env.LS_API_KEY!,
  webhookSecret: process.env.LS_WEBHOOK_SECRET!,
  callbacks: {
    onOrder: async (event, method) => {
      if (method === "purchase") { /* handle purchase */ }
      if (method === "refund") { /* handle refund */ }
    },
    onSubscription: async (event, method) => {
      if (method === "created") { /* activate subscription */ }
    },
    onLicenseKey: async (event, method) => {
      if (method === "created") { /* store key */ }
    }
  }
});

const url = await billing.createCheckout({
  variantId: billing.plans[0].variantId,
  email: "user@example.com",
  userId: "user_abc"
});

app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  if (!billing.verifyWebhook(req.body.toString(), req.headers["x-signature"] as string)) return res.sendStatus(401);
  await billing.handleWebhook(JSON.parse(req.body.toString()));
  res.json({ ok: true });
});
```

--------------------------------

### GET /subscription-invoices

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/scripts/ls-changelog/changelog/api-subscription-invoices-the-subscription-invoice-object.md

Retrieves the structure and attributes of a subscription invoice object.

```APIDOC
## GET /subscription-invoices

### Description
Retrieves the details of a specific subscription invoice object, including financial data, customer information, and payment status.

### Method
GET

### Endpoint
/v1/subscription-invoices/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the subscription invoice.

### Response
#### Success Response (200)
- **store_id** (integer) - The ID of the Store this subscription invoice belongs to.
- **subscription_id** (integer) - The ID of the Subscription associated with this invoice.
- **customer_id** (integer) - The ID of the customer this invoice belongs to.
- **user_name** (string) - The full name of the customer.
- **user_email** (string) - The email address of the customer.
- **total** (integer) - The total cost of the invoice in cents.
- **currency** (string) - The ISO 4217 currency code.
- **status** (string) - The current status of the invoice.
- **created_at** (string) - ISO 8601 formatted date-time string.

#### Response Example
{
  "data": {
    "type": "subscription-invoices",
    "id": "1",
    "attributes": {
      "store_id": 1,
      "subscription_id": 1,
      "customer_id": 1,
      "user_name": "John Doe",
      "user_email": "john@example.com",
      "total": 999,
      "currency": "USD",
      "status": "paid",
      "created_at": "2023-01-01T00:00:00Z"
    }
  }
}
```

--------------------------------

### Initialize Billing and Handle Webhooks with TypeScript

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/llms.txt

Demonstrates how to initialize the billing instance with required API credentials and callbacks, generate a checkout URL, and integrate webhook verification within an Express application.

```typescript
import { createBilling } from "fresh-squeezy";

const billing = await createBilling({
  apiKey: process.env.LS_API_KEY,
  webhookSecret: process.env.LS_WEBHOOK_SECRET,
  skipTestEvents: true,
  callbacks: {
    onOrder: async (event, method, meta) => {
      if (method === "purchase") await db.grantAccess(event.userId);
      if (method === "refund")   await db.revokeAccess(event.userId);
    },
    onSubscription: async (event, method, meta) => {
      if (method === "created")         await db.startSubscription(event.userId);
      if (method === "cancelled")       await db.cancelSubscription(event.userId);
      if (method === "payment_failed")  await notify.sendPaymentFailed(event.email);
    },
    onLicenseKey: async (event, method, meta) => {
      if (method === "created") await db.storeLicense(event.userId, event.key);
    },
  },
});

// Checkout
const url = await billing.createCheckout({ variantId: "123", email: "user@example.com", userId: "user_1" });

// Webhook (Express)
app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  if (!billing.verifyWebhook(req.body.toString(), req.headers["x-signature"] as string))
    return res.sendStatus(401);
  await billing.handleWebhook(JSON.parse(req.body.toString()));
  res.json({ ok: true });
});
```

--------------------------------

### GET /orders/{id}

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/scripts/ls-changelog/changelog/api-orders-the-order-object.md

Retrieves the details of a specific order by its unique identifier.

```APIDOC
## GET /orders/{id}

### Description
Retrieves a single order resource containing financial data, customer information, and order status.

### Method
GET

### Endpoint
/orders/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order.

### Response
#### Success Response (200)
- **type** (string) - The resource type (orders).
- **id** (string) - The order ID.
- **attributes** (object) - The order details including store_id, customer_id, total, status, and currency.

#### Response Example
{
  "type": "orders",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "customer_id": 1,
    "order_number": 1,
    "user_name": "John Doe",
    "total": 1199,
    "status": "paid",
    "currency": "USD"
  }
}
```

--------------------------------

### JSON Example for Updating a License Key

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-license-keys-update-license-key.md

This JSON structure represents an example payload for updating a license key via the Lemon Squeezy API. It includes versioning, links, and detailed data about the subscription item being updated. This is a read-only representation of a subscription item.

```json
{
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://api.lemonsqueezy.com/v1/subscription-item/1"
  },
  "data": {
    "type": "subscription-items",
    "id": "1",
    "attributes": {
      "subscription_id": 1,
      "price_id": 1,
      "quantity": 10,
      "is_usage_based": false,
      "created_at": "2023-07-18T12:16:24.000000Z",
      "updated_at": "2023-07-18T12:23:18.000000Z"
    },
    "relationships": {
      "subscription": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/subscription",
          "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/subscription"
        }
      },
      "price": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/price",
          "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/price"
        }
      },
      "usage-records": {
        "links": {
          "related": "https://api.lemonsqueezy.com/v1/subscription-items/1/usage-records",
          "self": "https://api.lemonsqueezy.com/v1/subscription-items/1/relationships/usage-records"
        }
      }
    },
    "links": {
      "self": "https://api.lemonsqueezy.com/v1/subscription-items/1"
    }
  }
}
```

--------------------------------

### createBilling - Initialize Billing

Source: https://context7.com/yosefhayim/fresh-squeezy/llms.txt

Initializes the billing instance with store discovery, caching, and event callbacks.

```APIDOC
## POST /createBilling

### Description
Initializes a fully configured billing instance. This setup enables automatic store discovery, plan caching, and registers callbacks for orders, subscriptions, and license keys.

### Method
POST

### Parameters
#### Request Body
- **apiKey** (string) - Required - Lemon Squeezy API Key
- **webhookSecret** (string) - Required - Secret for HMAC signature verification
- **storeId** (string) - Optional - Specific store ID to target
- **cachePath** (string) - Optional - Path for local cache file
- **callbacks** (object) - Required - Object containing onOrder, onSubscription, onLicenseKey, and onWebhook handlers

### Request Example
{
  "apiKey": "ls_...",
  "webhookSecret": "whsec_...",
  "callbacks": { "onOrder": "async function" }
}
```

--------------------------------

### Initialize Billing Instance with Fresh Squeezy

Source: https://context7.com/yosefhayim/fresh-squeezy/llms.txt

Creates a fully configured billing instance for Fresh Squeezy. It supports automatic store discovery, plan caching, and provides typed callbacks for various billing events like orders, subscriptions, and license keys. Dependencies include environment variables for API keys and optional configuration for caching and checkout expiration.

```typescript
import { createBilling } from "fresh-squeezy";

const billing = await createBilling({
  apiKey: process.env.LS_API_KEY!,
  webhookSecret: process.env.LS_WEBHOOK_SECRET!,
  storeId: "123456", // Optional: auto-detected if you have one store
  cachePath: ".billing/cache.json",
  cacheTtlMs: 3_600_000, // 1 hour
  checkoutExpiresInMs: 86_400_000, // 24 hours
  skipTestEvents: false,
  callbacks: {
    onOrder: async (event, method, meta) => {
      // event.userId, event.email, event.orderId, event.price
      if (method === "purchase") {
        await db.user.update({ where: { id: event.userId }, data: { isPro: true } });
      }
      if (method === "refund") {
        await db.user.update({ where: { id: event.userId }, data: { isPro: false } });
      }
    },
    onSubscription: async (event, method, meta) => {
      // event.userId, event.subscriptionId, event.status
      console.log(`Subscription ${method}:`, event.subscriptionId);
    },
    onLicenseKey: async (event, method, meta) => {
      // event.key, event.status, event.activationCount
      if (method === "created") {
        await db.license.create({ data: { userId: event.userId, key: event.key } });
      }
    },
    onWebhook: async (eventType, event, meta) => {
      // Catch-all for raw webhook events
      console.log(`Webhook ${eventType}:`, meta.isTest ? "(test)" : "");
    },
  },
});

// Access discovered data
console.log("Stores:", billing.stores);
console.log("Plans:", billing.plans);

```

--------------------------------

### GET /v1/users/{id}

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/scripts/ls-changelog/changelog/api-users-retrieve-user.md

Retrieves the details of a specific user by their unique identifier.

```APIDOC
## GET /v1/users/{id}

### Description
Retrieves the details of a specific user account associated with the provided ID.

### Method
GET

### Endpoint
/v1/users/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the user.

### Request Example
GET /v1/users/1

### Response
#### Success Response (200)
- **data** (object) - The user resource object containing attributes like name, email, and avatar_url.

#### Response Example
{
  "data": {
    "type": "users",
    "id": "1",
    "attributes": {
      "name": "John Doe",
      "email": "user@example.com",
      "color": "#898FA9",
      "avatar_url": "https://www.gravatar.com/avatar/1ace5b3965c59dbcd1db79d85da75048?d=blank",
      "createdAt": "2024-05-24T14:08:31.000000Z"
    }
  }
}
```

--------------------------------

### GET /orders

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-orders-the-order-object.md

Retrieves the structure and attributes of an Order object, including financial details, customer information, and status.

```APIDOC
## GET /orders

### Description
Retrieves the details of an order object. This object contains comprehensive financial data, customer details, and status information for a specific transaction.

### Method
GET

### Endpoint
/v1/orders/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the order.

### Response
#### Success Response (200)
- **store_id** (integer) - The ID of the store this order belongs to.
- **customer_id** (integer) - The ID of the customer this order belongs to.
- **identifier** (string) - The unique identifier (UUID) for this order.
- **order_number** (integer) - Sequential order number for the store.
- **user_name** (string) - Full name of the customer.
- **user_email** (string) - Email address of the customer.
- **currency** (string) - ISO 4217 currency code.
- **total** (integer) - Total cost in cents.
- **status** (string) - The status of the order.
- **created_at** (string) - ISO 8601 formatted date-time string.

#### Response Example
{
  "store_id": 12345,
  "customer_id": 67890,
  "identifier": "550e8400-e29b-41d4-a716-446655440000",
  "order_number": 1,
  "user_name": "John Doe",
  "user_email": "john@example.com",
  "currency": "USD",
  "total": 999,
  "status": "paid",
  "created_at": "2023-10-27T10:00:00Z"
}
```

--------------------------------

### Execute CLI Commands

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/README.md

Common command-line interface operations for setting up and validating the Fresh Squeezy billing configuration.

```bash
npx fresh-squeezy-billing wizard
npx fresh-squeezy-billing validate
npx fresh-squeezy-billing help
```

--------------------------------

### GET /prices/{id}

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/scripts/ls-changelog/changelog/api-prices-the-price-object.md

Retrieve the details of a specific Price object by its unique identifier.

```APIDOC
## GET /prices/{id}

### Description
Retrieves the attributes of a specific Price object, including pricing schemes, tiers, and subscription intervals.

### Method
GET

### Endpoint
/v1/prices/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the price object.

### Response
#### Success Response (200)
- **type** (string) - The resource type (prices).
- **id** (string) - The ID of the price.
- **attributes** (object) - The collection of price attributes including variant_id, scheme, unit_price, and tiers.

#### Response Example
{
  "type": "prices",
  "id": "1",
  "attributes": {
    "variant_id": 1,
    "category": "subscription",
    "scheme": "graduated",
    "unit_price": 999,
    "tiers": [
      {
        "last_unit": 2,
        "unit_price": 10000,
        "fixed_fee": 1000
      }
    ],
    "renewal_interval_unit": "year",
    "created_at": "2023-05-24T14:15:06.000000Z"
  }
}
```

--------------------------------

### Initialize Billing and Express Router

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/README.md

Demonstrates how to integrate the Fresh Squeezy billing router into an Express application and configure custom deduplication using Redis.

```typescript
app.use(
  "/billing",
  billing.getExpressRouter({
    getUserId: (req) => req.user.id,
    getUserEmail: (req) => req.user.email,
  })
);

import { RedisDedupBackend } from "fresh-squeezy";

const billing = await createBilling({
  ...config,
  dedup: { backend: new RedisDedupBackend(redisClient), ttlMs: 86_400_000 },
});
```

--------------------------------

### GET /subscription-invoices

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-subscription-invoices-the-subscription-invoice-object.md

Retrieves the structure and attributes of a subscription invoice object, including billing details, currency information, and tax calculations.

```APIDOC
## GET /subscription-invoices

### Description
Retrieves the details of a subscription invoice object. This object contains information regarding the store, customer, payment methods, and financial totals.

### Method
GET

### Endpoint
/v1/subscription-invoices/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the subscription invoice.

### Response
#### Success Response (200)
- **store_id** (integer) - The ID of the Store this subscription invoice belongs to.
- **subscription_id** (integer) - The ID of the Subscription associated with this invoice.
- **customer_id** (integer) - The ID of the customer this invoice belongs to.
- **user_name** (string) - The full name of the customer.
- **user_email** (string) - The email address of the customer.
- **billing_reason** (string) - The reason for the invoice being generated.
- **currency** (string) - The ISO 4217 currency code.
- **total** (integer) - Total cost of the invoice in cents.
- **status** (string) - The status of the invoice.
- **created_at** (string) - ISO 8601 formatted date-time string.

#### Response Example
{
  "data": {
    "type": "subscription-invoices",
    "id": "1",
    "attributes": {
      "store_id": 1,
      "subscription_id": 1,
      "customer_id": 1,
      "user_name": "John Doe",
      "user_email": "john@example.com",
      "total": 999,
      "currency": "USD",
      "status": "paid",
      "created_at": "2023-01-01T00:00:00.000000Z"
    }
  }
}
```

--------------------------------

### Access Product Catalog with TypeScript

Source: https://context7.com/yosefhayim/fresh-squeezy/llms.txt

Provides functionality to query products, variants, pricing, and associated downloadable files. Useful for building storefronts or managing digital product assets.

```typescript
// List all products
const products = await billing.listProducts("store_123");

// Get product details
const product = await billing.getProduct("prod_123");
console.log("Product:", product.name, product.description);

// List variants for a product
const variants = await billing.listVariants("prod_123");
for (const variant of variants) {
  console.log(`${variant.name}: $${variant.price / 100}`);
}

// Get variant details
const variant = await billing.getVariant("var_123");

// List prices for a variant (supports multiple currencies)
const prices = await billing.listPrices("var_123");

// Get downloadable files
const files = await billing.listFiles("var_123");
for (const file of files) {
  console.log(`${file.name}: ${file.download_url}`);
}
```

--------------------------------

### GET /variants

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-variants.md

Retrieves the structure and attributes of a Variant object, which represents a specific version or configuration of a product.

```APIDOC
## GET /variants

### Description
Retrieves the details of a specific variant. A variant represents a specific configuration of a product, including pricing, licensing rules, and subscription settings.

### Method
GET

### Endpoint
/v1/variants/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the variant.

### Request Example
GET /v1/variants/1

### Response
#### Success Response (200)
- **type** (string) - The resource type (variants).
- **id** (string) - The variant ID.
- **attributes** (object) - The collection of variant properties including product_id, name, slug, and license settings.

#### Response Example
{
  "type": "variants",
  "id": "1",
  "attributes": {
    "product_id": 1,
    "name": "Example Variant",
    "slug": "46beb127-a8a9-33e6-89b5-078505657239",
    "description": "<p>Lorem ipsum...</p>",
    "price": 999,
    "is_subscription": false,
    "has_license_keys": false,
    "license_activation_limit": 5,
    "status": "published",
    "created_at": "2021-05-24T14:15:06.000000Z",
    "updated_at": "2021-06-24T14:44:38.000000Z",
    "test_mode": false
  }
}
```

--------------------------------

### TypeScript Build Commands

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/AGENTS.md

Standard build commands for the project using pnpm. These commands handle compilation, type checking, and cleaning the build artifacts.

```bash
# Compile TypeScript to dist/ using tsc
pnpm build

# Type-check without emitting files
pnpm typecheck

# Remove the dist/ directory
pnpm clean
```

--------------------------------

### GET /customers/{id}

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/changelog/api-customers-the-customer-object.md

Retrieves the details of a specific customer object, including their store association, revenue metrics, and marketing status.

```APIDOC
## GET /customers/{id}

### Description
Retrieves the details of a specific customer object, including their store association, revenue metrics, and marketing status.

### Method
GET

### Endpoint
/customers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer.

### Response
#### Success Response (200)
- **type** (string) - The resource type (customers).
- **id** (string) - The customer ID.
- **attributes** (object) - The customer data attributes including store_id, name, email, status, city, region, country, total_revenue_currency, mrr, and URLs.

#### Response Example
{
  "type": "customers",
  "id": "1",
  "attributes": {
    "store_id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "status": "subscribed",
    "city": null,
    "region": null,
    "country": "US",
    "total_revenue_currency": 84332,
    "mrr": 1999,
    "status_formatted": "Subscribed",
    "country_formatted": "United States",
    "total_revenue_currency_formatted": "$843.32",
    "mrr_formatted": "$19.99",
    "urls": {
      "customer_portal": "https://my-store.lemonsqueezy.com/billing?expires=1666869343&signature=..."
    },
    "created_at": "2022-12-01T13:01:07.000000Z",
    "updated_at": "2022-12-09T09:05:21.000000Z",
    "test_mode": false
  }
}
```

--------------------------------

### GET /v1/subscription-items/{id}

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/scripts/ls-changelog/changelog/api-subscription-items.md

Retrieves the details of a specific subscription item, including its associated price, quantity, and usage-based billing status.

```APIDOC
## GET /v1/subscription-items/{id}

### Description
Retrieves the details of a specific subscription item.

### Method
GET

### Endpoint
/v1/subscription-items/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the subscription item.

### Response
#### Success Response (200)
- **type** (string) - The resource type (subscription-items).
- **id** (string) - The ID of the subscription item.
- **attributes** (object) - Contains subscription_id, price_id, quantity, is_usage_based, created_at, and updated_at.
- **relationships** (object) - Links to related subscription, price, and usage-records.

#### Response Example
{
  "type": "subscription-items",
  "id": "1",
  "attributes": {
    "subscription_id": 1,
    "price_id": 1,
    "quantity": 1,
    "is_usage_based": false,
    "created_at": "2023-07-18T12:16:24.000000Z",
    "updated_at": "2023-07-18T12:16:24.000000Z"
  }
}
```

--------------------------------

### Configure Webhook Deduplication Backends

Source: https://context7.com/yosefhayim/fresh-squeezy/llms.txt

Demonstrates how to configure webhook deduplication for multi-instance environments using Redis, database (Prisma), or in-memory backends to prevent duplicate event processing.

```typescript
import { createBilling, RedisDedupBackend, DatabaseDedupBackend } from "fresh-squeezy";
import Redis from "ioredis";
import { PrismaClient } from "@prisma/client";

// Redis backend
const redis = new Redis(process.env.REDIS_URL);
const billingWithRedis = await createBilling({
  apiKey: process.env.LS_API_KEY!,
  webhookSecret: process.env.LS_WEBHOOK_SECRET!,
  callbacks: { onOrder: async () => {} },
  dedup: {
    backend: new RedisDedupBackend(redis, 86_400_000), // 24h TTL
    ttlMs: 86_400_000,
  },
});

// Database backend (Prisma)
// Requires: model WebhookDedup { key String @id; expiresAt DateTime }
const prisma = new PrismaClient();
const billingWithDb = await createBilling({
  apiKey: process.env.LS_API_KEY!,
  webhookSecret: process.env.LS_WEBHOOK_SECRET!,
  callbacks: { onOrder: async () => {} },
  dedup: {
    backend: new DatabaseDedupBackend(prisma),
    ttlMs: 86_400_000,
  },
});

// In-memory (default, single instance only)
const billingInMemory = await createBilling({
  apiKey: process.env.LS_API_KEY!,
  webhookSecret: process.env.LS_WEBHOOK_SECRET!,
  callbacks: { onOrder: async () => {} },
  dedup: { ttlMs: 3_600_000 }, // 1 hour
});
```

--------------------------------

### Define Codemap Markdown Structure

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/agents/doc-updater.md

A standardized template for documenting architectural areas, including entry points, component relationships, data flow, and external dependencies.

```markdown
# [Area] Codemap

**Last Updated:** YYYY-MM-DD
**Entry Points:** list of main files

## Architecture
[ASCII diagram of component relationships]

## Key Modules
| Module | Purpose | Exports | Dependencies |

## Data Flow
[How data flows through this area]

## External Dependencies
- package-name - Purpose, Version

## Related Areas
Links to other codemaps
```

--------------------------------

### Execute Documentation and Analysis Commands

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/agents/doc-updater.md

Commands used to generate architectural codemaps, visualize dependency graphs, and extract JSDoc documentation from TypeScript source files.

```bash
npx tsx scripts/codemaps/generate.ts
npx madge --image graph.svg src/
npx jsdoc2md src/**/*.ts
```

--------------------------------

### Agent Browser CLI Commands for E2E Testing

Source: https://github.com/yosefhayim/fresh-squeezy/blob/master/agents/e2e-runner.md

Provides essential command-line interface commands for the Agent Browser, a preferred tool for end-to-end testing. It covers setup, opening URLs, interacting with elements using semantic selectors, taking screenshots, and waiting for element visibility. Agent Browser offers AI-optimized features and auto-waiting capabilities built on Playwright.

```bash
# Setup
npm install -g agent-browser && agent-browser install

# Core workflow
agent-browser open https://example.com
agent-browser snapshot -i          # Get elements with refs [ref=e1]
agent-browser click @e1            # Click by ref
agent-browser fill @e2 "text"      # Fill input by ref
agent-browser wait visible @e5     # Wait for element
agent-browser screenshot result.png
```
Tokens:
Raw