qarpeo 0.0.0-alpha.10

package/dist/runtime/server/utils/organization.mjs

@@ -0,0 +1,354 @@
+import { useNitroApp } from "nitro/app";
+import { createError, getRequestURL } from "nuxt/server";
+import { getD1Binding } from "../../db.mjs";
+import { sendEmail } from "../../email.mjs";
+import { ensureAuthTables } from "./auth.mjs";
+import { getQarpeoConfig } from "./config.mjs";
+import { escapeHtml, sanitizeUrl } from "./email-templates.mjs";
+import { hashSessionToken, getAuthSession, setAuthSession } from "./session.mjs";
+export function slugify(text) {
+  return text.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function getD1(event) {
+  const bindingName = globalThis.process?.env?.QARPEO_DEFAULT_DB_BINDING || "DB";
+  return getD1Binding(bindingName, event);
+}
+export async function createOrganization(event, input) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user || !user.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const name = input.name?.trim();
+  if (!name) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Bad Request",
+      message: "Organization name is required"
+    });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const orgId = crypto.randomUUID();
+  const baseSlug = slugify(input.slug || name) || `org-${orgId.slice(0, 6)}`;
+  let finalSlug = baseSlug;
+  const existing = await d1.prepare("SELECT id FROM _qarpeo_organizations WHERE slug = ? LIMIT 1").bind(finalSlug).first();
+  if (existing) {
+    finalSlug = `${baseSlug}-${crypto.randomUUID().slice(0, 6)}`;
+  }
+  const now = Date.now();
+  const organization = {
+    id: orgId,
+    name,
+    slug: finalSlug,
+    logoUrl: input.logoUrl || null,
+    createdAt: now
+  };
+  const memberId = crypto.randomUUID();
+  const member = {
+    id: memberId,
+    organizationId: orgId,
+    userId: user.id,
+    role: "owner",
+    createdAt: now
+  };
+  await d1.batch([
+    d1.prepare(
+      "INSERT INTO _qarpeo_organizations (id, name, slug, logo_url, created_at) VALUES (?, ?, ?, ?, ?)"
+    ).bind(
+      organization.id,
+      organization.name,
+      organization.slug,
+      organization.logoUrl,
+      organization.createdAt
+    ),
+    d1.prepare(
+      "INSERT INTO _qarpeo_members (id, organization_id, user_id, role, created_at) VALUES (?, ?, ?, ?, ?)"
+    ).bind(member.id, member.organizationId, member.userId, member.role, member.createdAt)
+  ]);
+  try {
+    const nitroApp = useNitroApp();
+    await nitroApp.hooks?.callHook("qarpeo:auth:organization:create", {
+      organization,
+      owner: user
+    });
+  } catch {
+  }
+  await setAuthSession(event, {
+    ...session,
+    currentOrganizationId: organization.id,
+    currentOrganization: organization,
+    currentRole: "owner"
+  });
+  return { organization, member };
+}
+export async function listUserOrganizations(event, userId) {
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const results = await d1.prepare(`
+      SELECT o.id, o.name, o.slug, o.logo_url as logoUrl, o.created_at as createdAt,
+             m.id as memberId, m.role
+      FROM _qarpeo_members m
+      JOIN _qarpeo_organizations o ON m.organization_id = o.id
+      WHERE m.user_id = ?
+      ORDER BY o.name ASC
+    `).bind(userId).all();
+  return results.results || [];
+}
+export async function switchActiveOrganization(event, organizationId) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user || !user.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const member = await d1.prepare(
+    "SELECT id, role FROM _qarpeo_members WHERE organization_id = ? AND user_id = ? LIMIT 1"
+  ).bind(organizationId, user.id).first();
+  if (!member) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden",
+      message: "You are not a member of this organization"
+    });
+  }
+  const orgRecord = await d1.prepare(
+    "SELECT id, name, slug, logo_url as logoUrl, created_at as createdAt FROM _qarpeo_organizations WHERE id = ? LIMIT 1"
+  ).bind(organizationId).first();
+  if (!orgRecord) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Not Found",
+      message: "Organization not found"
+    });
+  }
+  const organization = {
+    id: orgRecord.id,
+    name: orgRecord.name,
+    slug: orgRecord.slug,
+    logoUrl: orgRecord.logoUrl,
+    createdAt: orgRecord.createdAt
+  };
+  await setAuthSession(event, {
+    ...session,
+    currentOrganizationId: organization.id,
+    currentOrganization: organization,
+    currentRole: member.role
+  });
+  return { success: true, organization, role: member.role };
+}
+export async function inviteOrganizationMember(event, input) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user || !user.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const email = input.email?.trim().toLowerCase();
+  if (!email || !email.includes("@")) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Bad Request",
+      message: "Valid email address is required"
+    });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const callerMember = await d1.prepare("SELECT role FROM _qarpeo_members WHERE organization_id = ? AND user_id = ? LIMIT 1").bind(input.organizationId, user.id).first();
+  if (!callerMember || !["owner", "admin"].includes(callerMember.role)) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden",
+      message: "Only organization owners and admins can invite members"
+    });
+  }
+  const org = await d1.prepare(
+    "SELECT id, name, slug, logo_url as logoUrl, created_at as createdAt FROM _qarpeo_organizations WHERE id = ? LIMIT 1"
+  ).bind(input.organizationId).first();
+  if (!org) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Not Found",
+      message: "Organization not found"
+    });
+  }
+  const role = input.role && ["owner", "admin", "member"].includes(input.role) ? input.role : "member";
+  const rawToken = crypto.randomUUID().replace(/-/g, "") + crypto.randomUUID().replace(/-/g, "");
+  const tokenHash = await hashSessionToken(rawToken);
+  const invitationId = crypto.randomUUID();
+  const now = Date.now();
+  const expiresAt = now + 7 * 24 * 60 * 60 * 1e3;
+  await d1.prepare(`
+      INSERT INTO _qarpeo_invitations (id, organization_id, email, role, token_hash, expires_at, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).bind(invitationId, org.id, email, role, tokenHash, expiresAt, now).run();
+  const reqUrl = getRequestURL(event);
+  const origin = `${reqUrl.protocol}//${reqUrl.host}`;
+  const authPrefix = getQarpeoConfig(event).auth?.prefix || "/api/auth";
+  const inviteUrl = `${origin}${authPrefix}/organization/join?token=${rawToken}`;
+  const invitation = {
+    id: invitationId,
+    organizationId: org.id,
+    email,
+    role,
+    tokenHash,
+    expiresAt,
+    createdAt: now
+  };
+  let hookHandled = false;
+  try {
+    const nitroApp = useNitroApp();
+    await nitroApp.hooks?.callHook("qarpeo:auth:organization:invite", {
+      organization: org,
+      invitation,
+      inviteUrl
+    });
+    hookHandled = true;
+  } catch {
+  }
+  if (!hookHandled || globalThis.process?.env?.NODE_ENV === "development") {
+    try {
+      await sendEmail(
+        {
+          to: email,
+          subject: `You've been invited to join ${org.name}`,
+          text: `You have been invited to join ${org.name} on Qarpeo as a ${role}.
+Accept invitation: ${inviteUrl}`,
+          html: `<p>You have been invited to join <strong>${escapeHtml(org.name)}</strong> as a <strong>${escapeHtml(role)}</strong>.</p><p><a href="${sanitizeUrl(inviteUrl)}">Accept Invitation</a></p>`
+        },
+        event
+      );
+    } catch (err) {
+      console.error("[qarpeo:auth] Failed to send organization invite email:", err?.message || err);
+      return {
+        invitationId,
+        token: rawToken,
+        expiresAt,
+        inviteUrl,
+        sent: false,
+        error: err?.message || "Failed to send invitation email"
+      };
+    }
+  }
+  return { invitationId, token: rawToken, expiresAt, inviteUrl, sent: true };
+}
+export async function removeOrganizationMember(event, input) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user || !user.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const callerMember = await d1.prepare(
+    "SELECT id, role FROM _qarpeo_members WHERE organization_id = ? AND user_id = ? LIMIT 1"
+  ).bind(input.organizationId, user.id).first();
+  if (!callerMember) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden",
+      message: "Not a member of this organization"
+    });
+  }
+  const targetMember = await d1.prepare(
+    "SELECT id, user_id as userId, role FROM _qarpeo_members WHERE id = ? AND organization_id = ? LIMIT 1"
+  ).bind(input.memberId, input.organizationId).first();
+  if (!targetMember) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Not Found",
+      message: "Member record not found"
+    });
+  }
+  const isSelf = targetMember.userId === user.id;
+  const isOwnerOrAdmin = ["owner", "admin"].includes(callerMember.role);
+  if (!isSelf && !isOwnerOrAdmin) {
+    throw createError({ statusCode: 403, statusMessage: "Forbidden", message: "Permission denied" });
+  }
+  if (targetMember.role === "owner") {
+    const ownerCount = await d1.prepare(
+      "SELECT count(*) as count FROM _qarpeo_members WHERE organization_id = ? AND role = 'owner'"
+    ).bind(input.organizationId).first();
+    if ((ownerCount?.count || 0) <= 1) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Bad Request",
+        message: "Cannot remove the only owner of an organization. Transfer ownership first."
+      });
+    }
+  }
+  await d1.prepare("DELETE FROM _qarpeo_members WHERE id = ?").bind(input.memberId).run();
+  if (isSelf && session.currentOrganizationId === input.organizationId) {
+    await setAuthSession(event, {
+      ...session,
+      currentOrganizationId: null,
+      currentOrganization: null,
+      currentRole: null
+    });
+  }
+  return { success: true };
+}
+export async function acceptOrganizationInvitation(event, token) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user || !user.id) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Must be logged in to accept an invitation"
+    });
+  }
+  const tokenHash = await hashSessionToken(token);
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const invitation = await d1.prepare("SELECT * FROM _qarpeo_invitations WHERE token_hash = ? LIMIT 1").bind(tokenHash).first();
+  if (!invitation) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Not Found",
+      message: "Invalid or expired invitation"
+    });
+  }
+  if (Date.now() > invitation.expires_at) {
+    await d1.prepare("DELETE FROM _qarpeo_invitations WHERE id = ?").bind(invitation.id).run();
+    throw createError({ statusCode: 410, statusMessage: "Gone", message: "Invitation has expired" });
+  }
+  const memberId = crypto.randomUUID();
+  const now = Date.now();
+  await d1.batch([
+    d1.prepare(`
+        INSERT INTO _qarpeo_members (id, organization_id, user_id, role, created_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(organization_id, user_id) DO UPDATE SET role = excluded.role
+      `).bind(memberId, invitation.organization_id, user.id, invitation.role, now),
+    d1.prepare("DELETE FROM _qarpeo_invitations WHERE id = ?").bind(invitation.id)
+  ]);
+  await switchActiveOrganization(event, invitation.organization_id);
+  return { success: true, organizationId: invitation.organization_id, role: invitation.role };
+}
+export async function listOrganizationMembers(event, organizationId) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user || !user.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const caller = await d1.prepare("SELECT id FROM _qarpeo_members WHERE organization_id = ? AND user_id = ? LIMIT 1").bind(organizationId, user.id).first();
+  if (!caller) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden",
+      message: "Not a member of this organization"
+    });
+  }
+  const results = await d1.prepare(`
+      SELECT m.id, m.organization_id as organizationId, m.user_id as userId, m.role, m.created_at as createdAt,
+             u.email, u.name, u.avatar_url as avatarUrl
+      FROM _qarpeo_members m
+      LEFT JOIN _qarpeo_users u ON m.user_id = u.id
+      WHERE m.organization_id = ?
+      ORDER BY m.created_at ASC
+    `).bind(organizationId).all();
+  return results.results || [];
+}

