Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,319 @@
import { z } from "zod";
import type {
BillingGateway,
BillingGatewayCustomer,
BillingGatewayCustomerInput,
BillingGatewayInvoice,
BillingGatewayInvoiceListInput,
BillingGatewaySubscription,
BillingGatewaySubscriptionInput,
} from "./types.js";
const DEFAULT_LAGO_TIMEOUT_MS = 10_000;
const DEFAULT_LAGO_PER_PAGE = 20;
export type LagoBillingGatewayConfig = {
apiUrl: string;
apiKey: string;
timeoutMs?: number;
fetchImpl?: typeof fetch;
};
export class LagoBillingGatewayError extends Error {
readonly code: "CONFIG_INVALID" | "REQUEST_FAILED" | "RESPONSE_INVALID";
readonly status?: number;
constructor(message: string, code: LagoBillingGatewayError["code"], status?: number) {
super(message);
this.name = "LagoBillingGatewayError";
this.code = code;
this.status = status;
}
}
const nullableString = z.string().nullable().optional();
const lagoCustomerSchema = z.object({
lago_id: z.string(),
external_id: z.string(),
name: nullableString,
email: nullableString,
currency: nullableString,
created_at: nullableString,
});
const lagoSubscriptionSchema = z.object({
lago_id: z.string(),
external_id: z.string(),
external_customer_id: z.string(),
plan_code: z.string(),
status: z.string().nullable().optional(),
name: nullableString,
current_billing_period_started_at: nullableString,
current_billing_period_ending_at: nullableString,
created_at: nullableString,
});
const lagoInvoiceSchema = z.object({
lago_id: z.string(),
number: nullableString,
external_customer_id: nullableString,
customer: z
.object({
external_id: nullableString,
})
.nullable()
.optional(),
status: z.string().nullable().optional(),
payment_status: z.string().nullable().optional(),
invoice_type: nullableString,
currency: nullableString,
total_amount_cents: z.number().nullable().optional(),
issuing_date: nullableString,
file_url: nullableString,
});
const customerResponseSchema = z.object({ customer: lagoCustomerSchema });
const subscriptionResponseSchema = z.object({ subscription: lagoSubscriptionSchema });
const invoiceResponseSchema = z.object({ invoice: lagoInvoiceSchema });
const invoicesResponseSchema = z.object({ invoices: z.array(lagoInvoiceSchema) });
type LagoCustomer = z.infer<typeof lagoCustomerSchema>;
type LagoSubscription = z.infer<typeof lagoSubscriptionSchema>;
type LagoInvoice = z.infer<typeof lagoInvoiceSchema>;
export function createLagoBillingGateway(config: LagoBillingGatewayConfig): BillingGateway {
return new LagoBillingGateway(config);
}
export function normalizeLagoApiUrl(apiUrl: string): string {
let url: URL;
try {
url = new URL(apiUrl);
} catch {
throw new LagoBillingGatewayError("Lago API URL must be an absolute URL.", "CONFIG_INVALID");
}
if (url.protocol !== "http:" && url.protocol !== "https:") {
throw new LagoBillingGatewayError("Lago API URL must use http or https.", "CONFIG_INVALID");
}
url.pathname = url.pathname.replace(/\/+$/u, "");
return url.toString().replace(/\/$/u, "");
}
export function redactLagoValue(value: string | null | undefined): string | null {
if (!value) return null;
if (value.length <= 8) return "[redacted]";
return `${value.slice(0, 4)}…${value.slice(-4)}`;
}
class LagoBillingGateway implements BillingGateway {
private readonly apiUrl: string;
private readonly apiKey: string;
private readonly timeoutMs: number;
private readonly fetchImpl: typeof fetch;
constructor(config: LagoBillingGatewayConfig) {
this.apiUrl = normalizeLagoApiUrl(config.apiUrl);
this.apiKey = config.apiKey.trim();
if (!this.apiKey) {
throw new LagoBillingGatewayError("Lago API key is required.", "CONFIG_INVALID");
}
this.timeoutMs = normalizeTimeout(config.timeoutMs);
this.fetchImpl = config.fetchImpl ?? fetch;
}
async createCustomer(input: BillingGatewayCustomerInput): Promise<BillingGatewayCustomer> {
const response = await this.request("/customers", {
method: "POST",
body: {
customer: {
external_id: input.tenantId,
name: input.name,
...(input.email ? { email: input.email } : {}),
...(input.currency ? { currency: input.currency } : {}),
...(input.country ? { country: input.country } : {}),
...(input.timezone ? { timezone: input.timezone } : {}),
},
},
});
return toCustomer(parseLagoResponse(customerResponseSchema, response));
}
async getCustomer(tenantId: string): Promise<BillingGatewayCustomer | null> {
const response = await this.request(`/customers/${encodeURIComponent(tenantId)}`, { method: "GET", allowNotFound: true });
return response === null ? null : toCustomer(parseLagoResponse(customerResponseSchema, response));
}
async createSubscription(input: BillingGatewaySubscriptionInput): Promise<BillingGatewaySubscription> {
assertPositiveSeatQuantity(input.seatQuantity);
const response = await this.request("/subscriptions", {
method: "POST",
body: {
subscription: {
external_customer_id: input.tenantId,
external_id: input.subscriptionExternalId,
plan_code: input.planCode,
name: input.name ?? `${input.planCode} (${input.seatQuantity} seats)`,
billing_time: "anniversary",
...(input.subscriptionAt ? { subscription_at: toIsoString(input.subscriptionAt) } : {}),
...(input.endingAt ? { ending_at: toIsoString(input.endingAt) } : {}),
},
},
});
return toSubscription(parseLagoResponse(subscriptionResponseSchema, response));
}
async getSubscription(subscriptionExternalId: string): Promise<BillingGatewaySubscription | null> {
const response = await this.request(`/subscriptions/${encodeURIComponent(subscriptionExternalId)}`, { method: "GET", allowNotFound: true });
return response === null ? null : toSubscription(parseLagoResponse(subscriptionResponseSchema, response));
}
async listInvoices(input: BillingGatewayInvoiceListInput = {}): Promise<BillingGatewayInvoice[]> {
const query = new URLSearchParams();
if (input.tenantId) query.set("external_customer_id", input.tenantId);
query.set("page", String(input.page ?? 1));
query.set("per_page", String(input.perPage ?? DEFAULT_LAGO_PER_PAGE));
const response = await this.request(`/invoices?${query.toString()}`, { method: "GET" });
return parseLagoResponse(invoicesResponseSchema, response).invoices.map(toInvoice);
}
async downloadInvoice(providerInvoiceId: string): Promise<BillingGatewayInvoice | null> {
const id = providerInvoiceId.trim();
if (!id) {
throw new LagoBillingGatewayError("Invoice id is required.", "CONFIG_INVALID");
}
const response = await this.request(`/invoices/${encodeURIComponent(id)}/download`, { method: "POST", allowNotFound: true });
return response === null ? null : toInvoice(parseLagoResponse(invoiceResponseSchema, response).invoice);
}
async updateInvoicePaymentStatus(providerInvoiceId: string, paymentStatus: BillingGatewayInvoice["paymentStatus"]): Promise<BillingGatewayInvoice> {
const id = providerInvoiceId.trim();
if (!id) {
throw new LagoBillingGatewayError("Invoice id is required.", "CONFIG_INVALID");
}
if (paymentStatus !== "pending" && paymentStatus !== "succeeded" && paymentStatus !== "failed") {
throw new LagoBillingGatewayError("Invoice payment status is invalid.", "CONFIG_INVALID");
}
const response = await this.request(`/invoices/${encodeURIComponent(id)}`, {
method: "PUT",
body: {
invoice: {
payment_status: paymentStatus,
},
},
});
return toInvoice(parseLagoResponse(invoiceResponseSchema, response).invoice);
}
private async request(path: string, options: { method: "GET" | "POST" | "PUT"; body?: unknown; allowNotFound?: boolean }): Promise<unknown | null> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
try {
const response = await this.fetchImpl(`${this.apiUrl}/api/v1${path}`, {
method: options.method,
headers: {
authorization: `Bearer ${this.apiKey}`,
accept: "application/json",
...(options.body ? { "content-type": "application/json" } : {}),
},
body: options.body ? JSON.stringify(options.body) : undefined,
signal: controller.signal,
});
if (response.status === 404 && options.allowNotFound) {
return null;
}
if (!response.ok) {
throw new LagoBillingGatewayError(`Lago request failed with status ${response.status}.`, "REQUEST_FAILED", response.status);
}
return await response.json();
} catch (error) {
if (error instanceof LagoBillingGatewayError) throw error;
throw new LagoBillingGatewayError("Lago request failed.", "REQUEST_FAILED");
} finally {
clearTimeout(timeout);
}
}
}
function parseLagoResponse<T>(schema: z.ZodType<T>, response: unknown): T {
const result = schema.safeParse(response);
if (!result.success) {
throw new LagoBillingGatewayError("Lago response shape is invalid.", "RESPONSE_INVALID");
}
return result.data;
}
function toCustomer(response: { customer: LagoCustomer }): BillingGatewayCustomer {
const customer = response.customer;
return {
provider: "lago",
externalId: customer.external_id,
providerCustomerId: customer.lago_id,
name: customer.name ?? null,
email: customer.email ?? null,
currency: customer.currency ?? null,
createdAt: customer.created_at ?? null,
};
}
function toSubscription(response: { subscription: LagoSubscription }): BillingGatewaySubscription {
const subscription = response.subscription;
return {
provider: "lago",
externalId: subscription.external_id,
providerSubscriptionId: subscription.lago_id,
externalCustomerId: subscription.external_customer_id,
planCode: subscription.plan_code,
status: normalizeSubscriptionStatus(subscription.status),
name: subscription.name ?? null,
currentBillingPeriodStartedAt: subscription.current_billing_period_started_at ?? null,
currentBillingPeriodEndingAt: subscription.current_billing_period_ending_at ?? null,
createdAt: subscription.created_at ?? null,
};
}
function toInvoice(invoice: LagoInvoice): BillingGatewayInvoice {
return {
provider: "lago",
providerInvoiceId: invoice.lago_id,
number: invoice.number ?? null,
externalCustomerId: invoice.external_customer_id ?? invoice.customer?.external_id ?? null,
status: normalizeInvoiceStatus(invoice.status),
paymentStatus: normalizePaymentStatus(invoice.payment_status),
invoiceType: invoice.invoice_type ?? null,
currency: invoice.currency ?? null,
totalAmountCents: invoice.total_amount_cents ?? null,
issuingDate: invoice.issuing_date ?? null,
fileUrl: invoice.file_url ?? null,
};
}
function normalizeTimeout(timeoutMs: number | undefined): number {
return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? Math.trunc(timeoutMs) : DEFAULT_LAGO_TIMEOUT_MS;
}
function assertPositiveSeatQuantity(seatQuantity: number): void {
if (!Number.isInteger(seatQuantity) || seatQuantity < 1) {
throw new LagoBillingGatewayError("Seat quantity must be a positive integer.", "CONFIG_INVALID");
}
}
function toIsoString(value: Date | string): string {
return value instanceof Date ? value.toISOString() : value;
}
function normalizeSubscriptionStatus(value: string | null | undefined): BillingGatewaySubscription["status"] {
if (value === "pending" || value === "active" || value === "terminated" || value === "canceled" || value === "cancelled") return value;
return "unknown";
}
function normalizeInvoiceStatus(value: string | null | undefined): BillingGatewayInvoice["status"] {
if (value === "draft" || value === "finalized" || value === "voided" || value === "failed" || value === "pending") return value;
return "unknown";
}
function normalizePaymentStatus(value: string | null | undefined): BillingGatewayInvoice["paymentStatus"] {
if (value === "pending" || value === "succeeded" || value === "failed") return value;
return "unknown";
}