@rovela-ai/sdk 0.4.1 → 0.4.2

package/dist/admin/api/shipping.js

@@ -0,0 +1,746 @@
+/**
+ * @rovela/sdk/admin/api/shipping
+ *
+ * API route handlers for admin shipping carrier, zone, and rate management.
+ * Implements a carrier-first hierarchy: Carrier → Zone → Rate
+ *
+ * Usage:
+ * ```typescript
+ * // app/api/admin/shipping/carriers/route.ts
+ * export { getCarriers as GET, createCarrier as POST } from '@rovela/sdk/admin/api/shipping'
+ *
+ * // app/api/admin/shipping/carriers/[id]/route.ts
+ * export { getCarrier as GET, updateCarrier as PUT, deleteCarrier as DELETE } from '@rovela/sdk/admin/api/shipping'
+ *
+ * // app/api/admin/shipping/zones/route.ts
+ * export { getZones as GET, createZone as POST } from '@rovela/sdk/admin/api/shipping'
+ *
+ * // app/api/admin/shipping/zones/[id]/route.ts
+ * export { getZone as GET, updateZone as PUT, deleteZone as DELETE } from '@rovela/sdk/admin/api/shipping'
+ *
+ * // app/api/admin/shipping/rates/route.ts
+ * export { createRate as POST } from '@rovela/sdk/admin/api/shipping'
+ *
+ * // app/api/admin/shipping/rates/[id]/route.ts
+ * export { updateRate as PUT, deleteRate as DELETE } from '@rovela/sdk/admin/api/shipping'
+ * ```
+ */
+import { NextResponse } from 'next/server';
+import { requireAdmin } from '../server/admin-session';
+import { 
+// Carrier queries
+findCarriersWithZonesAndRates, findShippingCarrierById, createShippingCarrier, updateShippingCarrier, deleteShippingCarrier, 
+// Zone queries
+findShippingZones, findShippingZoneById, createShippingZone, updateShippingZone, deleteShippingZone, 
+// Rate queries
+createShippingRate, updateShippingRate, deleteShippingRate, 
+// Settings queries (for Shippo API key)
+findSettings, upsertSettings, } from '../../core/db/queries';
+// =============================================================================
+// Shipping Carriers - List & Create
+// =============================================================================
+/**
+ * GET /api/admin/shipping/carriers
+ *
+ * List all shipping carriers with their zones and rates.
+ * Returns carriers sorted by sortOrder, each with nested zones/rates.
+ */
+export async function getCarriers() {
+    // Shipping config is part of store settings — read permission.
+    const guard = await requireAdmin({ permission: 'settings.read' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const carriers = await findCarriersWithZonesAndRates();
+        return NextResponse.json({ data: carriers });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] getCarriers error:', error);
+        return NextResponse.json({ error: 'Failed to fetch shipping carriers', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * POST /api/admin/shipping/carriers
+ *
+ * Create a new shipping carrier.
+ * Store owners define their own carriers (e.g., "Standard Delivery", "Local Pickup").
+ *
+ * Request Body:
+ * ```json
+ * {
+ *   "name": "Standard Delivery",
+ *   "code": "standard",
+ *   "description": "Regular shipping via postal service",
+ *   "isActive": true,
+ *   "sortOrder": 0
+ * }
+ * ```
+ */
+export async function createCarrier(request) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const body = await request.json();
+        // Validate required fields
+        if (!body.name || typeof body.name !== 'string' || body.name.trim().length === 0) {
+            return NextResponse.json({ error: 'Carrier name is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        if (!body.code || typeof body.code !== 'string' || body.code.trim().length === 0) {
+            return NextResponse.json({ error: 'Carrier code is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        // Sanitize code: lowercase, alphanumeric + hyphens only
+        const code = body.code
+            .toLowerCase()
+            .trim()
+            .replace(/[^a-z0-9-]/g, '-')
+            .replace(/-+/g, '-')
+            .slice(0, 50);
+        if (code.length === 0) {
+            return NextResponse.json({ error: 'Carrier code must contain alphanumeric characters', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        const carrier = await createShippingCarrier({
+            name: body.name.trim().slice(0, 255),
+            code,
+            description: body.description ? body.description.trim().slice(0, 500) : undefined,
+            isActive: body.isActive !== false,
+            sortOrder: typeof body.sortOrder === 'number' ? body.sortOrder : 0,
+        });
+        return NextResponse.json({ success: true, data: carrier }, { status: 201 });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] createCarrier error:', error);
+        // Handle unique constraint violation
+        if (error instanceof Error && error.message.includes('unique')) {
+            return NextResponse.json({ error: 'A carrier with this code already exists', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        return NextResponse.json({ error: 'Failed to create shipping carrier', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+// =============================================================================
+// Shipping Carriers - Single Operations
+// =============================================================================
+/**
+ * GET /api/admin/shipping/carriers/[id]
+ *
+ * Get a single shipping carrier by ID with its zones and rates.
+ */
+export async function getCarrier(_request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.read' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const carrier = await findShippingCarrierById(id);
+        if (!carrier) {
+            return NextResponse.json({ error: 'Shipping carrier not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        return NextResponse.json({ data: carrier });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] getCarrier error:', error);
+        return NextResponse.json({ error: 'Failed to fetch shipping carrier', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * PUT /api/admin/shipping/carriers/[id]
+ *
+ * Update a shipping carrier by ID.
+ *
+ * Request Body:
+ * ```json
+ * {
+ *   "name": "Express Delivery",
+ *   "code": "express",
+ *   "description": "Fast shipping option",
+ *   "isActive": true,
+ *   "sortOrder": 1
+ * }
+ * ```
+ */
+export async function updateCarrier(request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const body = await request.json();
+        // Check carrier exists
+        const existing = await findShippingCarrierById(id);
+        if (!existing) {
+            return NextResponse.json({ error: 'Shipping carrier not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        // Build update data
+        const updateData = {};
+        if (body.name !== undefined) {
+            if (typeof body.name !== 'string' || body.name.trim().length === 0) {
+                return NextResponse.json({ error: 'Carrier name cannot be empty', code: 'VALIDATION_ERROR' }, { status: 400 });
+            }
+            updateData.name = body.name.trim().slice(0, 255);
+        }
+        if (body.code !== undefined) {
+            const code = body.code
+                .toLowerCase()
+                .trim()
+                .replace(/[^a-z0-9-]/g, '-')
+                .replace(/-+/g, '-')
+                .slice(0, 50);
+            if (code.length === 0) {
+                return NextResponse.json({ error: 'Carrier code must contain alphanumeric characters', code: 'VALIDATION_ERROR' }, { status: 400 });
+            }
+            updateData.code = code;
+        }
+        if (body.description !== undefined) {
+            updateData.description = body.description ? body.description.trim().slice(0, 500) : null;
+        }
+        if (body.isActive !== undefined) {
+            updateData.isActive = Boolean(body.isActive);
+        }
+        if (body.sortOrder !== undefined) {
+            updateData.sortOrder = typeof body.sortOrder === 'number' ? body.sortOrder : 0;
+        }
+        const carrier = await updateShippingCarrier(id, updateData);
+        return NextResponse.json({ success: true, data: carrier });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] updateCarrier error:', error);
+        // Handle unique constraint violation
+        if (error instanceof Error && error.message.includes('unique')) {
+            return NextResponse.json({ error: 'A carrier with this code already exists', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        return NextResponse.json({ error: 'Failed to update shipping carrier', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * DELETE /api/admin/shipping/carriers/[id]
+ *
+ * Delete a shipping carrier by ID.
+ * This cascades to delete all zones and rates under this carrier.
+ */
+export async function deleteCarrier(_request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const deleted = await deleteShippingCarrier(id);
+        if (!deleted) {
+            return NextResponse.json({ error: 'Shipping carrier not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        return NextResponse.json({ success: true });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] deleteCarrier error:', error);
+        return NextResponse.json({ error: 'Failed to delete shipping carrier', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+// =============================================================================
+// Shipping Zones - List & Create
+// =============================================================================
+/**
+ * GET /api/admin/shipping/zones
+ *
+ * List all shipping zones with their rates.
+ */
+export async function getZones() {
+    const guard = await requireAdmin({ permission: 'settings.read' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const zones = await findShippingZones();
+        return NextResponse.json({ data: zones });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] getZones error:', error);
+        return NextResponse.json({ error: 'Failed to fetch shipping zones', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * POST /api/admin/shipping/zones
+ *
+ * Create a new shipping zone under a carrier.
+ * Zones must belong to a carrier (carrier-first architecture).
+ *
+ * Request Body:
+ * ```json
+ * {
+ *   "carrierId": "uuid",
+ *   "name": "Domestic",
+ *   "countries": ["US", "CA"],
+ *   "isActive": true,
+ *   "sortOrder": 0
+ * }
+ * ```
+ */
+export async function createZone(request) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const body = await request.json();
+        // Validate required fields
+        if (!body.carrierId || typeof body.carrierId !== 'string') {
+            return NextResponse.json({ error: 'Carrier ID is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        if (!body.name || typeof body.name !== 'string') {
+            return NextResponse.json({ error: 'Zone name is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        if (!Array.isArray(body.countries) || body.countries.length === 0) {
+            return NextResponse.json({ error: 'At least one country is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        // Verify carrier exists
+        const carrier = await findShippingCarrierById(body.carrierId);
+        if (!carrier) {
+            return NextResponse.json({ error: 'Shipping carrier not found', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        // Sanitize countries (uppercase, 2-char codes, or '*')
+        const countries = body.countries
+            .filter((c) => typeof c === 'string')
+            .map((c) => c.toUpperCase().trim())
+            .filter((c) => c === '*' || c.length === 2);
+        if (countries.length === 0) {
+            return NextResponse.json({ error: 'Invalid country codes. Use 2-letter ISO codes or "*" for all countries.', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        const zone = await createShippingZone({
+            carrierId: body.carrierId,
+            name: body.name.trim().slice(0, 255),
+            countries,
+            isActive: body.isActive !== false,
+            sortOrder: typeof body.sortOrder === 'number' ? body.sortOrder : 0,
+        });
+        return NextResponse.json({ success: true, data: zone }, { status: 201 });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] createZone error:', error);
+        return NextResponse.json({ error: 'Failed to create shipping zone', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+// =============================================================================
+// Shipping Zones - Single Operations
+// =============================================================================
+/**
+ * GET /api/admin/shipping/zones/[id]
+ *
+ * Get a single shipping zone by ID with its rates.
+ */
+export async function getZone(_request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.read' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const zone = await findShippingZoneById(id);
+        if (!zone) {
+            return NextResponse.json({ error: 'Shipping zone not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        return NextResponse.json({ data: zone });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] getZone error:', error);
+        return NextResponse.json({ error: 'Failed to fetch shipping zone', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * PUT /api/admin/shipping/zones/[id]
+ *
+ * Update a shipping zone by ID.
+ * Can move zone to a different carrier by changing carrierId.
+ *
+ * Request Body:
+ * ```json
+ * {
+ *   "carrierId": "uuid",
+ *   "name": "Updated Zone Name",
+ *   "countries": ["US", "CA", "MX"],
+ *   "isActive": true,
+ *   "sortOrder": 1
+ * }
+ * ```
+ */
+export async function updateZone(request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const body = await request.json();
+        // Check zone exists
+        const existing = await findShippingZoneById(id);
+        if (!existing) {
+            return NextResponse.json({ error: 'Shipping zone not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        // Build update data
+        const updateData = {};
+        // Allow moving zone to different carrier
+        if (body.carrierId !== undefined) {
+            if (typeof body.carrierId !== 'string') {
+                return NextResponse.json({ error: 'Invalid carrier ID', code: 'VALIDATION_ERROR' }, { status: 400 });
+            }
+            // Verify new carrier exists
+            const carrier = await findShippingCarrierById(body.carrierId);
+            if (!carrier) {
+                return NextResponse.json({ error: 'Shipping carrier not found', code: 'VALIDATION_ERROR' }, { status: 400 });
+            }
+            updateData.carrierId = body.carrierId;
+        }
+        if (body.name !== undefined) {
+            updateData.name = body.name.trim().slice(0, 255);
+        }
+        if (body.countries !== undefined) {
+            if (!Array.isArray(body.countries) || body.countries.length === 0) {
+                return NextResponse.json({ error: 'At least one country is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+            }
+            const countries = body.countries
+                .filter((c) => typeof c === 'string')
+                .map((c) => c.toUpperCase().trim())
+                .filter((c) => c === '*' || c.length === 2);
+            if (countries.length === 0) {
+                return NextResponse.json({ error: 'Invalid country codes', code: 'VALIDATION_ERROR' }, { status: 400 });
+            }
+            updateData.countries = countries;
+        }
+        if (body.isActive !== undefined) {
+            updateData.isActive = Boolean(body.isActive);
+        }
+        if (body.sortOrder !== undefined) {
+            updateData.sortOrder = typeof body.sortOrder === 'number' ? body.sortOrder : 0;
+        }
+        const zone = await updateShippingZone(id, updateData);
+        return NextResponse.json({ success: true, data: zone });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] updateZone error:', error);
+        return NextResponse.json({ error: 'Failed to update shipping zone', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * DELETE /api/admin/shipping/zones/[id]
+ *
+ * Delete a shipping zone by ID. This cascades to delete all rates in the zone.
+ */
+export async function deleteZone(_request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const deleted = await deleteShippingZone(id);
+        if (!deleted) {
+            return NextResponse.json({ error: 'Shipping zone not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        return NextResponse.json({ success: true });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] deleteZone error:', error);
+        return NextResponse.json({ error: 'Failed to delete shipping zone', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+// =============================================================================
+// Shipping Rates - Create
+// =============================================================================
+/**
+ * POST /api/admin/shipping/rates
+ *
+ * Create a new shipping rate for a zone.
+ *
+ * Request Body:
+ * ```json
+ * {
+ *   "zoneId": "uuid",
+ *   "name": "Standard Shipping",
+ *   "description": "5-7 business days",
+ *   "price": 5.99,
+ *   "minOrderAmount": 0,
+ *   "maxOrderAmount": null,
+ *   "estimatedDays": "5-7",
+ *   "isActive": true,
+ *   "sortOrder": 0
+ * }
+ * ```
+ */
+export async function createRate(request) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const body = await request.json();
+        // Validate required fields
+        if (!body.zoneId || typeof body.zoneId !== 'string') {
+            return NextResponse.json({ error: 'Zone ID is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        if (!body.name || typeof body.name !== 'string') {
+            return NextResponse.json({ error: 'Rate name is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        if (typeof body.price !== 'number' || body.price < 0) {
+            return NextResponse.json({ error: 'Valid price is required (non-negative number)', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        // Verify zone exists
+        const zone = await findShippingZoneById(body.zoneId);
+        if (!zone) {
+            return NextResponse.json({ error: 'Shipping zone not found', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        const rate = await createShippingRate({
+            zoneId: body.zoneId,
+            name: body.name.trim().slice(0, 255),
+            description: body.description ? body.description.trim().slice(0, 500) : undefined,
+            price: body.price,
+            minOrderAmount: typeof body.minOrderAmount === 'number' && body.minOrderAmount >= 0
+                ? body.minOrderAmount
+                : undefined,
+            maxOrderAmount: typeof body.maxOrderAmount === 'number' && body.maxOrderAmount >= 0
+                ? body.maxOrderAmount
+                : undefined,
+            estimatedDays: body.estimatedDays ? body.estimatedDays.trim().slice(0, 50) : undefined,
+            isActive: body.isActive !== false,
+            sortOrder: typeof body.sortOrder === 'number' ? body.sortOrder : 0,
+        });
+        return NextResponse.json({ success: true, data: rate }, { status: 201 });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] createRate error:', error);
+        return NextResponse.json({ error: 'Failed to create shipping rate', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+// =============================================================================
+// Shipping Rates - Update & Delete
+// =============================================================================
+/**
+ * PUT /api/admin/shipping/rates/[id]
+ *
+ * Update a shipping rate by ID.
+ *
+ * Request Body:
+ * ```json
+ * {
+ *   "name": "Express Shipping",
+ *   "description": "2-3 business days",
+ *   "price": 12.99,
+ *   "minOrderAmount": 0,
+ *   "maxOrderAmount": 100,
+ *   "estimatedDays": "2-3",
+ *   "isActive": true,
+ *   "sortOrder": 1
+ * }
+ * ```
+ */
+export async function updateRate(request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const body = await request.json();
+        // Build update data
+        const updateData = {};
+        if (body.name !== undefined) {
+            updateData.name = body.name.trim().slice(0, 255);
+        }
+        if (body.description !== undefined) {
+            updateData.description = body.description ? body.description.trim().slice(0, 500) : null;
+        }
+        if (body.price !== undefined) {
+            if (typeof body.price !== 'number' || body.price < 0) {
+                return NextResponse.json({ error: 'Price must be a non-negative number', code: 'VALIDATION_ERROR' }, { status: 400 });
+            }
+            updateData.price = body.price;
+        }
+        if (body.minOrderAmount !== undefined) {
+            updateData.minOrderAmount = typeof body.minOrderAmount === 'number' && body.minOrderAmount >= 0
+                ? body.minOrderAmount
+                : null;
+        }
+        if (body.maxOrderAmount !== undefined) {
+            updateData.maxOrderAmount = typeof body.maxOrderAmount === 'number' && body.maxOrderAmount >= 0
+                ? body.maxOrderAmount
+                : null;
+        }
+        if (body.estimatedDays !== undefined) {
+            updateData.estimatedDays = body.estimatedDays ? body.estimatedDays.trim().slice(0, 50) : null;
+        }
+        if (body.isActive !== undefined) {
+            updateData.isActive = Boolean(body.isActive);
+        }
+        if (body.sortOrder !== undefined) {
+            updateData.sortOrder = typeof body.sortOrder === 'number' ? body.sortOrder : 0;
+        }
+        const rate = await updateShippingRate(id, updateData);
+        if (!rate) {
+            return NextResponse.json({ error: 'Shipping rate not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        return NextResponse.json({ success: true, data: rate });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] updateRate error:', error);
+        return NextResponse.json({ error: 'Failed to update shipping rate', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * DELETE /api/admin/shipping/rates/[id]
+ *
+ * Delete a shipping rate by ID.
+ */
+export async function deleteRate(_request, { params }) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const { id } = await params;
+        const deleted = await deleteShippingRate(id);
+        if (!deleted) {
+            return NextResponse.json({ error: 'Shipping rate not found', code: 'NOT_FOUND' }, { status: 404 });
+        }
+        return NextResponse.json({ success: true });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] deleteRate error:', error);
+        return NextResponse.json({ error: 'Failed to delete shipping rate', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+// =============================================================================
+// Shippo API Validation
+// =============================================================================
+/**
+ * POST /api/admin/shipping/shippo/validate
+ *
+ * Validate Shippo API key.
+ * Checks database first for store-specific key, falls back to environment variable.
+ *
+ * Response:
+ * ```json
+ * { "valid": true, "hasStoredKey": true, "maskedKey": "...abc1" }
+ * // or
+ * { "valid": false, "error": "Invalid API key", "hasStoredKey": false }
+ * ```
+ */
+export async function validateShippoApiKey() {
+    const guard = await requireAdmin({ permission: 'settings.read' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        // 1. Check database for stored API key first
+        const settings = await findSettings();
+        let apiKey = settings?.shippoApiKey;
+        const hasStoredKey = !!apiKey;
+        // 2. Fallback to environment variable
+        if (!apiKey) {
+            apiKey = process.env.SHIPPO_API_KEY;
+        }
+        if (!apiKey) {
+            return NextResponse.json({
+                valid: false,
+                error: 'No Shippo API key configured. Add it in Settings > Shipping.',
+                hasStoredKey: false,
+                maskedKey: null,
+            });
+        }
+        // 3. Validate with Shippo API
+        const { validateShippoKey } = await import('../../shipping/shippo');
+        const result = await validateShippoKey(apiKey);
+        return NextResponse.json({
+            ...result,
+            hasStoredKey,
+            maskedKey: hasStoredKey ? `...${apiKey.slice(-4)}` : null,
+        });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] validateShippoApiKey error:', error);
+        return NextResponse.json({ error: 'Failed to validate Shippo API key', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * POST /api/admin/shipping/shippo/api-key
+ *
+ * Save Shippo API key to database.
+ * Validates the key with Shippo before saving.
+ *
+ * Request:
+ * ```json
+ * { "apiKey": "shippo_live_abc123..." }
+ * ```
+ *
+ * Response:
+ * ```json
+ * { "success": true, "maskedKey": "...c123", "message": "Shippo API key saved successfully" }
+ * ```
+ */
+export async function saveShippoApiKey(request) {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        const body = await request.json();
+        const { apiKey } = body;
+        // Validate input
+        if (!apiKey || typeof apiKey !== 'string') {
+            return NextResponse.json({ error: 'API key is required', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        const trimmedKey = apiKey.trim();
+        if (trimmedKey.length < 10) {
+            return NextResponse.json({ error: 'Invalid API key format', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        // Validate the key actually works with Shippo
+        const { validateShippoKey } = await import('../../shipping/shippo');
+        const validation = await validateShippoKey(trimmedKey);
+        if (!validation.valid) {
+            return NextResponse.json({ error: validation.error || 'Invalid Shippo API key', code: 'VALIDATION_ERROR' }, { status: 400 });
+        }
+        // Save to database
+        await upsertSettings({ shippoApiKey: trimmedKey });
+        // Return masked key for UI display
+        const maskedKey = `...${trimmedKey.slice(-4)}`;
+        return NextResponse.json({
+            success: true,
+            maskedKey,
+            message: 'Shippo API key saved successfully',
+        });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] saveShippoApiKey error:', error);
+        return NextResponse.json({ error: 'Failed to save Shippo API key', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+/**
+ * DELETE /api/admin/shipping/shippo/api-key
+ *
+ * Remove Shippo API key from database.
+ * After removal, system will fallback to SHIPPO_API_KEY environment variable if set.
+ *
+ * Response:
+ * ```json
+ * { "success": true, "message": "Shippo API key removed" }
+ * ```
+ */
+export async function deleteShippoApiKey() {
+    const guard = await requireAdmin({ permission: 'settings.write' });
+    if (!guard.ok) {
+        return guard.response;
+    }
+    try {
+        // Set to null in database
+        await upsertSettings({ shippoApiKey: null });
+        return NextResponse.json({
+            success: true,
+            message: 'Shippo API key removed. Will fallback to environment variable if configured.',
+        });
+    }
+    catch (error) {
+        console.error('[Admin Shipping API] deleteShippoApiKey error:', error);
+        return NextResponse.json({ error: 'Failed to remove Shippo API key', code: 'INTERNAL_ERROR' }, { status: 500 });
+    }
+}
+//# sourceMappingURL=shipping.js.map