package/dist/runtime/server/utils/passwordless.d.ts

@@ -0,0 +1,48 @@
+export interface SendOTPOptions {
+    ttl?: number;
+}
+export interface OTPRecord {
+    codeHash: string;
+    attempts: number;
+    expiresAt: number;
+}
+export declare function sendOTPCode(event: any, email: string, options?: SendOTPOptions): Promise<{
+    sent: boolean;
+    expiresAt: number;
+    error: string;
+} | {
+    sent: boolean;
+    expiresAt: number;
+    error?: undefined;
+}>;
+export declare function verifyOTPCode(event: any, email: string, code: string): Promise<{
+    valid: boolean;
+    reason: string;
+    attemptsRemaining?: undefined;
+} | {
+    valid: boolean;
+    reason: string;
+    attemptsRemaining: number;
+} | {
+    valid: boolean;
+    reason?: undefined;
+    attemptsRemaining?: undefined;
+}>;
+export declare function sendMagicLink(event: any, email: string, options?: {
+    ttl?: number;
+}): Promise<{
+    sent: boolean;
+    expiresAt: number;
+    error: string;
+} | {
+    sent: boolean;
+    expiresAt: number;
+    error?: undefined;
+}>;
+export declare function verifyMagicLinkToken(event: any, token: string): Promise<{
+    valid: boolean;
+    email?: undefined;
+} | {
+    valid: boolean;
+    email: string;
+}>;

