@rovela-ai/sdk 0.4.1 → 0.4.2

package/dist/admin/index.js

@@ -0,0 +1,144 @@
+/**
+ * @rovela/sdk/admin
+ *
+ * Admin dashboard module: complete store management with separate admin auth.
+ *
+ * ## Features
+ * - Separate admin authentication (independent from customer auth)
+ * - Dashboard with stats, recent orders, and low stock alerts
+ * - Product management with variants and inventory
+ * - Order management with status updates and refunds
+ * - Customer viewing
+ * - Store settings
+ *
+ * ## Usage
+ *
+ * ### Setup Auth (app/api/admin-auth/[...nextauth]/route.ts)
+ * ```typescript
+ * import NextAuth from 'next-auth'
+ * import { createAdminAuthOptions } from '@rovela-ai/sdk/admin'
+ * const handler = NextAuth(createAdminAuthOptions())
+ * export { handler as GET, handler as POST }
+ * ```
+ *
+ * ### Protected Layout (app/admin/layout.tsx)
+ * ```tsx
+ * import { AdminGuard, AdminLayout } from '@rovela/sdk/admin'
+ *
+ * export default function Layout({ children }) {
+ *   return (
+ *     <AdminGuard>
+ *       <AdminLayout storeName="My Store">
+ *         {children}
+ *       </AdminLayout>
+ *     </AdminGuard>
+ *   )
+ * }
+ * ```
+ *
+ * ### Dashboard Page (app/admin/page.tsx)
+ * ```tsx
+ * import { StatsCards, RecentOrders, LowStockAlert, useAdminStats } from '@rovela/sdk/admin'
+ *
+ * export default function DashboardPage() {
+ *   const { stats, isLoading } = useAdminStats()
+ *   return (
+ *     <div>
+ *       <StatsCards stats={stats} isLoading={isLoading} />
+ *       <div className="grid grid-cols-2 gap-6">
+ *         <RecentOrders />
+ *         <LowStockAlert />
+ *       </div>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+// =============================================================================
+// Configuration (NextAuth)
+// =============================================================================
+export { createAdminAuthOptions, getAdminSession, } from './config';
+// =============================================================================
+// Server-side Services
+// =============================================================================
+export { authenticateAdmin, createAdmin, updateAdminPassword, findAdminForSession, findAdminByEmail, findAdminById, updateAdmin, adminEmailExists, countAdmins, 
+// Password reset (Phase 1)
+requestAdminPasswordReset, validateAdminResetToken, resetAdminPassword, deleteAdminPasswordResetTokens, cleanupExpiredAdminResetTokens, 
+// User management (Phase 2)
+listAdmins, countActiveOwners, deactivateAdmin, reactivateAdmin, hardDeleteAdmin, 
+// Phase 3 — invite flow + role change
+inviteAdmin, resendAdminInvite, cancelAdminInvite, changeAdminRole, validateInviteToken, acceptAdminInvite, deleteAdminInviteTokens, cleanupExpiredInviteTokens, 
+// Phase 4 — self-service
+changeOwnPassword, updateOwnProfile, 
+// Centralized auth guard for custom template routes
+requireAdmin, invalidateAdminSession, } from './server';
+// =============================================================================
+// API Route Handlers (re-exported for convenience)
+// Can also import from '@rovela-ai/sdk/admin/api' for individual handlers
+// =============================================================================
+export { getProducts, createProduct, getProduct, updateProduct, deleteProduct, addVariant, updateVariantHandler, deleteVariantHandler, getOrders, getOrder, updateOrder, processRefund, getStats, getCategories, createCategory, getCategory, updateCategory, deleteCategory, getCustomers, getCustomer, 
+// Setup (first-time admin creation)
+setupAdmin, 
+// Check (check if admin exists)
+checkAdminExists, 
+// Settings
+getSettings, updateSettings, 
+// Stripe Status
+getStripeStatus, 
+// Shipping Carriers
+getShippingCarriers, createShippingCarrier, getShippingCarrier, updateShippingCarrier, deleteShippingCarrier, 
+// Shipping Zones & Rates
+getShippingZones, createShippingZone, getShippingZone, updateShippingZone, deleteShippingZone, createShippingRate, updateShippingRate, deleteShippingRate, 
+// Tax Zones
+getTaxZones, createTaxZone, getTaxZone, updateTaxZone, deleteTaxZone, } from './api';
+// =============================================================================
+// React Hooks
+// =============================================================================
+export { useAdminAuth, useAdminSession, useAdminStats, useAdminProducts, useAdminProductMetrics, useAdminOrders, useAdminCategories, useAdminCustomers, 
+// Phase 2
+useAdminUsers, useAdminPermissions, 
+// Phase 4
+useAdminMe, 
+// R112
+useLinkedCustomerStatus, 
+// Setup guide (new-merchant onboarding)
+useSetupGuide, } from './hooks';
+// =============================================================================
+// React Components
+// =============================================================================
+export { 
+// Auth
+AdminGuard, AdminLoginForm, 
+// Layout
+AdminLayout, AdminNav, AdminBarBanner, ExampleContentBanner, 
+// Dashboard
+StatsCards, RecentOrders, LowStockAlert, RevenueChart, OrderStatusChart, PrimaryMetricsRow, SecondaryMetricsRow, PeriodSelector, SetupGuide, 
+// Products
+ProductTable, ProductForm, InventoryEditor, 
+// Categories
+CategorySelect, CategoryForm, 
+// Utility (used by ProductForm)
+SEOPreview, TagInput, VariantManager, 
+// Orders
+OrderTable, OrderDetails, RefundDialog, 
+// Settings
+StoreSettings, LogoUpload, PaymentSettings, 
+// Shipping
+ShippingSettings, 
+// Tax
+TaxSettings, 
+// Customers
+CustomerTable, CustomerDetails, 
+// User management (Phase 2)
+UsersTable, 
+// Auth forms (Phase 1)
+AdminForgotPasswordForm, AdminResetPasswordForm, 
+// User management (Phase 3)
+InviteUserDialog, AdminAcceptInviteForm, 
+// Self-service (Phase 4)
+AdminAccountPage, 
+// Role reference matrix (shown on Users page)
+PermissionsMatrix, 
+// Utility
+DeleteConfirmDialog, } from './components';
+//# sourceMappingURL=index.js.map

package/dist/admin/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/admin/index.ts"],"names":[],"mappings":"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"}

package/dist/admin/permissions.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @rovela/sdk/admin/permissions
+ *
+ * Role-based permission matrix for store admins.
+ *
+ * # Four-role hierarchy (strict)
+ *
+ *   owner          (rank 0) can do everything, including managing other owners.
+ *                           Subject to "at least one active owner always exists".
+ *   administrator  (rank 1) can do everything except manage owners or other administrators.
+ *                           Prevents lateral privilege escalation.
+ *   manager        (rank 2) full day-to-day operational access (products, orders, customers,
+ *                           returns, refunds). Cannot touch settings, billing, or users.
+ *   user           (rank 3) read-only on most resources + write access to orders only
+ *                           (for warehouse/fulfillment staff updating tracking).
+ *
+ * # Client vs server
+ *
+ * All checks in this file are pure functions over static data. They are safe to
+ * import from both server and client code. The server uses them as the source
+ * of truth for authorization; the client uses them for UX gating (hide/disable
+ * buttons). The client is always advisory — the server is the gate.
+ */
+import type { AdminRole } from '../core/types';
+/**
+ * Every action an admin can perform, grouped by resource. Adding a new
+ * permission here means:
+ *   1. Add it to this type union
+ *   2. Assign it to one or more roles in the PERMISSIONS map below
+ *   3. Reference it via `hasPermission(role, 'foo.bar')` at the relevant API handler
+ */
+export type Permission = 'products.read' | 'products.write' | 'products.delete' | 'orders.read' | 'orders.write' | 'orders.refund' | 'returns.approve' | 'returns.reject' | 'customers.read' | 'customers.write' | 'customers.delete' | 'settings.read' | 'settings.write' | 'billing.read' | 'billing.write' | 'users.read' | 'users.write' | 'users.delete';
+/**
+ * Returns true if `actorRole` is at least as powerful as `minRole`.
+ *
+ * @example
+ * meetsMinRole('owner', 'manager')  // true
+ * meetsMinRole('user', 'manager')   // false
+ */
+export declare function meetsMinRole(actorRole: AdminRole | null | undefined, minRole: AdminRole): boolean;
+/**
+ * Does this role have a specific permission?
+ *
+ * Safe to call with `undefined` / `null` actor — returns `false`, which is what
+ * unauthenticated requests want.
+ *
+ * @example
+ * hasPermission('owner', 'users.delete')          // true
+ * hasPermission('administrator', 'users.delete')  // false
+ * hasPermission(undefined, 'products.read')       // false
+ */
+export declare function hasPermission(role: AdminRole | null | undefined, permission: Permission): boolean;
+/**
+ * Can `actor` modify `target` as a user-management action?
+ *
+ * Rules:
+ *   - Owners can manage anyone, including other owners. The "at least one
+ *     active owner must remain" invariant is enforced separately at the
+ *     service layer, not here — this helper only answers "does the actor
+ *     have the authority in principle?"
+ *   - Administrators can manage managers and users only. They cannot touch
+ *     owners or other administrators. (Prevents lateral escalation.)
+ *   - Managers and users cannot manage anyone.
+ *   - Actor cannot manage themselves via this helper. Self-actions (password
+ *     change, profile update) go through /api/admin/me/* endpoints and have
+ *     their own rules.
+ */
+export declare function canManageUser(actor: {
+    id: string;
+    role: AdminRole;
+}, target: {
+    id: string;
+    role: AdminRole;
+}): boolean;
+/**
+ * Human-readable label for a role.
+ */
+export declare function roleLabel(role: AdminRole): string;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/admin/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/admin/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAM9C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAElB,eAAe,GACf,gBAAgB,GAChB,iBAAiB,GAEjB,aAAa,GACb,cAAc,GACd,eAAe,GAEf,iBAAiB,GACjB,gBAAgB,GAEhB,gBAAgB,GAChB,iBAAiB,GACjB,kBAAkB,GAElB,eAAe,GACf,gBAAgB,GAEhB,cAAc,GACd,eAAe,GAEf,YAAY,GACZ,aAAa,GACb,cAAc,CAAA;AAiBlB;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,EACvC,OAAO,EAAE,SAAS,GACjB,OAAO,CAGT;AAmFD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,EAClC,UAAU,EAAE,UAAU,GACrB,OAAO,CAIT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,EACtC,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GACtC,OAAO,CAaT;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAWjD"}

