@vibecodiq/cli 0.5.0 → 0.6.0

package/dist/foundation/db_basic/shared/utils.ts

@@ -0,0 +1,43 @@
+// --- ASA GENERATED START ---
+// Database utilities — pagination, filtering, error handling.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+export interface PaginationParams {
+  page?: number;
+  pageSize?: number;
+}
+
+export interface PaginatedResult<T> {
+  data: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  totalPages: number;
+}
+
+export function paginate<T>(
+  data: T[],
+  total: number,
+  params: PaginationParams = {},
+): PaginatedResult<T> {
+  const page = params.page ?? 1;
+  const pageSize = params.pageSize ?? 20;
+  return {
+    data,
+    total,
+    page,
+    pageSize,
+    totalPages: Math.ceil(total / pageSize),
+  };
+}
+
+export function handleDbError(error: unknown): never {
+  if (error instanceof Error) {
+    throw new Error(`Database error: ${error.message}`);
+  }
+  throw new Error('Unknown database error');
+}
+
+// --- USER CODE END ---

package/dist/foundation/payments_basic/manifest.json

@@ -0,0 +1,54 @@
+{
+  "name": "payments-basic",
+  "version": "1.0.0",
+  "description": "Basic Stripe billing for SaaS apps — subscriptions, webhooks, plan limits",
+  "min_cli_version": "2.0.0",
+  "stack": "asa-native-v1",
+  "dependencies": ["db-basic", "auth-basic"],
+  "package_dependencies": {
+    "stripe": "^17.0.0"
+  },
+  "package_dev_dependencies": {},
+  "slices": [
+    { "domain": "billing", "name": "subscribe", "type": "route", "has_ui": true, "has_repository": true },
+    { "domain": "billing", "name": "cancel", "type": "route", "has_ui": true, "has_repository": true },
+    { "domain": "billing", "name": "webhook", "type": "webhook", "has_ui": false, "has_repository": true },
+    { "domain": "billing", "name": "check-limits", "type": "route", "has_ui": true, "has_repository": true }
+  ],
+  "shared": [
+    { "src": "shared/stripe-client.ts", "dest": "shared/billing/stripe-client.ts", "overwrite": false },
+    { "src": "shared/plans.ts", "dest": "shared/billing/plans.ts", "overwrite": false },
+    { "src": "shared/hooks.ts", "dest": "shared/billing/hooks.ts", "overwrite": false },
+    { "src": "shared/types.ts", "dest": "shared/billing/types.ts", "overwrite": false },
+    { "src": "shared/webhook-handler.ts", "dest": "shared/billing/webhook-handler.ts", "overwrite": false },
+    { "src": "shared/entitlements.ts", "dest": "shared/billing/entitlements.ts", "overwrite": false },
+    { "src": "shared/webhook-processor.ts", "dest": "shared/billing/webhook-processor.ts", "overwrite": false },
+    { "src": "shared/reconciliation.ts", "dest": "shared/billing/reconciliation.ts", "overwrite": false },
+    { "src": "shared/guards.ts", "dest": "shared/entitlements/guards.ts", "overwrite": false },
+    { "src": "shared/resolver.ts", "dest": "shared/entitlements/resolver.ts", "overwrite": false },
+    { "src": "shared/entitlement-types.ts", "dest": "shared/entitlements/types.ts", "overwrite": false },
+    { "src": "shared/entitlement-hooks.ts", "dest": "shared/entitlements/hooks.ts", "overwrite": false }
+  ],
+  "migrations": [
+    { "src": "migrations/002_create_subscriptions.sql", "dest": "shared/db/migrations/002_create_subscriptions.sql" },
+    { "src": "migrations/003_create_entitlements.sql", "dest": "shared/db/migrations/003_create_entitlements.sql" },
+    { "src": "migrations/003b_create_webhook_events.sql", "dest": "shared/db/migrations/003b_create_webhook_events.sql" }
+  ],
+  "env_vars": [
+    "STRIPE_SECRET_KEY",
+    "STRIPE_WEBHOOK_SECRET",
+    "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY",
+    "STRIPE_PRO_PRICE_ID"
+  ],
+  "post_install_notes": [
+    "Create a Stripe account (test mode) at https://stripe.com",
+    "Create Products + Prices in Stripe Dashboard",
+    "Set up webhook endpoint in Stripe Dashboard → Developers → Webhooks",
+    "Copy keys to .env.local",
+    "Run migration: Apply shared/db/migrations/002_create_subscriptions.sql in Supabase SQL Editor",
+    "Run migration: Apply shared/db/migrations/003_create_entitlements.sql in Supabase SQL Editor",
+    "Seed plan_features table with your plan configuration",
+    "Use requireEntitlement() and requireLimit() guards in your route handlers",
+    "Run: npm install"
+  ]
+}