package/dist/runtime/server/utils/passwordless.mjs

@@ -0,0 +1,179 @@
+import { useNitroApp } from "nitro/app";
+import { getRequestURL, createError } from "nuxt/server";
+import { getQarpeoConfig } from "./config.mjs";
+import { sendEmail } from "../../email.mjs";
+import { getKVBinding } from "../../kv.mjs";
+import { escapeHtml, sanitizeUrl } from "./email-templates.mjs";
+import { assertRateLimit } from "./ratelimit.mjs";
+import { hashSessionToken } from "./session.mjs";
+import { timingSafeEqualString } from "./totp.mjs";
+export async function sendOTPCode(event, email, options = {}) {
+  const cleanEmail = email.trim().toLowerCase();
+  await assertRateLimit(event, {
+    key: `auth:otp:send:${cleanEmail}`,
+    max: 5,
+    window: "10m",
+    message: "Too many verification code requests. Please wait before requesting another."
+  }).catch((err) => {
+    if (err?.statusCode === 429) throw err;
+  });
+  const code = Math.floor(1e5 + Math.random() * 9e5).toString();
+  const codeHash = await hashSessionToken(code);
+  const authConfig = getQarpeoConfig(event).auth;
+  const otpCfg = typeof authConfig.passwordless?.otp === "object" ? authConfig.passwordless.otp : void 0;
+  const ttl = options.ttl || otpCfg?.ttl || 300;
+  const expiresAt = Date.now() + ttl * 1e3;
+  try {
+    const kv = getKVBinding("KV", event);
+    const record = {
+      codeHash,
+      attempts: 0,
+      expiresAt
+    };
+    await kv.put(`otp:${cleanEmail}`, JSON.stringify(record), {
+      expirationTtl: ttl
+    });
+  } catch (err) {
+    console.warn("[qarpeo] Failed to store OTP in KV:", err.message);
+  }
+  const nitroApp = useNitroApp();
+  let hookHandled = false;
+  try {
+    await nitroApp.hooks?.callHook("qarpeo:auth:otp:send", {
+      email: cleanEmail,
+      code,
+      type: "otp"
+    });
+    hookHandled = true;
+  } catch {
+  }
+  if (!hookHandled || globalThis.process?.env?.NODE_ENV === "development") {
+    try {
+      await sendEmail(
+        {
+          to: cleanEmail,
+          subject: `Your Login Code: ${code}`,
+          text: `Your verification code is: ${code}
+This code will expire in ${Math.round(ttl / 60)} minutes.`,
+          html: `<p>Your verification code is: <strong>${escapeHtml(code)}</strong></p><p>This code will expire in ${escapeHtml(String(Math.round(ttl / 60)))} minutes.</p>`
+        },
+        event
+      );
+    } catch (err) {
+      console.error("[qarpeo] Failed to send OTP email:", err?.message || err);
+      return { sent: false, expiresAt, error: "Failed to send verification code" };
+    }
+  }
+  return { sent: true, expiresAt };
+}
+export async function verifyOTPCode(event, email, code) {
+  const cleanEmail = email.trim().toLowerCase();
+  const cleanCode = code.trim();
+  await assertRateLimit(event, {
+    key: `auth:otp:verify:${cleanEmail}`,
+    max: 10,
+    window: "10m",
+    message: "Too many verification attempts. Please request a new code."
+  }).catch((err) => {
+    if (err?.statusCode === 429) throw err;
+  });
+  let kv;
+  try {
+    kv = getKVBinding("KV", event);
+  } catch {
+    throw createError({
+      statusCode: 500,
+      statusMessage: "Internal Server Error",
+      message: "KV database binding not available"
+    });
+  }
+  const raw = await kv.get(`otp:${cleanEmail}`, { type: "json" });
+  if (!raw) {
+    return { valid: false, reason: "expired" };
+  }
+  const record = raw;
+  if (record.attempts >= 5) {
+    await kv.delete(`otp:${cleanEmail}`);
+    return { valid: false, reason: "too_many_attempts" };
+  }
+  const inputHash = await hashSessionToken(cleanCode);
+  if (!timingSafeEqualString(inputHash, record.codeHash)) {
+    record.attempts += 1;
+    await kv.put(`otp:${cleanEmail}`, JSON.stringify(record), {
+      expirationTtl: 300
+    });
+    return { valid: false, reason: "invalid_code", attemptsRemaining: 5 - record.attempts };
+  }
+  await kv.delete(`otp:${cleanEmail}`);
+  return { valid: true };
+}
+export async function sendMagicLink(event, email, options = {}) {
+  const cleanEmail = email.trim().toLowerCase();
+  await assertRateLimit(event, {
+    key: `auth:magic:send:${cleanEmail}`,
+    max: 5,
+    window: "10m",
+    message: "Too many magic link requests. Please wait before requesting another."
+  }).catch((err) => {
+    if (err?.statusCode === 429) throw err;
+  });
+  const token = crypto.randomUUID().replace(/-/g, "") + crypto.randomUUID().replace(/-/g, "");
+  const authConfig = getQarpeoConfig(event).auth;
+  const magicCfg = typeof authConfig.passwordless?.magicLink === "object" ? authConfig.passwordless.magicLink : void 0;
+  const ttl = options.ttl || magicCfg?.ttl || 900;
+  const expiresAt = Date.now() + ttl * 1e3;
+  try {
+    const kv = getKVBinding("KV", event);
+    await kv.put(`magic:${token}`, JSON.stringify({ email: cleanEmail, expiresAt }), {
+      expirationTtl: ttl
+    });
+  } catch (err) {
+    console.warn("[qarpeo] Failed to store magic link in KV:", err.message);
+  }
+  const requestUrl = getRequestURL(event);
+  const origin = `${requestUrl.protocol}//${requestUrl.host}`;
+  const authPrefix = authConfig.prefix || "/api/auth";
+  const url = `${origin}${authPrefix}/magic-link/verify?token=${token}`;
+  const nitroApp = useNitroApp();
+  let hookHandled = false;
+  try {
+    await nitroApp.hooks?.callHook("qarpeo:auth:magic-link:send", {
+      email: cleanEmail,
+      url
+    });
+    hookHandled = true;
+  } catch {
+  }
+  if (!hookHandled || globalThis.process?.env?.NODE_ENV === "development") {
+    try {
+      await sendEmail(
+        {
+          to: cleanEmail,
+          subject: "Your Magic Sign-In Link",
+          text: `Click here to sign in: ${url}
+This link expires in ${Math.round(ttl / 60)} minutes.`,
+          html: `<p>Click the link below to sign in:</p><p><a href="${sanitizeUrl(url)}">Sign In to Your Account</a></p><p>This link expires in ${escapeHtml(String(Math.round(ttl / 60)))} minutes.</p>`
+        },
+        event
+      );
+    } catch (err) {
+      console.error("[qarpeo] Failed to send magic link email:", err?.message || err);
+      return { sent: false, expiresAt, error: "Failed to send magic link" };
+    }
+  }
+  return { sent: true, expiresAt };
+}
+export async function verifyMagicLinkToken(event, token) {
+  let kv;
+  try {
+    kv = getKVBinding("KV", event);
+  } catch {
+    return { valid: false };
+  }
+  const data = await kv.get(`magic:${token}`, { type: "json" });
+  if (!data || !data.email) {
+    return { valid: false };
+  }
+  await kv.delete(`magic:${token}`);
+  return { valid: true, email: data.email };
+}