package/dist/admin/permissions.js

@@ -0,0 +1,182 @@
+/**
+ * @rovela/sdk/admin/permissions
+ *
+ * Role-based permission matrix for store admins.
+ *
+ * # Four-role hierarchy (strict)
+ *
+ *   owner          (rank 0) can do everything, including managing other owners.
+ *                           Subject to "at least one active owner always exists".
+ *   administrator  (rank 1) can do everything except manage owners or other administrators.
+ *                           Prevents lateral privilege escalation.
+ *   manager        (rank 2) full day-to-day operational access (products, orders, customers,
+ *                           returns, refunds). Cannot touch settings, billing, or users.
+ *   user           (rank 3) read-only on most resources + write access to orders only
+ *                           (for warehouse/fulfillment staff updating tracking).
+ *
+ * # Client vs server
+ *
+ * All checks in this file are pure functions over static data. They are safe to
+ * import from both server and client code. The server uses them as the source
+ * of truth for authorization; the client uses them for UX gating (hide/disable
+ * buttons). The client is always advisory — the server is the gate.
+ */
+// =============================================================================
+// Role ranks + hierarchy helpers
+// =============================================================================
+/**
+ * Lower number = higher power. Used by `meetsMinRole` to enforce "must be at
+ * least an administrator" style checks.
+ */
+const ROLE_RANK = {
+    owner: 0,
+    administrator: 1,
+    manager: 2,
+    user: 3,
+};
+/**
+ * Returns true if `actorRole` is at least as powerful as `minRole`.
+ *
+ * @example
+ * meetsMinRole('owner', 'manager')  // true
+ * meetsMinRole('user', 'manager')   // false
+ */
+export function meetsMinRole(actorRole, minRole) {
+    if (!actorRole)
+        return false;
+    return ROLE_RANK[actorRole] <= ROLE_RANK[minRole];
+}
+// =============================================================================
+// Permission matrix
+// =============================================================================
+const OWNER_PERMISSIONS = [
+    'products.read',
+    'products.write',
+    'products.delete',
+    'orders.read',
+    'orders.write',
+    'orders.refund',
+    'returns.approve',
+    'returns.reject',
+    'customers.read',
+    'customers.write',
+    'customers.delete',
+    'settings.read',
+    'settings.write',
+    'billing.read',
+    'billing.write',
+    'users.read',
+    'users.write',
+    'users.delete',
+];
+const ADMINISTRATOR_PERMISSIONS = [
+    'products.read',
+    'products.write',
+    'products.delete',
+    'orders.read',
+    'orders.write',
+    'orders.refund',
+    'returns.approve',
+    'returns.reject',
+    'customers.read',
+    'customers.write',
+    'customers.delete',
+    'settings.read',
+    'settings.write',
+    'billing.read',
+    'billing.write',
+    'users.read',
+    'users.write',
+    // NOTE: 'users.delete' is intentionally owner-only. Administrators can
+    // deactivate (via users.write + canManageUser) but not hard-delete.
+];
+const MANAGER_PERMISSIONS = [
+    'products.read',
+    'products.write',
+    'orders.read',
+    'orders.write',
+    'orders.refund',
+    'returns.approve',
+    'returns.reject',
+    'customers.read',
+    'customers.write',
+    'settings.read',
+];
+const USER_PERMISSIONS = [
+    'products.read',
+    'orders.read',
+    'orders.write', // fulfillment staff update tracking/status
+];
+/**
+ * The canonical permission map. Each role points at a Set<Permission> for O(1)
+ * membership checks.
+ */
+const PERMISSIONS = {
+    owner: new Set(OWNER_PERMISSIONS),
+    administrator: new Set(ADMINISTRATOR_PERMISSIONS),
+    manager: new Set(MANAGER_PERMISSIONS),
+    user: new Set(USER_PERMISSIONS),
+};
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Does this role have a specific permission?
+ *
+ * Safe to call with `undefined` / `null` actor — returns `false`, which is what
+ * unauthenticated requests want.
+ *
+ * @example
+ * hasPermission('owner', 'users.delete')          // true
+ * hasPermission('administrator', 'users.delete')  // false
+ * hasPermission(undefined, 'products.read')       // false
+ */
+export function hasPermission(role, permission) {
+    if (!role)
+        return false;
+    const perms = PERMISSIONS[role];
+    return perms ? perms.has(permission) : false;
+}
+/**
+ * Can `actor` modify `target` as a user-management action?
+ *
+ * Rules:
+ *   - Owners can manage anyone, including other owners. The "at least one
+ *     active owner must remain" invariant is enforced separately at the
+ *     service layer, not here — this helper only answers "does the actor
+ *     have the authority in principle?"
+ *   - Administrators can manage managers and users only. They cannot touch
+ *     owners or other administrators. (Prevents lateral escalation.)
+ *   - Managers and users cannot manage anyone.
+ *   - Actor cannot manage themselves via this helper. Self-actions (password
+ *     change, profile update) go through /api/admin/me/* endpoints and have
+ *     their own rules.
+ */
+export function canManageUser(actor, target) {
+    // No self-management through this helper.
+    if (actor.id === target.id)
+        return false;
+    if (actor.role === 'owner') {
+        return true;
+    }
+    if (actor.role === 'administrator') {
+        return target.role === 'manager' || target.role === 'user';
+    }
+    return false;
+}
+/**
+ * Human-readable label for a role.
+ */
+export function roleLabel(role) {
+    switch (role) {
+        case 'owner':
+            return 'Owner';
+        case 'administrator':
+            return 'Administrator';
+        case 'manager':
+            return 'Manager';
+        case 'user':
+            return 'User';
+    }
+}
+//# sourceMappingURL=permissions.js.map

