@theruntimehq/react 0.2.1 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@theruntimehq/react.svg)](https://www.npmjs.com/package/@theruntimehq/react)
 [![license](https://img.shields.io/npm/l/@theruntimehq/react.svg)](https://github.com/TheRuntimeHQ/runtimehq-react/blob/main/LICENSE)
 
-The official React state management SDK for [RuntimeHQ](https://theruntimehq.com). Connect your status checks directly to your React primitives.
+The official [Runtime React SDK](https://docs.theruntimehq.com/runtime-sdks/react) for [RuntimeHQ](https://theruntimehq.com). The SDK provides a context provider and hooks to easily consume the effective runtime state in your application components.
 
 This SDK is a **pure state management SDK** with:
 - 🚫 **No visual UI components** (Customers use their own design systems).
@@ -19,9 +19,11 @@ This SDK is a **pure state management SDK** with:
 - [Installation](#installation)
 - [Core Hooks & Provider APIs](#core-hooks--provider-apis)
   - [1. Global Provider (\`RuntimeHQProvider\`)](#1-global-provider-runtimehqprovider)
-  - [2. Context Hook (\`useRuntimeHQ\`)](#2-context-hook-useruntimehq)
-  - [3. Standalone Direct Hook (\`useRuntimeHQState\`)](#3-standalone-direct-hook-useruntimehqstate)
+  - [2. Capability Hook (\`useCapability\`)](#2-capability-hook-usecapability)
+  - [3. Context Hook (\`useRuntimeHQ\`)](#3-context-hook-useruntimehq)
+  - [4. Standalone Direct Hook (\`useRuntimeHQState\`)](#4-standalone-direct-hook-useruntimehqstate)
 - [Convenience Helpers](#convenience-helpers)
+- [State Resolution Architecture](#state-resolution-architecture)
 - [Server Rendering (SSR) & Next.js App Router Integration](#server-rendering-ssr--nextjs-app-router-integration)
 - [Examples Directory](#examples-directory)
 - [License](#license)
@@ -51,7 +53,7 @@ export default function Root() {
   return (
     <RuntimeHQProvider 
       runtimeKey="rt_prod_your_key_here" 
-      intervalSeconds={15}
+      intervalSeconds={60}
     >
       <App />
     </RuntimeHQProvider>
@@ -62,14 +64,63 @@ export default function Root() {
 #### Provider Props
 | Prop | Type | Required | Default | Description |
 | :--- | :--- | :--- | :--- | :--- |
-| `runtimeKey` | `string` | **Yes** | - | Your RuntimeHQ API status key (must start with `rt_prod_` or `rt_test_`). |
-| `intervalSeconds` | `number` | No | `15` | Polling interval for updates in seconds. |
+| `runtimeKey` | `string` | **Yes** | - | The [Runtime Key](https://docs.theruntimehq.com/runtime-keys) required to get the resolved operational state of the application's capabilities. This is a public, read-only key that is absolutely safe for client-side exposure or browser environments. |
+| `intervalSeconds` | `number` | No | `60` | Configurable polling interval for updates in seconds. Defaults to 60 seconds. |
 
 ---
 
-### 2. Context Hook (`useRuntimeHQ`)
+### 2. Capability Hook (`useCapability`)
 
-Consume the global status state anywhere inside the provider.
+The recommended, idiomatic way to monitor feature health inside components. Encapsulates fail-open defaults (`isOperational: true`, `isOutage: false` when unconfigured or loading).
+
+```tsx
+import { useCapability } from "@theruntimehq/react";
+
+function SearchComponent() {
+  const { isOutage, isDegraded, message } = useCapability("search");
+
+  // Dynamically back off request frequency when search capability is degraded
+  const debounceDelayMs = isDegraded ? 1200 : 300;
+
+  return (
+    <div className="search-container">
+      <input 
+        type="text" 
+        placeholder="Search products..." 
+        disabled={isOutage}
+        onChange={debounce(handleSearch, debounceDelayMs)}
+      />
+      {(isOutage || isDegraded) && message && (
+        <p className={`helper-message ${isOutage ? 'text-red-600' : 'text-amber-600'}`}>
+          {message}
+        </p>
+      )}
+    </div>
+  );
+}
+```
+
+#### Return Value
+```typescript
+interface UseCapabilityResult {
+  capability: CapabilityState | undefined; // Raw capability state object (or undefined if not present)
+  state: RuntimeState;                     // Current state, defaults to "OPERATIONAL" (fail-open)
+  message: string;                         // Operational or degraded message (defaults to "")
+  isOperational: boolean;                  // true by default (fail-open)
+  isDegraded: boolean;                     // true if state === "DEGRADED"
+  isOutage: boolean;                       // true if state === "OUTAGE"
+  isMaintenance: boolean;                  // true if state === "MAINTENANCE"
+  exists: boolean;                         // true if capability is registered in configuration
+  loading: boolean;                        // true until the first fetch completes
+  error: Error | null;                     // Captured network or validation error (if any)
+}
+```
+
+---
+
+### 3. Context Hook (`useRuntimeHQ`)
+
+Consume the global status state anywhere inside the provider for application-wide status banners, dashboards, or lower-level inspection.
 
 ```tsx
 import { useRuntimeHQ, isOperational } from "@theruntimehq/react";
@@ -92,15 +143,16 @@ function StatusBanner() {
 #### Return Value
 ```typescript
 interface RuntimeHQContextValue {
-  runtime: RuntimeResponse | null; // Detailed status info or null before first fetch
-  loading: boolean;                // true until the first fetch (success or failure) completes
-  error: Error | null;             // Captured network or validation error (if any)
+  runtime: RuntimeResponse | null;                                   // Detailed status info or null before first fetch
+  loading: boolean;                                                  // true until the first fetch (success or failure) completes
+  error: Error | null;                                               // Captured network or validation error (if any)
+  hasCapability: (name: string) => boolean;                          // Checks if a capability is registered
+  getCapabilityState: (name: string) => CapabilityState | undefined; // Returns resolved capability state
 }
 ```
 
 > [!IMPORTANT]
-> If `useRuntimeHQ` is invoked outside a `<RuntimeHQProvider>`, it throws a descriptive error:
-> `useRuntimeHQ must be used within a RuntimeHQProvider`
+> Both `useCapability` and `useRuntimeHQ` must be used within a `<RuntimeHQProvider>`, or they will throw a descriptive error.
 
 ---
 
@@ -114,7 +166,7 @@ import { useRuntimeHQState } from "@theruntimehq/react";
 function IndependentWidget() {
   const { runtime, loading, error } = useRuntimeHQState({
     runtimeKey: "rt_prod_your_key_here",
-    intervalSeconds: 30,
+    intervalSeconds: 60,
   });
 
   if (loading) return <Spinner />;
@@ -145,6 +197,29 @@ isOutage(runtime)       // returns boolean
 
 ---
 
+## State Resolution Architecture
+
+```mermaid
+sequenceDiagram
+    participant App as React Application
+    participant SDK as @theruntimehq/react
+    participant Edge as Global Edge Cache
+
+    Note over SDK, Edge: 1. Asynchronous Background Polling
+    loop Every intervalSeconds
+        SDK->>Edge: Fetch latest operational state
+        Edge-->>SDK: Cached State JSON (High Availability)
+        SDK->>SDK: Update local React Context
+    end
+
+    Note over App, SDK: 2. Instant Local Resolution
+    App->>SDK: getCapabilityState("capability-name")
+    SDK-->>App: Returns state from local memory instantly
+    Note over App: Zero network latency impact on application speed
+```
+
+---
+
 ## Server Rendering (SSR) & Next.js App Router Integration
 
 To avoid layout shifts and flashes of loading states on initial load, fetch the status server-side using the underlying `@theruntimehq/js` SDK directly, and render a static warning component on the server:
@@ -195,7 +270,7 @@ interface ClientSidePollerProps {
 export default function ClientSidePoller({ initialData }: ClientSidePollerProps) {
   const { runtime } = useRuntimeHQState({
     runtimeKey: "rt_prod_your_key_here",
-    intervalSeconds: 15,
+    intervalSeconds: 60,
   });
 
   // Hydrate client-side with server-fetched data initially
@@ -238,6 +313,7 @@ Check out the [examples directory](./examples) for common integration patterns:
 | `19-maintenance-lock-screen.tsx` | Restrict access to workflows during active maintenance windows. |
 | `20-live-system-health-widget.tsx` | Embed a reusable health widget anywhere in the application. |
 | `21-production-ready-provider.tsx` | Complete production integration including provider setup, refresh handling, and resilience patterns. |
+| `22-adaptive-debounce-search.tsx` | Adapt client input debounce delay to shed backend load during degraded states. |
 
 ---
 

package/dist/index.cjs

@@ -40,7 +40,7 @@ const RuntimeHQContext = (0, react.createContext)(null);
 * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.
 */
 function useRuntimeHQState(options) {
-	const { runtimeKey, intervalSeconds = 15 } = options;
+	const { runtimeKey, intervalSeconds = 60 } = options;
 	const [client, clientInitError] = (0, react.useMemo)(() => {
 		if (!runtimeKey) return [null, /* @__PURE__ */ new Error("runtimeKey is required")];
 		try {
@@ -130,6 +130,45 @@ function useRuntimeHQ() {
 	return context;
 }
 
+//#endregion
+//#region src/hooks/useCapability.ts
+/**
+* Accesses and monitors the health state of a specific capability.
+* Must be used within a `<RuntimeHQProvider>`.
+*
+* Implements a fail-open pattern: if the capability is not present or
+* RuntimeHQ is loading/errored, the state defaults to "OPERATIONAL"
+* and isOperational is true.
+*
+* @param name The unique name of the capability to check (e.g. "search", "payments")
+*/
+function useCapability(name) {
+	const { getCapabilityState, hasCapability, loading, error } = useRuntimeHQ();
+	return (0, react.useMemo)(() => {
+		const capability = getCapabilityState(name);
+		const exists = hasCapability(name);
+		const state = capability?.state ?? "OPERATIONAL";
+		return {
+			capability,
+			state,
+			message: capability?.message ?? "",
+			isOperational: state === "OPERATIONAL",
+			isDegraded: state === "DEGRADED",
+			isOutage: state === "OUTAGE",
+			isMaintenance: state === "MAINTENANCE",
+			exists,
+			loading,
+			error
+		};
+	}, [
+		getCapabilityState,
+		hasCapability,
+		name,
+		loading,
+		error
+	]);
+}
+
 //#endregion
 //#region src/helpers/index.ts
 function getState(input) {
@@ -168,6 +207,7 @@ exports.isDegraded = isDegraded;
 exports.isMaintenance = isMaintenance;
 exports.isOperational = isOperational;
 exports.isOutage = isOutage;
+exports.useCapability = useCapability;
 exports.useRuntimeHQ = useRuntimeHQ;
 exports.useRuntimeHQState = useRuntimeHQState;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["RuntimeHQClient"],"sources":["../src/context/index.ts","../src/hooks/useRuntimeHQState.ts","../src/provider/index.tsx","../src/hooks/useRuntimeHQ.ts","../src/helpers/index.ts"],"sourcesContent":["\"use client\";\n\nimport { createContext } from \"react\";\nimport { RuntimeHQContextValue } from \"../types\";\n\nexport const RuntimeHQContext = createContext<RuntimeHQContextValue | null>(null);\n","\"use client\";\n\nimport { useState, useEffect, useMemo, useCallback } from \"react\";\nimport { RuntimeHQClient } from \"@theruntimehq/js\";\nimport { RuntimeResponse, RuntimeHQContextValue } from \"../types\";\n\nexport interface UseRuntimeHQStateOptions {\n  runtimeKey: string;\n  intervalSeconds?: number;\n}\n\n/**\n * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.\n */\nexport function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue {\n  const { runtimeKey, intervalSeconds = 15 } = options;\n\n  // Safely instantiate RuntimeHQClient\n  const [client, clientInitError] = useMemo(() => {\n    if (!runtimeKey) {\n      return [null, new Error(\"runtimeKey is required\")] as const;\n    }\n    try {\n      return [new RuntimeHQClient({ runtimeKey }), null] as const;\n    } catch (err) {\n      return [null, err instanceof Error ? err : new Error(String(err))] as const;\n    }\n  }, [runtimeKey]);\n\n  const [runtime, setRuntime] = useState<RuntimeResponse | null>(null);\n  const [error, setError] = useState<Error | null>(clientInitError || null);\n  const [loading, setLoading] = useState<boolean>(!clientInitError);\n\n  useEffect(() => {\n    if (clientInitError) {\n      setError(clientInitError);\n      setLoading(false);\n      return;\n    }\n\n    if (!client) {\n      return;\n    }\n\n    // Reset states when the client or key changes\n    setRuntime(null);\n    setError(null);\n    setLoading(true);\n\n    let active = true;\n\n    const unsubscribe = client.watchRuntime({\n      intervalSeconds,\n      onUpdate: (data) => {\n        if (active) {\n          setRuntime(data);\n          setError(null);\n          setLoading(false);\n        }\n      },\n      onError: (err) => {\n        if (active) {\n          setError(err);\n          setLoading(false);\n        }\n      },\n    });\n\n    return () => {\n      active = false;\n      unsubscribe();\n    };\n  }, [client, clientInitError, intervalSeconds]);\n\n  const hasCapability = useCallback((name: string) => {\n    return runtime ? runtime.hasCapability(name) : false;\n  }, [runtime]);\n\n  const getCapabilityState = useCallback((name: string) => {\n    return runtime ? runtime.getCapabilityState(name) : undefined;\n  }, [runtime]);\n\n  return {\n    runtime,\n    loading,\n    error,\n    hasCapability,\n    getCapabilityState,\n  };\n}\n","\"use client\";\n\nimport React from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { useRuntimeHQState } from \"../hooks/useRuntimeHQState\";\n\nexport interface RuntimeHQProviderProps {\n  runtimeKey: string;\n  intervalSeconds?: number;\n  children: React.ReactNode;\n}\n\n/**\n * Context Provider that manages a global RuntimeHQ client subscription and polling loop,\n * making the status state available to all child components using `useRuntimeHQ()`.\n */\nexport function RuntimeHQProvider({\n  runtimeKey,\n  intervalSeconds,\n  children,\n}: RuntimeHQProviderProps) {\n  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });\n\n  return (\n    <RuntimeHQContext.Provider value={value}>\n      {children}\n    </RuntimeHQContext.Provider>\n  );\n}\n","\"use client\";\n\nimport { useContext } from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { RuntimeHQContextValue } from \"../types\";\n\n/**\n * Accesses the global RuntimeHQ status check context.\n * Must be used within a `<RuntimeHQProvider>`.\n */\nexport function useRuntimeHQ(): RuntimeHQContextValue {\n  const context = useContext(RuntimeHQContext);\n  if (!context) {\n    throw new Error(\"useRuntimeHQ must be used within a RuntimeHQProvider\");\n  }\n  return context;\n}\n","import { RuntimeResponse, RuntimeState, CapabilityState } from \"../types\";\n\ntype StateInput = RuntimeResponse | CapabilityState | RuntimeState | null | undefined;\n\nfunction getState(input: StateInput): RuntimeState | null {\n  if (!input) return null;\n  if (typeof input === \"string\") return input;\n  return input.state || null;\n}\n\n/**\n * Checks if the application runtime status is OPERATIONAL.\n */\nexport function isOperational(input: StateInput): boolean {\n  return getState(input) === \"OPERATIONAL\";\n}\n\n/**\n * Checks if the application runtime status is MAINTENANCE.\n */\nexport function isMaintenance(input: StateInput): boolean {\n  return getState(input) === \"MAINTENANCE\";\n}\n\n/**\n * Checks if the application runtime status is DEGRADED.\n */\nexport function isDegraded(input: StateInput): boolean {\n  return getState(input) === \"DEGRADED\";\n}\n\n/**\n * Checks if the application runtime status is OUTAGE.\n */\nexport function isOutage(input: StateInput): boolean {\n  return getState(input) === \"OUTAGE\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAKA,MAAa,4CAA+D,IAAI;;;;;;;ACShF,SAAgB,kBAAkB,SAA0D;CAC1F,MAAM,EAAE,YAAY,kBAAkB,OAAO;CAG7C,MAAM,CAAC,QAAQ,4CAAiC;EAC9C,IAAI,CAAC,YACH,OAAO,CAAC,sBAAM,IAAI,MAAM,wBAAwB,CAAC;EAEnD,IAAI;GACF,OAAO,CAAC,IAAIA,iCAAgB,EAAE,WAAW,CAAC,GAAG,IAAI;EACnD,SAAS,KAAK;GACZ,OAAO,CAAC,MAAM,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;EACnE;CACF,GAAG,CAAC,UAAU,CAAC;CAEf,MAAM,CAAC,SAAS,kCAA+C,IAAI;CACnE,MAAM,CAAC,OAAO,gCAAmC,mBAAmB,IAAI;CACxE,MAAM,CAAC,SAAS,kCAAgC,CAAC,eAAe;CAEhE,2BAAgB;EACd,IAAI,iBAAiB;GACnB,SAAS,eAAe;GACxB,WAAW,KAAK;GAChB;EACF;EAEA,IAAI,CAAC,QACH;EAIF,WAAW,IAAI;EACf,SAAS,IAAI;EACb,WAAW,IAAI;EAEf,IAAI,SAAS;EAEb,MAAM,cAAc,OAAO,aAAa;GACtC;GACA,WAAW,SAAS;IAClB,IAAI,QAAQ;KACV,WAAW,IAAI;KACf,SAAS,IAAI;KACb,WAAW,KAAK;IAClB;GACF;GACA,UAAU,QAAQ;IAChB,IAAI,QAAQ;KACV,SAAS,GAAG;KACZ,WAAW,KAAK;IAClB;GACF;EACF,CAAC;EAED,aAAa;GACX,SAAS;GACT,YAAY;EACd;CACF,GAAG;EAAC;EAAQ;EAAiB;CAAe,CAAC;CAU7C,OAAO;EACL;EACA;EACA;EACA,uCAZiC,SAAiB;GAClD,OAAO,UAAU,QAAQ,cAAc,IAAI,IAAI;EACjD,GAAG,CAAC,OAAO,CAUG;EACZ,4CATsC,SAAiB;GACvD,OAAO,UAAU,QAAQ,mBAAmB,IAAI,IAAI;EACtD,GAAG,CAAC,OAAO,CAOQ;CACnB;AACF;;;;;;;;ACzEA,SAAgB,kBAAkB,EAChC,YACA,iBACA,YACyB;CACzB,MAAM,QAAQ,kBAAkB;EAAE;EAAY;CAAgB,CAAC;CAE/D,OACE,2CAAC,iBAAiB,UAAlB;EAAkC;EAC/B;CACwB;AAE/B;;;;;;;;AClBA,SAAgB,eAAsC;CACpD,MAAM,gCAAqB,gBAAgB;CAC3C,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,sDAAsD;CAExE,OAAO;AACT;;;;ACZA,SAAS,SAAS,OAAwC;CACxD,IAAI,CAAC,OAAO,OAAO;CACnB,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,OAAO,MAAM,SAAS;AACxB;;;;AAKA,SAAgB,cAAc,OAA4B;CACxD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,cAAc,OAA4B;CACxD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,WAAW,OAA4B;CACrD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,SAAS,OAA4B;CACnD,OAAO,SAAS,KAAK,MAAM;AAC7B"}
+{"version":3,"file":"index.cjs","names":["RuntimeHQClient"],"sources":["../src/context/index.ts","../src/hooks/useRuntimeHQState.ts","../src/provider/index.tsx","../src/hooks/useRuntimeHQ.ts","../src/hooks/useCapability.ts","../src/helpers/index.ts"],"sourcesContent":["\"use client\";\n\nimport { createContext } from \"react\";\nimport { RuntimeHQContextValue } from \"../types\";\n\nexport const RuntimeHQContext = createContext<RuntimeHQContextValue | null>(null);\n","\"use client\";\n\nimport { useState, useEffect, useMemo, useCallback } from \"react\";\nimport { RuntimeHQClient } from \"@theruntimehq/js\";\nimport { RuntimeResponse, RuntimeHQContextValue } from \"../types\";\n\nexport interface UseRuntimeHQStateOptions {\n  runtimeKey: string;\n  intervalSeconds?: number;\n}\n\n/**\n * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.\n */\nexport function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue {\n  const { runtimeKey, intervalSeconds = 60 } = options;\n\n  // Safely instantiate RuntimeHQClient\n  const [client, clientInitError] = useMemo(() => {\n    if (!runtimeKey) {\n      return [null, new Error(\"runtimeKey is required\")] as const;\n    }\n    try {\n      return [new RuntimeHQClient({ runtimeKey }), null] as const;\n    } catch (err) {\n      return [null, err instanceof Error ? err : new Error(String(err))] as const;\n    }\n  }, [runtimeKey]);\n\n  const [runtime, setRuntime] = useState<RuntimeResponse | null>(null);\n  const [error, setError] = useState<Error | null>(clientInitError || null);\n  const [loading, setLoading] = useState<boolean>(!clientInitError);\n\n  useEffect(() => {\n    if (clientInitError) {\n      setError(clientInitError);\n      setLoading(false);\n      return;\n    }\n\n    if (!client) {\n      return;\n    }\n\n    // Reset states when the client or key changes\n    setRuntime(null);\n    setError(null);\n    setLoading(true);\n\n    let active = true;\n\n    const unsubscribe = client.watchRuntime({\n      intervalSeconds,\n      onUpdate: (data) => {\n        if (active) {\n          setRuntime(data);\n          setError(null);\n          setLoading(false);\n        }\n      },\n      onError: (err) => {\n        if (active) {\n          setError(err);\n          setLoading(false);\n        }\n      },\n    });\n\n    return () => {\n      active = false;\n      unsubscribe();\n    };\n  }, [client, clientInitError, intervalSeconds]);\n\n  const hasCapability = useCallback((name: string) => {\n    return runtime ? runtime.hasCapability(name) : false;\n  }, [runtime]);\n\n  const getCapabilityState = useCallback((name: string) => {\n    return runtime ? runtime.getCapabilityState(name) : undefined;\n  }, [runtime]);\n\n  return {\n    runtime,\n    loading,\n    error,\n    hasCapability,\n    getCapabilityState,\n  };\n}\n","\"use client\";\n\nimport React from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { useRuntimeHQState } from \"../hooks/useRuntimeHQState\";\n\nexport interface RuntimeHQProviderProps {\n  runtimeKey: string;\n  intervalSeconds?: number;\n  children: React.ReactNode;\n}\n\n/**\n * Context Provider that manages a global RuntimeHQ client subscription and polling loop,\n * making the status state available to all child components using `useRuntimeHQ()`.\n */\nexport function RuntimeHQProvider({\n  runtimeKey,\n  intervalSeconds,\n  children,\n}: RuntimeHQProviderProps) {\n  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });\n\n  return (\n    <RuntimeHQContext.Provider value={value}>\n      {children}\n    </RuntimeHQContext.Provider>\n  );\n}\n","\"use client\";\n\nimport { useContext } from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { RuntimeHQContextValue } from \"../types\";\n\n/**\n * Accesses the global RuntimeHQ status check context.\n * Must be used within a `<RuntimeHQProvider>`.\n */\nexport function useRuntimeHQ(): RuntimeHQContextValue {\n  const context = useContext(RuntimeHQContext);\n  if (!context) {\n    throw new Error(\"useRuntimeHQ must be used within a RuntimeHQProvider\");\n  }\n  return context;\n}\n","\"use client\";\n\nimport { useMemo } from \"react\";\nimport { useRuntimeHQ } from \"./useRuntimeHQ\";\nimport { UseCapabilityResult, RuntimeState } from \"../types\";\n\n/**\n * Accesses and monitors the health state of a specific capability.\n * Must be used within a `<RuntimeHQProvider>`.\n *\n * Implements a fail-open pattern: if the capability is not present or\n * RuntimeHQ is loading/errored, the state defaults to \"OPERATIONAL\"\n * and isOperational is true.\n *\n * @param name The unique name of the capability to check (e.g. \"search\", \"payments\")\n */\nexport function useCapability(name: string): UseCapabilityResult {\n  const { getCapabilityState, hasCapability, loading, error } = useRuntimeHQ();\n\n  return useMemo(() => {\n    const capability = getCapabilityState(name);\n    const exists = hasCapability(name);\n    const state: RuntimeState = capability?.state ?? \"OPERATIONAL\";\n    const message = capability?.message ?? \"\";\n\n    return {\n      capability,\n      state,\n      message,\n      isOperational: state === \"OPERATIONAL\",\n      isDegraded: state === \"DEGRADED\",\n      isOutage: state === \"OUTAGE\",\n      isMaintenance: state === \"MAINTENANCE\",\n      exists,\n      loading,\n      error,\n    };\n  }, [getCapabilityState, hasCapability, name, loading, error]);\n}\n","import { RuntimeResponse, RuntimeState, CapabilityState } from \"../types\";\n\ntype StateInput = RuntimeResponse | CapabilityState | RuntimeState | null | undefined;\n\nfunction getState(input: StateInput): RuntimeState | null {\n  if (!input) return null;\n  if (typeof input === \"string\") return input;\n  return input.state || null;\n}\n\n/**\n * Checks if the application runtime status is OPERATIONAL.\n */\nexport function isOperational(input: StateInput): boolean {\n  return getState(input) === \"OPERATIONAL\";\n}\n\n/**\n * Checks if the application runtime status is MAINTENANCE.\n */\nexport function isMaintenance(input: StateInput): boolean {\n  return getState(input) === \"MAINTENANCE\";\n}\n\n/**\n * Checks if the application runtime status is DEGRADED.\n */\nexport function isDegraded(input: StateInput): boolean {\n  return getState(input) === \"DEGRADED\";\n}\n\n/**\n * Checks if the application runtime status is OUTAGE.\n */\nexport function isOutage(input: StateInput): boolean {\n  return getState(input) === \"OUTAGE\";\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import React from "react";
-import { CapabilityState, CapabilityState as CapabilityState$1, RuntimeHQClientOptions, RuntimeResponse, RuntimeResponse as RuntimeResponse$1, RuntimeState, WatchRuntimeOptions } from "@theruntimehq/js";
+import { CapabilityState, CapabilityState as CapabilityState$1, RuntimeHQClientOptions, RuntimeResponse, RuntimeResponse as RuntimeResponse$1, RuntimeState as RuntimeState$1, WatchRuntimeOptions } from "@theruntimehq/js";
 
 //#region src/provider/index.d.ts
 interface RuntimeHQProviderProps {
@@ -25,6 +25,18 @@ interface RuntimeHQContextValue {
   hasCapability: (name: string) => boolean;
   getCapabilityState: (name: string) => CapabilityState$1 | undefined;
 }
+interface UseCapabilityResult {
+  capability: CapabilityState$1 | undefined;
+  state: RuntimeState;
+  message: string;
+  isOperational: boolean;
+  isDegraded: boolean;
+  isOutage: boolean;
+  isMaintenance: boolean;
+  exists: boolean;
+  loading: boolean;
+  error: Error | null;
+}
 //#endregion
 //#region src/hooks/useRuntimeHQ.d.ts
 /**
@@ -43,8 +55,21 @@ interface UseRuntimeHQStateOptions {
  */
 declare function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue;
 //#endregion
+//#region src/hooks/useCapability.d.ts
+/**
+ * Accesses and monitors the health state of a specific capability.
+ * Must be used within a `<RuntimeHQProvider>`.
+ *
+ * Implements a fail-open pattern: if the capability is not present or
+ * RuntimeHQ is loading/errored, the state defaults to "OPERATIONAL"
+ * and isOperational is true.
+ *
+ * @param name The unique name of the capability to check (e.g. "search", "payments")
+ */
+declare function useCapability(name: string): UseCapabilityResult;
+//#endregion
 //#region src/helpers/index.d.ts
-type StateInput = RuntimeResponse | CapabilityState | RuntimeState | null | undefined;
+type StateInput = RuntimeResponse | CapabilityState | RuntimeState$1 | null | undefined;
 /**
  * Checks if the application runtime status is OPERATIONAL.
  */
@@ -62,5 +87,5 @@ declare function isDegraded(input: StateInput): boolean;
  */
 declare function isOutage(input: StateInput): boolean;
 //#endregion
-export { type CapabilityState, type RuntimeHQClientOptions, RuntimeHQContextValue, RuntimeHQProvider, type RuntimeHQProviderProps, type RuntimeResponse, type RuntimeState, type UseRuntimeHQStateOptions, type WatchRuntimeOptions, isDegraded, isMaintenance, isOperational, isOutage, useRuntimeHQ, useRuntimeHQState };
+export { type CapabilityState, type RuntimeHQClientOptions, RuntimeHQContextValue, RuntimeHQProvider, type RuntimeHQProviderProps, type RuntimeResponse, type RuntimeState$1 as RuntimeState, UseCapabilityResult, type UseRuntimeHQStateOptions, type WatchRuntimeOptions, isDegraded, isMaintenance, isOperational, isOutage, useCapability, useRuntimeHQ, useRuntimeHQState };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/provider/index.tsx","../src/types/index.ts","../src/hooks/useRuntimeHQ.ts","../src/hooks/useRuntimeHQState.ts","../src/helpers/index.ts"],"mappings":";;;;UAMiB,sBAAA;EACf,UAAA;EACA,eAAA;EACA,QAAA,EAAU,KAAA,CAAM,SAAS;AAAA;;;;;iBAOX,iBAAA;EACd,UAAA;EACA,eAAA;EACA;AAAA,GACC,sBAAA,GAAsB,KAAA,CAAA,GAAA,CAAA,OAAA;;;UCVR,qBAAA;EACf,OAAA,EAAS,iBAAA;EACT,OAAA;EACA,KAAA,EAAO,KAAA;EACP,aAAA,GAAgB,IAAA;EAChB,kBAAA,GAAqB,IAAA,aAAiB,iBAAA;AAAA;;;;;;ADTxC;iBEIgB,YAAA,IAAgB,qBAAqB;;;UCJpC,wBAAA;EACf,UAAA;EACA,eAAe;AAAA;;;;iBAMD,iBAAA,CAAkB,OAAA,EAAS,wBAAA,GAA2B,qBAAqB;;;KCZtF,UAAA,GAAa,eAAA,GAAkB,eAAA,GAAkB,YAAA;;;AJItD;iBIOgB,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,UAAA,CAAW,KAAiB,EAAV,UAAU;AJlBjB;AAO3B;;AAP2B,iBIyBX,QAAA,CAAS,KAAiB,EAAV,UAAU"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/provider/index.tsx","../src/types/index.ts","../src/hooks/useRuntimeHQ.ts","../src/hooks/useRuntimeHQState.ts","../src/hooks/useCapability.ts","../src/helpers/index.ts"],"mappings":";;;;UAMiB,sBAAA;EACf,UAAA;EACA,eAAA;EACA,QAAA,EAAU,KAAA,CAAM,SAAS;AAAA;;;;;iBAOX,iBAAA;EACd,UAAA;EACA,eAAA;EACA;AAAA,GACC,sBAAA,GAAsB,KAAA,CAAA,GAAA,CAAA,OAAA;;;UCVR,qBAAA;EACf,OAAA,EAAS,iBAAA;EACT,OAAA;EACA,KAAA,EAAO,KAAA;EACP,aAAA,GAAgB,IAAA;EAChB,kBAAA,GAAqB,IAAA,aAAiB,iBAAA;AAAA;AAAA,UAGvB,mBAAA;EACf,UAAA,EAAY,iBAAA;EACZ,KAAA,EAAO,YAAA;EACP,OAAA;EACA,aAAA;EACA,UAAA;EACA,QAAA;EACA,aAAA;EACA,MAAA;EACA,OAAA;EACA,KAAA,EAAO,KAAA;AAAA;;;;;;ADtBT;iBEIgB,YAAA,IAAgB,qBAAqB;;;UCJpC,wBAAA;EACf,UAAA;EACA,eAAe;AAAA;;;;iBAMD,iBAAA,CAAkB,OAAA,EAAS,wBAAA,GAA2B,qBAAqB;;;;;;AHR3F;;;;;;;iBIUgB,aAAA,CAAc,IAAA,WAAe,mBAAmB;;;KCd3D,UAAA,GAAa,eAAA,GAAkB,eAAA,GAAkB,cAAA;;;ALItD;iBKOgB,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,UAAA,CAAW,KAAiB,EAAV,UAAU;ALlBjB;AAO3B;;AAP2B,iBKyBX,QAAA,CAAS,KAAiB,EAAV,UAAU"}

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import React from "react";
-import { CapabilityState, CapabilityState as CapabilityState$1, RuntimeHQClientOptions, RuntimeResponse, RuntimeResponse as RuntimeResponse$1, RuntimeState, WatchRuntimeOptions } from "@theruntimehq/js";
+import { CapabilityState, CapabilityState as CapabilityState$1, RuntimeHQClientOptions, RuntimeResponse, RuntimeResponse as RuntimeResponse$1, RuntimeState as RuntimeState$1, WatchRuntimeOptions } from "@theruntimehq/js";
 
 //#region src/provider/index.d.ts
 interface RuntimeHQProviderProps {
@@ -25,6 +25,18 @@ interface RuntimeHQContextValue {
   hasCapability: (name: string) => boolean;
   getCapabilityState: (name: string) => CapabilityState$1 | undefined;
 }
+interface UseCapabilityResult {
+  capability: CapabilityState$1 | undefined;
+  state: RuntimeState;
+  message: string;
+  isOperational: boolean;
+  isDegraded: boolean;
+  isOutage: boolean;
+  isMaintenance: boolean;
+  exists: boolean;
+  loading: boolean;
+  error: Error | null;
+}
 //#endregion
 //#region src/hooks/useRuntimeHQ.d.ts
 /**
@@ -43,8 +55,21 @@ interface UseRuntimeHQStateOptions {
  */
 declare function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue;
 //#endregion
+//#region src/hooks/useCapability.d.ts
+/**
+ * Accesses and monitors the health state of a specific capability.
+ * Must be used within a `<RuntimeHQProvider>`.
+ *
+ * Implements a fail-open pattern: if the capability is not present or
+ * RuntimeHQ is loading/errored, the state defaults to "OPERATIONAL"
+ * and isOperational is true.
+ *
+ * @param name The unique name of the capability to check (e.g. "search", "payments")
+ */
+declare function useCapability(name: string): UseCapabilityResult;
+//#endregion
 //#region src/helpers/index.d.ts
-type StateInput = RuntimeResponse | CapabilityState | RuntimeState | null | undefined;
+type StateInput = RuntimeResponse | CapabilityState | RuntimeState$1 | null | undefined;
 /**
  * Checks if the application runtime status is OPERATIONAL.
  */
@@ -62,5 +87,5 @@ declare function isDegraded(input: StateInput): boolean;
  */
 declare function isOutage(input: StateInput): boolean;
 //#endregion
-export { type CapabilityState, type RuntimeHQClientOptions, RuntimeHQContextValue, RuntimeHQProvider, type RuntimeHQProviderProps, type RuntimeResponse, type RuntimeState, type UseRuntimeHQStateOptions, type WatchRuntimeOptions, isDegraded, isMaintenance, isOperational, isOutage, useRuntimeHQ, useRuntimeHQState };
+export { type CapabilityState, type RuntimeHQClientOptions, RuntimeHQContextValue, RuntimeHQProvider, type RuntimeHQProviderProps, type RuntimeResponse, type RuntimeState$1 as RuntimeState, UseCapabilityResult, type UseRuntimeHQStateOptions, type WatchRuntimeOptions, isDegraded, isMaintenance, isOperational, isOutage, useCapability, useRuntimeHQ, useRuntimeHQState };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/provider/index.tsx","../src/types/index.ts","../src/hooks/useRuntimeHQ.ts","../src/hooks/useRuntimeHQState.ts","../src/helpers/index.ts"],"mappings":";;;;UAMiB,sBAAA;EACf,UAAA;EACA,eAAA;EACA,QAAA,EAAU,KAAA,CAAM,SAAS;AAAA;;;;;iBAOX,iBAAA;EACd,UAAA;EACA,eAAA;EACA;AAAA,GACC,sBAAA,GAAsB,KAAA,CAAA,GAAA,CAAA,OAAA;;;UCVR,qBAAA;EACf,OAAA,EAAS,iBAAA;EACT,OAAA;EACA,KAAA,EAAO,KAAA;EACP,aAAA,GAAgB,IAAA;EAChB,kBAAA,GAAqB,IAAA,aAAiB,iBAAA;AAAA;;;;;;ADTxC;iBEIgB,YAAA,IAAgB,qBAAqB;;;UCJpC,wBAAA;EACf,UAAA;EACA,eAAe;AAAA;;;;iBAMD,iBAAA,CAAkB,OAAA,EAAS,wBAAA,GAA2B,qBAAqB;;;KCZtF,UAAA,GAAa,eAAA,GAAkB,eAAA,GAAkB,YAAA;;;AJItD;iBIOgB,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,UAAA,CAAW,KAAiB,EAAV,UAAU;AJlBjB;AAO3B;;AAP2B,iBIyBX,QAAA,CAAS,KAAiB,EAAV,UAAU"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/provider/index.tsx","../src/types/index.ts","../src/hooks/useRuntimeHQ.ts","../src/hooks/useRuntimeHQState.ts","../src/hooks/useCapability.ts","../src/helpers/index.ts"],"mappings":";;;;UAMiB,sBAAA;EACf,UAAA;EACA,eAAA;EACA,QAAA,EAAU,KAAA,CAAM,SAAS;AAAA;;;;;iBAOX,iBAAA;EACd,UAAA;EACA,eAAA;EACA;AAAA,GACC,sBAAA,GAAsB,KAAA,CAAA,GAAA,CAAA,OAAA;;;UCVR,qBAAA;EACf,OAAA,EAAS,iBAAA;EACT,OAAA;EACA,KAAA,EAAO,KAAA;EACP,aAAA,GAAgB,IAAA;EAChB,kBAAA,GAAqB,IAAA,aAAiB,iBAAA;AAAA;AAAA,UAGvB,mBAAA;EACf,UAAA,EAAY,iBAAA;EACZ,KAAA,EAAO,YAAA;EACP,OAAA;EACA,aAAA;EACA,UAAA;EACA,QAAA;EACA,aAAA;EACA,MAAA;EACA,OAAA;EACA,KAAA,EAAO,KAAA;AAAA;;;;;;ADtBT;iBEIgB,YAAA,IAAgB,qBAAqB;;;UCJpC,wBAAA;EACf,UAAA;EACA,eAAe;AAAA;;;;iBAMD,iBAAA,CAAkB,OAAA,EAAS,wBAAA,GAA2B,qBAAqB;;;;;;AHR3F;;;;;;;iBIUgB,aAAA,CAAc,IAAA,WAAe,mBAAmB;;;KCd3D,UAAA,GAAa,eAAA,GAAkB,eAAA,GAAkB,cAAA;;;ALItD;iBKOgB,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,aAAA,CAAc,KAAiB,EAAV,UAAU;;;;iBAO/B,UAAA,CAAW,KAAiB,EAAV,UAAU;ALlBjB;AAO3B;;AAP2B,iBKyBX,QAAA,CAAS,KAAiB,EAAV,UAAU"}

package/dist/index.mjs

@@ -11,7 +11,7 @@ const RuntimeHQContext = createContext(null);
 * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.
 */
 function useRuntimeHQState(options) {
-	const { runtimeKey, intervalSeconds = 15 } = options;
+	const { runtimeKey, intervalSeconds = 60 } = options;
 	const [client, clientInitError] = useMemo(() => {
 		if (!runtimeKey) return [null, /* @__PURE__ */ new Error("runtimeKey is required")];
 		try {
@@ -101,6 +101,45 @@ function useRuntimeHQ() {
 	return context;
 }
 
+//#endregion
+//#region src/hooks/useCapability.ts
+/**
+* Accesses and monitors the health state of a specific capability.
+* Must be used within a `<RuntimeHQProvider>`.
+*
+* Implements a fail-open pattern: if the capability is not present or
+* RuntimeHQ is loading/errored, the state defaults to "OPERATIONAL"
+* and isOperational is true.
+*
+* @param name The unique name of the capability to check (e.g. "search", "payments")
+*/
+function useCapability(name) {
+	const { getCapabilityState, hasCapability, loading, error } = useRuntimeHQ();
+	return useMemo(() => {
+		const capability = getCapabilityState(name);
+		const exists = hasCapability(name);
+		const state = capability?.state ?? "OPERATIONAL";
+		return {
+			capability,
+			state,
+			message: capability?.message ?? "",
+			isOperational: state === "OPERATIONAL",
+			isDegraded: state === "DEGRADED",
+			isOutage: state === "OUTAGE",
+			isMaintenance: state === "MAINTENANCE",
+			exists,
+			loading,
+			error
+		};
+	}, [
+		getCapabilityState,
+		hasCapability,
+		name,
+		loading,
+		error
+	]);
+}
+
 //#endregion
 //#region src/helpers/index.ts
 function getState(input) {
@@ -134,5 +173,5 @@ function isOutage(input) {
 }
 
 //#endregion
-export { RuntimeHQProvider, isDegraded, isMaintenance, isOperational, isOutage, useRuntimeHQ, useRuntimeHQState };
+export { RuntimeHQProvider, isDegraded, isMaintenance, isOperational, isOutage, useCapability, useRuntimeHQ, useRuntimeHQState };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/context/index.ts","../src/hooks/useRuntimeHQState.ts","../src/provider/index.tsx","../src/hooks/useRuntimeHQ.ts","../src/helpers/index.ts"],"sourcesContent":["\"use client\";\n\nimport { createContext } from \"react\";\nimport { RuntimeHQContextValue } from \"../types\";\n\nexport const RuntimeHQContext = createContext<RuntimeHQContextValue | null>(null);\n","\"use client\";\n\nimport { useState, useEffect, useMemo, useCallback } from \"react\";\nimport { RuntimeHQClient } from \"@theruntimehq/js\";\nimport { RuntimeResponse, RuntimeHQContextValue } from \"../types\";\n\nexport interface UseRuntimeHQStateOptions {\n  runtimeKey: string;\n  intervalSeconds?: number;\n}\n\n/**\n * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.\n */\nexport function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue {\n  const { runtimeKey, intervalSeconds = 15 } = options;\n\n  // Safely instantiate RuntimeHQClient\n  const [client, clientInitError] = useMemo(() => {\n    if (!runtimeKey) {\n      return [null, new Error(\"runtimeKey is required\")] as const;\n    }\n    try {\n      return [new RuntimeHQClient({ runtimeKey }), null] as const;\n    } catch (err) {\n      return [null, err instanceof Error ? err : new Error(String(err))] as const;\n    }\n  }, [runtimeKey]);\n\n  const [runtime, setRuntime] = useState<RuntimeResponse | null>(null);\n  const [error, setError] = useState<Error | null>(clientInitError || null);\n  const [loading, setLoading] = useState<boolean>(!clientInitError);\n\n  useEffect(() => {\n    if (clientInitError) {\n      setError(clientInitError);\n      setLoading(false);\n      return;\n    }\n\n    if (!client) {\n      return;\n    }\n\n    // Reset states when the client or key changes\n    setRuntime(null);\n    setError(null);\n    setLoading(true);\n\n    let active = true;\n\n    const unsubscribe = client.watchRuntime({\n      intervalSeconds,\n      onUpdate: (data) => {\n        if (active) {\n          setRuntime(data);\n          setError(null);\n          setLoading(false);\n        }\n      },\n      onError: (err) => {\n        if (active) {\n          setError(err);\n          setLoading(false);\n        }\n      },\n    });\n\n    return () => {\n      active = false;\n      unsubscribe();\n    };\n  }, [client, clientInitError, intervalSeconds]);\n\n  const hasCapability = useCallback((name: string) => {\n    return runtime ? runtime.hasCapability(name) : false;\n  }, [runtime]);\n\n  const getCapabilityState = useCallback((name: string) => {\n    return runtime ? runtime.getCapabilityState(name) : undefined;\n  }, [runtime]);\n\n  return {\n    runtime,\n    loading,\n    error,\n    hasCapability,\n    getCapabilityState,\n  };\n}\n","\"use client\";\n\nimport React from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { useRuntimeHQState } from \"../hooks/useRuntimeHQState\";\n\nexport interface RuntimeHQProviderProps {\n  runtimeKey: string;\n  intervalSeconds?: number;\n  children: React.ReactNode;\n}\n\n/**\n * Context Provider that manages a global RuntimeHQ client subscription and polling loop,\n * making the status state available to all child components using `useRuntimeHQ()`.\n */\nexport function RuntimeHQProvider({\n  runtimeKey,\n  intervalSeconds,\n  children,\n}: RuntimeHQProviderProps) {\n  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });\n\n  return (\n    <RuntimeHQContext.Provider value={value}>\n      {children}\n    </RuntimeHQContext.Provider>\n  );\n}\n","\"use client\";\n\nimport { useContext } from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { RuntimeHQContextValue } from \"../types\";\n\n/**\n * Accesses the global RuntimeHQ status check context.\n * Must be used within a `<RuntimeHQProvider>`.\n */\nexport function useRuntimeHQ(): RuntimeHQContextValue {\n  const context = useContext(RuntimeHQContext);\n  if (!context) {\n    throw new Error(\"useRuntimeHQ must be used within a RuntimeHQProvider\");\n  }\n  return context;\n}\n","import { RuntimeResponse, RuntimeState, CapabilityState } from \"../types\";\n\ntype StateInput = RuntimeResponse | CapabilityState | RuntimeState | null | undefined;\n\nfunction getState(input: StateInput): RuntimeState | null {\n  if (!input) return null;\n  if (typeof input === \"string\") return input;\n  return input.state || null;\n}\n\n/**\n * Checks if the application runtime status is OPERATIONAL.\n */\nexport function isOperational(input: StateInput): boolean {\n  return getState(input) === \"OPERATIONAL\";\n}\n\n/**\n * Checks if the application runtime status is MAINTENANCE.\n */\nexport function isMaintenance(input: StateInput): boolean {\n  return getState(input) === \"MAINTENANCE\";\n}\n\n/**\n * Checks if the application runtime status is DEGRADED.\n */\nexport function isDegraded(input: StateInput): boolean {\n  return getState(input) === \"DEGRADED\";\n}\n\n/**\n * Checks if the application runtime status is OUTAGE.\n */\nexport function isOutage(input: StateInput): boolean {\n  return getState(input) === \"OUTAGE\";\n}\n"],"mappings":";;;;;AAKA,MAAa,mBAAmB,cAA4C,IAAI;;;;;;;ACShF,SAAgB,kBAAkB,SAA0D;CAC1F,MAAM,EAAE,YAAY,kBAAkB,OAAO;CAG7C,MAAM,CAAC,QAAQ,mBAAmB,cAAc;EAC9C,IAAI,CAAC,YACH,OAAO,CAAC,sBAAM,IAAI,MAAM,wBAAwB,CAAC;EAEnD,IAAI;GACF,OAAO,CAAC,IAAI,gBAAgB,EAAE,WAAW,CAAC,GAAG,IAAI;EACnD,SAAS,KAAK;GACZ,OAAO,CAAC,MAAM,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;EACnE;CACF,GAAG,CAAC,UAAU,CAAC;CAEf,MAAM,CAAC,SAAS,cAAc,SAAiC,IAAI;CACnE,MAAM,CAAC,OAAO,YAAY,SAAuB,mBAAmB,IAAI;CACxE,MAAM,CAAC,SAAS,cAAc,SAAkB,CAAC,eAAe;CAEhE,gBAAgB;EACd,IAAI,iBAAiB;GACnB,SAAS,eAAe;GACxB,WAAW,KAAK;GAChB;EACF;EAEA,IAAI,CAAC,QACH;EAIF,WAAW,IAAI;EACf,SAAS,IAAI;EACb,WAAW,IAAI;EAEf,IAAI,SAAS;EAEb,MAAM,cAAc,OAAO,aAAa;GACtC;GACA,WAAW,SAAS;IAClB,IAAI,QAAQ;KACV,WAAW,IAAI;KACf,SAAS,IAAI;KACb,WAAW,KAAK;IAClB;GACF;GACA,UAAU,QAAQ;IAChB,IAAI,QAAQ;KACV,SAAS,GAAG;KACZ,WAAW,KAAK;IAClB;GACF;EACF,CAAC;EAED,aAAa;GACX,SAAS;GACT,YAAY;EACd;CACF,GAAG;EAAC;EAAQ;EAAiB;CAAe,CAAC;CAU7C,OAAO;EACL;EACA;EACA;EACA,eAZoB,aAAa,SAAiB;GAClD,OAAO,UAAU,QAAQ,cAAc,IAAI,IAAI;EACjD,GAAG,CAAC,OAAO,CAUG;EACZ,oBATyB,aAAa,SAAiB;GACvD,OAAO,UAAU,QAAQ,mBAAmB,IAAI,IAAI;EACtD,GAAG,CAAC,OAAO,CAOQ;CACnB;AACF;;;;;;;;ACzEA,SAAgB,kBAAkB,EAChC,YACA,iBACA,YACyB;CACzB,MAAM,QAAQ,kBAAkB;EAAE;EAAY;CAAgB,CAAC;CAE/D,OACE,oBAAC,iBAAiB,UAAlB;EAAkC;EAC/B;CACwB;AAE/B;;;;;;;;AClBA,SAAgB,eAAsC;CACpD,MAAM,UAAU,WAAW,gBAAgB;CAC3C,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,sDAAsD;CAExE,OAAO;AACT;;;;ACZA,SAAS,SAAS,OAAwC;CACxD,IAAI,CAAC,OAAO,OAAO;CACnB,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,OAAO,MAAM,SAAS;AACxB;;;;AAKA,SAAgB,cAAc,OAA4B;CACxD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,cAAc,OAA4B;CACxD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,WAAW,OAA4B;CACrD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,SAAS,OAA4B;CACnD,OAAO,SAAS,KAAK,MAAM;AAC7B"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/context/index.ts","../src/hooks/useRuntimeHQState.ts","../src/provider/index.tsx","../src/hooks/useRuntimeHQ.ts","../src/hooks/useCapability.ts","../src/helpers/index.ts"],"sourcesContent":["\"use client\";\n\nimport { createContext } from \"react\";\nimport { RuntimeHQContextValue } from \"../types\";\n\nexport const RuntimeHQContext = createContext<RuntimeHQContextValue | null>(null);\n","\"use client\";\n\nimport { useState, useEffect, useMemo, useCallback } from \"react\";\nimport { RuntimeHQClient } from \"@theruntimehq/js\";\nimport { RuntimeResponse, RuntimeHQContextValue } from \"../types\";\n\nexport interface UseRuntimeHQStateOptions {\n  runtimeKey: string;\n  intervalSeconds?: number;\n}\n\n/**\n * A direct React hook to fetch and watch RuntimeHQ status without using a Context Provider.\n */\nexport function useRuntimeHQState(options: UseRuntimeHQStateOptions): RuntimeHQContextValue {\n  const { runtimeKey, intervalSeconds = 60 } = options;\n\n  // Safely instantiate RuntimeHQClient\n  const [client, clientInitError] = useMemo(() => {\n    if (!runtimeKey) {\n      return [null, new Error(\"runtimeKey is required\")] as const;\n    }\n    try {\n      return [new RuntimeHQClient({ runtimeKey }), null] as const;\n    } catch (err) {\n      return [null, err instanceof Error ? err : new Error(String(err))] as const;\n    }\n  }, [runtimeKey]);\n\n  const [runtime, setRuntime] = useState<RuntimeResponse | null>(null);\n  const [error, setError] = useState<Error | null>(clientInitError || null);\n  const [loading, setLoading] = useState<boolean>(!clientInitError);\n\n  useEffect(() => {\n    if (clientInitError) {\n      setError(clientInitError);\n      setLoading(false);\n      return;\n    }\n\n    if (!client) {\n      return;\n    }\n\n    // Reset states when the client or key changes\n    setRuntime(null);\n    setError(null);\n    setLoading(true);\n\n    let active = true;\n\n    const unsubscribe = client.watchRuntime({\n      intervalSeconds,\n      onUpdate: (data) => {\n        if (active) {\n          setRuntime(data);\n          setError(null);\n          setLoading(false);\n        }\n      },\n      onError: (err) => {\n        if (active) {\n          setError(err);\n          setLoading(false);\n        }\n      },\n    });\n\n    return () => {\n      active = false;\n      unsubscribe();\n    };\n  }, [client, clientInitError, intervalSeconds]);\n\n  const hasCapability = useCallback((name: string) => {\n    return runtime ? runtime.hasCapability(name) : false;\n  }, [runtime]);\n\n  const getCapabilityState = useCallback((name: string) => {\n    return runtime ? runtime.getCapabilityState(name) : undefined;\n  }, [runtime]);\n\n  return {\n    runtime,\n    loading,\n    error,\n    hasCapability,\n    getCapabilityState,\n  };\n}\n","\"use client\";\n\nimport React from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { useRuntimeHQState } from \"../hooks/useRuntimeHQState\";\n\nexport interface RuntimeHQProviderProps {\n  runtimeKey: string;\n  intervalSeconds?: number;\n  children: React.ReactNode;\n}\n\n/**\n * Context Provider that manages a global RuntimeHQ client subscription and polling loop,\n * making the status state available to all child components using `useRuntimeHQ()`.\n */\nexport function RuntimeHQProvider({\n  runtimeKey,\n  intervalSeconds,\n  children,\n}: RuntimeHQProviderProps) {\n  const value = useRuntimeHQState({ runtimeKey, intervalSeconds });\n\n  return (\n    <RuntimeHQContext.Provider value={value}>\n      {children}\n    </RuntimeHQContext.Provider>\n  );\n}\n","\"use client\";\n\nimport { useContext } from \"react\";\nimport { RuntimeHQContext } from \"../context\";\nimport { RuntimeHQContextValue } from \"../types\";\n\n/**\n * Accesses the global RuntimeHQ status check context.\n * Must be used within a `<RuntimeHQProvider>`.\n */\nexport function useRuntimeHQ(): RuntimeHQContextValue {\n  const context = useContext(RuntimeHQContext);\n  if (!context) {\n    throw new Error(\"useRuntimeHQ must be used within a RuntimeHQProvider\");\n  }\n  return context;\n}\n","\"use client\";\n\nimport { useMemo } from \"react\";\nimport { useRuntimeHQ } from \"./useRuntimeHQ\";\nimport { UseCapabilityResult, RuntimeState } from \"../types\";\n\n/**\n * Accesses and monitors the health state of a specific capability.\n * Must be used within a `<RuntimeHQProvider>`.\n *\n * Implements a fail-open pattern: if the capability is not present or\n * RuntimeHQ is loading/errored, the state defaults to \"OPERATIONAL\"\n * and isOperational is true.\n *\n * @param name The unique name of the capability to check (e.g. \"search\", \"payments\")\n */\nexport function useCapability(name: string): UseCapabilityResult {\n  const { getCapabilityState, hasCapability, loading, error } = useRuntimeHQ();\n\n  return useMemo(() => {\n    const capability = getCapabilityState(name);\n    const exists = hasCapability(name);\n    const state: RuntimeState = capability?.state ?? \"OPERATIONAL\";\n    const message = capability?.message ?? \"\";\n\n    return {\n      capability,\n      state,\n      message,\n      isOperational: state === \"OPERATIONAL\",\n      isDegraded: state === \"DEGRADED\",\n      isOutage: state === \"OUTAGE\",\n      isMaintenance: state === \"MAINTENANCE\",\n      exists,\n      loading,\n      error,\n    };\n  }, [getCapabilityState, hasCapability, name, loading, error]);\n}\n","import { RuntimeResponse, RuntimeState, CapabilityState } from \"../types\";\n\ntype StateInput = RuntimeResponse | CapabilityState | RuntimeState | null | undefined;\n\nfunction getState(input: StateInput): RuntimeState | null {\n  if (!input) return null;\n  if (typeof input === \"string\") return input;\n  return input.state || null;\n}\n\n/**\n * Checks if the application runtime status is OPERATIONAL.\n */\nexport function isOperational(input: StateInput): boolean {\n  return getState(input) === \"OPERATIONAL\";\n}\n\n/**\n * Checks if the application runtime status is MAINTENANCE.\n */\nexport function isMaintenance(input: StateInput): boolean {\n  return getState(input) === \"MAINTENANCE\";\n}\n\n/**\n * Checks if the application runtime status is DEGRADED.\n */\nexport function isDegraded(input: StateInput): boolean {\n  return getState(input) === \"DEGRADED\";\n}\n\n/**\n * Checks if the application runtime status is OUTAGE.\n */\nexport function isOutage(input: StateInput): boolean {\n  return getState(input) === \"OUTAGE\";\n}\n"],"mappings":";;;;;AAKA,MAAa,mBAAmB,cAA4C,IAAI;;;;;;;ACShF,SAAgB,kBAAkB,SAA0D;CAC1F,MAAM,EAAE,YAAY,kBAAkB,OAAO;CAG7C,MAAM,CAAC,QAAQ,mBAAmB,cAAc;EAC9C,IAAI,CAAC,YACH,OAAO,CAAC,sBAAM,IAAI,MAAM,wBAAwB,CAAC;EAEnD,IAAI;GACF,OAAO,CAAC,IAAI,gBAAgB,EAAE,WAAW,CAAC,GAAG,IAAI;EACnD,SAAS,KAAK;GACZ,OAAO,CAAC,MAAM,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;EACnE;CACF,GAAG,CAAC,UAAU,CAAC;CAEf,MAAM,CAAC,SAAS,cAAc,SAAiC,IAAI;CACnE,MAAM,CAAC,OAAO,YAAY,SAAuB,mBAAmB,IAAI;CACxE,MAAM,CAAC,SAAS,cAAc,SAAkB,CAAC,eAAe;CAEhE,gBAAgB;EACd,IAAI,iBAAiB;GACnB,SAAS,eAAe;GACxB,WAAW,KAAK;GAChB;EACF;EAEA,IAAI,CAAC,QACH;EAIF,WAAW,IAAI;EACf,SAAS,IAAI;EACb,WAAW,IAAI;EAEf,IAAI,SAAS;EAEb,MAAM,cAAc,OAAO,aAAa;GACtC;GACA,WAAW,SAAS;IAClB,IAAI,QAAQ;KACV,WAAW,IAAI;KACf,SAAS,IAAI;KACb,WAAW,KAAK;IAClB;GACF;GACA,UAAU,QAAQ;IAChB,IAAI,QAAQ;KACV,SAAS,GAAG;KACZ,WAAW,KAAK;IAClB;GACF;EACF,CAAC;EAED,aAAa;GACX,SAAS;GACT,YAAY;EACd;CACF,GAAG;EAAC;EAAQ;EAAiB;CAAe,CAAC;CAU7C,OAAO;EACL;EACA;EACA;EACA,eAZoB,aAAa,SAAiB;GAClD,OAAO,UAAU,QAAQ,cAAc,IAAI,IAAI;EACjD,GAAG,CAAC,OAAO,CAUG;EACZ,oBATyB,aAAa,SAAiB;GACvD,OAAO,UAAU,QAAQ,mBAAmB,IAAI,IAAI;EACtD,GAAG,CAAC,OAAO,CAOQ;CACnB;AACF;;;;;;;;ACzEA,SAAgB,kBAAkB,EAChC,YACA,iBACA,YACyB;CACzB,MAAM,QAAQ,kBAAkB;EAAE;EAAY;CAAgB,CAAC;CAE/D,OACE,oBAAC,iBAAiB,UAAlB;EAAkC;EAC/B;CACwB;AAE/B;;;;;;;;AClBA,SAAgB,eAAsC;CACpD,MAAM,UAAU,WAAW,gBAAgB;CAC3C,IAAI,CAAC,SACH,MAAM,IAAI,MAAM,sDAAsD;CAExE,OAAO;AACT;;;;;;;;;;;;;;ACAA,SAAgB,cAAc,MAAmC;CAC/D,MAAM,EAAE,oBAAoB,eAAe,SAAS,UAAU,aAAa;CAE3E,OAAO,cAAc;EACnB,MAAM,aAAa,mBAAmB,IAAI;EAC1C,MAAM,SAAS,cAAc,IAAI;EACjC,MAAM,QAAsB,YAAY,SAAS;EAGjD,OAAO;GACL;GACA;GACA,SALc,YAAY,WAAW;GAMrC,eAAe,UAAU;GACzB,YAAY,UAAU;GACtB,UAAU,UAAU;GACpB,eAAe,UAAU;GACzB;GACA;GACA;EACF;CACF,GAAG;EAAC;EAAoB;EAAe;EAAM;EAAS;CAAK,CAAC;AAC9D;;;;AClCA,SAAS,SAAS,OAAwC;CACxD,IAAI,CAAC,OAAO,OAAO;CACnB,IAAI,OAAO,UAAU,UAAU,OAAO;CACtC,OAAO,MAAM,SAAS;AACxB;;;;AAKA,SAAgB,cAAc,OAA4B;CACxD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,cAAc,OAA4B;CACxD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,WAAW,OAA4B;CACrD,OAAO,SAAS,KAAK,MAAM;AAC7B;;;;AAKA,SAAgB,SAAS,OAA4B;CACnD,OAAO,SAAS,KAAK,MAAM;AAC7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theruntimehq/react",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Official React SDK for RuntimeHQ status checking and monitoring.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -43,7 +43,7 @@
     "react-dom": ">=18.0.0"
   },
   "dependencies": {
-    "@theruntimehq/js": "^0.2.1"
+    "@theruntimehq/js": "^0.2.2"
   },
   "devDependencies": {
     "@testing-library/react": "^15.0.7",