@notur/sdk 1.4.6 → 1.5.3

package/bin/notur-validate.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('yaml');
+
+const KNOWN_SLOTS = new Set([
+    'navbar', 'navbar.left', 'navbar.before', 'navbar.after',
+    'server.subnav', 'server.subnav.before', 'server.subnav.after', 'server.header', 'server.page', 'server.footer',
+    'server.terminal.buttons', 'server.console.header', 'server.console.info.before', 'server.console.info.after',
+    'server.console.sidebar', 'server.console.command', 'server.console.footer', 'server.files.actions',
+    'server.files.header', 'server.files.footer', 'server.files.dropdown', 'server.files.edit.before',
+    'server.files.edit.after', 'server.databases.before', 'server.databases.after', 'server.schedules.before',
+    'server.schedules.after', 'server.schedules.edit.before', 'server.schedules.edit.after', 'server.users.before',
+    'server.users.after', 'server.backups.before', 'server.backups.after', 'server.backups.dropdown',
+    'server.network.before', 'server.network.after', 'server.startup.before', 'server.startup.after',
+    'server.settings.before', 'server.settings.after', 'dashboard.header', 'dashboard.widgets',
+    'dashboard.serverlist.before', 'dashboard.serverlist.after', 'dashboard.serverrow.name.before',
+    'dashboard.serverrow.name.after', 'dashboard.serverrow.description.before', 'dashboard.serverrow.description.after',
+    'dashboard.serverrow.limits', 'dashboard.footer', 'dashboard.page', 'account.header', 'account.page',
+    'account.footer', 'account.subnav', 'account.subnav.before', 'account.subnav.after',
+    'account.overview.before', 'account.overview.after', 'account.api.before', 'account.api.after',
+    'account.ssh.before', 'account.ssh.after', 'auth.container.before', 'auth.container.after',
+]);
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = { path: '.', strict: false };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--strict') {
+            options.strict = true;
+        } else if (arg === '--help' || arg === '-h') {
+            usage(0);
+        } else if (!arg.startsWith('-')) {
+            options.path = arg;
+        } else {
+            console.error(`Unknown argument: ${arg}`);
+            usage(1);
+        }
+    }
+    return options;
+}
+
+function usage(code) {
+    console.log(`Usage:
+  npx notur-validate [path]
+  npx @notur/sdk validate [path]
+
+Options:
+  --strict   Treat warnings as errors`);
+    process.exit(code);
+}
+
+function readManifest(basePath, result) {
+    const manifestPath = ['extension.yaml', 'extension.yml']
+        .map(file => path.join(basePath, file))
+        .find(file => fs.existsSync(file));
+    if (!manifestPath) {
+        result.errors.push('extension.yaml not found.');
+        return null;
+    }
+
+    try {
+        return yaml.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (error) {
+        result.errors.push(`extension.yaml could not be parsed: ${error.message}`);
+        return null;
+    }
+}
+
+function validateManifest(basePath, manifest, result) {
+    if (!manifest) return;
+
+    for (const field of ['id', 'name', 'version']) {
+        if (!manifest[field]) {
+            result.errors.push(`extension.yaml is missing required field: ${field}`);
+        }
+    }
+
+    if (manifest.id && !/^[a-z0-9-]+\/[a-z0-9-]+$/.test(manifest.id)) {
+        result.errors.push(`extension id "${manifest.id}" must use vendor/name with lowercase letters, numbers, and hyphens.`);
+    }
+
+    if (manifest.frontend?.bundle) {
+        const bundlePath = path.join(basePath, manifest.frontend.bundle);
+        if (!fs.existsSync(bundlePath)) {
+            result.warnings.push(`frontend.bundle does not exist yet: ${manifest.frontend.bundle}. Run your build before packaging.`);
+        }
+    }
+
+    const routes = manifest.backend?.routes;
+    if (routes && typeof routes === 'object') {
+        for (const [group, routeFile] of Object.entries(routes)) {
+            if (typeof routeFile !== 'string') {
+                result.errors.push(`backend.routes.${group} must be a string path.`);
+                continue;
+            }
+            if (!fs.existsSync(path.join(basePath, routeFile))) {
+                result.errors.push(`backend.routes.${group} points to missing file: ${routeFile}`);
+            }
+        }
+    }
+}
+
+function readPackage(basePath, result) {
+    const packagePath = path.join(basePath, 'package.json');
+    if (!fs.existsSync(packagePath)) {
+        return null;
+    }
+    try {
+        return JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+    } catch (error) {
+        result.errors.push(`package.json could not be parsed: ${error.message}`);
+        return null;
+    }
+}
+
+function validatePackage(manifest, pkg, result) {
+    if (!manifest || !pkg) return;
+
+    const expectedName = manifest.id?.replace('/', '-');
+    if (expectedName && pkg.name && pkg.name !== expectedName) {
+        result.warnings.push(`package.json name "${pkg.name}" differs from manifest-derived "${expectedName}". Run npx notur-sync.`);
+    }
+
+    if (manifest.version && pkg.version && pkg.version !== manifest.version) {
+        result.warnings.push(`package.json version "${pkg.version}" differs from extension.yaml version "${manifest.version}". Run npx notur-sync.`);
+    }
+
+    for (const script of ['build', 'pack', 'push', 'sync']) {
+        if (!pkg.scripts?.[script]) {
+            result.warnings.push(`package.json is missing "${script}" script.`);
+        }
+    }
+}
+
+function validateFrontendSource(basePath, manifest, result) {
+    const indexPath = path.join(basePath, 'resources/frontend/src/index.tsx');
+    if (!fs.existsSync(indexPath)) {
+        if (manifest?.frontend) {
+            result.warnings.push('frontend is configured but resources/frontend/src/index.tsx was not found.');
+        }
+        return;
+    }
+
+    const source = fs.readFileSync(indexPath, 'utf8');
+    if (!source.includes('createExtension')) {
+        result.warnings.push('frontend entry does not appear to call createExtension().');
+    }
+
+    if (manifest?.id && !source.includes(manifest.id)) {
+        result.warnings.push(`frontend entry does not appear to reference manifest id "${manifest.id}".`);
+    }
+
+    const slotMatches = source.matchAll(/slot:\s*['"`]([^'"`]+)['"`]/g);
+    for (const match of slotMatches) {
+        if (!KNOWN_SLOTS.has(match[1])) {
+            result.warnings.push(`unknown slot id "${match[1]}". Check docs/slot-reference.md or SDK SlotId.`);
+        }
+    }
+}
+
+function printResult(result, strict) {
+    for (const warning of result.warnings) {
+        console.warn(`warning: ${warning}`);
+    }
+    for (const error of result.errors) {
+        console.error(`error: ${error}`);
+    }
+
+    const failed = result.errors.length > 0 || (strict && result.warnings.length > 0);
+    if (failed) {
+        console.error(`Notur validation failed (${result.errors.length} errors, ${result.warnings.length} warnings).`);
+        process.exit(1);
+    }
+
+    console.log(`Notur validation passed (${result.warnings.length} warnings).`);
+}
+
+function main() {
+    const options = parseArgs();
+    const basePath = path.resolve(options.path);
+    const result = { errors: [], warnings: [] };
+
+    if (!fs.existsSync(basePath) || !fs.statSync(basePath).isDirectory()) {
+        result.errors.push(`path does not exist or is not a directory: ${basePath}`);
+        printResult(result, options.strict);
+        return;
+    }
+
+    const manifest = readManifest(basePath, result);
+    validateManifest(basePath, manifest, result);
+    const pkg = readPackage(basePath, result);
+    validatePackage(manifest, pkg, result);
+    validateFrontendSource(basePath, manifest, result);
+    printResult(result, options.strict);
+}
+
+main();

package/bin/notur.js

@@ -8,6 +8,9 @@ const commands = {
     pack: 'notur-pack.js',
     keygen: 'notur-keygen.js',
     push: 'notur-push.js',
+    sync: 'notur-sync.js',
+    validate: 'notur-validate.js',
+    doctor: 'notur-doctor.js',
 };
 
 const [command, ...args] = process.argv.slice(2);
@@ -19,10 +22,13 @@ Usage:
   notur create <vendor/name> [options]
   notur pack [path] [options]
   notur push [path] --host <url> --key <token>
+  notur sync [path]
+  notur validate [path]
+  notur doctor [path]
   notur keygen
 
 Standalone bins are also available:
-  notur-create, notur-pack, notur-push, notur-keygen`);
+  notur-create, notur-pack, notur-push, notur-sync, notur-validate, notur-doctor, notur-keygen`);
     process.exit(command ? 0 : 1);
 }
 

package/dist/events.d.ts

@@ -1,6 +1,9 @@
 export interface ScopedEventChannel {
+    /** Convert a local event name into the fully scoped global event name. */
     eventName: (name: string) => string;
+    /** Emit a scoped event with optional payload data. */
     emit: (name: string, data?: unknown) => void;
+    /** Subscribe to a scoped event. Returns an unsubscribe function. */
     on: (name: string, callback: (data?: unknown) => void) => () => void;
 }
 /**
@@ -8,6 +11,13 @@ export interface ScopedEventChannel {
  *
  * This avoids accidental collisions in global event names by scoping
  * all events to `ext:<extensionId>:<event>`.
+ *
+ * @example
+ * ```ts
+ * const channel = createScopedEventChannel('acme/tools');
+ * channel.emit('saved', { id: 1 });
+ * channel.on('saved', data => console.log(data));
+ * ```
  */
 export declare function createScopedEventChannel(extensionId: string): ScopedEventChannel;
 //# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IAC/B,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACxE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAchF"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IAC/B,0EAA0E;IAC1E,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,sDAAsD;IACtD,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,oEAAoE;IACpE,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,CAchF"}

package/dist/events.js

@@ -4,6 +4,13 @@ import { getNoturApi } from './types';
  *
  * This avoids accidental collisions in global event names by scoping
  * all events to `ext:<extensionId>:<event>`.
+ *
+ * @example
+ * ```ts
+ * const channel = createScopedEventChannel('acme/tools');
+ * channel.emit('saved', { id: 1 });
+ * channel.on('saved', data => console.log(data));
+ * ```
  */
 export function createScopedEventChannel(extensionId) {
     const api = getNoturApi();

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQtC;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IACxD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAE1B,MAAM,SAAS,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,OAAO,WAAW,IAAI,IAAI,EAAE,CAAC;IAEzE,OAAO;QACH,SAAS;QACT,IAAI,EAAE,CAAC,IAAY,EAAE,IAAc,EAAQ,EAAE;YACzC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QAClD,CAAC;QACD,EAAE,EAAE,CAAC,IAAY,EAAE,QAAkC,EAAgB,EAAE;YACnE,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC3D,CAAC;KACJ,CAAC;AACN,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAWtC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IACxD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAE1B,MAAM,SAAS,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,OAAO,WAAW,IAAI,IAAI,EAAE,CAAC;IAEzE,OAAO;QACH,SAAS;QACT,IAAI,EAAE,CAAC,IAAY,EAAE,IAAc,EAAQ,EAAE;YACzC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;QAClD,CAAC;QACD,EAAE,EAAE,CAAC,IAAY,EAAE,QAAkC,EAAgB,EAAE;YACnE,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC3D,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/hooks/useExtensionConfig.d.ts

@@ -1,17 +1,36 @@
-interface UseExtensionConfigOptions<T> {
+/**
+ * Options for `useExtensionConfig()`.
+ */
+export interface UseExtensionConfigOptions<T> {
+    /** Override the Notur client API base URL. Defaults to `/api/client/notur`. */
     baseUrl?: string;
+    /** Initial config value used before the first request completes. */
     initial?: T;
+    /** Optional polling interval in milliseconds. Omit or set `0` to disable polling. */
     pollInterval?: number;
 }
-interface ExtensionConfigState<T> {
+/**
+ * Return value from `useExtensionConfig()`.
+ */
+export interface ExtensionConfigState<T> {
+    /** Public settings object for the extension. */
     config: T;
+    /** True while a request is in flight. */
     loading: boolean;
+    /** Last error message, or `null` when config loaded successfully. */
     error: string | null;
+    /** Re-fetch config immediately and resolve with the latest value. */
     refresh: () => Promise<T>;
 }
 /**
- * Fetch public extension settings exposed via admin.settings.*.public.
+ * Fetch public extension settings exposed by `admin.settings` fields marked `public: true`.
+ *
+ * @example
+ * ```tsx
+ * const { config, loading, error, refresh } = useExtensionConfig('acme/red-button', {
+ *   initial: { enabled: true },
+ * });
+ * ```
  */
 export declare function useExtensionConfig<T extends Record<string, any> = Record<string, any>>(extensionId: string, options?: UseExtensionConfigOptions<T>): ExtensionConfigState<T>;
-export {};
 //# sourceMappingURL=useExtensionConfig.d.ts.map

package/dist/hooks/useExtensionConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useExtensionConfig.d.ts","sourceRoot":"","sources":["../../src/hooks/useExtensionConfig.ts"],"names":[],"mappings":"AAEA,UAAU,yBAAyB,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,oBAAoB,CAAC,CAAC;IAC5B,MAAM,EAAE,CAAC,CAAC;IACV,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClF,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,yBAAyB,CAAC,CAAC,CAAM,GAC3C,oBAAoB,CAAC,CAAC,CAAC,CAoGzB"}
+{"version":3,"file":"useExtensionConfig.d.ts","sourceRoot":"","sources":["../../src/hooks/useExtensionConfig.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IACxC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,qFAAqF;IACrF,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACnC,gDAAgD;IAChD,MAAM,EAAE,CAAC,CAAC;IACV,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qEAAqE;IACrE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClF,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,yBAAyB,CAAC,CAAC,CAAM,GAC3C,oBAAoB,CAAC,CAAC,CAAC,CAoGzB"}

package/dist/hooks/useExtensionConfig.js

@@ -1,6 +1,13 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 /**
- * Fetch public extension settings exposed via admin.settings.*.public.
+ * Fetch public extension settings exposed by `admin.settings` fields marked `public: true`.
+ *
+ * @example
+ * ```tsx
+ * const { config, loading, error, refresh } = useExtensionConfig('acme/red-button', {
+ *   initial: { enabled: true },
+ * });
+ * ```
  */
 export function useExtensionConfig(extensionId, options = {}) {
     const { baseUrl, initial, pollInterval } = options;

package/dist/hooks/useExtensionConfig.js.map

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

package/dist/hooks/useNavigate.d.ts

@@ -1,12 +1,33 @@
-interface UseNavigateOptions {
+/**
+ * Options for `useNavigate()`.
+ */
+export interface UseNavigateOptions {
+    /** Owning extension id. Used to build `/notur/{extensionId}/...` URLs. */
     extensionId: string;
 }
 /**
- * Returns a navigate function scoped to the extension's route namespace.
- * Navigates to `/notur/{extensionId}/{path}` using pushState.
+ * Options accepted by the navigate function returned from `useNavigate()`.
  */
-export declare function useNavigate({ extensionId }: UseNavigateOptions): (path: string, options?: {
+export interface NavigateOptions {
+    /** Replace the current history entry instead of pushing a new one. */
     replace?: boolean;
-}) => void;
-export {};
+}
+/**
+ * Function returned by `useNavigate()`.
+ */
+export type NavigateFunction = (path: string, options?: NavigateOptions) => void;
+/**
+ * Returns a navigate function scoped to the extension route namespace.
+ *
+ * Navigates to `/notur/{extensionId}/{path}` using the browser History API and
+ * dispatches `popstate` so Notur route renderers update immediately.
+ *
+ * @example
+ * ```tsx
+ * const navigate = useNavigate({ extensionId: 'acme/tools' });
+ * navigate('/settings');
+ * navigate('/overview', { replace: true });
+ * ```
+ */
+export declare function useNavigate({ extensionId }: UseNavigateOptions): NavigateFunction;
 //# sourceMappingURL=useNavigate.d.ts.map

package/dist/hooks/useNavigate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useNavigate.d.ts","sourceRoot":"","sources":["../../src/hooks/useNavigate.ts"],"names":[],"mappings":"AAEA,UAAU,kBAAkB;IACxB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,EAAE,WAAW,EAAE,EAAE,kBAAkB,UAEhD,MAAM,YAAY;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,UAYrD"}
+{"version":3,"file":"useNavigate.d.ts","sourceRoot":"","sources":["../../src/hooks/useNavigate.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,sEAAsE;IACtE,OAAO,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;AAEjF;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,EAAE,WAAW,EAAE,EAAE,kBAAkB,GAAG,gBAAgB,CAcjF"}

package/dist/hooks/useNavigate.js

@@ -1,7 +1,16 @@
 import { useCallback } from 'react';
 /**
- * Returns a navigate function scoped to the extension's route namespace.
- * Navigates to `/notur/{extensionId}/{path}` using pushState.
+ * Returns a navigate function scoped to the extension route namespace.
+ *
+ * Navigates to `/notur/{extensionId}/{path}` using the browser History API and
+ * dispatches `popstate` so Notur route renderers update immediately.
+ *
+ * @example
+ * ```tsx
+ * const navigate = useNavigate({ extensionId: 'acme/tools' });
+ * navigate('/settings');
+ * navigate('/overview', { replace: true });
+ * ```
  */
 export function useNavigate({ extensionId }) {
     return useCallback((path, options) => {

package/dist/hooks/useNavigate.js.map

@@ -1 +1 @@
-{"version":3,"file":"useNavigate.js","sourceRoot":"","sources":["../../src/hooks/useNavigate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAMpC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAE,WAAW,EAAsB;IAC3D,OAAO,WAAW,CACd,CAAC,IAAY,EAAE,OAA+B,EAAE,EAAE;QAC9C,MAAM,QAAQ,GAAG,UAAU,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC;QACpF,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,EAAE,CAAC;YACnB,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACJ,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACjD,CAAC;QACD,yDAAyD;QACzD,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;IACxD,CAAC,EACD,CAAC,WAAW,CAAC,CAChB,CAAC;AACN,CAAC"}
+{"version":3,"file":"useNavigate.js","sourceRoot":"","sources":["../../src/hooks/useNavigate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAuBpC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,EAAE,WAAW,EAAsB;IAC3D,OAAO,WAAW,CACd,CAAC,IAAY,EAAE,OAAyB,EAAE,EAAE;QACxC,MAAM,QAAQ,GAAG,UAAU,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC;QACpF,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,OAAO,EAAE,CAAC;YACnB,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACpD,CAAC;aAAM,CAAC;YACJ,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACjD,CAAC;QACD,yDAAyD;QACzD,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC;IACxD,CAAC,EACD,CAAC,WAAW,CAAC,CAChB,CAAC;AACN,CAAC"}

package/dist/hooks/useNoturEvent.d.ts

@@ -1,10 +1,22 @@
 /**
  * Subscribe to an inter-extension event.
+ *
  * Automatically unsubscribes on unmount.
+ *
+ * @example
+ * ```tsx
+ * useNoturEvent('acme:refresh', data => console.log(data));
+ * ```
  */
 export declare function useNoturEvent(event: string, handler: (data?: unknown) => void): void;
 /**
  * Returns a function to emit events on the inter-extension event bus.
+ *
+ * @example
+ * ```tsx
+ * const emit = useEmitEvent();
+ * emit('acme:refresh', { source: 'button' });
+ * ```
  */
 export declare function useEmitEvent(): (event: string, data?: unknown) => void;
 //# sourceMappingURL=useNoturEvent.d.ts.map

package/dist/hooks/useNoturEvent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useNoturEvent.d.ts","sourceRoot":"","sources":["../../src/hooks/useNoturEvent.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAMpF;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAKtE"}
+{"version":3,"file":"useNoturEvent.d.ts","sourceRoot":"","sources":["../../src/hooks/useNoturEvent.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAMpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAKtE"}

package/dist/hooks/useNoturEvent.js

@@ -2,7 +2,13 @@ import { useEffect, useCallback } from 'react';
 import { getNoturApi } from '../types';
 /**
  * Subscribe to an inter-extension event.
+ *
  * Automatically unsubscribes on unmount.
+ *
+ * @example
+ * ```tsx
+ * useNoturEvent('acme:refresh', data => console.log(data));
+ * ```
  */
 export function useNoturEvent(event, handler) {
     useEffect(() => {
@@ -13,6 +19,12 @@ export function useNoturEvent(event, handler) {
 }
 /**
  * Returns a function to emit events on the inter-extension event bus.
+ *
+ * @example
+ * ```tsx
+ * const emit = useEmitEvent();
+ * emit('acme:refresh', { source: 'button' });
+ * ```
  */
 export function useEmitEvent() {
     return useCallback((event, data) => {

package/dist/hooks/useNoturEvent.js.map

@@ -1 +1 @@
-{"version":3,"file":"useNoturEvent.js","sourceRoot":"","sources":["../../src/hooks/useNoturEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,OAAiC;IAC1E,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO,WAAW,CAAC;IACvB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IACxB,OAAO,WAAW,CAAC,CAAC,KAAa,EAAE,IAAc,EAAE,EAAE;QACjD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC,EAAE,EAAE,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"useNoturEvent.js","sourceRoot":"","sources":["../../src/hooks/useNoturEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEvC;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,OAAiC;IAC1E,SAAS,CAAC,GAAG,EAAE;QACX,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,MAAM,WAAW,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO,WAAW,CAAC;IACvB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY;IACxB,OAAO,WAAW,CAAC,CAAC,KAAa,EAAE,IAAc,EAAE,EAAE;QACjD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;QAC1B,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC,EAAE,EAAE,CAAC,CAAC;AACX,CAAC"}

package/dist/hooks/usePermission.d.ts

@@ -1,5 +1,14 @@
 /**
- * Hook to check if the current user has a specific extension permission.
+ * Check whether the current server user has a permission.
+ *
+ * This hook reads server context permissions when available. It returns `false`
+ * outside server pages, while context is unavailable, or when the permission is
+ * missing. Server owners are treated as allowed.
+ *
+ * @example
+ * ```tsx
+ * const canInstall = usePermission('notur.acme/tools.install');
+ * ```
  */
 export declare function usePermission(permission: string): boolean;
 //# sourceMappingURL=usePermission.d.ts.map

package/dist/hooks/usePermission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePermission.d.ts","sourceRoot":"","sources":["../../src/hooks/usePermission.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAwBzD"}
+{"version":3,"file":"usePermission.d.ts","sourceRoot":"","sources":["../../src/hooks/usePermission.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAwBzD"}

package/dist/hooks/usePermission.js

@@ -1,7 +1,16 @@
 import { useState, useEffect } from 'react';
 import { useServerContext } from './useServerContext';
 /**
- * Hook to check if the current user has a specific extension permission.
+ * Check whether the current server user has a permission.
+ *
+ * This hook reads server context permissions when available. It returns `false`
+ * outside server pages, while context is unavailable, or when the permission is
+ * missing. Server owners are treated as allowed.
+ *
+ * @example
+ * ```tsx
+ * const canInstall = usePermission('notur.acme/tools.install');
+ * ```
  */
 export function usePermission(permission) {
     const serverContext = useServerContext();

package/dist/hooks/usePermission.js.map

@@ -1 +1 @@
-{"version":3,"file":"usePermission.js","sourceRoot":"","sources":["../../src/hooks/usePermission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC5C,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE1D,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,aAAa,EAAE,CAAC;YACjB,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACxB,OAAO;QACX,CAAC;QAED,iBAAiB;QACjB,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;YACxB,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACvB,OAAO;QACX,CAAC;QAED,0BAA0B;QAC1B,MAAM,KAAK,GAAG,aAAa,CAAC,WAAW,IAAI,EAAE,CAAC;QAC9C,gBAAgB,CACZ,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAChE,CAAC;IACN,CAAC,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;IAEhC,OAAO,aAAa,CAAC;AACzB,CAAC"}
+{"version":3,"file":"usePermission.js","sourceRoot":"","sources":["../../src/hooks/usePermission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC5C,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE1D,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,CAAC,aAAa,EAAE,CAAC;YACjB,gBAAgB,CAAC,KAAK,CAAC,CAAC;YACxB,OAAO;QACX,CAAC;QAED,iBAAiB;QACjB,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;YACxB,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACvB,OAAO;QACX,CAAC;QAED,0BAA0B;QAC1B,MAAM,KAAK,GAAG,aAAa,CAAC,WAAW,IAAI,EAAE,CAAC;QAC9C,gBAAgB,CACZ,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAChE,CAAC;IACN,CAAC,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC,CAAC;IAEhC,OAAO,aAAa,CAAC;AACzB,CAAC"}

package/dist/hooks/useServerContext.d.ts

@@ -1,15 +1,30 @@
-interface ServerContext {
+/**
+ * Server metadata available when the current page is scoped to a Pterodactyl server.
+ */
+export interface ServerContext {
+    /** Server UUID from the current URL or panel data payload. */
     uuid: string;
+    /** Server display name when available. */
     name: string;
+    /** Node name/identifier when available. */
     node: string;
+    /** True when the current user owns the server or has owner-level access. */
     isOwner: boolean;
+    /** Runtime status reported by the panel, or `null` when unknown. */
     status: string | null;
+    /** Server permission keys available to the current user. */
     permissions: string[];
 }
 /**
  * Hook to access the current server context from the Pterodactyl panel.
- * Only available within server-scoped pages.
+ *
+ * Returns `null` outside server-scoped pages or while context is unavailable.
+ *
+ * @example
+ * ```tsx
+ * const server = useServerContext();
+ * return <span>{server?.uuid}</span>;
+ * ```
  */
 export declare function useServerContext(): ServerContext | null;
-export {};
 //# sourceMappingURL=useServerContext.d.ts.map

package/dist/hooks/useServerContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useServerContext.d.ts","sourceRoot":"","sources":["../../src/hooks/useServerContext.ts"],"names":[],"mappings":"AAEA,UAAU,aAAa;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CA0BvD"}
+{"version":3,"file":"useServerContext.d.ts","sourceRoot":"","sources":["../../src/hooks/useServerContext.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CA0BvD"}

package/dist/hooks/useServerContext.js

@@ -1,7 +1,14 @@
 import { useState, useEffect } from 'react';
 /**
  * Hook to access the current server context from the Pterodactyl panel.
- * Only available within server-scoped pages.
+ *
+ * Returns `null` outside server-scoped pages or while context is unavailable.
+ *
+ * @example
+ * ```tsx
+ * const server = useServerContext();
+ * return <span>{server?.uuid}</span>;
+ * ```
  */
 export function useServerContext() {
     const [context, setContext] = useState(null);

package/dist/hooks/useServerContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"useServerContext.js","sourceRoot":"","sources":["../../src/hooks/useServerContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAW5C;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC5B,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAuB,IAAI,CAAC,CAAC;IAEnE,SAAS,CAAC,GAAG,EAAE;QACX,oEAAoE;QACpE,uDAAuD;QACvD,MAAM,aAAa,GAAG,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,aAAa;YAAE,OAAO;QAE3B,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC;QAChD,IAAI,UAAU,EAAE,CAAC;YACb,IAAI,CAAC;gBACD,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;YACvC,CAAC;YAAC,WAAM,CAAC;gBACL,uBAAuB;YAC3B,CAAC;QACL,CAAC;QAED,qCAAqC;QACrC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACvE,IAAI,KAAK,EAAE,CAAC;YACR,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;QACtH,CAAC;IACL,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,OAAO,CAAC;AACnB,CAAC"}
+{"version":3,"file":"useServerContext.js","sourceRoot":"","sources":["../../src/hooks/useServerContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAoB5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB;IAC5B,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAuB,IAAI,CAAC,CAAC;IAEnE,SAAS,CAAC,GAAG,EAAE;QACX,oEAAoE;QACpE,uDAAuD;QACvD,MAAM,aAAa,GAAG,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;QACrD,IAAI,CAAC,aAAa;YAAE,OAAO;QAE3B,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC;QAChD,IAAI,UAAU,EAAE,CAAC;YACb,IAAI,CAAC;gBACD,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;YACvC,CAAC;YAAC,WAAM,CAAC;gBACL,uBAAuB;YAC3B,CAAC;QACL,CAAC;QAED,qCAAqC;QACrC,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACvE,IAAI,KAAK,EAAE,CAAC;YACR,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC;QACtH,CAAC;IACL,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/dist/hooks/useUserContext.d.ts

@@ -1,12 +1,20 @@
-interface UserContext {
+/**
+ * Current Pterodactyl user metadata returned by `useUserContext()`.
+ */
+export interface UserContext {
+    /** User UUID. */
     uuid: string;
+    /** Username shown in the panel. */
     username: string;
+    /** User email address. */
     email: string;
+    /** True when the user is a root/admin user. */
     isAdmin: boolean;
 }
 /**
  * Hook to access the current user context from the Pterodactyl panel.
+ *
+ * Returns `null` while loading or when the user cannot be resolved.
  */
 export declare function useUserContext(): UserContext | null;
-export {};
 //# sourceMappingURL=useUserContext.d.ts.map

package/dist/hooks/useUserContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useUserContext.d.ts","sourceRoot":"","sources":["../../src/hooks/useUserContext.ts"],"names":[],"mappings":"AAEA,UAAU,WAAW;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAiDnD"}
+{"version":3,"file":"useUserContext.d.ts","sourceRoot":"","sources":["../../src/hooks/useUserContext.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,WAAW;IACxB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAiDnD"}