package/dist/foundation/payments_basic/migrations/002_create_subscriptions.sql

@@ -0,0 +1,44 @@
+-- ASA Module: payments-basic
+-- Migration: 002_create_subscriptions
+-- Creates subscriptions table for Stripe billing
+
+-- Subscription state machine: active, past_due, trialing, incomplete, canceled, unpaid
+-- IMPORTANT: past_due = "still has access" (Stripe retrying payment)
+create table if not exists subscriptions (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid references profiles(id) on delete cascade not null,
+  stripe_customer_id text,
+  stripe_subscription_id text,
+  plan text not null default 'free',
+  status text not null default 'active'
+    check (status in ('active', 'past_due', 'trialing', 'incomplete', 'canceled', 'unpaid')),
+  current_period_end timestamptz,
+  cancel_at_period_end boolean not null default false,
+  created_at timestamptz default now(),
+  updated_at timestamptz default now()
+);
+
+-- RLS policies (correct WITH CHECK for all operations)
+alter table subscriptions enable row level security;
+
+create policy "Users can view own subscription"
+  on subscriptions for select
+  using (auth.uid() = user_id);
+
+-- No direct insert/update from client — managed by webhook handler via admin client
+
+-- Webhook event idempotency table
+create table if not exists webhook_events (
+  event_id text primary key,
+  event_type text not null,
+  processed_at timestamptz default now()
+);
+
+-- No RLS on webhook_events — accessed only via admin client (server-side)
+alter table webhook_events enable row level security;
+-- No policies = deny all client access (correct — admin client bypasses RLS)
+
+-- Indexes
+create index if not exists idx_subscriptions_user_id on subscriptions(user_id);
+create index if not exists idx_subscriptions_stripe_customer on subscriptions(stripe_customer_id);
+create index if not exists idx_webhook_events_type on webhook_events(event_type);

package/dist/foundation/payments_basic/migrations/003_create_entitlements.sql

@@ -0,0 +1,54 @@
+-- ASA Module: payments-basic (entitlement architecture)
+-- Migration: 003_create_entitlements
+-- Creates deterministic entitlement tables for feature/limit checks.
+--
+-- Usage:
+-- 1. Apply this migration in Supabase SQL Editor
+-- 2. Seed plan_features with your plan configuration
+-- 3. Use requireEntitlement() and requireLimit() guards in route handlers
+
+-- Plan → feature/limit mapping (seed data, admin-editable)
+create table if not exists plan_features (
+  id uuid primary key default gen_random_uuid(),
+  plan_key text not null,
+  feature_key text not null,
+  feature_type text not null check (feature_type in ('boolean', 'number')),
+  value text not null,
+  unique(plan_key, feature_key)
+);
+
+-- Materialized entitlements per user (source of truth for app)
+create table if not exists entitlements (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  feature_key text not null,
+  feature_type text not null check (feature_type in ('boolean', 'number')),
+  value text not null,
+  source text not null default 'plan' check (source in ('plan', 'override')),
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now(),
+  unique(user_id, feature_key)
+);
+
+-- RLS: users can only read their own entitlements
+alter table entitlements enable row level security;
+
+create policy "Users can read own entitlements"
+  on entitlements for select
+  using (auth.uid() = user_id);
+
+-- No direct insert/update from client — managed by resolver via admin client
+
+-- RLS: plan_features readable by all authenticated users (public pricing info)
+alter table plan_features enable row level security;
+
+create policy "Anyone can read plan features"
+  on plan_features for select
+  using (true);
+
+-- No direct insert/update from client — managed by admin
+
+-- Indexes
+create index if not exists idx_entitlements_user_id on entitlements(user_id);
+create index if not exists idx_entitlements_feature on entitlements(user_id, feature_key);
+create index if not exists idx_plan_features_plan on plan_features(plan_key);

package/dist/foundation/payments_basic/migrations/003b_create_webhook_events.sql

