@eminuckan/spine 0.2.4 → 0.3.0

package/docs/installation.md

@@ -0,0 +1,213 @@
+# Installation
+
+This guide gets a new app from zero to a working Spine integration shape.
+
+## Requirements
+
+- Node.js 20 or newer
+- pnpm 9 or newer
+- React 18 or newer when using client-side provider/hooks
+- A Redis-compatible store for server sessions and OAuth state
+- An OpenID Connect provider for the built-in auth flow
+
+## Install
+
+```bash
+pnpm add @eminuckan/spine
+```
+
+For React apps, install the peer dependencies used by the provider and query modules:
+
+```bash
+pnpm add react @tanstack/react-query
+```
+
+## Environment
+
+```bash
+OIDC_AUTHORITY=https://identity.example.com/realms/demo
+OIDC_CLIENT_ID=your-client
+OIDC_REDIRECT_URI=http://localhost:5173/auth/callback
+OIDC_POST_LOGOUT_REDIRECT_URI=http://localhost:5173/
+OIDC_CLIENT_AUTH_METHOD=none
+OIDC_SCOPE="openid profile email api"
+REDIS_URL=redis://localhost:6379
+API_BASE_URL=http://localhost:8080
+```
+
+Use `OIDC_CLIENT_SECRET` with `OIDC_CLIENT_AUTH_METHOD=client_secret_post` or
+`client_secret_basic` for confidential server-side clients.
+
+## React Router Routes
+
+```ts
+// app/routes/auth.login.tsx
+import { login } from '@eminuckan/spine/react-router/server';
+
+export async function loader({ request }: { request: Request }) {
+  throw await login(request, { returnUrl: '/dashboard' });
+}
+```
+
+```ts
+// app/routes/auth.callback.tsx
+import { handleCallback } from '@eminuckan/spine/react-router/server';
+
+export async function loader({ request }: { request: Request }) {
+  return handleCallback(request);
+}
+```
+
+```ts
+// app/routes/auth.logout.tsx
+import { logout } from '@eminuckan/spine/react-router/server';
+
+export async function loader({ request }: { request: Request }) {
+  return logout(request);
+}
+```
+
+```ts
+// app/routes/dashboard.tsx
+import { authRoute } from '@eminuckan/spine/react-router/server';
+
+export async function loader({ request }: { request: Request }) {
+  return authRoute(request, async (user) => ({ user }));
+}
+```
+
+## Tenant Data
+
+Configure cookie conventions in the app layer:
+
+```ts
+import { configureTenantCookie } from '@eminuckan/spine/tenant/server';
+
+configureTenantCookie({
+  name: '__spine_tenant',
+  sameSite: 'Lax',
+  httpOnly: false,
+});
+```
+
+Simple apps can use the default tenant client by configuring endpoint names:
+
+```ts
+import { configureTenantClient } from '@eminuckan/spine/tenant';
+
+configureTenantClient({
+  tenantDataEndpoint: '/api/tenant/data',
+  tenantSwitchEndpoint: '/api/tenant/switch',
+  tenantCookieName: '__spine_tenant',
+});
+```
+
+Apps with different multi-tenancy contracts should provide their own client functions:
+
+```ts
+import { configureTenantClient } from '@eminuckan/spine/tenant';
+
+configureTenantClient({
+  fetchTenantData: async ({ tenantId }) => {
+    const response = await fetch(`/api/workspaces/${tenantId}`);
+    const payload = await response.json();
+    return {
+      id: payload.workspace.id,
+      name: payload.workspace.displayName,
+      plan: payload.workspace.plan,
+    };
+  },
+  switchTenant: async ({ tenantId }) => {
+    const response = await fetch('/api/session/workspace', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ workspaceId: tenantId }),
+    });
+
+    return { success: response.ok, reload: false };
+  },
+});
+```
+
+Use the generic client hooks for new code:
+
+```tsx
+import { useCurrentTenant, useCurrentTenantData, useTenantData } from '@eminuckan/spine/tenant';
+
+export function TenantBadge() {
+  const tenantId = useCurrentTenant();
+  const tenantData = useCurrentTenantData();
+  const { refreshTenantData } = useTenantData();
+
+  return (
+    <button type="button" onClick={refreshTenantData}>
+      {tenantData?.name ?? tenantId ?? 'No tenant'}
+    </button>
+  );
+}
+```
+
+The older organization-named hooks remain as deprecated compatibility aliases.
+
+## Identity Client Contracts
+
+Simple apps can configure browser-side identity endpoints:
+
+```ts
+import { configureIdentityStore } from '@eminuckan/spine/identity';
+
+configureIdentityStore({
+  contextEndpoint: '/api/identity/context',
+  permissionsEndpoint: '/api/identity/permissions',
+  logoutPath: '/auth/logout',
+});
+```
+
+Apps with different response shapes can provide functions instead:
+
+```ts
+configureIdentityStore({
+  fetchContext: async () => {
+    const response = await fetch('/session/me');
+    const payload = await response.json();
+
+    return {
+      userId: payload.user.id,
+      email: payload.user.email,
+      memberships: payload.accounts.map((account) => ({
+        tenantId: account.id,
+        tenantName: account.name,
+      })),
+    };
+  },
+  fetchPermissions: async () => {
+    const response = await fetch('/session/capabilities');
+    const payload = await response.json();
+    return payload.capabilities;
+  },
+});
+```
+
+## Try the Example
+
+```bash
+cd examples/react-router-saas
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+The example uses React Router framework mode and includes auth routes, a protected
+dashboard loader, provider wiring, and local app adapters for identity and tenant
+fetching.
+
+## Validation
+
+For library development, run:
+
+```bash
+pnpm check
+```
+
+`pnpm check` runs the public-surface guard, TypeScript, ESLint, Vitest, and the
+package build.

package/docs/module-reference.md

@@ -0,0 +1,207 @@
+# Module Reference
+
+This is a high-level reference for Spine's public surfaces.
+
+## Auth
+
+Server entry point:
+
+- `@eminuckan/spine/auth/server`
+- `@eminuckan/spine/server`
+- `@eminuckan/spine/react-router/server`
+
+Key exports:
+
+- `login`
+- `handleCallback`
+- `logout`
+- `getUser`
+- `requireAuth`
+- `getAccessToken`
+- `refreshTokens`
+- `getAuthSession`
+- `updateAuthSession`
+- `destroyAuthSession`
+- `configureAuthClaimMapping`
+- `resetAuthClaimMapping`
+- `configureRouteProtection`
+- `authRoute`
+- `protectedRoute`
+- `policyRoute`
+- `publicRoute`
+
+Deprecated compatibility aliases:
+
+- `onboardingRoute`
+- `subscriptionRoute`
+
+## Tenant
+
+Client entry point:
+
+- `@eminuckan/spine/tenant`
+
+Server entry point:
+
+- `@eminuckan/spine/tenant/server`
+
+Key client exports:
+
+- `TenantProvider`
+- `useTenant`
+- `useCurrentTenant`
+- `useCurrentTenantData`
+- `useTenantData`
+- `useTenantStore`
+- `initializeTenantStore`
+- `configureTenantClient`
+- `configureTenantEndpoints`
+- `resetTenantClientConfig`
+- `normalizeTenantDataPayload`
+- `normalizeTenantSwitchPayload`
+- `TenantData`
+- `TenantBranding`
+
+Deprecated compatibility aliases:
+
+- `useCurrentOrganization`
+- `useOrganization`
+- `OrganizationData`
+- `OrganizationBranding`
+
+Key server exports:
+
+- `configureTenantCookie`
+- `resetTenantCookieConfig`
+- `getActiveTenant`
+- `setActiveTenant`
+- `clearActiveTenant`
+- `configureTenantResolution`
+- `resetTenantResolutionConfig`
+- `configureIdentityContextFetcher`
+- `getCurrentTenant`
+- `getAvailableTenants`
+- `initializeTenant`
+- `setCurrentTenant`
+- `clearCurrentTenant`
+
+## Identity
+
+Client entry point:
+
+- `@eminuckan/spine/identity`
+
+Server entry point:
+
+- `@eminuckan/spine/identity/server`
+
+Key client exports:
+
+- `IdentityContextProvider`
+- `useIdentityStore`
+- `useIdentityContext`
+- `useIsOnboarded`
+- `useHasSubscription`
+- `useUserTenants`
+- `useUserPermissions`
+- `configureIdentityStore`
+- `configureIdentityEndpoints`
+- `resetIdentityStoreConfig`
+- `normalizeIdentityContextPayload`
+- `normalizeIdentityPermissionsPayload`
+
+Key server exports:
+
+- `configureIdentityAPIFetcher`
+- `configurePermissionFetcher`
+- `fetchIdentityContext`
+- `getIdentityContext`
+- `fetchUserPermissions`
+- `contextToUserInfo`
+- `clearIdentityContextCache`
+- `hasContextVersionChanged`
+- `updateContextVersion`
+
+## Permissions
+
+Client entry point:
+
+- `@eminuckan/spine/permissions`
+
+Server entry point:
+
+- `@eminuckan/spine/server`
+
+Key client exports:
+
+- `usePermissionStore`
+- `initializePermissions`
+- `getPermissionChecker`
+- `getPermissions`
+- `usePermission`
+- `useHasPermission`
+- `usePermissions`
+- `useHasPermissions`
+- `useModulePermission`
+- `useHasModulePermission`
+- `usePermissionChecker`
+- `useAllPermissions`
+- `ProtectedButton`
+- `ProtectedLink`
+- `ProtectedSection`
+- `ProtectedAction`
+
+Key server exports:
+
+- `configurePermissionRouteProtection`
+- `resetPermissionRouteProtection`
+- `requirePermission`
+- `checkPermission`
+- `withPermission`
+
+## API Client
+
+Client entry point:
+
+- `@eminuckan/spine/api-client`
+
+Server entry point:
+
+- `@eminuckan/spine/api-client/server`
+
+Key server exports:
+
+- `createAPIConfigFactory`
+- `createFetchMiddleware`
+- `createApiClient`
+- `APIConfigFactoryOptions`
+- `APIHeaderStrategyContext`
+
+## Query Client
+
+Entry point:
+
+- `@eminuckan/spine/query-client`
+
+Key exports:
+
+- `createQueryClient`
+- `cachePresets`
+- `createQueryKeyFactory`
+- `invalidationHelpers`
+
+## Logging
+
+Entry point:
+
+- `@eminuckan/spine/logging`
+
+The logging module provides typed logger configuration and a default service-level logger.
+
+## SignalR
+
+Entry point:
+
+- `@eminuckan/spine/signalr`
+
+Use this module for generic realtime client helpers and types.

package/docs/releasing.md

@@ -0,0 +1,92 @@
+# Releasing Spine
+
+This guide covers local validation, GitHub release setup, and npm publishing.
+
+## Before Releasing
+
+Run:
+
+```bash
+pnpm install
+pnpm check
+npm pack --dry-run
+```
+
+Review:
+
+- `README.md`
+- `package.json`
+- `CHANGELOG.md`
+- `README.md`
+- `ROADMAP.md`
+
+## Versioning
+
+Update the version in `package.json` and add a changelog entry.
+
+## GitHub Repository
+
+If the repository does not exist yet:
+
+```bash
+gh repo create eminuckan/spine --public --source=. --remote=origin --push
+```
+
+Useful follow-up commands:
+
+```bash
+gh repo edit eminuckan/spine --description "Framework-agnostic SaaS primitives for auth, identity, multi-tenancy, permissions, and API access."
+gh repo edit eminuckan/spine --homepage "https://github.com/eminuckan/spine#readme"
+```
+
+## npm Publishing
+
+You need npm authentication on the machine for manual publishing, or npm trusted publishing configured for GitHub Actions.
+
+Manual publish:
+
+```bash
+npm publish --access public
+```
+
+Dry run:
+
+```bash
+npm publish --dry-run
+```
+
+## GitHub Actions Release Workflow
+
+The repository includes a release workflow that expects npm trusted publishing to be configured for the `npm-publish` GitHub environment.
+
+Recommended tag format:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+## Release Checklist
+
+- Version updated
+- Changelog updated
+- Docs updated
+- `pnpm check` passes
+- `npm pack --dry-run` includes only intended files
+- GitHub repo is public
+- npm auth is available
+- Publish succeeds
+
+## Troubleshooting
+
+### `npm whoami` fails
+
+You are not authenticated with npm on the current machine.
+
+### `npm view @eminuckan/spine version` returns 404
+
+The package is not currently published or the scope/package name is unavailable to the current user.
+
+### GitHub push fails because the repo does not exist
+
+Create the repository first with `gh repo create`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eminuckan/spine",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Framework-agnostic SaaS primitives for auth, identity, multi-tenancy, permissions, and API access.",
   "type": "module",
   "main": "./dist/index.js",
@@ -80,8 +80,14 @@
   },
   "files": [
     "dist",
+    "docs",
     "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
     "README.md",
+    "MAINTAINERS.md",
+    "ROADMAP.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
@@ -89,12 +95,23 @@
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --max-warnings 0",
-    "prepublishOnly": "pnpm run build"
+    "test": "vitest run",
+    "check:public-surface": "node scripts/check-public-surface.mjs",
+    "check": "pnpm run check:public-surface && pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build",
+    "prepublishOnly": "pnpm run check"
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",
     "react": ">=18.0.0"
   },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@microsoft/signalr": "^9.0.0",
     "ioredis": "^5.4.1",
@@ -110,7 +127,8 @@
     "globals": "^17.4.0",
     "tsdown": "^0.9.0",
     "typescript": "^5.7.0",
-    "typescript-eslint": "^8.57.0"
+    "typescript-eslint": "^8.57.0",
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=20.0.0"

package/dist/access-DlAqsVGQ.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"access-DlAqsVGQ.js","names":["EMPTY_DECISION: AccessDecision","value: string","subscription?: SubscriptionAccessSnapshot | null","grantedFeatures: readonly string[]","requiredFeatures: readonly string[]","operator: AccessOperator","requirement: AccessRequirement | null | undefined","subject: AccessSubject","reasons: AccessDeniedReason[]","missingPermissions: string[]","missingFeatures: string[]"],"sources":["../src/access/evaluator.ts"],"sourcesContent":["import { PermissionChecker } from '../permissions/permission-service';\nimport type {\n  AccessDecision,\n  AccessDeniedReason,\n  AccessOperator,\n  AccessRequirement,\n  AccessSubject,\n  SubscriptionAccessSnapshot,\n} from './types';\n\nconst ACTIVE_SUBSCRIPTION_STATUSES = new Set(['active', 'trialing']);\n\nconst EMPTY_DECISION: AccessDecision = Object.freeze({\n  allowed: true,\n  reasons: [],\n  missingPermissions: [],\n  missingFeatures: [],\n});\n\nfunction normalizeFeature(value: string): string {\n  return value.trim().toLowerCase();\n}\n\nfunction hasActiveSubscription(subscription?: SubscriptionAccessSnapshot | null): boolean {\n  if (!subscription?.exists) {\n    return false;\n  }\n\n  return ACTIVE_SUBSCRIPTION_STATUSES.has(subscription.status?.toLowerCase() ?? '');\n}\n\nfunction checkFeatureSet(\n  grantedFeatures: readonly string[],\n  requiredFeatures: readonly string[],\n  operator: AccessOperator,\n): string[] {\n  if (requiredFeatures.length === 0) {\n    return [];\n  }\n\n  const granted = new Set(grantedFeatures.map(normalizeFeature));\n  const normalizedRequired = requiredFeatures.map(normalizeFeature).filter(Boolean);\n\n  if (operator === 'OR') {\n    return normalizedRequired.some((feature) => granted.has(feature)) ? [] : normalizedRequired;\n  }\n\n  return normalizedRequired.filter((feature) => !granted.has(feature));\n}\n\nexport function evaluateAccessRequirement(\n  requirement: AccessRequirement | null | undefined,\n  subject: AccessSubject,\n): AccessDecision {\n  if (!requirement) {\n    return EMPTY_DECISION;\n  }\n\n  const reasons: AccessDeniedReason[] = [];\n  const permissions = requirement.permissions ?? [];\n  const features = requirement.features ?? [];\n  let missingPermissions: string[] = [];\n  let missingFeatures: string[] = [];\n\n  if (requirement.internalOnly && !subject.isInternalUser) {\n    reasons.push('internal-only');\n  }\n\n  if (requirement.requireActiveSubscription && !hasActiveSubscription(subject.subscription)) {\n    reasons.push('inactive-subscription');\n  }\n\n  if (permissions.length > 0) {\n    const checker = new PermissionChecker([...(subject.permissions ?? [])]);\n    const result = checker.hasPermissions([...permissions], {\n      operator: requirement.permissionOperator ?? 'AND',\n      wildcard: true,\n    });\n\n    if (!result.hasPermission) {\n      missingPermissions = result.missingPermissions;\n      reasons.push('missing-permissions');\n    }\n  }\n\n  if (features.length > 0) {\n    missingFeatures = checkFeatureSet(\n      subject.subscription?.featureKeys ?? [],\n      features,\n      requirement.featureOperator ?? 'AND',\n    );\n\n    if (missingFeatures.length > 0) {\n      reasons.push('missing-features');\n    }\n  }\n\n  return {\n    allowed: reasons.length === 0,\n    reasons,\n    missingPermissions,\n    missingFeatures,\n  };\n}\n"],"mappings":";;;AAUA,MAAM,+BAA+B,IAAI,IAAI,CAAC,UAAU,UAAW;AAEnE,MAAMA,iBAAiC,OAAO,OAAO;CACnD,SAAS;CACT,SAAS,CAAE;CACX,oBAAoB,CAAE;CACtB,iBAAiB,CAAE;AACpB,EAAC;AAEF,SAAS,iBAAiBC,OAAuB;AAC/C,QAAO,MAAM,MAAM,CAAC,aAAa;AAClC;AAED,SAAS,sBAAsBC,cAA2D;AACxF,MAAK,cAAc,OACjB,QAAO;AAGT,QAAO,6BAA6B,IAAI,aAAa,QAAQ,aAAa,IAAI,GAAG;AAClF;AAED,SAAS,gBACPC,iBACAC,kBACAC,UACU;AACV,KAAI,iBAAiB,WAAW,EAC9B,QAAO,CAAE;CAGX,MAAM,UAAU,IAAI,IAAI,gBAAgB,IAAI,iBAAiB;CAC7D,MAAM,qBAAqB,iBAAiB,IAAI,iBAAiB,CAAC,OAAO,QAAQ;AAEjF,KAAI,aAAa,KACf,QAAO,mBAAmB,KAAK,CAAC,YAAY,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAE,IAAG;AAG3E,QAAO,mBAAmB,OAAO,CAAC,aAAa,QAAQ,IAAI,QAAQ,CAAC;AACrE;AAED,SAAgB,0BACdC,aACAC,SACgB;AAChB,MAAK,YACH,QAAO;CAGT,MAAMC,UAAgC,CAAE;CACxC,MAAM,cAAc,YAAY,eAAe,CAAE;CACjD,MAAM,WAAW,YAAY,YAAY,CAAE;CAC3C,IAAIC,qBAA+B,CAAE;CACrC,IAAIC,kBAA4B,CAAE;AAElC,KAAI,YAAY,iBAAiB,QAAQ,eACvC,SAAQ,KAAK,gBAAgB;AAG/B,KAAI,YAAY,8BAA8B,sBAAsB,QAAQ,aAAa,CACvF,SAAQ,KAAK,wBAAwB;AAGvC,KAAI,YAAY,SAAS,GAAG;EAC1B,MAAM,UAAU,IAAI,kBAAkB,CAAC,GAAI,QAAQ,eAAe,CAAE,CAAE;EACtE,MAAM,SAAS,QAAQ,eAAe,CAAC,GAAG,WAAY,GAAE;GACtD,UAAU,YAAY,sBAAsB;GAC5C,UAAU;EACX,EAAC;AAEF,OAAK,OAAO,eAAe;AACzB,wBAAqB,OAAO;AAC5B,WAAQ,KAAK,sBAAsB;EACpC;CACF;AAED,KAAI,SAAS,SAAS,GAAG;AACvB,oBAAkB,gBAChB,QAAQ,cAAc,eAAe,CAAE,GACvC,UACA,YAAY,mBAAmB,MAChC;AAED,MAAI,gBAAgB,SAAS,EAC3B,SAAQ,KAAK,mBAAmB;CAEnC;AAED,QAAO;EACL,SAAS,QAAQ,WAAW;EAC5B;EACA;EACA;CACD;AACF"}

package/dist/api-client-CZapXIF8.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"api-client-CZapXIF8.js","names":["problemDetails: ProblemDetails","response: Response","config: ErrorHandlerConfig","error: ApiError","message: string","type: 'error' | 'success' | 'info'","DEFAULT_RETRY_CONFIG: Required<RetryConfig>","error: unknown","attempt: number","baseDelay: number","maxDelay: number","fn: () => Promise<T>","config?: RetryConfig","lastError: unknown","input: RequestInfo | URL","init?: RequestInit & { timeout?: number }","init?: RequestInit"],"sources":["../src/api-client/error-codes.ts","../src/api-client/error-handler.ts","../src/api-client/retry-handler.ts"],"sourcesContent":["/**\n * Error Codes\n * \n * Standard error codes from backend.\n */\n\nexport const ErrorCodes = {\n  // Validation\n  Validation: {\n    Failed: 'ValidationFailed',\n  },\n\n  // Identity\n  Identity: {\n    InvalidCredentials: 'InvalidCredentials',\n    UserInactive: 'UserInactive',\n    TenantContextMissing: 'TenantContextMissing',\n    InvalidCurrentPassword: 'InvalidCurrentPassword',\n    OwnerCannotDisableMembership: 'OwnerCannotDisableMembership',\n    CurrentUserMissing: 'CurrentUserMissing',\n    UserNotFound: 'UserNotFound',\n    EmailAlreadyExists: 'EmailAlreadyExists',\n  },\n\n  // Accounting\n  Accounting: {\n    OpeningBalanceLockedReconciliation: 'OpeningBalanceLockedReconciliation',\n    OpeningBalanceLockedJournal: 'OpeningBalanceLockedJournal',\n    SystemLocked: 'SystemLocked',\n    AccountsDuplicate: 'AccountsDuplicate',\n    AccountNotFound: 'AccountNotFound',\n  },\n\n  // Subscription\n  Subscription: {\n    SubscriptionRequired: 'SubscriptionRequired',\n    SubscriptionExpired: 'SubscriptionExpired',\n    FeatureNotAvailable: 'FeatureNotAvailable',\n  },\n\n  // Property Management\n  PropertyManagement: {\n    PropertyNotFound: 'PropertyNotFound',\n    UnitNotFound: 'UnitNotFound',\n    DuplicateProperty: 'DuplicateProperty',\n    DuplicateUnit: 'DuplicateUnit',\n  },\n\n  // Leasing\n  Leasing: {\n    LeaseNotFound: 'LeaseNotFound',\n    LeaseConflict: 'LeaseConflict',\n    TenantNotFound: 'TenantNotFound',\n    LateFeeValidationError: 'LateFeeValidationError',\n  },\n\n  // General\n  NotFound: 'NotFound',\n  Unauthorized: 'Unauthorized',\n  Forbidden: 'Forbidden',\n  InternalError: 'InternalError',\n} as const;\n\n/**\n * Check if error code is from PropertyManagement module\n */\nexport function isPropertyManagementError(code: string): boolean {\n  return Object.values(ErrorCodes.PropertyManagement).includes(code as any);\n}\n\n/**\n * Check if error code is from Leasing module\n */\nexport function isLeasingError(code: string): boolean {\n  return Object.values(ErrorCodes.Leasing).includes(code as any);\n}\n","/**\n * Error Handler\n * \n * Centralized error handling with ProblemDetails parsing.\n */\n\nimport type { ProblemDetails, ValidationError } from './types';\nimport { ErrorCodes } from './error-codes';\nimport { logger } from '../logging';\n\n/**\n * API Error Class\n */\nexport class ApiError extends Error {\n  constructor(\n    public problemDetails: ProblemDetails,\n    public response: Response\n  ) {\n    super(problemDetails.detail);\n    this.name = 'ApiError';\n  }\n\n  get code(): string {\n    return this.problemDetails.title;\n  }\n\n  get status(): number {\n    return this.problemDetails.status;\n  }\n\n  get isValidationError(): boolean {\n    return this.code === ErrorCodes.Validation.Failed;\n  }\n\n  get validationErrors(): ValidationError[] {\n    return this.problemDetails.meta?.errors ?? [];\n  }\n\n  get traceId(): string {\n    return this.problemDetails.traceId;\n  }\n}\n\n/**\n * Parse API error response\n */\nexport async function handleApiError(response: Response): Promise<never> {\n  let problemDetails: ProblemDetails;\n\n  try {\n    problemDetails = await response.json();\n  } catch {\n    problemDetails = {\n      type: `https://httpstatuses.com/${response.status}`,\n      title: 'UnknownError',\n      status: response.status,\n      detail: response.statusText || 'An unknown error occurred',\n      traceId: response.headers.get('x-trace-id') ?? 'unknown',\n    };\n  }\n\n  logger.error('API request failed', undefined, {\n    code: problemDetails.title,\n    status: problemDetails.status,\n    detail: problemDetails.detail,\n    traceId: problemDetails.traceId,\n  });\n\n  throw new ApiError(problemDetails, response);\n}\n\n/**\n * Error Handler Configuration\n */\nexport interface ErrorHandlerConfig {\n  handlers?: Partial<Record<string, (error: ApiError) => void>>;\n  showToast?: boolean;\n  toastMessages?: Partial<Record<string, string>>;\n  onError?: (error: ApiError) => void;\n  toast?: (message: string, type: 'error' | 'success' | 'info') => void;\n}\n\n/**\n * Error Handler Class\n */\nexport class ErrorHandler {\n  private config: ErrorHandlerConfig;\n\n  constructor(config: ErrorHandlerConfig = {}) {\n    this.config = {\n      showToast: true,\n      ...config,\n    };\n  }\n\n  handle(error: ApiError): void {\n    const code = error.code;\n\n    logger.error('Handling API Error', undefined, {\n      code,\n      status: error.status,\n      traceId: error.traceId,\n    });\n\n    // Try custom handler first\n    if (this.config.handlers?.[code]) {\n      this.config.handlers[code]!(error);\n      return;\n    }\n\n    // Fallback\n    if (this.config.onError) {\n      this.config.onError(error);\n    } else {\n      this.showDefaultToast(error);\n    }\n  }\n\n  private showToast(message: string, type: 'error' | 'success' | 'info'): void {\n    if (this.config.showToast && this.config.toast) {\n      this.config.toast(message, type);\n    }\n  }\n\n  private showDefaultToast(error: ApiError): void {\n    const message =\n      this.config.toastMessages?.[error.code] ||\n      error.problemDetails.detail ||\n      'An error occurred';\n    this.showToast(message, 'error');\n  }\n}\n\n/**\n * Create global error handler\n */\nexport function createErrorHandler(config?: ErrorHandlerConfig): ErrorHandler {\n  return new ErrorHandler(config);\n}\n\n/**\n * Map validation errors to form fields\n */\nexport function mapValidationErrors(errors: ValidationError[]): Record<string, string> {\n  const mapped: Record<string, string> = {};\n  for (const error of errors) {\n    const fieldName = error.field.charAt(0).toLowerCase() + error.field.slice(1);\n    mapped[fieldName] = error.message;\n  }\n  return mapped;\n}\n","/**\n * Retry Handler\n * \n * Retry logic for API requests.\n */\n\nimport type { RetryConfig } from './types';\n\nconst DEFAULT_RETRY_CONFIG: Required<RetryConfig> = {\n  maxRetries: 3,\n  baseDelay: 1000,\n  maxDelay: 10000,\n  retryCondition: (error: unknown) => {\n    if (error instanceof Response) {\n      return error.status >= 500 || error.status === 429;\n    }\n    return false;\n  },\n};\n\n/**\n * Calculate backoff delay\n */\nexport function calculateBackoffDelay(\n  attempt: number,\n  baseDelay: number,\n  maxDelay: number\n): number {\n  const delay = baseDelay * Math.pow(2, attempt);\n  const jitter = Math.random() * 0.3 * delay;\n  return Math.min(delay + jitter, maxDelay);\n}\n\n/**\n * Check if error is retryable\n */\nexport function isRetryableError(error: unknown): boolean {\n  if (error instanceof Response) {\n    return error.status >= 500 || error.status === 429;\n  }\n  if (error instanceof TypeError) {\n    // Network errors\n    return true;\n  }\n  return false;\n}\n\n/**\n * Execute function with retry logic\n */\nexport async function withRetry<T>(\n  fn: () => Promise<T>,\n  config?: RetryConfig\n): Promise<T> {\n  const { maxRetries, baseDelay, maxDelay, retryCondition } = {\n    ...DEFAULT_RETRY_CONFIG,\n    ...config,\n  };\n\n  let lastError: unknown;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      return await fn();\n    } catch (error) {\n      lastError = error;\n\n      if (attempt === maxRetries || !retryCondition(error)) {\n        throw error;\n      }\n\n      const delay = calculateBackoffDelay(attempt, baseDelay, maxDelay);\n      console.log(`Retry attempt ${attempt + 1}/${maxRetries} after ${delay}ms`);\n      await new Promise((resolve) => setTimeout(resolve, delay));\n    }\n  }\n\n  throw lastError;\n}\n\n/**\n * Fetch with timeout\n */\nexport async function fetchWithTimeout(\n  input: RequestInfo | URL,\n  init?: RequestInit & { timeout?: number }\n): Promise<Response> {\n  const { timeout = 30000, ...fetchInit } = init || {};\n\n  const controller = new AbortController();\n  const timeoutId = setTimeout(() => controller.abort(), timeout);\n\n  try {\n    const response = await fetch(input, {\n      ...fetchInit,\n      signal: controller.signal,\n    });\n    return response;\n  } finally {\n    clearTimeout(timeoutId);\n  }\n}\n\n/**\n * Create fetch function with retry\n */\nexport function createRetryFetch(config?: RetryConfig) {\n  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {\n    return withRetry(() => fetch(input, init), config);\n  };\n}\n"],"mappings":";;;;;;;;AAMA,MAAa,aAAa;CAExB,YAAY,EACV,QAAQ,mBACT;CAGD,UAAU;EACR,oBAAoB;EACpB,cAAc;EACd,sBAAsB;EACtB,wBAAwB;EACxB,8BAA8B;EAC9B,oBAAoB;EACpB,cAAc;EACd,oBAAoB;CACrB;CAGD,YAAY;EACV,oCAAoC;EACpC,6BAA6B;EAC7B,cAAc;EACd,mBAAmB;EACnB,iBAAiB;CAClB;CAGD,cAAc;EACZ,sBAAsB;EACtB,qBAAqB;EACrB,qBAAqB;CACtB;CAGD,oBAAoB;EAClB,kBAAkB;EAClB,cAAc;EACd,mBAAmB;EACnB,eAAe;CAChB;CAGD,SAAS;EACP,eAAe;EACf,eAAe;EACf,gBAAgB;EAChB,wBAAwB;CACzB;CAGD,UAAU;CACV,cAAc;CACd,WAAW;CACX,eAAe;AAChB;;;;;;;AChDD,IAAa,WAAb,cAA8B,MAAM;CAClC,YACSA,gBACAC,UACP;AACA,QAAM,eAAe,OAAO;EAqI/B,KAxIU;EAwIT,KAvIS;AAGP,OAAK,OAAO;CACb;CAED,IAAI,OAAe;AACjB,SAAO,KAAK,eAAe;CAC5B;CAED,IAAI,SAAiB;AACnB,SAAO,KAAK,eAAe;CAC5B;CAED,IAAI,oBAA6B;AAC/B,SAAO,KAAK,SAAS,WAAW,WAAW;CAC5C;CAED,IAAI,mBAAsC;AACxC,SAAO,KAAK,eAAe,MAAM,UAAU,CAAE;CAC9C;CAED,IAAI,UAAkB;AACpB,SAAO,KAAK,eAAe;CAC5B;AACF;;;;AAKD,eAAsB,eAAeA,UAAoC;CACvE,IAAID;AAEJ,KAAI;AACF,mBAAiB,MAAM,SAAS,MAAM;CACvC,QAAO;AACN,mBAAiB;GACf,OAAO,2BAA2B,SAAS,OAAO;GAClD,OAAO;GACP,QAAQ,SAAS;GACjB,QAAQ,SAAS,cAAc;GAC/B,SAAS,SAAS,QAAQ,IAAI,aAAa,IAAI;EAChD;CACF;AAED,QAAO,MAAM,8BAAiC;EAC5C,MAAM,eAAe;EACrB,QAAQ,eAAe;EACvB,QAAQ,eAAe;EACvB,SAAS,eAAe;CACzB,EAAC;AAEF,OAAM,IAAI,SAAS,gBAAgB;AACpC;;;;AAgBD,IAAa,eAAb,MAA0B;CACxB,AAAQ;CAER,YAAYE,SAA6B,CAAE,GAAE;AAC3C,OAAK,SAAS;GACZ,WAAW;GACX,GAAG;EACJ;CACF;CAED,OAAOC,OAAuB;EAC5B,MAAM,OAAO,MAAM;AAEnB,SAAO,MAAM,8BAAiC;GAC5C;GACA,QAAQ,MAAM;GACd,SAAS,MAAM;EAChB,EAAC;AAGF,MAAI,KAAK,OAAO,WAAW,OAAO;AAChC,QAAK,OAAO,SAAS,MAAO,MAAM;AAClC;EACD;AAGD,MAAI,KAAK,OAAO,QACd,MAAK,OAAO,QAAQ,MAAM;MAE1B,MAAK,iBAAiB,MAAM;CAE/B;CAED,AAAQ,UAAUC,SAAiBC,MAA0C;AAC3E,MAAI,KAAK,OAAO,aAAa,KAAK,OAAO,MACvC,MAAK,OAAO,MAAM,SAAS,KAAK;CAEnC;CAED,AAAQ,iBAAiBF,OAAuB;EAC9C,MAAM,UACJ,KAAK,OAAO,gBAAgB,MAAM,SAClC,MAAM,eAAe,UACrB;AACF,OAAK,UAAU,SAAS,QAAQ;CACjC;AACF;;;;AC3HD,MAAMG,uBAA8C;CAClD,YAAY;CACZ,WAAW;CACX,UAAU;CACV,gBAAgB,CAACC,UAAmB;AAClC,MAAI,iBAAiB,SACnB,QAAO,MAAM,UAAU,OAAO,MAAM,WAAW;AAEjD,SAAO;CACR;AACF;;;;AAKD,SAAgB,sBACdC,SACAC,WACAC,UACQ;CACR,MAAM,QAAQ,YAAY,KAAK,IAAI,GAAG,QAAQ;CAC9C,MAAM,SAAS,KAAK,QAAQ,GAAG,KAAM;AACrC,QAAO,KAAK,IAAI,QAAQ,QAAQ,SAAS;AAC1C;;;;AAKD,SAAgB,iBAAiBH,OAAyB;AACxD,KAAI,iBAAiB,SACnB,QAAO,MAAM,UAAU,OAAO,MAAM,WAAW;AAEjD,KAAI,iBAAiB,UAEnB,QAAO;AAET,QAAO;AACR;;;;AAKD,eAAsB,UACpBI,IACAC,QACY;CACZ,MAAM,EAAE,YAAY,WAAW,UAAU,gBAAgB,GAAG;EAC1D,GAAG;EACH,GAAG;CACJ;CAED,IAAIC;AAEJ,MAAK,IAAI,UAAU,GAAG,WAAW,YAAY,UAC3C,KAAI;AACF,SAAO,MAAM,IAAI;CAClB,SAAQ,OAAO;AACd,cAAY;AAEZ,MAAI,YAAY,eAAe,eAAe,MAAM,CAClD,OAAM;EAGR,MAAM,QAAQ,sBAAsB,SAAS,WAAW,SAAS;AACjE,UAAQ,KAAK,gBAAgB,UAAU,EAAE,GAAG,WAAW,SAAS,MAAM,IAAI;AAC1E,QAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,MAAM;CAC1D;AAGH,OAAM;AACP;;;;AAKD,eAAsB,iBACpBC,OACAC,MACmB;CACnB,MAAM,EAAE,UAAU,IAAO,GAAG,WAAW,GAAG,QAAQ,CAAE;CAEpD,MAAM,aAAa,IAAI;CACvB,MAAM,YAAY,WAAW,MAAM,WAAW,OAAO,EAAE,QAAQ;AAE/D,KAAI;EACF,MAAM,WAAW,MAAM,MAAM,OAAO;GAClC,GAAG;GACH,QAAQ,WAAW;EACpB,EAAC;AACF,SAAO;CACR,UAAS;AACR,eAAa,UAAU;CACxB;AACF;;;;AAKD,SAAgB,iBAAiBH,QAAsB;AACrD,QAAO,OAAOE,OAA0BE,SAA0C;AAChF,SAAO,UAAU,MAAM,MAAM,OAAO,KAAK,EAAE,OAAO;CACnD;AACF"}