Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
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";
|
||||
}
|
||||
Reference in new issue
Block a user