@@ -0,0 +1,28 @@
+-- ASA Foundation: webhook_events table for Postgres inbox pattern
+-- Stripe webhook events are stored here with status tracking.
+-- A scheduled processor picks 'pending' events and processes them asynchronously.
+
+CREATE TABLE IF NOT EXISTS public.webhook_events (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  stripe_event_id TEXT NOT NULL UNIQUE,
+  type TEXT NOT NULL,
+  payload JSONB NOT NULL DEFAULT '{}',
+  status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'processing', 'processed', 'failed')),
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  locked_at TIMESTAMPTZ,
+  last_error TEXT,
+  received_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  processed_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Index for processor: find pending events efficiently
+CREATE INDEX IF NOT EXISTS idx_webhook_events_status ON public.webhook_events (status) WHERE status = 'pending';
+
+-- Index for deduplication lookup
+CREATE INDEX IF NOT EXISTS idx_webhook_events_stripe_id ON public.webhook_events (stripe_event_id);
+
+-- RLS: webhook_events should only be accessible by service_role (backend)
+ALTER TABLE public.webhook_events ENABLE ROW LEVEL SECURITY;
+
+-- No RLS policies = only service_role/admin can access (which is correct for webhooks)

package/dist/foundation/payments_basic/shared/entitlement-hooks.ts

@@ -0,0 +1,50 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { createBrowserClient } from '@/shared/db/supabase-client';
+
+// --- ASA GENERATED START ---
+// Entitlement hooks for client components.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+/**
+ * Get all entitlements for current user.
+ */
+export function useEntitlements(): Map<string, string> {
+  const [entitlements, setEntitlements] = useState<Map<string, string>>(
+    new Map(),
+  );
+
+  useEffect(() => {
+    const supabase = createBrowserClient();
+    supabase.auth.getUser().then(({ data: { user } }) => {
+      if (!user) return;
+      supabase
+        .from('entitlements')
+        .select('feature_key, value')
+        .eq('user_id', user.id)
+        .then(({ data }) => {
+          const map = new Map<string, string>();
+          (data ?? []).forEach(
+            (row: { feature_key: string; value: string }) =>
+              map.set(row.feature_key, row.value),
+          );
+          setEntitlements(map);
+        });
+    });
+  }, []);
+
+  return entitlements;
+}
+
+/**
+ * Check if current user has a boolean feature.
+ */
+export function useHasFeature(featureKey: string): boolean {
+  const entitlements = useEntitlements();
+  return entitlements.get(featureKey) === 'true';
+}
+
+// --- USER CODE END ---

package/dist/foundation/payments_basic/shared/entitlement-types.ts

@@ -0,0 +1,29 @@
+// --- ASA GENERATED START ---
+// Entitlement types for deterministic feature/limit architecture.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+export type EntitlementSource = 'plan' | 'override';
+export type FeatureType = 'boolean' | 'number';
+
+export interface EntitlementRow {
+  id: string;
+  user_id: string;
+  feature_key: string;
+  feature_type: FeatureType;
+  value: string;
+  source: EntitlementSource;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PlanFeatureRow {
+  id: string;
+  plan_key: string;
+  feature_key: string;
+  feature_type: FeatureType;
+  value: string;
+}
+
+// --- USER CODE END ---

package/dist/foundation/payments_basic/shared/entitlements.ts

@@ -0,0 +1,78 @@
+import { createAdminClient } from '@/shared/db/supabase-client';
+import { PLANS } from '@/shared/billing/plans';
+
+// --- ASA GENERATED START ---
+// Entitlement engine — single source of truth for plan-based access control.
+// Entitlements are separated from raw Stripe subscription status.
+// Always fetch current state — never trust cached/stale data for access decisions.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+export interface EntitlementResult {
+  plan: string;
+  status: string;
+  entitlements: Record<string, boolean | number>;
+  can_access: boolean;
+}
+
+/**
+ * Check what the user is entitled to based on their current subscription.
+ * Optionally check a specific feature.
+ *
+ * Dunning-safe: users in 'past_due' status retain read access
+ * but lose write/create capabilities.
+ */
+export async function checkEntitlement(
+  userId: string,
+  feature?: string,
+): Promise<EntitlementResult> {
+  const supabase = createAdminClient();
+
+  // Always fetch current state from DB
+  const { data: subscription } = await supabase
+    .from('subscriptions')
+    .select('plan, status')
+    .eq('user_id', userId)
+    .single();
+
+  const plan = subscription?.plan ?? 'free';
+  const status = subscription?.status ?? 'active';
+
+  // Find plan definition
+  const planDef = PLANS.find((p) => p.id === plan);
+  const entitlements: Record<string, boolean | number> = {};
+
+  if (planDef?.limits) {
+    for (const [key, value] of Object.entries(planDef.limits)) {
+      entitlements[key] = value;
+    }
+  }
+
+  // Dunning-safe access: past_due users keep read access but lose create/write
+  const isDunning = status === 'past_due';
+  let canAccess = status === 'active' || status === 'trialing' || isDunning;
+
+  if (feature && planDef?.limits) {
+    const limit = planDef.limits[feature];
+    if (limit === undefined || limit === false || limit === 0) {
+      canAccess = false;
+    }
+    // During dunning, block write-type features
+    if (isDunning && feature.startsWith('create_') || isDunning && feature.startsWith('write_')) {
+      canAccess = false;
+    }
+  }
+
+  return { plan, status, entitlements, can_access: canAccess };
+}
+
+/**
+ * Quick guard: can user access a specific feature?
+ */
+export async function canAccess(userId: string, feature: string): Promise<boolean> {
+  const result = await checkEntitlement(userId, feature);
+  return result.can_access;
+}
+
+// --- USER CODE END ---

