crovver-node 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-29
+
+### Added
+
+- **Core Client**
+  - `baseUrl` config option to override the API base URL (useful for local development and testing)
+  - `CrovverClient` class with full TypeScript support
+  - Automatic retry with exponential backoff for transient failures (5xx, 429, timeouts)
+  - Debug logging support with custom logger option
+
+- **Tenant Management** (B2B)
+  - `createTenant()` - Create a new tenant/workspace
+  - `getTenant()` - Get tenant information by external ID
+
+- **Plans**
+  - `getPlans()` - Fetch all available subscription plans
+
+- **Subscriptions**
+  - `getSubscriptions()` - Get active subscriptions for a tenant/user
+
+- **Checkout**
+  - `createCheckoutSession()` - Create payment checkout session
+  - Support for B2B and D2C checkout flows
+  - Support for Stripe, Paddle, and LemonSqueezy providers
+
+- **Entitlements**
+  - `canAccess()` - Check feature access for tenant/user
+  - `recordUsage()` - Record metered usage
+  - `checkUsageLimit()` - Check usage against limits
+
+- **Seat-Based Billing**
+  - `getActiveCapacity()` - Get current seat utilization
+  - `recordSeatAllocation()` - Record seat assignment with proration calculation
+  - `removeSeat()` - Remove seat allocation
+  - `createProrationCheckout()` - Create payment session for seat upgrades
+
+- **Payment Providers**
+  - `getSupportedProviders()` - List available payment providers
+
+- **Error Handling**
+  - `CrovverError` class with status codes and error codes
+  - Automatic classification of retryable vs non-retryable errors
+
+- **TypeScript**
+  - Full type definitions for all requests and responses
+  - Strict TypeScript configuration
+  - ESM and CommonJS dual build support
+
+### Security
+
+- API key passed via Authorization header (not in URL)
+- No credentials logged in debug mode
+
+## [0.1.0] - 2026-01-15
+
+### Added
+
+- Initial beta release
+- Basic client implementation
+- Core API methods
+
+---
+
+## Migration Guide
+
+### From 0.x to 1.0.0
+
+1. **Import Changes**
+
+   ```typescript
+   // Old
+   import CrovverClient from "@crovver/sdk";
+
+   // New (recommended)
+   import { CrovverClient } from "@crovver/sdk";
+   ```
+
+2. **Configuration**
+
+   ```typescript
+   // New options available
+   const client = new CrovverClient({
+     apiKey: "your-key",
+     maxRetries: 3, // New: Configure retries (default: 3)
+     debug: true, // New: Enable debug logging
+   });
+   ```
+
+3. **New Methods**
+   - `recordSeatAllocation()` - Use for seat-based billing
+   - `removeSeat()` - Use for seat removal
+   - `getSupportedProviders()` - List payment providers
+
+4. **Error Handling**
+   ```typescript
+   // CrovverError now includes more context
+   catch (error) {
+     if (error instanceof CrovverError) {
+       console.log(error.isRetryable); // New: Check if error is retryable
+       console.log(error.statusCode);
+       console.log(error.code);
+     }
+   }
+   ```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Crovver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,271 @@
+# crovver-node
+
+[![npm version](https://img.shields.io/npm/v/crovver-node.svg)](https://www.npmjs.com/package/crovver-node)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.4+-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Node.js/TypeScript SDK for integrating [Crovver](https://crovver.com) subscription management into your backend.
+
+## Features
+
+- **Complete API Coverage** — tenants, plans, subscriptions, checkout, entitlements, invoices, proration
+- **TypeScript Support** — full type definitions included
+- **B2B & D2C Support** — works with both organization types
+- **Error Handling** — `CrovverError` class with status codes and retryability flags
+- **Automatic Retries** — exponential backoff with jitter for transient failures
+- **No Checkout Retry** — payment-creating endpoints are never retried to prevent duplicate charges
+- **ESM & CommonJS** — dual module support
+
+## Installation
+
+```bash
+npm install crovver-node
+# or
+yarn add crovver-node
+# or
+pnpm add crovver-node
+```
+
+## Quick Start
+
+```typescript
+import { CrovverClient } from "crovver-node";
+
+const crovver = new CrovverClient({
+  apiKey: "sk_live_your_api_key",
+});
+
+const canAccess = await crovver.canAccess("company-123", "advanced-analytics");
+if (canAccess) {
+  console.log("Access granted!");
+}
+```
+
+## Configuration
+
+```typescript
+interface CrovverConfig {
+  apiKey: string;       // Bearer API key — starts with sk_live_ or sk_test_
+  timeout?: number;     // ms, default 30 000
+  maxRetries?: number;  // default 3
+  debug?: boolean;      // default false
+  logger?: (message: string, data?: unknown) => void;
+}
+```
+
+## Error Handling
+
+```typescript
+import { CrovverClient, CrovverError } from "crovver-node";
+
+try {
+  await crovver.canAccess("company-123", "premium-feature");
+} catch (error) {
+  if (error instanceof CrovverError) {
+    console.error(error.message);
+    console.error("HTTP status:", error.statusCode);
+    console.error("Retryable:", error.isRetryable);
+  }
+}
+```
+
+Automatic retries apply to 5xx, 429, 408, and network errors. 4xx errors are **not** retried.
+
+---
+
+## API Reference
+
+### Tenant Management (B2B Only)
+
+#### `createTenant`
+
+```typescript
+const result = await crovver.createTenant({
+  externalTenantId: "company-123",
+  name: "Acme Corporation",
+  ownerExternalUserId: "user-456",
+  ownerEmail: "admin@acme.com",
+  ownerName: "John Doe",
+});
+console.log("Tenant ID:", result.tenant.id);
+```
+
+#### `getTenant`
+
+```typescript
+const { tenant, members } = await crovver.getTenant("company-123");
+```
+
+---
+
+### Plans
+
+#### `getPlans`
+
+```typescript
+const { plans } = await crovver.getPlans();
+plans.forEach((plan) => {
+  console.log(`${plan.name}: ${plan.pricing.currency} ${plan.pricing.amount}/${plan.pricing.interval}`);
+});
+```
+
+---
+
+### Subscriptions
+
+#### `getSubscriptions`
+
+```typescript
+const { subscriptions } = await crovver.getSubscriptions("company-123");
+subscriptions.forEach((sub) => {
+  console.log(`${sub.plan.name} — ${sub.status}`);
+});
+```
+
+#### `cancelSubscription`
+
+Cancels at period end (no immediate termination).
+
+```typescript
+const result = await crovver.cancelSubscription(
+  "sub-uuid",
+  "too_expensive",
+  "Pricing is a bit high for our team size"
+);
+console.log(`Ends at: ${result.willEndAt}`);
+```
+
+---
+
+### Checkout
+
+#### `createCheckoutSession`
+
+**B2B:**
+
+```typescript
+const checkout = await crovver.createCheckoutSession({
+  requestingUserId: "user-456",
+  requestingTenantId: "company-123",
+  planId: "plan-uuid",
+  provider: "stripe",
+  successUrl: "https://myapp.com/success",
+  cancelUrl: "https://myapp.com/cancel",
+});
+window.location.href = checkout.checkoutUrl;
+```
+
+**D2C (tenant auto-created):**
+
+```typescript
+const checkout = await crovver.createCheckoutSession({
+  requestingUserId: "user-789",
+  userEmail: "john@example.com",
+  userName: "John Doe",
+  planId: "plan-uuid",
+  provider: "stripe",
+  successUrl: "https://myapp.com/success",
+  cancelUrl: "https://myapp.com/cancel",
+});
+```
+
+---
+
+### Entitlements
+
+#### `canAccess`
+
+```typescript
+const canAccess = await crovver.canAccess("company-123", "advanced-analytics");
+```
+
+#### `recordUsage`
+
+```typescript
+await crovver.recordUsage("company-123", "api-calls", 1, {
+  endpoint: "/api/v1/users",
+});
+```
+
+#### `checkUsageLimit`
+
+```typescript
+const usage = await crovver.checkUsageLimit("company-123", "api-calls");
+console.log(`${usage.current} / ${usage.limit} — allowed: ${usage.allowed}`);
+```
+
+---
+
+### Proration (Seat-Based Plans)
+
+#### `createProrationCheckout`
+
+Creates a one-time payment session for a mid-cycle seat capacity upgrade.
+The proration amount is calculated server-side.
+
+```typescript
+const checkout = await crovver.createProrationCheckout({
+  requestingEntityId: "company-123",
+  newCapacity: 15,
+  planId: "plan-uuid",           // optional
+  successUrl: "https://myapp.com/success",
+  cancelUrl: "https://myapp.com/cancel",
+});
+
+if (checkout.checkoutUrl) {
+  window.location.href = checkout.checkoutUrl;
+}
+console.log(`Prorated amount: ${checkout.prorationAmount} ${checkout.prorationDetails.currency}`);
+```
+
+---
+
+### Billing
+
+#### `getInvoices`
+
+```typescript
+const { invoices } = await crovver.getInvoices("company-123");
+invoices.forEach((inv) => {
+  console.log(`${inv.invoice_number}: ${inv.total_amount} ${inv.currency} — ${inv.status}`);
+});
+```
+
+---
+
+### Payment Providers
+
+#### `getSupportedProviders`
+
+```typescript
+const { providers } = await crovver.getSupportedProviders();
+providers.forEach((p) => console.log(`${p.name}: ${p.code}`));
+```
+
+---
+
+## TypeScript Exports
+
+```typescript
+import {
+  CrovverClient,
+  CrovverError,
+  CrovverConfig,
+  Plan,
+  Subscription,
+  Tenant,
+  CreateTenantRequest,
+  CreateCheckoutSessionRequest,
+  CreateProrationCheckoutRequest,
+  CreateProrationCheckoutResponse,
+  CancelSubscriptionResponse,
+  GetInvoicesResponse,
+  CheckUsageLimitResponse,
+} from "crovver-node";
+```
+
+---
+
+## License
+
+MIT

package/dist/cjs/constants.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CROVVER_BASE_URL = void 0;
+exports.CROVVER_BASE_URL = "https://app.crovver.com";
+//# sourceMappingURL=constants.js.map

package/dist/cjs/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,gBAAgB,GAAG,yBAAyB,CAAC"}