package/dist/admin/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/admin/permissions.ts"],"names":[],"mappings":"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"}

package/dist/admin/server/admin-invite.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @rovela/sdk/admin/server/admin-invite
+ *
+ * Admin invite token lifecycle: validation, acceptance, and housekeeping.
+ *
+ * Paired with `user-management.ts::inviteAdmin` which creates the token +
+ * sends the email. This file handles the INVITEE's side of the flow: they
+ * click the email link, land on `/admin/accept-invite?token=X`, and this
+ * module validates + consumes the token.
+ *
+ * # Failure modes (all graceful — no exceptions leak out)
+ *
+ *   - Token unknown            → `{valid: false}` / `INVALID_TOKEN`
+ *   - Token expired            → delete row, return `{valid: false}` with "expired"
+ *   - Admin deleted            → cascaded delete already removed the token;
+ *                                caller will see `{valid: false}`
+ *   - Admin already accepted   → `{valid: false}` with "already accepted"
+ *                                (protects against double-clicks)
+ *   - Admin was deactivated    → same as "already accepted" from UX point of view
+ *   - Concurrent acceptance    → atomic UPDATE returns 0 rows → `INVALID_STATE`
+ *
+ * # Design notes
+ *
+ * The structure mirrors `admin-password-reset.ts` from Phase 1 exactly:
+ *   1. `validate*` is non-destructive (opportunistically cleans up expired
+ *      tokens but doesn't touch the admin row).
+ *   2. `accept*` is destructive — it updates the password, flips status,
+ *      and deletes ALL tokens for the admin (both invite + reset tokens,
+ *      so a stale reset link can't resurrect access).
+ *   3. `delete*ForAdmin` helper used by `cancelInvite` / `resendInvite` to
+ *      wipe stale tokens before issuing a new one.
+ *   4. `cleanupExpired` is an optional cron hook.
+ */
+import type { AdminRole } from '../../core/types';
+/**
+ * Invite token lifetime: 72 hours. Matches industry standard
+ * (Google Workspace, GitHub, Shopify).
+ */
+export declare const INVITE_EXPIRY_MS: number;
+/** Token length — nanoid(32) = ~192 bits of entropy, URL-safe. */
+export declare const INVITE_TOKEN_LENGTH = 32;
+/** Display string for the expiry duration. */
+export declare const INVITE_EXPIRY_HOURS = "72";
+export interface AdminInviteSnapshot {
+    id: string;
+    email: string;
+    name: string;
+    role: AdminRole;
+}
+export interface ValidateInviteResult {
+    valid: boolean;
+    error?: string;
+    admin?: AdminInviteSnapshot;
+}
+export interface AcceptInviteResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Create a new invite token for an existing `invited` admin row.
+ *
+ * The caller is responsible for:
+ *   - Validating the admin exists and is in `invited` status
+ *   - Deleting any existing invite tokens for this admin (via
+ *     `deleteAdminInviteTokens`) before calling this to keep "one active
+ *     token" semantics
+ *
+ * @returns The plain-text token that should be embedded in the email link.
+ */
+export declare function createInviteToken(params: {
+    adminId: string;
+    invitedBy: string;
+}): Promise<{
+    token: string;
+    expires: Date;
+}>;
+/**
+ * Validate an invite token without consuming it.
+ *
+ * Used by the accept-invite page on mount to decide between rendering the
+ * password form or an "invalid/expired" error view.
+ *
+ * Side effect: expired tokens are opportunistically deleted as part of the
+ * check. All other failure modes leave the DB untouched.
+ */
+export declare function validateInviteToken(token: string): Promise<ValidateInviteResult>;
+/**
+ * Consume an invite token and activate the invited admin.
+ *
+ * Atomically:
+ *   1. Validates the token + admin row.
+ *   2. Hashes + stores the new password via the existing
+ *      `updateAdminPassword` helper.
+ *   3. Flips status from 'invited' → 'active' via an atomic guarded UPDATE
+ *      (if two clicks race, the second one fails with INVALID_STATE).
+ *   4. Deletes all invite tokens for this admin (single-use batch).
+ *   5. Defensively deletes any stale password reset tokens too — a
+ *      previously abandoned reset flow shouldn't grant access after the
+ *      user has taken ownership of the account via accept-invite.
+ */
+export declare function acceptAdminInvite(token: string, newPassword: string): Promise<AcceptInviteResult>;
+/**
+ * Delete all invite tokens for a specific admin.
+ *
+ * Called from:
+ *   - `user-management.ts::inviteAdmin` — not called; the admin is newly
+ *     created so there are no tokens to delete
+ *   - `user-management.ts::resendAdminInvite` — clear stale tokens before
+ *     creating a new one
+ *   - `acceptAdminInvite` above — invalidate the used batch
+ *   - `user-management.ts::cancelAdminInvite` — cascade handles this
+ *     automatically via FK, but we call explicitly for clarity
+ */
+export declare function deleteAdminInviteTokens(adminId: string): Promise<void>;
+/**
+ * Delete all expired invite tokens. Optional hook for a periodic cleanup
+ * job. Safe to call anytime — no-op if nothing is expired.
+ *
+ * @returns Number of tokens deleted
+ */
+export declare function cleanupExpiredInviteTokens(): Promise<number>;
+//# sourceMappingURL=admin-invite.d.ts.map

package/dist/admin/server/admin-invite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-invite.d.ts","sourceRoot":"","sources":["../../../src/admin/server/admin-invite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AASH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAMjD;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QAAsB,CAAA;AAEnD,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB,OAAO,CAAA;AAMvC,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,SAAS,CAAA;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,mBAAmB,CAAA;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAC,CAa5C;AAMD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,oBAAoB,CAAC,CA+D/B;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC,CA8C7B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK5E;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CAOlE"}