package/dist/foundation/payments_basic/shared/guards.ts

@@ -0,0 +1,110 @@
+import { createServerClient } from '@/shared/db/supabase-client';
+
+// --- ASA GENERATED START ---
+// Entitlement guard API for deterministic feature/limit checks.
+// Use these guards in route handlers instead of inline plan checks.
+//
+// Example:
+//   await requireEntitlement(userId, "csv_export");
+//   await requireLimit(userId, "max_invoices_per_month", currentCount);
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+/**
+ * Check if user has a boolean entitlement.
+ * Throws 403 Response if not entitled.
+ */
+export async function requireEntitlement(
+  userId: string,
+  featureKey: string,
+): Promise<void> {
+  const entitled = await hasEntitlement(userId, featureKey);
+  if (!entitled) {
+    throw new Response(
+      JSON.stringify({
+        error: 'FORBIDDEN',
+        message: `Entitlement required: ${featureKey}`,
+      }),
+      { status: 403, headers: { 'Content-Type': 'application/json' } },
+    );
+  }
+}
+
+/**
+ * Check if user is within a numeric limit.
+ * Throws 403 Response if currentCount >= limit.
+ */
+export async function requireLimit(
+  userId: string,
+  limitKey: string,
+  currentCount: number,
+): Promise<void> {
+  const limit = await getLimit(userId, limitKey);
+  if (currentCount >= limit) {
+    throw new Response(
+      JSON.stringify({
+        error: 'LIMIT_EXCEEDED',
+        message: `Limit exceeded: ${limitKey} (${currentCount}/${limit})`,
+      }),
+      { status: 403, headers: { 'Content-Type': 'application/json' } },
+    );
+  }
+}
+
+/**
+ * Check entitlement without throwing (for conditional UI or soft checks).
+ */
+export async function hasEntitlement(
+  userId: string,
+  featureKey: string,
+): Promise<boolean> {
+  const supabase = createServerClient();
+  const { data } = await supabase
+    .from('entitlements')
+    .select('value')
+    .eq('user_id', userId)
+    .eq('feature_key', featureKey)
+    .single();
+
+  return data?.value === 'true';
+}
+
+/**
+ * Get numeric limit value for a user. Returns 0 if not found.
+ */
+export async function getLimit(
+  userId: string,
+  limitKey: string,
+): Promise<number> {
+  const supabase = createServerClient();
+  const { data } = await supabase
+    .from('entitlements')
+    .select('value')
+    .eq('user_id', userId)
+    .eq('feature_key', limitKey)
+    .single();
+
+  return data ? parseInt(data.value, 10) : 0;
+}
+
+/**
+ * Get all entitlements for a user (for UI display or bulk checks).
+ */
+export async function getEntitlements(
+  userId: string,
+): Promise<Map<string, string>> {
+  const supabase = createServerClient();
+  const { data } = await supabase
+    .from('entitlements')
+    .select('feature_key, value')
+    .eq('user_id', userId);
+
+  const map = new Map<string, string>();
+  (data ?? []).forEach((row: { feature_key: string; value: string }) =>
+    map.set(row.feature_key, row.value),
+  );
+  return map;
+}
+
+// --- USER CODE END ---

package/dist/foundation/payments_basic/shared/hooks.ts