package/dist/runtime/server/utils/payments.d.ts

@@ -0,0 +1,121 @@
+import type { PaymentsOptions, PaymentProvider, QarpeoSubscription, SubscriptionStatus, CreateCheckoutOptions, MeterRecordOptions, MeterUsageResult, UsageSummary } from "../../../types";
+export declare function getPaymentsConfig(event?: any): PaymentsOptions & {
+    provider: PaymentProvider;
+    secretKey: string;
+    webhookSecret: string;
+};
+export declare function ensurePaymentsTables(event?: any): Promise<void>;
+/** Verifies Stripe webhook signature: Stripe-Signature header contains: `t=timestamp,v1=signature` */
+export declare function verifyStripeSignature(rawBody: string, signatureHeader: string | null | undefined, secret: string, toleranceSec?: number): Promise<boolean>;
+/** Verifies Lemon Squeezy webhook signature (X-Signature header) */
+export declare function verifyLemonSqueezySignature(rawBody: string, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/** Verifies Polar webhook signature (webhook-signature header) */
+export declare function verifyPolarSignature(rawBody: string, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+/** Verifies Paddle Billing webhook signature (Paddle-Signature header: `ts=TIMESTAMP;h1=HMAC_HEX`) */
+export declare function verifyPaddleSignature(rawBody: string, signatureHeader: string | null | undefined, secret: string): Promise<boolean>;
+export declare function processPaymentWebhook(event: any, rawBody: string): Promise<{
+    success: boolean;
+    eventType?: string;
+} | {
+    received: true;
+    skipped: true;
+    reason: "duplicate";
+}>;
+/**
+ * Creates a Stripe checkout session via Stripe REST API. Runs 100% edge-native on Cloudflare
+ * Workers using standard `fetch`.
+ */
+export declare function createCheckoutSession(event: any, options: CreateCheckoutOptions): Promise<{
+    id: string;
+    url: string;
+}>;
+/** Creates a Customer Billing Portal session for the current user. */
+export declare function createCustomerPortalSession(event: any, options?: {
+    returnUrl?: string;
+}): Promise<{
+    url: string;
+}>;
+/**
+ * Cancels a Stripe subscription at the end of the current billing period. Calls Stripe POST
+ * /v1/subscriptions/{id} with `cancel_at_period_end: true` and marks the D1 row as canceled.
+ */
+export declare function cancelSubscription(event: any, subscriptionId: string): Promise<{
+    success: boolean;
+    subscriptionId: string;
+    status: string;
+}>;
+/**
+ * Pauses collection on a Stripe subscription. Calls Stripe POST /v1/subscriptions/{id} with
+ * `pause_collection: { behavior: 'void', resumes_at: null }` and marks the D1 row as paused.
+ */
+export declare function pauseSubscription(event: any, subscriptionId: string): Promise<{
+    success: boolean;
+    subscriptionId: string;
+    status: string;
+}>;
+/**
+ * Changes a Stripe subscription to a new price/plan with proration. Fetches the current
+ * subscription item id, calls Stripe POST /v1/subscriptions/{id} to swap the item price, and
+ * updates the D1 plan_id/price_id.
+ */
+export declare function changePlan(event: any, subscriptionId: string, newPriceId: string): Promise<{
+    success: boolean;
+    subscriptionId: string;
+    planId: string;
+}>;
+/** Gets the current active subscription for a user or organization from D1. */
+export declare function getSubscription(event: any, options?: {
+    userId?: string;
+    orgId?: string;
+}): Promise<QarpeoSubscription | null>;
+export interface RequireSubscriptionOptions {
+    tier?: string | string[];
+    plan?: string | string[];
+    status?: SubscriptionStatus[];
+    message?: string;
+}
+/** Server guard: throws 402 Payment Required if caller has no active subscription. */
+export declare function requireSubscription(event: any, options?: RequireSubscriptionOptions): Promise<QarpeoSubscription>;
+/**
+ * Checks whether the current user or organization's active subscription plan includes a specific
+ * feature flag.
+ *
+ * @example
+ *   ;```ts
+ *   if (!(await hasFeature(event, "custom_domain"))) {
+ *     throw createError({ statusCode: 403, message: "Custom domains require Pro plan" })
+ *   }
+ *   ```
+ */
+export declare function hasFeature(event: any, feature: string): Promise<boolean>;
+/**
+ * Checks whether a numerical usage limit defined on the active plan configuration has been
+ * exceeded.
+ *
+ * @example
+ *   ```ts
+ *   const { allowed, limit, current } = await checkLimit(event, "max_projects", projectCount)
+ *   if (!allowed) {
+ *   throw createError({ statusCode: 403, message: `Project limit (${limit}) reached` })
+ *   }
+ *   ```
+ */
+export declare function checkLimit(event: any, limitKey: string, currentUsage: number): Promise<{
+    allowed: boolean;
+    limit: number;
+    current: number;
+}>;
+/**
+ * Records a metered usage event in D1 and reports to upstream provider (e.g. Stripe Meters API).
+ */
+export declare function reportUsage(event: any, options: MeterRecordOptions): Promise<MeterUsageResult>;
+/**
+ * Queries metered usage summary and records from D1 for a user or organization.
+ */
+export declare function getUsageSummary(event: any, options: {
+    eventName?: string;
+    userId?: string;
+    orgId?: string;
+    since?: number;
+    until?: number;
+}): Promise<UsageSummary>;