@@ -0,0 +1,45 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { createBrowserClient } from '@/shared/db/supabase-client';
+import type { Subscription, PlanLimitCheck } from './types';
+import { getPlan } from './plans';
+
+// --- ASA GENERATED START ---
+// Billing hooks for client components.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+export function useSubscription() {
+  const [subscription, setSubscription] = useState<Subscription | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const supabase = createBrowserClient();
+    supabase
+      .from('subscriptions')
+      .select('*')
+      .single()
+      .then(({ data }) => {
+        setSubscription(data as Subscription | null);
+        setLoading(false);
+      });
+  }, []);
+
+  const plan = subscription ? getPlan(subscription.plan) : getPlan('free');
+
+  return { subscription, plan, loading };
+}
+
+export function usePlanLimits() {
+  const { plan, loading } = useSubscription();
+
+  return {
+    limits: plan.limits,
+    planName: plan.name,
+    loading,
+  };
+}
+
+// --- USER CODE END ---

package/dist/foundation/payments_basic/shared/plans.ts

@@ -0,0 +1,54 @@
+// --- ASA GENERATED START ---
+// Plan definitions for payments-basic module.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+export type PlanId = 'free' | 'pro';
+
+export interface PlanDefinition {
+  id: PlanId;
+  name: string;
+  price: number;
+  stripePriceId: string | null;
+  limits: {
+    monthlyItems: number;
+  };
+  features: string[];
+}
+
+export const PLANS: Record<PlanId, PlanDefinition> = {
+  free: {
+    id: 'free',
+    name: 'Free',
+    price: 0,
+    stripePriceId: null,
+    limits: {
+      monthlyItems: 5,
+    },
+    features: [
+      'Up to 5 items per month',
+      'Basic features',
+    ],
+  },
+  pro: {
+    id: 'pro',
+    name: 'Pro',
+    price: 29,
+    stripePriceId: process.env.STRIPE_PRO_PRICE_ID || '',
+    limits: {
+      monthlyItems: Infinity,
+    },
+    features: [
+      'Unlimited items',
+      'Priority support',
+      'Advanced features',
+    ],
+  },
+};
+
+export function getPlan(planId: string): PlanDefinition {
+  return PLANS[planId as PlanId] ?? PLANS.free;
+}
+
+// --- USER CODE END ---

package/dist/foundation/payments_basic/shared/reconciliation.ts

@@ -0,0 +1,85 @@
+import { createAdminClient } from '@/shared/db/supabase-client';
+import { stripe } from '@/shared/billing/stripe-client';
+
+// --- ASA GENERATED START ---
+// Reconciliation job template — identifies and repairs drift between Stripe and local DB.
+// Run periodically (e.g., daily via cron) to catch missed webhooks or state inconsistencies.
+// --- ASA GENERATED END ---
+
+// --- USER CODE START ---
+
+export interface ReconciliationResult {
+  checked: number;
+  drifted: number;
+  repaired: number;
+  errors: string[];
+}
+
+/**
+ * Reconcile local subscription state with Stripe.
+ * Fetches all active Stripe subscriptions and compares with local DB.
+ * Repairs any drift found.
+ */
+export async function reconcileSubscriptions(): Promise<ReconciliationResult> {
+  const supabase = createAdminClient();
+  const result: ReconciliationResult = { checked: 0, drifted: 0, repaired: 0, errors: [] };
+
+  try {
+    // Get all local subscriptions with Stripe customer IDs
+    const { data: localSubs } = await supabase
+      .from('subscriptions')
+      .select('user_id, stripe_customer_id, stripe_subscription_id, plan, status')
+      .not('stripe_customer_id', 'is', null);
+
+    if (!localSubs) return result;
+
+    for (const local of localSubs) {
+      result.checked++;
+
+      try {
+        if (!local.stripe_subscription_id) continue;
+
+        // Fetch current state from Stripe (source of truth)
+        const stripeSub = await stripe.subscriptions.retrieve(local.stripe_subscription_id);
+
+        // Compare status
+        const stripeStatus = mapStripeStatus(stripeSub.status);
+        if (local.status !== stripeStatus) {
+          result.drifted++;
+
+          await supabase
+            .from('subscriptions')
+            .update({ status: stripeStatus })
+            .eq('user_id', local.user_id);
+
+          result.repaired++;
+          console.log(
+            `[reconciliation] Repaired drift for user ${local.user_id}: ` +
+            `${local.status} → ${stripeStatus}`,
+          );
+        }
+      } catch (err) {
+        result.errors.push(
+          `User ${local.user_id}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  } catch (err) {
+    result.errors.push(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  return result;
+}
+
+function mapStripeStatus(stripeStatus: string): string {
+  switch (stripeStatus) {
+    case 'active': return 'active';
+    case 'trialing': return 'trialing';
+    case 'past_due': return 'past_due';
+    case 'canceled': return 'canceled';
+    case 'unpaid': return 'past_due';
+    default: return stripeStatus;
+  }
+}
+
+// --- USER CODE END ---